# Romeo15 2026-08-26 -- static OpenAPI 3.0 spec for the v1 API surface.
# Companion to /api/openapi.json (v0 v3.1 spec). This yaml is Postman-
# import-friendly and intentionally scoped to the three v1 enterprise
# endpoints so procurement can review a small, stable contract without
# wading through the full v0 web surface.
openapi: 3.0.3
info:
  title: Digital Empire portfolio v1 API
  version: 1.0.0-beta
  description: |
    v1 API for PixelProof, EntryProof, and TariffWatch.

    All endpoints require `Authorization: Bearer de_<key>`. Contact
    hello@citationsafe.com to request a beta key. Rate limits: 100
    requests/minute and 10,000 requests/day per key.

    Beta status: valid keys currently return 403 with
    `{ "error": "beta" }` unless enrolled in delegate mode. The
    contract shapes below are stable and safe to build against.
  contact:
    name: Digital Empire Holdings LLC
    email: hello@citationsafe.com
    url: https://digital-empire-app.vercel.app/
  license:
    name: Proprietary
    url: https://digital-empire-app.vercel.app/meta-monitor/terms
servers:
  - url: https://digital-empire-app.vercel.app
    description: Production
security:
  - bearerAuth: []
tags:
  - name: TariffWatch
    description: Section 232 HTS lookup + comment-letter filing.
  - name: PixelProof
    description: Shopify + Meta Pixel drift monitoring.
  - name: EntryProof
    description: CPSC eFile GCC generation.
paths:
  /api/v1/tariffwatch/hts/lookup:
    post:
      tags: [TariffWatch]
      summary: Look up one or more HTS codes against the BIS-14 derivative list.
      operationId: htsLookup
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [codes]
              properties:
                codes:
                  type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    type: string
                  example: ["7601.10.6000", "7603.10.0000"]
      responses:
        '200':
          description: Lookup results
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/HtsLookupResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Beta'
  /api/v1/pixelproof/scan:
    post:
      tags: [PixelProof]
      summary: Scan a Shopify storefront for legacy Meta Pixel / GA4 / GTM code.
      operationId: pixelproofScan
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url:
                  type: string
                  format: uri
                  example: https://your-store.myshopify.com
      responses:
        '200':
          description: Scan report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanReport'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Beta'
  /api/v1/entryproof/gcc/generate:
    post:
      tags: [EntryProof]
      summary: Generate a General Certificate of Conformity (GCC) PDF.
      operationId: entryproofGccGenerate
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [product_info, manufacturer, testing_lab]
              properties:
                product_info:
                  type: object
                  properties:
                    name: { type: string }
                    model: { type: string }
                    sku: { type: string }
                    date_of_manufacture: { type: string, format: date }
                    place_of_manufacture: { type: string }
                manufacturer:
                  type: object
                  properties:
                    name: { type: string }
                    address: { type: string }
                    contact_email: { type: string, format: email }
                testing_lab:
                  type: object
                  properties:
                    name: { type: string }
                    accreditation_id: { type: string }
                    test_date: { type: string, format: date }
                cpsc_rules_cited:
                  type: array
                  items: { type: string }
      responses:
        '200':
          description: Certificate generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  gcc_pdf_url: { type: string, format: uri }
                  gcc_id: { type: string, format: uuid }
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Beta'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: de_<24 chars>
  responses:
    Unauthorized:
      description: Missing / malformed / unknown key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Beta:
      description: Beta -- contact hello@ to enable delegate mode
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  schemas:
    ErrorEnvelope:
      type: object
      properties:
        error: { type: string, example: beta }
        message: { type: string }
        contact: { type: string, example: hello@citationsafe.com }
    HtsLookupResult:
      type: object
      properties:
        code: { type: string, example: "7601.10.6000" }
        hit: { type: boolean }
        in_scope: { type: boolean }
        status:
          type: string
          enum: [hit, adjacent, in_scope_no_bis14, clear, invalid]
        adjacent_hits:
          type: array
          items:
            type: object
            properties:
              code_heading: { type: string }
              article_slug: { type: string }
              article_name: { type: string }
              proposed_rate: { type: number }
    ScanReport:
      type: object
      properties:
        score: { type: integer, minimum: 0, maximum: 100 }
        findings:
          type: array
          items:
            type: object
            properties:
              rule_id: { type: string }
              severity: { type: string, enum: [info, warn, error] }
              message: { type: string }
        severity_counts:
          type: object
          properties:
            info: { type: integer }
            warn: { type: integer }
            error: { type: integer }