E-commerce Integration Guide

curl --request GET \
  'https://api.vambe.me/api/public/product/product-blocks' \
  --header 'x-api-key: your_api_key_here'

[
  {
    "id": "block-abc123",
    "name": "Main Product Catalog",
    "count": 150
  },
  {
    "id": "block-def456",
    "name": "Seasonal Products",
    "count": 25
  }
]

// 1. Get product block ID
const blocksResponse = await fetch(
  'https://api.vambe.me/api/public/product/product-blocks',
  {
    headers: { 'x-api-key': 'your_api_key_here' },
  },
);

const blocks = await blocksResponse.json();
const mainBlockId = blocks.find((b) => b.name === 'Main Product Catalog')?.id;

// 2. Create initial products
const createResponse = await fetch(
  `https://api.vambe.me/api/public/product/create/${mainBlockId}`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'your_api_key_here',
    },
    body: JSON.stringify([
      {
        name: 'Premium Coffee Beans',
        description:
          'High-quality arabica coffee from Colombia. Rich flavor with chocolate notes. Perfect for espresso.',
        price: 24.99,
        currency: 'USD',
        type: 'PRODUCT',
        external_id: 'coffee-001',
        file_url: 'https://shop.com/coffee.jpg',
        metadata: [
          { key: 'origin', value: 'Colombia' },
          { key: 'roast', value: 'Medium' },
          { key: 'weight', value: '500g' },
        ],
      },
      {
        name: 'Express Delivery',
        description:
          'Fast delivery service. Next-day delivery for orders placed before 2 PM. Available nationwide.',
        price: 5.0,
        currency: 'USD',
        type: 'SERVICE',
        external_id: 'delivery-express',
        metadata: [
          { key: 'delivery_time', value: '1 day' },
          { key: 'coverage', value: 'Nationwide' },
        ],
      },
    ]),
  },
);

console.log('Products created successfully!');

// Complete catalog sync from your e-commerce platform
const syncCatalog = async (productBlockId) => {
  // 1. Get products from your e-commerce platform
  const shopProducts = await yourEcommercePlatform.getAllProducts();

  // 2. Transform to Vambe format
  const vambeProducts = shopProducts.map((product) => ({
    name: product.title,
    description: `${product.description}. ${product.features.join('. ')}`,
    price: parseFloat(product.price),
    currency: 'USD',
    type: 'PRODUCT',
    external_id: `shop-${product.id}`,
    file_url: product.image_url,
    metadata: [
      { key: 'sku', value: product.sku },
      { key: 'category', value: product.category },
      { key: 'brand', value: product.brand },
      { key: 'in_stock', value: product.in_stock.toString() },
    ],
  }));

  // 3. Upsert to Vambe (full sync - removes discontinued products)
  const response = await fetch(
    `https://api.vambe.me/api/public/product/upsert/${productBlockId}`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here',
      },
      body: JSON.stringify(vambeProducts),
    },
  );

  const result = await response.json();
  console.log(`Synced ${vambeProducts.length} products`);
  console.log(`Created: ${result.created}, Updated: ${result.updated}`);

  return result;
};

// Run nightly
// cron.schedule('0 2 * * *', () => syncCatalog('block-abc123'));

// Add a single new product without affecting others
const addNewProduct = async (productBlockId, newProduct) => {
  const response = await fetch(
    `https://api.vambe.me/api/public/product/create/${productBlockId}`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here',
      },
      body: JSON.stringify([
        {
          name: newProduct.name,
          description: newProduct.description,
          price: newProduct.price,
          currency: 'USD',
          type: 'PRODUCT',
          external_id: `new-${Date.now()}`,
          file_url: newProduct.imageUrl,
          metadata: [
            { key: 'category', value: newProduct.category },
            { key: 'new_arrival', value: 'true' },
          ],
        },
      ]),
    },
  );

  console.log('New product added!');
  return await response.json();
};

// Remove products that are no longer available
const removeDiscontinued = async (productBlockId, externalIds) => {
  const response = await fetch(
    `https://api.vambe.me/api/public/product/delete/${productBlockId}`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here',
      },
      body: JSON.stringify(externalIds.map((id) => ({ external_id: id }))),
    },
  );

  const result = await response.json();
  console.log(`Deleted ${result.deleted} products`);

  return result;
};

// Usage
removeDiscontinued('block-abc123', ['old-product-001', 'discontinued-002']);

"Premium wireless headphones with active noise cancellation. Over-ear design provides comfort for long listening sessions. 30-hour battery life. Perfect for travel, work, and music lovers who demand high-quality audio."

"Model: WH-1000XM4. Price: $349.99. Buy now at https://shop.com. SKU: WH1000XM4."

// Good: Trackable, meaningful IDs
external_id: 'sku-WH1000XM4';
external_id: 'shopify-6789012345';
external_id: 'coffee-premium-colombia-500g';

// Avoid: Hard to track
external_id: '1';
external_id: 'product';

metadata: [
  { key: 'category', value: 'Electronics' },
  { key: 'subcategory', value: 'Audio' },
  { key: 'brand', value: 'Sony' },
  { key: 'in_stock', value: 'true' },
  { key: 'warehouse_location', value: 'A-12' },
  { key: 'seasonal', value: 'false' },
];

// Batch products into chunks for reliability
const BATCH_SIZE = 500;

const uploadInBatches = async (products, blockId) => {
  for (let i = 0; i < products.length; i += BATCH_SIZE) {
    const batch = products.slice(i, i + BATCH_SIZE);

    await fetch(`https://api.vambe.me/api/public/product/create/${blockId}`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here',
      },
      body: JSON.stringify(batch),
    });

    console.log(`Uploaded batch ${Math.floor(i / BATCH_SIZE) + 1}`);

    // Small delay between batches
    await new Promise((resolve) => setTimeout(resolve, 1000));
  }
};

// Daily sync from Shopify/WooCommerce/etc
const dailySync = async () => {
  // 1. Get block ID
  const blocks = await getProductBlocks();
  const blockId = blocks[0].id;

  // 2. Get products from your platform
  const products = await shopifyAPI.getProducts();

  // 3. Transform and sync
  const vambeProducts = products.map(transformToVambeFormat);

  // 4. Upsert (removes products no longer in your catalog)
  await upsertProducts(blockId, vambeProducts);

  console.log('Daily sync complete!');
};

// When a product is added/updated in your system
const onProductChange = async (product) => {
  const blockId = 'block-abc123';

  // Use create (doesn't affect other products)
  await createProducts(blockId, [transformProduct(product)]);

  console.log('Product updated in AI knowledge');
};

// When a product is discontinued
const onProductDiscontinued = async (productId) => {
  const blockId = 'block-abc123';

  await deleteProducts(blockId, [{ external_id: productId }]);

  console.log('Product removed from AI knowledge');
};

// Different product blocks for different categories
const setupCategories = async () => {
  const blocks = await getProductBlocks();

  const electronicsBlock = blocks.find((b) => b.name === 'Electronics');
  const clothingBlock = blocks.find((b) => b.name === 'Clothing');

  // Sync electronics
  await upsertProducts(electronicsBlock.id, electronicsProducts);

  // Sync clothing
  await upsertProducts(clothingBlock.id, clothingProducts);

  console.log('All categories synced!');
};