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

package/dist/index.d.cts

@@ -0,0 +1,1512 @@
+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"];
+            asyncapi: 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>;
+        EventEnvelope: {
+            id: string;
+            type: string;
+            /** Format: date-time */
+            created_at: string;
+            api_version: string;
+            subject: string;
+            data: {
+                [key: string]: unknown;
+            };
+        };
+        LessonPlanReadyData: {
+            /** Format: uuid */
+            plan_id: string;
+            status: components["schemas"]["PlanReadyStatus"];
+            title: string | null;
+            source_lang: string;
+            target_lang: string;
+            /** Format: int16 */
+            level: number;
+        };
+        /** @enum {string} */
+        PlanReadyStatus: "complete" | "partial";
+        LessonPlanFailedData: {
+            /** Format: uuid */
+            plan_id: string;
+            reason: components["schemas"]["PlanFailReason"];
+        };
+        /** @enum {string} */
+        PlanFailReason: "generation_failed" | "timed_out";
+        UsageThresholdReachedData: {
+            scope: components["schemas"]["ThresholdScope"];
+            /** @enum {integer} */
+            threshold_pct: 50 | 70 | 90 | 100;
+            month: string;
+            client_id?: string | null;
+        };
+        /** @enum {string} */
+        ThresholdScope: "account" | "client";
+        WebhookTestData: Record<string, never>;
+        AppInstalledData: {
+            client_id: string;
+            /** Format: uuid */
+            install_id: string;
+            context: components["schemas"]["AppContextSlice"][];
+            tutor_note: boolean;
+        };
+        AppUninstalledData: {
+            client_id: string;
+            /** Format: uuid */
+            install_id: string;
+        };
+        /** @enum {string} */
+        AppContextSlice: "languages" | "plan_summary" | "review_due" | "tutor_topic";
+        EventPage: {
+            items: components["schemas"]["EventEnvelope"][];
+            next_cursor: string;
+            has_more: boolean;
+        };
+        WorldContextChanged: {
+            scene: string;
+            npc?: components["schemas"]["Npc"] | null;
+            source_lang: string;
+            target_lang: string;
+            /** Format: uint8 */
+            level: number;
+            tags?: string[];
+            generate?: boolean | null;
+        };
+        WorldPracticeRequested: {
+            topic: string;
+            source_lang: string;
+            target_lang: string;
+            /** Format: uint8 */
+            level: number;
+            tags?: string[];
+            generate?: boolean | null;
+        };
+        Npc: {
+            name: string;
+            persona?: string | null;
+        };
+        InboundEventAccepted: {
+            id: string;
+            type: string;
+            /** Format: date-time */
+            created_at: string;
+            reaction?: components["schemas"]["ReactionReport"] | null;
+        };
+        ReactionReport: {
+            status: components["schemas"]["ReactionStatus"];
+            /** Format: uuid */
+            plan_id?: string | null;
+            /** @description The plan's status when the event was accepted. Only `generating` promises that `lesson_plan.ready` or `lesson_plan.failed` will follow. Any other value is a plan served from the library, which you can read now with `GET /v1/lesson-plans/{id}`. */
+            plan_status?: components["schemas"]["PlanStatus"] | null;
+            code?: string | null;
+            error?: string | null;
+        };
+        /** @enum {string} */
+        ReactionStatus: "started" | "refused" | "failed";
+        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"];
+        StreamEventsEventEvent: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "event";
+            data: components["schemas"]["EventEnvelope"];
+        };
+        StreamEventsEventDone: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "done";
+            data: components["schemas"]["Done"];
+        };
+        StreamEventsEventError: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            event: "error";
+            data: components["schemas"]["StreamError"];
+        };
+        StreamEventsEvent: components["schemas"]["StreamEventsEventEvent"] | components["schemas"]["StreamEventsEventDone"] | components["schemas"]["StreamEventsEventError"];
+    };
+    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 `api_version_discontinued`: this request's API version has been discontinued. `cursor_expired`: the cursor is older than 30 days; start again without one. */
+        Gone: {
+            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;
+        /** @description Where to continue from: an earlier page's `next_cursor`, or a stream event's `id:`. A cursor older than 30 days answers `410` with code `cursor_expired`. */
+        EventCursor: string;
+        /** @description Where to begin without a cursor: `latest` for events from now on, or `oldest` for every event still kept. */
+        EventStart: "latest" | "oldest";
+        /** @description Only these event types, comma-separated. Without it, every type your token's scopes can read. */
+        EventTypes: string[];
+        /** @description The most events one page returns, from 1 to 100. */
+        EventLimit: number;
+        /** @description The `id:` of the last event you received. It takes precedence over `cursor` and `start`. */
+        LastEventId: string;
+        /** @description A value you choose for each event and reuse when you retry it: 1 to 255 visible ASCII characters, such as a UUID. A retry with the same key gets the first answer back and is not billed again, even if its body differs. Without a valid key the request answers `400` with code `idempotency_key_required`. */
+        IdempotencyKey: 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"];
+        };
+    };
+    listEvents: {
+        parameters: {
+            query?: {
+                /** @description Where to continue from: an earlier page's `next_cursor`, or a stream event's `id:`. A cursor older than 30 days answers `410` with code `cursor_expired`. */
+                cursor?: components["parameters"]["EventCursor"];
+                /** @description Where to begin without a cursor: `latest` for events from now on, or `oldest` for every event still kept. */
+                start?: components["parameters"]["EventStart"];
+                /** @description Only these event types, comma-separated. Without it, every type your token's scopes can read. */
+                types?: components["parameters"]["EventTypes"];
+                /** @description The most events one page returns, from 1 to 100. */
+                limit?: components["parameters"]["EventLimit"];
+            };
+            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 A page of events and the cursor to continue from */
+            200: {
+                headers: {
+                    "Lingara-Version": components["headers"]["LingaraVersion"];
+                    Deprecation: components["headers"]["Deprecation"];
+                    Sunset: components["headers"]["Sunset"];
+                    Link: components["headers"]["Link"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "items": [
+                     *         {
+                     *           "id": "lgr_evt_4f2a9c1e7b3d4e5f8a9b0c1d2e3f4a5b",
+                     *           "type": "lesson_plan.ready",
+                     *           "created_at": "2026-10-01T09:12:44Z",
+                     *           "api_version": "2026-09-equipped-boxfish",
+                     *           "subject": "lgr_sub_0f1e2d3c4b5a69788796a5b4c3d2e1f0",
+                     *           "data": {
+                     *             "plan_id": "3f1c2a9e-5b7d-4e21-9a0c-6d8e4f2b1a37",
+                     *             "status": "complete",
+                     *             "title": "At the night market",
+                     *             "source_lang": "en",
+                     *             "target_lang": "zh",
+                     *             "level": 2
+                     *           }
+                     *         }
+                     *       ],
+                     *       "next_cursor": "djEuNzQ0MTIuOTkxLjE3OTAyNDk1NjQ",
+                     *       "has_more": false
+                     *     }
+                     */
+                    "application/json": components["schemas"]["EventPage"];
+                };
+            };
+            410: components["responses"]["Gone"];
+            503: components["responses"]["Unavailable"];
+            "4XX": components["responses"]["Error"];
+            "5XX": components["responses"]["Error"];
+        };
+    };
+    sendEvent: {
+        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"];
+                /** @description A value you choose for each event and reuse when you retry it: 1 to 255 visible ASCII characters, such as a UUID. A retry with the same key gets the first answer back and is not billed again, even if its body differs. Without a valid key the request answers `400` with code `idempotency_key_required`. */
+                "Idempotency-Key": components["parameters"]["IdempotencyKey"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": Record<string, never>;
+            };
+        };
+        responses: {
+            /** @description The event is recorded */
+            202: {
+                headers: {
+                    "Lingara-Version": components["headers"]["LingaraVersion"];
+                    Deprecation: components["headers"]["Deprecation"];
+                    Sunset: components["headers"]["Sunset"];
+                    Link: components["headers"]["Link"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "id": "lgr_evt_4f2a9c1e7b3d4e5f8a9b0c1d2e3f4a5b",
+                     *       "type": "world.context_changed",
+                     *       "created_at": "2026-10-01T09:12:44Z",
+                     *       "reaction": {
+                     *         "status": "started",
+                     *         "plan_id": "3f1c2a9e-5b7d-4e21-9a0c-6d8e4f2b1a37",
+                     *         "plan_status": "generating"
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["InboundEventAccepted"];
+                };
+            };
+            402: components["responses"]["PaymentRequired"];
+            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"];
+        };
+    };
+    getAsyncApiDocument: {
+        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 AsyncAPI 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"
+                     *       },
+                     *       "asyncapi": {
+                     *         "url": "/v1/asyncapi.json",
+                     *         "sha256": null
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["VersionDetail"];
+                };
+            };
+            410: components["responses"]["VersionDiscontinued"];
+            503: components["responses"]["Unavailable"];
+            "4XX": components["responses"]["Error"];
+            "5XX": components["responses"]["Error"];
+        };
+    };
+}
+
+type Schemas$1 = components["schemas"];
+/** The envelope every event carries, with its type and its typed `data`. */
+interface EventOf<T extends string, D> {
+    readonly id: string;
+    readonly type: T;
+    readonly createdAt: string;
+    readonly apiVersion: string;
+    readonly subject: string;
+    readonly data: D;
+}
+/** `lesson_plan.ready`. */
+type LessonPlanReady = EventOf<"lesson_plan.ready", Schemas$1["LessonPlanReadyData"]>;
+/** `lesson_plan.failed`. */
+type LessonPlanFailed = EventOf<"lesson_plan.failed", Schemas$1["LessonPlanFailedData"]>;
+/** `usage.threshold_reached`. */
+type UsageThresholdReached = EventOf<"usage.threshold_reached", Schemas$1["UsageThresholdReachedData"]>;
+/** `webhook.test`. */
+type WebhookTest = EventOf<"webhook.test", Schemas$1["WebhookTestData"]>;
+/** `app.installed`. */
+type AppInstalled = EventOf<"app.installed", Schemas$1["AppInstalledData"]>;
+/** `app.uninstalled`. */
+type AppUninstalled = EventOf<"app.uninstalled", Schemas$1["AppUninstalledData"]>;
+/**
+ * An event type this library does not know: the catalogue is additive, so a
+ * newer type than the library is this, never an error. Acknowledge it (and
+ * log it), or the sender keeps retrying it.
+ */
+declare class UnknownEvent implements EventOf<string, unknown> {
+    #private;
+    static [Symbol.hasInstance](value: unknown): value is UnknownEvent;
+    readonly id: string;
+    readonly type: string;
+    readonly createdAt: string;
+    readonly apiVersion: string;
+    readonly subject: string;
+    /** The raw JSON value. */
+    readonly data: unknown;
+    constructor(fields: EventOf<string, unknown>);
+}
+/** Every outbound event, discriminated on `type`; `instanceof UnknownEvent` first. */
+type Event = LessonPlanReady | LessonPlanFailed | UsageThresholdReached | WebhookTest | AppInstalled | AppUninstalled | UnknownEvent;
+/** An event your game sends with `sendEvent`, serialised as `{type, data}`. */
+type InboundEvent = {
+    readonly type: "world.context_changed";
+    readonly data: Schemas$1["WorldContextChanged"];
+} | {
+    readonly type: "world.practice_requested";
+    readonly data: Schemas$1["WorldPracticeRequested"];
+};
+/** One constructor per inbound type, named after its `data` model. */
+declare const InboundEvent: {
+    /** `world.context_changed`. */
+    readonly worldContextChanged: (data: Schemas$1["WorldContextChanged"]) => InboundEvent;
+    /** `world.practice_requested`. */
+    readonly worldPracticeRequested: (data: Schemas$1["WorldPracticeRequested"]) => InboundEvent;
+};
+/**
+ * One event from its JSON (text, or an already-decoded value). A known type
+ * is its arm; an unknown type is `UnknownEvent`. Throws
+ * `TransportError{kind: "malformed_event"}` for anything that is not an
+ * envelope, or a known type whose `data` does not decode.
+ */
+declare function parseEvent(json: unknown): Event;
+
+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 StreamEventsEvent = Schemas["StreamEventsEvent"];
+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"];
+type EventEnvelope = Schemas["EventEnvelope"];
+type EventPage = Schemas["EventPage"];
+type LessonPlanReadyData = Schemas["LessonPlanReadyData"];
+type LessonPlanFailedData = Schemas["LessonPlanFailedData"];
+type UsageThresholdReachedData = Schemas["UsageThresholdReachedData"];
+type WebhookTestData = Schemas["WebhookTestData"];
+type AppInstalledData = Schemas["AppInstalledData"];
+type AppUninstalledData = Schemas["AppUninstalledData"];
+type WorldContextChanged = Schemas["WorldContextChanged"];
+type WorldPracticeRequested = Schemas["WorldPracticeRequested"];
+type Npc = Schemas["Npc"];
+type InboundEventAccepted = Schemas["InboundEventAccepted"];
+type ReactionReport = Schemas["ReactionReport"];
+
+/** Where a feed or a tail starts, and which types it carries. */
+interface EventsParams {
+    /** An earlier `cursor` (a page's `next_cursor`, or a stream `id:`). */
+    cursor?: string | undefined;
+    /** Without a `cursor`: `"latest"` (the server's default) or `"oldest"`. */
+    start?: "latest" | "oldest" | undefined;
+    /** Only these types. */
+    types?: readonly string[] | undefined;
+}
+/** `listEvents`' query: one page. */
+interface ListEventsParams extends EventsParams {
+    /** 1–100; the server's default is 50. */
+    limit?: number | undefined;
+}
+/** Fetches one page. */
+type PageSource = (query: ListEventsParams) => Promise<EventPage>;
+/**
+ * Every event from `cursor` (or `start`) to where the feed is caught up.
+ * `for await` it, then save `cursor` and call `events({ cursor })` again
+ * later, or hand it to `tailEvents`.
+ */
+declare class EventFeed implements AsyncIterableIterator<Event> {
+    #private;
+    constructor(params: EventsParams, page: PageSource);
+    /**
+     * Where to resume: once a page's last item has been yielded (or the page
+     * was empty), that page's `next_cursor`; before the first page, the
+     * caller's `cursor`.
+     */
+    get cursor(): string | undefined;
+    [Symbol.asyncIterator](): this;
+    next(): Promise<IteratorResult<Event>>;
+    return(): Promise<IteratorResult<Event>>;
+}
+
+/** 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>;
+
+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;
+    /** Consecutive failed reopens before `tailEvents` raises the last (CONTRACT.md K5a). Default 8. */
+    tailMaxFailures?: 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;
+}
+
+interface SendEventOptions extends CallOptions {
+    /**
+     * Sent unchanged as `Idempotency-Key`. Supply your own when you may resend
+     * after a crash: a generated key is gone once the call returns. A reused
+     * key returns the first answer, whatever the body.
+     */
+    idempotencyKey?: string;
+}
+
+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";
+        };
+    };
+    readonly streamEvents: {
+        readonly method: "GET";
+        readonly path: "/v1/events/stream";
+        readonly requestBody: null;
+        readonly union: "StreamEventsEvent";
+        readonly events: readonly ["event", "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>;
+    /**
+     * The last `id:` the stream has carried, as of the frame last handled
+     * (CONTRACT.md K5, Parsing). Only the tail reads it (K5a).
+     */
+    get lastEventId(): 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>;
+}
+
+interface EventTailInit {
+    /** One connection: the raw operation, sent with `Last-Event-ID` when given and without K4's retries. */
+    open: (lastEventId: string | undefined, signal: AbortSignal) => EventStream<StreamEventsEvent>;
+    cursor: string | undefined;
+    sleeper: Sleeper;
+    retryAfterCapSeconds: number;
+    maxFailures: number;
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Live events from `cursor`, reconnecting after every ending. `for await` it;
+ * `break` or the signal ends it. `cursor` is the `id:` of the last frame
+ * that carried one, an event's or a `done`'s.
+ */
+declare class EventTail implements AsyncIterableIterator<Event> {
+    #private;
+    constructor(init: EventTailInit);
+    /** Where to resume: hand it to `tailEvents` or `events` later. */
+    get cursor(): string | undefined;
+    [Symbol.asyncIterator](): this;
+    next(): Promise<IteratorResult<Event>>;
+    return(): Promise<IteratorResult<Event>>;
+    /** Ends the tail and closes the connection. Idempotent. */
+    close(): Promise<void>;
+}
+
+/** 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"] extends {
+    200: {
+        content: {
+            "application/json": infer T;
+        };
+    };
+} ? T : never;
+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>;
+    /** One connection under K5; `tailEvents` is the one that reconnects. */
+    streamEvents(params?: EventsParams & {
+        lastEventId?: string;
+    }, options?: CallOptions): EventStream<StreamEventsEvent>;
+    /** Every event from `cursor` (or `start`) to where the feed is caught up; never polls. */
+    events(params?: EventsParams, options?: CallOptions): EventFeed;
+    /** Live events, reconnecting from `cursor` after every ending (CONTRACT.md K5a). */
+    tailEvents(params?: EventsParams, options?: CallOptions): EventTail;
+    /** `{type, data}` with one `Idempotency-Key` across K4's attempts; the `202` body. */
+    sendEvent(event: InboundEvent, options?: SendEventOptions): Promise<WithServedVersion<InboundEventAccepted>>;
+    getLessonPlan(params: {
+        id: string;
+    }, options?: CallOptions): Promise<WithServedVersion<JsonOk<"getLessonPlan">>>;
+    getUsage(options?: CallOptions): Promise<WithServedVersion<JsonOk<"getUsage">>>;
+    /** One page of events; `events()` walks them. */
+    listEvents(params?: ListEventsParams, options?: CallOptions): Promise<WithServedVersion<JsonOk<"listEvents">>>;
+    getOpenApiDocument(options?: CallOptions): Promise<WithServedVersion<JsonOk<"getOpenApiDocument">>>;
+    getAsyncApiDocument(options?: CallOptions): Promise<WithServedVersion<JsonOk<"getAsyncApiDocument">>>;
+    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;
+}
+
+type WebhookVerificationReason = "missing_header" | "malformed_header" | "timestamp_too_old" | "timestamp_too_new" | "no_matching_signature" | "malformed_payload";
+/**
+ * A webhook that failed verification. Deliberately not a `LingaraError`: a
+ * catch around API calls must not also swallow a forged delivery. The
+ * message never carries a secret, a signature or the body.
+ */
+declare class WebhookVerificationError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    readonly reason: WebhookVerificationReason;
+    constructor(reason: WebhookVerificationReason);
+}
+/** A Fetch `Headers`, or a plain map such as Node's `req.headers`. */
+type WebhookHeaders = Headers | Readonly<Record<string, string | readonly string[] | undefined>>;
+interface WebhookOptions {
+    /** A testing seam: epoch milliseconds. */
+    clock?: Clock;
+}
+/**
+ * Verifies Lingara webhooks. Pass the raw body exactly as received, never a
+ * parsed object. Two secrets verify during a rotation.
+ */
+declare class Webhook {
+    #private;
+    constructor(secret: string | readonly string[], options?: WebhookOptions);
+    /** Signature checks, then the body parsed into an `Event` whose `id` is `webhook-id`. */
+    verify(body: string | Uint8Array, headers: WebhookHeaders): Promise<Event>;
+    /** The signature checks alone, for a signed body that is not an event (an app-kit request). */
+    verifySignature(body: string | Uint8Array, headers: WebhookHeaders): Promise<void>;
+    toJSON(): Record<string, unknown>;
+    toString(): string;
+}
+
+export { type AllowanceRow, ApiError, type AppInstalled, type AppInstalledData, type AppUninstalled, type AppUninstalledData, type CallOptions, ClientCredentials, type ClientCredentialsOptions, type Clock, type CreateLessonPlanEvent, DEFAULT_BASE_URL, DEFAULT_TOKEN_URL, type DeprecationHook, type DeprecationNotice, type Event, type EventEnvelope, EventFeed, type EventOf, type EventPage, EventStream, EventTail, type EventsParams, type FetchLike, type GenerateVocabularyEvent, InboundEvent, type InboundEventAccepted, type LessonPlan, type LessonPlanContent, type LessonPlanCreateRequest, type LessonPlanFailed, type LessonPlanFailedData, type LessonPlanReady, type LessonPlanReadyData, Lingara, LingaraError, type LingaraOptions, type ListEventsParams, MaintenanceError, type Notice, type Npc, OAuthError, type PlanPending, type PlanPhase, type PlanResult, type PlanStarted, type PlanStatus, type ReactionReport, type SendEventOptions, type SendTutorMessageEvent, type Sleeper, type StreamError, type StreamEventsEvent, type StreamLessonPlanEvent, type TokenSource, TransportError, type TransportKind, type TurnDelta, type TutorTurnRequest, UnknownEvent, type Usage, type UsageThresholdReached, type UsageThresholdReachedData, type VersionDetail, type VersionList, type VersionState, type VersionSummary, type VocabExample, type VocabItem, type VocabMeta, type VocabRequest, type VocabStarted, Webhook, type WebhookHeaders, type WebhookOptions, type WebhookTest, type WebhookTestData, WebhookVerificationError, type WebhookVerificationReason, type WithServedVersion, type WorldContextChanged, type WorldPracticeRequested, type Yielded, type components, type operations, parseEvent };