aura-labs.ai

AURA Integration Guides

Platform-specific guides for integrating AURA into existing merchant systems.

E-commerce Platforms

Shopify

WooCommerce

Custom E-commerce

Enterprise Systems

ERP Integration

Inventory Management

Payment Providers

Integration Patterns

Pattern 1: Direct SDK Integration

Best for custom-built platforms with development resources.

import { createBeacon } from '@aura-labs/beacon';

const beacon = createBeacon({
  externalId: 'my-store-001',
  name: 'My Store',
  endpointUrl: 'https://mystore.com/webhooks/aura',
  capabilities: {
    category: 'electronics',
    products: ['headphones', 'speakers', 'microphones'],
    features: ['next-day delivery', '30-day returns'],
  },
});

// Enforce business rules
beacon.registerPolicies({
  minPrice: 10,
  maxQuantityPerOrder: 100,
  maxDeliveryDays: 14,
  deliveryRegions: ['US', 'CA', 'UK'],
});

// Validate inventory before committing to offers
beacon.beforeOffer(async (session, offer) => {
  const stock = await yourInventory.check(offer.product.sku);
  if (stock < offer.quantity) {
    throw new Error(`Only ${stock} units available`);
  }
});

// Handle committed transactions
beacon.onOfferAccepted(async (transaction) => {
  await yourSystem.createOrder(transaction);
});

Pattern 2: Plugin/Extension

Best for platforms with extension ecosystems (Shopify, WooCommerce).

Pattern 3: Middleware

Best for complex enterprise environments.

Common Integration Tasks

1. Register Your Beacon

Declare what you sell — AURA matches sessions to your capabilities:

const beacon = createBeacon({
  externalId: 'your-store-id',
  name: 'Your Store Name',
  endpointUrl: 'https://yourstore.com/webhooks/aura',
  capabilities: {
    category: 'coffee',
    products: ['organic coffee', 'espresso', 'cold brew'],
    features: ['free shipping', 'subscription available'],
    priceRange: '£5-£35 per bag',
  },
});

await beacon.register();

2. Respond to Sessions

Poll for matching sessions and use NLP-powered catalog matching:

// Define your product catalog for intent matching
const catalog = [
  { name: 'Organic Coffee Beans', sku: 'COF-ORG-001', category: 'coffee', tags: ['organic', 'whole-bean'] },
  { name: 'Espresso Blend', sku: 'COF-ESP-001', category: 'coffee', tags: ['espresso', 'dark-roast'] },
];

beacon.onSession(async (session, beacon) => {
  // Use interpretIntent for smart catalog matching
  const result = await beacon.interpretIntent(session.intent.raw, catalog);

  if (result.matches.length > 0) {
    const topMatch = result.matches[0];
    await beacon.submitOffer(session.sessionId, {
      product: { name: topMatch.item.name, sku: topMatch.item.sku },
      unitPrice: calculatePrice(topMatch.item),
      quantity: 1,
      currency: 'GBP',
      deliveryDate: calculateDeliveryDate(topMatch.item),
    });
  }
});

await beacon.startPolling();

3. Fulfillment Tracking

Report order progress back to AURA Core:

// When you ship the order
await beacon.updateFulfillment(transactionId, {
  fulfillmentStatus: 'shipped',
  fulfillmentReference: 'TRACK-12345',
});

// When the order is delivered — auto-transitions to 'fulfilled'
await beacon.updateFulfillment(transactionId, {
  fulfillmentStatus: 'delivered',
});

4. Payment Confirmation

Report payment via the REST API:

curl -X PUT https://aura-labsai-production.up.railway.app/transactions/{id}/payment \
  -H "Content-Type: application/json" \
  -d '{"paymentStatus": "charged", "paymentReference": "pi_xxx"}'

When payment is charged and the order has been delivered, the transaction auto-transitions to completed.

Transaction Lifecycle

committed → shipped → delivered (→ fulfilled) → charged (→ completed)

Each state change dispatches a webhook to your endpointUrl with the event type and transaction details.

Testing Your Integration

  1. Local Testing: Run AURA Core locally (node src/index.js in aura-core/services/core-api/)
  2. Railway Deployment: Test against https://aura-labsai-production.up.railway.app
  3. Demo Script: Run ./scripts/demo.sh for a full end-to-end walkthrough

Support