@w6w/sdk 0.1.0

package/dist/src/documents.js

@@ -0,0 +1,178 @@
+/**
+ * `client.documents.*` — the document store, addressed the way the server
+ * addresses it.
+ *
+ * Six operations, one HTTP call each. **Create by `key`, read by id or by key,
+ * update and delete by id** (`docs/implementation.md` §7, D6 amended by D12).
+ * There is no key-addressed façade over the id routes and no client-side
+ * list-then-filter anywhere in this file: a `getByKey` implemented as "list
+ * everything and scan" is O(n) over someone's whole store, it races, and a
+ * wrapper that has to compose two calls is describing an operation that belongs
+ * in the API.
+ *
+ * `getByKey` therefore targets a real route — `GET /documents/by-key/{key}`
+ * (verified live 2026-07-28).
+ *
+ * Documents are **project-scoped**: every route below accepts an optional
+ * `?project=`, resolved per call, then from the client's default, and otherwise
+ * left to the server (which picks the account's default project). Vars are not
+ * — see `src/vars.ts`.
+ *
+ * @module
+ */
+import { path } from "./http.js";
+import { unwrap } from "./types.js";
+/**
+ * The `documents` namespace on a `W6wClient`.
+ *
+ * @example
+ * ```ts
+ * const doc = await client.documents.create({ key: "welcome", content: "# Hi" });
+ * await client.documents.update(doc.id, { content: "# Hello" });
+ * await client.documents.delete(doc.id);
+ * ```
+ */
+export class DocumentsApi {
+    #host;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host) {
+        this.#host = host;
+    }
+    /**
+     * The project this call is scoped to: per-call argument first, then the
+     * client's default, then nothing at all — an absent value means "no
+     * `?project=`", which is how the caller asks for the account's default.
+     */
+    #project(options) {
+        return options?.project ?? this.#host.config.project ?? undefined;
+    }
+    /**
+     * List the caller's documents.
+     *
+     * @param options - Optional per-call project scope.
+     * @returns The documents, unwrapped from the `documents` envelope.
+     * @throws {ApiError} On any non-2xx, e.g. `400 unknown_project`.
+     */
+    async list(options) {
+        const res = await this.#host.request({
+            method: "GET",
+            path: "/documents",
+            query: { project: this.#project(options) },
+        });
+        return unwrap(res, "documents");
+    }
+    /**
+     * Fetch one document by its server-issued id.
+     *
+     * @param id - The `doc_…` id.
+     * @param options - Optional per-call project scope.
+     * @returns The document.
+     * @throws {ApiError} `404 unknown_document` when there is no such id.
+     */
+    async get(id, options) {
+        const res = await this.#host.request({
+            method: "GET",
+            path: path `/documents/${id}`,
+            query: { project: this.#project(options) },
+        });
+        return unwrap(res, "document");
+    }
+    /**
+     * Fetch one document by the `key` its author chose.
+     *
+     * The key is percent-encoded at interpolation by the `path` tag, which is not
+     * ceremony: the server accepts any non-empty key up to 128 characters, so
+     * `"a/b"` and `".."` are keys a user can legitimately create, and concatenated
+     * naively they address a *different route* — `".."` resolves to the list
+     * endpoint and returns every document with a `200` and no error anywhere.
+     *
+     * Encoding, never validation: a key the server accepts is sent as-is
+     * (encoded). This method does not reject, trim or canonicalise a key —
+     * refusing one locally would make a document that exists permanently
+     * unreadable through this client.
+     *
+     * @param key - The document key, sent encoded and otherwise untouched.
+     * @param options - Optional per-call project scope.
+     * @returns The document.
+     * @throws {ApiError} `404 unknown_document` when there is no such key.
+     */
+    async getByKey(key, options) {
+        const res = await this.#host.request({
+            method: "GET",
+            path: path `/documents/by-key/${key}`,
+            query: { project: this.#project(options) },
+        });
+        return unwrap(res, "document");
+    }
+    /**
+     * Create a document under a caller-chosen key.
+     *
+     * @param input - `key` and `content` are required; `format` defaults server-side to `"text"`.
+     * @param options - Optional per-call project scope.
+     * @returns The created document (the server answers `201`).
+     * @throws {ApiError} `409 document_exists` on a duplicate key — the code reaches the caller intact.
+     */
+    async create(input, options) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: "/documents",
+            query: { project: this.#project(options) },
+            // Assembled field by field rather than forwarded wholesale: the body that
+            // goes on the wire is exactly the four documented fields, and `undefined`
+            // ones are dropped by JSON serialisation.
+            body: {
+                key: input.key,
+                content: input.content,
+                format: input.format,
+                description: input.description,
+            },
+        });
+        return unwrap(res, "document");
+    }
+    /**
+     * Patch a document's content, format or description.
+     *
+     * Addressed by id, never by key, and the key itself cannot be changed.
+     *
+     * @param id - The `doc_…` id.
+     * @param patch - The fields to change; omitted fields are left alone.
+     * @param options - Optional per-call project scope.
+     * @returns The updated document.
+     * @throws {ApiError} `404 unknown_document` when there is no such id.
+     */
+    async update(id, patch, options) {
+        const res = await this.#host.request({
+            method: "PATCH",
+            path: path `/documents/${id}`,
+            query: { project: this.#project(options) },
+            body: {
+                content: patch.content,
+                format: patch.format,
+                description: patch.description,
+            },
+        });
+        return unwrap(res, "document");
+    }
+    /**
+     * Delete a document.
+     *
+     * Returns nothing: the server's `{ok: true}` carries no information a caller
+     * can use, and unwrapping it to a value would invite `if (await delete(...))`.
+     * Deleting an unknown id is `404 unknown_document`, **not** a silent success —
+     * the delete is not idempotent and this method does not pretend otherwise.
+     *
+     * @param id - The `doc_…` id.
+     * @param options - Optional per-call project scope.
+     * @throws {ApiError} `404 unknown_document` when there is no such id.
+     */
+    async delete(id, options) {
+        await this.#host.request({
+            method: "DELETE",
+            path: path `/documents/${id}`,
+            query: { project: this.#project(options) },
+        });
+    }
+}
+//# sourceMappingURL=documents.js.map

