openapi: 3.1.0
info:
  title: monk-code-screen billing API
  version: 1.0.0
  description: |
    Billing/invoicing/payments backend. Invoices are ingested from CSV; rows failing
    validation (negative values, empty currency, missing/unparseable amount or dates)
    are stored with status `corrupted` rather than rejected.

    Money fields (`unit_price`, `amount`) are integer minor units (cents): CSV `150` → `15000`.
servers:
  - url: http://localhost:3000
# Explicitly unauthenticated: local interview skeleton, no auth layer
security: []

paths:
  /health:
    get:
      summary: Liveness check
      operationId: getHealth
      responses:
        "200":
          description: Service is up
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    const: true
                required: [ok]

  /customers:
    get:
      summary: List customers
      description: Ordered by `last_updated`. Customers are deduplicated by email (case-insensitive); rows without an email are keyed by name.
      operationId: listCustomers
      responses:
        "200":
          description: All customers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Customer"

  /customers/{id}/invoices:
    get:
      summary: List a customer's invoices
      description: Newest first. Unknown customer ids return an empty list.
      operationId: listCustomerInvoices
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: cus_1a2b3c4d
      responses:
        "200":
          description: The customer's invoices (empty array when the customer is unknown)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Invoice"

  /ingest:
    post:
      summary: Ingest invoices from CSV
      description: |
        CSV attached as the raw request body. Header must be exactly:
        `invoice_number,customer_name,customer_email,invoice_date,due_date,description,quantity,unit_price,amount,currency`

        Messy-but-parseable values are normalized (`1/12/26`, `Jan 16 2026`, `"$12,000.00"`, `"€1,850.00"`).
        Rows failing validation are still inserted with status `corrupted`.
        Not idempotent: re-posting the same file appends duplicate invoices (customers are deduplicated).
      operationId: ingestCsv
      requestBody:
        required: true
        content:
          text/csv:
            schema:
              type: string
            example: |
              invoice_number,customer_name,customer_email,invoice_date,due_date,description,quantity,unit_price,amount,currency
              INV-1001,Acme Corp,billing@acme.com,2026-01-05,2026-02-04,Consulting services,10,150,1500,USD
      responses:
        "200":
          description: Ingest summary with per-row results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IngestResult"
        "400":
          description: Empty body or unexpected CSV header
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /invoice/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: Surrogate id (`inv_...`) or invoice number (`INV-1001`). Duplicate invoice numbers resolve to the newest invoice.
        schema:
          type: string
        example: INV-1001
    get:
      summary: Get an invoice with its payments
      operationId: getInvoice
      responses:
        "200":
          description: The invoice (with status) and its payments (status owned by the external PSP)
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoice:
                    $ref: "#/components/schemas/Invoice"
                  payments:
                    type: array
                    items:
                      $ref: "#/components/schemas/Payment"
                required: [invoice, payments]
        "404":
          description: Invoice not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    put:
      summary: Update an invoice
      description: |
        Partial update of non-identity fields. `id`, `invoice_number`, `customer_id`, and
        `created_at` are immutable and rejected. At least one field is required.

        A `corrupted` invoice can be repaired by supplying the missing fields together with a
        new `status` in the same request; moving off `corrupted` while money/date fields are
        still missing fails the database CHECK and returns 400.
      operationId: updateInvoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InvoiceUpdate"
      responses:
        "200":
          description: The updated invoice
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
        "400":
          description: Validation error, unknown/immutable field, or integrity CHECK failure
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Invoice not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /payment/{invoice_id}:
    post:
      summary: Pay an invoice
      description: |
        Only `open` and `partially_paid` invoices are payable. Payments start as `pending`;
        status transitions are owned by the external PSP. `idempotency_key` is generated
        client-side: repeating a key replays the original payment instead of double-charging.
      operationId: createPayment
      parameters:
        - name: invoice_id
          in: path
          required: true
          description: Surrogate id (`inv_...`) or invoice number (`INV-1001`).
          schema:
            type: string
          example: INV-1011
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentCreate"
      responses:
        "201":
          description: Payment created (status `pending`)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentView"
        "200":
          description: Idempotent replay — the original payment for this key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentView"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Invoice not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Invoice is not payable (paid, void, or corrupted)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    Customer:
      type: object
      properties:
        id:
          type: string
          example: cus_1a2b3c4d
        customer_name:
          type: string
          example: Acme Corp
        customer_email:
          type: [string, "null"]
          description: Unique when present; null for rows ingested without an email.
          example: billing@acme.com
        last_updated:
          type: string
          example: "2026-08-10 14:33:55"
      required: [id, customer_name, customer_email, last_updated]

    Invoice:
      type: object
      description: Money fields are integer minor units (cents). Nullable fields are only null on `corrupted` invoices.
      properties:
        id:
          type: string
          example: inv_f726dd40
        invoice_number:
          type: string
          description: Not unique — duplicate numbers in source data are ingested as-is.
          example: INV-1011
        customer_id:
          type: [string, "null"]
          example: cus_1a2b3c4d
        status:
          $ref: "#/components/schemas/InvoiceStatus"
        created_at:
          type: string
          example: "2026-01-22"
        due_on:
          type: [string, "null"]
          example: "2026-02-21"
        description:
          type: [string, "null"]
          example: Security audit
        quantity:
          type: [integer, "null"]
          example: 1
        unit_price:
          type: [integer, "null"]
          description: Minor units (cents).
          example: 1500000
        amount:
          type: [integer, "null"]
          description: Minor units (cents).
          example: 1500000
        currency:
          type: [string, "null"]
          example: USD
      required:
        [id, invoice_number, customer_id, status, created_at, due_on, description, quantity, unit_price, amount, currency]

    InvoiceStatus:
      type: string
      enum: [open, partially_paid, paid, void, corrupted]

    InvoiceUpdate:
      type: object
      description: All fields optional, at least one required. Unknown or immutable fields are rejected.
      additionalProperties: false
      minProperties: 1
      properties:
        status:
          $ref: "#/components/schemas/InvoiceStatus"
        due_on:
          type: string
          format: date
          example: "2026-03-01"
        description:
          type: [string, "null"]
        quantity:
          type: integer
          minimum: 1
        unit_price:
          type: integer
          minimum: 0
          description: Minor units (cents).
        amount:
          type: integer
          minimum: 0
          description: Minor units (cents).
        currency:
          type: string
          minLength: 1
          description: Normalized to uppercase.
          example: USD

    Payment:
      type: object
      properties:
        id:
          type: string
          example: pay_4696225e
        idempotency_key:
          type: string
          format: uuid
        invoice_id:
          type: string
          example: inv_f726dd40
        status:
          type: string
          description: Owned by the external PSP; starts as `pending`.
          example: pending
        last_updated:
          type: string
          example: "2026-08-10 14:34:11"
        completed_at:
          type: [string, "null"]
        amount:
          type: integer
          description: Minor units (cents).
          example: 1500000
        currency:
          type: string
          example: USD
      required: [id, idempotency_key, invoice_id, status, last_updated, completed_at, amount, currency]

    PaymentCreate:
      type: object
      properties:
        idempotency_key:
          type: string
          format: uuid
          description: Generated client-side to prevent duplicate charges.
        amount:
          type: integer
          minimum: 1
          description: Minor units (cents).
        currency:
          type: string
          minLength: 1
      required: [idempotency_key, amount, currency]

    PaymentView:
      type: object
      properties:
        payment:
          $ref: "#/components/schemas/Payment"
      required: [payment]

    IngestResult:
      type: object
      properties:
        status:
          type: string
          const: ok
        ingested:
          type: integer
          description: Total rows inserted, including corrupted ones.
        errors:
          type: integer
          description: Count of rows stored with status `corrupted`.
        rows:
          type: array
          items:
            type: object
            properties:
              line:
                type: integer
                description: 1-based CSV line number (header is line 1).
              id:
                type: string
              invoice_number:
                type: string
              status:
                type: string
                enum: [open, corrupted]
              errors:
                type: array
                items:
                  type: string
            required: [line, id, invoice_number, status, errors]
      required: [status, ingested, errors, rows]

    Error:
      type: object
      properties:
        error:
          description: Message string, or a zod error tree for validation failures.
          oneOf:
            - type: string
            - type: object
      required: [error]