@yolk-sdk/emulators 0.1.0-canary.96

package/dist/todoist.d.mts

@@ -0,0 +1,68 @@
+import { EmulatorEvidence, EmulatorRouteEvidence, emulatorEvidenceHeader } from "./route-evidence.mjs";
+import { StatefulCoverage, StatefulFault, StatefulFaultMatch, StatefulFaultState, StatefulHeaderlessLedgerEntry } from "./stateful-emulator.mjs";
+import { TodoistEmulatorDue, TodoistEmulatorLabel, TodoistEmulatorProfile, TodoistEmulatorProject, TodoistEmulatorProjectSeed, TodoistEmulatorSeed, TodoistEmulatorState, TodoistEmulatorStateSchema, TodoistEmulatorTask, TodoistEmulatorTaskSeed } from "./todoist/state.mjs";
+import { TodoistCursor, TodoistEmulatorDrills, todoistEmulatorBasePath } from "./todoist/api.mjs";
+
+//#region src/todoist.d.ts
+/** Origin the connector calls. */
+declare const todoistEmulatorDefaultOrigin = "https://api.todoist.com";
+/**
+ * Route evidence manifest: every emulated route, whether it writes, and the conformance cases
+ * whose (currently synthetic, unverified) wire claims it follows. Kept in sync with the handlers
+ * by construction (both come from one route table). Every route cites at least one case.
+ */
+declare const todoistEmulatorRoutes: ReadonlyArray<EmulatorRouteEvidence>;
+type TodoistFaultState = StatefulFaultState;
+type TodoistLedgerEntry = StatefulHeaderlessLedgerEntry;
+type TodoistCoverage = StatefulCoverage;
+declare const TodoistEmulatorInputInvalid_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "TodoistEmulatorInputInvalid";
+} & Readonly<A>;
+/** Invalid emulator input from the JS API: a seed or a fault. A programmer error. */
+declare class TodoistEmulatorInputInvalid extends TodoistEmulatorInputInvalid_base<{
+  readonly input: 'seed' | 'fault';
+  readonly reason: string;
+}> {
+  get message(): string;
+}
+type TodoistEmulatorOptions = {
+  /** Typed seed; defaults to the fixture entities (`profile: 'default'`). */readonly seed?: TodoistEmulatorSeed; /** Clock in epoch milliseconds (created and closed timestamps). Defaults to `Date.now`. */
+  readonly now?: () => number; /** Drill knobs (tests only): make the emulator disagree with one conformance claim. */
+  readonly drills?: TodoistEmulatorDrills;
+};
+type TodoistEmulator = {
+  /** The fetch handler (Todoist routes and `/_emulate/*`). Never rejects. */readonly fetch: (request: Request) => Promise<Response>;
+  readonly ledger: {
+    readonly entries: () => ReadonlyArray<TodoistLedgerEntry>;
+    readonly clear: () => void;
+  };
+  readonly faults: {
+    /** Add a fault; throws `TodoistEmulatorInputInvalid` for an invalid fault. */readonly add: (fault: StatefulFault) => TodoistFaultState;
+    readonly list: () => ReadonlyArray<TodoistFaultState>;
+    readonly clear: () => void;
+  }; /** Task-listing cursors answered since the last reset or seed (runtime data). */
+  readonly cursors: () => ReadonlyArray<TodoistCursor>; /** Restore the current seed and clear the ledger, faults, and cursors. */
+  readonly reset: () => Promise<void>;
+  /**
+   * Replace the state with a new seed, which becomes what `reset` restores (cursors are cleared).
+   * Rejects with `TodoistEmulatorInputInvalid` for an invalid seed.
+   */
+  readonly seed: (seed: TodoistEmulatorSeed) => Promise<void>; /** A deep copy of the current state (entities and counters). */
+  readonly snapshot: () => TodoistEmulatorState;
+  readonly coverage: () => TodoistCoverage; /** Close the core runtime. Later requests answer 503. Idempotent. */
+  readonly close: () => Promise<void>;
+};
+/**
+ * Create a stateful Todoist emulator on the `@emulators/core` custom runtime. Each call has its
+ * own state, ledger, faults, and cursors. Rejects with `TodoistEmulatorInputInvalid` for an
+ * invalid seed.
+ *
+ * Routes (under `/api/v1`, `Authorization: Bearer <token of at least 8 characters>`): task
+ * listing with cursor paging, task read, create, update, and close, label listing, and project
+ * create, read, and delete.
+ * See `README.md` (Todoist emulator) for the wire claims.
+ */
+declare const makeTodoistEmulator: (options?: TodoistEmulatorOptions) => Promise<TodoistEmulator>;
+//#endregion
+export { type EmulatorEvidence, type EmulatorRouteEvidence, TodoistCoverage, TodoistEmulator, type TodoistEmulatorDrills, TodoistEmulatorDue, TodoistEmulatorInputInvalid, TodoistEmulatorLabel, TodoistEmulatorOptions, TodoistEmulatorProfile, TodoistEmulatorProject, TodoistEmulatorProjectSeed, TodoistEmulatorSeed, type TodoistEmulatorState, TodoistEmulatorStateSchema, TodoistEmulatorTask, TodoistEmulatorTaskSeed, StatefulFault as TodoistFault, StatefulFaultMatch as TodoistFaultMatch, TodoistFaultState, TodoistLedgerEntry, emulatorEvidenceHeader, makeTodoistEmulator, todoistEmulatorBasePath, todoistEmulatorDefaultOrigin, todoistEmulatorRoutes };
+//# sourceMappingURL=todoist.d.mts.map

