whale-code 6.5.4 → 6.5.6

package/dist/server/handlers/api-docs.js

@@ -0,0 +1,1613 @@
+// server/handlers/api-docs.ts — Static API documentation reference for agents
+
+const GATEWAY_BASE_URL = "https://whale-gateway.fly.dev";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Endpoint registry — every public REST API route
+// ---------------------------------------------------------------------------
+
+const SECTIONS = {
+  products: {
+    name: "Products",
+    description: "Product catalog CRUD, variations, and categories",
+    base: "/v1/stores/:storeId/products",
+    endpoints: [{
+      method: "GET",
+      path: "/v1/stores/:storeId/products",
+      scope: "read:products",
+      description: "List products with pagination and filters",
+      params: {
+        limit: "Number (1-100, default 25)",
+        starting_after: "Product ID cursor for forward pagination",
+        ending_before: "Product ID cursor for backward pagination",
+        category_id: "Filter by category UUID",
+        status: "Filter by status: published, draft, archived",
+        type: "Filter by type: simple, variable, grouped",
+        search: "Full-text search on name and SKU",
+        include: "Set to 'none' to skip loading variations (faster for large catalogs)"
+      },
+      response: '{ object: "list", data: Product[], has_more: boolean, url: string }'
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/products/:id",
+      scope: "read:products",
+      description: "Get a single product with variations and inventory",
+      response: "Product (includes pricing_data, field_values, inventory, variations)"
+    }, {
+      method: "POST",
+      path: "/v1/stores/:storeId/products",
+      scope: "write:products",
+      description: "Create a new product",
+      body: {
+        name: "Required. Product name",
+        sku: "SKU code",
+        category_id: "Category UUID",
+        status: "published | draft (default: draft)",
+        type: "simple | variable | grouped (default: simple)",
+        description: "Full description",
+        short_description: "Summary text",
+        cost_price: "Cost per unit",
+        pricing_data: "Pricing tiers JSON",
+        field_values: "Custom fields JSON (must match category field schema)",
+        featured_image: "Image URL",
+        image_gallery: "Array of image URLs",
+        manage_stock: "Boolean — track inventory",
+        stock_quantity: "Initial stock (if manage_stock)"
+      },
+      response: "Product"
+    }, {
+      method: "PATCH",
+      path: "/v1/stores/:storeId/products/:id",
+      scope: "write:products",
+      description: "Update an existing product (partial update)",
+      body: {
+        "...": "Any product fields to update"
+      },
+      response: "Product"
+    }, {
+      method: "DELETE",
+      path: "/v1/stores/:storeId/products/:id",
+      scope: "write:products",
+      description: "Archive a product (soft delete)",
+      response: "{ deleted: true }"
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/products/:id/variations",
+      scope: "read:products",
+      description: "List variations for a product",
+      response: '{ object: "list", data: Variation[] }'
+    }, {
+      method: "POST",
+      path: "/v1/stores/:storeId/products/:id/variations",
+      scope: "write:products",
+      description: "Create a product variation",
+      body: {
+        name: "Variation name (e.g. 'Small', '1oz')",
+        sku: "Variation SKU",
+        pricing_data: "Variation-specific pricing",
+        field_values: "Variation-specific field values",
+        stock_quantity: "Initial stock"
+      },
+      response: "Variation"
+    }, {
+      method: "PATCH",
+      path: "/v1/stores/:storeId/products/:id/variations/:variationId",
+      scope: "write:products",
+      description: "Update a variation",
+      body: {
+        "...": "Any variation fields"
+      },
+      response: "Variation"
+    }, {
+      method: "DELETE",
+      path: "/v1/stores/:storeId/products/:id/variations/:variationId",
+      scope: "write:products",
+      description: "Delete a variation",
+      response: "{ deleted: true }"
+    }]
+  },
+  orders: {
+    name: "Orders",
+    description: "Order management — list, view, update status, void, and refund",
+    base: "/v1/stores/:storeId/orders",
+    endpoints: [{
+      method: "GET",
+      path: "/v1/stores/:storeId/orders",
+      scope: "read:orders",
+      description: "List orders with pagination",
+      params: {
+        limit: "Number (1-100, default 25)",
+        starting_after: "Order ID cursor",
+        ending_before: "Order ID cursor",
+        status: "Filter: pending, confirmed, processing, shipped, delivered, cancelled",
+        customer_id: "Filter by customer UUID",
+        location_id: "Filter by location UUID",
+        created_after: "ISO datetime — filter orders created on or after this date",
+        created_before: "ISO datetime — filter orders created on or before this date"
+      },
+      response: '{ object: "list", data: Order[], has_more: boolean }'
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/orders/:id",
+      scope: "read:orders",
+      description: "Get a single order with line items",
+      response: "Order (includes line_items[], customer, payment_details)"
+    }, {
+      method: "PATCH",
+      path: "/v1/stores/:storeId/orders/:id",
+      scope: "write:orders",
+      description: "Update order status or fields",
+      body: {
+        status: "Order status: pending, confirmed, processing, preparing, packed, ready, shipped, in_transit, delivered, completed, cancelled, refunded",
+        fulfillment_status: "unfulfilled, partial, fulfilled, cancelled, shipped, in_transit, delivered, ready_for_pickup, ready",
+        tracking_number: "Shipping tracking number",
+        tracking_url: "Tracking URL",
+        shipping_service: "Carrier name",
+        shipping_method: "Shipping method",
+        staff_notes: "Internal notes"
+      },
+      response: "Order"
+    }, {
+      method: "POST",
+      path: "/v1/stores/:storeId/orders/:id/void",
+      scope: "write:orders",
+      description: "Void an unsettled order",
+      response: "Order (status: voided)",
+      notes: "Only works on orders where payment has not yet settled"
+    }, {
+      method: "POST",
+      path: "/v1/stores/:storeId/orders/:id/refund",
+      scope: "write:orders",
+      description: "Refund a settled order",
+      body: {
+        amount: "Partial refund amount (optional — omit for full refund)",
+        reason: "Refund reason"
+      },
+      response: "Order (includes refund details)"
+    }]
+  },
+  cart: {
+    name: "Cart",
+    description: "Shopping cart — create, add/update/remove items, view",
+    base: "/v1/stores/:storeId/cart",
+    endpoints: [{
+      method: "POST",
+      path: "/v1/stores/:storeId/cart",
+      scope: "write:cart",
+      description: "Create a new shopping cart",
+      body: {
+        customer_id: "Optional customer UUID",
+        location_id: "Optional location UUID (auto-resolves default)"
+      },
+      response: "Cart { id, items: [], totals }"
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/cart/:cartId",
+      scope: "read:cart",
+      description: "Get cart with all items and computed totals",
+      response: "Cart { id, items: CartItem[], totals: { subtotal, tax, total } }"
+    }, {
+      method: "POST",
+      path: "/v1/stores/:storeId/cart/:cartId/items",
+      scope: "write:cart",
+      description: "Add an item to the cart",
+      body: {
+        product_id: "Required. Product UUID",
+        quantity: "Required. Number of units",
+        variation_id: "Variation UUID (for variable products)",
+        tier: "Pricing tier name (e.g. 'retail', 'wholesale')",
+        unit_price: "Override price (optional — auto-resolved from pricing_data)"
+      },
+      response: 'CartItem { object: "cart_item", id, product_id, product_name, quantity, unit_price, line_total }'
+    }, {
+      method: "PATCH",
+      path: "/v1/stores/:storeId/cart/:cartId/items/:itemId",
+      scope: "write:cart",
+      description: "Update cart item quantity",
+      body: {
+        quantity: "New quantity (must be >= 1)"
+      },
+      response: 'CartItem { object: "cart_item", id, quantity, unit_price, line_total }'
+    }, {
+      method: "DELETE",
+      path: "/v1/stores/:storeId/cart/:cartId/items/:itemId",
+      scope: "write:cart",
+      description: "Remove an item from the cart",
+      response: '{ object: "cart_item", id, deleted: true }'
+    }]
+  },
+  checkout: {
+    name: "Checkout",
+    description: "E-commerce checkout and POS payment intents",
+    base: "/v1/stores/:storeId/checkout",
+    endpoints: [{
+      method: "POST",
+      path: "/v1/stores/:storeId/checkout",
+      scope: "write:checkout",
+      description: "Convert a cart into an order (e-commerce checkout)",
+      body: {
+        cart_id: "Required. Cart UUID",
+        customer_email: "Customer email (auto-creates customer if not found)",
+        customer_name: "Customer name",
+        customer_id: "Existing customer UUID",
+        payment_method: "Payment method identifier",
+        opaque_data: "Authorize.Net card token { dataDescriptor, dataValue }",
+        bill_to: "Billing address { firstName, lastName, address, city, state, zip, country }",
+        ship_to: "Shipping address (same shape as bill_to)",
+        loyalty_code: "Loyalty/discount code",
+        loyalty_points_redeemed: "Points to redeem (integer >= 0)",
+        loyalty_discount_amount: "Discount amount from loyalty (number >= 0)"
+      },
+      response: 'Order { object: "order", id, order_number, status: "completed" }',
+      notes: "Cart is consumed — cannot be reused after successful checkout. Supports idempotency (returns existing order on replay)."
+    }, {
+      method: "POST",
+      path: "/v1/stores/:storeId/checkout/intents",
+      scope: "write:checkout",
+      description: "Create a payment intent (POS terminal flow)",
+      body: {
+        cartItems: "Required. Array of cart items",
+        paymentMethod: "Payment method (card, cash, etc.)",
+        locationId: "Location UUID",
+        registerId: "POS register ID",
+        sessionId: "POS session ID",
+        customerId: "Customer UUID",
+        customerName: "Customer name",
+        userId: "Staff user UUID",
+        tipAmount: "Tip amount",
+        cashTendered: "Cash amount given (for cash payments)",
+        changeGiven: "Change returned",
+        idempotencyKey: "Idempotency key for safe retries"
+      },
+      response: "PaymentIntent { id, status: 'created', amount }"
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/checkout/intents/:id",
+      scope: "read:checkout",
+      description: "Get payment intent status",
+      response: "PaymentIntent { id, status, amount, created_at }"
+    }, {
+      method: "POST",
+      path: "/v1/stores/:storeId/checkout/intents/:id/capture",
+      scope: "write:checkout",
+      description: "Capture an authorized payment",
+      response: "PaymentIntent { status: 'captured' }"
+    }, {
+      method: "POST",
+      path: "/v1/stores/:storeId/checkout/intents/:id/cancel",
+      scope: "write:checkout",
+      description: "Cancel a payment intent",
+      response: "PaymentIntent { status: 'cancelled' }"
+    }, {
+      method: "POST",
+      path: "/v1/stores/:storeId/checkout/intents/:id/charge",
+      scope: "write:checkout",
+      description: "Charge via Dejavoo POS terminal",
+      body: {
+        terminal_id: "Dejavoo terminal ID"
+      },
+      response: "PaymentIntent (with terminal response)",
+      notes: "POS-specific — sends charge request to physical terminal"
+    }, {
+      method: "POST",
+      path: "/v1/stores/:storeId/checkout/intents/:id/abort",
+      scope: "write:checkout",
+      description: "Abort an in-progress terminal charge",
+      response: "PaymentIntent { status: 'aborted' }"
+    }]
+  },
+  customers: {
+    name: "Customers",
+    description: "Customer CRM — CRUD and search",
+    base: "/v1/stores/:storeId/customers",
+    endpoints: [{
+      method: "GET",
+      path: "/v1/stores/:storeId/customers",
+      scope: "read:customers",
+      description: "List customers with pagination and search",
+      params: {
+        limit: "Number (1-100, default 25)",
+        starting_after: "Customer ID cursor",
+        search: "Search by name, email, or phone"
+      },
+      response: '{ object: "list", data: Customer[], has_more: boolean }'
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/customers/:id",
+      scope: "read:customers",
+      description: "Get a single customer with full profile",
+      response: "Customer (includes loyalty_points, total_spent, total_orders)"
+    }, {
+      method: "POST",
+      path: "/v1/stores/:storeId/customers",
+      scope: "write:customers",
+      description: "Create a new customer",
+      body: {
+        first_name: "Required",
+        last_name: "Required",
+        email: "Email address",
+        phone: "Phone number",
+        date_of_birth: "YYYY-MM-DD"
+      },
+      response: "Customer"
+    }, {
+      method: "PATCH",
+      path: "/v1/stores/:storeId/customers/:id",
+      scope: "write:customers",
+      description: "Update a customer",
+      body: {
+        "...": "Any customer fields"
+      },
+      response: "Customer"
+    }]
+  },
+  inventory: {
+    name: "Inventory",
+    description: "Inventory levels, summaries, adjustments, and transfers",
+    base: "/v1/stores/:storeId/inventory",
+    endpoints: [{
+      method: "GET",
+      path: "/v1/stores/:storeId/inventory",
+      scope: "read:inventory",
+      description: "List inventory levels across locations",
+      params: {
+        limit: "Number (1-100, default 25)",
+        starting_after: "Cursor",
+        location_id: "Filter by location UUID",
+        product_id: "Filter by product UUID",
+        low_stock: "Set to 'true' to filter to low_stock or out_of_stock items only"
+      },
+      response: '{ object: "list", data: InventoryLevel[] }'
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/inventory/summary",
+      scope: "read:inventory",
+      description: "Inventory summary grouped by location",
+      response: "{ locations: [{ id, name, total_products, total_units, total_value }] }"
+    }, {
+      method: "POST",
+      path: "/v1/stores/:storeId/inventory/adjust",
+      scope: "write:inventory",
+      description: "Adjust inventory quantity for a product at a location",
+      body: {
+        product_id: "Required. Product UUID",
+        location_id: "Required. Location UUID",
+        quantity_change: "Required. Number (+/-) to adjust by",
+        reason: "Reason for adjustment (default: 'api_adjustment')"
+      },
+      response: '{ object: "inventory_adjustment", product_id, location_id, quantity_change, new_quantity, reason }'
+    }, {
+      method: "POST",
+      path: "/v1/stores/:storeId/inventory/transfer",
+      scope: "write:inventory",
+      description: "Transfer inventory between locations",
+      body: {
+        product_id: "Required. Product UUID",
+        from_location_id: "Required. Source location UUID",
+        to_location_id: "Required. Destination location UUID",
+        quantity: "Required. Number of units to transfer"
+      },
+      response: "{ from: InventoryLevel, to: InventoryLevel }"
+    }]
+  },
+  locations: {
+    name: "Locations",
+    description: "Store locations — list and view",
+    base: "/v1/stores/:storeId/locations",
+    endpoints: [{
+      method: "GET",
+      path: "/v1/stores/:storeId/locations",
+      scope: "read:locations",
+      description: "List all store locations",
+      response: '{ object: "list", data: Location[] }'
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/locations/:id",
+      scope: "read:locations",
+      description: "Get a single location",
+      response: "Location { id, name, address, city, state, zip, type, is_active }"
+    }]
+  },
+  analytics: {
+    name: "Analytics",
+    description: "Sales, inventory, traffic, customer, and product analytics",
+    base: "/v1/stores/:storeId/analytics",
+    endpoints: [{
+      method: "GET",
+      path: "/v1/stores/:storeId/analytics/sales",
+      scope: "read:analytics",
+      description: "Sales analytics summary",
+      params: {
+        start_date: "YYYY-MM-DD (default: 30 days ago)",
+        end_date: "YYYY-MM-DD (default: today)",
+        location_id: "Filter by location UUID"
+      },
+      response: '{ object: "analytics.sales", period: { start_date, end_date }, total_orders, completed_orders, total_revenue, total_tax, total_discount, average_order_value, gross_sales, net_sales, total_profit, profit_margin, unique_customers }'
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/analytics/sales/daily",
+      scope: "read:analytics",
+      description: "Daily sales breakdown",
+      params: {
+        start_date: "YYYY-MM-DD (default: 30 days ago)",
+        end_date: "YYYY-MM-DD (default: today)",
+        location_id: "Filter by location UUID"
+      },
+      response: "{ days: [{ date, revenue, orders, average_order_value }] }"
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/analytics/sales/weekly",
+      scope: "read:analytics",
+      description: "Weekly sales breakdown",
+      params: {
+        start_date: "YYYY-MM-DD (default: 30 days ago)",
+        end_date: "YYYY-MM-DD (default: today)",
+        location_id: "Filter by location UUID"
+      },
+      response: "{ weeks: [{ week_start, revenue, orders }] }"
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/analytics/inventory",
+      scope: "read:analytics",
+      description: "Inventory analytics — stock levels and velocity",
+      response: "{ total_value, low_stock[], out_of_stock[], velocity[] }"
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/analytics/traffic",
+      scope: "read:analytics",
+      description: "Storefront traffic analytics",
+      response: "{ sessions, page_views, bounce_rate, avg_session_duration }"
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/analytics/funnel",
+      scope: "read:analytics",
+      description: "Conversion funnel analytics",
+      response: "{ steps: [{ name, count, conversion_rate }] }"
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/analytics/customers",
+      scope: "read:analytics",
+      description: "Customer analytics — segments, retention, lifetime value",
+      response: "{ total_customers, new_customers, returning, avg_ltv, segments[] }"
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/analytics/products",
+      scope: "read:analytics",
+      description: "Per-product performance analytics",
+      params: {
+        limit: "Number of products",
+        category_id: "Filter by category"
+      },
+      response: "{ products: [{ id, name, revenue, units_sold, avg_price }] }"
+    }]
+  },
+  storefront: {
+    name: "Storefront",
+    description: "Storefront sessions, event tracking, and customer OTP authentication",
+    base: "/v1/stores/:storeId/storefront",
+    endpoints: [{
+      method: "GET",
+      path: "/v1/stores/:storeId/storefront/sessions",
+      scope: "read:storefront",
+      description: "List storefront sessions",
+      response: '{ object: "list", data: Session[] }'
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/storefront/sessions/:id",
+      scope: "read:storefront",
+      description: "Get a single session",
+      response: "Session { id, customer_id, events[], created_at }"
+    }, {
+      method: "POST",
+      path: "/v1/stores/:storeId/storefront/sessions",
+      scope: "write:storefront",
+      description: "Create a storefront session",
+      body: {
+        customer_id: "Optional customer UUID",
+        metadata: "Optional session metadata"
+      },
+      response: "Session"
+    }, {
+      method: "PATCH",
+      path: "/v1/stores/:storeId/storefront/sessions/:id",
+      scope: "write:storefront",
+      description: "Update a session",
+      body: {
+        metadata: "Updated metadata"
+      },
+      response: "Session"
+    }, {
+      method: "POST",
+      path: "/v1/stores/:storeId/storefront/events",
+      scope: "write:storefront",
+      description: "Track a storefront event",
+      body: {
+        session_id: "Session UUID",
+        event_type: "Event name (e.g. page_view, add_to_cart, purchase)",
+        event_data: "Event payload JSON"
+      },
+      response: "{ tracked: true }"
+    }, {
+      method: "POST",
+      path: "/v1/stores/:storeId/storefront/auth/send-code",
+      scope: "write:storefront",
+      description: "Send passwordless OTP to a customer",
+      body: {
+        email: "Customer email OR",
+        phone: "Customer phone"
+      },
+      response: "{ sent: true }",
+      notes: "Rate-limited to prevent abuse. Code expires in 10 minutes."
+    }, {
+      method: "POST",
+      path: "/v1/stores/:storeId/storefront/auth/verify-code",
+      scope: "write:storefront",
+      description: "Verify OTP code and authenticate customer",
+      body: {
+        email: "Customer email OR phone",
+        code: "6-digit OTP code"
+      },
+      response: "{ customer_id, session_token, expires_at }"
+    }]
+  },
+  coa: {
+    name: "COA (Certificates of Analysis)",
+    description: "Lab test results — list, verify, view, and embed",
+    base: "/v1/stores/:storeId/coa",
+    endpoints: [{
+      method: "GET",
+      path: "/v1/stores/:storeId/coa",
+      scope: "read:coa",
+      description: "List COAs (scoped to client)",
+      params: {
+        limit: "Number (1-100)",
+        starting_after: "Cursor"
+      },
+      response: '{ object: "list", data: COA[] }'
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/coa/verify",
+      scope: "read:coa",
+      description: "Verify a COA by sample ID",
+      params: {
+        sample_id: "Lab sample identifier"
+      },
+      response: "COA (with verification status)",
+      notes: "Public-facing verification — can be linked from product pages"
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/coa/:id",
+      scope: "read:coa",
+      description: "Get a single COA with full lab data",
+      response: "COA { id, product_name, batch_number, sample_id, cannabinoids, terpenes, ... }"
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/coa/:id/embed",
+      scope: "read:coa",
+      description: "Get embeddable COA data for iframes or widgets",
+      response: "{ html: string, data: COA }",
+      notes: "Use for embedding lab results on product detail pages"
+    }]
+  },
+  portal: {
+    name: "Customer Portal",
+    description: "B2B portal — authentication, profiles, and documents",
+    base: "/v1/stores/:storeId/portal",
+    endpoints: [{
+      method: "POST",
+      path: "/v1/stores/:storeId/portal/auth/send-code",
+      scope: "write:portal",
+      description: "Send portal login OTP",
+      body: {
+        email: "Customer email"
+      },
+      response: "{ sent: true }"
+    }, {
+      method: "POST",
+      path: "/v1/stores/:storeId/portal/auth/verify",
+      scope: "write:portal",
+      description: "Verify OTP and get portal session",
+      body: {
+        email: "Customer email",
+        code: "OTP code"
+      },
+      response: "{ customer_id, token, expires_at }"
+    }, {
+      method: "POST",
+      path: "/v1/stores/:storeId/portal/auth/refresh",
+      scope: "write:portal",
+      description: "Refresh portal session token",
+      body: {
+        token: "Current session token"
+      },
+      response: "{ token, expires_at }"
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/portal/stores",
+      scope: "read:portal",
+      description: "Get stores the customer belongs to",
+      response: "{ stores: Store[] }"
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/portal/profiles",
+      scope: "read:portal",
+      description: "List customer profiles",
+      response: "{ profiles: Profile[] }"
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/portal/documents",
+      scope: "read:portal",
+      description: "List customer documents",
+      response: '{ object: "list", data: Document[] }'
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/portal/documents/:id",
+      scope: "read:portal",
+      description: "Get a single document",
+      response: "Document { id, name, type, url, created_at }"
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/portal/api-key",
+      scope: "read:portal",
+      description: "Get customer's API key for portal access",
+      response: "{ api_key, scopes[], expires_at }"
+    }]
+  },
+  webhooks: {
+    name: "Webhooks",
+    description: "Inbound webhook ingestion — receives events from external services (HMAC-authenticated, no API key required)",
+    base: "/v1/webhooks",
+    endpoints: [{
+      method: "POST",
+      path: "/v1/webhooks/:slug",
+      scope: "(none — HMAC signature)",
+      description: "Receive an inbound webhook event",
+      body: {
+        timestamp: "Unix timestamp (optional — replay protection, rejects if > 5 min old)",
+        event: "Event type identifier (or 'type' field)",
+        "...": "All other fields pass through to webhook_events table"
+      },
+      response: '{ object: "webhook_event", received: true, event_type: string }',
+      notes: "Authenticated via HMAC sha256 signature from the webhook endpoint's signing_secret. No API key required."
+    }]
+  },
+  agent: {
+    name: "Agent",
+    description: "AI agent chat — SSE streaming proxy to the internal whale-agent service",
+    base: "/v1/stores/:storeId/agent",
+    endpoints: [{
+      method: "POST",
+      path: "/v1/stores/:storeId/agent/chat",
+      scope: "write:agent",
+      description: "Stream an AI agent response via Server-Sent Events",
+      body: {
+        message: "User message (string — either this or messages required)",
+        messages: "Array of { role: 'user'|'assistant'|'system', content: string }",
+        conversation_id: "Conversation ID for multi-turn context",
+        context: "Additional context object passed to the agent"
+      },
+      response: "SSE stream (text/event-stream) — streamed tokens from the agent",
+      notes: "Proxies to internal whale-agent service. 120s timeout (504 on timeout, 502 on connection failure)."
+    }]
+  },
+  telemetry: {
+    name: "Telemetry",
+    description: "SDK telemetry ingestion — errors, analytics events, Web Vitals, and AI/LLM call tracking",
+    base: "/v1/stores/:storeId/telemetry",
+    endpoints: [{
+      method: "POST",
+      path: "/v1/stores/:storeId/telemetry/ingest",
+      scope: "write:telemetry",
+      description: "Ingest a batch of telemetry data (errors, events, vitals, AI calls)",
+      body: {
+        session: "Required. { session_id, visitor_id, started_at, page_url, referrer, user_agent, screen_width, screen_height, device, language, utm_* }",
+        user: "Optional. { user_id, email?, name?, traits? }",
+        errors: "Array (max 50). Each: { error_type, error_message, fingerprint, occurred_at, severity?, stack_trace?, breadcrumbs? }",
+        events: "Array (max 100). Each: { event_name, properties, timestamp }",
+        vitals: "Array (max 20). Each: { name: CLS|FID|LCP|INP|TTFB|FCP, value, rating, timestamp }",
+        ai_calls: "Array (max 50). Each: { model, provider?, prompt_tokens?, completion_tokens?, cost?, duration_ms?, status?, agent_id? }"
+      },
+      response: '{ object: "telemetry_batch", accepted: { errors, events, vitals, ai_calls }, session_id }',
+      notes: "Used by @neowhale/telemetry SDK. Errors go to ClickHouse, events to Supabase, vitals and AI calls to ClickHouse."
+    }, {
+      method: "POST",
+      path: "/v1/native/telemetry",
+      scope: "(JWT-authenticated)",
+      description: "Ingest telemetry from native (macOS/iOS) apps",
+      body: {
+        "...": "Same batch format as /telemetry/ingest"
+      },
+      response: '{ object: "telemetry_batch", accepted: { ... } }',
+      notes: "Authenticated via JWT token (not API key). Bypasses standard API key middleware."
+    }]
+  },
+  media: {
+    name: "Media",
+    description: "Image and video proxy with on-the-fly transformations (HMAC-signed, no API key required)",
+    base: "/v1/stores/:storeId",
+    endpoints: [{
+      method: "GET",
+      path: "/v1/stores/:storeId/media",
+      scope: "(HMAC signature via 's' query param)",
+      description: "Proxy and transform an image (resize, format conversion, quality)",
+      params: {
+        url: "Required. Base64url-encoded source image URL",
+        w: "Width: 64, 96, 128, 256, 384, 640, 828, 1080, 1280, or 1920",
+        q: "Quality 1-100 (default: 80)",
+        f: "Format: avif, webp, jpeg, png (default: webp)",
+        s: "Required. HMAC signature"
+      },
+      response: "Binary image data with Cache-Control: public, max-age=86400, s-maxage=604800, immutable",
+      notes: "Max 8 concurrent transforms, queues for 5s then returns 503 with Retry-After: 2. Use WhaleClient.signMedia() to generate signatures."
+    }, {
+      method: "GET",
+      path: "/v1/stores/:storeId/video",
+      scope: "(HMAC signature via 's' query param)",
+      description: "Stream a video with HTTP range request support",
+      params: {
+        url: "Required. Base64url-encoded source video URL",
+        s: "Required. HMAC signature"
+      },
+      response: "Streamed video (supports Accept-Ranges: bytes for seeking). Auto-resolves optimized -web.mp4 variants.",
+      notes: "Cache-Control: public, max-age=86400, s-maxage=604800, immutable. X-Video-Source header indicates original vs optimized."
+    }]
+  },
+  infrastructure: {
+    name: "Infrastructure",
+    description: "Health checks, OpenAPI spec, and interactive documentation",
+    base: "",
+    endpoints: [{
+      method: "GET",
+      path: "/health",
+      scope: "(no auth)",
+      description: "Health check — simple or detailed with dependency status",
+      params: {
+        detailed: "Set to 'true' to check Supabase and ClickHouse dependencies"
+      },
+      response: '{ status: "ok"|"degraded"|"down", version: "2026-02-20", uptime_s?, dependencies?: { supabase, clickhouse } }',
+      notes: "Simple response: 200 always. Detailed: 503 if both dependencies are down. Cached for 10s."
+    }, {
+      method: "GET",
+      path: "/openapi.json",
+      scope: "(no auth)",
+      description: "OpenAPI 3.0 specification",
+      response: "OpenAPI JSON spec"
+    }, {
+      method: "GET",
+      path: "/docs",
+      scope: "(no auth)",
+      description: "Interactive API documentation page",
+      response: "HTML page"
+    }]
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Auth reference
+// ---------------------------------------------------------------------------
+
+const AUTH_GUIDE = {
+  base_url: GATEWAY_BASE_URL,
+  api_version: "2026-02-20",
+  api_version_header: "X-API-Version",
+  authentication: {
+    method: "API Key via header",
+    header: "x-api-key",
+    key_format: "wk_live_<32chars> (production) or wk_test_<32chars> (sandbox)",
+    how_to_get: "Use the api_keys tool (action: generate) or the WhaleTools dashboard under Settings → API Keys"
+  },
+  scopes: {
+    wildcard: "* (full access), read:* (all reads), write:* (all writes)",
+    per_resource: ["read:products", "write:products", "read:orders", "write:orders", "read:customers", "write:customers", "read:inventory", "write:inventory", "read:locations", "read:analytics", "read:cart", "write:cart", "read:checkout", "write:checkout", "read:storefront", "write:storefront", "read:portal", "write:portal", "read:coa"],
+    internal: ["write:agent", "write:telemetry"],
+    internal_note: "Agent chat and telemetry scopes are used by WhaleTools SDKs and internal services. Media/video endpoints use HMAC signatures instead of API keys."
+  },
+  rate_limits: {
+    default_per_minute: 60,
+    headers: "X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset",
+    exceeded_status: 429,
+    retry_header: "Retry-After (seconds)"
+  },
+  pagination: {
+    style: "Cursor-based",
+    params: "limit (1-100, default 25), starting_after (ID), ending_before (ID)",
+    response: '{ object: "list", data: [...], has_more: true|false, url: "..." }'
+  },
+  error_format: {
+    shape: '{ error: { type, message, code, param?, request_id? } }',
+    types: {
+      authentication_error: "401 — invalid_api_key (also returned for missing key)",
+      permission_error: "403 — insufficient_scope, store_mismatch",
+      not_found_error: "404 — resource_not_found",
+      invalid_request_error: "400/405/409 — validation_error, method_not_allowed, conflict",
+      rate_limit_error: "429 — rate_limit_exceeded, auth_rate_limited (too many auth attempts)",
+      api_error: "500 — internal_error"
+    }
+  },
+  security_headers: {
+    cors: "Configurable per-store. Default: allow all origins",
+    idempotency: "Idempotency-Key header supported on all POST/PATCH requests",
+    versioning: "X-API-Version header (optional — latest version used if omitted)"
+  },
+  url_pattern: "All endpoints: /v1/stores/:storeId/<resource>",
+  note: "Replace :storeId with your store UUID. Get it from the WhaleTools dashboard or the store tool."
+};
+
+// ---------------------------------------------------------------------------
+// Code examples by section
+// ---------------------------------------------------------------------------
+
+function getExamples(section) {
+  const BASE = GATEWAY_BASE_URL;
+  const storeVar = "${STORE_ID}";
+  const keyVar = "${API_KEY}";
+  const templates = {
+    products: {
+      raw_fetch: `// List products
+const res = await fetch("${BASE}/v1/stores/${storeVar}/products?limit=25&status=published", {
+  headers: { "x-api-key": "${keyVar}" }
+});
+const { data: products, has_more } = await res.json();
+
+// Get single product
+const product = await fetch("${BASE}/v1/stores/${storeVar}/products/\${productId}", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());`,
+      nextjs_ssr: `// app/products/page.tsx (Next.js App Router — Server Component)
+const API_KEY = process.env.WHALE_API_KEY!;
+const STORE_ID = process.env.WHALE_STORE_ID!;
+const BASE = "${BASE}";
+
+async function getProducts(page?: string) {
+  const params = new URLSearchParams({ limit: "25", status: "published" });
+  if (page) params.set("starting_after", page);
+
+  const res = await fetch(\`\${BASE}/v1/stores/\${STORE_ID}/products?\${params}\`, {
+    headers: { "x-api-key": API_KEY },
+    next: { revalidate: 60 }, // ISR: revalidate every 60s
+  });
+
+  if (!res.ok) throw new Error("Failed to fetch products");
+  return res.json();
+}
+
+export default async function ProductsPage({ searchParams }: { searchParams: { after?: string } }) {
+  const { data: products, has_more } = await getProducts(searchParams.after);
+
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      {products.map((p: any) => (
+        <div key={p.id} className="border rounded p-4">
+          {p.featured_image && <img src={p.featured_image} alt={p.name} />}
+          <h2>{p.name}</h2>
+          <p>{p.pricing_data?.tiers?.[0]?.price ? \`$\${p.pricing_data.tiers[0].price}\` : "Contact for pricing"}</p>
+        </div>
+      ))}
+      {has_more && <a href={\`?after=\${products.at(-1)?.id}\`}>Next page →</a>}
+    </div>
+  );
+}`,
+      react_client: `// hooks/useProducts.ts (React client-side)
+import { useState, useEffect } from "react";
+
+const BASE = "${BASE}";
+
+export function useProducts(storeId: string, apiKey: string) {
+  const [products, setProducts] = useState([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    fetch(\`\${BASE}/v1/stores/\${storeId}/products?status=published&limit=50\`, {
+      headers: { "x-api-key": apiKey },
+    })
+      .then(r => r.json())
+      .then(({ data }) => setProducts(data))
+      .finally(() => setLoading(false));
+  }, [storeId, apiKey]);
+
+  return { products, loading };
+}`
+    },
+    cart: {
+      raw_fetch: `// Create cart
+const cart = await fetch("${BASE}/v1/stores/${storeVar}/cart", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({ customer_id: customerId })
+}).then(r => r.json());
+
+// Add item
+await fetch("${BASE}/v1/stores/${storeVar}/cart/\${cart.id}/items", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({ product_id: "...", quantity: 2 })
+}).then(r => r.json());
+
+// View cart
+const fullCart = await fetch("${BASE}/v1/stores/${storeVar}/cart/\${cart.id}", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());`,
+      nextjs_ssr: `// app/api/cart/route.ts (Next.js Route Handler — server-side proxy)
+import { NextRequest, NextResponse } from "next/server";
+
+const API_KEY = process.env.WHALE_API_KEY!;
+const STORE_ID = process.env.WHALE_STORE_ID!;
+const BASE = "${BASE}";
+
+export async function POST(req: NextRequest) {
+  const body = await req.json();
+  const res = await fetch(\`\${BASE}/v1/stores/\${STORE_ID}/cart\`, {
+    method: "POST",
+    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return NextResponse.json(await res.json());
+}`,
+      react_client: `// hooks/useCart.ts
+import { useState, useCallback } from "react";
+
+export function useCart(storeId: string, apiKey: string) {
+  const [cart, setCart] = useState<any>(null);
+  const BASE = "${BASE}";
+  const headers = { "x-api-key": apiKey, "Content-Type": "application/json" };
+
+  const createCart = useCallback(async () => {
+    const res = await fetch(\`\${BASE}/v1/stores/\${storeId}/cart\`, {
+      method: "POST", headers,
+    });
+    const data = await res.json();
+    setCart(data);
+    return data;
+  }, [storeId]);
+
+  const addItem = useCallback(async (productId: string, quantity: number) => {
+    if (!cart) return;
+    const res = await fetch(\`\${BASE}/v1/stores/\${storeId}/cart/\${cart.id}/items\`, {
+      method: "POST", headers,
+      body: JSON.stringify({ product_id: productId, quantity }),
+    });
+    const data = await res.json();
+    setCart(data);
+    return data;
+  }, [storeId, cart]);
+
+  const removeItem = useCallback(async (itemId: string) => {
+    if (!cart) return;
+    const res = await fetch(\`\${BASE}/v1/stores/\${storeId}/cart/\${cart.id}/items/\${itemId}\`, {
+      method: "DELETE", headers,
+    });
+    const data = await res.json();
+    setCart(data);
+    return data;
+  }, [storeId, cart]);
+
+  return { cart, createCart, addItem, removeItem };
+}`
+    },
+    checkout: {
+      raw_fetch: `// E-commerce checkout (convert cart to order)
+const order = await fetch("${BASE}/v1/stores/${storeVar}/checkout", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({
+    cart_id: cartId,
+    payment_method: "card",
+    shipping_address: { street: "123 Main St", city: "Charlotte", state: "NC", zip: "28202" }
+  })
+}).then(r => r.json());
+
+// POS payment intent flow
+const intent = await fetch("${BASE}/v1/stores/${storeVar}/checkout/intents", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({ cart_id: cartId, amount: 49.99 })
+}).then(r => r.json());
+
+// Capture after authorization
+await fetch("${BASE}/v1/stores/${storeVar}/checkout/intents/\${intent.id}/capture", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}" }
+});`,
+      nextjs_ssr: `// app/api/checkout/route.ts (Server-side checkout — keep API key secret)
+import { NextRequest, NextResponse } from "next/server";
+
+const API_KEY = process.env.WHALE_API_KEY!;
+const STORE_ID = process.env.WHALE_STORE_ID!;
+const BASE = "${BASE}";
+
+export async function POST(req: NextRequest) {
+  const { cart_id, shipping_address } = await req.json();
+
+  const res = await fetch(\`\${BASE}/v1/stores/\${STORE_ID}/checkout\`, {
+    method: "POST",
+    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
+    body: JSON.stringify({ cart_id, shipping_address }),
+  });
+
+  if (!res.ok) {
+    const err = await res.json();
+    return NextResponse.json(err, { status: res.status });
+  }
+
+  return NextResponse.json(await res.json());
+}`,
+      react_client: `// components/CheckoutButton.tsx
+"use client";
+import { useState } from "react";
+
+export function CheckoutButton({ cartId }: { cartId: string }) {
+  const [loading, setLoading] = useState(false);
+
+  const handleCheckout = async () => {
+    setLoading(true);
+    try {
+      // Call YOUR server-side route (never expose API key to client)
+      const res = await fetch("/api/checkout", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ cart_id: cartId }),
+      });
+      const order = await res.json();
+      if (order.id) window.location.href = \`/orders/\${order.id}/confirmation\`;
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return <button onClick={handleCheckout} disabled={loading}>{loading ? "Processing..." : "Checkout"}</button>;
+}`
+    },
+    orders: {
+      raw_fetch: `// List orders
+const { data: orders } = await fetch("${BASE}/v1/stores/${storeVar}/orders?limit=25", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());
+
+// Get order details
+const order = await fetch("${BASE}/v1/stores/${storeVar}/orders/\${orderId}", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());
+
+// Update order status
+await fetch("${BASE}/v1/stores/${storeVar}/orders/\${orderId}", {
+  method: "PATCH",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({ status: "shipped" })
+});`,
+      nextjs_ssr: `// app/orders/page.tsx (Server Component)
+async function getOrders() {
+  const res = await fetch(
+    \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/orders?limit=50\`,
+    { headers: { "x-api-key": process.env.WHALE_API_KEY! }, next: { revalidate: 30 } }
+  );
+  return res.json();
+}
+
+export default async function OrdersPage() {
+  const { data: orders } = await getOrders();
+  return (
+    <table>
+      <thead><tr><th>Order</th><th>Status</th><th>Total</th><th>Date</th></tr></thead>
+      <tbody>
+        {orders.map((o: any) => (
+          <tr key={o.id}>
+            <td><a href={\`/orders/\${o.id}\`}>{o.order_number}</a></td>
+            <td>{o.status}</td>
+            <td>\${o.total}</td>
+            <td>{new Date(o.created_at).toLocaleDateString()}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}`,
+      react_client: `// hooks/useOrders.ts
+import useSWR from "swr";
+
+const fetcher = (url: string) => fetch(url).then(r => r.json());
+
+export function useOrders() {
+  // Fetch via your own API route (keeps API key server-side)
+  const { data, error, isLoading } = useSWR("/api/orders", fetcher);
+  return { orders: data?.data ?? [], error, isLoading };
+}`
+    },
+    customers: {
+      raw_fetch: `// Search customers
+const { data: customers } = await fetch("${BASE}/v1/stores/${storeVar}/customers?search=john", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());
+
+// Create customer
+const customer = await fetch("${BASE}/v1/stores/${storeVar}/customers", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({ first_name: "John", last_name: "Doe", email: "john@example.com" })
+}).then(r => r.json());`,
+      nextjs_ssr: `// app/api/customers/route.ts
+import { NextRequest, NextResponse } from "next/server";
+
+const headers = { "x-api-key": process.env.WHALE_API_KEY! };
+const base = \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}\`;
+
+export async function GET(req: NextRequest) {
+  const search = req.nextUrl.searchParams.get("q") || "";
+  const res = await fetch(\`\${base}/customers?search=\${encodeURIComponent(search)}\`, { headers });
+  return NextResponse.json(await res.json());
+}`,
+      react_client: `// hooks/useCustomers.ts
+import useSWR from "swr";
+
+export function useCustomers(search: string) {
+  const { data, isLoading } = useSWR(
+    search ? \`/api/customers?q=\${encodeURIComponent(search)}\` : null,
+    (url) => fetch(url).then(r => r.json())
+  );
+  return { customers: data?.data ?? [], isLoading };
+}`
+    },
+    inventory: {
+      raw_fetch: `// Get inventory summary
+const summary = await fetch("${BASE}/v1/stores/${storeVar}/inventory/summary", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());
+
+// Adjust stock
+await fetch("${BASE}/v1/stores/${storeVar}/inventory/adjust", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({ product_id: "...", location_id: "...", adjustment: -5, reason: "Sold offline" })
+});`,
+      nextjs_ssr: `// app/inventory/page.tsx
+async function getInventory() {
+  const res = await fetch(
+    \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/inventory/summary\`,
+    { headers: { "x-api-key": process.env.WHALE_API_KEY! }, next: { revalidate: 60 } }
+  );
+  return res.json();
+}
+
+export default async function InventoryPage() {
+  const summary = await getInventory();
+  return (
+    <div>
+      {summary.locations.map((loc: any) => (
+        <div key={loc.id}>
+          <h3>{loc.name}</h3>
+          <p>{loc.total_products} products, {loc.total_units} units</p>
+        </div>
+      ))}
+    </div>
+  );
+}`,
+      react_client: `// hooks/useInventory.ts
+import useSWR from "swr";
+
+export function useInventorySummary() {
+  const { data, isLoading } = useSWR("/api/inventory/summary", (url) => fetch(url).then(r => r.json()));
+  return { summary: data, isLoading };
+}`
+    },
+    analytics: {
+      raw_fetch: `// Sales analytics
+const sales = await fetch("${BASE}/v1/stores/${storeVar}/analytics/sales?period=last_30", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());
+
+// Daily breakdown
+const daily = await fetch("${BASE}/v1/stores/${storeVar}/analytics/sales/daily?period=last_7", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());
+
+// Product performance
+const topProducts = await fetch("${BASE}/v1/stores/${storeVar}/analytics/products?limit=10", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());`,
+      nextjs_ssr: `// app/dashboard/page.tsx
+async function getDashboard() {
+  const base = \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/analytics\`;
+  const headers = { "x-api-key": process.env.WHALE_API_KEY! };
+  const opts = { headers, next: { revalidate: 300 } as any };
+
+  const [sales, daily, products] = await Promise.all([
+    fetch(\`\${base}/sales?period=last_30\`, opts).then(r => r.json()),
+    fetch(\`\${base}/sales/daily?period=last_7\`, opts).then(r => r.json()),
+    fetch(\`\${base}/products?limit=5\`, opts).then(r => r.json()),
+  ]);
+
+  return { sales, daily, products };
+}
+
+export default async function DashboardPage() {
+  const { sales, daily, products } = await getDashboard();
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      <div className="grid grid-cols-3 gap-4">
+        <div>Revenue: \${sales.total_revenue}</div>
+        <div>Orders: {sales.total_orders}</div>
+        <div>AOV: \${sales.average_order_value}</div>
+      </div>
+    </div>
+  );
+}`,
+      react_client: `// hooks/useAnalytics.ts
+import useSWR from "swr";
+
+export function useSalesAnalytics(period = "last_30") {
+  const { data, isLoading } = useSWR(
+    \`/api/analytics/sales?period=\${period}\`,
+    (url) => fetch(url).then(r => r.json())
+  );
+  return { sales: data, isLoading };
+}`
+    },
+    locations: {
+      raw_fetch: `// List all locations
+const { data: locations } = await fetch("${BASE}/v1/stores/${storeVar}/locations", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());`,
+      nextjs_ssr: `// lib/api.ts — shared helper
+export async function getLocations() {
+  const res = await fetch(
+    \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/locations\`,
+    { headers: { "x-api-key": process.env.WHALE_API_KEY! }, next: { revalidate: 3600 } }
+  );
+  return res.json().then(r => r.data);
+}`,
+      react_client: `// hooks/useLocations.ts
+import useSWR from "swr";
+
+export function useLocations() {
+  const { data } = useSWR("/api/locations", (url) => fetch(url).then(r => r.json()));
+  return data?.data ?? [];
+}`
+    },
+    storefront: {
+      raw_fetch: `// Track page view event
+await fetch("${BASE}/v1/stores/${storeVar}/storefront/events", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({
+    session_id: sessionId,
+    event_type: "page_view",
+    event_data: { url: "/products/blue-dream", product_id: "..." }
+  })
+});
+
+// Send OTP for customer login
+await fetch("${BASE}/v1/stores/${storeVar}/storefront/auth/send-code", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({ email: "customer@example.com" })
+});`,
+      nextjs_ssr: `// app/api/auth/send-code/route.ts
+import { NextRequest, NextResponse } from "next/server";
+
+export async function POST(req: NextRequest) {
+  const { email } = await req.json();
+  const res = await fetch(
+    \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/storefront/auth/send-code\`,
+    {
+      method: "POST",
+      headers: { "x-api-key": process.env.WHALE_API_KEY!, "Content-Type": "application/json" },
+      body: JSON.stringify({ email }),
+    }
+  );
+  return NextResponse.json(await res.json(), { status: res.status });
+}`,
+      react_client: `// hooks/useAuth.ts
+import { useState } from "react";
+
+export function useStorefrontAuth() {
+  const [loading, setLoading] = useState(false);
+
+  const sendCode = async (email: string) => {
+    setLoading(true);
+    await fetch("/api/auth/send-code", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email }),
+    });
+    setLoading(false);
+  };
+
+  const verifyCode = async (email: string, code: string) => {
+    const res = await fetch("/api/auth/verify-code", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email, code }),
+    });
+    return res.json(); // { customer_id, session_token }
+  };
+
+  return { sendCode, verifyCode, loading };
+}`
+    },
+    coa: {
+      raw_fetch: `// List COAs
+const { data: coas } = await fetch("${BASE}/v1/stores/${storeVar}/coa?limit=50", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());
+
+// Verify by sample ID
+const verified = await fetch("${BASE}/v1/stores/${storeVar}/coa/verify?sample_id=LAB-2026-001", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());
+
+// Get embeddable COA data
+const embed = await fetch("${BASE}/v1/stores/${storeVar}/coa/\${coaId}/embed", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());`,
+      nextjs_ssr: `// app/products/[id]/coa/page.tsx
+async function getCOAEmbed(coaId: string) {
+  const res = await fetch(
+    \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/coa/\${coaId}/embed\`,
+    { headers: { "x-api-key": process.env.WHALE_API_KEY! }, next: { revalidate: 3600 } }
+  );
+  return res.json();
+}
+
+export default async function COAPage({ params }: { params: { id: string } }) {
+  const { html, data } = await getCOAEmbed(params.id);
+  return (
+    <div>
+      <h1>Certificate of Analysis — {data.product_name}</h1>
+      <div dangerouslySetInnerHTML={{ __html: html }} />
+    </div>
+  );
+}`,
+      react_client: `// components/COAViewer.tsx
+"use client";
+import { useEffect, useState } from "react";
+
+export function COAViewer({ coaId }: { coaId: string }) {
+  const [html, setHtml] = useState("");
+
+  useEffect(() => {
+    fetch(\`/api/coa/\${coaId}/embed\`).then(r => r.json()).then(d => setHtml(d.html));
+  }, [coaId]);
+
+  return <div dangerouslySetInnerHTML={{ __html: html }} />;
+}`
+    },
+    portal: {
+      raw_fetch: `// B2B portal login
+await fetch("${BASE}/v1/stores/${storeVar}/portal/auth/send-code", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({ email: "buyer@dispensary.com" })
+});
+
+// Verify and get session
+const session = await fetch("${BASE}/v1/stores/${storeVar}/portal/auth/verify", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({ email: "buyer@dispensary.com", code: "123456" })
+}).then(r => r.json());
+
+// List documents with portal token
+const { data: docs } = await fetch("${BASE}/v1/stores/${storeVar}/portal/documents", {
+  headers: { "x-api-key": "${keyVar}", "Authorization": "Bearer " + session.token }
+}).then(r => r.json());`,
+      nextjs_ssr: `// app/portal/layout.tsx — server-side session check
+import { cookies } from "next/headers";
+import { redirect } from "next/navigation";
+
+export default async function PortalLayout({ children }: { children: React.ReactNode }) {
+  const token = cookies().get("portal_token")?.value;
+  if (!token) redirect("/portal/login");
+  return <div className="portal-layout">{children}</div>;
+}`,
+      react_client: `// hooks/usePortal.ts
+import { useState } from "react";
+
+export function usePortal() {
+  const [token, setToken] = useState<string | null>(null);
+
+  const login = async (email: string, code: string) => {
+    const res = await fetch("/api/portal/verify", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email, code }),
+    });
+    const data = await res.json();
+    setToken(data.token);
+    return data;
+  };
+
+  const getDocuments = async () => {
+    const res = await fetch("/api/portal/documents", {
+      headers: { Authorization: \`Bearer \${token}\` },
+    });
+    return res.json();
+  };
+
+  return { token, login, getDocuments };
+}`
+    }
+  };
+  return templates[section] ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Quick start guide
+// ---------------------------------------------------------------------------
+
+const QUICK_START = {
+  title: "WhaleTools API — Quick Start Guide",
+  steps: [{
+    step: 1,
+    title: "Get your API key",
+    description: "Generate an API key from the WhaleTools dashboard (Settings → API Keys) or use the api_keys MCP tool.",
+    code: `// Via dashboard: Settings → API Keys → Generate
+// Or programmatically:
+// api_keys tool: { action: "generate", name: "My Website", scopes: ["read:products", "read:cart", "write:cart", "write:checkout"] }`
+  }, {
+    step: 2,
+    title: "Set up environment variables",
+    description: "Store your API key and store ID securely. Never expose the API key in client-side code.",
+    code: `# .env.local (Next.js) or .env
+WHALE_API_KEY=wk_live_abc123...
+WHALE_STORE_ID=your-store-uuid`
+  }, {
+    step: 3,
+    title: "Fetch products",
+    description: "Make your first API call to list published products.",
+    code: `const res = await fetch(
+  \`https://whale-gateway.fly.dev/v1/stores/\${process.env.WHALE_STORE_ID}/products?status=published&limit=25\`,
+  { headers: { "x-api-key": process.env.WHALE_API_KEY } }
+);
+const { data: products, has_more } = await res.json();
+console.log(\`Loaded \${products.length} products\`);`
+  }, {
+    step: 4,
+    title: "Create a cart",
+    description: "Start a shopping session by creating a cart.",
+    code: `const cart = await fetch(
+  \`https://whale-gateway.fly.dev/v1/stores/\${STORE_ID}/cart\`,
+  {
+    method: "POST",
+    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
+    body: JSON.stringify({})
+  }
+).then(r => r.json());
+console.log("Cart ID:", cart.id);`
+  }, {
+    step: 5,
+    title: "Add items to cart",
+    description: "Add products to the cart by product ID.",
+    code: `await fetch(
+  \`https://whale-gateway.fly.dev/v1/stores/\${STORE_ID}/cart/\${cart.id}/items\`,
+  {
+    method: "POST",
+    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
+    body: JSON.stringify({ product_id: products[0].id, quantity: 1 })
+  }
+);`
+  }, {
+    step: 6,
+    title: "Checkout",
+    description: "Convert the cart into an order.",
+    code: `const order = await fetch(
+  \`https://whale-gateway.fly.dev/v1/stores/\${STORE_ID}/checkout\`,
+  {
+    method: "POST",
+    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
+    body: JSON.stringify({
+      cart_id: cart.id,
+      shipping_address: {
+        street: "123 Main St",
+        city: "Charlotte",
+        state: "NC",
+        zip: "28202"
+      }
+    })
+  }
+).then(r => r.json());
+console.log("Order created:", order.id, "Status:", order.status);`
+  }],
+  tips: ["Keep your API key server-side. Use Next.js Route Handlers or API routes as a proxy for client-side calls.", "Use cursor pagination (starting_after) instead of offset for consistent results.", "Set next: { revalidate: 60 } in Next.js fetch for automatic ISR (Incremental Static Regeneration).", "Idempotency-Key header prevents duplicate orders — always set it on checkout requests.", "All list endpoints return { object: 'list', data: [...], has_more: boolean }."]
+};
+
+// ---------------------------------------------------------------------------
+// Main handler
+// ---------------------------------------------------------------------------
+
+export async function handleApiDocs(_sb, args, _storeId) {
+  const action = args.action;
+  switch (action) {
+    case "sections":
+      {
+        const sections = Object.entries(SECTIONS).map(([key, s]) => ({
+          key,
+          name: s.name,
+          description: s.description,
+          endpoint_count: s.endpoints.length
+        }));
+        return {
+          success: true,
+          data: {
+            total_endpoints: sections.reduce((sum, s) => sum + s.endpoint_count, 0),
+            sections,
+            usage: 'Use api_docs with action "endpoints" and section "<key>" to see full endpoint details.'
+          }
+        };
+      }
+    case "endpoints":
+      {
+        const section = args.section;
+        if (!section) {
+          return {
+            success: false,
+            error: 'Missing required param "section". Use action "sections" to see available sections.'
+          };
+        }
+        const s = SECTIONS[section];
+        if (!s) {
+          return {
+            success: false,
+            error: `Unknown section "${section}". Available: ${Object.keys(SECTIONS).join(", ")}`
+          };
+        }
+        return {
+          success: true,
+          data: {
+            section: s.name,
+            description: s.description,
+            base: s.base,
+            endpoints: s.endpoints
+          }
+        };
+      }
+    case "auth":
+      {
+        return {
+          success: true,
+          data: AUTH_GUIDE
+        };
+      }
+    case "examples":
+      {
+        const section = args.section;
+        if (!section) {
+          return {
+            success: false,
+            error: 'Missing required param "section". Use action "sections" to see available sections.'
+          };
+        }
+        const examples = getExamples(section);
+        if (!examples) {
+          return {
+            success: false,
+            error: `No examples for section "${section}". Available: ${Object.keys(SECTIONS).join(", ")}`
+          };
+        }
+        return {
+          success: true,
+          data: {
+            section,
+            examples,
+            tip: "Always keep API keys server-side. Use Next.js Route Handlers or API routes as a proxy for client-side calls."
+          }
+        };
+      }
+    case "quick_start":
+      {
+        return {
+          success: true,
+          data: QUICK_START
+        };
+      }
+    default:
+      return {
+        success: false,
+        error: `Unknown api_docs action: "${action}". Available: sections, endpoints, auth, examples, quick_start`
+      };
+  }
+}
+//# sourceMappingURL=api-docs.js.map