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

package/dist/index.mjs

@@ -0,0 +1,1368 @@
+// src/errors.ts
+var REDACTED = "[REDACTED]";
+var INSPECT = /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom");
+function brand(name) {
+  return /* @__PURE__ */ Symbol.for(`lingara.error.${name}`);
+}
+function mark(target, name) {
+  Object.defineProperty(target, brand(name), { value: true, enumerable: false });
+}
+function hasBrand(value, name) {
+  return typeof value === "object" && value !== null && value[brand(name)] === true;
+}
+var LingaraError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return hasBrand(value, "LingaraError");
+  }
+  constructor(message, options) {
+    super(message, options);
+    this.name = new.target.name;
+    mark(this, "LingaraError");
+  }
+  /** The fields a caller reads, for `JSON.stringify` and inspection. */
+  toJSON() {
+    return { name: this.name, message: this.message, ...this.fields() };
+  }
+  [INSPECT]() {
+    return `${this.name}: ${this.message} ${JSON.stringify(this.fields())}`;
+  }
+  fields() {
+    return {};
+  }
+};
+var ApiError = class extends LingaraError {
+  static [Symbol.hasInstance](value) {
+    return hasBrand(value, "ApiError");
+  }
+  status;
+  code;
+  retryAfter;
+  planId;
+  servedVersion;
+  constructor(init) {
+    super(init.message);
+    mark(this, "ApiError");
+    this.status = init.status;
+    this.code = init.code;
+    if (init.retryAfter !== void 0) this.retryAfter = init.retryAfter;
+    if (init.planId !== void 0) this.planId = init.planId;
+    if (init.servedVersion !== void 0) this.servedVersion = init.servedVersion;
+  }
+  fields() {
+    const { status, code, retryAfter, planId, servedVersion } = this;
+    return { status, code, retryAfter, planId, servedVersion };
+  }
+};
+var OAuthError = class extends LingaraError {
+  static [Symbol.hasInstance](value) {
+    return hasBrand(value, "OAuthError");
+  }
+  status;
+  error;
+  description;
+  retryAfter;
+  constructor(init) {
+    super(init.description ? `${init.error}: ${init.description}` : init.error);
+    mark(this, "OAuthError");
+    this.status = init.status;
+    this.error = init.error;
+    if (init.description !== void 0) this.description = init.description;
+    if (init.retryAfter !== void 0) this.retryAfter = init.retryAfter;
+  }
+  fields() {
+    const { status, error, description, retryAfter } = this;
+    return { status, error, description, retryAfter };
+  }
+};
+var MaintenanceError = class extends LingaraError {
+  static [Symbol.hasInstance](value) {
+    return hasBrand(value, "MaintenanceError");
+  }
+  /** The response text, at most 1 KiB. */
+  body;
+  retryAfter;
+  constructor(body, retryAfter) {
+    super("the Lingara API is under maintenance");
+    mark(this, "MaintenanceError");
+    this.body = body;
+    if (retryAfter !== void 0) this.retryAfter = retryAfter;
+  }
+  fields() {
+    return { body: this.body, retryAfter: this.retryAfter };
+  }
+};
+var TransportError = class extends LingaraError {
+  static [Symbol.hasInstance](value) {
+    return hasBrand(value, "TransportError");
+  }
+  kind;
+  constructor(kind, cause) {
+    super(`transport failure: ${kind}`, cause === void 0 ? void 0 : { cause });
+    mark(this, "TransportError");
+    this.kind = kind;
+  }
+  fields() {
+    return { kind: this.kind };
+  }
+};
+var MAINTENANCE_BODY_BYTES = 1024;
+async function errorFromResponse(res, ctx) {
+  const text = await res.text().catch(() => "");
+  if (res.status === 503 && !isJson(res)) {
+    return new MaintenanceError(truncateUtf8(text, MAINTENANCE_BODY_BYTES), ctx.retryAfter);
+  }
+  const body = parseObject(text);
+  return ctx.endpoint === "token" ? oauthError(res.status, body, ctx) : apiError(res.status, body, ctx);
+}
+function apiError(status, body, ctx) {
+  const code = body?.["code"];
+  const message = body?.["error"];
+  const envelope2 = typeof code === "string" && typeof message === "string";
+  return new ApiError({
+    status,
+    code: envelope2 ? code : `http_${status}`,
+    message: envelope2 ? message : `HTTP ${status}`,
+    retryAfter: ctx.retryAfter,
+    servedVersion: ctx.servedVersion
+  });
+}
+function oauthError(status, body, ctx) {
+  const error = body?.["error"];
+  if (typeof error !== "string") return new OAuthError({ status, error: `http_${status}`, retryAfter: ctx.retryAfter });
+  const description = body?.["error_description"];
+  return new OAuthError({
+    status,
+    error,
+    description: typeof description === "string" ? description : void 0,
+    retryAfter: ctx.retryAfter
+  });
+}
+function mediaType(res) {
+  return (res.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+}
+function isJson(res) {
+  const type = mediaType(res);
+  return type === "application/json" || type.endsWith("+json");
+}
+function parseObject(text) {
+  try {
+    const value = JSON.parse(text);
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function truncateUtf8(text, maxBytes) {
+  const bytes = new TextEncoder().encode(text);
+  if (bytes.length <= maxBytes) return text;
+  return new TextDecoder().decode(bytes.slice(0, maxBytes)).replace(/�$/, "");
+}
+var TLS = /cert|ssl|tls|unable_to_verify/i;
+var CONNECT = /refused|enotfound|eai_again|dns/i;
+var RESET = /reset|epipe|socket|closed|aborted/i;
+function transportKind(err, phase) {
+  const text = describe(err).join("\n");
+  if (TLS.test(text)) return "tls";
+  if (CONNECT.test(text)) return "connect";
+  if (RESET.test(text)) return "reset";
+  return phase === "fetch" ? "connect" : "reset";
+}
+function describe(err, depth = 0) {
+  if (typeof err !== "object" || err === null || depth > 4) return [];
+  const e = err;
+  const own = [e.code, e.message].filter((v) => typeof v === "string");
+  return [...own, ...describe(e.cause, depth + 1)];
+}
+function redactCause(err, secrets, depth = 0) {
+  const live = secrets.filter((s) => typeof s === "string" && s.length > 0);
+  if (typeof err === "string") return scrub(err, live);
+  if (typeof err !== "object" || err === null || depth > 4) return err;
+  return redactObject(err, live, depth);
+}
+function redactObject(e, secrets, depth) {
+  const copy = new Error(scrub(String(e.message ?? ""), secrets));
+  copy.name = typeof e.name === "string" ? e.name : "Error";
+  if (typeof e.stack === "string") copy.stack = scrub(e.stack, secrets);
+  if (typeof e.code === "string") Object.assign(copy, { code: e.code });
+  if (e.cause !== void 0) copy.cause = redactCause(e.cause, secrets, depth + 1);
+  return copy;
+}
+function scrub(text, secrets) {
+  return secrets.reduce((acc, s) => acc.split(s).join(REDACTED), text);
+}
+
+// src/generated/events.ts
+var UNKNOWN = /* @__PURE__ */ Symbol.for("lingara.event.UnknownEvent");
+var UnknownEvent = class {
+  static [Symbol.hasInstance](value) {
+    return typeof value === "object" && value !== null && value[UNKNOWN] === true;
+  }
+  // Nominal, so a known arm is never mistaken for this one by the compiler.
+  #unknown = true;
+  id;
+  type;
+  createdAt;
+  apiVersion;
+  subject;
+  /** The raw JSON value. */
+  data;
+  constructor(fields) {
+    Object.defineProperty(this, UNKNOWN, { value: this.#unknown, enumerable: false });
+    this.id = fields.id;
+    this.type = fields.type;
+    this.createdAt = fields.createdAt;
+    this.apiVersion = fields.apiVersion;
+    this.subject = fields.subject;
+    this.data = fields.data;
+  }
+};
+var InboundEvent = {
+  /** `world.context_changed`. */
+  worldContextChanged: (data) => ({ type: "world.context_changed", data }),
+  /** `world.practice_requested`. */
+  worldPracticeRequested: (data) => ({ type: "world.practice_requested", data })
+};
+var SHAPES = {
+  "lesson_plan.ready": { "type": ["object"], "properties": { "plan_id": { "type": ["string"] }, "status": { "type": ["string"], "enum": ["complete", "partial"] }, "title": { "type": ["string", "null"] }, "source_lang": { "type": ["string"] }, "target_lang": { "type": ["string"] }, "level": { "type": ["integer"] } }, "required": ["plan_id", "status", "title", "source_lang", "target_lang", "level"] },
+  "lesson_plan.failed": { "type": ["object"], "properties": { "plan_id": { "type": ["string"] }, "reason": { "type": ["string"], "enum": ["generation_failed", "timed_out"] } }, "required": ["plan_id", "reason"] },
+  "usage.threshold_reached": { "type": ["object"], "properties": { "scope": { "type": ["string"], "enum": ["account", "client"] }, "threshold_pct": { "type": ["integer"], "enum": [50, 70, 90, 100] }, "month": { "type": ["string"] }, "client_id": { "type": ["string", "null"] } }, "required": ["scope", "threshold_pct", "month"] },
+  "webhook.test": { "type": ["object"] },
+  "app.installed": { "type": ["object"], "properties": { "client_id": { "type": ["string"] }, "install_id": { "type": ["string"] }, "context": { "type": ["array"], "items": { "type": ["string"], "enum": ["languages", "plan_summary", "review_due", "tutor_topic"] } }, "tutor_note": { "type": ["boolean"] } }, "required": ["client_id", "install_id", "context", "tutor_note"] },
+  "app.uninstalled": { "type": ["object"], "properties": { "client_id": { "type": ["string"] }, "install_id": { "type": ["string"] } }, "required": ["client_id", "install_id"] }
+};
+function isType(type, value) {
+  if (type === "null") return value === null;
+  if (type === "array") return Array.isArray(value);
+  if (type === "object") return typeof value === "object" && value !== null && !Array.isArray(value);
+  if (type === "integer") return Number.isInteger(value);
+  return typeof value === type;
+}
+function conforms(s, value) {
+  if (s.anyOf && !s.anyOf.some((a) => conforms(a, value))) return false;
+  if (s.enum && !s.enum.includes(value)) return false;
+  if (s.type && !s.type.some((t) => isType(t, value))) return false;
+  if (Array.isArray(value)) return !s.items || value.every((v) => conforms(s.items, v));
+  if (typeof value !== "object" || value === null) return true;
+  const o = value;
+  if (!(s.required ?? []).every((k) => Object.hasOwn(o, k))) return false;
+  const present = Object.entries(s.properties ?? {}).filter(([k]) => Object.hasOwn(o, k) && (o[k] !== null || s.required?.includes(k)));
+  return present.every(([k, p]) => conforms(p, o[k]));
+}
+var ENVELOPE = ["id", "type", "created_at", "api_version", "subject"];
+function envelope(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TransportError("malformed_event");
+  const o = value;
+  if (!ENVELOPE.every((k) => typeof o[k] === "string") || !Object.hasOwn(o, "data")) throw new TransportError("malformed_event");
+  const [id, type, createdAt, apiVersion, subject] = ENVELOPE.map((k) => o[k]);
+  return { id, type, createdAt, apiVersion, subject, data: o["data"] };
+}
+function parseEvent(json) {
+  let value = json;
+  if (typeof json === "string") {
+    try {
+      value = JSON.parse(json);
+    } catch {
+      throw new TransportError("malformed_event");
+    }
+  }
+  const event = envelope(value);
+  const s = Object.hasOwn(SHAPES, event.type) ? SHAPES[event.type] : void 0;
+  if (s === void 0) return new UnknownEvent(event);
+  if (!conforms(s, event.data)) throw new TransportError("malformed_event");
+  return event;
+}
+
+// src/events/feed.ts
+function eventsQuery(params) {
+  const q = new URLSearchParams();
+  if (params.cursor !== void 0) q.set("cursor", params.cursor);
+  if (params.start !== void 0) q.set("start", params.start);
+  if (params.types !== void 0) q.set("types", params.types.join(","));
+  if (params.limit !== void 0) q.set("limit", String(params.limit));
+  const text = q.toString();
+  return text === "" ? "" : `?${text}`;
+}
+var EventFeed = class {
+  #page;
+  #types;
+  #query;
+  #cursor;
+  #items = [];
+  #next;
+  #more = true;
+  constructor(params, page) {
+    this.#page = page;
+    this.#types = params.types;
+    this.#cursor = params.cursor;
+    const from = params.cursor !== void 0 ? { cursor: params.cursor } : params.start !== void 0 ? { start: params.start } : {};
+    this.#query = this.#withTypes(from);
+  }
+  /**
+   * 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() {
+    return this.#cursor;
+  }
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+  async next() {
+    for (; ; ) {
+      if (this.#items.length > 0) return { done: false, value: this.#take() };
+      if (!this.#more) return { done: true, value: void 0 };
+      await this.#fetch();
+    }
+  }
+  async return() {
+    this.#more = false;
+    this.#items = [];
+    return { done: true, value: void 0 };
+  }
+  #take() {
+    let event;
+    try {
+      event = parseEvent(this.#items.shift());
+    } catch (err) {
+      this.#more = false;
+      this.#items = [];
+      throw err;
+    }
+    if (this.#items.length === 0) this.#cursor = this.#next;
+    return event;
+  }
+  async #fetch() {
+    let page;
+    try {
+      page = await this.#page(this.#query);
+    } catch (err) {
+      this.#more = false;
+      throw err;
+    }
+    this.#items = [...page.items];
+    this.#next = page.next_cursor;
+    this.#more = page.has_more;
+    this.#query = this.#withTypes({ cursor: page.next_cursor });
+    if (this.#items.length === 0) this.#cursor = page.next_cursor;
+  }
+  #withTypes(query) {
+    return this.#types === void 0 ? query : { ...query, types: this.#types };
+  }
+};
+
+// src/events/send.ts
+function sendEventRequest(event, options) {
+  const key = options.idempotencyKey ?? globalThis.crypto.randomUUID();
+  return { body: { type: event.type, data: event.data }, headers: { "idempotency-key": key } };
+}
+
+// src/events/tail.ts
+var FIRST_DELAY_S = 1;
+var MAX_DELAY_S = 30;
+function backoffSeconds(failures) {
+  return Math.min(MAX_DELAY_S, FIRST_DELAY_S * 2 ** (failures - 1));
+}
+function failureWait(err, capSeconds) {
+  if (err instanceof TransportError && err.kind !== "malformed_event") return void 0;
+  if (err instanceof ApiError && err.status === 200) return void 0;
+  if (!isBusy(err)) throw err;
+  if (err.retryAfter !== void 0 && err.retryAfter > capSeconds) throw err;
+  return err.retryAfter;
+}
+function isBusy(err) {
+  return err instanceof MaintenanceError || err instanceof ApiError && (err.status === 429 || err.status === 503);
+}
+var REOPEN = /* @__PURE__ */ Symbol("lingara.reopen");
+var EventTail = class {
+  #init;
+  #own = new AbortController();
+  #signal;
+  #cursor;
+  #stream;
+  #failures = 0;
+  #done = false;
+  constructor(init) {
+    this.#init = init;
+    this.#cursor = init.cursor;
+    this.#signal = init.signal ? AbortSignal.any([init.signal, this.#own.signal]) : this.#own.signal;
+  }
+  /** Where to resume: hand it to `tailEvents` or `events` later. */
+  get cursor() {
+    return this.#cursor;
+  }
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+  async next() {
+    if (this.#done) return { done: true, value: void 0 };
+    try {
+      for (; ; ) {
+        const step = await this.#step();
+        if (step !== REOPEN) return { done: false, value: step };
+      }
+    } catch (err) {
+      await this.close();
+      throw err;
+    }
+  }
+  async return() {
+    await this.close();
+    return { done: true, value: void 0 };
+  }
+  /** Ends the tail and closes the connection. Idempotent. */
+  async close() {
+    if (this.#done) return;
+    this.#done = true;
+    if (!this.#own.signal.aborted) this.#own.abort();
+    await this.#stream?.close();
+  }
+  /** One frame's worth of progress: an event, or a reopen to make. */
+  async #step() {
+    const stream = this.#stream ??= this.#init.open(this.#cursor, this.#signal);
+    let result;
+    try {
+      result = await stream.next();
+    } catch (err) {
+      this.#stream = void 0;
+      await this.#failed(err);
+      return REOPEN;
+    }
+    this.#cursor = stream.lastEventId ?? this.#cursor;
+    this.#failures = 0;
+    if (!result.done) return parseEvent(result.value.data);
+    this.#stream = void 0;
+    return REOPEN;
+  }
+  async #failed(err) {
+    this.#signal.throwIfAborted();
+    const wait = failureWait(err, this.#init.retryAfterCapSeconds);
+    this.#failures++;
+    if (this.#failures >= this.#init.maxFailures) throw err;
+    const seconds = wait ?? backoffSeconds(this.#failures);
+    await this.#init.sleeper(seconds * 1e3, this.#signal);
+  }
+};
+
+// src/generated/streams.ts
+var STREAMS = {
+  generateVocabulary: {
+    method: "POST",
+    path: "/v1/vocab/stream",
+    requestBody: "VocabRequest",
+    union: "GenerateVocabularyEvent",
+    events: ["started", "item", "done", "error"],
+    ends: { done: "end", error: "raise" }
+  },
+  createLessonPlan: {
+    method: "POST",
+    path: "/v1/lesson-plans",
+    requestBody: "LessonPlanCreateRequest",
+    union: "CreateLessonPlanEvent",
+    events: ["started", "phase", "result", "error"],
+    ends: { result: "yield", error: "raise" }
+  },
+  streamLessonPlan: {
+    method: "GET",
+    path: "/v1/lesson-plans/{id}/stream",
+    requestBody: null,
+    union: "StreamLessonPlanEvent",
+    events: ["started", "phase", "result", "pending", "error"],
+    ends: { result: "yield", pending: "yield", error: "raise" }
+  },
+  sendTutorMessage: {
+    method: "POST",
+    path: "/v1/tutor/message",
+    requestBody: "TutorTurnRequest",
+    union: "SendTutorMessageEvent",
+    events: ["delta", "notice", "done", "error"],
+    ends: { done: "end", error: "raise" }
+  },
+  streamEvents: {
+    method: "GET",
+    path: "/v1/events/stream",
+    requestBody: null,
+    union: "StreamEventsEvent",
+    events: ["event", "done", "error"],
+    ends: { done: "end", error: "raise" }
+  }
+};
+
+// src/seams.ts
+var systemClock = { now: () => Date.now() };
+var realSleeper = (ms, signal) => raceAbort(
+  new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => clearTimeout(timer), { once: true });
+  }),
+  signal
+);
+function raceAbort(promise, signal) {
+  if (!signal) return promise;
+  if (signal.aborted) {
+    promise.catch(() => void 0);
+    return Promise.reject(signal.reason);
+  }
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      }
+    );
+  });
+}
+
+// src/retry.ts
+var DELTA_SECONDS = /^\d+$/;
+function parseRetryAfter(value, clock) {
+  if (value === null) return void 0;
+  const trimmed = value.trim();
+  if (DELTA_SECONDS.test(trimmed)) return Number(trimmed);
+  const at = Date.parse(trimmed);
+  if (Number.isNaN(at)) return void 0;
+  return Math.max(0, Math.ceil((at - clock.now()) / 1e3));
+}
+async function withRetries(policy, signal, attempt) {
+  for (let tries = 1; ; tries++) {
+    const res = await attempt();
+    const wait = retryWait(res, policy, tries);
+    if (wait === void 0) return res;
+    await res.body?.cancel().catch(() => void 0);
+    await policy.sleeper(wait * 1e3, signal);
+  }
+}
+function retryWait(res, policy, tries) {
+  if (res.status !== 429 && res.status !== 503) return void 0;
+  if (tries >= policy.maxAttempts) return void 0;
+  const seconds = parseRetryAfter(res.headers.get("retry-after"), policy.clock);
+  if (seconds === void 0 || seconds > policy.retryAfterCapSeconds) return void 0;
+  return seconds;
+}
+async function withTokenRetry(tokens, signal, send) {
+  const options = signal ? { signal } : {};
+  const first = await tokens.token(options);
+  const res = await send(first);
+  if (res.status !== 401) return res;
+  await res.body?.cancel().catch(() => void 0);
+  tokens.invalidate(first);
+  return send(await tokens.token(options));
+}
+
+// src/transport.ts
+async function fetchOnce(req) {
+  try {
+    return await req.fetch(req.url, req.init);
+  } catch (err) {
+    throw transportFailure(err, req.init.signal ?? void 0, "fetch", req.secrets);
+  }
+}
+function transportFailure(err, signal, phase, secrets) {
+  if (signal?.aborted) return signal.reason;
+  if (err instanceof TransportError) return err;
+  return new TransportError(transportKind(err, phase), redactCause(err, secrets));
+}
+
+// src/userAgent.ts
+var LIBRARY_VERSION = "0.1.0-alpha.12";
+function runtimeToken(g = globalThis) {
+  const bun = g.Bun?.version;
+  if (typeof bun === "string") return clean(`bun/${bun}`);
+  const deno = g.Deno?.version?.deno;
+  if (typeof deno === "string") return clean(`deno/${deno}`);
+  const node = g.process?.versions?.node;
+  if (typeof node === "string") return clean(`node/${node}`);
+  return "unknown";
+}
+function clean(value) {
+  return value.replace(/[^\x21-\x28\x2A-\x7E]/g, "");
+}
+function userAgent(suffix) {
+  const own = `lingara-typescript/${LIBRARY_VERSION} (${runtimeToken()})`;
+  return suffix ? `${own} ${suffix}` : own;
+}
+
+// src/token.ts
+var DEFAULT_TOKEN_URL = "https://api.getlingara.com/oauth/token";
+var ClientCredentials = class {
+  clientId;
+  #secret;
+  #cached;
+  #flight;
+  #options;
+  constructor(options) {
+    this.clientId = options.clientId;
+    this.#secret = options.clientSecret;
+    this.#options = {
+      auth: options.auth ?? "basic",
+      scopes: options.scopes,
+      tokenUrl: options.tokenUrl ?? DEFAULT_TOKEN_URL,
+      maxAttempts: options.maxAttempts ?? 3,
+      retryAfterCapSeconds: options.retryAfterCapSeconds ?? 60,
+      tokenRequestTimeoutMs: options.tokenRequestTimeoutMs ?? 3e4,
+      userAgent: userAgent(options.userAgentSuffix),
+      clock: options.clock ?? systemClock,
+      sleeper: options.sleeper ?? realSleeper,
+      fetch: options.fetch ?? ((input, init) => globalThis.fetch(input, init))
+    };
+  }
+  async token(options = {}) {
+    options.signal?.throwIfAborted();
+    const cached = this.#cached;
+    if (cached && this.#options.clock.now() < cached.staleAt) return cached.token;
+    if (!this.#flight) {
+      const flight = this.#exchange();
+      this.#flight = flight;
+      flight.then(
+        () => this.#settle(flight),
+        () => this.#settle(flight)
+      );
+    }
+    return raceAbort(this.#flight, options.signal);
+  }
+  invalidate(token) {
+    if (this.#cached?.token === token) this.#cached = void 0;
+  }
+  /** The cached access token, raw. The one accessor that does not redact. */
+  exposeToken() {
+    return this.#cached?.token;
+  }
+  toJSON() {
+    return { clientId: this.clientId, clientSecret: REDACTED, token: this.#cached ? REDACTED : void 0 };
+  }
+  [INSPECT]() {
+    return `ClientCredentials ${JSON.stringify(this.toJSON())}`;
+  }
+  toString() {
+    return this[INSPECT]();
+  }
+  #settle(flight) {
+    if (this.#flight === flight) this.#flight = void 0;
+  }
+  async #exchange() {
+    const o = this.#options;
+    const policy = { maxAttempts: o.maxAttempts, retryAfterCapSeconds: o.retryAfterCapSeconds, clock: o.clock, sleeper: o.sleeper };
+    let sentAt = o.clock.now();
+    const res = await withRetries(policy, void 0, () => {
+      sentAt = o.clock.now();
+      return this.#post();
+    });
+    if (!res.ok) {
+      const retryAfter = parseRetryAfter(res.headers.get("retry-after"), o.clock);
+      throw await errorFromResponse(res, { endpoint: "token", retryAfter });
+    }
+    const grant = await this.#readGrant(res);
+    const skew = Math.min(60, grant.expiresIn / 2);
+    this.#cached = { token: grant.token, staleAt: sentAt + (grant.expiresIn - skew) * 1e3 };
+    return grant.token;
+  }
+  async #post() {
+    const o = this.#options;
+    const headers = {
+      "content-type": "application/x-www-form-urlencoded",
+      accept: "application/json",
+      "user-agent": o.userAgent
+    };
+    const body = new URLSearchParams({ grant_type: "client_credentials" });
+    if (o.scopes && o.scopes.length > 0) body.set("scope", o.scopes.join(" "));
+    if (o.auth === "post") {
+      body.set("client_id", this.clientId);
+      body.set("client_secret", this.#secret);
+    } else {
+      headers["authorization"] = `Basic ${btoa(`${formEncode(this.clientId)}:${formEncode(this.#secret)}`)}`;
+    }
+    const signal = AbortSignal.timeout(o.tokenRequestTimeoutMs);
+    try {
+      return await fetchOnce({ fetch: o.fetch, url: o.tokenUrl, init: { method: "POST", headers, body: body.toString(), signal }, secrets: [this.#secret] });
+    } catch (err) {
+      throw signal.aborted ? new TransportError("timeout") : err;
+    }
+  }
+  async #readGrant(res) {
+    let body;
+    try {
+      body = await res.json();
+    } catch (err) {
+      throw this.#readFailure(err);
+    }
+    const grant = body ?? {};
+    const { access_token: token, expires_in: expiresIn, token_type: type } = grant;
+    const bearer = typeof type === "string" && type.toLowerCase() === "bearer";
+    if (typeof token !== "string" || typeof expiresIn !== "number" || !bearer) {
+      throw new TransportError("malformed_response");
+    }
+    return { token, expiresIn };
+  }
+  #readFailure(err) {
+    if (err instanceof SyntaxError) return new TransportError("malformed_response");
+    if (err?.name === "TimeoutError") return new TransportError("timeout");
+    return transportFailure(err, void 0, "body", [this.#secret]);
+  }
+};
+function formEncode(value) {
+  return new URLSearchParams([["", value]]).toString().slice(1);
+}
+
+// src/options.ts
+function checkOptions(options) {
+  if (options.tokenSource && options.clientSecret !== void 0) {
+    throw new LingaraError("pass either tokenSource or clientSecret, not both");
+  }
+  if (options.version === "") throw new LingaraError("version must not be empty");
+  if (options.clientSecret !== void 0 && globalThis.document !== void 0) {
+    throw new LingaraError(
+      "a client secret must not be used in a browser: anyone who loads the page can read it. Call the Lingara API from your server."
+    );
+  }
+  if (options.clientSecret === void 0 !== (options.clientId === void 0) && !options.tokenSource) {
+    throw new LingaraError("clientId and clientSecret go together");
+  }
+}
+function retryPolicy(options) {
+  return {
+    maxAttempts: options.maxAttempts ?? 3,
+    retryAfterCapSeconds: options.retryAfterCapSeconds ?? 60,
+    clock: options.clock ?? systemClock,
+    sleeper: options.sleeper ?? realSleeper
+  };
+}
+function credentialsFrom(options) {
+  const { clientId, clientSecret } = options;
+  if (clientId === void 0 || clientSecret === void 0) return void 0;
+  return new ClientCredentials({ ...options, clientId, clientSecret });
+}
+
+// src/sse.ts
+var SseParser = class {
+  #buffer = "";
+  #event = "";
+  #data = [];
+  #hasData = false;
+  // WHATWG's last-event-id buffer: it persists across frames until the next
+  // `id` field, and is not reset on dispatch.
+  #lastEventId = "";
+  // A chunk ended on `\r`: a `\n` opening the next chunk is the same line end.
+  #skipLf = false;
+  /** Feeds decoded text; returns every frame it completed. */
+  push(text) {
+    let input = text;
+    if (this.#skipLf && input.length > 0) {
+      if (input.startsWith("\n")) input = input.slice(1);
+      this.#skipLf = false;
+    }
+    const frames = [];
+    const s = this.#buffer + input;
+    let start = 0;
+    for (; ; ) {
+      const end = lineEnd(s, start);
+      if (end < 0) break;
+      this.#line(s.slice(start, end), frames);
+      start = this.#afterEnding(s, end);
+    }
+    this.#buffer = s.slice(start);
+    return frames;
+  }
+  /** End of input: an undispatched frame is discarded, as WHATWG says. */
+  end() {
+    this.#buffer = "";
+    this.#reset();
+    return [];
+  }
+  #afterEnding(s, end) {
+    if (s[end] === "\n") return end + 1;
+    if (end + 1 < s.length) return s[end + 1] === "\n" ? end + 2 : end + 1;
+    this.#skipLf = true;
+    return end + 1;
+  }
+  #line(line, frames) {
+    if (line === "") {
+      if (this.#hasData) frames.push(this.#frame());
+      this.#reset();
+      return;
+    }
+    if (line.startsWith(":")) return;
+    const colon = line.indexOf(":");
+    const field = colon < 0 ? line : line.slice(0, colon);
+    let value = colon < 0 ? "" : line.slice(colon + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    this.#field(field, value);
+  }
+  #field(field, value) {
+    if (field === "event") this.#event = value;
+    if (field === "data") {
+      this.#data.push(value);
+      this.#hasData = true;
+    }
+    if (field === "id" && !value.includes("\0")) this.#lastEventId = value;
+  }
+  #frame() {
+    const frame = { event: this.#event || "message", data: this.#data.join("\n") };
+    if (this.#lastEventId !== "") frame.id = this.#lastEventId;
+    return frame;
+  }
+  #reset() {
+    this.#event = "";
+    this.#data = [];
+    this.#hasData = false;
+  }
+};
+function lineEnd(s, from) {
+  for (let i = from; i < s.length; i++) {
+    const c = s[i];
+    if (c === "\n" || c === "\r") return i;
+  }
+  return -1;
+}
+
+// src/stream.ts
+function outcomeOf(operation, event) {
+  const ends = STREAMS[operation].ends;
+  return Object.hasOwn(ends, event) ? ends[event] : void 0;
+}
+var IDLE = /* @__PURE__ */ Symbol("lingara.idle");
+var CLOSED = /* @__PURE__ */ Symbol("lingara.closed");
+var EventStream = class {
+  #init;
+  #own = new AbortController();
+  #signal;
+  #parser = new SseParser();
+  #decoder = new TextDecoder("utf-8");
+  #frames = [];
+  #started;
+  #reader;
+  #servedVersion;
+  #lastEventId;
+  #eof = false;
+  #done = false;
+  constructor(init) {
+    this.#init = init;
+    this.#signal = init.signal ? AbortSignal.any([init.signal, this.#own.signal]) : this.#own.signal;
+  }
+  /**
+   * 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() {
+    if (this.#done && !this.#started) return Promise.resolve(void 0);
+    return this.#start().then(
+      (opened) => opened.servedVersion,
+      () => void 0
+    );
+  }
+  /**
+   * 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() {
+    return this.#lastEventId;
+  }
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+  async next() {
+    if (this.#done) return { done: true, value: void 0 };
+    try {
+      await this.#start();
+      for (; ; ) {
+        const frame = this.#frames.shift();
+        if (frame) {
+          const result = this.#handle(frame);
+          if (result) return result;
+          continue;
+        }
+        if (this.#eof) throw new TransportError("stream_ended_early");
+        await this.#read();
+      }
+    } catch (err) {
+      return this.#fail(err);
+    }
+  }
+  async return() {
+    await this.close();
+    return { done: true, value: void 0 };
+  }
+  /** Ends the stream and closes the connection. Idempotent. */
+  async close() {
+    this.#finish(CLOSED);
+  }
+  #start() {
+    this.#started ??= this.#init.open(this.#signal).then((opened) => {
+      this.#servedVersion = opened.servedVersion;
+      const body = opened.response.body;
+      if (!body) throw new TransportError("stream_ended_early");
+      this.#reader = body.getReader();
+      if (this.#done) this.#reader.cancel().catch(() => void 0);
+      return opened;
+    });
+    return this.#started;
+  }
+  async #read() {
+    const reader = this.#reader;
+    const timer = setTimeout(() => this.#own.abort(IDLE), this.#init.idleTimeoutMs);
+    try {
+      const chunk = await raceAbort(reader.read(), this.#signal);
+      if (chunk.done) {
+        this.#frames.push(...this.#parser.push(this.#decoder.decode()), ...this.#parser.end());
+        this.#eof = true;
+      } else {
+        this.#frames.push(...this.#parser.push(this.#decoder.decode(chunk.value, { stream: true })));
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  #handle(frame) {
+    if (frame.id !== void 0) this.#lastEventId = frame.id;
+    const events = STREAMS[this.#init.operation].events;
+    if (!events.includes(frame.event)) return void 0;
+    const data = decode(frame.data);
+    const outcome = outcomeOf(this.#init.operation, frame.event);
+    if (outcome === "raise") throw this.#streamError(data);
+    const value = { event: frame.event, data };
+    if (outcome === void 0) return { done: false, value };
+    this.#finish(CLOSED);
+    if (outcome === "end") return { done: true, value: void 0 };
+    return { done: false, value };
+  }
+  #streamError(data) {
+    const d = data ?? {};
+    return new ApiError({
+      status: 200,
+      code: typeof d.code === "string" ? d.code : "stream_error",
+      message: typeof d.message === "string" ? d.message : "the stream reported an error",
+      planId: typeof d.plan_id === "string" ? d.plan_id : void 0,
+      servedVersion: this.#servedVersion
+    });
+  }
+  #fail(err) {
+    const reason = this.#signal.aborted ? this.#signal.reason : void 0;
+    this.#finish(CLOSED);
+    if (reason === CLOSED) return { done: true, value: void 0 };
+    if (reason === IDLE) throw new TransportError("timeout");
+    if (reason !== void 0) throw reason;
+    if (err instanceof LingaraError) throw err;
+    throw new TransportError(transportKind(err, "body"), redactCause(err, []));
+  }
+  /** Marks the stream done and closes the connection; clears nothing twice. */
+  #finish(reason) {
+    if (this.#done) return;
+    this.#done = true;
+    if (!this.#own.signal.aborted) this.#own.abort(reason);
+    this.#reader?.cancel().catch(() => void 0);
+  }
+};
+function decode(data) {
+  try {
+    return JSON.parse(data);
+  } catch {
+    throw new TransportError("malformed_event");
+  }
+}
+
+// src/generated/specVersion.ts
+var GENERATED_FOR_VERSION = "2026-10-affable-towhee";
+
+// src/version.ts
+var UNIX_SECONDS = /^@(-?\d+)$/;
+var IMF_FIXDATE = /^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/;
+var LINK_TARGET = /^\s*<([^>]*)>/;
+function parseDeprecation(value) {
+  const match = UNIX_SECONDS.exec(value.trim());
+  return match ? new Date(Number(match[1]) * 1e3) : void 0;
+}
+function parseSunset(value) {
+  const trimmed = value.trim();
+  if (!IMF_FIXDATE.test(trimmed)) return void 0;
+  const at = Date.parse(trimmed);
+  return Number.isNaN(at) ? void 0 : new Date(at);
+}
+function parseLink(raw, requestUrl) {
+  const target = LINK_TARGET.exec(raw)?.[1];
+  if (target === void 0) return { raw };
+  try {
+    return { raw, url: new URL(target, requestUrl) };
+  } catch {
+    return { raw };
+  }
+}
+function deprecationNotice(headers, requestUrl) {
+  const deprecation = headers.get("deprecation");
+  if (deprecation === null) return void 0;
+  const notice = { deprecation };
+  const version = headers.get("lingara-version");
+  const sunset = headers.get("sunset");
+  const link = headers.get("link");
+  const deprecatedAt = parseDeprecation(deprecation);
+  if (version !== null) notice.version = version;
+  if (deprecatedAt) notice.deprecatedAt = deprecatedAt;
+  if (sunset !== null) {
+    notice.sunset = sunset;
+    const sunsetAt = parseSunset(sunset);
+    if (sunsetAt) notice.sunsetAt = sunsetAt;
+  }
+  if (link !== null) notice.link = parseLink(link, requestUrl);
+  return notice;
+}
+var VersionObserver = class {
+  #hook;
+  #warned = /* @__PURE__ */ new Set();
+  // Its own set: sharing `#warned` would let a version that is both
+  // deprecated and mismatched warn only once in total.
+  #mismatched = /* @__PURE__ */ new Set();
+  constructor(hook) {
+    this.#hook = hook;
+  }
+  /** Returns the `Lingara-Version` echo, after reporting any deprecation or mismatch. */
+  observe(res, requestUrl) {
+    const notice = deprecationNotice(res.headers, requestUrl);
+    if (notice) this.#report(notice);
+    const served = res.headers.get("lingara-version") ?? void 0;
+    if (served !== void 0) this.#checkGenerated(served);
+    return served;
+  }
+  #checkGenerated(served) {
+    if (served === GENERATED_FOR_VERSION || this.#mismatched.has(served)) return;
+    this.#mismatched.add(served);
+    console.warn(
+      `Lingara API version ${served} served this response, but this library's types were generated for ${GENERATED_FOR_VERSION}; response shapes may differ. Pin the OAuth client to ${GENERATED_FOR_VERSION} or upgrade the library.`
+    );
+  }
+  #report(notice) {
+    if (!this.#hook) {
+      const id = notice.version ?? "";
+      if (this.#warned.has(id)) return;
+      this.#warned.add(id);
+      const sunset = notice.sunset ? `; sunset ${notice.sunset}` : "";
+      console.warn(`Lingara API version ${id || "(unnamed)"} is deprecated${sunset}. See GET /v1/versions.`);
+      return;
+    }
+    try {
+      this.#hook(notice);
+    } catch (err) {
+      console.debug("Lingara deprecation hook threw", err);
+    }
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.getlingara.com";
+var Lingara = class {
+  clientId;
+  #tokens;
+  #baseUrl;
+  #version;
+  #versions;
+  #policy;
+  #idleMs;
+  #tailMaxFailures;
+  #userAgent;
+  #fetch;
+  constructor(options = {}) {
+    checkOptions(options);
+    this.clientId = options.clientId;
+    this.#tokens = options.tokenSource ?? credentialsFrom(options);
+    this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.#version = options.version;
+    this.#versions = new VersionObserver(options.onDeprecation);
+    this.#policy = retryPolicy(options);
+    this.#idleMs = options.streamIdleTimeoutMs ?? 12e4;
+    this.#tailMaxFailures = options.tailMaxFailures ?? 8;
+    this.#userAgent = userAgent(options.userAgentSuffix);
+    this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  }
+  /** The token source in use, if the client has credentials. */
+  get tokenSource() {
+    return this.#tokens;
+  }
+  // --- streams -------------------------------------------------------------
+  generateVocabulary(body, options = {}) {
+    return this.#stream("generateVocabulary", { body }, options);
+  }
+  createLessonPlan(body, options = {}) {
+    return this.#stream("createLessonPlan", { body }, options);
+  }
+  streamLessonPlan(params, options = {}) {
+    return this.#stream("streamLessonPlan", { id: params.id }, options);
+  }
+  sendTutorMessage(body, options = {}) {
+    return this.#stream("sendTutorMessage", { body }, options);
+  }
+  /** One connection under K5; `tailEvents` is the one that reconnects. */
+  streamEvents(params = {}, options = {}) {
+    const headers = params.lastEventId === void 0 ? {} : { "last-event-id": params.lastEventId };
+    return this.#stream("streamEvents", { query: eventsQuery(params), headers }, options);
+  }
+  // --- events (ADR 30.9.26aa) ----------------------------------------------
+  /** Every event from `cursor` (or `start`) to where the feed is caught up; never polls. */
+  events(params = {}, options = {}) {
+    return new EventFeed(params, (query) => this.listEvents(query, options));
+  }
+  /** Live events, reconnecting from `cursor` after every ending (CONTRACT.md K5a). */
+  tailEvents(params = {}, options = {}) {
+    const query = eventsQuery(params.cursor === void 0 ? { start: params.start, types: params.types } : { types: params.types });
+    return new EventTail({
+      open: (cursor, signal) => {
+        const headers = cursor === void 0 ? {} : { "last-event-id": cursor };
+        return this.#stream("streamEvents", { query, headers, retries: false }, { signal });
+      },
+      cursor: params.cursor,
+      sleeper: this.#policy.sleeper,
+      retryAfterCapSeconds: this.#policy.retryAfterCapSeconds,
+      maxFailures: this.#tailMaxFailures,
+      signal: options.signal
+    });
+  }
+  /** `{type, data}` with one `Idempotency-Key` across K4's attempts; the `202` body. */
+  sendEvent(event, options = {}) {
+    const { body, headers } = sendEventRequest(event, options);
+    return this.#json("/v1/events", true, options, { method: "POST", body, headers });
+  }
+  // --- JSON ----------------------------------------------------------------
+  getLessonPlan(params, options = {}) {
+    return this.#json(`/v1/lesson-plans/${encodeURIComponent(params.id)}`, true, options);
+  }
+  getUsage(options = {}) {
+    return this.#json("/v1/usage", true, options);
+  }
+  /** One page of events; `events()` walks them. */
+  listEvents(params = {}, options = {}) {
+    return this.#json(`/v1/events${eventsQuery(params)}`, true, options);
+  }
+  getOpenApiDocument(options = {}) {
+    return this.#json("/v1/openapi.json", false, options);
+  }
+  getAsyncApiDocument(options = {}) {
+    return this.#json("/v1/asyncapi.json", false, options);
+  }
+  listApiVersions(options = {}) {
+    return this.#json("/v1/versions", false, options);
+  }
+  getApiVersion(params, options = {}) {
+    return this.#json(`/v1/versions/${encodeURIComponent(params.id)}`, false, options);
+  }
+  // --- rendering: the secret and tokens never appear ------------------------
+  toJSON() {
+    const secret = this.#tokens instanceof ClientCredentials ? REDACTED : void 0;
+    return { clientId: this.clientId, clientSecret: secret, baseUrl: this.#baseUrl, version: this.#version };
+  }
+  [INSPECT]() {
+    return `Lingara ${JSON.stringify(this.toJSON())}`;
+  }
+  toString() {
+    return this[INSPECT]();
+  }
+  // --- the pipeline --------------------------------------------------------
+  #stream(op, input, options) {
+    const route = STREAMS[op];
+    const path = (input.id === void 0 ? route.path : route.path.replace("{id}", encodeURIComponent(input.id))) + (input.query ?? "");
+    const req = { method: route.method, path, body: input.body, accept: "text/event-stream", needsToken: true, headers: input.headers };
+    const open = (signal) => this.#openStream({ ...req, retries: input.retries ?? true, signal });
+    return new EventStream({ operation: op, open, signal: options.signal, idleTimeoutMs: this.#idleMs });
+  }
+  async #openStream(req) {
+    const res = await this.#send(req);
+    if (mediaType(res) !== "text/event-stream") {
+      await res.body?.cancel().catch(() => void 0);
+      throw new TransportError("malformed_response");
+    }
+    const servedVersion = this.#versions.observe(res, this.#baseUrl + req.path);
+    return { response: res, servedVersion };
+  }
+  async #json(path, needsToken, options, extra = {}) {
+    const res = await this.#send({ method: "GET", path, accept: "application/json", needsToken, signal: options.signal, ...extra });
+    const servedVersion = this.#versions.observe(res, this.#baseUrl + path);
+    let body;
+    try {
+      body = await res.json();
+    } catch (err) {
+      if (err instanceof SyntaxError) throw new TransportError("malformed_response");
+      throw transportFailure(err, options.signal, "body", []);
+    }
+    if (servedVersion !== void 0 && typeof body === "object" && body !== null) {
+      Object.defineProperty(body, "servedVersion", { value: servedVersion, enumerable: false });
+    }
+    return body;
+  }
+  /** Auth, retries and error mapping; resolves with a 2xx response. */
+  async #send(req) {
+    const url = this.#baseUrl + req.path;
+    const once = (token) => fetchOnce({ fetch: this.#fetch, url, init: this.#init(req, token), secrets: [token] });
+    const attempt = req.retries === false ? once : (token) => withRetries(this.#policy, req.signal, () => once(token));
+    let res;
+    if (!req.needsToken) res = await attempt();
+    else if (this.#tokens) res = await withTokenRetry(this.#tokens, req.signal, attempt);
+    else throw new LingaraError("this operation needs credentials: construct the client with clientId and clientSecret");
+    if (res.ok) return res;
+    const retryAfter = parseRetryAfter(res.headers.get("retry-after"), this.#policy.clock);
+    const servedVersion = res.headers.get("lingara-version") ?? void 0;
+    throw await errorFromResponse(res, { endpoint: "v1", retryAfter, servedVersion });
+  }
+  #init(req, token) {
+    const headers = { accept: req.accept, "user-agent": this.#userAgent, ...req.headers };
+    if (token !== void 0) headers["authorization"] = `Bearer ${token}`;
+    if (this.#version !== void 0) headers["lingara-version"] = this.#version;
+    const init = { method: req.method, headers };
+    if (req.body !== void 0) {
+      headers["content-type"] = "application/json";
+      init.body = JSON.stringify(req.body);
+    }
+    if (req.signal) init.signal = req.signal;
+    return init;
+  }
+};
+
+// src/events/webhook.ts
+var MESSAGES = {
+  missing_header: "a webhook-id, webhook-timestamp or webhook-signature header is missing",
+  malformed_header: "webhook-timestamp is not a whole number of seconds",
+  timestamp_too_old: "webhook-timestamp is more than 300 s old",
+  timestamp_too_new: "webhook-timestamp is more than 300 s in the future",
+  no_matching_signature: "no signature matches the body",
+  malformed_payload: "the signed body is not a Lingara event"
+};
+var BRAND = /* @__PURE__ */ Symbol.for("lingara.webhook.WebhookVerificationError");
+var WebhookVerificationError = class extends Error {
+  static [Symbol.hasInstance](value) {
+    return typeof value === "object" && value !== null && value[BRAND] === true;
+  }
+  reason;
+  constructor(reason) {
+    super(MESSAGES[reason]);
+    this.name = "WebhookVerificationError";
+    this.reason = reason;
+    Object.defineProperty(this, BRAND, { value: true, enumerable: false });
+  }
+};
+var PREFIX = "lgr_whsec_";
+var MIN_KEY_BYTES = 24;
+var SIGNATURE_BYTES = 32;
+var TOLERANCE_S = 300;
+var BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
+var DIGITS = /^[0-9]+$/;
+function strictBase64(text) {
+  if (!BASE64.test(text) || text.length % 4 !== 0) return void 0;
+  try {
+    return Uint8Array.from(atob(text), (c) => c.charCodeAt(0));
+  } catch {
+    return void 0;
+  }
+}
+function keyOf(secret) {
+  const key = secret.startsWith(PREFIX) ? strictBase64(secret.slice(PREFIX.length)) : void 0;
+  if (key === void 0 || key.length < MIN_KEY_BYTES) {
+    throw new LingaraError("a webhook secret is lgr_whsec_ followed by padded base64 of at least 24 bytes");
+  }
+  return key;
+}
+function header(headers, name) {
+  if (isFetchHeaders(headers)) return headers.get(name) ?? void 0;
+  const entry = Object.entries(headers).find(([k]) => k.toLowerCase() === name);
+  const value = entry?.[1];
+  return typeof value === "string" || value === void 0 ? value : value.join(" ");
+}
+function isFetchHeaders(headers) {
+  return typeof headers.get === "function";
+}
+function sameBytes(a, b) {
+  if (a.length !== SIGNATURE_BYTES || b.length !== SIGNATURE_BYTES) return false;
+  let diff = 0;
+  for (let i = 0; i < SIGNATURE_BYTES; i++) diff |= a[i] ^ b[i];
+  return diff === 0;
+}
+function v1Signatures(list) {
+  return list.split(" ").filter((e) => e.startsWith("v1,")).map((e) => strictBase64(e.slice(3))).filter((s) => s !== void 0);
+}
+function signedContent(id, timestamp, body) {
+  const encoder = new TextEncoder();
+  const head = encoder.encode(`${id}.${timestamp}.`);
+  const rest = typeof body === "string" ? encoder.encode(body) : body;
+  const out = new Uint8Array(head.length + rest.length);
+  out.set(head);
+  out.set(rest, head.length);
+  return out;
+}
+var Webhook = class {
+  #secrets;
+  #clock;
+  #keys;
+  constructor(secret, options = {}) {
+    const secrets = typeof secret === "string" ? [secret] : secret;
+    if (secrets.length === 0) throw new LingaraError("a Webhook needs at least one secret");
+    this.#secrets = secrets.map(keyOf);
+    this.#clock = options.clock ?? systemClock;
+  }
+  /** Signature checks, then the body parsed into an `Event` whose `id` is `webhook-id`. */
+  async verify(body, headers) {
+    const signed = await this.#check(body, headers);
+    let event;
+    try {
+      event = parseEvent(typeof body === "string" ? body : new TextDecoder("utf-8", { fatal: true }).decode(body));
+    } catch {
+      throw new WebhookVerificationError("malformed_payload");
+    }
+    if (event.id !== signed.id) throw new WebhookVerificationError("malformed_payload");
+    return event;
+  }
+  /** The signature checks alone, for a signed body that is not an event (an app-kit request). */
+  async verifySignature(body, headers) {
+    await this.#check(body, headers);
+  }
+  toJSON() {
+    return { secrets: this.#secrets.map(() => REDACTED) };
+  }
+  toString() {
+    return `Webhook ${JSON.stringify(this.toJSON())}`;
+  }
+  async #check(body, headers) {
+    const signed = this.#headers(headers);
+    const content = signedContent(signed.id, signed.timestamp, body);
+    const candidates = v1Signatures(signed.signature);
+    const keys = await this.#cryptoKeys();
+    const expected = await Promise.all(keys.map((k) => globalThis.crypto.subtle.sign("HMAC", k, content)));
+    const match = expected.some((e) => candidates.some((c) => sameBytes(new Uint8Array(e), c)));
+    if (!match) throw new WebhookVerificationError("no_matching_signature");
+    return signed;
+  }
+  #headers(headers) {
+    const id = header(headers, "webhook-id");
+    const timestamp = header(headers, "webhook-timestamp");
+    const signature = header(headers, "webhook-signature");
+    if (id === void 0 || timestamp === void 0 || signature === void 0) throw new WebhookVerificationError("missing_header");
+    if (!DIGITS.test(timestamp)) throw new WebhookVerificationError("malformed_header");
+    const age = this.#clock.now() / 1e3 - Number(timestamp);
+    if (age > TOLERANCE_S) throw new WebhookVerificationError("timestamp_too_old");
+    if (age < -TOLERANCE_S) throw new WebhookVerificationError("timestamp_too_new");
+    return { id, timestamp, signature };
+  }
+  #cryptoKeys() {
+    const algorithm = { name: "HMAC", hash: "SHA-256" };
+    this.#keys ??= Promise.all(this.#secrets.map((k) => globalThis.crypto.subtle.importKey("raw", k, algorithm, false, ["sign"])));
+    return this.#keys;
+  }
+};
+export {
+  ApiError,
+  ClientCredentials,
+  DEFAULT_BASE_URL,
+  DEFAULT_TOKEN_URL,
+  EventFeed,
+  EventStream,
+  EventTail,
+  InboundEvent,
+  Lingara,
+  LingaraError,
+  MaintenanceError,
+  OAuthError,
+  TransportError,
+  UnknownEvent,
+  Webhook,
+  WebhookVerificationError,
+  parseEvent
+};