package/dist/src/documents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.js","sourceRoot":"","sources":["../../src/documents.ts"],"names":[],"mappings":"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"}

package/dist/src/env.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The **only** module in this package that reads the environment.
+ *
+ * `docs/implementation.md` §2 (MECHANISM PIN — instance state, never globals)
+ * pins exactly one environment-reading module per wrapper; everything else
+ * receives resolved configuration as a value. That is not a style preference:
+ * it is what keeps `Deno.env` / `process.env` out of the operation modules, so
+ * no operation can silently acquire a dependency on ambient state and every
+ * env-var behaviour has exactly one seam to exercise in tests (§9).
+ *
+ * The spec names that module `src/config.ts`; this package splits the *reading*
+ * (here) from the *resolving* (`src/config.ts`, which imports this file and is
+ * the only caller). The invariant the pin is about — one place touches the
+ * environment — is unchanged, and it is enforced mechanically: the repo gate
+ * greps the whole `src/` tree for `Deno.env|process.env` and requires exactly
+ * one matching file.
+ *
+ * The read is a **capability probe**, not a runtime assumption, so the same
+ * source runs under Deno, Node and Bun (`docs/implementation.md` §1: the client
+ * core is runtime-neutral TypeScript over Web-standard globals). Where neither
+ * runtime object is present the value degrades to "unset" rather than throwing —
+ * a browser bundle of this package must still construct a client from explicit
+ * arguments.
+ *
+ * @module
+ */
+/** Environment variable holding the server **origin** (see `src/config.ts`). */
+export declare const ENV_BASE_URL = "W6W_BASE_URL";
+/** Environment variable holding the bearer token. */
+export declare const ENV_TOKEN = "W6W_TOKEN";
+/**
+ * Read one environment variable, or `undefined` when it carries no usable
+ * value.
+ *
+ * **A variable that is set but empty — or whitespace-only — reads as ABSENT.**
+ * `W6W_BASE_URL=`, `W6W_BASE_URL="   "` and an unset `W6W_BASE_URL` are all the
+ * same thing here, and the precedence chain falls through all three to the next
+ * source (and ultimately to a configuration error).
+ *
+ * This deviates deliberately from the pinned snippet in
+ * `docs/implementation.md` §2, which reads `g.Deno.env.get(name) ?? undefined`.
+ * A nullish coalesce does **not** convert `""` to `undefined`, so an empty
+ * `W6W_BASE_URL` would survive as a value, reach the join rule, and resolve to
+ * the relative URL `"/api"` — exactly the browser same-origin default that §2
+ * forbids a library from having. A relative base URL fails later, somewhere
+ * else, with a message about the request rather than about the configuration.
+ *
+ * So the check below is a **truthiness/trim** check and not a nullish one, on
+ * purpose. Do not "tidy" it back to `??`. An empty-string environment variable
+ * is not a hypothetical: a Docker `ENV`/`--build-arg` that was never given a
+ * value produces exactly this, and it looks absent in every log line while
+ * behaving as present in every `??`.
+ *
+ * The value is returned verbatim (not trimmed) — normalising the *shape* of a
+ * base URL belongs to `src/config.ts`, which owns the join rule.
+ *
+ * @param name - The variable to read, e.g. {@linkcode ENV_BASE_URL}.
+ * @returns The value, or `undefined` if unset, empty, blank or unavailable.
+ */
+export declare function readEnv(name: string): string | undefined;
+//# sourceMappingURL=env.d.ts.map

