@lingara/api 0.0.0-reserved.0 → 0.1.0-alpha.6

package/dist/index.d.cts

@@ -0,0 +1,1000 @@
+declare const INSPECT: unique symbol;
+/** The base of every error this library raises. */
+declare class LingaraError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+    /** The fields a caller reads, for `JSON.stringify` and inspection. */
+    toJSON(): Record<string, unknown>;
+    [INSPECT](): string;
+    protected fields(): Record<string, unknown>;
+}
+interface ApiErrorInit {
+    status: number;
+    code: string;
+    message: string;
+    retryAfter?: number | undefined;
+    planId?: string | undefined;
+    servedVersion?: string | undefined;
+}
+/** A `/v1` refusal, or a stream's `error` event (then `status` is 200). */
+declare class ApiError extends LingaraError {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    readonly status: number;
+    readonly code: string;
+    readonly retryAfter?: number;
+    readonly planId?: string;
+    readonly servedVersion?: string;
+    constructor(init: ApiErrorInit);
+    protected fields(): Record<string, unknown>;
+}
+interface OAuthErrorInit {
+    status: number;
+    error: string;
+    description?: string | undefined;
+    retryAfter?: number | undefined;
+}
+/** A token-endpoint refusal (RFC 6749 §5.2, or `http_<status>`). */
+declare class OAuthError extends LingaraError {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    readonly status: number;
+    readonly error: string;
+    readonly description?: string;
+    readonly retryAfter?: number;
+    constructor(init: OAuthErrorInit);
+    protected fields(): Record<string, unknown>;
+}
+/** A 503 whose body is not JSON: the service is in maintenance. */
+declare class MaintenanceError extends LingaraError {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    /** The response text, at most 1 KiB. */
+    readonly body: string;
+    readonly retryAfter?: number;
+    constructor(body: string, retryAfter?: number);
+    protected fields(): Record<string, unknown>;
+}
+type TransportKind = "connect" | "tls" | "reset" | "timeout" | "stream_ended_early" | "malformed_response" | "malformed_event";
+/** No usable HTTP answer. `cause` is the runtime's error, redacted. */
+declare class TransportError extends LingaraError {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    readonly kind: TransportKind;
+    constructor(kind: TransportKind, cause?: unknown);
+    protected fields(): Record<string, unknown>;
+}
+
+interface components {
+    schemas: {
+        VocabRequest: {
+            /** Format: uint8 */
+            level: number;
+            source_lang: string;
+            target_lang: string;
+            /** Format: uint8 */
+            count?: number | null;
+        };
+        LessonPlanCreateRequest: {
+            context: string;
+            source_lang: string;
+            target_lang: string;
+            /** Format: uint8 */
+            level: number;
+        };
+        TutorTurnRequest: {
+            message: string;
+            /** @default [] */
+            history: components["schemas"]["TurnEntry"][];
+            source_lang: string;
+            target_lang: string;
+            /** Format: uint8 */
+            level?: number | null;
+            character?: string | null;
+            situation?: string | null;
+        };
+        TurnEntry: {
+            role: components["schemas"]["TurnRole"];
+            content: string;
+        };
+        /** @enum {string} */
+        TurnRole: "user" | "assistant";
+        VocabStarted: {
+            meta: components["schemas"]["VocabMeta"];
+        };
+        VocabMeta: {
+            /** Format: uint8 */
+            level: number;
+            source_lang: string;
+            target_lang: string;
+            framework: string;
+            /** Format: uint32 */
+            count: number;
+            ai_generated: boolean;
+        };
+        VocabItem: {
+            word: string;
+            pronunciation?: string | null;
+            reading?: string | null;
+            translation: string;
+            example?: components["schemas"]["VocabExample"] | null;
+            image_url?: string | null;
+        };
+        VocabExample: {
+            sentence: string;
+            translation: string;
+        };
+        LessonPlan: {
+            /** Format: uuid */
+            id: string;
+            status: components["schemas"]["PlanStatus"];
+            title?: string | null;
+            source_lang: string;
+            target_lang: string;
+            /** Format: uint8 */
+            level: number;
+            /** Format: date-time */
+            created_at: string;
+            /** Format: date-time */
+            completed_at?: string | null;
+            ai_generated: boolean;
+            content?: components["schemas"]["LessonPlanContent"] | null;
+        };
+        /** @enum {string} */
+        PlanStatus: "generating" | "partial" | "complete";
+        LessonPlanContent: {
+            introduction?: string | null;
+            learning_objectives: string[];
+            vocabulary: components["schemas"]["PlanWord"][];
+            sets: components["schemas"]["PlanSet"][];
+        };
+        PlanWord: {
+            word: string;
+            pronunciation?: string | null;
+            translation: string;
+        };
+        PlanSet: {
+            /** Format: uint8 */
+            number: number;
+            context?: string | null;
+            questions: components["schemas"]["PlanQuestion"][];
+        };
+        PlanQuestion: {
+            type: string;
+            prompt: string;
+            options?: string[] | null;
+            answer: string;
+            explanation: string;
+            hint?: string | null;
+        };
+        PlanStarted: {
+            /** Format: uuid */
+            plan_id: string;
+        };
+        PlanPhase: {
+            phase: string;
+            /** Format: uint8 */
+            attempt: number;
+        };
+        PlanResult: {
+            plan: components["schemas"]["LessonPlan"];
+        };
+        PlanPending: {
+            /** Format: uuid */
+            plan_id: string;
+            status: components["schemas"]["PlanStatus"];
+        };
+        TurnDelta: {
+            text: string;
+        };
+        Usage: {
+            allowance: components["schemas"]["AllowanceRow"][];
+            /** @description This client's calls and units since midnight UTC on the first of the month. Present only for a metered client, whose calls spend no allowance. It can trail your latest call by up to five seconds. */
+            ledger?: components["schemas"]["UsageLedger"] | null;
+        };
+        UsageLedger: {
+            /** Format: date-time */
+            since: string;
+            /** Format: uint64 */
+            calls: number;
+            /** Format: uint64 */
+            units: number;
+        };
+        AllowanceRow: {
+            feature: string;
+            window: string;
+            /** Format: uint32 */
+            limit: number;
+            /** Format: uint32 */
+            used: number;
+            /** Format: uint32 */
+            remaining: number;
+            /** Format: int64 */
+            reset_at?: number | null;
+        };
+        VersionList: {
+            current: string | null;
+            development: string | null;
+            versions: components["schemas"]["VersionSummary"][];
+        };
+        VersionSummary: {
+            id: string;
+            state: components["schemas"]["VersionState"];
+            lts: boolean;
+            /** Format: date-time */
+            minted_at: string;
+            /** Format: date-time */
+            sunset_at: string | null;
+        };
+        VersionDetail: {
+            id: string;
+            state: components["schemas"]["VersionState"];
+            lts: boolean;
+            /** Format: date-time */
+            minted_at: string;
+            /** Format: date-time */
+            sunset_at: string | null;
+            summary: string | null;
+            history: components["schemas"]["VersionHistoryEntry"][];
+            spec: components["schemas"]["VersionSpec"];
+        };
+        /** @enum {string} */
+        VersionState: "development" | "supported" | "lts" | "deprecated" | "discontinued";
+        VersionHistoryEntry: {
+            state: components["schemas"]["VersionState"];
+            /** Format: date-time */
+            at: string;
+        };
+        VersionSpec: {
+            url: string;
+            sha256: string | null;
+        };
+        Error: {
+            /** @description Why the request was refused, as a stable code to branch on: for example `insufficient_scope` (`403`), `rate_limited` (`429`) and, for a metered client, `spend_cap_reached` (`402`) and `metered_billing_inactive` (`402`). */
+            code: string;
+            error: string;
+        };
+        Notice: {
+            code: string;
+            message: string;
+        };
+        StreamError: {
+            code: string;
+            message: string;
+            /** Format: uuid */
+            plan_id?: string | null;
+        };
+        Done: Record<string, never>;
+        GenerateVocabularyEventStarted: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "started";
+            data: components["schemas"]["VocabStarted"];
+        };
+        GenerateVocabularyEventItem: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "item";
+            data: components["schemas"]["VocabItem"];
+        };
+        GenerateVocabularyEventDone: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "done";
+            data: components["schemas"]["Done"];
+        };
+        GenerateVocabularyEventError: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "error";
+            data: components["schemas"]["StreamError"];
+        };
+        GenerateVocabularyEvent: components["schemas"]["GenerateVocabularyEventStarted"] | components["schemas"]["GenerateVocabularyEventItem"] | components["schemas"]["GenerateVocabularyEventDone"] | components["schemas"]["GenerateVocabularyEventError"];
+        CreateLessonPlanEventStarted: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "started";
+            data: components["schemas"]["PlanStarted"];
+        };
+        CreateLessonPlanEventPhase: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "phase";
+            data: components["schemas"]["PlanPhase"];
+        };
+        CreateLessonPlanEventResult: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "result";
+            data: components["schemas"]["PlanResult"];
+        };
+        CreateLessonPlanEventError: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "error";
+            data: components["schemas"]["StreamError"];
+        };
+        CreateLessonPlanEvent: components["schemas"]["CreateLessonPlanEventStarted"] | components["schemas"]["CreateLessonPlanEventPhase"] | components["schemas"]["CreateLessonPlanEventResult"] | components["schemas"]["CreateLessonPlanEventError"];
+        StreamLessonPlanEventStarted: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "started";
+            data: components["schemas"]["PlanStarted"];
+        };
+        StreamLessonPlanEventPhase: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "phase";
+            data: components["schemas"]["PlanPhase"];
+        };
+        StreamLessonPlanEventResult: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "result";
+            data: components["schemas"]["PlanResult"];
+        };
+        StreamLessonPlanEventPending: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "pending";
+            data: components["schemas"]["PlanPending"];
+        };
+        StreamLessonPlanEventError: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "error";
+            data: components["schemas"]["StreamError"];
+        };
+        StreamLessonPlanEvent: components["schemas"]["StreamLessonPlanEventStarted"] | components["schemas"]["StreamLessonPlanEventPhase"] | components["schemas"]["StreamLessonPlanEventResult"] | components["schemas"]["StreamLessonPlanEventPending"] | components["schemas"]["StreamLessonPlanEventError"];
+        SendTutorMessageEventDelta: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "delta";
+            data: components["schemas"]["TurnDelta"];
+        };
+        SendTutorMessageEventNotice: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "notice";
+            data: components["schemas"]["Notice"];
+        };
+        SendTutorMessageEventDone: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "done";
+            data: components["schemas"]["Done"];
+        };
+        SendTutorMessageEventError: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "error";
+            data: components["schemas"]["StreamError"];
+        };
+        SendTutorMessageEvent: components["schemas"]["SendTutorMessageEventDelta"] | components["schemas"]["SendTutorMessageEventNotice"] | components["schemas"]["SendTutorMessageEventDone"] | components["schemas"]["SendTutorMessageEventError"];
+    };
+    responses: {
+        /** @description The request was refused. `code` says why, and `error` says it in words. */
+        Error: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+        /** @description A metered client's call was refused before it spent anything. `spend_cap_reached`: the client or its account has reached its monthly spending limit; raise the limit on the Integrations page. `metered_billing_inactive`: usage billing is not active for this account; set it up, or update the payment method, on the Integrations page. */
+        PaymentRequired: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+        /** @description The API version this request is answered under has been discontinued. Send a supported version in `Lingara-Version`, or re-pin the client. */
+        VersionDiscontinued: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+        /** @description The service is temporarily unavailable; retry after the number of seconds in `Retry-After`. During maintenance the body is plain text rather than the error envelope. */
+        Unavailable: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+                "text/plain": string;
+            };
+        };
+    };
+    parameters: {
+        PlanId: string;
+        VersionId: string;
+        /** @description The API version to answer this request under. Without it, an access token gets the version its client is pinned to, and a request with no token gets the current version. The version still in development is reached only by naming it here. An unknown version answers `400` with code `api_version_unknown`. `GET /v1/versions` lists the versions. */
+        LingaraVersion: string;
+    };
+    requestBodies: never;
+    headers: {
+        /** @description The API version this response was answered under. Absent until the first version is frozen. */
+        LingaraVersion: string;
+        /** @description When this response's API version was deprecated, as `@` followed by Unix seconds. Present only on a deprecated version. */
+        Deprecation: string;
+        /** @description The date from which this response's API version may be discontinued. Present only on a deprecated version. */
+        Sunset: string;
+        /** @description A link, with relation `deprecation`, to this API version's details. Present only on a deprecated version. */
+        Link: string;
+    };
+    pathItems: never;
+}
+interface operations {
+    getLessonPlan: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description The API version to answer this request under. Without it, an access token gets the version its client is pinned to, and a request with no token gets the current version. The version still in development is reached only by naming it here. An unknown version answers `400` with code `api_version_unknown`. `GET /v1/versions` lists the versions. */
+                "Lingara-Version"?: components["parameters"]["LingaraVersion"];
+            };
+            path: {
+                id: components["parameters"]["PlanId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The lesson plan */
+            200: {
+                headers: {
+                    "Lingara-Version": components["headers"]["LingaraVersion"];
+                    Deprecation: components["headers"]["Deprecation"];
+                    Sunset: components["headers"]["Sunset"];
+                    Link: components["headers"]["Link"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "id": "3f1c2a9e-5b7d-4e21-9a0c-6d8e4f2b1a37",
+                     *       "status": "complete",
+                     *       "title": "At the night market",
+                     *       "source_lang": "en",
+                     *       "target_lang": "zh",
+                     *       "level": 2,
+                     *       "created_at": "2026-09-23T10:00:00Z",
+                     *       "completed_at": "2026-09-23T10:00:41Z",
+                     *       "ai_generated": true,
+                     *       "content": {
+                     *         "introduction": "Order food and ask prices at a night market.",
+                     *         "learning_objectives": [
+                     *           "Ask how much something costs"
+                     *         ],
+                     *         "vocabulary": [
+                     *           {
+                     *             "word": "多少钱",
+                     *             "pronunciation": "duōshao qián",
+                     *             "translation": "how much"
+                     *           }
+                     *         ],
+                     *         "sets": [
+                     *           {
+                     *             "number": 1,
+                     *             "questions": [
+                     *               {
+                     *                 "type": "multiple_choice_word",
+                     *                 "prompt": "Which word asks for a price?",
+                     *                 "options": [
+                     *                   "多少钱",
+                     *                   "谢谢"
+                     *                 ],
+                     *                 "answer": "多少钱",
+                     *                 "explanation": "多少钱 means how much money."
+                     *               }
+                     *             ]
+                     *           }
+                     *         ]
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["LessonPlan"];
+                };
+            };
+            410: components["responses"]["VersionDiscontinued"];
+            503: components["responses"]["Unavailable"];
+            "4XX": components["responses"]["Error"];
+            "5XX": components["responses"]["Error"];
+        };
+    };
+    getUsage: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description The API version to answer this request under. Without it, an access token gets the version its client is pinned to, and a request with no token gets the current version. The version still in development is reached only by naming it here. An unknown version answers `400` with code `api_version_unknown`. `GET /v1/versions` lists the versions. */
+                "Lingara-Version"?: components["parameters"]["LingaraVersion"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Your allowance */
+            200: {
+                headers: {
+                    "Lingara-Version": components["headers"]["LingaraVersion"];
+                    Deprecation: components["headers"]["Deprecation"];
+                    Sunset: components["headers"]["Sunset"];
+                    Link: components["headers"]["Link"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "allowance": [
+                     *         {
+                     *           "feature": "vocab",
+                     *           "window": "daily",
+                     *           "limit": 50,
+                     *           "used": 12,
+                     *           "remaining": 38,
+                     *           "reset_at": 1790208000
+                     *         },
+                     *         {
+                     *           "feature": "lesson_plans",
+                     *           "window": "lifetime",
+                     *           "limit": 3,
+                     *           "used": 1,
+                     *           "remaining": 2
+                     *         }
+                     *       ]
+                     *     }
+                     */
+                    "application/json": components["schemas"]["Usage"];
+                };
+            };
+            410: components["responses"]["VersionDiscontinued"];
+            503: components["responses"]["Unavailable"];
+            "4XX": components["responses"]["Error"];
+            "5XX": components["responses"]["Error"];
+        };
+    };
+    getOpenApiDocument: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description The API version to answer this request under. Without it, an access token gets the version its client is pinned to, and a request with no token gets the current version. The version still in development is reached only by naming it here. An unknown version answers `400` with code `api_version_unknown`. `GET /v1/versions` lists the versions. */
+                "Lingara-Version"?: components["parameters"]["LingaraVersion"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The OpenAPI document */
+            200: {
+                headers: {
+                    "Lingara-Version": components["headers"]["LingaraVersion"];
+                    Deprecation: components["headers"]["Deprecation"];
+                    Sunset: components["headers"]["Sunset"];
+                    Link: components["headers"]["Link"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": Record<string, never>;
+                };
+            };
+            410: components["responses"]["VersionDiscontinued"];
+            503: components["responses"]["Unavailable"];
+            "4XX": components["responses"]["Error"];
+        };
+    };
+    listApiVersions: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description The API version to answer this request under. Without it, an access token gets the version its client is pinned to, and a request with no token gets the current version. The version still in development is reached only by naming it here. An unknown version answers `400` with code `api_version_unknown`. `GET /v1/versions` lists the versions. */
+                "Lingara-Version"?: components["parameters"]["LingaraVersion"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Every API version */
+            200: {
+                headers: {
+                    "Lingara-Version": components["headers"]["LingaraVersion"];
+                    Deprecation: components["headers"]["Deprecation"];
+                    Sunset: components["headers"]["Sunset"];
+                    Link: components["headers"]["Link"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "current": "2026-10-brave-otter",
+                     *       "development": "2026-11-quiet-lantern",
+                     *       "versions": [
+                     *         {
+                     *           "id": "2026-10-gentle-heron",
+                     *           "state": "deprecated",
+                     *           "lts": true,
+                     *           "minted_at": "2026-10-01T09:00:00Z",
+                     *           "sunset_at": "2027-03-01T00:00:00Z"
+                     *         },
+                     *         {
+                     *           "id": "2026-10-brave-otter",
+                     *           "state": "supported",
+                     *           "lts": false,
+                     *           "minted_at": "2026-10-01T09:00:05Z",
+                     *           "sunset_at": null
+                     *         },
+                     *         {
+                     *           "id": "2026-11-quiet-lantern",
+                     *           "state": "development",
+                     *           "lts": false,
+                     *           "minted_at": "2026-11-02T10:00:00Z",
+                     *           "sunset_at": null
+                     *         }
+                     *       ]
+                     *     }
+                     */
+                    "application/json": components["schemas"]["VersionList"];
+                };
+            };
+            410: components["responses"]["VersionDiscontinued"];
+            503: components["responses"]["Unavailable"];
+            "4XX": components["responses"]["Error"];
+            "5XX": components["responses"]["Error"];
+        };
+    };
+    getApiVersion: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description The API version to answer this request under. Without it, an access token gets the version its client is pinned to, and a request with no token gets the current version. The version still in development is reached only by naming it here. An unknown version answers `400` with code `api_version_unknown`. `GET /v1/versions` lists the versions. */
+                "Lingara-Version"?: components["parameters"]["LingaraVersion"];
+            };
+            path: {
+                id: components["parameters"]["VersionId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The API version */
+            200: {
+                headers: {
+                    "Lingara-Version": components["headers"]["LingaraVersion"];
+                    Deprecation: components["headers"]["Deprecation"];
+                    Sunset: components["headers"]["Sunset"];
+                    Link: components["headers"]["Link"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "id": "2026-10-brave-otter",
+                     *       "state": "supported",
+                     *       "lts": false,
+                     *       "minted_at": "2026-10-01T09:00:05Z",
+                     *       "sunset_at": null,
+                     *       "summary": "The first surface.",
+                     *       "history": [
+                     *         {
+                     *           "state": "development",
+                     *           "at": "2026-10-01T09:00:05Z"
+                     *         },
+                     *         {
+                     *           "state": "supported",
+                     *           "at": "2026-11-02T10:00:00Z"
+                     *         }
+                     *       ],
+                     *       "spec": {
+                     *         "url": "/v1/openapi.json",
+                     *         "sha256": "3b7e0c1f9a2d4e5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3"
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["VersionDetail"];
+                };
+            };
+            410: components["responses"]["VersionDiscontinued"];
+            503: components["responses"]["Unavailable"];
+            "4XX": components["responses"]["Error"];
+            "5XX": components["responses"]["Error"];
+        };
+    };
+}
+
+type Schemas = components["schemas"];
+type VocabRequest = Schemas["VocabRequest"];
+type LessonPlanCreateRequest = Schemas["LessonPlanCreateRequest"];
+type TutorTurnRequest = Schemas["TutorTurnRequest"];
+type GenerateVocabularyEvent = Schemas["GenerateVocabularyEvent"];
+type CreateLessonPlanEvent = Schemas["CreateLessonPlanEvent"];
+type StreamLessonPlanEvent = Schemas["StreamLessonPlanEvent"];
+type SendTutorMessageEvent = Schemas["SendTutorMessageEvent"];
+type VocabStarted = Schemas["VocabStarted"];
+type VocabItem = Schemas["VocabItem"];
+type VocabMeta = Schemas["VocabMeta"];
+type VocabExample = Schemas["VocabExample"];
+type PlanStarted = Schemas["PlanStarted"];
+type PlanPhase = Schemas["PlanPhase"];
+type PlanResult = Schemas["PlanResult"];
+type PlanPending = Schemas["PlanPending"];
+type TurnDelta = Schemas["TurnDelta"];
+type Notice = Schemas["Notice"];
+type StreamError = Schemas["StreamError"];
+type LessonPlan = Schemas["LessonPlan"];
+type LessonPlanContent = Schemas["LessonPlanContent"];
+type PlanStatus = Schemas["PlanStatus"];
+type Usage = Schemas["Usage"];
+type AllowanceRow = Schemas["AllowanceRow"];
+type VersionList = Schemas["VersionList"];
+type VersionDetail = Schemas["VersionDetail"];
+type VersionSummary = Schemas["VersionSummary"];
+type VersionState = Schemas["VersionState"];
+
+/** Wall-clock time, in epoch milliseconds. A testing seam. */
+interface Clock {
+    now(): number;
+}
+/**
+ * Waits `ms` milliseconds, or rejects with `signal.reason` as soon as the
+ * signal aborts. A testing seam.
+ */
+type Sleeper = (ms: number, signal?: AbortSignal) => Promise<void>;
+
+declare const STREAMS: {
+    readonly generateVocabulary: {
+        readonly method: "POST";
+        readonly path: "/v1/vocab/stream";
+        readonly requestBody: "VocabRequest";
+        readonly union: "GenerateVocabularyEvent";
+        readonly events: readonly ["started", "item", "done", "error"];
+        readonly ends: {
+            readonly done: "end";
+            readonly error: "raise";
+        };
+    };
+    readonly createLessonPlan: {
+        readonly method: "POST";
+        readonly path: "/v1/lesson-plans";
+        readonly requestBody: "LessonPlanCreateRequest";
+        readonly union: "CreateLessonPlanEvent";
+        readonly events: readonly ["started", "phase", "result", "error"];
+        readonly ends: {
+            readonly result: "yield";
+            readonly error: "raise";
+        };
+    };
+    readonly streamLessonPlan: {
+        readonly method: "GET";
+        readonly path: "/v1/lesson-plans/{id}/stream";
+        readonly requestBody: null;
+        readonly union: "StreamLessonPlanEvent";
+        readonly events: readonly ["started", "phase", "result", "pending", "error"];
+        readonly ends: {
+            readonly result: "yield";
+            readonly pending: "yield";
+            readonly error: "raise";
+        };
+    };
+    readonly sendTutorMessage: {
+        readonly method: "POST";
+        readonly path: "/v1/tutor/message";
+        readonly requestBody: "TutorTurnRequest";
+        readonly union: "SendTutorMessageEvent";
+        readonly events: readonly ["delta", "notice", "done", "error"];
+        readonly ends: {
+            readonly done: "end";
+            readonly error: "raise";
+        };
+    };
+};
+type StreamOperation = keyof typeof STREAMS;
+
+/** What a stream yields: every event but `done` and `error`. */
+type Yielded<E> = Exclude<E, {
+    event: "done";
+} | {
+    event: "error";
+}>;
+/** An opened stream: a 200 `text/event-stream` response and its echo. */
+interface OpenedStream {
+    response: Response;
+    servedVersion: string | undefined;
+}
+interface EventStreamInit {
+    operation: StreamOperation;
+    /** Sends the request (auth, retries, error mapping) under `signal`. */
+    open: (signal: AbortSignal) => Promise<OpenedStream>;
+    signal?: AbortSignal | undefined;
+    idleTimeoutMs: number;
+}
+/** A stream of events. `for await` it; `break` or `close()` ends it. */
+declare class EventStream<E extends {
+    event: string;
+}> implements AsyncIterableIterator<Yielded<E>> {
+    #private;
+    constructor(init: EventStreamInit);
+    /**
+     * The `Lingara-Version` echo. Reading it starts the request if iteration
+     * has not. Never rejects: `undefined` when the request fails or the stream
+     * closes first.
+     */
+    get servedVersion(): Promise<string | undefined>;
+    [Symbol.asyncIterator](): this;
+    next(): Promise<IteratorResult<Yielded<E>>>;
+    return(): Promise<IteratorResult<Yielded<E>>>;
+    /** Ends the stream and closes the connection. Idempotent. */
+    close(): Promise<void>;
+}
+
+type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+
+/** Where the client gets its access tokens. A caller may supply their own. */
+interface TokenSource {
+    /** An access token. `signal` abandons this caller's wait only. */
+    token(options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    /** Forgets `token` only if it is still the cached one. */
+    invalidate(token: string): void;
+}
+interface ClientCredentialsOptions {
+    clientId: string;
+    clientSecret: string;
+    /** `"basic"` (the default) is `client_secret_basic`; `"post"` is `client_secret_post`. */
+    auth?: "basic" | "post" | undefined;
+    scopes?: readonly string[] | undefined;
+    tokenUrl?: string | undefined;
+    maxAttempts?: number | undefined;
+    retryAfterCapSeconds?: number | undefined;
+    tokenRequestTimeoutMs?: number | undefined;
+    userAgentSuffix?: string | undefined;
+    /** A testing seam. */
+    clock?: Clock | undefined;
+    /** A testing seam. */
+    sleeper?: Sleeper | undefined;
+    fetch?: FetchLike | undefined;
+}
+declare const DEFAULT_TOKEN_URL = "https://api.getlingara.com/oauth/token";
+/** The OAuth 2.0 client-credentials grant against `/oauth/token`. */
+declare class ClientCredentials implements TokenSource {
+    #private;
+    readonly clientId: string;
+    constructor(options: ClientCredentialsOptions);
+    token(options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    invalidate(token: string): void;
+    /** The cached access token, raw. The one accessor that does not redact. */
+    exposeToken(): string | undefined;
+    toJSON(): Record<string, unknown>;
+    [INSPECT](): string;
+    toString(): string;
+}
+
+/** What a response under a deprecated version says about it. */
+interface DeprecationNotice {
+    /** The `Lingara-Version` echo. */
+    version?: string;
+    /** `Deprecation`, parsed from `@<unix seconds>`; absent when unparseable. */
+    deprecatedAt?: Date;
+    /** `Sunset`, parsed from an IMF-fixdate; absent when unparseable or missing. */
+    sunsetAt?: Date;
+    /** `Link`: the raw value, and its target resolved against the request URL. */
+    link?: {
+        raw: string;
+        url?: URL;
+    };
+    /** The raw `Deprecation` header. */
+    deprecation: string;
+    /** The raw `Sunset` header. */
+    sunset?: string;
+}
+type DeprecationHook = (notice: DeprecationNotice) => void;
+
+interface LingaraOptions {
+    clientId?: string;
+    clientSecret?: string;
+    /** `"basic"` (the default) or `"post"` (`client_secret_post`). */
+    auth?: "basic" | "post";
+    scopes?: readonly string[];
+    /** Replaces the built-in client-credentials source. Not with `clientSecret`. */
+    tokenSource?: TokenSource;
+    baseUrl?: string;
+    tokenUrl?: string;
+    /** Pins every `/v1` request to this API version. */
+    version?: string;
+    /** Called once per response under a deprecated version. */
+    onDeprecation?: DeprecationHook;
+    /** Tries per HTTP request; `1` turns retries off. Default 3. */
+    maxAttempts?: number;
+    /** Default 60. */
+    retryAfterCapSeconds?: number;
+    /** Default 120 000. */
+    streamIdleTimeoutMs?: number;
+    /** Default 30 000. */
+    tokenRequestTimeoutMs?: number;
+    /** Appended to the `User-Agent` after one space. */
+    userAgentSuffix?: string;
+    /** A testing seam: epoch milliseconds. */
+    clock?: Clock;
+    /** A testing seam. */
+    sleeper?: Sleeper;
+    /** Defaults to `globalThis.fetch`. */
+    fetch?: FetchLike;
+}
+interface CallOptions {
+    signal?: AbortSignal;
+}
+/** A JSON result, with the `Lingara-Version` echo beside it (non-enumerable). */
+type WithServedVersion<T> = T & {
+    readonly servedVersion?: string;
+};
+type JsonOk<Op extends keyof operations> = operations[Op]["responses"][200]["content"]["application/json"];
+declare const DEFAULT_BASE_URL = "https://api.getlingara.com";
+/** The Lingara API. Server-side only: Node, Deno and Bun. */
+declare class Lingara {
+    #private;
+    readonly clientId: string | undefined;
+    constructor(options?: LingaraOptions);
+    /** The token source in use, if the client has credentials. */
+    get tokenSource(): TokenSource | undefined;
+    generateVocabulary(body: VocabRequest, options?: CallOptions): EventStream<GenerateVocabularyEvent>;
+    createLessonPlan(body: LessonPlanCreateRequest, options?: CallOptions): EventStream<CreateLessonPlanEvent>;
+    streamLessonPlan(params: {
+        id: string;
+    }, options?: CallOptions): EventStream<StreamLessonPlanEvent>;
+    sendTutorMessage(body: TutorTurnRequest, options?: CallOptions): EventStream<SendTutorMessageEvent>;
+    getLessonPlan(params: {
+        id: string;
+    }, options?: CallOptions): Promise<WithServedVersion<JsonOk<"getLessonPlan">>>;
+    getUsage(options?: CallOptions): Promise<WithServedVersion<JsonOk<"getUsage">>>;
+    getOpenApiDocument(options?: CallOptions): Promise<WithServedVersion<JsonOk<"getOpenApiDocument">>>;
+    listApiVersions(options?: CallOptions): Promise<WithServedVersion<JsonOk<"listApiVersions">>>;
+    getApiVersion(params: {
+        id: string;
+    }, options?: CallOptions): Promise<WithServedVersion<JsonOk<"getApiVersion">>>;
+    toJSON(): Record<string, unknown>;
+    [INSPECT](): string;
+    toString(): string;
+}
+
+export { type AllowanceRow, ApiError, type CallOptions, ClientCredentials, type ClientCredentialsOptions, type Clock, type CreateLessonPlanEvent, DEFAULT_BASE_URL, DEFAULT_TOKEN_URL, type DeprecationHook, type DeprecationNotice, EventStream, type FetchLike, type GenerateVocabularyEvent, type LessonPlan, type LessonPlanContent, type LessonPlanCreateRequest, Lingara, LingaraError, type LingaraOptions, MaintenanceError, type Notice, OAuthError, type PlanPending, type PlanPhase, type PlanResult, type PlanStarted, type PlanStatus, type SendTutorMessageEvent, type Sleeper, type StreamError, type StreamLessonPlanEvent, type TokenSource, TransportError, type TransportKind, type TurnDelta, type TutorTurnRequest, type Usage, type VersionDetail, type VersionList, type VersionState, type VersionSummary, type VocabExample, type VocabItem, type VocabMeta, type VocabRequest, type VocabStarted, type WithServedVersion, type Yielded, type components, type operations };