autocart-sdk 1.0.0

package/README.md

@@ -0,0 +1,61 @@
+# @autocart/sdk
+
+The official Node.js SDK for the AutoCart Agentic Commerce Platform.
+
+This SDK allows you to instantly expose your existing e-commerce inventory to autonomous AI Buyers, while enforcing strict, cryptographic spending policies and risk-tier firewalls to protect your revenue.
+
+## Installation
+
+```bash
+npm install @autocart/sdk
+```
+
+## Quick Start Integration
+
+You do not need to change your database structure to use AutoCart. You simply provide a `fetchCatalog` adapter function that maps your existing database fields to the standard AutoCart format (`sku`, `name`, `price`, `stock`).
+
+```javascript
+import express from 'express';
+import { AutoCartGateway } from '@autocart/sdk';
+
+const app = express();
+
+// Initialize the Gateway
+const autocart = new AutoCartGateway({
+  merchantKey: 'YOUR_MERCHANT_KEY',       // Generated in the AutoCart Portal
+  merchantSecret: 'YOUR_MERCHANT_SECRET', // Keep this safe!
+  
+  // The Adapter Function: Translate your DB format to the AutoCart format
+  fetchCatalog: async () => {
+    // 1. Fetch data from your specific database (SQL, MongoDB, Shopify, etc.)
+    const myRawInventory = await myCustomDatabase.getProducts();
+    
+    // 2. Map your custom fields to the strict AutoCart schema
+    return myRawInventory.map(product => ({
+      sku: product.item_id,         // Must be a unique string
+      name: product.product_title,  // String
+      price: product.price_in_inr,  // Number (e.g., 4500)
+      stock: product.inventory_qty, // Number (e.g., 10)
+      
+      // Optional: Add a short description to help the AI make decisions
+      description: product.short_desc 
+    }));
+  }
+});
+
+// Mount the SDK on your Express server
+app.use('/api/ai-store', autocart.createRouter());
+
+app.listen(3000, () => {
+  console.log('AI-Ready Storefront running on port 3000');
+});
+```
+
+## How It Works
+
+By mounting `autocart.createRouter()`, the SDK automatically generates two endpoints on your server:
+
+1. **`GET /api/ai-store/catalog`**: A highly optimized, token-lean JSON endpoint that AI Scout Agents query to compare prices and check stock.
+2. **`POST /api/ai-store/checkout`**: The Policy Firewall interceptor. When an AI attempts a purchase, this endpoint verifies the price against your live DB, cryptographically signs the payload, and pings the AutoCart Trust Engine to ensure the human buyer has approved the budget.
+
+For support, visit [merchants.autocart.com](https://autocart.com).

package/index.d.ts

@@ -0,0 +1,14 @@
+import { Router } from 'express';
+
+export interface AutoCartConfig {
+  merchantKey: string;
+  merchantSecret: string;
+  nexusUrl?: string;
+  fetchCatalog?: () => Promise<Array<{ sku: string; name: string; price: number; stock: number }>>;
+  fetchProduct: (sku: string) => Promise<{ sku: string; price: number; stock: number } | null>;
+}
+
+export class AutoCartGateway {
+  constructor(config: AutoCartConfig);
+  createRouter(): Router;
+}

package/index.js

@@ -0,0 +1,136 @@
+import express from 'express';
+import crypto from 'crypto';
+
+
+export class AutoCartGateway {
+  constructor(config) {
+    if (!config.merchantKey || !config.merchantSecret || !config.fetchProduct) {
+      throw new Error('AutoCartGateway requires merchantKey, merchantSecret, and fetchProduct');
+    }
+    this.merchantKey = config.merchantKey;
+    this.merchantSecret = config.merchantSecret;
+    this.fetchCatalog = config.fetchCatalog; // Optional for legacy/indexing
+    this.fetchProduct = config.fetchProduct;
+    this.nexusUrl = config.nexusUrl || 'http://localhost:5000';
+  }
+
+  _signPayload(payload) {
+    return crypto
+      .createHmac('sha256', this.merchantSecret)
+      .update(JSON.stringify(payload))
+      .digest('hex');
+  }
+
+  createRouter() {
+    const router = express.Router();
+    router.use(express.json());
+
+    router.get('/catalog', async (req, res) => {
+      try {
+        if (!this.fetchCatalog) {
+          return res.status(501).json({ error: 'Merchant does not support full catalog fetching' });
+        }
+        const fullCatalog = await this.fetchCatalog();
+        const leanCatalog = fullCatalog.map(item => ({
+          sku: item.sku,
+          n: item.name,
+          p: item.price,
+          s: item.stock
+        }));
+        res.json({ catalog: leanCatalog });
+      } catch (err) {
+        res.status(500).json({ error: 'Failed to fetch catalog' });
+      }
+    });
+
+    router.post('/checkout', async (req, res) => {
+      try {
+        const { sku, qty, idempotencyKey, maxAuthorizedAmount } = req.body;
+        const buyerKey = req.headers['x-buyer-key'];
+
+        if (!buyerKey || !sku || !qty || !idempotencyKey) {
+          return res.status(400).json({ error: 'Missing required checkout fields or x-buyer-key header' });
+        }
+
+        const product = await this.fetchProduct(sku);
+
+        if (!product) {
+          return res.status(404).json({ error: 'Product SKU not found in merchant catalog' });
+        }
+        if (product.stock < qty) {
+          return res.status(409).json({ error: 'Insufficient stock' });
+        }
+
+        const lineTotal = product.price * qty;
+
+        const enginePayload = {
+          merchantKey: this.merchantKey,
+          buyerKey,
+          sku,
+          qty,
+          lineTotal,
+          idempotencyKey,
+          maxAuthorizedAmount
+        };
+
+        const signature = this._signPayload(enginePayload);
+
+        const response = await fetch(`${this.nexusUrl}/api/engine/verify-intent`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'x-autocart-signature': signature
+          },
+          body: JSON.stringify(enginePayload)
+        });
+
+        const engineResult = await response.json();
+
+        if (!response.ok) {
+          return res.status(response.status).json(engineResult);
+        }
+
+        if (engineResult.status !== 'AUTO_APPROVED') {
+          return res.status(200).json({
+            status: engineResult.status,
+            message: 'Transaction requires human approval or is blocked.',
+            auditId: engineResult.auditId
+          });
+        }
+
+        // Simulating the Webhook since headless payments aren't tokenized in this demo
+        await fetch(`${this.nexusUrl}/api/webhook/razorpay`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'x-razorpay-signature': 'test-webhook-bypass'
+          },
+          body: JSON.stringify({
+            event: 'payment.captured',
+            payload: {
+              payment: {
+                entity: {
+                  id: 'pay_sdk_auto',
+                  order_id: engineResult.razorpayOrderId
+                }
+              }
+            }
+          })
+        });
+
+        return res.status(200).json({
+          status: 'PAYMENT_CAPTURED',
+          razorpayOrderId: engineResult.razorpayOrderId,
+          auditId: engineResult.auditId,
+          receipt: `Paid ${lineTotal} INR`
+        });
+
+      } catch (err) {
+        console.error('[AutoCart SDK] Checkout Error:', err.message);
+        res.status(500).json({ error: 'SDK Checkout processing failed' });
+      }
+    });
+
+    return router;
+  }
+}

package/package.json

@@ -0,0 +1 @@
+{"name":"autocart-sdk","version":"1.0.0","type":"module","main":"index.js","dependencies":{"axios":"^1.19.0","express":"^5.2.1"}}