whale-code 6.5.5 → 6.5.7

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

@@ -1,727 +1,853 @@
 // 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",
-                },
-                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",
-                },
-                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: "New status", notes: "Optional order 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: "Cart (updated)",
-            },
-            {
-                method: "PATCH",
-                path: "/v1/stores/:storeId/cart/:cartId/items/:itemId",
-                scope: "write:cart",
-                description: "Update cart item quantity",
-                body: { quantity: "New quantity" },
-                response: "Cart (updated)",
-            },
-            {
-                method: "DELETE",
-                path: "/v1/stores/:storeId/cart/:cartId/items/:itemId",
-                scope: "write:cart",
-                description: "Remove an item from the cart",
-                response: "Cart (updated)",
-            },
-        ],
-    },
-    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",
-                    payment_method: "Payment method identifier",
-                    shipping_address: "Shipping address JSON",
-                    billing_address: "Billing address JSON",
-                },
-                response: "Order",
-                notes: "Cart is consumed — cannot be reused after successful checkout",
-            },
-            {
-                method: "POST",
-                path: "/v1/stores/:storeId/checkout/intents",
-                scope: "write:checkout",
-                description: "Create a payment intent (POS terminal flow)",
-                body: {
-                    cart_id: "Cart UUID",
-                    amount: "Total amount in dollars",
-                    payment_method: "Terminal payment method",
-                    terminal_id: "POS terminal identifier",
-                },
-                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",
-                },
-                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",
-                    adjustment: "Required. Number (+/-) to adjust by",
-                    reason: "Reason for adjustment",
-                },
-                response: "InventoryLevel (updated)",
-            },
-            {
-                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: {
-                    period: "today | yesterday | last_7 | last_30 | last_90 | last_365 | ytd | mtd",
-                    start_date: "YYYY-MM-DD (custom range)",
-                    end_date: "YYYY-MM-DD (custom range)",
-                    location_id: "Filter by location",
-                },
-                response: "{ total_revenue, total_orders, average_order_value, top_products[] }",
-            },
-            {
-                method: "GET",
-                path: "/v1/stores/:storeId/analytics/sales/daily",
-                scope: "read:analytics",
-                description: "Daily sales breakdown",
-                params: { period: "Time period", location_id: "Optional location filter" },
-                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: { period: "Time period", location_id: "Optional location filter" },
-                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 }",
-            },
-        ],
-    },
+  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_only: ["write:agent", "write:telemetry"],
-        internal_note: "Agent chat and telemetry scopes are used internally by WhaleTools SDKs. Not needed for storefront/website integrations.",
-    },
-    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.",
+  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 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}" }
 });
@@ -731,7 +857,7 @@ const { data: products, has_more } = await res.json();
 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)
+      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}";
@@ -765,7 +891,7 @@ export default async function ProductsPage({ searchParams }: { searchParams: { a
     </div>
   );
 }`,
-            react_client: `// hooks/useProducts.ts (React client-side)
+      react_client: `// hooks/useProducts.ts (React client-side)
 import { useState, useEffect } from "react";
 
 const BASE = "${BASE}";
@@ -784,10 +910,10 @@ export function useProducts(storeId: string, apiKey: string) {
   }, [storeId, apiKey]);
 
   return { products, loading };
-}`,
-        },
-        cart: {
-            raw_fetch: `// Create cart
+}`
+    },
+    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" },
@@ -805,7 +931,7 @@ await fetch("${BASE}/v1/stores/${storeVar}/cart/\${cart.id}/items", {
 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)
+      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!;
@@ -821,7 +947,7 @@ export async function POST(req: NextRequest) {
   });
   return NextResponse.json(await res.json());
 }`,
-            react_client: `// hooks/useCart.ts
+      react_client: `// hooks/useCart.ts
 import { useState, useCallback } from "react";
 
 export function useCart(storeId: string, apiKey: string) {
@@ -860,10 +986,10 @@ export function useCart(storeId: string, apiKey: string) {
   }, [storeId, cart]);
 
   return { cart, createCart, addItem, removeItem };
-}`,
-        },
-        checkout: {
-            raw_fetch: `// E-commerce checkout (convert cart to order)
+}`
+    },
+    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" },
@@ -886,7 +1012,7 @@ await fetch("${BASE}/v1/stores/${storeVar}/checkout/intents/\${intent.id}/captur
   method: "POST",
   headers: { "x-api-key": "${keyVar}" }
 });`,
-            nextjs_ssr: `// app/api/checkout/route.ts (Server-side checkout — keep API key secret)
+      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!;
@@ -909,7 +1035,7 @@ export async function POST(req: NextRequest) {
 
   return NextResponse.json(await res.json());
 }`,
-            react_client: `// components/CheckoutButton.tsx
+      react_client: `// components/CheckoutButton.tsx
 "use client";
 import { useState } from "react";
 
@@ -933,10 +1059,10 @@ export function CheckoutButton({ cartId }: { cartId: string }) {
   };
 
   return <button onClick={handleCheckout} disabled={loading}>{loading ? "Processing..." : "Checkout"}</button>;
-}`,
-        },
-        orders: {
-            raw_fetch: `// List orders
+}`
+    },
+    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());
@@ -952,7 +1078,7 @@ await fetch("${BASE}/v1/stores/${storeVar}/orders/\${orderId}", {
   headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
   body: JSON.stringify({ status: "shipped" })
 });`,
-            nextjs_ssr: `// app/orders/page.tsx (Server Component)
+      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\`,
@@ -979,7 +1105,7 @@ export default async function OrdersPage() {
     </table>
   );
 }`,
