whale-code 6.5.4 → 6.5.5

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

@@ -0,0 +1,1478 @@
+// server/handlers/api-docs.ts — Static API documentation reference for agents
+const GATEWAY_BASE_URL = "https://whale-gateway.fly.dev";
+// ---------------------------------------------------------------------------
+// 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 }",
+            },
+        ],
+    },
+};
+// ---------------------------------------------------------------------------
+// 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.",
+};
+// ---------------------------------------------------------------------------
+// Code examples by section
+// ---------------------------------------------------------------------------
+function getExamples(section) {
+    const BASE = GATEWAY_BASE_URL;
+    const storeVar = "${STORE_ID}";
+    const keyVar = "${API_KEY}";
+    const templates = {
+        products: {
+            raw_fetch: `// List products
+const res = await fetch("${BASE}/v1/stores/${storeVar}/products?limit=25&status=published", {
+  headers: { "x-api-key": "${keyVar}" }
+});
+const { data: products, has_more } = await res.json();
+
+// Get single product
+const product = await fetch("${BASE}/v1/stores/${storeVar}/products/\${productId}", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());`,
+            nextjs_ssr: `// app/products/page.tsx (Next.js App Router — Server Component)
+const API_KEY = process.env.WHALE_API_KEY!;
+const STORE_ID = process.env.WHALE_STORE_ID!;
+const BASE = "${BASE}";
+
+async function getProducts(page?: string) {
+  const params = new URLSearchParams({ limit: "25", status: "published" });
+  if (page) params.set("starting_after", page);
+
+  const res = await fetch(\`\${BASE}/v1/stores/\${STORE_ID}/products?\${params}\`, {
+    headers: { "x-api-key": API_KEY },
+    next: { revalidate: 60 }, // ISR: revalidate every 60s
+  });
+
+  if (!res.ok) throw new Error("Failed to fetch products");
+  return res.json();
+}
+
+export default async function ProductsPage({ searchParams }: { searchParams: { after?: string } }) {
+  const { data: products, has_more } = await getProducts(searchParams.after);
+
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      {products.map((p: any) => (
+        <div key={p.id} className="border rounded p-4">
+          {p.featured_image && <img src={p.featured_image} alt={p.name} />}
+          <h2>{p.name}</h2>
+          <p>{p.pricing_data?.tiers?.[0]?.price ? \`$\${p.pricing_data.tiers[0].price}\` : "Contact for pricing"}</p>
+        </div>
+      ))}
+      {has_more && <a href={\`?after=\${products.at(-1)?.id}\`}>Next page →</a>}
+    </div>
+  );
+}`,
+            react_client: `// hooks/useProducts.ts (React client-side)
+import { useState, useEffect } from "react";
+
+const BASE = "${BASE}";
+
+export function useProducts(storeId: string, apiKey: string) {
+  const [products, setProducts] = useState([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    fetch(\`\${BASE}/v1/stores/\${storeId}/products?status=published&limit=50\`, {
+      headers: { "x-api-key": apiKey },
+    })
+      .then(r => r.json())
+      .then(({ data }) => setProducts(data))
+      .finally(() => setLoading(false));
+  }, [storeId, apiKey]);
+
+  return { products, loading };
+}`,
+        },
+        cart: {
+            raw_fetch: `// Create cart
+const cart = await fetch("${BASE}/v1/stores/${storeVar}/cart", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({ customer_id: customerId })
+}).then(r => r.json());
+
+// Add item
+await fetch("${BASE}/v1/stores/${storeVar}/cart/\${cart.id}/items", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({ product_id: "...", quantity: 2 })
+}).then(r => r.json());
+
+// View cart
+const fullCart = await fetch("${BASE}/v1/stores/${storeVar}/cart/\${cart.id}", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());`,
+            nextjs_ssr: `// app/api/cart/route.ts (Next.js Route Handler — server-side proxy)
+import { NextRequest, NextResponse } from "next/server";
+
+const API_KEY = process.env.WHALE_API_KEY!;
+const STORE_ID = process.env.WHALE_STORE_ID!;
+const BASE = "${BASE}";
+
+export async function POST(req: NextRequest) {
+  const body = await req.json();
+  const res = await fetch(\`\${BASE}/v1/stores/\${STORE_ID}/cart\`, {
+    method: "POST",
+    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return NextResponse.json(await res.json());
+}`,
+            react_client: `// hooks/useCart.ts
+import { useState, useCallback } from "react";
+
+export function useCart(storeId: string, apiKey: string) {
+  const [cart, setCart] = useState<any>(null);
+  const BASE = "${BASE}";
+  const headers = { "x-api-key": apiKey, "Content-Type": "application/json" };
+
+  const createCart = useCallback(async () => {
+    const res = await fetch(\`\${BASE}/v1/stores/\${storeId}/cart\`, {
+      method: "POST", headers,
+    });
+    const data = await res.json();
+    setCart(data);
+    return data;
+  }, [storeId]);
+
+  const addItem = useCallback(async (productId: string, quantity: number) => {
+    if (!cart) return;
+    const res = await fetch(\`\${BASE}/v1/stores/\${storeId}/cart/\${cart.id}/items\`, {
+      method: "POST", headers,
+      body: JSON.stringify({ product_id: productId, quantity }),
+    });
+    const data = await res.json();
+    setCart(data);
+    return data;
+  }, [storeId, cart]);
+
+  const removeItem = useCallback(async (itemId: string) => {
+    if (!cart) return;
+    const res = await fetch(\`\${BASE}/v1/stores/\${storeId}/cart/\${cart.id}/items/\${itemId}\`, {
+      method: "DELETE", headers,
+    });
+    const data = await res.json();
+    setCart(data);
+    return data;
+  }, [storeId, cart]);
+
+  return { cart, createCart, addItem, removeItem };
+}`,
+        },
+        checkout: {
+            raw_fetch: `// E-commerce checkout (convert cart to order)
+const order = await fetch("${BASE}/v1/stores/${storeVar}/checkout", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({
+    cart_id: cartId,
+    payment_method: "card",
+    shipping_address: { street: "123 Main St", city: "Charlotte", state: "NC", zip: "28202" }
+  })
+}).then(r => r.json());
+
+// POS payment intent flow
+const intent = await fetch("${BASE}/v1/stores/${storeVar}/checkout/intents", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({ cart_id: cartId, amount: 49.99 })
+}).then(r => r.json());
+
+// Capture after authorization
+await fetch("${BASE}/v1/stores/${storeVar}/checkout/intents/\${intent.id}/capture", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}" }
+});`,
+            nextjs_ssr: `// app/api/checkout/route.ts (Server-side checkout — keep API key secret)
+import { NextRequest, NextResponse } from "next/server";
+
+const API_KEY = process.env.WHALE_API_KEY!;
+const STORE_ID = process.env.WHALE_STORE_ID!;
+const BASE = "${BASE}";
+
+export async function POST(req: NextRequest) {
+  const { cart_id, shipping_address } = await req.json();
+
+  const res = await fetch(\`\${BASE}/v1/stores/\${STORE_ID}/checkout\`, {
+    method: "POST",
+    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
+    body: JSON.stringify({ cart_id, shipping_address }),
+  });
+
+  if (!res.ok) {
+    const err = await res.json();
+    return NextResponse.json(err, { status: res.status });
+  }
+
+  return NextResponse.json(await res.json());
+}`,
+            react_client: `// components/CheckoutButton.tsx
+"use client";
+import { useState } from "react";
+
+export function CheckoutButton({ cartId }: { cartId: string }) {
+  const [loading, setLoading] = useState(false);
+
+  const handleCheckout = async () => {
+    setLoading(true);
+    try {
+      // Call YOUR server-side route (never expose API key to client)
+      const res = await fetch("/api/checkout", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ cart_id: cartId }),
+      });
+      const order = await res.json();
+      if (order.id) window.location.href = \`/orders/\${order.id}/confirmation\`;
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return <button onClick={handleCheckout} disabled={loading}>{loading ? "Processing..." : "Checkout"}</button>;
+}`,
+        },
+        orders: {
+            raw_fetch: `// List orders
+const { data: orders } = await fetch("${BASE}/v1/stores/${storeVar}/orders?limit=25", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());
+
+// Get order details
+const order = await fetch("${BASE}/v1/stores/${storeVar}/orders/\${orderId}", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());
+
+// Update order status
+await fetch("${BASE}/v1/stores/${storeVar}/orders/\${orderId}", {
+  method: "PATCH",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({ status: "shipped" })
+});`,
+            nextjs_ssr: `// app/orders/page.tsx (Server Component)
+async function getOrders() {
+  const res = await fetch(
+    \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/orders?limit=50\`,
+    { headers: { "x-api-key": process.env.WHALE_API_KEY! }, next: { revalidate: 30 } }
+  );
+  return res.json();
+}
+
+export default async function OrdersPage() {
+  const { data: orders } = await getOrders();
+  return (
+    <table>
+      <thead><tr><th>Order</th><th>Status</th><th>Total</th><th>Date</th></tr></thead>
+      <tbody>
+        {orders.map((o: any) => (
+          <tr key={o.id}>
+            <td><a href={\`/orders/\${o.id}\`}>{o.order_number}</a></td>
+            <td>{o.status}</td>
+            <td>\${o.total}</td>
+            <td>{new Date(o.created_at).toLocaleDateString()}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}`,
+            react_client: `// hooks/useOrders.ts
+import useSWR from "swr";
+
+const fetcher = (url: string) => fetch(url).then(r => r.json());
+
+export function useOrders() {
+  // Fetch via your own API route (keeps API key server-side)
+  const { data, error, isLoading } = useSWR("/api/orders", fetcher);
+  return { orders: data?.data ?? [], error, isLoading };
+}`,
+        },
+        customers: {
+            raw_fetch: `// Search customers
+const { data: customers } = await fetch("${BASE}/v1/stores/${storeVar}/customers?search=john", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());
+
+// Create customer
+const customer = await fetch("${BASE}/v1/stores/${storeVar}/customers", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({ first_name: "John", last_name: "Doe", email: "john@example.com" })
+}).then(r => r.json());`,
+            nextjs_ssr: `// app/api/customers/route.ts
+import { NextRequest, NextResponse } from "next/server";
+
+const headers = { "x-api-key": process.env.WHALE_API_KEY! };
+const base = \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}\`;
+
+export async function GET(req: NextRequest) {
+  const search = req.nextUrl.searchParams.get("q") || "";
+  const res = await fetch(\`\${base}/customers?search=\${encodeURIComponent(search)}\`, { headers });
+  return NextResponse.json(await res.json());
+}`,
+            react_client: `// hooks/useCustomers.ts
+import useSWR from "swr";
+
+export function useCustomers(search: string) {
+  const { data, isLoading } = useSWR(
+    search ? \`/api/customers?q=\${encodeURIComponent(search)}\` : null,
+    (url) => fetch(url).then(r => r.json())
+  );
+  return { customers: data?.data ?? [], isLoading };
+}`,
+        },
+        inventory: {
+            raw_fetch: `// Get inventory summary
+const summary = await fetch("${BASE}/v1/stores/${storeVar}/inventory/summary", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());
+
+// Adjust stock
+await fetch("${BASE}/v1/stores/${storeVar}/inventory/adjust", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({ product_id: "...", location_id: "...", adjustment: -5, reason: "Sold offline" })
+});`,
+            nextjs_ssr: `// app/inventory/page.tsx
+async function getInventory() {
+  const res = await fetch(
+    \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/inventory/summary\`,
+    { headers: { "x-api-key": process.env.WHALE_API_KEY! }, next: { revalidate: 60 } }
+  );
+  return res.json();
+}
+
+export default async function InventoryPage() {
+  const summary = await getInventory();
+  return (
+    <div>
+      {summary.locations.map((loc: any) => (
+        <div key={loc.id}>
+          <h3>{loc.name}</h3>
+          <p>{loc.total_products} products, {loc.total_units} units</p>
+        </div>
+      ))}
+    </div>
+  );
+}`,
+            react_client: `// hooks/useInventory.ts
+import useSWR from "swr";
+
+export function useInventorySummary() {
+  const { data, isLoading } = useSWR("/api/inventory/summary", (url) => fetch(url).then(r => r.json()));
+  return { summary: data, isLoading };
+}`,
+        },
+        analytics: {
+            raw_fetch: `// Sales analytics
+const sales = await fetch("${BASE}/v1/stores/${storeVar}/analytics/sales?period=last_30", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());
+
+// Daily breakdown
+const daily = await fetch("${BASE}/v1/stores/${storeVar}/analytics/sales/daily?period=last_7", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());
+
+// Product performance
+const topProducts = await fetch("${BASE}/v1/stores/${storeVar}/analytics/products?limit=10", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());`,
+            nextjs_ssr: `// app/dashboard/page.tsx
+async function getDashboard() {
+  const base = \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/analytics\`;
+  const headers = { "x-api-key": process.env.WHALE_API_KEY! };
+  const opts = { headers, next: { revalidate: 300 } as any };
+
+  const [sales, daily, products] = await Promise.all([
+    fetch(\`\${base}/sales?period=last_30\`, opts).then(r => r.json()),
+    fetch(\`\${base}/sales/daily?period=last_7\`, opts).then(r => r.json()),
+    fetch(\`\${base}/products?limit=5\`, opts).then(r => r.json()),
+  ]);
+
+  return { sales, daily, products };
+}
+
+export default async function DashboardPage() {
+  const { sales, daily, products } = await getDashboard();
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      <div className="grid grid-cols-3 gap-4">
+        <div>Revenue: \${sales.total_revenue}</div>
+        <div>Orders: {sales.total_orders}</div>
+        <div>AOV: \${sales.average_order_value}</div>
+      </div>
+    </div>
+  );
+}`,
+            react_client: `// hooks/useAnalytics.ts
+import useSWR from "swr";
+
+export function useSalesAnalytics(period = "last_30") {
+  const { data, isLoading } = useSWR(
+    \`/api/analytics/sales?period=\${period}\`,
+    (url) => fetch(url).then(r => r.json())
+  );
+  return { sales: data, isLoading };
+}`,
+        },
+        locations: {
+            raw_fetch: `// List all locations
+const { data: locations } = await fetch("${BASE}/v1/stores/${storeVar}/locations", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());`,
+            nextjs_ssr: `// lib/api.ts — shared helper
+export async function getLocations() {
+  const res = await fetch(
+    \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/locations\`,
+    { headers: { "x-api-key": process.env.WHALE_API_KEY! }, next: { revalidate: 3600 } }
+  );
+  return res.json().then(r => r.data);
+}`,
+            react_client: `// hooks/useLocations.ts
+import useSWR from "swr";
+
+export function useLocations() {
+  const { data } = useSWR("/api/locations", (url) => fetch(url).then(r => r.json()));
+  return data?.data ?? [];
+}`,
+        },
+        storefront: {
+            raw_fetch: `// Track page view event
+await fetch("${BASE}/v1/stores/${storeVar}/storefront/events", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({
+    session_id: sessionId,
+    event_type: "page_view",
+    event_data: { url: "/products/blue-dream", product_id: "..." }
+  })
+});
+
+// Send OTP for customer login
+await fetch("${BASE}/v1/stores/${storeVar}/storefront/auth/send-code", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({ email: "customer@example.com" })
+});`,
+            nextjs_ssr: `// app/api/auth/send-code/route.ts
+import { NextRequest, NextResponse } from "next/server";
+
+export async function POST(req: NextRequest) {
+  const { email } = await req.json();
+  const res = await fetch(
+    \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/storefront/auth/send-code\`,
+    {
+      method: "POST",
+      headers: { "x-api-key": process.env.WHALE_API_KEY!, "Content-Type": "application/json" },
+      body: JSON.stringify({ email }),
+    }
+  );
+  return NextResponse.json(await res.json(), { status: res.status });
+}`,
+            react_client: `// hooks/useAuth.ts
+import { useState } from "react";
+
+export function useStorefrontAuth() {
+  const [loading, setLoading] = useState(false);
+
+  const sendCode = async (email: string) => {
+    setLoading(true);
+    await fetch("/api/auth/send-code", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email }),
+    });
+    setLoading(false);
+  };
+
+  const verifyCode = async (email: string, code: string) => {
+    const res = await fetch("/api/auth/verify-code", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email, code }),
+    });
+    return res.json(); // { customer_id, session_token }
+  };
+
+  return { sendCode, verifyCode, loading };
+}`,
+        },
+        coa: {
+            raw_fetch: `// List COAs
+const { data: coas } = await fetch("${BASE}/v1/stores/${storeVar}/coa?limit=50", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());
+
+// Verify by sample ID
+const verified = await fetch("${BASE}/v1/stores/${storeVar}/coa/verify?sample_id=LAB-2026-001", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());
+
+// Get embeddable COA data
+const embed = await fetch("${BASE}/v1/stores/${storeVar}/coa/\${coaId}/embed", {
+  headers: { "x-api-key": "${keyVar}" }
+}).then(r => r.json());`,
+            nextjs_ssr: `// app/products/[id]/coa/page.tsx
+async function getCOAEmbed(coaId: string) {
+  const res = await fetch(
+    \`${BASE}/v1/stores/\${process.env.WHALE_STORE_ID}/coa/\${coaId}/embed\`,
+    { headers: { "x-api-key": process.env.WHALE_API_KEY! }, next: { revalidate: 3600 } }
+  );
+  return res.json();
+}
+
+export default async function COAPage({ params }: { params: { id: string } }) {
+  const { html, data } = await getCOAEmbed(params.id);
+  return (
+    <div>
+      <h1>Certificate of Analysis — {data.product_name}</h1>
+      <div dangerouslySetInnerHTML={{ __html: html }} />
+    </div>
+  );
+}`,
+            react_client: `// components/COAViewer.tsx
+"use client";
+import { useEffect, useState } from "react";
+
+export function COAViewer({ coaId }: { coaId: string }) {
+  const [html, setHtml] = useState("");
+
+  useEffect(() => {
+    fetch(\`/api/coa/\${coaId}/embed\`).then(r => r.json()).then(d => setHtml(d.html));
+  }, [coaId]);
+
+  return <div dangerouslySetInnerHTML={{ __html: html }} />;
+}`,
+        },
+        portal: {
+            raw_fetch: `// B2B portal login
+await fetch("${BASE}/v1/stores/${storeVar}/portal/auth/send-code", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({ email: "buyer@dispensary.com" })
+});
+
+// Verify and get session
+const session = await fetch("${BASE}/v1/stores/${storeVar}/portal/auth/verify", {
+  method: "POST",
+  headers: { "x-api-key": "${keyVar}", "Content-Type": "application/json" },
+  body: JSON.stringify({ email: "buyer@dispensary.com", code: "123456" })
+}).then(r => r.json());
+
+// List documents with portal token
+const { data: docs } = await fetch("${BASE}/v1/stores/${storeVar}/portal/documents", {
+  headers: { "x-api-key": "${keyVar}", "Authorization": "Bearer " + session.token }
+}).then(r => r.json());`,
+            nextjs_ssr: `// app/portal/layout.tsx — server-side session check
+import { cookies } from "next/headers";
+import { redirect } from "next/navigation";
+
+export default async function PortalLayout({ children }: { children: React.ReactNode }) {
+  const token = cookies().get("portal_token")?.value;
+  if (!token) redirect("/portal/login");
+  return <div className="portal-layout">{children}</div>;
+}`,
+            react_client: `// hooks/usePortal.ts
+import { useState } from "react";
+
+export function usePortal() {
+  const [token, setToken] = useState<string | null>(null);
+
+  const login = async (email: string, code: string) => {
+    const res = await fetch("/api/portal/verify", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email, code }),
+    });
+    const data = await res.json();
+    setToken(data.token);
+    return data;
+  };
+
+  const getDocuments = async () => {
+    const res = await fetch("/api/portal/documents", {
+      headers: { Authorization: \`Bearer \${token}\` },
+    });
+    return res.json();
+  };
+
+  return { token, login, getDocuments };
+}`,
+        },
+    };
+    return templates[section] ?? null;
+}
+// ---------------------------------------------------------------------------
+// Quick start guide
+// ---------------------------------------------------------------------------
+const QUICK_START = {
+    title: "WhaleTools API — Quick Start Guide",
+    steps: [
+        {
+            step: 1,
+            title: "Get your API key",
+            description: "Generate an API key from the WhaleTools dashboard (Settings → API Keys) or use the api_keys MCP tool.",
+            code: `// Via dashboard: Settings → API Keys → Generate
+// Or programmatically:
+// api_keys tool: { action: "generate", name: "My Website", scopes: ["read:products", "read:cart", "write:cart", "write:checkout"] }`,
+        },
+        {
+            step: 2,
+            title: "Set up environment variables",
+            description: "Store your API key and store ID securely. Never expose the API key in client-side code.",
+            code: `# .env.local (Next.js) or .env
+WHALE_API_KEY=wk_live_abc123...
+WHALE_STORE_ID=your-store-uuid`,
+        },
+        {
+            step: 3,
+            title: "Fetch products",
+            description: "Make your first API call to list published products.",
+            code: `const res = await fetch(
+  \`https://whale-gateway.fly.dev/v1/stores/\${process.env.WHALE_STORE_ID}/products?status=published&limit=25\`,
+  { headers: { "x-api-key": process.env.WHALE_API_KEY } }
+);
+const { data: products, has_more } = await res.json();
+console.log(\`Loaded \${products.length} products\`);`,
+        },
+        {
+            step: 4,
+            title: "Create a cart",
+            description: "Start a shopping session by creating a cart.",
+            code: `const cart = await fetch(
+  \`https://whale-gateway.fly.dev/v1/stores/\${STORE_ID}/cart\`,
+  {
+    method: "POST",
+    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
+    body: JSON.stringify({})
+  }
+).then(r => r.json());
+console.log("Cart ID:", cart.id);`,
+        },
+        {
+            step: 5,
+            title: "Add items to cart",
+            description: "Add products to the cart by product ID.",
+            code: `await fetch(
+  \`https://whale-gateway.fly.dev/v1/stores/\${STORE_ID}/cart/\${cart.id}/items\`,
+  {
+    method: "POST",
+    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
+    body: JSON.stringify({ product_id: products[0].id, quantity: 1 })
+  }
+);`,
+        },
+        {
+            step: 6,
+            title: "Checkout",
+            description: "Convert the cart into an order.",
+            code: `const order = await fetch(
+  \`https://whale-gateway.fly.dev/v1/stores/\${STORE_ID}/checkout\`,
+  {
+    method: "POST",
+    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
+    body: JSON.stringify({
+      cart_id: cart.id,
+      shipping_address: {
+        street: "123 Main St",
+        city: "Charlotte",
+        state: "NC",
+        zip: "28202"
+      }
+    })
+  }
+).then(r => r.json());
+console.log("Order created:", order.id, "Status:", order.status);`,
+        },
+    ],
+    tips: [
+        "Keep your API key server-side. Use Next.js Route Handlers or API routes as a proxy for client-side calls.",
+        "Use cursor pagination (starting_after) instead of offset for consistent results.",
+        "Set next: { revalidate: 60 } in Next.js fetch for automatic ISR (Incremental Static Regeneration).",
+        "Idempotency-Key header prevents duplicate orders — always set it on checkout requests.",
+        "All list endpoints return { object: 'list', data: [...], has_more: boolean }.",
+    ],
+};
+// ---------------------------------------------------------------------------
+// Main handler
+// ---------------------------------------------------------------------------
+export async function handleApiDocs(_sb, args, _storeId) {
+    const action = args.action;
+    switch (action) {
+        case "sections": {
+            const sections = Object.entries(SECTIONS).map(([key, s]) => ({
+                key,
+                name: s.name,
+                description: s.description,
+                endpoint_count: s.endpoints.length,
+            }));
+            return {
+                success: true,
+                data: {
+                    total_endpoints: sections.reduce((sum, s) => sum + s.endpoint_count, 0),
+                    sections,
+                    usage: 'Use api_docs with action "endpoints" and section "<key>" to see full endpoint details.',
+                },
+            };
+        }
+        case "endpoints": {
+            const section = args.section;
+            if (!section) {
+                return { success: false, error: 'Missing required param "section". Use action "sections" to see available sections.' };
+            }
+            const s = SECTIONS[section];
+            if (!s) {
+                return {
+                    success: false,
+                    error: `Unknown section "${section}". Available: ${Object.keys(SECTIONS).join(", ")}`,
+                };
+            }
+            return {
+                success: true,
+                data: {
+                    section: s.name,
+                    description: s.description,
+                    base: s.base,
+                    endpoints: s.endpoints,
+                },
+            };
+        }
+        case "auth": {
+            return { success: true, data: AUTH_GUIDE };
+        }
+        case "examples": {
+            const section = args.section;
+            if (!section) {
+                return { success: false, error: 'Missing required param "section". Use action "sections" to see available sections.' };
+            }
+            const examples = getExamples(section);
+            if (!examples) {
+                return {
+                    success: false,
+                    error: `No examples for section "${section}". Available: ${Object.keys(SECTIONS).join(", ")}`,
+                };
+            }
+            return {
+                success: true,
+                data: {
+                    section,
+                    examples,
+                    tip: "Always keep API keys server-side. Use Next.js Route Handlers or API routes as a proxy for client-side calls.",
+                },
+            };
+        }
+        case "quick_start": {
+            return { success: true, data: QUICK_START };
+        }
+        default:
+            return {
+                success: false,
+                error: `Unknown api_docs action: "${action}". Available: sections, endpoints, auth, examples, quick_start`,
+            };
+    }
+}