package/dist/todoist.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"todoist.d.mts","names":[],"sources":["../src/todoist.ts"],"mappings":";;;;;;;cAiGa,4BAAA;AAOb;;;;AAAuE;AAAvE,cAAa,qBAAA,EAAuB,aAAa,CAAC,qBAAA;AAAA,KAItC,iBAAA,GAAoB,kBAAkB;AAAA,KAEtC,kBAAA,GAAqB,6BAA6B;AAAA,KAElD,eAAA,GAAkB,gBAAgB;AAAA,cAAA,gCAAA;;;;cAGjC,2BAAA,SAAoC,gCAAA;EAAA,SACtC,KAAA;EAAA,SACA,MAAA;AAAA;EAAA,IAEI,OAAA,CAAA;AAAA;AAAA,KAKH,sBAAA;EAZkC,oFAcnC,IAAA,GAAO,mBAAA;WAEP,GAAA;WAEA,MAAA,GAAS,qBAAqB;AAAA;AAAA,KAG7B,eAAA;sFAED,KAAA,GAAQ,OAAA,EAAS,OAAA,KAAY,OAAA,CAAQ,QAAA;EAAA,SACrC,MAAA;IAAA,SACE,OAAA,QAAe,aAAA,CAAc,kBAAA;IAAA,SAC7B,KAAA;EAAA;EAAA,SAEF,MAAA;2FAEE,GAAA,GAAM,KAAA,EAAO,aAAA,KAAkB,iBAAA;IAAA,SAC/B,IAAA,QAAY,aAAA,CAAc,iBAAA;IAAA,SAC1B,KAAA;EAAA;WAGF,OAAA,QAAe,aAAA,CAAc,aAAA;WAE7B,KAAA,QAAa,OAAA;;;;;WAKb,IAAA,GAAO,IAAA,EAAM,mBAAA,KAAwB,OAAA,QAvCnC;EAAA,SAyCF,QAAA,QAAgB,oBAAA;EAAA,SAChB,QAAA,QAAgB,eAAA,EA1CsB;EAAA,SA4CtC,KAAA,QAAa,OAAA;AAAA;;;;AAxCF;AAKtB;;;;;;cAwHa,mBAAA,GACX,OAAA,GAAS,sBAAA,KACR,OAAA,CAAQ,eAAA"}

package/dist/todoist.mjs