package/dist/src/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,gFAAgF;AAChF,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C,qDAAqD;AACrD,eAAO,MAAM,SAAS,cAAc,CAAC;AAarC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQxD"}

package/dist/src/env.js

@@ -0,0 +1,73 @@
+/**
+ * The **only** module in this package that reads the environment.
+ *
+ * `docs/implementation.md` §2 (MECHANISM PIN — instance state, never globals)
+ * pins exactly one environment-reading module per wrapper; everything else
+ * receives resolved configuration as a value. That is not a style preference:
+ * it is what keeps `Deno.env` / `process.env` out of the operation modules, so
+ * no operation can silently acquire a dependency on ambient state and every
+ * env-var behaviour has exactly one seam to exercise in tests (§9).
+ *
+ * The spec names that module `src/config.ts`; this package splits the *reading*
+ * (here) from the *resolving* (`src/config.ts`, which imports this file and is
+ * the only caller). The invariant the pin is about — one place touches the
+ * environment — is unchanged, and it is enforced mechanically: the repo gate
+ * greps the whole `src/` tree for `Deno.env|process.env` and requires exactly
+ * one matching file.
+ *
+ * The read is a **capability probe**, not a runtime assumption, so the same
+ * source runs under Deno, Node and Bun (`docs/implementation.md` §1: the client
+ * core is runtime-neutral TypeScript over Web-standard globals). Where neither
+ * runtime object is present the value degrades to "unset" rather than throwing —
+ * a browser bundle of this package must still construct a client from explicit
+ * arguments.
+ *
+ * @module
+ */
+/** Environment variable holding the server **origin** (see `src/config.ts`). */
+export const ENV_BASE_URL = "W6W_BASE_URL";
+/** Environment variable holding the bearer token. */
+export const ENV_TOKEN = "W6W_TOKEN";
+/**
+ * Read one environment variable, or `undefined` when it carries no usable
+ * value.
+ *
+ * **A variable that is set but empty — or whitespace-only — reads as ABSENT.**
+ * `W6W_BASE_URL=`, `W6W_BASE_URL="   "` and an unset `W6W_BASE_URL` are all the
+ * same thing here, and the precedence chain falls through all three to the next
+ * source (and ultimately to a configuration error).
+ *
+ * This deviates deliberately from the pinned snippet in
+ * `docs/implementation.md` §2, which reads `g.Deno.env.get(name) ?? undefined`.
+ * A nullish coalesce does **not** convert `""` to `undefined`, so an empty
+ * `W6W_BASE_URL` would survive as a value, reach the join rule, and resolve to
+ * the relative URL `"/api"` — exactly the browser same-origin default that §2
+ * forbids a library from having. A relative base URL fails later, somewhere
+ * else, with a message about the request rather than about the configuration.
+ *
+ * So the check below is a **truthiness/trim** check and not a nullish one, on
+ * purpose. Do not "tidy" it back to `??`. An empty-string environment variable
+ * is not a hypothetical: a Docker `ENV`/`--build-arg` that was never given a
+ * value produces exactly this, and it looks absent in every log line while
+ * behaving as present in every `??`.
+ *
+ * The value is returned verbatim (not trimmed) — normalising the *shape* of a
+ * base URL belongs to `src/config.ts`, which owns the join rule.
+ *
+ * @param name - The variable to read, e.g. {@linkcode ENV_BASE_URL}.
+ * @returns The value, or `undefined` if unset, empty, blank or unavailable.
+ */
+export function readEnv(name) {
+    const g = globalThis;
+    let value;
+    if (g.Deno?.env?.get)
+        value = g.Deno.env.get(name);
+    else if (g.process?.env)
+        value = g.process.env[name];
+    else
+        return undefined;
+    if (value === undefined || value.trim().length === 0)
+        return undefined;
+    return value;
+}
+//# sourceMappingURL=env.js.map

