openapi: 3.1.0
info:
  title: PlatPhorm Invoices API
  version: 0.1.0
  description: Solo-preneur invoicing, customer automation, assessment handoff, and PlatPhormNews network discovery API.
servers:
  - url: https://invoices.platphormnews.com
    description: Production
  - url: http://localhost:3000
    description: Local development
security:
  - PlatformApiKey: []
paths:
  /api/health:
    get:
      summary: Public platform health
      responses:
        "200":
          description: Health payload
  /api/v1/health:
    get:
      summary: Versioned public platform health
      responses:
        "200":
          description: Health payload
  /api/docs:
    get:
      summary: API and platform documentation
      responses:
        "200":
          description: Route, MCP, auth, and trust documentation
  /api/invoices:
    get:
      summary: List saved invoices
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [draft, sent, viewed, overdue, paid, writeoff]
      responses:
        "200":
          description: Invoice list
    post:
      summary: Create a saved draft invoice
      description: Public operator endpoint. Local development writes to data/invoice-store.local.json; deployed environments write to private Vercel Blob JSON storage when configured.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [customerName, description, amountCents]
              properties:
                customerName:
                  type: string
                contactName:
                  type: string
                email:
                  type: string
                  format: email
                description:
                  type: string
                amountCents:
                  type: integer
                  minimum: 1
                dueInDays:
                  type: integer
                  minimum: 0
                  maximum: 120
      responses:
        "201":
          description: Draft invoice saved
        "422":
          description: Invalid input
  /api/invoices/{id}:
    get:
      summary: Read one invoice
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Invoice detail
        "404":
          description: Invoice not found
    patch:
      summary: Update an invoice status
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status:
                  type: string
                  enum: [draft, sent, viewed, overdue, paid, writeoff]
      responses:
        "200":
          description: Updated invoice detail
        "404":
          description: Invoice not found
        "422":
          description: Invalid status
  /api/invoices/{id}/actions:
    get:
      summary: List stored invoice action artifacts
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Stored reminder, payment-plan, and receipt artifacts for the invoice
    post:
      summary: Create an invoice action artifact
      description: Creates a persisted reminder, payment plan, or receipt artifact from real invoice/customer state. Receipts are not generated for unpaid invoices; the response stores a not_applicable artifact instead.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [action]
              properties:
                action:
                  type: string
                  enum: [reminder, payment_plan, receipt]
      responses:
        "201":
          description: Stored invoice action artifact
        "404":
          description: Invoice not found
        "422":
          description: Invalid action
  /api/invoices/preview:
    post:
      summary: Create a public invoice preview
      description: Returns a non-durable invoice preview. No downstream write is performed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [customerName, description, amountCents]
              properties:
                customerName:
                  type: string
                description:
                  type: string
                amountCents:
                  type: integer
                  minimum: 1
      responses:
        "200":
          description: Preview invoice
        "422":
          description: Invalid input
  /api/customers:
    get:
      summary: List customers
      responses:
        "200":
          description: Customer list
  /api/automations:
    get:
      summary: List automation rules
      responses:
        "200":
          description: Automation rules
    post:
      summary: Preview an automation run
      description: Public operator endpoint. Backend service execution uses PLATPHORM_API_KEY when configured.
      responses:
        "200":
          description: Execution status
  /api/integrations/status:
    get:
      summary: Run public read-only integration status checks
      description: Performs bounded public GET checks against platphormnews.com, assessments, docs, notes, and mcp services. No receipts are stored.
      responses:
        "200":
          description: Integration status receipt list
  /api/integrations/sync:
    post:
      summary: Sync one invoice with PlatPhormNews services
      description: Performs real bounded service calls and stores integration receipts. Protected backend targets use PLATPHORM_API_KEY server-side.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [invoiceId]
              properties:
                invoiceId:
                  type: string
                assessmentToken:
                  type: string
                targets:
                  type: array
                  items:
                    type: string
                    enum: [platphormnews, assessments, docs, notes, mcp]
      responses:
        "200":
          description: Stored integration receipts
        "404":
          description: Invoice not found
        "422":
          description: Invalid input
  /api/network/handoff:
    post:
      summary: Compatibility alias for invoice integration sync
      description: Runs the same receipt-backed cross-site calls as /api/integrations/sync.
      responses:
        "200":
          description: Integration sync receipt state
  /api/mcp:
    get:
      summary: MCP metadata
      responses:
        "200":
          description: MCP usage metadata
    post:
      summary: MCP JSON-RPC endpoint
      description: Supports initialize, ping, tools/list, tools/call, resources/list, resources/read, prompts/list, and prompts/get.
      responses:
        "200":
          description: JSON-RPC response
        "400":
          description: Invalid JSON-RPC request
  /api/web/status:
    get:
      summary: Machine-readable Web Status
      responses:
        "200":
          description: Web Status scorecard
components:
  securitySchemes:
    PlatformApiKey:
      type: apiKey
      in: header
      name: X-PlatPhorm-API-Key
      description: Use PLATPHORM_API_KEY. Authorization: Bearer $PLATPHORM_API_KEY is also accepted for protected backend service calls.