@@ -0,0 +1,181 @@
+import { emulatorEvidenceHeader } from "./route-evidence.mjs";
+import { StatefulFault, StatefulFaultMatch, makeHeaderlessStatefulEmulator, routeEvidence } from "./stateful-emulator.mjs";
+import { statefulCoreRuntime } from "./stateful-core.mjs";
+import { TodoistEmulatorDue, TodoistEmulatorLabel, TodoistEmulatorProfile, TodoistEmulatorProject, TodoistEmulatorProjectSeed, TodoistEmulatorSeed, TodoistEmulatorStateSchema, TodoistEmulatorTask, TodoistEmulatorTaskSeed, buildTodoistSeedState, decodeTodoistState } from "./todoist/state.mjs";
+import { matchTodoistRoute, todoistApiRoutes, todoistEmulatorBasePath, todoistQueryProblem } from "./todoist/api.mjs";
+import { Data, Predicate } from "effect";
+//#region src/todoist.ts
+/**
+* Stateful Todoist emulator (API v1 under `https://api.todoist.com/api/v1`), built on the upstream
+* `@emulators/core` custom runtime, with a request ledger, status faults, and an `/_emulate/*`
+* control plane.
+*
+* Fixture-only: it never imports SDK code; its wire shapes and default seed are copied as data
+* from the synthetic Todoist conformance fixtures, and every route names the conformance cases it
+* follows in `todoistEmulatorRoutes`. Only the routes the seven Todoist cases (with their cleanup)
+* need are emulated; anything the fixtures do not record answers one ledgered 400
+* `{ error: { type: 'not_emulated', message } }`. That includes the project listing of the
+* read-only leftover lookup (`findTodoistConformanceLeftovers`), which no fixture records: the
+* lookup fails (`todoist_list_projects_failed`, HTTP 400), and runners print their lookup-failed
+* WARN instead of leftover warnings.
+*
+* Fail closed: a request on no emulated route (or with a raw id segment that is not a Todoist id)
+* is ledgered and answered with constant text only (`/<unrecognised>`, a standard method or
+* `<other>`, no query or body, a constant reason). So is a request whose `Authorization` header is
+* present but is not one recognisable bearer, whatever its route: its credential cannot be
+* extracted and scrubbed.
+*
+* No answer is synthesised: a seeded project (whose object no fixture records) answers
+* not-emulated on a read; only items created through the recorded create flow are updated,
+* closed, or deleted; a case project takes one task and a seeded parent one sub-project (the
+* fixtures record `child_order: 1` only). Minted ids use the reserved prefix `6XEmu`, which seeds
+* may not use. The bearer value is guarded like the Telegram token: scrubbed from everything
+* ledgered or answered, and a path, query, or body that repeats it is refused.
+*
+* Request-shape latitude (the only accepted deviations from the fixture requests): any credential
+* value of at least 8 characters that occurs nowhere else in the request (its path, query, or body;
+* never checked against anything, stored, or ledgered); extra request headers; `content-type`
+* parameters; query parameters in any order; any Todoist id (1-64 of `[A-Za-z0-9_-]`) of an
+* existing item where a fixture has an id (reads: seeded or created tasks and created projects;
+* task listings: the paging project with `limit=2` and case projects created here without `limit`;
+* writes: only items created through the recorded create flow; a new project's `parent_id`: a
+* seeded project); any `run-` run id (at most 40 characters) in a case project name; any non-empty
+* task `content`; a task update sending `content`, `due_datetime`, or both; a label listing `limit`
+* of 1 to 200 that covers every label.
+*
+* Node-only: `@emulators/core` imports Node builtins, so the core is loaded lazily by
+* `makeTodoistEmulator` (importing this module has no side effects).
+*
+* @experimental
+*/
+/** Origin the connector calls. */
+const todoistEmulatorDefaultOrigin = "https://api.todoist.com";
+/**
+* Route evidence manifest: every emulated route, whether it writes, and the conformance cases
+* whose (currently synthetic, unverified) wire claims it follows. Kept in sync with the handlers
+* by construction (both come from one route table). Every route cites at least one case.
+*/
+const todoistEmulatorRoutes = todoistApiRoutes.map(({ route }) => routeEvidence(route));
+/** Invalid emulator input from the JS API: a seed or a fault. A programmer error. */
+var TodoistEmulatorInputInvalid = class extends Data.TaggedError("TodoistEmulatorInputInvalid") {
+	get message() {
+		return `Invalid Todoist emulator ${this.input}: ${this.reason}`;
+	}
+};
+const bearerPattern = /^bearer\s+(\S{8,})\s*$/i;
+const resolve = (request, url) => {
+	const ledgerPath = url.pathname;
+	const authorization = request.headers.get("authorization");
+	const bearer = bearerPattern.exec(authorization ?? "")?.[1];
+	if (authorization !== null && bearer === void 0) return {
+		kind: "unrecognised",
+		reason: "an unrecognisable Authorization header is not emulated"
+	};
+	const secrets = bearer === void 0 ? [] : [bearer];
+	const matched = matchTodoistRoute(request.method, url.pathname);
+	if (matched === void 0) return {
+		kind: "unrecognised",
+		reason: "no emulated Todoist route for this method and path"
+	};
+	const refuse = (reason) => ({
+		kind: "refused",
+		ledgerPath,
+		reason,
+		route: matched.route.route,
+		secrets
+	});
+	if (bearer === void 0) return refuse("requests without Authorization: Bearer <token of at least 8 characters> are not emulated");
+	const problem = todoistQueryProblem(matched.route, url.searchParams);
+	if (problem !== void 0) return refuse(problem);
+	return {
+		kind: "route",
+		ledgerPath,
+		route: matched.route.route,
+		params: matched.params,
+		guardedPath: `${url.pathname}${url.search}`,
+		secrets
+	};
+};
+/** The texts of Todoist's recovery answers (500 failed, 503 closed, 500 unhandled). */
+const errorTexts = {
+	failed: "Synthetic: the emulator could not build the response.",
+	closed: "Synthetic: the emulator is closed.",
+	unhandled: "emulator failed to handle the request"
+};
+/** The wrapper reports invalid seeds and faults only (Todoist takes no other option input). */
+const inputInvalid = (input, reason) => new TodoistEmulatorInputInvalid({
+	input: input === "seed" ? "seed" : "fault",
+	reason
+});
+/**
+* Create a stateful Todoist emulator on the `@emulators/core` custom runtime. Each call has its
+* own state, ledger, faults, and cursors. Rejects with `TodoistEmulatorInputInvalid` for an
+* invalid seed.
+*
+* Routes (under `/api/v1`, `Authorization: Bearer <token of at least 8 characters>`): task
+* listing with cursor paging, task read, create, update, and close, label listing, and project
+* create, read, and delete.
+* See `README.md` (Todoist emulator) for the wire claims.
+*/
+const makeTodoistEmulator = async (options = {}) => {
+	const initial = buildTodoistSeedState(options.seed ?? {});
+	if (Predicate.isString(initial)) throw new TodoistEmulatorInputInvalid({
+		input: "seed",
+		reason: initial
+	});
+	const drills = options.drills ?? {};
+	const env = {
+		now: options.now ?? (() => Date.now()),
+		drills: {
+			cursorRestarts: drills.cursorRestarts ?? false,
+			notFoundWithoutError: drills.notFoundWithoutError ?? false,
+			taskLabelsAsIds: drills.taskLabelsAsIds ?? false,
+			listIncludesClosed: drills.listIncludesClosed ?? false,
+			ignoreDue: drills.ignoreDue ?? false,
+			createOmitsParent: drills.createOmitsParent ?? false,
+			deleteKeepsTasks: drills.deleteKeepsTasks ?? false
+		},
+		cursors: /* @__PURE__ */ new Map(),
+		cursorCounter: { next: 1 }
+	};
+	const cursorList = () => [...env.cursors.values()];
+	const emulator = await makeHeaderlessStatefulEmulator({
+		routes: todoistApiRoutes.map(({ route }) => route),
+		env,
+		initial,
+		buildSeed: buildTodoistSeedState,
+		resolveRequest: resolve,
+		errorTexts,
+		clearRuntime: () => {
+			env.cursors.clear();
+			env.cursorCounter.next = 1;
+		},
+		runtimeState: () => ({ runtime: { cursors: cursorList().map((cursor) => ({ ...cursor })) } }),
+		seedSummary: (state) => ({
+			projects: state.projects.length,
+			tasks: state.tasks.length,
+			labels: state.labels.length
+		}),
+		inputInvalid
+	}, statefulCoreRuntime({
+		name: "todoist",
+		initial,
+		decodeState: decodeTodoistState,
+		inputInvalid
+	}));
+	return {
+		fetch: emulator.fetch,
+		ledger: emulator.ledger,
+		faults: emulator.faults,
+		cursors: cursorList,
+		reset: emulator.reset,
+		seed: emulator.seed,
+		snapshot: emulator.snapshot,
+		coverage: emulator.coverage,
+		close: emulator.close
+	};
+};
+//#endregion
+export { TodoistEmulatorDue, TodoistEmulatorInputInvalid, TodoistEmulatorLabel, TodoistEmulatorProfile, TodoistEmulatorProject, TodoistEmulatorProjectSeed, TodoistEmulatorSeed, TodoistEmulatorStateSchema, TodoistEmulatorTask, TodoistEmulatorTaskSeed, StatefulFault as TodoistFault, StatefulFaultMatch as TodoistFaultMatch, emulatorEvidenceHeader, makeTodoistEmulator, todoistEmulatorBasePath, todoistEmulatorDefaultOrigin, todoistEmulatorRoutes };
+
+//# sourceMappingURL=todoist.mjs.map