package/dist/src/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,gFAAgF;AAChF,MAAM,CAAC,MAAM,YAAY,GAAG,cAAc,CAAC;AAE3C,qDAAqD;AACrD,MAAM,CAAC,MAAM,SAAS,GAAG,WAAW,CAAC;AAarC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,MAAM,CAAC,GAAG,UAAyC,CAAC;IACpD,IAAI,KAAyB,CAAC;IAC9B,IAAI,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG;QAAE,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;SAC9C,IAAI,CAAC,CAAC,OAAO,EAAE,GAAG;QAAE,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;;QAChD,OAAO,SAAS,CAAC;IACtB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACvE,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/src/errors.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The package's error types.
+ *
+ * Two of them, and the split is deliberate:
+ *
+ * - {@linkcode ApiError} — the server answered (or could not be reached at all).
+ *   Four fields, pinned identically in all three w6w wrappers by
+ *   `docs/implementation.md` §3, and raised by exactly the three failure modes
+ *   in `src/http.ts`.
+ * - {@linkcode ConfigError} — the client was never in a position to make a
+ *   request: no base URL, or no token. No HTTP exchange happened, so an
+ *   `ApiError`'s `status` and `code` would have to be invented; `status: 0` in
+ *   particular is already spoken for by `network_error`, and conflating "your
+ *   server is unreachable" with "you have not configured a server" is exactly
+ *   the diagnosis a user needs kept apart.
+ *
+ * Every public member carries an explicit type annotation. That is a
+ * publishing requirement, not a preference: JSR publishes this file as
+ * TypeScript source and rejects inferred public types ("no slow types",
+ * `docs/implementation.md` §1).
+ *
+ * @module
+ */
+/**
+ * An error raised by a w6w API call.
+ *
+ * `raw` is the **parsed response body** when the server sent one, otherwise
+ * `null`. It is kept because an error body carries fields the message alone
+ * drops — an invoke failure rides alongside `logs` and `apiCalls` — and because
+ * a caller inspecting a server error should never have to re-issue the request
+ * to see what came back.
+ *
+ * Classification is by {@linkcode status} plus a **prefix** of
+ * {@linkcode code} — `unknown_*` (404), `invalid_*` (400), `*_exists` (409) —
+ * never by an exhaustive list of code strings. The server mints codes freely
+ * and a closed list in three wrappers would be stale within a release
+ * (`docs/implementation.md` §3).
+ *
+ * One status deserves singling out: **`424` is an app/upstream failure in the
+ * execute phase**, and it is a 4xx rather than a 5xx on purpose — Cloudflare
+ * replaces an origin 5xx with its own CORS-less HTML page, which would strip
+ * the real message. Do not normalise a 424 into a server error or into a
+ * transport failure; pass it through with its code and body intact.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.request({ method: "GET", path: "/vars/var_missing" });
+ * } catch (err) {
+ *   if (err instanceof ApiError && err.status === 404) {
+ *     // err.code === "unknown_var", err.raw === { error: { … } }
+ *   }
+ * }
+ * ```
+ */
+export declare class ApiError extends Error {
+    /** HTTP status, or `0` when the request never produced a response. */
+    readonly status: number;
+    /** Server-minted error code, `"network_error"`, or `"bad_response"`. */
+    readonly code: string;
+    /** The parsed response body, when there was one; otherwise `null`. */
+    readonly raw: unknown;
+    constructor(status: number, code: string, message: string, raw?: unknown);
+}
+/**
+ * The client is not configured well enough to make a request.
+ *
+ * Raised at construction when there is no base URL, and on the first request
+ * when there is no token — a client with no token can still be *built*, so a
+ * CLI's `--help` and `--version` work offline (`docs/implementation.md` §2).
+ *
+ * The message always names the environment variable that would have supplied
+ * the missing value, because "which variable?" is the only question a user has
+ * at this point.
+ */
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;gBAEV,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,OAAc;CAO/E;AAED;;;;;;;;;;GAUG;AACH,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAI5B"}

