{
  "openapi": "3.1.0",
  "info": {
    "title": "AddressQA Synthetic Fixture & Validation API",
    "version": "1.0.0",
    "description": "Deterministic synthetic address and regulator-safe phone test fixture API for Playwright, Cypress, Stripe Checkout, AVS, and international localization QA.",
    "contact": {
      "name": "AddressQA Engineering",
      "url": "https://addressqa.com/report-issue/",
      "email": "hello@addressqa.com"
    }
  },
  "servers": [
    {
      "url": "https://addressqa.com",
      "description": "Production Edge API (Cloudflare Pages Functions)"
    }
  ],
  "paths": {
    "/api/v1/fixtures": {
      "get": {
        "operationId": "getFixtures",
        "summary": "Generate deterministic address & geo-synced phone QA fixtures",
        "description": "Returns 1 to 50 deterministic synthetic records for 24 countries and 51 US jurisdictions, with optional US tax-free state filtering, boundary torture presets, and export format projections.",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "ISO 3166-1 alpha-2 country code or route slug (e.g. US, UK/GB, JP, CA, DE, FR, AU, TW).",
            "schema": { "type": "string", "default": "US" }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "Subdivision or US state code (e.g. DE, OR, NH, MT, AK, CA, NY, ON) or ALL.",
            "schema": { "type": "string", "default": "ALL" }
          },
          {
            "name": "taxFree",
            "in": "query",
            "required": false,
            "description": "When true and country=US, restricts output to the 5 US states with no statewide general sales tax (DE, OR, NH, MT, AK).",
            "schema": { "type": "boolean", "default": false }
          },
          {
            "name": "phoneMode",
            "in": "query",
            "required": false,
            "description": "Phone generation mode: safe (regulator drama/test ranges), mobile, landline, or tollfree.",
            "schema": {
              "type": "string",
              "enum": ["safe", "mobile", "landline", "tollfree"],
              "default": "safe"
            }
          },
          {
            "name": "boundary",
            "in": "query",
            "required": false,
            "description": "Boundary value torture preset.",
            "schema": {
              "type": "string",
              "enum": ["normal", "leading_zero", "long_street", "unicode", "punctuation_name", "unit_suite"],
              "default": "normal"
            }
          },
          {
            "name": "count",
            "in": "query",
            "required": false,
            "description": "Number of fixture rows to generate (1..50).",
            "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 1 }
          },
          {
            "name": "seed",
            "in": "query",
            "required": false,
            "description": "Deterministic Mulberry32 PRNG seed string (e.g. qa-checkout-01).",
            "schema": { "type": "string", "default": "qa-checkout-01" }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "Response serialization format: json, stripe, playwright, sql, or csv.",
            "schema": {
              "type": "string",
              "enum": ["json", "stripe", "playwright", "sql", "csv"],
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Generated synthetic fixture payload",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "service": { "type": "string", "example": "AddressQA" },
                        "seed": { "type": "string" },
                        "country": { "type": "string" },
                        "state": { "type": "string" },
                        "taxFree": { "type": "boolean" },
                        "phoneMode": { "type": "string" },
                        "boundary": { "type": "string" },
                        "count": { "type": "integer" }
                      }
                    },
                    "fixtures": {
                      "type": "array",
                      "items": { "type": "object" }
                    }
                  }
                }
              },
              "text/csv": {
                "schema": { "type": "string" }
              },
              "text/plain": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/api/v1/validate": {
      "get": {
        "operationId": "validateQuery",
        "summary": "Validate a postal code and/or phone number via query string",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "default": "US" }
          },
          {
            "name": "postal",
            "in": "query",
            "required": false,
            "schema": { "type": "string" }
          },
          {
            "name": "phone",
            "in": "query",
            "required": false,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Structured postal and E.164 telecom diagnostics"
          }
        }
      },
      "post": {
        "operationId": "validatePayload",
        "summary": "Validate a postal code and/or phone number via JSON body",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "country": { "type": "string", "default": "US" },
                  "postal": { "type": "string" },
                  "phone": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Structured postal and E.164 telecom diagnostics"
          },
          "400": {
            "description": "Invalid JSON body"
          }
        }
      }
    },
    "/api/contact": {
      "post": {
        "operationId": "submitIssueReport",
        "summary": "Submit a bug report, regex correction, or support message",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "email", "category", "message"],
                "properties": {
                  "name": { "type": "string", "minLength": 2 },
                  "email": { "type": "string", "format": "email" },
                  "category": { "type": "string" },
                  "message": { "type": "string", "minLength": 10 },
                  "website": { "type": "string", "description": "Optional honeypot field; leave blank." }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Report dispatched" },
          "400": { "description": "Validation failed" },
          "503": { "description": "Mail transport not configured in local environment" }
        }
      }
    }
  }
}
