{
  "openapi": "3.0.3",
  "info": {
    "title": "PDF Generation API",
    "description": "Generate professional PDFs from structured JSON. POST a template name and typed data; receive `application/pdf` bytes. No HTML or CSS required. Authenticate with the `X-API-Key` header.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://pdfapi-nu.vercel.app",
      "description": "Production"
    }
  ],
  "tags": [
    { "name": "Generate", "description": "PDF generation" },
    { "name": "Templates", "description": "Template metadata" }
  ],
  "paths": {
    "/api/v1/generate": {
      "post": {
        "tags": ["Generate"],
        "summary": "Generate a PDF from JSON",
        "description": "Renders a PDF for the given template and data. Success responses are raw PDF bytes (`application/pdf`). Errors return JSON with an `error` object.",
        "operationId": "generatePdf",
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  { "$ref": "#/components/schemas/GenerateInvoiceRequest" },
                  { "$ref": "#/components/schemas/GenerateReceiptRequest" },
                  { "$ref": "#/components/schemas/GenerateReportRequest" }
                ],
                "discriminator": {
                  "propertyName": "template",
                  "mapping": {
                    "invoice": "#/components/schemas/GenerateInvoiceRequest",
                    "receipt": "#/components/schemas/GenerateReceiptRequest",
                    "report": "#/components/schemas/GenerateReportRequest"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "PDF document generated successfully.",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON or validation failure (`INVALID_JSON`, `VALIDATION_ERROR`).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key (`UNAUTHORIZED`).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded or monthly quota exceeded.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Server or rendering error (`INTERNAL_ERROR`, `RENDER_FAILED`, `CHROME_NOT_FOUND`, etc.).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v1/templates": {
      "get": {
        "tags": ["Templates"],
        "summary": "List available PDF templates",
        "description": "Returns metadata for each template, including id, display name, and description.",
        "operationId": "listTemplates",
        "security": [],
        "responses": {
          "200": {
            "description": "Template list.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TemplatesListResponse" }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key from the dashboard. Send as header `X-API-Key: <your-key>`."
      }
    },
    "schemas": {
      "InvoiceLineItem": {
        "type": "object",
        "required": ["description", "quantity", "unitPrice"],
        "properties": {
          "description": { "type": "string", "minLength": 1 },
          "quantity": { "type": "number", "exclusiveMinimum": 0 },
          "unitPrice": { "type": "number", "minimum": 0 }
        }
      },
      "InvoiceData": {
        "type": "object",
        "required": ["companyName", "fromAddress", "toAddress", "lineItems", "taxRate"],
        "properties": {
          "companyName": { "type": "string", "minLength": 1 },
          "fromAddress": { "type": "string", "minLength": 1 },
          "toAddress": { "type": "string", "minLength": 1 },
          "lineItems": {
            "type": "array",
            "minItems": 1,
            "items": { "$ref": "#/components/schemas/InvoiceLineItem" }
          },
          "taxRate": {
            "type": "number",
            "minimum": 0,
            "description": "Decimal tax rate applied to subtotal (e.g. 0.08 for 8%)."
          }
        }
      },
      "GenerateInvoiceRequest": {
        "type": "object",
        "required": ["template", "data"],
        "properties": {
          "template": { "type": "string", "enum": ["invoice"] },
          "data": { "$ref": "#/components/schemas/InvoiceData" }
        }
      },
      "ReceiptData": {
        "type": "object",
        "required": ["merchantName", "date", "items", "amountPaid", "paymentMethodLast4"],
        "properties": {
          "merchantName": { "type": "string", "minLength": 1 },
          "date": { "type": "string", "minLength": 1 },
          "items": {
            "type": "array",
            "minItems": 1,
            "items": { "type": "string", "minLength": 1 }
          },
          "amountPaid": { "type": "number", "minimum": 0 },
          "paymentMethodLast4": {
            "type": "string",
            "pattern": "^\\d{4}$",
            "description": "Exactly four digits (e.g. last four of card number)."
          }
        }
      },
      "GenerateReceiptRequest": {
        "type": "object",
        "required": ["template", "data"],
        "properties": {
          "template": { "type": "string", "enum": ["receipt"] },
          "data": { "$ref": "#/components/schemas/ReceiptData" }
        }
      },
      "ReportSummaryStat": {
        "type": "object",
        "required": ["label", "value"],
        "properties": {
          "label": { "type": "string", "minLength": 1 },
          "value": {
            "oneOf": [{ "type": "string" }, { "type": "number" }]
          }
        }
      },
      "ReportTableRow": {
        "type": "object",
        "additionalProperties": true,
        "description": "Flexible key-value row. Values are typically string, number, boolean, or null."
      },
      "ReportData": {
        "type": "object",
        "required": ["title", "dateRange", "summaryStats", "tableData"],
        "properties": {
          "title": { "type": "string", "minLength": 1 },
          "dateRange": { "type": "string", "minLength": 1 },
          "summaryStats": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ReportSummaryStat" }
          },
          "tableData": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ReportTableRow" }
          }
        }
      },
      "GenerateReportRequest": {
        "type": "object",
        "required": ["template", "data"],
        "properties": {
          "template": { "type": "string", "enum": ["report"] },
          "data": { "$ref": "#/components/schemas/ReportData" }
        }
      },
      "TemplateMeta": {
        "type": "object",
        "required": ["id", "name", "description"],
        "properties": {
          "id": { "type": "string", "example": "invoice" },
          "name": { "type": "string", "example": "Invoice" },
          "description": { "type": "string" }
        }
      },
      "TemplatesListResponse": {
        "type": "object",
        "required": ["templates"],
        "properties": {
          "templates": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/TemplateMeta" }
          }
        }
      },
      "ApiError": {
        "type": "object",
        "required": ["code", "message"],
        "properties": {
          "code": {
            "type": "string",
            "examples": ["INVALID_JSON", "VALIDATION_ERROR", "UNAUTHORIZED", "QUOTA_EXCEEDED", "INTERNAL_ERROR", "RENDER_FAILED"]
          },
          "message": { "type": "string" },
          "details": {
            "description": "Optional structured details (e.g. Zod field errors for validation)."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "$ref": "#/components/schemas/ApiError" }
        }
      }
    }
  }
}