{
    "openapi": "3.1.0",
    "info": {
        "title": "BookBeam Headless API",
        "version": "1.0.0",
        "description": "Headless REST API for BookBeam author workflows, book distribution, newsletter sync, and telemetry.",
        "contact": {
            "name": "BookBeam Support",
            "url": "https://bookbeam.app"
        }
    },
    "servers": [
        {
            "url": "https://bookbeam.app",
            "description": "Current Environment"
        }
    ],
    "tags": [
        {
            "name": "Authentication & Tokens",
            "description": "Personal access tokens for headless API authentication."
        },
        {
            "name": "Book Projects",
            "description": "Manage author book projects and reader access."
        },
        {
            "name": "Book Files",
            "description": "Upload, manage, and download book asset files (EPUB, MOBI, PDF)."
        },
        {
            "name": "Signup Links",
            "description": "Create and configure reader campaign giveaway links."
        },
        {
            "name": "Reader Distribution",
            "description": "Public reader-facing link resolution, email signup, confirmation, and file delivery."
        },
        {
            "name": "Newsletters & Integrations",
            "description": "Configure newsletter providers, webhooks, and subscriber list syncing."
        },
        {
            "name": "Telemetry & Billing",
            "description": "Query author activity logs, dashboard metrics, and subscription status."
        }
    ],
    "paths": {
        "/api/v1/oauth/device/code": {
            "post": {
                "tags": [
                    "Authentication & Tokens"
                ],
                "summary": "Request Device Authorization Code",
                "description": "Initiate OAuth 2.0 Device Authorization Grant flow.",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "client_id": {
                                        "type": "string",
                                        "example": "bookbeam-cli"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Device code issued successfully.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DeviceCodeResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation error."
                    }
                }
            }
        },
        "/api/v1/oauth/device/token": {
            "post": {
                "tags": [
                    "Authentication & Tokens"
                ],
                "summary": "Poll Device Access Token",
                "description": "Poll for authorization status and receive token upon user approval.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "grant_type",
                                    "device_code"
                                ],
                                "properties": {
                                    "grant_type": {
                                        "type": "string",
                                        "example": "urn:ietf:params:oauth:grant-type:device_code"
                                    },
                                    "device_code": {
                                        "type": "string",
                                        "example": "gm4x..."
                                    },
                                    "client_id": {
                                        "type": "string",
                                        "example": "bookbeam-cli"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Personal access token issued.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DeviceTokenResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Authorization pending, slow down, expired, or access denied."
                    },
                    "422": {
                        "description": "Validation error."
                    }
                }
            }
        },
        "/api/v1/oauth/device/verify": {
            "post": {
                "tags": [
                    "Authentication & Tokens"
                ],
                "summary": "Verify Device Code (Headless)",
                "description": "Approve or deny a pending device code authorization request headlessly.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "user_code",
                                    "action"
                                ],
                                "properties": {
                                    "user_code": {
                                        "type": "string",
                                        "example": "ABCD-EFGH"
                                    },
                                    "action": {
                                        "type": "string",
                                        "enum": [
                                            "approve",
                                            "deny"
                                        ],
                                        "example": "approve"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Device authorization action applied successfully."
                    },
                    "400": {
                        "description": "Invalid or expired user code."
                    },
                    "401": {
                        "description": "Unauthenticated."
                    },
                    "422": {
                        "description": "Validation error."
                    }
                }
            }
        },
        "/api/v1/tokens": {
            "post": {
                "tags": [
                    "Authentication & Tokens"
                ],
                "summary": "Generate API Token",
                "description": "Create a new personal access token using author account credentials.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "email",
                                    "password",
                                    "name"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "password": {
                                        "type": "string"
                                    },
                                    "name": {
                                        "type": "string",
                                        "example": "CLI Integration"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Token created successfully.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/TokenResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation error or invalid credentials."
                    }
                }
            },
            "get": {
                "tags": [
                    "Authentication & Tokens"
                ],
                "summary": "List API Tokens",
                "description": "List all active personal access tokens for the authenticated user.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of tokens."
                    },
                    "401": {
                        "description": "Unauthenticated."
                    }
                }
            }
        },
        "/api/v1/tokens/{token_id}": {
            "delete": {
                "tags": [
                    "Authentication & Tokens"
                ],
                "summary": "Revoke API Token",
                "description": "Revoke an existing personal access token by ID.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "token_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Token revoked successfully."
                    },
                    "404": {
                        "description": "Token not found."
                    }
                }
            }
        },
        "/api/v1/user": {
            "get": {
                "tags": [
                    "Authentication & Tokens"
                ],
                "summary": "Get Authenticated User Profile",
                "description": "Return current user details and their active team.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Authenticated user profile details.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/UserProfile"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    }
                }
            }
        },
        "/api/v1/projects": {
            "get": {
                "tags": [
                    "Book Projects"
                ],
                "summary": "List Book Projects",
                "description": "List book projects belonging to the active team, newest first, 15 per page.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated book projects.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "current_page",
                                        "data",
                                        "last_page",
                                        "per_page",
                                        "total"
                                    ],
                                    "properties": {
                                        "current_page": {
                                            "type": "integer"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Project"
                                            }
                                        },
                                        "first_page_url": {
                                            "type": "string"
                                        },
                                        "from": {
                                            "type": "integer",
                                            "nullable": true
                                        },
                                        "last_page": {
                                            "type": "integer"
                                        },
                                        "last_page_url": {
                                            "type": "string"
                                        },
                                        "links": {
                                            "type": "array",
                                            "items": {
                                                "type": "object"
                                            }
                                        },
                                        "next_page_url": {
                                            "type": "string",
                                            "nullable": true
                                        },
                                        "path": {
                                            "type": "string"
                                        },
                                        "per_page": {
                                            "type": "integer"
                                        },
                                        "prev_page_url": {
                                            "type": "string",
                                            "nullable": true
                                        },
                                        "to": {
                                            "type": "integer",
                                            "nullable": true
                                        },
                                        "total": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    }
                }
            },
            "post": {
                "tags": [
                    "Book Projects"
                ],
                "summary": "Create Book Project",
                "description": "Create a new book project for the team.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "title"
                                ],
                                "properties": {
                                    "title": {
                                        "type": "string"
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "cover_image": {
                                        "type": "string",
                                        "format": "binary",
                                        "nullable": true
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Project created.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Project"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/projects/{project_id}": {
            "get": {
                "tags": [
                    "Book Projects"
                ],
                "summary": "Get Book Project",
                "description": "Retrieve a book project by ID with its files and links count.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "project_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Project found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Project"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Project not found."
                    }
                }
            },
            "put": {
                "tags": [
                    "Book Projects"
                ],
                "summary": "Update Book Project",
                "description": "Update details of an existing book project.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "project_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "title": {
                                        "type": "string"
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "cover_image": {
                                        "type": "string",
                                        "format": "binary",
                                        "nullable": true
                                    },
                                    "remove_cover_image": {
                                        "type": "boolean"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Project updated."
                    },
                    "404": {
                        "description": "Project not found."
                    }
                }
            },
            "delete": {
                "tags": [
                    "Book Projects"
                ],
                "summary": "Delete Book Project",
                "description": "Permanently delete a book project and all attached assets.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "project_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Project deleted."
                    },
                    "404": {
                        "description": "Project not found."
                    }
                }
            }
        },
        "/api/v1/projects/{project_id}/downloaders": {
            "get": {
                "tags": [
                    "Book Projects"
                ],
                "summary": "List Project Downloaders",
                "description": "Retrieve paginated reader downloads and email signups for this project.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "project_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated downloaders."
                    }
                }
            }
        },
        "/api/v1/projects/{project_id}/export-downloaders": {
            "get": {
                "tags": [
                    "Book Projects"
                ],
                "summary": "Export Downloaders CSV",
                "description": "Export reader downloader emails and timestamp details as a CSV file.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "project_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "CSV file download stream.",
                        "content": {
                            "text/csv": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/projects/{project_id}/files": {
            "get": {
                "tags": [
                    "Book Files"
                ],
                "summary": "List Project Files",
                "description": "Retrieve all uploaded ebook files for a project.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "project_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Array of book files.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/BookFile"
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "tags": [
                    "Book Files"
                ],
                "summary": "Upload Book File",
                "description": "Upload a new EPUB, MOBI, or PDF file for this project.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "project_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "file",
                                    "format"
                                ],
                                "properties": {
                                    "file": {
                                        "type": "string",
                                        "format": "binary"
                                    },
                                    "format": {
                                        "type": "string",
                                        "enum": [
                                            "epub",
                                            "mobi",
                                            "pdf"
                                        ]
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "File uploaded.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BookFile"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/projects/{project_id}/files/{file_id}": {
            "delete": {
                "tags": [
                    "Book Files"
                ],
                "summary": "Delete Book File",
                "description": "Delete a file asset and purge its storage.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "project_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "file_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "File deleted."
                    },
                    "404": {
                        "description": "File not found."
                    }
                }
            }
        },
        "/api/v1/projects/{project_id}/files/{file_id}/download": {
            "get": {
                "tags": [
                    "Book Files"
                ],
                "summary": "Download Book File (Author)",
                "description": "Stream or download the book file as an authenticated author.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "project_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "file_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Binary file stream."
                    }
                }
            }
        },
        "/api/v1/projects/{project_id}/links": {
            "get": {
                "tags": [
                    "Signup Links"
                ],
                "summary": "List Signup Links",
                "description": "List giveaway campaign links for a book project.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "project_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Array of signup links.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/SignupLink"
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "tags": [
                    "Signup Links"
                ],
                "summary": "Create Signup Link",
                "description": "Create a new reader giveaway campaign link.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "project_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "title": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "opt_in_text": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Link created.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SignupLink"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/projects/{project_id}/links/{link_id}": {
            "put": {
                "tags": [
                    "Signup Links"
                ],
                "summary": "Update Signup Link",
                "description": "Update giveaway campaign link parameters.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "project_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "link_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "title": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "opt_in_text": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Link updated."
                    }
                }
            },
            "delete": {
                "tags": [
                    "Signup Links"
                ],
                "summary": "Delete Signup Link",
                "description": "Delete a signup link.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "project_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "link_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Link deleted."
                    }
                }
            }
        },
        "/api/v1/readers/links/{slug}": {
            "get": {
                "tags": [
                    "Reader Distribution"
                ],
                "summary": "Public Campaign Details",
                "description": "Fetch public campaign info, book title, and available formats for readers.",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Campaign details.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ReaderCampaign"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Campaign link not found or expired."
                    }
                }
            }
        },
        "/api/v1/readers/links/{slug}/signup": {
            "post": {
                "tags": [
                    "Reader Distribution"
                ],
                "summary": "Reader Email Signup",
                "description": "Reader signs up with an email address to receive the book.",
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "email"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Signup successful or confirmation sent."
                    },
                    "422": {
                        "description": "Validation error."
                    }
                }
            }
        },
        "/api/v1/readers/confirm": {
            "post": {
                "tags": [
                    "Reader Distribution"
                ],
                "summary": "Confirm Reader Verification Token",
                "description": "Verify magic token sent to reader email and generate download session.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "signup_link_id",
                                    "reader_id",
                                    "expires",
                                    "signature"
                                ],
                                "properties": {
                                    "signup_link_id": {
                                        "type": "integer"
                                    },
                                    "reader_id": {
                                        "type": "integer"
                                    },
                                    "expires": {
                                        "type": "string"
                                    },
                                    "signature": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Confirmed; returns signed download URLs."
                    },
                    "400": {
                        "description": "Invalid or expired confirmation signature."
                    }
                }
            }
        },
        "/api/v1/readers/files/{file_id}/download": {
            "get": {
                "tags": [
                    "Reader Distribution"
                ],
                "summary": "Reader File Delivery",
                "description": "Secure stream of reader file using signed token or validated session.",
                "parameters": [
                    {
                        "name": "file_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "File stream."
                    },
                    "403": {
                        "description": "Unauthorized or expired download request."
                    }
                }
            }
        },
        "/api/v1/settings/newsletter": {
            "get": {
                "tags": [
                    "Newsletters & Integrations"
                ],
                "summary": "Get Newsletter Settings",
                "description": "Retrieve current active team newsletter integration status.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Newsletter configuration.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/NewsletterSettings"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/settings/newsletter/provider": {
            "put": {
                "tags": [
                    "Newsletters & Integrations"
                ],
                "summary": "Configure Newsletter Provider",
                "description": "Set provider credentials (mailcoach, mailerlite, kit).",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "provider",
                                    "api_token"
                                ],
                                "properties": {
                                    "provider": {
                                        "type": "string",
                                        "enum": [
                                            "mailcoach",
                                            "mailerlite",
                                            "kit"
                                        ]
                                    },
                                    "api_token": {
                                        "type": "string"
                                    },
                                    "api_url": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "default_list_id": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Provider saved."
                    }
                }
            },
            "delete": {
                "tags": [
                    "Newsletters & Integrations"
                ],
                "summary": "Disconnect Newsletter Provider",
                "description": "Disconnect and remove provider credentials.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Provider disconnected."
                    }
                }
            }
        },
        "/api/v1/settings/newsletter/webhook": {
            "put": {
                "tags": [
                    "Newsletters & Integrations"
                ],
                "summary": "Configure Generic Webhook",
                "description": "Configure webhook URL for reader sync events.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "webhook_url"
                                ],
                                "properties": {
                                    "webhook_url": {
                                        "type": "string",
                                        "format": "uri"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Webhook configured."
                    }
                }
            }
        },
        "/api/v1/settings/newsletter/lists": {
            "post": {
                "tags": [
                    "Newsletters & Integrations"
                ],
                "summary": "Fetch Provider Lists",
                "description": "Live-fetch email audience lists from the configured provider.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Audience lists returned."
                    }
                }
            }
        },
        "/api/v1/projects/{project_id}/newsletter": {
            "put": {
                "tags": [
                    "Newsletters & Integrations"
                ],
                "summary": "Update Project Newsletter Sync",
                "description": "Assign or update the newsletter list ID linked to this project.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "project_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "newsletter_list_id"
                                ],
                                "properties": {
                                    "newsletter_list_id": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Newsletter list configured."
                    }
                }
            }
        },
        "/api/v1/logs": {
            "get": {
                "tags": [
                    "Telemetry & Billing"
                ],
                "summary": "Fetch Team Audit Logs",
                "description": "Fetch chronological team audit logs and events.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of team events."
                    }
                }
            }
        },
        "/api/v1/dashboard/metrics": {
            "get": {
                "tags": [
                    "Telemetry & Billing"
                ],
                "summary": "Get Dashboard Metrics",
                "description": "Aggregate reader downloads, signups, and link conversion counts.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Metrics summary.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/TelemetryMetrics"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/billing": {
            "get": {
                "tags": [
                    "Telemetry & Billing"
                ],
                "summary": "Get Billing Status",
                "description": "Retrieve author team subscription status, active offer, and tier quotas.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Billing status details."
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "Sanctum API Token",
                "description": "Provide your Personal Access Token in the Authorization header: `Bearer <token>`"
            }
        },
        "schemas": {
            "TokenResponse": {
                "type": "object",
                "properties": {
                    "token": {
                        "type": "string",
                        "example": "1|abcdef1234567890"
                    },
                    "token_id": {
                        "type": "integer",
                        "example": 1
                    },
                    "name": {
                        "type": "string",
                        "example": "CLI Integration"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "DeviceCodeResponse": {
                "type": "object",
                "properties": {
                    "device_code": {
                        "type": "string",
                        "example": "gm4x..."
                    },
                    "user_code": {
                        "type": "string",
                        "example": "WDJB-MJHT"
                    },
                    "verification_uri": {
                        "type": "string",
                        "example": "https://bookbeam.app/device"
                    },
                    "verification_uri_complete": {
                        "type": "string",
                        "example": "https://bookbeam.app/device?user_code=WDJB-MJHT"
                    },
                    "expires_in": {
                        "type": "integer",
                        "example": 900
                    },
                    "interval": {
                        "type": "integer",
                        "example": 5
                    }
                }
            },
            "DeviceTokenResponse": {
                "type": "object",
                "properties": {
                    "access_token": {
                        "type": "string",
                        "example": "1|abcdef1234567890"
                    },
                    "token_type": {
                        "type": "string",
                        "example": "Bearer"
                    },
                    "token_id": {
                        "type": "integer",
                        "example": 1
                    },
                    "team_id": {
                        "type": "integer",
                        "example": 1
                    }
                }
            },
            "Project": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "team_id": {
                        "type": "integer",
                        "example": 1
                    },
                    "title": {
                        "type": "string",
                        "example": "My Debut Novel"
                    },
                    "description": {
                        "type": "string",
                        "nullable": true,
                        "example": "A gripping thriller"
                    },
                    "cover_image_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "newsletter_list_id": {
                        "type": "string",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "BookFile": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 10
                    },
                    "book_project_id": {
                        "type": "integer",
                        "example": 1
                    },
                    "format": {
                        "type": "string",
                        "example": "epub"
                    },
                    "filename": {
                        "type": "string",
                        "example": "my-debut-novel.epub"
                    },
                    "file_size": {
                        "type": "integer",
                        "example": 1048576
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "SignupLink": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 5
                    },
                    "book_project_id": {
                        "type": "integer",
                        "example": 1
                    },
                    "slug": {
                        "type": "string",
                        "example": "free-sample-chapter"
                    },
                    "title": {
                        "type": "string",
                        "nullable": true,
                        "example": "Free Prequel Novella"
                    },
                    "opt_in_text": {
                        "type": "string",
                        "nullable": true,
                        "example": "Join my reader newsletter"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "ReaderCampaign": {
                "type": "object",
                "properties": {
                    "slug": {
                        "type": "string",
                        "example": "free-sample-chapter"
                    },
                    "title": {
                        "type": "string",
                        "example": "Free Prequel Novella"
                    },
                    "opt_in_text": {
                        "type": "string",
                        "nullable": true
                    },
                    "project": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "integer"
                            },
                            "title": {
                                "type": "string"
                            },
                            "description": {
                                "type": "string",
                                "nullable": true
                            }
                        }
                    },
                    "formats": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "example": "epub"
                        }
                    }
                }
            },
            "NewsletterSettings": {
                "type": "object",
                "properties": {
                    "provider": {
                        "type": "string",
                        "nullable": true,
                        "example": "mailerlite"
                    },
                    "webhook_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "is_configured": {
                        "type": "boolean",
                        "example": true
                    }
                }
            },
            "TelemetryMetrics": {
                "type": "object",
                "properties": {
                    "total_projects": {
                        "type": "integer",
                        "example": 4
                    },
                    "total_files": {
                        "type": "integer",
                        "example": 8
                    },
                    "total_downloads": {
                        "type": "integer",
                        "example": 142
                    },
                    "total_views": {
                        "type": "integer",
                        "example": 320
                    }
                }
            }
        }
    }
}