openapi: "3.1.0"
info:
  title: GEO Agent
  version: "0.1.0"
  description: Shopify app for heuristic catalog-readiness audits, sampled model responses, and merchant-reviewed product fixes.
servers:
  - url: https://geo-agent.fly.dev
paths:
  /.well-known/agent.json:
    get:
      summary: Agent-facing manifest
      responses:
        "200":
          description: Agent manifest with Shopify billing commerce endpoints.
          content:
            application/json:
              schema:
                type: object
  /.well-known/commerce.json:
    get:
      summary: Agent-readable commerce manifest
      responses:
        "200":
          description: Shopify Billing catalog and checkout constraints.
          content:
            application/json:
              schema:
                type: object
  /api/v1/catalog:
    get:
      summary: List Geo Agent subscription plans
      responses:
        "200":
          description: Static catalog of Shopify Billing plans.
          content:
            application/json:
              schema:
                type: object
  /api/v1/quote:
    get:
      summary: Static quote catalog
      responses:
        "200":
          description: Static pricing for Starter, Growth, and Enterprise plans.
          content:
            application/json:
              schema:
                type: object
  /api/v1/checkout:
    get:
      summary: Shopify Billing checkout handoff
      responses:
        "200":
          description: Shopify install URL and billing-approval constraints for app subscriptions. External checkout and machine-payment modes are not enabled for the app-review path.
          content:
            application/json:
              schema:
                type: object
    post:
      summary: Return Shopify Billing checkout handoff
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [payment_mode]
              properties:
                product_id:
                  type: string
                  enum: [geo_agent_starter, geo_agent_growth, geo_agent_enterprise]
                payment_mode:
                  type: string
                  enum: [shopify_billing]
      responses:
        "200":
          description: Merchant must install from a Shopify-owned App Store or Admin surface and approve billing inside Shopify Admin.
  /app-review:
    get:
      summary: Shopify app-review packet
      responses:
        "200":
          description: Human-readable reviewer packet for scopes, billing, app proxy, compliance webhooks, and demo flow.
          content:
            text/html:
              schema:
                type: string
  /app-review.json:
    get:
      summary: Machine-readable Shopify app-review packet
      responses:
        "200":
          description: Structured reviewer packet for scopes, billing, app proxy, compliance webhooks, and demo flow.
          content:
            application/json:
              schema:
                type: object
  /app-review-submission-checklist.md:
    get:
      summary: Shopify app-review submission checklist
      responses:
        "200":
          description: Partner Dashboard field checklist, proof routes, manual gates, and review guardrails.
          content:
            text/markdown:
              schema:
                type: string
  /app-review-media-plan.md:
    get:
      summary: Shopify app-review media plan
      responses:
        "200":
          description: Screenshot captions and demo screencast runbook for Shopify review submission.
          content:
            text/markdown:
              schema:
                type: string
  /app-review-tester-instructions.md:
    get:
      summary: Shopify app-review tester instructions
      responses:
        "200":
          description: Partner Dashboard testing instructions for Shopify reviewers.
          content:
            text/markdown:
              schema:
                type: string
  /app-review-app-proxy-verification.md:
    get:
      summary: Shopify app-review app proxy verification guide
      responses:
        "200":
          description: Signed app-proxy verification guide for Shopify review stores.
          content:
            text/markdown:
              schema:
                type: string
  /app-review-billing-verification.md:
    get:
      summary: Shopify app-review billing verification guide
      responses:
        "200":
          description: Shopify Billing-only subscription approval and callback verification steps.
          content:
            text/markdown:
              schema:
                type: string
  /app-review-data-use.md:
    get:
      summary: Shopify app-review data-use appendix
      responses:
        "200":
          description: Protected-customer-data and data-minimization appendix for Shopify review.
          content:
            text/markdown:
              schema:
                type: string
  /app-review-ai-self-review.md:
    get:
      summary: Shopify app-review AI self-review answer packet
      responses:
        "200":
          description: Paste-ready AI self-review answers for Shopify App Store review.
          content:
            text/markdown:
              schema:
                type: string
  /app-review-evidence-ledger.md:
    get:
      summary: Shopify app-review evidence ledger
      responses:
        "200":
          description: Current automated proof, remaining dashboard-only gates, and submission guardrails.
          content:
            text/markdown:
              schema:
                type: string
  /app-review-partner-dashboard-fields.md:
    get:
      summary: Shopify app-review Partner Dashboard field packet
      responses:
        "200":
          description: Paste-ready Partner Dashboard field values, disclosure text, proof links, and final submission boundary.
          content:
            text/markdown:
              schema:
                type: string
  /app-review-final-submission-runbook.md:
    get:
      summary: Shopify app-review final submission runbook
      responses:
        "200":
          description: Last-mile Partner Dashboard sequence, submit boundary, and post-submit response workflow.
          content:
            text/markdown:
              schema:
                type: string
  /app-review-response-playbook.md:
    get:
      summary: Shopify app-review response playbook
      responses:
        "200":
          description: Narrow response templates and verification steps for Shopify review feedback.
          content:
            text/markdown:
              schema:
                type: string
  /:
    get:
      summary: Public product entrypoint
      responses:
        "200":
          description: Product landing page or Shopify install form.
  /auth/login:
    get:
      summary: Handle Shopify OAuth when Shopify supplies shop context
      description: Public merchant installs should start from Shopify-owned App Store or Admin surfaces. This route does not provide a standalone manual shop-domain install form.
      responses:
        "302":
          description: Redirects to Shopify OAuth when a valid Shopify shop context is present.
        "200":
          description: Displays install guidance when no Shopify shop context is present.
  /api/llms-txt:
    get:
      summary: Return generated llms.txt for an installed Shopify shop
      responses:
        "200":
          description: Generated llms.txt content.
          content:
            text/plain:
              schema:
                type: string
        "401":
          description: Missing Shopify app-proxy session.
  /api/product-schema/{handle}:
    get:
      summary: Return product JSON-LD for an installed Shopify shop
      parameters:
        - name: handle
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Product schema response.
          content:
            application/json:
              schema:
                type: object
        "401":
          description: Missing Shopify app-proxy session.
  /api/ucp:
    get:
      summary: Return Shopify-managed Storefront MCP and UCP catalog endpoints for an installed shop
      responses:
        "200":
          description: Shopify-managed endpoint discovery response.
          content:
            application/json:
              schema:
                type: object
        "401":
          description: Missing Shopify app-proxy session.