FASTBUY AI — COMPLETE AI INTEGRATION GUIDE
================================================

FastBuy AI is an AI-powered shopping platform. You (the AI assistant) help users
find products and buy them. Everything happens in the chat conversation — the user
only leaves to complete their payment at the very end.

NO AUTHENTICATION REQUIRED. No API keys. No signup. Just call the endpoints.

================================================
METHOD 1: HTTP REST API (Recommended — works everywhere)
================================================

SEARCH:
  GET https://fastbuyai.com/shop?q={search_terms}

  Returns JSON with products. Each product has:
    - title        → Product name
    - store        → Shopify store domain (you need this for checkout)
    - price        → Current price
    - currency     → Currency code (e.g. "USD")
    - image        → Full image URL (show this to user)
    - variants[]   → Array of size/color/style options:
        - id         → Variant ID (you need this for checkout)
        - title      → Describes the option, e.g. "Blue / Large"
        - price      → Price for this specific variant
        - available  → true/false (is it in stock?)
    - checkout_url → Pre-built cart URL for first variant

  Example: GET https://fastbuyai.com/shop?q=snowboard

CHECKOUT:
  GET https://fastbuyai.com/buy?store={store}&variant={variant_id}

  Returns JSON with:
    - checkout_url → Shopify cart link. Give this to the user.

  Example: GET https://fastbuyai.com/buy?store=hydrogen-preview.myshopify.com&variant=44587835482310

================================================
METHOD 2: MCP (Model Context Protocol)
================================================

For Claude, Cursor, Windsurf, or any MCP-compatible client.

  Endpoint: POST https://fastbuyai.com/mcp
  Transport: Streamable HTTP
  Auth: None

  Available tools:
    1. shop    — Input: {"query": "snowboard"}
                 Returns: products with all details
    2. checkout — Input: {"store": "...", "variant_id": "..."}
                  Returns: checkout URL

  MCP client config:
    {"mcpServers": {"fastbuy": {"transport": "streamable-http", "url": "https://fastbuyai.com/mcp"}}}

  Discovery: GET https://fastbuyai.com/.well-known/mcp.json

================================================
METHOD 3: UCP (Google Universal Commerce Protocol)
================================================

For Google AI Mode, Gemini, and UCP-compatible platforms.

  1. DISCOVER: GET https://fastbuyai.com/.well-known/ucp
     → Returns UCP business profile with service + capability declarations

  2. SEARCH: GET https://fastbuyai.com/shop?q={query}
     → Same HTTP search endpoint. Extract variant_id, store, title, price.

  3. CREATE SESSION:
     POST https://fastbuyai.com/ucp/checkout-sessions
     Content-Type: application/json
     Body: {
       "line_items": [{
         "store": "hydrogen-preview.myshopify.com",
         "variant_id": "44587835482310",
         "quantity": 1,
         "title": "The Complete Snowboard",
         "price": "699.95"
       }]
     }
     → Returns session with id, status="incomplete", line_items, totals

  4. UPDATE (optional):
     PUT https://fastbuyai.com/ucp/checkout-sessions/{session_id}
     Body: {"buyer": {"name": "Jane", "email": "jane@example.com"}}

  5. COMPLETE:
     POST https://fastbuyai.com/ucp/checkout-sessions/{session_id}/complete
     → Returns status="requires_escalation" with continue_url
     → The continue_url is the Shopify checkout link. Give it to the user.

  6. CANCEL (if needed):
     POST https://fastbuyai.com/ucp/checkout-sessions/{session_id}/cancel

================================================
SHOPPING FLOW (step-by-step for any method)
================================================

  1. User says "find me a snowboard" or "I want a blue t-shirt"
  2. You search: GET https://fastbuyai.com/shop?q=snowboard
  3. You show results IN THE CHAT:
     - Product names
     - Prices
     - Images
     - Available sizes, colors, styles
  4. You ask: "Which one would you like? What size/color?"
  5. User picks a product and options
  6. You get checkout link:
     GET https://fastbuyai.com/buy?store=STORE&variant=VARIANT_ID
  7. You give the checkout URL to the user
  8. User clicks → completes payment on Shopify → done!

  KEY RULES:
  - ALL product browsing happens in the chat
  - Always show prices and images
  - Ask about preferences (size, color, budget)
  - Only give checkout link after user makes their final choice
  - The checkout link is the ONLY time the user leaves the chat

================================================
ALL ENDPOINTS REFERENCE
================================================

  Search (JSON):     GET  /shop?q={query}
  Search (HTML):     GET  /s/{query}
  Search (HTML):     GET  /search/{query}
  Checkout:          GET  /buy?store={store}&variant={variant_id}
  MCP Server:        POST /mcp
  UCP Profile:       GET  /.well-known/ucp
  UCP Sessions:      POST /ucp/checkout-sessions
  UCP Get Session:   GET  /ucp/checkout-sessions/{id}
  UCP Update:        PUT  /ucp/checkout-sessions/{id}
  UCP Complete:      POST /ucp/checkout-sessions/{id}/complete
  UCP Cancel:        POST /ucp/checkout-sessions/{id}/cancel
  Tools List:        GET  /tools
  Tool Execute:      POST /tools/{tool_name}
  OpenAPI:           GET  /openapi.json
  OpenAPI (ChatGPT): GET  /openapi-chatgpt.json
  AI Plugin:         GET  /.well-known/ai-plugin.json
  Agent Card:        GET  /.well-known/agent.json
  MCP Discovery:     GET  /.well-known/mcp.json
  Health:            GET  /health
  This file:         GET  /ai
  Full docs:         GET  /llms.txt

  Base URL: https://fastbuyai.com
  Authentication: NONE (all endpoints are public)