External source groups

// 1. Call external source (such as  a retail media platform) with a timeout.
const RMP_TIMEOUT = 500; // Maximize for fast response

// Helper function to enforce timeout on fetch requests
const fetchWithTimeout = (url, options, timeout) => {
  return Promise.race([
    fetch(url, options),
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error('RMP timeout')), timeout)
    )
  ]);
};

let sponsoredItems = [];
try {
  // Request sponsored products from RMP
  const retailMediaResponse = await fetchWithTimeout(
    'https://rmp.example.com/api/bids',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        query: 'camera',
        category: 'electronics',
        slots: 2 // Number of sponsored items to request
      })
    },
    RMP_TIMEOUT
  );

  if (retailMediaResponse.ok) {
    sponsoredItems = await retailMediaResponse.json();
    // Example response: [
    //   { objectID: 'camera_123', bid: 2.50 },
    //   { objectID: 'camera_456', bid: 2.00 }
    // ]
  }
} catch (error) {
  // RMP timeout or error - continue just with organic results
  console.warn('RMP unavailable, just showing organic results:', error.message);
}

// 2. Extract object IDs with metadata (only if there are sponsored items)
const injectedItems = sponsoredItems.map(item => ({
  objectID: item.objectID,
  metadata: {
    sponsored: true, // Required for regulatory compliance
    source: 'retail_media',
    bid: item.bid
  }
}));

// 3. Call Algolia Composition API
const response = await client.search({
  compositionID: 'YOUR_COMPOSITION_ID',
  requestBody: {
    params: {
      query: 'camera',
      hitsPerPage: 20,
      // Only include injectedItems if there are sponsored products
      ...(injectedItems.length > 0 && {
        injectedItems: {
          retail_media: { // Key must match group name from Merchandising Studio
            items: injectedItems
          }
        }
      })
    }
  }
});

const injectedItems = sponsoredItems.map(item => ({
  objectID: item.objectID,
  metadata: {
    // Required for regulatory compliance
    sponsored: true,

    // Campaign details (can include nested objects)
    campaign_id: item.campaign_id,
    bid: item.bid_amount,
    advertiser: {
      name: item.advertiser_name,
      id: item.advertiser_id
    },

    // Extra attributes
    promotion_tier: 'premium',
    coupon_code: 'SAVE10'
  }
}));

// Initialize the Composition client
import { compositionClient } from '@algolia/composition';

const client = compositionClient(
  'ALGOLIA_APPLICATION_ID',
  'ALGOLIA_API_KEY'
);

// Backend middleware endpoint
app.get('/search', async (req, res) => {
  const { query, category } = req.query;

  // Call retail media platform with timeout
  let sponsoredItems = [];
  try {
    const rmpResponse = await Promise.race([
      callRetailMediaPlatform({
        query,
        category,
        slots: 2, // Request 2 sponsored items
        user_id: req.user.id
      }),
      new Promise((_, reject) =>
        setTimeout(() => reject(new Error('RMP timeout')), 500)
      )
    ]);

    // Format as Algolia injected items
    sponsoredItems = rmpResponse.ads.map(ad => ({
      objectID: ad.product_id,
      metadata: {
        sponsored: true, // Required for regulatory compliance
        source: 'retail_media',
        campaign_id: ad.campaign_id,
        bid: ad.bid_amount
      }
    }));
  } catch (error) {
    // RMP timeout or error - continue just with organic results
    console.warn('Retail media platform is unavailable:', error.message);
  }

  // Search with Algolia Composition API
  const response = await client.search({
    compositionID: 'YOUR_COMPOSITION_ID',
    requestBody: {
      params: {
        query,
        ...(category && { filters: `category:${category}` }),
        hitsPerPage: 20,
        ...(sponsoredItems.length > 0 && {
          injectedItems: {
            retail_media: {
              items: sponsoredItems
            }
          }
        })
      }
    }
  });

  res.json(response);
});

import { compositionClient } from '@algolia/composition';

const searchClient = compositionClient(
  'YOUR_APP_ID',
  'YOUR_SEARCH_API_KEY'
);

// Use with InstantSearch as usual
<InstantSearch
  compositionID="YOUR_COMPOSITION_ID"
  searchClient={searchClient}
>
  {/* Your widgets */}
</InstantSearch>