# Ancore OS OpenAPI Specification
openapi: 3.1.0
info:
  title: Ancore OS API
  version: 2.0.0
  description: Machine-readable API specification for Ancore OS — Shopify Risk Diagnosis, Compliance Audit & Verification Proof System.
  contact:
    name: PARDPRO TECHNOLOGIES LTD.
    url: "https://ancore.pardpro.ca/docs"
    email: info@pardpro.ca
  license:
    name: Proprietary
    url: "https://ancore.pardpro.ca/legal/terms"
servers:
  - url: "https://ancore.pardpro.ca"
    description: Production API Server
security:
  - BearerAuth: []
  - OAuth2:
      - "read:scan"
      - "write:scan"
      - "read:reports"
      - "write:reports"
      - "read:tasks"
      - "write:tasks"
paths:
  /api/scan/public:
    post:
      operationId: triggerPublicScan
      summary: Execute Lightweight Storefront Compliance Audit
      description: Executes a public, non-authenticated storefront compliance scan against a Shopify domain. Returns overall health score, critical risk count, and category breakdown.
      tags:
        - Public Audit
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - domain
              properties:
                domain:
                  type: string
                  example: auragoods.myshopify.com
                  description: Target Shopify store domain or URL
      responses:
        200:
          description: Storefront audit payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  domain:
                    type: string
                  overallScore:
                    type: integer
                    example: 78
                  affectedProducts:
                    type: integer
                    example: 14
                  criticalRisks:
                    type: integer
                    example: 2
                  findings:
                    type: array
                    items:
                      type: object
                      properties:
                        title:
                          type: string
                        severity:
                          type: string
                          enum:
                            - CRITICAL
                            - HIGH
                            - MEDIUM
                            - LOW
                        category:
                          type: string
        400:
          description: Invalid domain or payload error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        403:
          description: Domain security policy violation (e.g. localhost/SSRF attempt)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/scan:
    post:
      operationId: triggerDeepScan
      summary: Execute Deep Store & Feed Audit
      description: Requires authenticated session and active subscription plan. Triggers a full edge scan for a connected Shopify store ID.
      tags:
        - Store Operations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - storeId
              properties:
                storeId:
                  type: string
                  example: STORE-101
      responses:
        200:
          description: Scan completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  storeId:
                    type: string
                  issuesCount:
                    type: integer
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        403:
          description: Subscription entitlement error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/reports/download:
    get:
      operationId: downloadExecutiveReport
      summary: Generate Executive White-Label PDF Report
      description: Generates a downloadable PDF report for a store ID. Requires active subscription.
      tags:
        - Reports & Proof
      parameters:
        - name: storeId
          in: query
          required: true
          schema:
            type: string
          description: ID of the target store
      responses:
        200:
          description: PDF Document stream
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/stripe/checkout:
    post:
      operationId: createCheckoutSession
      summary: Create Stripe Checkout Session
      description: Creates a Stripe subscription session for Starter, Pro, or Agency plans.
      tags:
        - Billing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - plan
              properties:
                plan:
                  type: string
                  enum:
                    - starter
                    - pro
                    - agency
                billingPeriod:
                  type: string
                  enum:
                    - monthly
                    - yearly
      responses:
        200:
          description: Stripe checkout URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    example: "https://checkout.stripe.com/c/pay/..."
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "Provide Supabase JWT or Access Token in Authorization header: Bearer <token>"
    OAuth2:
      type: oauth2
      description: Shopify OAuth 2.0 Authorization Server
      flows:
        authorizationCode:
          authorizationUrl: "https://ancore.pardpro.ca/api/auth/shopify"
          tokenUrl: "https://ancore.pardpro.ca/api/auth/shopify/callback"
          scopes:
            read:scan: Read store audit scan results
            write:scan: Trigger store audit scans
            read:reports: Read store reports and verification receipts
            write:reports: Generate executive reports
            read:tasks: Read priority tasks
            write:tasks: Apply suggested fixes and resolve tasks
  schemas:
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              example: UNAUTHORIZED
            message:
              type: string
              example: Authentication required
            hint:
              type: string
              example: Provide a valid session or Bearer token header