package/dist/todoist.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"todoist.mjs","names":[],"sources":["../src/todoist.ts"],"sourcesContent":["/**\n * Stateful Todoist emulator (API v1 under `https://api.todoist.com/api/v1`), built on the upstream\n * `@emulators/core` custom runtime, with a request ledger, status faults, and an `/_emulate/*`\n * control plane.\n *\n * Fixture-only: it never imports SDK code; its wire shapes and default seed are copied as data\n * from the synthetic Todoist conformance fixtures, and every route names the conformance cases it\n * follows in `todoistEmulatorRoutes`. Only the routes the seven Todoist cases (with their cleanup)\n * need are emulated; anything the fixtures do not record answers one ledgered 400\n * `{ error: { type: 'not_emulated', message } }`. That includes the project listing of the\n * read-only leftover lookup (`findTodoistConformanceLeftovers`), which no fixture records: the\n * lookup fails (`todoist_list_projects_failed`, HTTP 400), and runners print their lookup-failed\n * WARN instead of leftover warnings.\n *\n * Fail closed: a request on no emulated route (or with a raw id segment that is not a Todoist id)\n * is ledgered and answered with constant text only (`/<unrecognised>`, a standard method or\n * `<other>`, no query or body, a constant reason). So is a request whose `Authorization` header is\n * present but is not one recognisable bearer, whatever its route: its credential cannot be\n * extracted and scrubbed.\n *\n * No answer is synthesised: a seeded project (whose object no fixture records) answers\n * not-emulated on a read; only items created through the recorded create flow are updated,\n * closed, or deleted; a case project takes one task and a seeded parent one sub-project (the\n * fixtures record `child_order: 1` only). Minted ids use the reserved prefix `6XEmu`, which seeds\n * may not use. The bearer value is guarded like the Telegram token: scrubbed from everything\n * ledgered or answered, and a path, query, or body that repeats it is refused.\n *\n * Request-shape latitude (the only accepted deviations from the fixture requests): any credential\n * value of at least 8 characters that occurs nowhere else in the request (its path, query, or body;\n * never checked against anything, stored, or ledgered); extra request headers; `content-type`\n * parameters; query parameters in any order; any Todoist id (1-64 of `[A-Za-z0-9_-]`) of an\n * existing item where a fixture has an id (reads: seeded or created tasks and created projects;\n * task listings: the paging project with `limit=2` and case projects created here without `limit`;\n * writes: only items created through the recorded create flow; a new project's `parent_id`: a\n * seeded project); any `run-` run id (at most 40 characters) in a case project name; any non-empty\n * task `content`; a task update sending `content`, `due_datetime`, or both; a label listing `limit`\n * of 1 to 200 that covers every label.\n *\n * Node-only: `@emulators/core` imports Node builtins, so the core is loaded lazily by\n * `makeTodoistEmulator` (importing this module has no side effects).\n *\n * @experimental\n */\nimport { Data, Predicate } from 'effect'\nimport type { EmulatorRouteEvidence } from './route-evidence.ts'\nimport { statefulCoreRuntime } from './stateful-core.ts'\nimport {\n  makeHeaderlessStatefulEmulator,\n  routeEvidence,\n  type StatefulCoverage,\n  type StatefulFault,\n  type StatefulFaultState,\n  type StatefulHeaderlessLedgerEntry,\n  type StatefulErrorTexts,\n  type StatefulInputKind,\n  type StatefulResolution\n} from './stateful-emulator.ts'\nimport {\n  matchTodoistRoute,\n  todoistApiRoutes,\n  todoistQueryProblem,\n  type TodoistApiEnv,\n  type TodoistCursor,\n  type TodoistEmulatorDrills\n} from './todoist/api.ts'\nimport {\n  buildTodoistSeedState,\n  decodeTodoistState,\n  type TodoistEmulatorSeed,\n  type TodoistEmulatorState\n} from './todoist/state.ts'\n\nexport type { EmulatorEvidence, EmulatorRouteEvidence } from './route-evidence.ts'\n\nexport { emulatorEvidenceHeader } from './route-evidence.ts'\n\nexport {\n  StatefulFault as TodoistFault,\n  StatefulFaultMatch as TodoistFaultMatch\n} from './stateful-emulator.ts'\n\nexport { todoistEmulatorBasePath, type TodoistEmulatorDrills } from './todoist/api.ts'\n\nexport {\n  TodoistEmulatorDue,\n  TodoistEmulatorLabel,\n  TodoistEmulatorProfile,\n  TodoistEmulatorProject,\n  TodoistEmulatorProjectSeed,\n  TodoistEmulatorSeed,\n  TodoistEmulatorStateSchema,\n  TodoistEmulatorTask,\n  TodoistEmulatorTaskSeed,\n  type TodoistEmulatorState\n} from './todoist/state.ts'\n\n/** Origin the connector calls. */\nexport const todoistEmulatorDefaultOrigin = 'https://api.todoist.com'\n\n/**\n * Route evidence manifest: every emulated route, whether it writes, and the conformance cases\n * whose (currently synthetic, unverified) wire claims it follows. Kept in sync with the handlers\n * by construction (both come from one route table). Every route cites at least one case.\n */\nexport const todoistEmulatorRoutes: ReadonlyArray<EmulatorRouteEvidence> = todoistApiRoutes.map(\n  ({ route }) => routeEvidence(route)\n)\n\nexport type TodoistFaultState = StatefulFaultState\n\nexport type TodoistLedgerEntry = StatefulHeaderlessLedgerEntry\n\nexport type TodoistCoverage = StatefulCoverage\n\n/** Invalid emulator input from the JS API: a seed or a fault. A programmer error. */\nexport class TodoistEmulatorInputInvalid extends Data.TaggedError('TodoistEmulatorInputInvalid')<{\n  readonly input: 'seed' | 'fault'\n  readonly reason: string\n}> {\n  override get message(): string {\n    return `Invalid Todoist emulator ${this.input}: ${this.reason}`\n  }\n}\n\nexport type TodoistEmulatorOptions = {\n  /** Typed seed; defaults to the fixture entities (`profile: 'default'`). */\n  readonly seed?: TodoistEmulatorSeed\n  /** Clock in epoch milliseconds (created and closed timestamps). Defaults to `Date.now`. */\n  readonly now?: () => number\n  /** Drill knobs (tests only): make the emulator disagree with one conformance claim. */\n  readonly drills?: TodoistEmulatorDrills\n}\n\nexport type TodoistEmulator = {\n  /** The fetch handler (Todoist routes and `/_emulate/*`). Never rejects. */\n  readonly fetch: (request: Request) => Promise<Response>\n  readonly ledger: {\n    readonly entries: () => ReadonlyArray<TodoistLedgerEntry>\n    readonly clear: () => void\n  }\n  readonly faults: {\n    /** Add a fault; throws `TodoistEmulatorInputInvalid` for an invalid fault. */\n    readonly add: (fault: StatefulFault) => TodoistFaultState\n    readonly list: () => ReadonlyArray<TodoistFaultState>\n    readonly clear: () => void\n  }\n  /** Task-listing cursors answered since the last reset or seed (runtime data). */\n  readonly cursors: () => ReadonlyArray<TodoistCursor>\n  /** Restore the current seed and clear the ledger, faults, and cursors. */\n  readonly reset: () => Promise<void>\n  /**\n   * Replace the state with a new seed, which becomes what `reset` restores (cursors are cleared).\n   * Rejects with `TodoistEmulatorInputInvalid` for an invalid seed.\n   */\n  readonly seed: (seed: TodoistEmulatorSeed) => Promise<void>\n  /** A deep copy of the current state (entities and counters). */\n  readonly snapshot: () => TodoistEmulatorState\n  readonly coverage: () => TodoistCoverage\n  /** Close the core runtime. Later requests answer 503. Idempotent. */\n  readonly close: () => Promise<void>\n}\n\n// A bearer credential of at least 8 characters. The value is never checked against anything,\n// stored, forwarded, or ledgered; it is guarded like the Telegram token: a path, query, or body\n// that repeats it is refused, and it is scrubbed from everything ledgered or answered.\nconst bearerPattern = /^bearer\\s+(\\S{8,})\\s*$/i\n\nconst resolve = (\n  request: Request,\n  url: URL\n): StatefulResolution<TodoistEmulatorState, TodoistApiEnv> => {\n  const ledgerPath = url.pathname\n  const authorization = request.headers.get('authorization')\n  const bearer = bearerPattern.exec(authorization ?? '')?.[1]\n\n  // Fail closed: an Authorization header that is present but not one recognisable bearer (extra\n  // words, duplicated headers) means the credential cannot be extracted and scrubbed, so the\n  // request is ledgered and answered with constant text only, whatever the route.\n  if (authorization !== null && bearer === undefined) {\n    return {\n      kind: 'unrecognised',\n      reason: 'an unrecognisable Authorization header is not emulated'\n    }\n  }\n\n  // On a recognised route the bearer value is guarded (scrubbed and never repeated).\n  const secrets = bearer === undefined ? [] : [bearer]\n  const matched = matchTodoistRoute(request.method, url.pathname)\n\n  // Fail closed: a request on no emulated route is ledgered and answered with constant text only.\n  if (matched === undefined) {\n    return { kind: 'unrecognised', reason: 'no emulated Todoist route for this method and path' }\n  }\n\n  const refuse = (reason: string): StatefulResolution<TodoistEmulatorState, TodoistApiEnv> => ({\n    kind: 'refused',\n    ledgerPath,\n    reason,\n    route: matched.route.route,\n    secrets\n  })\n\n  if (bearer === undefined) {\n    return refuse(\n      'requests without Authorization: Bearer <token of at least 8 characters> are not emulated'\n    )\n  }\n\n  const problem = todoistQueryProblem(matched.route, url.searchParams)\n\n  if (problem !== undefined) return refuse(problem)\n\n  return {\n    kind: 'route',\n    ledgerPath,\n    route: matched.route.route,\n    params: matched.params,\n    // The path and query the request must not repeat the bearer in.\n    guardedPath: `${url.pathname}${url.search}`,\n    secrets\n  }\n}\n\n/** The texts of Todoist's recovery answers (500 failed, 503 closed, 500 unhandled). */\nconst errorTexts: StatefulErrorTexts = {\n  failed: 'Synthetic: the emulator could not build the response.',\n  closed: 'Synthetic: the emulator is closed.',\n  unhandled: 'emulator failed to handle the request'\n}\n\n/** The wrapper reports invalid seeds and faults only (Todoist takes no other option input). */\nconst inputInvalid = (input: StatefulInputKind, reason: string) =>\n  new TodoistEmulatorInputInvalid({ input: input === 'seed' ? 'seed' : 'fault', reason })\n\n/**\n * Create a stateful Todoist emulator on the `@emulators/core` custom runtime. Each call has its\n * own state, ledger, faults, and cursors. Rejects with `TodoistEmulatorInputInvalid` for an\n * invalid seed.\n *\n * Routes (under `/api/v1`, `Authorization: Bearer <token of at least 8 characters>`): task\n * listing with cursor paging, task read, create, update, and close, label listing, and project\n * create, read, and delete.\n * See `README.md` (Todoist emulator) for the wire claims.\n */\nexport const makeTodoistEmulator = async (\n  options: TodoistEmulatorOptions = {}\n): Promise<TodoistEmulator> => {\n  const initial = buildTodoistSeedState(options.seed ?? {})\n\n  if (Predicate.isString(initial)) {\n    throw new TodoistEmulatorInputInvalid({ input: 'seed', reason: initial })\n  }\n\n  const drills = options.drills ?? {}\n\n  const env: TodoistApiEnv = {\n    now: options.now ?? (() => Date.now()),\n    drills: {\n      cursorRestarts: drills.cursorRestarts ?? false,\n      notFoundWithoutError: drills.notFoundWithoutError ?? false,\n      taskLabelsAsIds: drills.taskLabelsAsIds ?? false,\n      listIncludesClosed: drills.listIncludesClosed ?? false,\n      ignoreDue: drills.ignoreDue ?? false,\n      createOmitsParent: drills.createOmitsParent ?? false,\n      deleteKeepsTasks: drills.deleteKeepsTasks ?? false\n    },\n    cursors: new Map(),\n    cursorCounter: { next: 1 }\n  }\n\n  const cursorList = (): ReadonlyArray<TodoistCursor> => [...env.cursors.values()]\n\n  const emulator = await makeHeaderlessStatefulEmulator<\n    TodoistEmulatorState,\n    TodoistApiEnv,\n    TodoistEmulatorSeed\n  >(\n    {\n      routes: todoistApiRoutes.map(({ route }) => route),\n      env,\n      initial,\n      buildSeed: buildTodoistSeedState,\n      resolveRequest: resolve,\n      errorTexts,\n      clearRuntime: () => {\n        env.cursors.clear()\n        env.cursorCounter.next = 1\n      },\n      runtimeState: () => ({ runtime: { cursors: cursorList().map(cursor => ({ ...cursor })) } }),\n      seedSummary: state => ({\n        projects: state.projects.length,\n        tasks: state.tasks.length,\n        labels: state.labels.length\n      }),\n      inputInvalid\n    },\n    statefulCoreRuntime({\n      name: 'todoist',\n      initial,\n      decodeState: decodeTodoistState,\n      inputInvalid\n    })\n  )\n\n  return {\n    fetch: emulator.fetch,\n    ledger: emulator.ledger,\n    faults: emulator.faults,\n    cursors: cursorList,\n    reset: emulator.reset,\n    seed: emulator.seed,\n    snapshot: emulator.snapshot,\n    coverage: emulator.coverage,\n    close: emulator.close\n  }\n}\n"],"mappings":"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"}