package/dist/src/errors.js

@@ -0,0 +1,88 @@
+/**
+ * The package's error types.
+ *
+ * Two of them, and the split is deliberate:
+ *
+ * - {@linkcode ApiError} — the server answered (or could not be reached at all).
+ *   Four fields, pinned identically in all three w6w wrappers by
+ *   `docs/implementation.md` §3, and raised by exactly the three failure modes
+ *   in `src/http.ts`.
+ * - {@linkcode ConfigError} — the client was never in a position to make a
+ *   request: no base URL, or no token. No HTTP exchange happened, so an
+ *   `ApiError`'s `status` and `code` would have to be invented; `status: 0` in
+ *   particular is already spoken for by `network_error`, and conflating "your
+ *   server is unreachable" with "you have not configured a server" is exactly
+ *   the diagnosis a user needs kept apart.
+ *
+ * Every public member carries an explicit type annotation. That is a
+ * publishing requirement, not a preference: JSR publishes this file as
+ * TypeScript source and rejects inferred public types ("no slow types",
+ * `docs/implementation.md` §1).
+ *
+ * @module
+ */
+/**
+ * An error raised by a w6w API call.
+ *
+ * `raw` is the **parsed response body** when the server sent one, otherwise
+ * `null`. It is kept because an error body carries fields the message alone
+ * drops — an invoke failure rides alongside `logs` and `apiCalls` — and because
+ * a caller inspecting a server error should never have to re-issue the request
+ * to see what came back.
+ *
+ * Classification is by {@linkcode status} plus a **prefix** of
+ * {@linkcode code} — `unknown_*` (404), `invalid_*` (400), `*_exists` (409) —
+ * never by an exhaustive list of code strings. The server mints codes freely
+ * and a closed list in three wrappers would be stale within a release
+ * (`docs/implementation.md` §3).
+ *
+ * One status deserves singling out: **`424` is an app/upstream failure in the
+ * execute phase**, and it is a 4xx rather than a 5xx on purpose — Cloudflare
+ * replaces an origin 5xx with its own CORS-less HTML page, which would strip
+ * the real message. Do not normalise a 424 into a server error or into a
+ * transport failure; pass it through with its code and body intact.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.request({ method: "GET", path: "/vars/var_missing" });
+ * } catch (err) {
+ *   if (err instanceof ApiError && err.status === 404) {
+ *     // err.code === "unknown_var", err.raw === { error: { … } }
+ *   }
+ * }
+ * ```
+ */
+export class ApiError extends Error {
+    /** HTTP status, or `0` when the request never produced a response. */
+    status;
+    /** Server-minted error code, `"network_error"`, or `"bad_response"`. */
+    code;
+    /** The parsed response body, when there was one; otherwise `null`. */
+    raw;
+    constructor(status, code, message, raw = null) {
+        super(message);
+        this.name = "ApiError";
+        this.status = status;
+        this.code = code;
+        this.raw = raw;
+    }
+}
+/**
+ * The client is not configured well enough to make a request.
+ *
+ * Raised at construction when there is no base URL, and on the first request
+ * when there is no token — a client with no token can still be *built*, so a
+ * CLI's `--help` and `--version` work offline (`docs/implementation.md` §2).
+ *
+ * The message always names the environment variable that would have supplied
+ * the missing value, because "which variable?" is the only question a user has
+ * at this point.
+ */
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,sEAAsE;IAC7D,MAAM,CAAS;IACxB,wEAAwE;IAC/D,IAAI,CAAS;IACtB,sEAAsE;IAC7D,GAAG,CAAU;IAEtB,YAAY,MAAc,EAAE,IAAY,EAAE,OAAe,EAAE,MAAe,IAAI;QAC5E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF"}

