openapi.yaml

openapi: 3.0.3
info:
    title: Adblock Compiler API
    description: |
        **Compiler-as-a-Service** for adblock filter lists. Transform, optimize, and combine filter lists from multiple sources with real-time progress tracking.

        ## Features
        - 🎯 Multi-Source Compilation
        - ⚡ Performance (Gzip compression, caching, request deduplication)
        - 🔄 Circuit Breaker with retry logic
        - 📊 Visual Diff between compilations
        - 📡 Real-time progress via SSE and WebSocket
        - 🎪 Batch Processing
        - 🌍 Universal (Deno, Node.js, Cloudflare Workers, browsers)

        ## Links
        - [GitHub Repository](https://github.com/jaypatrick/adblock-compiler)
        - [Documentation](https://github.com/jaypatrick/adblock-compiler/tree/master/docs)
        - [Web UI](https://adblock-compiler.jayson-knight.workers.dev/)

    version: 2.0.0
    license:
        name: GPL-3.0
        url: https://github.com/jaypatrick/adblock-compiler/blob/master/LICENSE
    contact:
        name: Jayson Knight
        url: https://github.com/jaypatrick/adblock-compiler

servers:
    - url: https://adblock-compiler.jayson-knight.workers.dev
      description: Production server
    - url: http://localhost:8787
      description: Local development server

tags:
    - name: Compilation
      description: Filter list compilation endpoints
    - name: Streaming
      description: Real-time event streaming endpoints
    - name: Queue
      description: Async job queue management
    - name: Metrics
      description: Performance metrics and statistics
    - name: WebSocket
      description: Bidirectional real-time communication
    - name: Admin
      description: Administration endpoints for storage, auth, migration, and backends (require X-Admin-Key header)
    - name: Workflow
      description: Durable execution workflow endpoints
    - name: Health
      description: Health monitoring endpoints
    - name: Browser Rendering
      description: Endpoints backed by the Cloudflare Browser Rendering binding (`BROWSER`). Used for resolving redirect chains and monitoring filter-list source URLs for changes.
    - name: Authentication
      description: User-level authentication endpoints — API key management and webhook receivers. Requires Clerk JWT or API key auth.
    - name: LocalAuth
      description: Local JWT auth bridge — self-contained sign-up/login until Clerk is production-ready. When `CLERK_JWKS_URL` is set the provider auto-switches to Clerk and these endpoints are no longer used.
    - name: Info
      description: API metadata and self-describing schema endpoints (anonymous access, cached).
    - name: Configuration
      description: Compilation configuration defaults, validation, and resolution endpoints.

paths:
    /api:
        get:
            tags: [Metrics]
            summary: Get API information
            description: Returns API version, available endpoints, and usage examples
            operationId: getApiInfo
            responses:
                '200':
                    description: API information
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ApiInfo'

    /api/schemas:
        get:
            tags: [Info]
            operationId: getApiSchemas
            summary: Get JSON Schemas for all public request/response types
            description: |
                Returns JSON Schema representations of all public Zod schemas
                (ConfigurationSchema, CompileRequestSchema, SourceSchema, BenchmarkMetricsSchema)
                for use by API testers and external tooling.
                Anonymous access. Cached for 1 hour.
            responses:
                '200':
                    description: JSON Schema definitions.
                    headers:
                        Cache-Control:
                            schema: { type: string, example: 'public, max-age=3600' }
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    success: { type: boolean, example: true }
                                    schemas:
                                        type: object
                                        additionalProperties:
                                            type: object
                                            description: A JSON Schema definition object.
                '429':
                    $ref: '#/components/responses/RateLimited'

    /compile:
        post:
            tags: [Compilation]
            summary: Compile filter list (JSON)
            description: |
                Compile filter lists and return results as JSON. Results are cached for 1 hour.
                Supports request deduplication for concurrent identical requests.
            operationId: compileJson
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CompileRequest'
                        examples:
                            simple:
                                summary: Simple compilation
                                value:
                                    configuration:
                                        name: My Filter List
                                        sources:
                                            - source: https://example.com/filters.txt
                                              transformations:
                                                  - RemoveComments
                                                  - Validate
                                        transformations:
                                            - Deduplicate
                            withPreFetched:
                                summary: With pre-fetched content
                                value:
                                    configuration:
                                        name: Custom Rules
                                        sources:
                                            - source: my-custom-rules
                                    preFetchedContent:
                                        my-custom-rules: "||ads.example.com^\n||tracking.example.com^"
            responses:
                '200':
                    description: Compilation successful
                    headers:
                        X-Cache:
                            schema:
                                type: string
                                enum: [HIT, MISS]
                            description: Cache hit/miss status
                        X-Request-Deduplication:
                            schema:
                                type: string
                                enum: [HIT]
                            description: Present if request was deduplicated
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CompileResponse'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '429':
                    $ref: '#/components/responses/RateLimitError'
                '500':
                    $ref: '#/components/responses/CompilationError'

    /compile/stream:
        post:
            tags: [Streaming]
            summary: Compile with real-time progress (SSE)
            description: |
                Compile filter lists with real-time progress updates via Server-Sent Events.
                Streams events including source downloads, transformations, diagnostics, cache operations, network events, and metrics.
            operationId: compileStream
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CompileRequest'
            responses:
                '200':
                    description: Event stream
                    content:
                        text/event-stream:
                            schema:
                                type: string
                                description: |
                                    Server-Sent Events stream with the following event types:

                                    **Compilation Events:**
                                    - `log` - Log messages (info, warn, error, debug)
                                    - `source:start` - Source download started
                                    - `source:complete` - Source download completed
                                    - `source:error` - Source download failed
                                    - `transformation:start` - Transformation started
                                    - `transformation:complete` - Transformation completed
                                    - `progress` - Compilation progress update
                                    - `result` - Final compilation result
                                    - `done` - Compilation finished
                                    - `error` - Compilation error

                                    **Enhanced Events:**
                                    - `diagnostic` - Diagnostic event from tracing system
                                    - `cache` - Cache operation (hit/miss/write)
                                    - `network` - Network operation (HTTP requests)
                                    - `metric` - Performance metric
                            examples:
                                logEvent:
                                    value: |
                                        event: log
                                        data: {"level":"info","message":"Fetching source..."}
                                sourceStart:
                                    value: |
                                        event: source:start
                                        data: {"source":{"name":"Source 1","source":"https://..."},"sourceIndex":0,"totalSources":2}
                                diagnostic:
                                    value: |
                                        event: diagnostic
                                        data: {"eventId":"evt-123","timestamp":"2026-01-14T05:00:00Z","category":"compilation","severity":"info","message":"Started compilation"}
                                cache:
                                    value: |
                                        event: cache
                                        data: {"operation":"hit","key":"cache:abc123","size":1024}
                                network:
                                    value: |
                                        event: network
                                        data: {"method":"GET","url":"https://example.com/filters.txt","statusCode":200,"durationMs":234,"responseSize":51200}
                                metric:
                                    value: |
                                        event: metric
                                        data: {"metric":"download_speed","value":218.5,"unit":"KB/s"}
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '429':
                    $ref: '#/components/responses/RateLimitError'

    /compile/batch:
        post:
            tags: [Compilation]
            summary: Batch compile multiple lists
            description: Compile multiple filter lists in parallel (max 10 per batch)
            operationId: compileBatch
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/BatchCompileRequest'
            responses:
                '200':
                    description: Batch compilation results
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BatchCompileResponse'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '429':
                    $ref: '#/components/responses/RateLimitError'

    /compile/async:
        post:
            tags: [Queue]
            summary: Queue async compilation job
            description: |
                Queue a compilation job for asynchronous processing. Returns immediately with a request ID.
                Use GET /queue/results/{requestId} to retrieve results when complete.
            operationId: compileAsync
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CompileRequest'
            responses:
                '202':
                    description: Job queued successfully
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/QueueResponse'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '500':
                    $ref: '#/components/responses/ServiceUnavailable'

    /compile/batch/async:
        post:
            tags: [Queue]
            summary: Queue batch async compilation
            description: Queue multiple compilations for async processing
            operationId: compileBatchAsync
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/BatchCompileRequest'
            responses:
                '202':
                    description: Batch queued successfully
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/QueueResponse'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '500':
                    $ref: '#/components/responses/ServiceUnavailable'

    /ws/compile:
        get:
            tags: [WebSocket]
            summary: WebSocket endpoint for real-time compilation
            description: |
                Bidirectional WebSocket connection for real-time compilation with event streaming.

                **Client → Server Messages:**
                - `compile` - Start compilation
                - `cancel` - Cancel running compilation
                - `ping` - Heartbeat ping

                **Server → Client Messages:**
                - `welcome` - Connection established
                - `pong` - Heartbeat response
                - `compile:started` - Compilation started
                - `event` - Compilation event (source, transformation, progress, diagnostic, cache, network, metric)
                - `compile:complete` - Compilation finished successfully
                - `compile:error` - Compilation failed
                - `compile:cancelled` - Compilation cancelled
                - `error` - Error message

                **Features:**
                - Up to 3 concurrent compilations per connection
                - Automatic heartbeat (30s interval)
                - Connection timeout (5 minutes idle)
                - Session-based compilation tracking
                - Cancellation support
            operationId: websocketCompile
            responses:
                '101':
                    description: WebSocket connection established
                '426':
                    description: Upgrade required (not a WebSocket request)
            x-websocket-messages:
                client-to-server:
                    - $ref: '#/components/schemas/WsCompileRequest'
                    - $ref: '#/components/schemas/WsCancelRequest'
                    - $ref: '#/components/schemas/WsPingMessage'
                server-to-client:
                    - $ref: '#/components/schemas/WsWelcomeMessage'
                    - $ref: '#/components/schemas/WsPongMessage'
                    - $ref: '#/components/schemas/WsCompileStartedMessage'
                    - $ref: '#/components/schemas/WsEventMessage'
                    - $ref: '#/components/schemas/WsCompileCompleteMessage'
                    - $ref: '#/components/schemas/WsCompileErrorMessage'

    /metrics:
        get:
            tags: [Metrics]
            summary: Get performance metrics
            description: Returns aggregated metrics for the last 30 minutes
            operationId: getMetrics
            responses:
                '200':
                    description: Performance metrics
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/MetricsResponse'

    /queue/stats:
        get:
            tags: [Queue]
            summary: Get queue statistics
            description: Returns queue health metrics and job statistics
            operationId: getQueueStats
            responses:
                '200':
                    description: Queue statistics
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/QueueStats'

    /queue/results/{requestId}:
        get:
            tags: [Queue]
            summary: Get async job results
            description: Retrieve results for a completed async compilation job
            operationId: getQueueResults
            parameters:
                - name: requestId
                  in: path
                  required: true
                  schema:
                      type: string
                  description: Request ID returned from async endpoints
            responses:
                '200':
                    description: Job results
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/CompileResponse'
                                    - $ref: '#/components/schemas/QueueJobStatus'
                '404':
                    description: Job not found

    /api/version:
        get:
            tags: [Metrics]
            summary: Get latest deployment version
            description: Returns the current version from deployment history
            operationId: getApiVersion
            responses:
                '200':
                    description: Version information
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/VersionResponse'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /api/deployments:
        get:
            tags: [Metrics]
            summary: Get deployment history
            description: Returns deployment history records
            operationId: getDeployments
            parameters:
                - name: limit
                  in: query
                  schema:
                      type: integer
                      format: int32
                      default: 50
                      minimum: 1
                      maximum: 1000
                  description: Maximum number of records to return
                - name: version
                  in: query
                  schema:
                      type: string
                  description: Filter by version
                - name: status
                  in: query
                  schema:
                      type: string
                  description: Filter by deployment status
                - name: branch
                  in: query
                  schema:
                      type: string
                  description: Filter by branch name
            responses:
                '200':
                    description: Deployment history
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/DeploymentHistoryResponse'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /api/deployments/stats:
        get:
            tags: [Metrics]
            summary: Get deployment statistics
            description: Returns aggregated deployment statistics
            operationId: getDeploymentStats
            responses:
                '200':
                    description: Deployment statistics
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/DeploymentStatsResponse'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /api/turnstile-config:
        get:
            tags: [Metrics]
            summary: Get Turnstile configuration
            description: Returns the Cloudflare Turnstile site key and whether it is enabled
            operationId: getTurnstileConfig
            responses:
                '200':
                    description: Turnstile configuration
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TurnstileConfigResponse'

    /queue/history:
        get:
            tags: [Queue]
            summary: Get queue job history
            description: Returns job history and queue depth over time
            operationId: getQueueHistory
            responses:
                '200':
                    description: Queue history
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/QueueHistoryResponse'

    /queue/cancel/{requestId}:
        delete:
            tags: [Queue]
            summary: Cancel a pending queue job
            description: |
                Cancels a pending queue job by its requestId.
                Returns 409 if the job is already completed, failed, or cancelled.
                Requires authentication (free tier or above).
            operationId: cancelQueueJob
            security:
                - BearerAuth: []
                - ApiKeyAuth: []
            parameters:
                - name: requestId
                  in: path
                  required: true
                  schema:
                      type: string
                      pattern: '^[a-zA-Z0-9_-]+$'
                  description: The requestId of the queue job to cancel.
            responses:
                '200':
                    description: Job cancelled successfully.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    success:
                                        type: boolean
                                        example: true
                                    cancelled:
                                        type: boolean
                                        example: true
                                        description: Whether the cancellation signal was recorded. This is a best-effort operation.
                                    requestId:
                                        type: string
                                        description: The requestId of the job.
                '400':
                    $ref: '#/components/responses/BadRequest'
                '401':
                    $ref: '#/components/responses/Unauthorized'
                '403':
                    description: Cloudflare Access JWT invalid or missing.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '429':
                    $ref: '#/components/responses/RateLimited'

    /ast/parse:
        post:
            tags: [Compilation]
            summary: Parse filter rules into AST
            description: Parses adblock filter rules into an Abstract Syntax Tree representation
            operationId: parseAST
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ASTParseRequest'
            responses:
                '200':
                    description: Parsed AST
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ASTParseResponse'
                '400':
                    description: Invalid request (must provide rules or text)
                '500':
                    description: Parse error

    /configuration/defaults:
        get:
            tags: [Configuration]
            operationId: getConfigurationDefaults
            summary: Get system compilation defaults and limits
            description: |
                Returns the system defaults and hard limits that apply to every compilation.
                No authentication required (anonymous tier).
            responses:
                '200':
                    description: Defaults and limits.
                    headers:
                        Cache-Control:
                            schema: { type: string, example: 'public, max-age=3600' }
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    success: { type: boolean, example: true }
                                    defaults:
                                        type: object
                                        properties:
                                            compilation: { type: object }
                                            validation: { type: object }
                                    limits:
                                        type: object
                                        properties:
                                            maxSources: { type: integer, example: 20 }
                                            maxExclusions: { type: integer, example: 1000 }
                                    supportedSourceTypes:
                                        type: array
                                        items: { type: string }
                                        example: ['adblock', 'hosts']
                '429':
                    $ref: '#/components/responses/RateLimited'

    /configuration/validate:
        post:
            tags: [Configuration]
            operationId: validateConfiguration
            summary: Validate a configuration object against the schema
            description: |
                Validates a configuration object against the Zod `ConfigurationSchema`.
                Requires a Cloudflare Turnstile token when `TURNSTILE_SECRET_KEY` is configured.
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [config]
                            properties:
                                config:
                                    type: object
                                    description: The configuration object to validate.
                                turnstileToken:
                                    type: string
                                    description: Cloudflare Turnstile token (required when Turnstile is enabled).
            responses:
                '200':
                    description: Validation result.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    success: { type: boolean, example: true }
                                    valid: { type: boolean }
                                    errors:
                                        type: array
                                        items:
                                            type: object
                                            properties:
                                                path: { type: string }
                                                message: { type: string }
                                                code: { type: string }
                '400':
                    $ref: '#/components/responses/BadRequest'
                '403':
                    description: Turnstile verification failed.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '429':
                    $ref: '#/components/responses/RateLimited'

    /configuration/resolve:
        post:
            tags: [Configuration]
            operationId: resolveConfiguration
            summary: Merge configuration layers and return effective IConfiguration
            description: |
                Merges one or more configuration layers (base config + optional override) and
                returns the effective `IConfiguration`. Useful for previewing the result of a
                config + environment overlay before submitting a compile job.
                Requires a Cloudflare Turnstile token when `TURNSTILE_SECRET_KEY` is configured.
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [config]
                            properties:
                                config:
                                    type: object
                                    description: Base configuration object.
                                override:
                                    type: object
                                    description: Optional highest-priority JSON overlay merged on top of config.
                                applyEnvOverrides:
                                    type: boolean
                                    default: true
                                    description: Whether to apply environment variable overrides.
                                turnstileToken:
                                    type: string
                                    description: Cloudflare Turnstile token (required when Turnstile is enabled).
            responses:
                '200':
                    description: Resolved configuration.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    success: { type: boolean, example: true }
                                    config:
                                        $ref: '#/components/schemas/Configuration'
                '400':
                    $ref: '#/components/responses/BadRequest'
                '403':
                    description: Turnstile verification failed.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '429':
                    $ref: '#/components/responses/RateLimited'

    /admin/storage/stats:
        get:
            tags: [Admin]
            summary: Get storage statistics
            description: Returns database table counts and expired entry counts
            operationId: getAdminStorageStats
            security:
                - AdminKey: []
            responses:
                '200':
                    description: Storage statistics
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AdminStorageStatsResponse'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /admin/storage/clear-expired:
        post:
            tags: [Admin]
            summary: Clear expired entries
            description: Deletes all expired entries from storage tables
            operationId: clearExpiredEntries
            security:
                - AdminKey: []
            responses:
                '200':
                    description: Entries cleared
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AdminOperationResponse'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /admin/storage/clear-cache:
        post:
            tags: [Admin]
            summary: Clear cache entries
            description: Deletes all cache entries from storage tables
            operationId: clearCacheEntries
            security:
                - AdminKey: []
            responses:
                '200':
                    description: Cache cleared
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AdminOperationResponse'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /admin/storage/export:
        get:
            tags: [Admin]
            summary: Export storage data
            description: Exports storage entries as JSON (includes storage entries, filter cache, and compilation metadata; returned amounts subject to implementation limits)
            operationId: exportStorage
            security:
                - AdminKey: []
            responses:
                '200':
                    description: Storage export
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AdminExportResponse'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /admin/storage/vacuum:
        post:
            tags: [Admin]
            summary: Vacuum database
            description: Runs VACUUM on the D1 database to reclaim space
            operationId: vacuumDatabase
            security:
                - AdminKey: []
            responses:
                '200':
                    description: Vacuum completed
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AdminOperationResponse'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /admin/storage/tables:
        get:
            tags: [Admin]
            summary: List database tables
            description: Returns all tables and indexes in the D1 database
            operationId: listStorageTables
            security:
                - AdminKey: []
            responses:
                '200':
                    description: Table listing
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AdminTablesResponse'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /admin/storage/query:
        post:
            tags: [Admin]
            summary: Execute read-only SQL query
            description: Executes a SELECT-only SQL query against the D1 database for debugging
            operationId: queryStorage
            security:
                - AdminKey: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/AdminQueryRequest'
            responses:
                '200':
                    description: Query results
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AdminQueryResponse'
                '400':
                    description: Invalid or disallowed SQL
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /workflow/compile:
        post:
            tags: [Workflow]
            summary: Start async compilation workflow
            description: Creates a durable Cloudflare Workflow instance for compilation
            operationId: startWorkflowCompile
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CompileRequest'
            responses:
                '202':
                    description: Workflow started
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkflowStartResponse'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /workflow/batch:
        post:
            tags: [Workflow]
            summary: Start async batch compilation workflow
            description: Creates a durable Cloudflare Workflow instance for batch compilation
            operationId: startWorkflowBatch
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/BatchCompileRequest'
            responses:
                '202':
                    description: Workflow started
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkflowStartResponse'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /workflow/cache-warm:
        post:
            tags: [Workflow]
            summary: Start cache warming workflow
            description: Triggers manual cache warming for specified configurations
            operationId: startWorkflowCacheWarm
            requestBody:
                required: false
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CacheWarmRequest'
            responses:
                '202':
                    description: Workflow started
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkflowStartResponse'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /workflow/health-check:
        post:
            tags: [Workflow]
            summary: Start health monitoring workflow
            description: Triggers manual health check for specified filter list sources
            operationId: startWorkflowHealthCheck
            requestBody:
                required: false
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/HealthCheckRequest'
            responses:
                '202':
                    description: Workflow started
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkflowStartResponse'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /workflow/status/{workflowType}/{instanceId}:
        get:
            tags: [Workflow]
            summary: Get workflow instance status
            description: Returns the current status and output of a workflow instance
            operationId: getWorkflowStatus
            parameters:
                - name: workflowType
                  in: path
                  required: true
                  schema:
                      type: string
                      enum: [compilation, batch-compilation, cache-warming, health-monitoring]
                  description: Type of workflow
                - name: instanceId
                  in: path
                  required: true
                  schema:
                      type: string
                  description: Workflow instance ID
            responses:
                '200':
                    description: Workflow status
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkflowStatusResponse'
                '400':
                    description: Unknown workflow type
                '404':
                    description: Workflow instance not found
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /workflow/metrics:
        get:
            tags: [Workflow]
            summary: Get workflow metrics
            description: Returns aggregated metrics for all workflow types
            operationId: getWorkflowMetrics
            responses:
                '200':
                    description: Workflow metrics
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkflowMetricsResponse'

    /workflow/events/{workflowId}:
        get:
            tags: [Workflow]
            summary: Get workflow events
            description: Returns progress events for a specific workflow instance
            operationId: getWorkflowEvents
            parameters:
                - name: workflowId
                  in: path
                  required: true
                  schema:
                      type: string
                  description: Workflow instance ID
                - name: since
                  in: query
                  schema:
                      type: string
                      format: date-time
                  description: Return only events after this timestamp
            responses:
                '200':
                    description: Workflow events
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkflowEventsResponse'

    /health/latest:
        get:
            tags: [Health]
            summary: Get latest health check results
            description: Returns the results of the most recent health monitoring workflow run
            operationId: getLatestHealth
            responses:
                '200':
                    description: Latest health check data
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/HealthLatestResponse'

    /health:
        get:
            tags: [Health]
            summary: Basic health check
            description: Returns current service health status and version
            operationId: getHealth
            responses:
                '200':
                    description: Service is healthy
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/HealthResponse'

    /admin/auth/users:
        post:
            tags: [Admin]
            summary: Create user
            description: Creates a new user account. Requires Hyperdrive (PostgreSQL) binding.
            operationId: createUser
            security:
                - AdminKey: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateUserRequest'
            responses:
                '201':
                    description: User created
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CreateUserResponse'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '409':
                    description: User with this email already exists
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /admin/auth/api-keys:
        post:
            tags: [Admin]
            summary: Create API key
            description: |
                Creates a new API key for a user. Requires Hyperdrive (PostgreSQL) binding.

                **Important:** The raw API key is only returned once. Store it securely.
            operationId: createApiKey
            security:
                - AdminKey: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateApiKeyRequest'
            responses:
                '201':
                    description: API key created
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CreateApiKeyResponse'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '404':
                    description: User not found
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'
        get:
            tags: [Admin]
            summary: List API keys
            description: Lists API keys for a user (without key hashes). Requires Hyperdrive (PostgreSQL) binding.
            operationId: listApiKeys
            security:
                - AdminKey: []
            parameters:
                - name: userId
                  in: query
                  required: true
                  schema:
                      type: string
                      format: uuid
                  description: User ID to list API keys for
            responses:
                '200':
                    description: List of API keys
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListApiKeysResponse'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /admin/auth/api-keys/revoke:
        post:
            tags: [Admin]
            summary: Revoke API key
            description: Revokes an API key by ID or key prefix. Requires Hyperdrive (PostgreSQL) binding.
            operationId: revokeApiKey
            security:
                - AdminKey: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/RevokeApiKeyRequest'
            responses:
                '200':
                    description: API key revoked
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/RevokeApiKeyResponse'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '404':
                    description: API key not found or already revoked
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /admin/auth/api-keys/validate:
        post:
            tags: [Admin]
            summary: Validate API key
            description: Validates an API key without authenticating a full request. Useful for the admin UI to test keys.
            operationId: validateApiKey
            security:
                - AdminKey: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ValidateApiKeyRequest'
            responses:
                '200':
                    description: Validation result
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ValidateApiKeyResponse'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    # ─── User-Level Authentication Endpoints ───────────────────────────

    /api/keys:
        post:
            tags: [Authentication]
            summary: Create API key
            description: |
                Creates a new API key for the authenticated user.
                The raw API key (with `abc_` prefix) is returned **only once** — store it securely.
                Requires Clerk JWT authentication.
            operationId: userCreateApiKey
            security:
                - ClerkJWT: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/UserCreateApiKeyRequest'
            responses:
                '201':
                    description: API key created
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UserCreateApiKeyResponse'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
        get:
            tags: [Authentication]
            summary: List user's API keys
            description: |
                Lists all API keys belonging to the authenticated user.
                Returns metadata only — never the key hash or plaintext.
                Requires Clerk JWT authentication.
            operationId: userListApiKeys
            security:
                - ClerkJWT: []
            responses:
                '200':
                    description: List of API keys
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UserListApiKeysResponse'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'

    /api/keys/{keyId}:
        delete:
            tags: [Authentication]
            summary: Revoke API key
            description: |
                Revokes (soft-deletes) an API key. The key remains in the database for audit
                purposes but is no longer valid for authentication.
                Only the key owner can revoke their own keys.
            operationId: userRevokeApiKey
            security:
                - ClerkJWT: []
            parameters:
                - name: keyId
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
                  description: ID of the API key to revoke
            responses:
                '200':
                    description: API key revoked
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    success:
                                        type: boolean
                                    message:
                                        type: string
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '404':
                    description: API key not found or already revoked
        patch:
            tags: [Authentication]
            summary: Update API key
            description: |
                Updates an API key's name or scopes. Only the key owner can update their own keys.
                Requires Clerk JWT authentication.
            operationId: userUpdateApiKey
            security:
                - ClerkJWT: []
            parameters:
                - name: keyId
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
                  description: ID of the API key to update
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/UserUpdateApiKeyRequest'
            responses:
                '200':
                    description: API key updated
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UserUpdateApiKeyResponse'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '404':
                    description: API key not found or already revoked

    /api/webhooks/clerk:
        post:
            tags: [Authentication]
            summary: Clerk webhook receiver
            description: |
                Receives Clerk webhook events (user.created, user.updated, user.deleted, session.created).
                Verified via Svix webhook signature. This endpoint is called by Clerk's webhook infrastructure
                and should not be called directly.
            operationId: clerkWebhook
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            description: Clerk webhook event payload (Svix-signed)
                            properties:
                                type:
                                    type: string
                                    description: Event type (e.g. user.created, user.updated)
                                data:
                                    type: object
                                    description: Event-specific payload
                                object:
                                    type: string
                                    enum: [event]
            parameters:
                - name: svix-id
                  in: header
                  required: true
                  schema:
                      type: string
                  description: Svix webhook ID
                - name: svix-timestamp
                  in: header
                  required: true
                  schema:
                      type: string
                  description: Svix webhook timestamp
                - name: svix-signature
                  in: header
                  required: true
                  schema:
                      type: string
                  description: Svix webhook signature
            responses:
                '200':
                    description: Webhook processed successfully
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    success:
                                        type: boolean
                                    message:
                                        type: string
                '400':
                    description: Invalid webhook signature or payload
                '401':
                    description: Webhook signature verification failed

    /admin/migrate/d1-to-pg:
        post:
            tags: [Admin]
            summary: Migrate D1 data to PostgreSQL
            description: |
                One-time migration that reads data from Cloudflare D1 (SQLite) and writes it to PostgreSQL via Hyperdrive.

                Migrates the following tables: `storage_entries`, `filter_cache`, `compilation_metadata`.

                The migration is:
                - **Idempotent**: uses ON CONFLICT DO NOTHING to skip existing rows
                - **Batched**: processes rows in chunks of 100
                - **Read-only on D1**: never modifies the source database
                - **Resumable**: can be re-run safely if interrupted
            operationId: migrateD1ToPg
            security:
                - AdminKey: []
            parameters:
                - name: dryRun
                  in: query
                  required: false
                  schema:
                      type: boolean
                      default: false
                  description: Count rows without writing (dry run)
                - name: tables
                  in: query
                  required: false
                  schema:
                      type: string
                  description: 'Comma-separated list of tables to migrate (default: all)'
                  example: storage_entries,filter_cache
            responses:
                '200':
                    description: Migration result
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/MigrationResult'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /admin/backends:
        get:
            tags: [Admin]
            summary: Backend health status
            description: Returns health and connectivity status of both D1 and PostgreSQL backends
            operationId: getBackendStatus
            security:
                - AdminKey: []
            responses:
                '200':
                    description: Backend status
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BackendStatusResponse'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'

    /admin/pg/stats:
        get:
            tags: [Admin]
            summary: PostgreSQL storage statistics
            description: Returns storage statistics from the PostgreSQL backend (mirrors /admin/storage/stats for D1)
            operationId: getPgStorageStats
            security:
                - AdminKey: []
            responses:
                '200':
                    description: PostgreSQL storage statistics
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PgStorageStatsResponse'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /admin/pg/export:
        get:
            tags: [Admin]
            summary: Export PostgreSQL data
            description: Exports data from the PostgreSQL backend (mirrors /admin/storage/export for D1)
            operationId: exportPgData
            security:
                - AdminKey: []
            responses:
                '200':
                    description: PostgreSQL data export
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AdminExportResponse'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /admin/pg/clear-expired:
        post:
            tags: [Admin]
            summary: Clear expired PostgreSQL entries
            description: Deletes all expired entries from PostgreSQL storage and cache tables
            operationId: clearPgExpiredEntries
            security:
                - AdminKey: []
            responses:
                '200':
                    description: Entries cleared
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AdminOperationResponse'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /admin/pg/clear-cache:
        post:
            tags: [Admin]
            summary: Clear PostgreSQL cache
            description: Deletes all cache entries from PostgreSQL tables
            operationId: clearPgCache
            security:
                - AdminKey: []
            responses:
                '200':
                    description: Cache cleared
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AdminOperationResponse'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /admin/pg/query:
        post:
            tags: [Admin]
            summary: Execute read-only PostgreSQL query
            description: Executes a SELECT-only SQL query against PostgreSQL for debugging (mirrors /admin/storage/query for D1)
            operationId: queryPg
            security:
                - AdminKey: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/AdminQueryRequest'
            responses:
                '200':
                    description: Query results
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AdminQueryResponse'
                '400':
                    description: Invalid or disallowed SQL
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /api/browser/resolve-url:
        post:
            tags: [Browser Rendering]
            summary: Resolve canonical URL via browser
            description: |
                Navigates to a URL using the Cloudflare Browser Rendering binding and returns the
                final canonical URL after all redirects. Useful for discovering the true destination
                of redirect chains or URL shorteners before scheduling a filter-list download.

                Requires the `BROWSER` binding to be configured in `wrangler.toml`.
            operationId: browserResolveUrl
            security:
                - BearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/BrowserResolveRequest'
            responses:
                '200':
                    description: Resolved URL
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BrowserResolveResponse'
                '400':
                    description: Invalid request body
                '502':
                    description: Browser navigation failed
                '503':
                    description: BROWSER binding not configured

    /api/browser/monitor:
        post:
            tags: [Browser Rendering]
            summary: Monitor filter-list sources for reachability
            description: |
                Performs parallel browser-based health checks on a list of filter-list source
                URLs. For each URL a headless browser navigates to the page, verifies non-empty
                text content, and optionally captures a full-page PNG screenshot stored in R2.

                The full result set is persisted under the KV key `browser:monitor:latest`
                and is retrievable via `GET /api/browser/monitor/latest`.

                Requires the `BROWSER` binding. `FILTER_STORAGE` (R2) is required for
                screenshot capture. `COMPILATION_CACHE` (KV) is required for result persistence.
            operationId: browserMonitor
            security:
                - BearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/SourceMonitorRequest'
            responses:
                '200':
                    description: Per-source reachability results
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SourceMonitorResponse'
                '400':
                    description: Invalid request body
                '503':
                    description: BROWSER binding not configured

    /api/browser/monitor/latest:
        get:
            tags: [Browser Rendering]
            summary: Retrieve the latest monitor results
            description: |
                Returns the most recent result set written by `POST /api/browser/monitor`. Reads
                the KV key `browser:monitor:latest` from `COMPILATION_CACHE`.

                Requires the `COMPILATION_CACHE` binding.
            operationId: browserMonitorLatest
            security:
                - BearerAuth: []
            responses:
                '200':
                    description: Latest monitor results
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SourceMonitorResponse'
                '404':
                    description: No monitor results available yet
                '503':
                    description: COMPILATION_CACHE binding not configured

    /convert-rule:
        post:
            summary: Convert a filter rule to a different syntax
            description: Converts a single adblock filter rule between AdGuard and uBlock Origin syntaxes using AGTree's RuleConverter.
            operationId: convertRule
            tags:
                - Rules
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ConvertRuleRequest'
            responses:
                '200':
                    description: Conversion result
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ConvertRuleResponse'
                '400':
                    description: Invalid request body
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '422':
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'

    /validate-rule:
        post:
            summary: Validate a single adblock rule
            description: Parses and validates a single adblock/DNS rule, returning its AST representation, type, and optional URL match result.
            operationId: validateRule
            tags:
                - Rules
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ValidateRuleRequest'
            responses:
                '200':
                    description: Rule validation result
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ValidateRuleResponse'
                '400':
                    description: Invalid request body
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'

    /rules:
        get:
            summary: List saved rule sets
            description: Returns all saved rule sets stored in the KV namespace.
            operationId: listRuleSets
            tags:
                - Rule Sets
            responses:
                '200':
                    description: List of rule sets
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/RuleSetListResponse'
                '500':
                    description: Internal server error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
        post:
            summary: Create a new rule set
            description: Creates and stores a new named rule set in the KV namespace.
            operationId: createRuleSet
            tags:
                - Rule Sets
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/RuleSetCreateRequest'
            responses:
                '201':
                    description: Rule set created
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/RuleSetResponse'
                '400':
                    description: Invalid request body
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'

    /rules/{id}:
        parameters:
            - name: id
              in: path
              required: true
              description: UUID of the rule set
              schema:
                  type: string
                  format: uuid
        get:
            summary: Get a rule set by ID
            operationId: getRuleSet
            tags:
                - Rule Sets
            responses:
                '200':
                    description: Rule set found
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/RuleSetResponse'
                '404':
                    description: Rule set not found
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
        put:
            summary: Update a rule set by ID
            operationId: updateRuleSet
            tags:
                - Rule Sets
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/RuleSetUpdateRequest'
            responses:
                '200':
                    description: Rule set updated
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/RuleSetResponse'
                '400':
                    description: Invalid request body
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '404':
                    description: Rule set not found
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
        delete:
            summary: Delete a rule set by ID
            operationId: deleteRuleSet
            tags:
                - Rule Sets
            responses:
                '200':
                    description: Rule set deleted
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - success
                                    - message
                                properties:
                                    success:
                                        type: boolean
                                    message:
                                        type: string
                                        description: Confirmation message
                '404':
                    description: Rule set not found
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'

    /notify:
        post:
            summary: Send a notification event to configured webhook targets
            description: Delivers a notification event (e.g. error, warning, info) to one or more configured targets — generic HTTP webhook (WEBHOOK_URL), Sentry (SENTRY_DSN), and/or Datadog (DATADOG_API_KEY). At least one target must be configured in the worker environment.
            operationId: notify
            tags:
                - Notifications
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/WebhookNotifyRequest'
            responses:
                '200':
                    description: Notification delivered to at least one target
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WebhookNotifyResponse'
                '400':
                    description: Invalid request body
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '502':
                    description: All configured notification targets failed to receive the event
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WebhookNotifyResponse'
                '503':
                    description: No notification targets configured (set WEBHOOK_URL, SENTRY_DSN, or DATADOG_API_KEY)
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'

    # ---------------------------------------------------------------------------
    # Local JWT Auth Bridge — POST /auth/signup, /auth/login, GET /auth/me, POST /auth/change-password
    # Active when CLERK_JWKS_URL is NOT set. Auto-replaced by Clerk when CLERK_JWKS_URL is set.
    # ---------------------------------------------------------------------------

    /auth/signup:
        post:
            tags: [LocalAuth]
            summary: Register a new local account
            description: |
                Create a new account using an email address or E.164 phone number and password.
                All self-registered users receive the `user` role (Free tier).
                Admin role must be granted via `POST /admin/local-users`.

                **Rate limited** (anonymous tier). Returns a signed HS256 JWT on success.

                > Only active when `CLERK_JWKS_URL` is not configured. When Clerk is live,
                > sign up via the Clerk-hosted UI instead.
            operationId: localSignup
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/LocalSignupRequest'
                        example:
                            identifier: user@example.com
                            password: minEightChars
            responses:
                '201':
                    description: Account created — JWT returned
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/LocalAuthResponse'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '409':
                    description: An account with this identifier already exists
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '429':
                    $ref: '#/components/responses/RateLimitError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /auth/login:
        post:
            tags: [LocalAuth]
            summary: Authenticate and receive a JWT
            description: |
                Authenticate with an identifier (email or phone) and password.
                Returns a signed HS256 JWT valid for 24 hours.

                Timing-safe: always runs full PBKDF2 derivation even for unknown identifiers
                to prevent user enumeration via timing side-channels.

                **Rate limited** (anonymous tier).
            operationId: localLogin
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/LocalLoginRequest'
                        example:
                            identifier: user@example.com
                            password: yourpassword
            responses:
                '200':
                    description: Authentication successful — JWT returned
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/LocalAuthResponse'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '401':
                    description: Invalid credentials (generic — no user enumeration)
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '429':
                    $ref: '#/components/responses/RateLimitError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /auth/me:
        get:
            tags: [LocalAuth]
            summary: Get current user profile
            description: |
                Returns the authenticated user's public profile.
                Requires a valid `Authorization: Bearer <jwt>` header.
            operationId: localMe
            security:
                - BearerAuth: []
            responses:
                '200':
                    description: Current user profile
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/LocalMeResponse'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '404':
                    description: User record not found (deleted since token was issued)
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /auth/change-password:
        post:
            tags: [LocalAuth]
            summary: Change the current user's password
            description: |
                Update the authenticated user's password.
                Requires a valid `Authorization: Bearer <jwt>` header and the correct current password.
            operationId: localChangePassword
            security:
                - BearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/LocalChangePasswordRequest'
            responses:
                '200':
                    description: Password updated successfully
                    content:
                        application/json:
                            schema:
                                type: object
                                required: [success, message]
                                properties:
                                    success:
                                        type: boolean
                                        example: true
                                    message:
                                        type: string
                                        example: Password updated successfully
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '401':
                    description: Not authenticated or current password is wrong
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    # ---------------------------------------------------------------------------
    # Admin — local user management
    # ---------------------------------------------------------------------------

    /admin/local-users:
        get:
            tags: [Admin]
            summary: List local auth users
            description: |
                Returns a paginated list of all local auth users.
                Responses never include `password_hash`.
                Requires Admin tier + admin role.
            operationId: adminListLocalUsers
            security:
                - BearerAuth: []
            parameters:
                - name: limit
                  in: query
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 100
                      default: 50
                  description: Maximum number of users to return
                - name: offset
                  in: query
                  schema:
                      type: integer
                      minimum: 0
                      default: 0
                  description: Number of users to skip (for pagination)
            responses:
                '200':
                    description: Paginated user list
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AdminLocalUsersListResponse'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '403':
                    $ref: '#/components/responses/ForbiddenError'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'
        post:
            tags: [Admin]
            summary: Create a local auth user
            description: |
                Create a new local auth user with any valid role and tier.
                Admins can create users with privileged roles (e.g. `admin`) that cannot be self-registered.
                Requires Admin tier + admin role.
            operationId: adminCreateLocalUser
            security:
                - BearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/AdminCreateLocalUserRequest'
                        example:
                            identifier: newuser@example.com
                            password: securepass123
                            role: user
                            tier: free
            responses:
                '201':
                    description: User created
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AdminLocalUserResponse'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '403':
                    $ref: '#/components/responses/ForbiddenError'
                '409':
                    description: An account with this identifier already exists
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /admin/local-users/{userId}:
        get:
            tags: [Admin]
            summary: Get a local auth user
            description: |
                Returns the public profile of a single local auth user by UUID.
                Requires Admin tier + admin role.
            operationId: adminGetLocalUser
            security:
                - BearerAuth: []
            parameters:
                - name: userId
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
                  description: Local auth user UUID
            responses:
                '200':
                    description: User profile
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AdminLocalUserResponse'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '403':
                    $ref: '#/components/responses/ForbiddenError'
                '404':
                    description: User not found
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'
        patch:
            tags: [Admin]
            summary: Update a local auth user
            description: |
                Update a user's `tier`, `role`, and/or `api_disabled` flag.
                Tier and role are independent fields — changing role does not automatically change tier unless
                no explicit tier is provided (in which case the role's default tier is applied).
                Requires Admin tier + admin role.
            operationId: adminUpdateLocalUser
            security:
                - BearerAuth: []
            parameters:
                - name: userId
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
                  description: Local auth user UUID
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/AdminUpdateLocalUserRequest'
                        examples:
                            disable:
                                summary: Disable API access
                                value:
                                    api_disabled: 1
                            promote:
                                summary: Promote to admin
                                value:
                                    role: admin
                                    tier: admin
            responses:
                '200':
                    description: Updated user profile
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AdminLocalUserResponse'
                '400':
                    $ref: '#/components/responses/BadRequestError'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '403':
                    $ref: '#/components/responses/ForbiddenError'
                '404':
                    description: User not found
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'
        delete:
            tags: [Admin]
            summary: Delete a local auth user
            description: |
                Permanently deletes a local auth user by UUID.
                Requires Admin tier + admin role.
            operationId: adminDeleteLocalUser
            security:
                - BearerAuth: []
            parameters:
                - name: userId
                  in: path
                  required: true
                  schema:
                      type: string
                      format: uuid
                  description: Local auth user UUID
            responses:
                '200':
                    description: User deleted
                    content:
                        application/json:
                            schema:
                                type: object
                                required: [success, message]
                                properties:
                                    success:
                                        type: boolean
                                        example: true
                                    message:
                                        type: string
                                        example: User deleted
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '403':
                    $ref: '#/components/responses/ForbiddenError'
                '404':
                    description: User not found
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                '503':
                    $ref: '#/components/responses/ServiceUnavailable'

    /admin/auth/config:
        get:
            tags: [Admin]
            summary: Inspect active auth registries
            description: |
                Returns a read-only snapshot of all three extensibility registries at runtime:
                - `LOCAL_ROLE_REGISTRY` — all defined roles, their tiers, and self-register flag
                - `TIER_REGISTRY` — all tiers with rate limits and ordering
                - `ROUTE_PERMISSION_REGISTRY` — all registered route permission rules

                Also reports which auth provider is active (`local-jwt` vs `clerk`).
                Requires Admin tier + admin role.
            operationId: adminAuthConfig
            security:
                - BearerAuth: []
            responses:
                '200':
                    description: Active auth configuration snapshot
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AdminAuthConfigResponse'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '403':
                    $ref: '#/components/responses/ForbiddenError'

    /admin/usage/{userId}:
        get:
            tags: [Admin]
            summary: Get per-user API usage statistics
            description: |
                Returns KV-backed API usage counters for a specific user:
                - `total` — lifetime request count, first/last seen timestamps
                - `days` — per-day breakdown for the requested lookback window (max 90 days)

                Requires Admin tier + admin role.
            operationId: adminGetUserUsage
            security:
                - BearerAuth: []
            parameters:
                - name: userId
                  in: path
                  required: true
                  schema:
                      type: string
                  description: User ID (UUID or Clerk user ID)
                - name: days
                  in: query
                  schema:
                      type: integer
                      minimum: 1
                      maximum: 90
                      default: 30
                  description: Number of past days to include in the daily breakdown
            responses:
                '200':
                    description: Per-user usage statistics
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AdminUserUsageResponse'
                '401':
                    $ref: '#/components/responses/UnauthorizedError'
                '403':
                    $ref: '#/components/responses/ForbiddenError'

components:
    schemas:
        # Shared response schema
        ErrorResponse:
            type: object
            properties:
                success: { type: boolean, example: false }
                error: { type: string }

        # Request Schemas
        CompileRequest:
            type: object
            required:
                - configuration
            properties:
                configuration:
                    $ref: '#/components/schemas/Configuration'
                preFetchedContent:
                    type: object
                    additionalProperties:
                        type: string
                    description: Map of source keys to pre-fetched content
                benchmark:
                    type: boolean
                    default: false
                    description: Include detailed performance metrics
                turnstileToken:
                    type: string
                    description: Cloudflare Turnstile token (if enabled)
                priority:
                    type: string
                    enum: [standard, high]
                    default: standard
                    description: Job processing priority (used for async compilation)

        Configuration:
            type: object
            required:
                - name
                - sources
            properties:
                name:
                    type: string
                    minLength: 1
                    description: Name of the compiled list
                description:
                    type: string
                    description: Description of the list
                homepage:
                    type: string
                    format: uri
                    description: Homepage URL
                license:
                    type: string
                    description: License identifier
                version:
                    type: string
                    description: Version string
                sources:
                    type: array
                    items:
                        $ref: '#/components/schemas/Source'
                    minItems: 1
                transformations:
                    type: array
                    items:
                        $ref: '#/components/schemas/Transformation'
                    description: Global transformations to apply
                exclusions:
                    type: array
                    items:
                        type: string
                    description: Rules to exclude (supports wildcards and regex)
                exclusions_sources:
                    type: array
                    items:
                        type: string
                    description: Files containing exclusion rules
                inclusions:
                    type: array
                    items:
                        type: string
                    description: Rules to include (supports wildcards and regex)
                inclusions_sources:
                    type: array
                    items:
                        type: string
                    description: Files containing inclusion rules

        Source:
            type: object
            required:
                - source
            properties:
                source:
                    type: string
                    description: URL or key for pre-fetched content
                name:
                    type: string
                    description: Name of the source
                type:
                    type: string
                    enum: [adblock, hosts]
                    default: adblock
                    description: Source type
                transformations:
                    type: array
                    items:
                        $ref: '#/components/schemas/Transformation'
                exclusions:
                    type: array
                    items:
                        type: string
                inclusions:
                    type: array
                    items:
                        type: string

        Transformation:
            type: string
            enum:
                - ConvertToAscii
                - RemoveComments
                - Compress
                - RemoveModifiers
                - Validate
                - ValidateAllowIp
                - Deduplicate
                - InvertAllow
                - RemoveEmptyLines
                - TrimLines
                - InsertFinalNewLine
            description: |
                Available transformations (applied in this order):
                - **ConvertToAscii**: Convert internationalized domains to ASCII
                - **RemoveComments**: Remove comment lines
                - **Compress**: Convert hosts format to adblock syntax
                - **RemoveModifiers**: Strip unsupported modifiers
                - **Validate**: Remove invalid/dangerous rules
                - **ValidateAllowIp**: Like Validate but keeps IP addresses
                - **Deduplicate**: Remove duplicate rules
                - **InvertAllow**: Convert blocking rules to allowlist
                - **RemoveEmptyLines**: Remove blank lines
                - **TrimLines**: Remove leading/trailing whitespace
                - **InsertFinalNewLine**: Add final newline

        BatchCompileRequest:
            type: object
            required:
                - requests
            properties:
                requests:
                    type: array
                    items:
                        $ref: '#/components/schemas/BatchRequestItem'
                    minItems: 1
                    maxItems: 10

        BatchRequestItem:
            type: object
            required:
                - id
                - configuration
            properties:
                id:
                    type: string
                    description: Unique request identifier
                configuration:
                    $ref: '#/components/schemas/Configuration'
                preFetchedContent:
                    type: object
                    additionalProperties:
                        type: string
                benchmark:
                    type: boolean

        # Response Schemas
        CompileResponse:
            type: object
            required:
                - success
            properties:
                success:
                    type: boolean
                rules:
                    type: array
                    items:
                        type: string
                    description: Compiled filter rules
                ruleCount:
                    type: integer
                    description: Number of rules
                metrics:
                    $ref: '#/components/schemas/CompilationMetrics'
                compiledAt:
                    type: string
                    format: date-time
                previousVersion:
                    $ref: '#/components/schemas/PreviousVersion'
                cached:
                    type: boolean
                    description: Whether result was served from cache
                deduplicated:
                    type: boolean
                    description: Whether request was deduplicated
                error:
                    type: string
                    description: Error message if success=false

        CompilationMetrics:
            type: object
            properties:
                totalDurationMs:
                    type: integer
                sourceCount:
                    type: integer
                ruleCount:
                    type: integer
                transformationMetrics:
                    type: array
                    items:
                        type: object
                        properties:
                            name:
                                type: string
                            inputCount:
                                type: integer
                            outputCount:
                                type: integer
                            durationMs:
                                type: integer

        PreviousVersion:
            type: object
            properties:
                rules:
                    type: array
                    items:
                        type: string
                ruleCount:
                    type: integer
                compiledAt:
                    type: string
                    format: date-time

        BatchCompileResponse:
            type: object
            properties:
                success:
                    type: boolean
                results:
                    type: array
                    items:
                        allOf:
                            - type: object
                              properties:
                                  id:
                                      type: string
                            - $ref: '#/components/schemas/CompileResponse'

        QueueResponse:
            type: object
            properties:
                success:
                    type: boolean
                message:
                    type: string
                requestId:
                    type: string
                priority:
                    type: string
                    enum: [standard, high]
                note:
                    type: string
                    description: Informational note about the queued job
                batchSize:
                    type: integer
                    description: Number of items in the batch (only for batch async requests)

        QueueJobStatus:
            type: object
            properties:
                success:
                    type: boolean
                status:
                    type: string
                    enum: [completed, failed, not_found, no_cache, cache_miss]
                jobInfo:
                    type: object
                    properties:
                        configName:
                            type: string
                        duration:
                            type: integer
                        timestamp:
                            type: string
                        error:
                            type: string

        QueueStats:
            type: object
            properties:
                pending:
                    type: integer
                completed:
                    type: integer
                failed:
                    type: integer
                cancelled:
                    type: integer
                totalProcessingTime:
                    type: integer
                averageProcessingTime:
                    type: integer
                processingRate:
                    type: number
                    description: Jobs per minute
                queueLag:
                    type: integer
                    description: Average time in queue (ms)
                lastUpdate:
                    type: string
                    format: date-time
                history:
                    type: array
                    items:
                        $ref: '#/components/schemas/JobHistoryEntry'
                depthHistory:
                    type: array
                    items:
                        type: object
                        properties:
                            timestamp:
                                type: string
                            pending:
                                type: integer

        JobHistoryEntry:
            type: object
            properties:
                requestId:
                    type: string
                configName:
                    type: string
                status:
                    type: string
                    enum: [completed, failed, cancelled]
                duration:
                    type: integer
                timestamp:
                    type: string
                error:
                    type: string
                ruleCount:
                    type: integer

        MetricsResponse:
            type: object
            properties:
                window:
                    type: string
                timestamp:
                    type: string
                    format: date-time
                endpoints:
                    type: object
                    additionalProperties:
                        type: object
                        properties:
                            count:
                                type: integer
                            success:
                                type: integer
                            failed:
                                type: integer
                            avgDuration:
                                type: number
                            errors:
                                type: object
                                additionalProperties:
                                    type: integer

        ApiInfo:
            type: object
            properties:
                name:
                    type: string
                version:
                    type: string
                endpoints:
                    type: object
                    additionalProperties:
                        type: string
                example:
                    type: object

        # Version and Deployment Schemas
        VersionResponse:
            type: object
            required:
                - success
                - version
            properties:
                success:
                    type: boolean
                version:
                    type: string
                    description: Semantic version string
                buildNumber:
                    type: integer
                fullVersion:
                    type: string
                    description: Full version string including build number
                gitCommit:
                    type: string
                gitBranch:
                    type: string
                deployedAt:
                    type: string
                    description: "Deployment timestamp as stored by SQLite datetime('now') in 'YYYY-MM-DD HH:MM:SS' format"
                deployedBy:
                    type: string
                status:
                    type: string
                message:
                    type: string
                    description: Present when no deployment history is available

        DeploymentHistoryResponse:
            type: object
            required:
                - success
                - deployments
                - count
            properties:
                success:
                    type: boolean
                deployments:
                    type: array
                    items:
                        $ref: '#/components/schemas/DeploymentInfo'
                count:
                    type: integer
                    description: Total number of deployments returned

        DeploymentStatsResponse:
            type: object
            required:
                - success
                - totalDeployments
                - successfulDeployments
                - failedDeployments
            properties:
                success:
                    type: boolean
                totalDeployments:
                    type: integer
                successfulDeployments:
                    type: integer
                failedDeployments:
                    type: integer
                latestVersion:
                    type: string
                    nullable: true

        TurnstileConfigResponse:
            type: object
            properties:
                siteKey:
                    type: string
                    nullable: true
                    description: Cloudflare Turnstile site key
                enabled:
                    type: boolean
                    description: Whether Turnstile verification is enabled

        DeploymentInfo:
            type: object
            required:
                - version
                - buildNumber
                - fullVersion
                - gitCommit
                - gitBranch
                - deployedAt
                - deployedBy
                - status
            properties:
                version:
                    type: string
                buildNumber:
                    type: integer
                fullVersion:
                    type: string
                gitCommit:
                    type: string
                gitBranch:
                    type: string
                deployedAt:
                    type: string
                    description: "Deployment timestamp as stored by SQLite datetime('now') in 'YYYY-MM-DD HH:MM:SS' format"
                deployedBy:
                    type: string
                status:
                    type: string
                metadata:
                    type: object
                    additionalProperties: true
                    nullable: true

        # Queue History Schemas
        QueueHistoryResponse:
            type: object
            properties:
                history:
                    type: array
                    items:
                        $ref: '#/components/schemas/JobHistoryEntry'
                depthHistory:
                    type: array
                    items:
                        type: object
                        properties:
                            timestamp:
                                type: string
                            pending:
                                type: integer

        CancelJobResponse:
            type: object
            properties:
                success:
                    type: boolean
                message:
                    type: string
                note:
                    type: string
                    description: Note that job may still process if already started

        # AST Parse Schemas
        ASTParseRequest:
            type: object
            properties:
                rules:
                    type: array
                    items:
                        type: string
                    description: Array of filter rule strings to parse
                text:
                    type: string
                    description: Raw text containing filter rules (newline-separated)
            description: Either 'rules' or 'text' must be provided

        ASTParseResponse:
            type: object
            properties:
                success:
                    type: boolean
                parsedRules:
                    type: array
                    items:
                        type: object
                        additionalProperties: true
                    description: Array of parsed rule AST objects
                summary:
                    type: object
                    description: Summary statistics about the parsed rules (e.g., total rules, rule types, parse errors)
                    additionalProperties: true

        # Admin Schemas
        AdminStorageStatsResponse:
            type: object
            properties:
                success:
                    type: boolean
                stats:
                    $ref: '#/components/schemas/StorageStats'
                timestamp:
                    type: string
                    format: date-time

        StorageStats:
            type: object
            properties:
                storage_entries:
                    type: integer
                filter_cache:
                    type: integer
                compilation_metadata:
                    type: integer
                expired_storage:
                    type: integer
                expired_cache:
                    type: integer

        AdminOperationResponse:
            type: object
            properties:
                success:
                    type: boolean
                deleted:
                    type: integer
                    description: Number of entries deleted (for clear operations)
                message:
                    type: string

        AdminExportResponse:
            type: object
            properties:
                success:
                    type: boolean
                exportedAt:
                    type: string
                    format: date-time
                storage_entries:
                    type: array
                    items:
                        type: object
                filter_cache:
                    type: array
                    items:
                        type: object
                compilation_metadata:
                    type: array
                    items:
                        type: object

        AdminTablesResponse:
            type: object
            properties:
                success:
                    type: boolean
                tables:
                    type: array
                    items:
                        $ref: '#/components/schemas/TableInfo'

        TableInfo:
            type: object
            properties:
                name:
                    type: string
                type:
                    type: string
                    enum: [table, index]

        AdminQueryRequest:
            type: object
            required:
                - sql
            properties:
                sql:
                    type: string
                    description: SELECT-only SQL query to execute

        AdminQueryResponse:
            type: object
            properties:
                success:
                    type: boolean
                rows:
                    type: array
                    items:
                        type: object
                        additionalProperties: true
                rowCount:
                    type: integer
                meta:
                    type: object
                    description: Query metadata (e.g., column names, types, execution time)
                    additionalProperties: true

        # Workflow Schemas
        WorkflowStartResponse:
            type: object
            properties:
                success:
                    type: boolean
                message:
                    type: string
                workflowId:
                    type: string
                workflowType:
                    type: string
                    enum: [compilation, batch-compilation, cache-warming, health-monitoring]
                batchSize:
                    type: integer
                    description: Number of items in the batch (batch workflows only)
                configurationsCount:
                    type: string
                    description: Number of configurations to warm, or 'default' for all default configurations (cache-warming only)
                sourcesCount:
                    type: string
                    description: Number of sources to check, or 'default' for all default sources (health-monitoring only)

        CacheWarmRequest:
            type: object
            properties:
                configurations:
                    type: array
                    items:
                        $ref: '#/components/schemas/Configuration'
                    description: Configurations to warm (uses defaults if empty)

        HealthCheckRequest:
            type: object
            properties:
                sources:
                    type: array
                    items:
                        type: object
                        required:
                            - name
                            - url
                        properties:
                            name:
                                type: string
                            url:
                                type: string
                                format: uri
                            expectedMinRules:
                                type: integer
                    description: Sources to health-check (uses defaults if empty)
                alertOnFailure:
                    type: boolean
                    default: true

        WorkflowStatusResponse:
            type: object
            properties:
                success:
                    type: boolean
                workflowId:
                    type: string
                workflowType:
                    type: string
                status:
                    type: string
                    enum: [queued, running, completed, failed, paused, terminated]
                output:
                    type: object
                    nullable: true
                error:
                    type: string
                    nullable: true

        WorkflowMetricsResponse:
            type: object
            properties:
                success:
                    type: boolean
                timestamp:
                    type: string
                    format: date-time
                workflows:
                    type: object
                    description: Metrics grouped by workflow type
                    properties:
                        compilation:
                            type: object
                            description: Compilation workflow metrics (e.g., count, success rate, avg duration)
                            additionalProperties: true
                        batchCompilation:
                            type: object
                            description: Batch compilation workflow metrics
                            additionalProperties: true
                        cacheWarming:
                            type: object
                            description: Cache warming workflow metrics
                            additionalProperties: true
                        healthMonitoring:
                            type: object
                            description: Health monitoring workflow metrics
                            additionalProperties: true

        WorkflowEventsResponse:
            type: object
            properties:
                success:
                    type: boolean
                workflowId:
                    type: string
                workflowType:
                    type: string
                startedAt:
                    type: string
                    format: date-time
                completedAt:
                    type: string
                    format: date-time
                    nullable: true
                progress:
                    type: number
                    minimum: 0
                    maximum: 100
                isComplete:
                    type: boolean
                events:
                    type: array
                    items:
                        $ref: '#/components/schemas/WorkflowEvent'

        WorkflowEvent:
            type: object
            properties:
                type:
                    type: string
                workflowId:
                    type: string
                workflowType:
                    type: string
                timestamp:
                    type: string
                    format: date-time
                step:
                    type: string
                progress:
                    type: number
                    minimum: 0
                    maximum: 100
                message:
                    type: string
                data:
                    type: object
                    description: Step-specific data (structure varies by workflow type and step)
                    additionalProperties: true

        # Health Schemas
        HealthLatestResponse:
            type: object
            required:
                - success
            properties:
                success:
                    type: boolean
                message:
                    type: string
                    description: Present when no health data is available
                timestamp:
                    type: string
                    format: date-time
                    description: ISO timestamp of when this health check ran
                runId:
                    type: string
                    description: Unique identifier for the health monitoring workflow run
                results:
                    type: array
                    description: Per-source health check results
                    items:
                        $ref: '#/components/schemas/SourceHealthResult'
                summary:
                    type: object
                    description: Aggregate counts for the health check run
                    properties:
                        total:
                            type: integer
                        healthy:
                            type: integer
                        unhealthy:
                            type: integer

        SourceHealthResult:
            type: object
            required:
                - name
                - url
                - healthy
                - lastChecked
            properties:
                name:
                    type: string
                url:
                    type: string
                healthy:
                    type: boolean
                statusCode:
                    type: integer
                    nullable: true
                responseTimeMs:
                    type: number
                    nullable: true
                ruleCount:
                    type: integer
                    nullable: true
                error:
                    type: string
                    nullable: true
                lastChecked:
                    type: string
                    format: date-time

        HealthResponse:
            type: object
            properties:
                status:
                    type: string
                    enum: [healthy]
                version:
                    type: string
                    description: Current service version

        # Auth Admin Schemas
        CreateUserRequest:
            type: object
            required:
                - email
            properties:
                email:
                    type: string
                    format: email
                    description: User email address
                displayName:
                    type: string
                    description: Display name
                role:
                    type: string
                    enum: [admin, user, readonly]
                    default: user
                    description: User role

        CreateUserResponse:
            type: object
            properties:
                success:
                    type: boolean
                data:
                    type: object
                    properties:
                        user:
                            type: object
                            properties:
                                id:
                                    type: string
                                    format: uuid
                                email:
                                    type: string
                                    format: email
                                role:
                                    type: string

        CreateApiKeyRequest:
            type: object
            required:
                - userId
                - name
            properties:
                userId:
                    type: string
                    format: uuid
                    description: ID of the user to create the key for
                name:
                    type: string
                    description: Descriptive name for the API key
                scopes:
                    type: array
                    items:
                        type: string
                    description: Permission scopes for the key
                rateLimitPerMinute:
                    type: integer
                    description: Rate limit override for this key
                expiresAt:
                    type: string
                    format: date-time
                    description: Expiry date for the key

        CreateApiKeyResponse:
            type: object
            properties:
                success:
                    type: boolean
                data:
                    type: object
                    properties:
                        id:
                            type: string
                            format: uuid
                        apiKey:
                            type: string
                            description: The raw API key (only returned once — store securely)
                        keyPrefix:
                            type: string
                            description: Prefix for identifying the key
                        name:
                            type: string
                        scopes:
                            type: array
                            items:
                                type: string
                        message:
                            type: string

        ListApiKeysResponse:
            type: object
            properties:
                success:
                    type: boolean
                data:
                    type: object
                    properties:
                        keys:
                            type: array
                            items:
                                $ref: '#/components/schemas/ApiKeyInfo'
                        count:
                            type: integer

        ApiKeyInfo:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                name:
                    type: string
                keyPrefix:
                    type: string
                scopes:
                    type: array
                    items:
                        type: string
                rateLimitPerMinute:
                    type: integer
                createdAt:
                    type: string
                    format: date-time
                expiresAt:
                    type: string
                    format: date-time
                    nullable: true
                revokedAt:
                    type: string
                    format: date-time
                    nullable: true
                lastUsedAt:
                    type: string
                    format: date-time
                    nullable: true
                status:
                    type: string
                    enum: [active, expired, revoked]

        RevokeApiKeyRequest:
            type: object
            properties:
                apiKeyId:
                    type: string
                    format: uuid
                    description: ID of the API key to revoke
                keyPrefix:
                    type: string
                    description: Prefix of the API key to revoke

        RevokeApiKeyResponse:
            type: object
            properties:
                success:
                    type: boolean
                data:
                    type: object
                    properties:
                        revoked:
                            type: boolean

        ValidateApiKeyRequest:
            type: object
            required:
                - apiKey
            properties:
                apiKey:
                    type: string
                    description: The API key to validate

        ValidateApiKeyResponse:
            type: object
            properties:
                success:
                    type: boolean
                data:
                    type: object
                    properties:
                        valid:
                            type: boolean
                        keyPrefix:
                            type: string
                        name:
                            type: string
                        scopes:
                            type: array
                            items:
                                type: string
                        userEmail:
                            type: string
                        status:
                            type: string
                            enum: [active, expired, revoked]
                        error:
                            type: string
                            description: Present when valid is false

        # User-Level API Key Schemas
        UserCreateApiKeyRequest:
            type: object
            required:
                - name
            properties:
                name:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: Human-readable name for the key
                scopes:
                    type: array
                    items:
                        type: string
                        enum: [compile, rules, admin]
                    minItems: 1
                    default: [compile]
                    description: Permissions granted to this key (defaults to ["compile"])
                expiresInDays:
                    type: integer
                    minimum: 1
                    maximum: 365
                    description: Days until expiration (omit for no expiry)

        UserCreateApiKeyResponse:
            type: object
            properties:
                success:
                    type: boolean
                id:
                    type: string
                    format: uuid
                key:
                    type: string
                    description: 'The plaintext API key (returned **only once** on creation). Starts with `abc_`.'
                keyPrefix:
                    type: string
                    description: First 8 characters of the key (e.g. abc_XXXX)
                name:
                    type: string
                scopes:
                    type: array
                    items:
                        type: string
                rateLimitPerMinute:
                    type: integer
                expiresAt:
                    type: string
                    format: date-time
                    nullable: true
                createdAt:
                    type: string
                    format: date-time

        UserApiKeyInfo:
            type: object
            properties:
                id:
                    type: string
                    format: uuid
                keyPrefix:
                    type: string
                name:
                    type: string
                scopes:
                    type: array
                    items:
                        type: string
                rateLimitPerMinute:
                    type: integer
                lastUsedAt:
                    type: string
                    format: date-time
                    nullable: true
                expiresAt:
                    type: string
                    format: date-time
                    nullable: true
                revokedAt:
                    type: string
                    format: date-time
                    nullable: true
                createdAt:
                    type: string
                    format: date-time
                updatedAt:
                    type: string
                    format: date-time
                isActive:
                    type: boolean
                    description: Whether the key is currently usable (not revoked and not expired)

        UserListApiKeysResponse:
            type: object
            properties:
                success:
                    type: boolean
                keys:
                    type: array
                    items:
                        $ref: '#/components/schemas/UserApiKeyInfo'
                total:
                    type: integer

        UserUpdateApiKeyRequest:
            type: object
            minProperties: 1
            properties:
                name:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: New name for the key
                scopes:
                    type: array
                    items:
                        type: string
                        enum: [compile, rules, admin]
                    minItems: 1
                    description: New scopes for the key
            description: At least one of `name` or `scopes` must be provided.

        UserUpdateApiKeyResponse:
            type: object
            properties:
                success:
                    type: boolean
                id:
                    type: string
                    format: uuid
                keyPrefix:
                    type: string
                name:
                    type: string
                scopes:
                    type: array
                    items:
                        type: string
                rateLimitPerMinute:
                    type: integer
                lastUsedAt:
                    type: string
                    format: date-time
                    nullable: true
                expiresAt:
                    type: string
                    format: date-time
                    nullable: true
                createdAt:
                    type: string
                    format: date-time
                updatedAt:
                    type: string
                    format: date-time

        # Migration Schemas
        MigrationResult:
            type: object
            properties:
                success:
                    type: boolean
                data:
                    type: object
                    properties:
                        dryRun:
                            type: boolean
                        startedAt:
                            type: string
                            format: date-time
                        completedAt:
                            type: string
                            format: date-time
                        totalDurationMs:
                            type: integer
                        tables:
                            type: array
                            items:
                                $ref: '#/components/schemas/MigrationTableStats'
                        errors:
                            type: array
                            items:
                                type: string
                        summary:
                            type: string
                            description: Human-readable summary (omitted for dry runs)
                        message:
                            type: string
                            description: Present for dry runs

        MigrationTableStats:
            type: object
            properties:
                table:
                    type: string
                sourceCount:
                    type: integer
                migratedCount:
                    type: integer
                skippedCount:
                    type: integer
                errorCount:
                    type: integer
                durationMs:
                    type: integer

        # Backend Status Schemas
        BackendStatusResponse:
            type: object
            properties:
                success:
                    type: boolean
                data:
                    type: object
                    properties:
                        backends:
                            type: object
                            properties:
                                d1:
                                    $ref: '#/components/schemas/BackendHealth'
                                postgresql:
                                    $ref: '#/components/schemas/BackendHealth'
                        primary:
                            type: string
                            enum: [d1, postgresql]
                            description: Currently active primary backend
                        timestamp:
                            type: string
                            format: date-time

        BackendHealth:
            type: object
            properties:
                available:
                    type: boolean
                latencyMs:
                    type: integer
                host:
                    type: string
                    description: Host name (PostgreSQL only)
                error:
                    type: string
                    description: Error message if unavailable

        # PostgreSQL Admin Schemas
        PgStorageStatsResponse:
            type: object
            properties:
                success:
                    type: boolean
                data:
                    type: object
                    properties:
                        stats:
                            type: object
                            properties:
                                storage_entries:
                                    type: integer
                                filter_cache:
                                    type: integer
                                compilation_metadata:
                                    type: integer
                                expired_storage:
                                    type: integer
                                expired_cache:
                                    type: integer
                                users:
                                    type: integer
                                active_api_keys:
                                    type: integer
                        backend:
                            type: string
                            example: postgresql
                        host:
                            type: string
                        timestamp:
                            type: string
                            format: date-time

        # WebSocket Message Schemas
        WsCompileRequest:
            type: object
            required:
                - type
                - sessionId
                - configuration
            properties:
                type:
                    type: string
                    enum: [compile]
                sessionId:
                    type: string
                configuration:
                    $ref: '#/components/schemas/Configuration'
                preFetchedContent:
                    type: object
                    additionalProperties:
                        type: string
                benchmark:
                    type: boolean

        WsCancelRequest:
            type: object
            required:
                - type
                - sessionId
            properties:
                type:
                    type: string
                    enum: [cancel]
                sessionId:
                    type: string

        WsPingMessage:
            type: object
            required:
                - type
            properties:
                type:
                    type: string
                    enum: [ping]

        WsWelcomeMessage:
            type: object
            required:
                - type
                - version
                - connectionId
                - capabilities
            properties:
                type:
                    type: string
                    enum: [welcome]
                version:
                    type: string
                connectionId:
                    type: string
                capabilities:
                    type: object
                    properties:
                        maxConcurrentCompilations:
                            type: integer
                        supportsPauseResume:
                            type: boolean
                        supportsStreaming:
                            type: boolean

        WsPongMessage:
            type: object
            required:
                - type
            properties:
                type:
                    type: string
                    enum: [pong]
                timestamp:
                    type: string

        WsCompileStartedMessage:
            type: object
            required:
                - type
                - sessionId
                - configurationName
            properties:
                type:
                    type: string
                    enum: [compile:started]
                sessionId:
                    type: string
                configurationName:
                    type: string

        WsEventMessage:
            type: object
            required:
                - type
                - sessionId
                - eventType
                - data
            properties:
                type:
                    type: string
                    enum: [event]
                sessionId:
                    type: string
                eventType:
                    type: string
                    enum:
                        - log
                        - source:start
                        - source:complete
                        - source:error
                        - transformation:start
                        - transformation:complete
                        - progress
                        - result
                        - done
                        - error
                        - diagnostic
                        - cache
                        - network
                        - metric
                data:
                    type: object

        WsCompileCompleteMessage:
            type: object
            required:
                - type
                - sessionId
                - rules
                - ruleCount
            properties:
                type:
                    type: string
                    enum: [compile:complete]
                sessionId:
                    type: string
                rules:
                    type: array
                    items:
                        type: string
                ruleCount:
                    type: integer
                metrics:
                    type: object
                compiledAt:
                    type: string

        WsCompileErrorMessage:
            type: object
            required:
                - type
                - sessionId
                - error
            properties:
                type:
                    type: string
                    enum: [compile:error]
                sessionId:
                    type: string
                error:
                    type: string
                details:
                    type: object

        BrowserWaitUntil:
            type: string
            enum: [load, domcontentloaded, networkidle]
            default: networkidle
            description: |
                Playwright `waitUntil` navigation event. `networkidle` (default) waits until
                there are no more than 0 network connections for at least 500 ms — suitable for
                most filter-list sources. Use `load` for fastest navigation.

        BrowserResolveRequest:
            type: object
            required: [url]
            properties:
                url:
                    type: string
                    format: uri
                    description: The URL to navigate to and resolve.
                    example: 'https://example.com/redirect-me'
                waitUntil:
                    $ref: '#/components/schemas/BrowserWaitUntil'

        BrowserResolveResponse:
            type: object
            required: [success, resolvedUrl, originalUrl]
            properties:
                success:
                    type: boolean
                    example: true
                resolvedUrl:
                    type: string
                    format: uri
                    description: The canonical URL after all JavaScript redirects have settled.
                    example: 'https://example.com/final-destination'
                originalUrl:
                    type: string
                    format: uri
                    description: The original URL that was submitted.
                    example: 'https://example.com/redirect-me'

        SourceMonitorEntry:
            type: object
            required: [url, reachable, checkedAt]
            properties:
                url:
                    type: string
                    format: uri
                    description: The source URL that was checked.
                reachable:
                    type: boolean
                    description: Whether the URL was reachable and returned non-empty content.
                checkedAt:
                    type: string
                    format: date-time
                    description: ISO-8601 timestamp of when this URL was checked.
                screenshotKey:
                    type: string
                    description: R2 object key for the captured screenshot (only present when captureScreenshots is true).
                error:
                    type: string
                    description: Error message, present only when the URL could not be fetched.

        SourceMonitorRequest:
            type: object
            required: [urls]
            properties:
                urls:
                    type: array
                    items:
                        type: string
                        format: uri
                    minItems: 1
                    maxItems: 10
                    description: One or more filter-list source URLs to check (max 10).
                    example:
                        - 'https://example.com/filter-list.txt'
                        - 'https://another.example.com/rules.txt'
                captureScreenshots:
                    type: boolean
                    default: false
                    description: When true, a full-page PNG screenshot is captured and stored in R2 per URL.
                screenshotPrefix:
                    type: string
                    description: R2 key prefix for screenshots (alphanumeric, hyphens, underscores only). Defaults to the current ISO date.
                    example: '2025-07-01'
                timeout:
                    type: integer
                    minimum: 1000
                    maximum: 60000
                    description: Per-URL navigation timeout in milliseconds.
                    example: 30000
                waitUntil:
                    $ref: '#/components/schemas/BrowserWaitUntil'

        SourceMonitorResponse:
            type: object
            required: [success, results, total, reachable, unreachable]
            properties:
                success:
                    type: boolean
                    example: true
                results:
                    type: array
                    items:
                        $ref: '#/components/schemas/SourceMonitorEntry'
                total:
                    type: integer
                    description: Total number of URLs checked.
                reachable:
                    type: integer
                    description: Number of reachable URLs.
                unreachable:
                    type: integer
                    description: Number of unreachable URLs.

    responses:
        BadRequest:
            description: Bad request - input validation failed
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            success: { type: boolean, example: false }
                            error: { type: string, example: 'requestId: Invalid requestId format' }

        Unauthorized:
            description: Unauthorized - authentication required
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            success: { type: boolean, example: false }
                            error: { type: string, example: 'Authentication required' }

        RateLimited:
            description: Rate limit exceeded
            headers:
                Retry-After:
                    schema: { type: integer }
                    description: Seconds until retry allowed
                X-RateLimit-Limit:
                    schema: { type: integer }
                X-RateLimit-Remaining:
                    schema: { type: integer }
                X-RateLimit-Reset:
                    schema: { type: integer }
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            success: { type: boolean, example: false }
                            error: { type: string, example: 'Rate limit exceeded.' }

        BadRequestError:
            description: Bad request - request body failed schema validation
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            success:
                                type: boolean
                                example: false
                            error:
                                type: string
                                example: Invalid request body

        RateLimitError:
            description: Rate limit exceeded
            headers:
                Retry-After:
                    schema:
                        type: integer
                    description: Seconds until retry allowed
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            success:
                                type: boolean
                                example: false
                            error:
                                type: string
                                example: Rate limit exceeded. Maximum 10 requests per minute.

        CompilationError:
            description: Compilation failed
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            success:
                                type: boolean
                                example: false
                            error:
                                type: string

        UnauthorizedError:
            description: Unauthorized - missing or invalid admin key
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            success:
                                type: boolean
                                example: false
                            error:
                                type: string

        ServiceUnavailable:
            description: Service unavailable - required binding not configured
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            success:
                                type: boolean
                                example: false
                            error:
                                type: string

        # Rule Validation Schemas
        ConvertRuleRequest:
            type: object
            required:
                - rule
                - targetSyntax
            properties:
                rule:
                    type: string
                    description: The adblock filter rule text to convert
                    example: "example.com##+js(abort-on-property-read, ads)"
                targetSyntax:
                    type: string
                    enum:
                        - adg
                        - ubo
                    description: 'Target adblock syntax: adg (AdGuard) or ubo (uBlock Origin)'
                    example: 'adg'
                turnstileToken:
                    type: string
                    description: Cloudflare Turnstile token. Required when Turnstile protection is enabled for the `/convert-rule` endpoint.
                    example: "0.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

        ConvertRuleResponse:
            type: object
            required:
                - success
                - rule
                - targetSyntax
                - convertedRules
                - isConverted
                - duration
            properties:
                success:
                    type: boolean
                    description: Whether the conversion request was processed successfully
                rule:
                    type: string
                    description: The original rule text that was submitted
                targetSyntax:
                    type: string
                    enum:
                        - adg
                        - ubo
                    description: The target syntax that was requested
                convertedRules:
                    type: array
                    items:
                        type: string
                    description: The converted rule text(s); may be multiple when a single rule expands
                isConverted:
                    type: boolean
                    description: Whether the rule was actually converted (false if already in target syntax)
                error:
                    type: string
                    description: Error message if conversion failed
                    nullable: true
                duration:
                    type: string
                    description: Time taken to perform the conversion (e.g. "2ms")
                    example: '2ms'

        ValidateRuleRequest:
            type: object
            required:
                - rule
            properties:
                rule:
                    type: string
                    description: The adblock rule string to validate
                    example: '||example.com^'
                testUrl:
                    type: string
                    format: uri
                    description: Optional URL to test the rule against
                    example: 'https://example.com/ads/banner.png'
                strict:
                    type: boolean
                    description: Enable strict validation mode (rejects rules that the tolerant parser would silently accept)
                    default: false
                    example: true

        ValidateRuleResponse:
            type: object
            required:
                - success
                - valid
                - rule
                - duration
            properties:
                success:
                    type: boolean
                    description: Whether the validation request was processed successfully
                valid:
                    type: boolean
                    description: Whether the rule is syntactically valid
                rule:
                    type: string
                    description: The original rule string
                ruleType:
                    type: string
                    description: High-level classification of the rule (e.g. "NetworkRule", "CosmeticRule")
                    nullable: true
                category:
                    type: string
                    description: Category of the rule (e.g. "Network", "Cosmetic")
                    nullable: true
                syntax:
                    type: string
                    description: Detected adblock syntax variant for the rule
                    nullable: true
                ast:
                    type: object
                    description: Abstract Syntax Tree of the parsed rule
                    nullable: true
                matchResult:
                    type: boolean
                    description: Whether the rule matches the provided testUrl (if supplied)
                    nullable: true
                testUrl:
                    type: string
                    format: uri
                    description: The URL used to test the rule against, if provided
                    nullable: true
                error:
                    type: string
                    description: Error message if the rule is invalid
                    nullable: true
                duration:
                    type: string
                    description: Processing duration (e.g. "2ms")

        # Rule Set Schemas
        RuleSet:
            type: object
            required:
                - id
                - name
                - rules
                - createdAt
                - updatedAt
            properties:
                id:
                    type: string
                    format: uuid
                    description: Unique identifier for the rule set
                name:
                    type: string
                    description: Human-readable name for the rule set
                description:
                    type: string
                    description: Optional description of the rule set
                    nullable: true
                rules:
                    type: array
                    items:
                        type: string
                    description: Array of adblock rule strings
                tags:
                    type: array
                    items:
                        type: string
                    description: Optional tags for categorising the rule set
                createdAt:
                    type: string
                    format: date-time
                updatedAt:
                    type: string
                    format: date-time

        RuleSetCreateRequest:
            type: object
            required:
                - name
                - rules
            properties:
                name:
                    type: string
                    description: Name for the new rule set
                description:
                    type: string
                    nullable: true
                rules:
                    type: array
                    items:
                        type: string
                    minItems: 1
                tags:
                    type: array
                    items:
                        type: string

        RuleSetUpdateRequest:
            type: object
            properties:
                name:
                    type: string
                description:
                    type: string
                    nullable: true
                rules:
                    type: array
                    items:
                        type: string
                tags:
                    type: array
                    items:
                        type: string

        RuleSetMeta:
            type: object
            description: Rule set metadata returned in list responses (no rules array)
            required:
                - id
                - name
                - ruleCount
                - createdAt
                - updatedAt
            properties:
                id:
                    type: string
                    format: uuid
                    description: Unique identifier for the rule set
                name:
                    type: string
                    description: Human-readable name for the rule set
                description:
                    type: string
                    description: Optional description of the rule set
                    nullable: true
                ruleCount:
                    type: integer
                    description: Number of rules in the set
                tags:
                    type: array
                    items:
                        type: string
                    description: Optional tags for categorising the rule set
                createdAt:
                    type: string
                    format: date-time
                updatedAt:
                    type: string
                    format: date-time

        RuleSetListResponse:
            type: object
            required:
                - success
                - items
                - total
            properties:
                success:
                    type: boolean
                items:
                    type: array
                    items:
                        $ref: '#/components/schemas/RuleSetMeta'
                    description: Metadata-only list of rule sets (rules array excluded)
                total:
                    type: integer
                    description: Total number of rule sets

        RuleSetResponse:
            type: object
            required:
                - success
                - data
            properties:
                success:
                    type: boolean
                data:
                    $ref: '#/components/schemas/RuleSet'

        # Webhook / Notification Schemas
        NotifyLevel:
            type: string
            enum:
                - info
                - warn
                - error
                - debug
            description: Severity level of the notification

        WebhookNotifyRequest:
            type: object
            required:
                - event
                - message
            properties:
                event:
                    type: string
                    description: Event name or type (e.g. "compile.error", "rule.invalid")
                    minLength: 1
                    maxLength: 128
                level:
                    $ref: '#/components/schemas/NotifyLevel'
                message:
                    type: string
                    description: Human-readable message describing the event
                    minLength: 1
                    maxLength: 2048
                metadata:
                    type: object
                    additionalProperties: true
                    description: Optional structured metadata associated with the event
                    nullable: true
                source:
                    type: string
                    description: Identifies the component that emitted the event
                    nullable: true
                timestamp:
                    type: string
                    format: date-time
                    description: ISO 8601 event timestamp; defaults to current time if omitted
                    nullable: true

        WebhookDelivery:
            type: object
            required:
                - target
                - success
            properties:
                target:
                    type: string
                    description: Delivery target identifier (e.g. webhook, sentry, datadog)
                success:
                    type: boolean
                statusCode:
                    type: integer
                    description: HTTP status code returned by the target
                    nullable: true
                error:
                    type: string
                    description: Error message if delivery failed
                    nullable: true

        WebhookNotifyResponse:
            type: object
            required:
                - success
                - event
                - deliveries
                - duration
            properties:
                success:
                    type: boolean
                    description: True if at least one delivery succeeded
                event:
                    type: string
                    description: The event name from the request
                deliveries:
                    type: array
                    items:
                        $ref: '#/components/schemas/WebhookDelivery'
                duration:
                    type: string
                    description: Processing duration (e.g. "5ms")

        # -------------------------------------------------------------------------
        # Local JWT Auth Bridge Schemas
        # -------------------------------------------------------------------------

        LocalSignupRequest:
            type: object
            required: [identifier, password]
            properties:
                identifier:
                    type: string
                    description: Email address (user@example.com) or E.164 phone number (+12025551234)
                    example: user@example.com
                password:
                    type: string
                    minLength: 8
                    maxLength: 128
                    description: Password (minimum 8 characters)

        LocalLoginRequest:
            type: object
            required: [identifier, password]
            properties:
                identifier:
                    type: string
                    description: Email address or E.164 phone number used at signup
                    example: user@example.com
                password:
                    type: string
                    minLength: 1
                    maxLength: 128

        LocalChangePasswordRequest:
            type: object
            required: [currentPassword, newPassword]
            properties:
                currentPassword:
                    type: string
                    minLength: 1
                    maxLength: 128
                    description: The user's current password
                newPassword:
                    type: string
                    minLength: 8
                    maxLength: 128
                    description: The new password (minimum 8 characters)

        LocalUserPublic:
            type: object
            required: [id, identifier, identifier_type, role, tier, api_disabled, created_at, updated_at]
            properties:
                id:
                    type: string
                    format: uuid
                    description: User UUID
                identifier:
                    type: string
                    description: Email address or E.164 phone number
                identifier_type:
                    type: string
                    enum: [email, phone]
                    description: Whether the identifier is an email address or phone number
                role:
                    type: string
                    description: User role (e.g. `user`, `admin`)
                    example: user
                tier:
                    type: string
                    description: Rate-limit tier (e.g. `free`, `pro`, `admin`)
                    example: free
                api_disabled:
                    type: integer
                    enum: [0, 1]
                    description: Whether API access is disabled for this user (0 = enabled, 1 = disabled)
                created_at:
                    type: string
                    format: date-time
                updated_at:
                    type: string
                    format: date-time

        LocalAuthResponse:
            type: object
            required: [success, token, user]
            properties:
                success:
                    type: boolean
                    example: true
                token:
                    type: string
                    description: Signed HS256 JWT valid for 24 hours
                user:
                    $ref: '#/components/schemas/LocalUserPublic'

        LocalMeResponse:
            type: object
            required: [success, user]
            properties:
                success:
                    type: boolean
                    example: true
                user:
                    $ref: '#/components/schemas/LocalUserPublic'

        AdminLocalUsersListResponse:
            type: object
            required: [success, users, total, limit, offset]
            properties:
                success:
                    type: boolean
                    example: true
                users:
                    type: array
                    items:
                        $ref: '#/components/schemas/LocalUserPublic'
                total:
                    type: integer
                    description: Total number of users in the database
                limit:
                    type: integer
                offset:
                    type: integer

        AdminLocalUserResponse:
            type: object
            required: [success, user]
            properties:
                success:
                    type: boolean
                    example: true
                user:
                    $ref: '#/components/schemas/LocalUserPublic'

        AdminCreateLocalUserRequest:
            type: object
            required: [identifier, password]
            properties:
                identifier:
                    type: string
                    description: Email address or E.164 phone number
                password:
                    type: string
                    minLength: 8
                    maxLength: 128
                role:
                    type: string
                    description: Role to assign (defaults to `user`)
                    default: user
                    example: user
                tier:
                    type: string
                    description: Tier to assign (defaults to the role's default tier)
                    example: free

        AdminUpdateLocalUserRequest:
            type: object
            description: At least one of `tier`, `role`, or `api_disabled` must be provided.
            properties:
                tier:
                    type: string
                    description: New rate-limit tier
                    example: pro
                role:
                    type: string
                    minLength: 1
                    maxLength: 64
                    description: New role name
                    example: admin
                api_disabled:
                    type: integer
                    enum: [0, 1]
                    description: Set to 1 to disable API access, 0 to re-enable

        AdminAuthConfigResponse:
            type: object
            required: [success, provider, roles, tiers, routes]
            properties:
                success:
                    type: boolean
                    example: true
                provider:
                    type: string
                    enum: [local-jwt, clerk]
                    description: Active auth provider
                roles:
                    type: array
                    items:
                        type: object
                        required: [role, displayName, tier, canSelfRegister, description]
                        properties:
                            role:
                                type: string
                            displayName:
                                type: string
                            tier:
                                type: string
                            canSelfRegister:
                                type: boolean
                            description:
                                type: string
                tiers:
                    type: array
                    items:
                        type: object
                        required: [tier, displayName, order, description]
                        properties:
                            tier:
                                type: string
                            displayName:
                                type: string
                            order:
                                type: integer
                            rateLimit:
                                type: integer
                                nullable: true
                                description: Requests per minute (null = unlimited)
                            description:
                                type: string
                routes:
                    type: array
                    items:
                        type: object
                        required: [pattern, minTier, description]
                        properties:
                            pattern:
                                type: string
                            minTier:
                                type: string
                            requiredRole:
                                type: string
                                nullable: true
                            description:
                                type: string

        AdminUserUsageResponse:
            type: object
            required: [success, userId, lookbackDays]
            properties:
                success:
                    type: boolean
                    example: true
                userId:
                    type: string
                lookbackDays:
                    type: integer
                total:
                    type: object
                    nullable: true
                    properties:
                        count:
                            type: integer
                        firstSeen:
                            type: string
                            format: date-time
                            nullable: true
                        lastSeen:
                            type: string
                            format: date-time
                            nullable: true
                days:
                    type: array
                    items:
                        type: object
                        required: [date, count]
                        properties:
                            date:
                                type: string
                                format: date
                                description: Date in YYYY-MM-DD format
                            count:
                                type: integer
                            routes:
                                type: object
                                additionalProperties:
                                    type: integer
                                description: Per-route request counts for this day

    securitySchemes:
        Turnstile:
            type: apiKey
            in: header
            name: turnstileToken
            description: Cloudflare Turnstile token (if enabled on the server)
        AdminKey:
            type: apiKey
            in: header
            name: X-Admin-Key
            description: Admin API key for protected admin endpoints
        ClerkJWT:
            type: http
            scheme: bearer
            bearerFormat: JWT
            description: Clerk-issued JWT for authenticated user requests. Obtain via Clerk sign-in flow.
        UserApiKey:
            type: http
            scheme: bearer
            bearerFormat: ApiKey
            description: "User API key with abc_ prefix. Pass the key as a Bearer token in the Authorization header (e.g. Authorization: Bearer abc_...)."

security: []