-            react_client: `// hooks/useOrders.ts
+      react_client: `// hooks/useOrders.ts
 import useSWR from "swr";
 
 const fetcher = (url: string) => fetch(url).then(r => r.json());
@@ -988,10 +1114,10 @@ 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
+}`
+    },
+    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());
@@ -1002,7 +1128,7 @@ const customer = await fetch("${BASE}/v1/stores/${storeVar}/customers", {
   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
+      nextjs_ssr: `// app/api/customers/route.ts
 import { NextRequest, NextResponse } from "next/server";
 
 const headers = { "x-api-key": process.env.WHALE_API_KEY! };
@@ -1013,7 +1139,7 @@ export async function GET(req: NextRequest) {
   const res = await fetch(\`\${base}/customers?search=\${encodeURIComponent(search)}\`, { headers });
   return NextResponse.json(await res.json());
 }`,
-            react_client: `// hooks/useCustomers.ts
+      react_client: `// hooks/useCustomers.ts
 import useSWR from "swr";
 
 export function useCustomers(search: string) {
@@ -1022,10 +1148,10 @@ export function useCustomers(search: string) {
     (url) => fetch(url).then(r => r.json())
   );
   return { customers: data?.data ?? [], isLoading };
-}`,
-        },
-        inventory: {
-            raw_fetch: `// Get inventory summary
+}`
+    },
+    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());
@@ -1036,7 +1162,7 @@ await fetch("${BASE}/v1/stores/${storeVar}/inventory/adjust", {
   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
+      nextjs_ssr: `// app/inventory/page.tsx
 async function getInventory() {
   const res = await fetch(
     \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/inventory/summary\`,
@@ -1058,16 +1184,16 @@ export default async function InventoryPage() {
     </div>
   );
 }`,
-            react_client: `// hooks/useInventory.ts
+      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
+}`
+    },
+    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());
@@ -1081,7 +1207,7 @@ const daily = await fetch("${BASE}/v1/stores/${storeVar}/analytics/sales/daily?p
 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
+      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! };
@@ -1109,7 +1235,7 @@ export default async function DashboardPage() {
     </div>
   );
 }`,
-            react_client: `// hooks/useAnalytics.ts
+      react_client: `// hooks/useAnalytics.ts
 import useSWR from "swr";
 
 export function useSalesAnalytics(period = "last_30") {
@@ -1118,14 +1244,14 @@ export function useSalesAnalytics(period = "last_30") {
     (url) => fetch(url).then(r => r.json())
   );
   return { sales: data, isLoading };
-}`,
-        },
-        locations: {
-            raw_fetch: `// List all locations
+}`
+    },
+    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
+      nextjs_ssr: `// lib/api.ts — shared helper
 export async function getLocations() {
   const res = await fetch(
     \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/locations\`,
@@ -1133,16 +1259,16 @@ export async function getLocations() {
   );
   return res.json().then(r => r.data);
 }`,