package/dist/src/http.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The transport: one `request()`, three failure modes, no policy.
+ *
+ * Everything the operation modules do goes through {@linkcode request}. It
+ * attaches the bearer, serialises a JSON body, reads the response exactly once,
+ * parses it guardedly, and raises one of the three failure modes pinned in
+ * `docs/implementation.md` §3 — and nothing else. In particular it does **not**
+ * retry, does **not** refresh a token, does **not** poll, and does **not**
+ * inspect an error code to decide on a side effect. A `401` raises and stops.
+ *
+ * It also returns the **HTTP status** alongside the parsed body, because a
+ * `202` is a normal outcome on this API (a queued workflow run), not an error —
+ * and a signature that dropped the status would leave the run operations unable
+ * to tell "finished" from "queued" (§4).
+ *
+ * @module
+ */
+import { type FetchLike, type ResolvedConfig } from "./config.ts";
+/** HTTP methods this surface uses. */
+export type HttpMethod = "GET" | "POST" | "PATCH" | "DELETE";
+/**
+ * Query parameters. `undefined` values are dropped, so an optional argument
+ * can be forwarded without a conditional at the call site. Values are
+ * percent-encoded by `URLSearchParams`.
+ */
+export type QueryParams = Record<string, string | number | boolean | undefined>;
+/** One request, fully described. */
+export interface RequestOptions {
+    /** HTTP method. */
+    method: HttpMethod;
+    /**
+     * Base-relative path with a leading slash, e.g. `/documents`. Build it with
+     * the {@linkcode path} tag whenever any part of it comes from the caller.
+     */
+    path: string;
+    /** Query parameters, if any. */
+    query?: QueryParams;
+    /** Request body. Serialised as JSON when present; omit it for a bodiless request. */
+    body?: unknown;
+}
+/**
+ * A successful response: the parsed body plus the status that carried it.
+ *
+ * `body` is `null` for an empty body — a `204`-style response must not crash a
+ * caller, and the server's `{ok:true}` deletes carry nothing an operation needs.
+ */
+export interface HttpResponse<T> {
+    status: number;
+    body: T;
+}
+/**
+ * Build a base-relative path, percent-encoding every interpolated value.
+ *
+ * ```ts
+ * path`/documents/by-key/${key}`   // key "a/b" → "/documents/by-key/a%2Fb"
+ * ```
+ *
+ * **Use this tag for every path that contains a caller-supplied value**, per the
+ * encoding pin in `docs/implementation.md` §2. It exists as a tag rather than a
+ * helper function because the encoding then happens at the point of
+ * interpolation and cannot be forgotten one call site at a time: there is no way
+ * to write the template and skip it.
+ *
+ * Why it matters, in one line: the server accepts any non-empty key up to 128
+ * characters, so `".."` is a key a user can legitimately create — and
+ * `` `/documents/by-key/${".."}` `` naively concatenated resolves to the
+ * **list** route, returning every document with a `200` and no error anywhere.
+ *
+ * This is encoding, never validation. A key the server accepts is sent as-is
+ * (encoded); the wrapper does not reject, canonicalise or rewrite it. A
+ * character policy for keys is business logic, and it lives in the server.
+ *
+ * The one case encoding cannot fix is a dot-only segment: `.` is unreserved in
+ * RFC 3986, and the URL parser behind `fetch` removes dot segments regardless of
+ * how they are spelled. `"."` and `".."` are therefore not addressable through a
+ * path segment from this runtime — encode and send anyway, and let the server
+ * decide what it means.
+ *
+ * @param strings - Template literal fragments (author-controlled, not encoded).
+ * @param values - Interpolated values (caller-controlled, each percent-encoded).
+ * @returns The assembled path.
+ */
+export declare function path(strings: TemplateStringsArray, ...values: string[]): string;
+/**
+ * Assemble the full request URL from a resolved base, a path and query params.
+ *
+ * The base is already joined with the API base path by `src/config.ts`; the
+ * path is appended verbatim (it is expected to be encoded already — see
+ * {@linkcode path}), and the query string is built with `URLSearchParams`,
+ * which encodes both names and values.
+ *
+ * @param config - The resolved configuration.
+ * @param options - The request being built.
+ * @returns The absolute URL to fetch.
+ */
+export declare function buildUrl(config: ResolvedConfig, options: RequestOptions): string;
+/**
+ * Perform one request and map its outcome.
+ *
+ * Returns `{status, body}` on any `2xx`. Raises {@linkcode ApiError} in exactly
+ * three cases, transcribed from the studio's client, which has these three and
+ * no others:
+ *
+ * 1. **Transport failure** — `fetch` itself rejected: server down, DNS, TLS,
+ *    connection refused. `status` `0`, code `network_error`, and the message
+ *    names the **method and full URL** plus the underlying message, because a
+ *    bare `TypeError: Failed to fetch` says nothing a user can act on.
+ * 2. **Non-JSON body on a non-OK status** — a proxy or Cloudflare HTML error
+ *    page. `code` `bad_response`, message carrying a ≤200-character snippet;
+ *    reporting it as an opaque `SyntaxError` would throw away the only
+ *    diagnostic present. A non-JSON body on an **OK** status is not an error.
+ * 3. **Envelope error** — a non-OK status with a JSON body. `code` from
+ *    `body.error.code` (else `"error"`), `message` from `body.error.message`
+ *    (else the status text), and `raw` = the parsed body, which carries the
+ *    fields an invoke failure rides alongside (`logs`, `apiCalls`).
+ *
+ * A `424` lands in case 3 like any other non-OK JSON status: it means the
+ * target app or its upstream vendor failed during execute, and it is
+ * deliberately a 4xx so Cloudflare cannot swallow it. It is never a transport
+ * error and is never normalised into a 5xx.
+ *
+ * @param config - Resolved configuration (base URL and credential).
+ * @param fetchImpl - The transport to use; injected, never read from a module global.
+ * @param options - The request.
+ * @returns The status and parsed body.
+ * @throws {ConfigError} When no token is configured.
+ * @throws {ApiError} On any of the three failure modes above.
+ */
+export declare function request<T>(config: ResolvedConfig, fetchImpl: FetchLike, options: RequestOptions): Promise<HttpResponse<T>>;
+//# sourceMappingURL=http.d.ts.map

package/dist/src/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAgB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAGhF,sCAAsC;AACtC,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE7D;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;AAEhF,oCAAoC;AACpC,MAAM,WAAW,cAAc;IAC7B,mBAAmB;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,qFAAqF;IACrF,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,CAAC,CAAC;CACT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAM/E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,CAOhF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAC7B,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAwD1B"}