package/dist/xai.d.mts

@@ -0,0 +1,267 @@
+import { EmulatorEvidence, EmulatorRouteEvidence, emulatorEvidenceHeader } from "./route-evidence.mjs";
+import { EmulatorCoverage, EmulatorFaultMatch, EmulatorFaultState, EmulatorRouteCoverage, EmulatorScriptedError } from "./emulator-kernel.mjs";
+import { SubscriptionUsageEmulator, SubscriptionUsageFault, SubscriptionUsageLedgerEntry, SubscriptionUsageScriptedTurn } from "./subscription-usage.mjs";
+import { ResponsesEmulator, ResponsesErrorEventFault, ResponsesFault, ResponsesFaultKind, ResponsesLedgerEntry, ResponsesScriptedFunctionCall, ResponsesScriptedResponse, ResponsesScriptedTurn, ResponsesScriptedUsage, ResponsesStreamError } from "./responses.mjs";
+import * as Schema from "effect/Schema";
+
+//#region src/xai.d.ts
+declare const xAiGrokResponsesPath = "/v1/responses";
+/**
+ * The Grok subscription-usage path; the SDK fetcher (`xAiGrokSubscriptionUsageUrl`) adds
+ * `?format=credits`, the recorded query.
+ */
+declare const xAiGrokSubscriptionUsagePath = "/v1/billing";
+/**
+ * Route evidence manifest of the Grok subscription-usage route (served by the same fetch handler
+ * as the Responses route, with its own ledger and coverage). Synthetic, unverified.
+ */
+declare const xAiGrokSubscriptionUsageEmulatorRoutes: ReadonlyArray<EmulatorRouteEvidence>;
+/**
+ * The recorded Grok usage body (the synthetic `xai.grok.usage.snapshot` fixture, copied as data):
+ * `config.creditUsagePercent` and `config.currentPeriod` `{ type, start, end }`.
+ */
+declare const xAiGrokSubscriptionUsageDefault: Schema.Json;
+/** Synthetic-safe default model ids, including the Grok conformance defaults. */
+declare const xAiGrokEmulatorDefaultModels: ReadonlyArray<string>;
+/**
+ * Route evidence manifest: every emulated Grok route and the conformance cases whose (currently
+ * synthetic, unverified) wire shapes it follows.
+ */
+declare const xAiGrokEmulatorRoutes: ReadonlyArray<EmulatorRouteEvidence>;
+/** Optional fault filter; an omitted field matches every request. `path` ending in `*` is a prefix. */
+declare const XAiGrokFaultMatch: Schema.Struct<{
+  readonly path: Schema.optionalKey<Schema.String>;
+  readonly model: Schema.optionalKey<Schema.String>;
+}>;
+type XAiGrokFaultMatch = typeof EmulatorFaultMatch.Type;
+/** A mid-stream Responses error (`{ code, message }`). */
+declare const XAiGrokStreamError: Schema.Struct<{
+  readonly code: Schema.NonEmptyString;
+  readonly message: Schema.String;
+}>;
+type XAiGrokStreamError = ResponsesStreamError;
+/** A mid-stream `error` or `response.failed` event fault, streamed responses only. */
+declare const XAiGrokErrorEventFault: Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"error-event-after-chunks">;
+  readonly chunks: Schema.Int;
+  readonly event: Schema.optionalKey<Schema.Literals<readonly ["error", "response.failed"]>>;
+  readonly error: Schema.optionalKey<Schema.Struct<{
+    readonly code: Schema.NonEmptyString;
+    readonly message: Schema.String;
+  }>>;
+}>;
+type XAiGrokErrorEventFault = typeof ResponsesErrorEventFault.Type;
+/**
+ * Wire faults: `status` (for example 429 with `retry-after`; the body defaults to the error
+ * envelope for the status), `error-after-chunks` (a dropped connection),
+ * `truncate-after-chunks` (a clean close, for example before `response.completed`), and
+ * `error-event-after-chunks` (a mid-stream `error` or `response.failed` event). Statuses that
+ * cannot carry a body and redirects are rejected, as are invalid headers and `location`. A fault
+ * that cannot take effect answers 500 and is not consumed.
+ */
+declare const XAiGrokFault: Schema.Union<readonly [Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"status">;
+  readonly status: Schema.Int;
+  readonly headers: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+  readonly body: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>, Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"error-after-chunks">;
+  readonly chunks: Schema.Int;
+}>, Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"truncate-after-chunks">;
+  readonly chunks: Schema.Int;
+}>, Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"error-event-after-chunks">;
+  readonly chunks: Schema.Int;
+  readonly event: Schema.optionalKey<Schema.Literals<readonly ["error", "response.failed"]>>;
+  readonly error: Schema.optionalKey<Schema.Struct<{
+    readonly code: Schema.NonEmptyString;
+    readonly message: Schema.String;
+  }>>;
+}>]>;
+type XAiGrokFault = ResponsesFault;
+type XAiGrokFaultKind = ResponsesFaultKind;
+/** Usage for a scripted turn (sent in `response.completed` or the JSON body). */
+declare const XAiGrokScriptedUsage: Schema.Struct<{
+  readonly inputTokens: Schema.Int;
+  readonly outputTokens: Schema.Int;
+  readonly reasoningTokens: Schema.optionalKey<Schema.Int>;
+}>;
+type XAiGrokScriptedUsage = ResponsesScriptedUsage;
+/** One scripted `function_call` item; its arguments stream as these fragments. */
+declare const XAiGrokScriptedFunctionCall: Schema.Struct<{
+  readonly name: Schema.NonEmptyString;
+  readonly argumentFragments: Schema.$Array<Schema.String>;
+  readonly callId: Schema.optionalKey<Schema.NonEmptyString>;
+}>;
+type XAiGrokScriptedFunctionCall = ResponsesScriptedFunctionCall;
+/**
+ * A scripted response: `reasoning` (summary fragments), `text`, `functionCalls`, `order`,
+ * `usage` (`null` drops it), and `format` (`sse` or `json`, default: the request's `stream`).
+ */
+declare const XAiGrokScriptedResponse: Schema.Struct<{
+  readonly reasoning: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly text: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly functionCalls: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly argumentFragments: Schema.$Array<Schema.String>;
+    readonly callId: Schema.optionalKey<Schema.NonEmptyString>;
+  }>>>;
+  readonly order: Schema.optionalKey<Schema.Literals<readonly ["reasoning-first", "text-first"]>>;
+  readonly usage: Schema.optionalKey<Schema.NullOr<Schema.Struct<{
+    readonly inputTokens: Schema.Int;
+    readonly outputTokens: Schema.Int;
+    readonly reasoningTokens: Schema.optionalKey<Schema.Int>;
+  }>>>;
+  readonly format: Schema.optionalKey<Schema.Literals<readonly ["sse", "json"]>>;
+}>;
+type XAiGrokScriptedResponse = ResponsesScriptedResponse;
+/** A scripted error response: status, body (a string is sent as is), and optional headers. */
+declare const XAiGrokScriptedError: Schema.Struct<{
+  readonly error: Schema.Struct<{
+    readonly status: Schema.Int;
+    readonly body: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly headers: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+  }>;
+}>;
+type XAiGrokScriptedError = typeof EmulatorScriptedError.Type;
+/** A turn queued for the next Grok request. */
+declare const XAiGrokScriptedTurn: Schema.Union<readonly [Schema.Struct<{
+  readonly error: Schema.Struct<{
+    readonly status: Schema.Int;
+    readonly body: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly headers: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+  }>;
+}>, Schema.Struct<{
+  readonly reasoning: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly text: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly functionCalls: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly argumentFragments: Schema.$Array<Schema.String>;
+    readonly callId: Schema.optionalKey<Schema.NonEmptyString>;
+  }>>>;
+  readonly order: Schema.optionalKey<Schema.Literals<readonly ["reasoning-first", "text-first"]>>;
+  readonly usage: Schema.optionalKey<Schema.NullOr<Schema.Struct<{
+    readonly inputTokens: Schema.Int;
+    readonly outputTokens: Schema.Int;
+    readonly reasoningTokens: Schema.optionalKey<Schema.Int>;
+  }>>>;
+  readonly format: Schema.optionalKey<Schema.Literals<readonly ["sse", "json"]>>;
+}>]>;
+type XAiGrokScriptedTurn = ResponsesScriptedTurn;
+declare const XAiGrokEmulatorInputInvalid_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "XAiGrokEmulatorInputInvalid";
+} & Readonly<A>;
+/** Thrown by the JS API (`faults.add`, `script.enqueue`) for invalid input; a programmer error. */
+declare class XAiGrokEmulatorInputInvalid extends XAiGrokEmulatorInputInvalid_base<{
+  readonly input: 'fault' | 'turn';
+  readonly reason: string;
+}> {
+  get message(): string;
+}
+type XAiGrokLedgerEntry = ResponsesLedgerEntry;
+type XAiGrokFaultState = EmulatorFaultState<XAiGrokFault>;
+type XAiGrokRouteCoverage = EmulatorRouteCoverage;
+type XAiGrokCoverage = EmulatorCoverage;
+/** A usage-route fault (`status`, `error-after-chunks`, `truncate-after-chunks`). */
+declare const XAiGrokUsageFault: Schema.Union<readonly [Schema.Struct<{
+  readonly status: Schema.Int;
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"status">;
+  readonly headers: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+  readonly body: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>, Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"error-after-chunks">;
+  readonly chunks: Schema.Int;
+}>, Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"truncate-after-chunks">;
+  readonly chunks: Schema.Int;
+}>]>;
+type XAiGrokUsageFault = SubscriptionUsageFault;
+/** A usage turn: `{ usage }` (a body with the recorded JSON shape) or `{ error }`. */
+type XAiGrokUsageScriptedTurn = SubscriptionUsageScriptedTurn;
+type XAiGrokUsageLedgerEntry = SubscriptionUsageLedgerEntry;
+type XAiGrokUsageEmulator = SubscriptionUsageEmulator;
+type XAiGrokEmulatorOptions = {
+  /** Model ids that exist. Defaults to `xAiGrokEmulatorDefaultModels`. */readonly knownModels?: ReadonlyArray<string>;
+  /**
+   * Replacement usage-route body; must have the recorded JSON shape (same keys and value kinds).
+   * Defaults to the recorded body (`xAiGrokSubscriptionUsageDefault`).
+   */
+  readonly subscriptionUsage?: Schema.Json;
+};
+/** The Responses emulator, plus `usage`: the subscription-usage route's own emulator API. */
+type XAiGrokEmulator = ResponsesEmulator & {
+  readonly usage: XAiGrokUsageEmulator;
+};
+/**
+ * Create a Grok CLI proxy Responses emulator. Each call has independent ledger, fault, and script
+ * state.
+ *
+ * Without a script, `POST /v1/responses` answers a known model with synthetic output: `stream:
+ * true` streams `response.created`, `response.in_progress`, the output items
+ * (`response.output_item.added`, their parts and deltas, `response.output_item.done`), and
+ * `response.completed` with usage; `stream: false` returns one `response` JSON body. A request
+ * whose `reasoning` asks for a `summary` gets a reasoning item first. A request with function
+ * `tools` gets one `function_call` item whose arguments are synthesized from the tool's JSON
+ * Schema and streamed as `response.function_call_arguments.delta` fragments. Unknown models get
+ * 400 `model_not_found`; a request without a bearer credential gets 401 `invalid_api_key`,
+ * without `X-XAI-Token-Auth` 401, without `x-grok-client-version` 426, and without
+ * `x-grok-model-override` 400; a non-positive `max_output_tokens` gets 400; unknown routes get a
+ * 404 envelope. Not enforced: that `x-grok-model-override` matches the body `model`, the client
+ * version value, and the output limit itself (recorded as `maxOutputTokens`).
+ *
+ * `GET /v1/billing?format=credits` is fixture-only: a request with the headers the SDK fetcher
+ * sends (a non-empty bearer, `X-XAI-Token-Auth: xai-grok-cli`, a non-empty `x-userid`, a
+ * non-empty `x-grok-client-version`, and `x-grok-client-mode: headless`; the bearer, user id, and
+ * client-version values are request-shape latitude, and the user id and token-auth are never
+ * recorded),
+ * `accept: application/json`, and exactly the recorded `format=credits` query gets the recorded
+ * body (`xAiGrokSubscriptionUsageDefault`, or a same-shaped `options.subscriptionUsage` / scripted
+ * `{ usage }`); anything else answers 400 not-emulated. The client version and mode are recorded.
+ * Its ledger, faults, turns, and coverage are `emulator.usage`
+ * (control plane `/_emulate/usage/*`); `reset()` and `POST /_emulate/reset` reset both routes.
+ */
+declare const makeXAiGrokEmulator: (options?: XAiGrokEmulatorOptions) => XAiGrokEmulator;
+//#endregion
+export { type EmulatorEvidence, type EmulatorRouteEvidence, XAiGrokCoverage, XAiGrokEmulator, XAiGrokEmulatorInputInvalid, XAiGrokEmulatorOptions, XAiGrokErrorEventFault, XAiGrokFault, XAiGrokFaultKind, XAiGrokFaultMatch, XAiGrokFaultState, XAiGrokLedgerEntry, XAiGrokRouteCoverage, XAiGrokScriptedError, XAiGrokScriptedFunctionCall, XAiGrokScriptedResponse, XAiGrokScriptedTurn, XAiGrokScriptedUsage, XAiGrokStreamError, XAiGrokUsageEmulator, XAiGrokUsageFault, XAiGrokUsageLedgerEntry, XAiGrokUsageScriptedTurn, emulatorEvidenceHeader, makeXAiGrokEmulator, xAiGrokEmulatorDefaultModels, xAiGrokEmulatorRoutes, xAiGrokResponsesPath, xAiGrokSubscriptionUsageDefault, xAiGrokSubscriptionUsageEmulatorRoutes, xAiGrokSubscriptionUsagePath };
+//# sourceMappingURL=xai.d.mts.map

