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

package/dist/index.mjs

@@ -0,0 +1,907 @@
+// 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 envelope = typeof code === "string" && typeof message === "string";
+  return new ApiError({
+    status,
+    code: envelope ? code : `http_${status}`,
+    message: envelope ? 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/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" }
+  }
+};
+
+// 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/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/sse.ts
+var SseParser = class {
+  #buffer = "";
+  #event = "";
+  #data = [];
+  #hasData = false;
+  // 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({ event: this.#event || "message", data: this.#data.join("\n") });
+      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);
+    if (field === "event") this.#event = value;
+    if (field === "data") {
+      this.#data.push(value);
+      this.#hasData = true;
+    }
+  }
+  #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;
+  #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
+    );
+  }
+  [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) {
+    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/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.6";
+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/generated/specVersion.ts
+var GENERATED_FOR_VERSION = "2026-09-glowing-hoatzin";
+
+// 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;
+  #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 = {
+      maxAttempts: options.maxAttempts ?? 3,
+      retryAfterCapSeconds: options.retryAfterCapSeconds ?? 60,
+      clock: options.clock ?? systemClock,
+      sleeper: options.sleeper ?? realSleeper
+    };
+    this.#idleMs = options.streamIdleTimeoutMs ?? 12e4;
+    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);
+  }
+  // --- JSON ----------------------------------------------------------------
+  getLessonPlan(params, options = {}) {
+    return this.#json(`/v1/lesson-plans/${encodeURIComponent(params.id)}`, true, options);
+  }
+  getUsage(options = {}) {
+    return this.#json("/v1/usage", true, options);
+  }
+  getOpenApiDocument(options = {}) {
+    return this.#json("/v1/openapi.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));
+    const open = (signal) => this.#openStream({ method: route.method, path, body: input.body, accept: "text/event-stream", needsToken: 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) {
+    const res = await this.#send({ method: "GET", path, accept: "application/json", needsToken, signal: options.signal });
+    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 attempt = (token) => withRetries(
+      this.#policy,
+      req.signal,
+      () => fetchOnce({ fetch: this.#fetch, url, init: this.#init(req, token), secrets: [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 };
+    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;
+  }
+};
+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 credentialsFrom(options) {
+  const { clientId, clientSecret } = options;
+  if (clientId === void 0 || clientSecret === void 0) return void 0;
+  return new ClientCredentials({ ...options, clientId, clientSecret });
+}
+export {
+  ApiError,
+  ClientCredentials,
+  DEFAULT_BASE_URL,
+  DEFAULT_TOKEN_URL,
+  EventStream,
+  Lingara,
+  LingaraError,
+  MaintenanceError,
+  OAuthError,
+  TransportError
+};