-            react_client: `// hooks/useLocations.ts
+      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
+}`
+    },
+    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" },
@@ -1159,7 +1285,7 @@ await fetch("${BASE}/v1/stores/${storeVar}/storefront/auth/send-code", {
   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
+      nextjs_ssr: `// app/api/auth/send-code/route.ts
 import { NextRequest, NextResponse } from "next/server";
 
 export async function POST(req: NextRequest) {
@@ -1174,7 +1300,7 @@ export async function POST(req: NextRequest) {
   );
   return NextResponse.json(await res.json(), { status: res.status });
 }`,
-            react_client: `// hooks/useAuth.ts
+      react_client: `// hooks/useAuth.ts
 import { useState } from "react";
 
 export function useStorefrontAuth() {
@@ -1200,10 +1326,10 @@ export function useStorefrontAuth() {
   };
 
   return { sendCode, verifyCode, loading };
-}`,
-        },
-        coa: {
-            raw_fetch: `// List COAs
+}`
+    },
+    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());
@@ -1217,7 +1343,7 @@ const verified = await fetch("${BASE}/v1/stores/${storeVar}/coa/verify?sample_id
 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
+      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\`,
@@ -1235,7 +1361,7 @@ export default async function COAPage({ params }: { params: { id: string } }) {
     </div>
   );
 }`,
-            react_client: `// components/COAViewer.tsx
+      react_client: `// components/COAViewer.tsx
 "use client";
 import { useEffect, useState } from "react";
 
@@ -1247,10 +1373,10 @@ export function COAViewer({ coaId }: { coaId: string }) {
   }, [coaId]);
 
   return <div dangerouslySetInnerHTML={{ __html: html }} />;
-}`,
-        },
-        portal: {
-            raw_fetch: `// B2B portal login
+}`
+    },
+    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" },
@@ -1268,7 +1394,7 @@ const session = await fetch("${BASE}/v1/stores/${storeVar}/portal/auth/verify",
 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
+      nextjs_ssr: `// app/portal/layout.tsx — server-side session check
 import { cookies } from "next/headers";
 import { redirect } from "next/navigation";
 
@@ -1277,7 +1403,7 @@ export default async function PortalLayout({ children }: { children: React.React
   if (!token) redirect("/portal/login");
   return <div className="portal-layout">{children}</div>;
 }`,
-            react_client: `// hooks/usePortal.ts
+      react_client: `// hooks/usePortal.ts
 import { useState } from "react";
 
 export function usePortal() {
@@ -1302,49 +1428,47 @@ export function usePortal() {
   };
 
   return { token, login, getDocuments };
-}`,
-        },
-    };
-    return templates[section] ?? null;
+}`
+    }
+  };
+  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
+  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
+// 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(
+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(
+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",
@@ -1352,26 +1476,24 @@ console.log(\`Loaded \${products.length} products\`);`,
     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(
+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(
+);`
+  }, {
+    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",
@@ -1387,92 +1509,282 @@ console.log("Cart ID:", cart.id);`,
     })
   }
 ).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 }.",
-    ],
+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.',
-                },
-            };
+  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.'
+          };
         }
-        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,
-                },
-            };
+        const s = SECTIONS[section];
+        if (!s) {
+          return {
+            success: false,
+            error: `Unknown section "${section}". Available: ${Object.keys(SECTIONS).join(", ")}`
+          };
         }
-        case "auth": {
-            return { success: true, data: AUTH_GUIDE };
+        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.'
+          };
         }
-        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.",
-                },
-            };
+        const examples = getExamples(section);
+        if (!examples) {
+          return {
+            success: false,
+            error: `No examples for section "${section}". Available: ${Object.keys(SECTIONS).join(", ")}`
+          };
         }