package/dist/xai.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xai.d.mts","names":[],"sources":["../src/xai.ts"],"mappings":";;;;;;;cAiEa,oBAAA;;;AAAoB;AAMjC;cAAa,4BAAA;;;AAA4B;AAMzC;cAAa,sCAAA,EAAwC,aAAa,CAAC,qBAAA;;;AAAqB;AAgBxF;cAAa,+BAAA,EAAiC,MAAA,CAAO,IAA+C;;cAGvF,4BAAA,EAA8B,aAAa;AAH4C;AAGpG;;;AAHoG,cASvF,qBAAA,EAAuB,aAAa,CAAC,qBAAA;AANM;AAAA,cAwB3C,iBAAA,EAAiB,MAAA,CAAA,MAAA;EAAA;;;KAElB,iBAAA,UAA2B,kBAAA,CAAmB,IAAI;AAF9D;AAAA,cAKa,kBAAA,EAAkB,MAAA,CAAA,MAAA;EAAA;;;KAEnB,kBAAA,GAAqB,oBAAoB;;cAGxC,sBAAA,EAAsB,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;;KAEvB,sBAAA,UAAgC,wBAAA,CAAyB,IAAI;;;AAVzE;;;;AAA8D;AAG9D;cAiBa,YAAA,EAAY,MAAA,CAAA,KAAA,WAAA,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAEb,YAAA,GAAe,cAAc;AAAA,KAE7B,gBAAA,GAAmB,kBAAkB;;cAGpC,oBAAA,EAAoB,MAAA,CAAA,MAAA;EAAA;;;;KAErB,oBAAA,GAAuB,sBAAsB;;cAG5C,2BAAA,EAA2B,MAAA,CAAA,MAAA;EAAA;;;;KAE5B,2BAAA,GAA8B,6BAA6B;;;;;cAM1D,uBAAA,EAAuB,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;;;;KAExB,uBAAA,GAA0B,yBAAyB;;cAGlD,oBAAA,EAAoB,MAAA,CAAA,MAAA;EAAA;;;;;;KAErB,oBAAA,UAA8B,qBAAA,CAAsB,IAAI;;cAGvD,mBAAA,EAAmB,MAAA,CAAA,KAAA,WAAA,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;;;;;;;;;;KAEpB,mBAAA,GAAsB,qBAAqB;AAAA,cAAA,gCAAA;;;;cAG1C,2BAAA,SAAoC,gCAAA;EAAA,SACtC,KAAA;EAAA,SACA,MAAA;AAAA;EAAA,IAEI,OAAA,CAAA;AAAA;AAAA,KAKH,kBAAA,GAAqB,oBAAoB;AAAA,KAEzC,iBAAA,GAAoB,kBAAkB,CAAC,YAAA;AAAA,KAEvC,oBAAA,GAAuB,qBAAqB;AAAA,KAE5C,eAAA,GAAkB,gBAAgB;;cAGjC,iBAAA,EAAiB,MAAA,CAAA,KAAA,WAAA,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;KAElB,iBAAA,GAAoB,sBAAsB;;KAG1C,wBAAA,GAA2B,6BAA6B;AAAA,KAExD,uBAAA,GAA0B,4BAA4B;AAAA,KAEtD,oBAAA,GAAuB,yBAAyB;AAAA,KAEhD,sBAAA;EAhEa,iFAkEd,WAAA,GAAc,aAAA;EAlEA;;;;EAAA,SAuEd,iBAAA,GAAoB,MAAA,CAAO,IAAI;AAAA;;KAI9B,eAAA,GAAkB,iBAAA;EAAA,SAA+B,KAAA,EAAO,oBAAoB;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAuC3E,mBAAA,GAAuB,OAAA,GAAS,sBAAA,KAA8B,eAKxE"}