-        case "quick_start": {
-            return { success: true, data: QUICK_START };
+        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`
+      };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// OpenAPI 3.0 spec generation — serves /openapi.json for Scalar docs viewer
+// ---------------------------------------------------------------------------
+
+let _cachedSpec = null;
+
+/** Convert :param to {param} for OpenAPI path syntax */
+function toOpenApiPath(path) {
+  return path.replace(/:([a-zA-Z_]+)/g, "{$1}");
+}
+
+/** Build OpenAPI parameter objects from the endpoint definition */
+function buildParameters(endpoint, path) {
+  const params = [];
+
+  // Extract path parameters from the path itself
+  const pathParams = path.match(/:([a-zA-Z_]+)/g) || [];
+  for (const p of pathParams) {
+    const name = p.slice(1);
+    params.push({
+      name,
+      in: "path",
+      required: true,
+      schema: {
+        type: "string"
+      },
+      description: name === "storeId" ? "Store UUID" : name === "id" ? "Resource UUID" : `${name} identifier`
+    });
+  }
+
+  // Add query parameters for GET endpoints
+  if (endpoint.method === "GET" && endpoint.params) {
+    for (const [name, desc] of Object.entries(endpoint.params)) {
+      params.push({
+        name,
+        in: "query",
+        required: desc.toLowerCase().startsWith("required"),
+        schema: {
+          type: "string"
+        },
+        description: desc
+      });
+    }
+  }
+  return params;
+}
+
+/** Build request body schema from endpoint body definition */
+function buildRequestBody(endpoint) {
+  if (!endpoint.body || endpoint.method === "GET") return undefined;
+  const properties = {};
+  const required = [];
+  for (const [name, desc] of Object.entries(endpoint.body)) {
+    if (name === "...") {
+      properties["additionalProperties"] = {
+        type: "object",
+        description: desc
+      };
+      continue;
+    }
+    properties[name] = {
+      type: "string",
+      description: desc
+    };
+    if (desc.toLowerCase().startsWith("required")) {
+      required.push(name);
+    }
+  }
+  return {
+    required: true,
+    content: {
+      "application/json": {
+        schema: {
+          type: "object",
+          properties,
+          ...(required.length > 0 ? {
+            required
+          } : {})
         }
-        default:
-            return {
-                success: false,
-                error: `Unknown api_docs action: "${action}". Available: sections, endpoints, auth, examples, quick_start`,
-            };
+      }
     }
+  };
+}
+
+/** Generate the full OpenAPI 3.0 spec from SECTIONS */
+export function generateOpenApiSpec() {
+  if (_cachedSpec) return _cachedSpec;
+  const paths = {};
+  for (const [sectionKey, section] of Object.entries(SECTIONS)) {
+    for (const endpoint of section.endpoints) {
+      const openApiPath = toOpenApiPath(endpoint.path);
+      if (!paths[openApiPath]) paths[openApiPath] = {};
+      const method = endpoint.method.toLowerCase();
+      const operation = {
+        summary: endpoint.description,
+        operationId: `${method}_${sectionKey}_${endpoint.path.split("/").pop()?.replace(/:/g, "")}`,
+        tags: [section.name],
+        parameters: buildParameters(endpoint, endpoint.path),
+        responses: {
+          "200": {
+            description: endpoint.response || "Success",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object"
+                }
+              }
+            }
+          },
+          "401": {
+            description: "Unauthorized — missing or invalid API key"
+          },
+          "404": {
+            description: "Resource not found"
+          }
+        },
+        security: [{
+          BearerAuth: []
+        }, {
+          ApiKeyAuth: []
+        }]
+      };
+      if (endpoint.notes) {
+        operation.description = endpoint.notes;
+      }
+      const requestBody = buildRequestBody(endpoint);
+      if (requestBody) {
+        operation.requestBody = requestBody;
+      }
+      paths[openApiPath][method] = operation;
+    }
+  }
+  _cachedSpec = {
+    openapi: "3.0.3",
+    info: {
+      title: "WhaleTools Platform API",
+      description: "Complete commerce, catalog, CRM, analytics, and agent API for the WhaleTools platform.",
+      version: "2026-03-07",
+      contact: {
+        name: "WhaleTools",
+        url: "https://whaletools.dev"
+      }
+    },
+    servers: [{
+      url: GATEWAY_BASE_URL,
+      description: "Production"
+    }],
+    security: [{
+      BearerAuth: []
+    }, {
+      ApiKeyAuth: []
+    }],
+    paths,
+    components: {
+      securitySchemes: {
+        BearerAuth: {
+          type: "http",
+          scheme: "bearer",
+          bearerFormat: "JWT",
+          description: "Supabase JWT from auth login"
+        },
+        ApiKeyAuth: {
+          type: "apiKey",
+          in: "header",
+          name: "x-api-key",
+          description: "Store API key generated via the api_keys tool"
+        }
+      }
+    },
+    tags: Object.entries(SECTIONS).map(([, s]) => ({
+      name: s.name,
+      description: s.description
+    }))
+  };
+  return _cachedSpec;
 }
+//# sourceMappingURL=api-docs.js.map