@w6w/sdk 0.1.0

package/dist/src/config.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Configuration resolution: what server, what credential, what project.
+ *
+ * This module turns whatever the caller supplied — plus the environment, read
+ * through the single seam in `src/env.ts` — into one plain {@linkcode
+ * ResolvedConfig} value. It is resolved **once, at client construction**, and
+ * handed to the transport; nothing downstream re-reads the environment.
+ *
+ * @module
+ */
+/**
+ * The API's base path, from the shared contract's `basePath`
+ * (`packages/wrappers/endpoints.json`). It is appended to the configured
+ * origin by {@linkcode joinBaseUrl}; users never type it.
+ */
+export declare const BASE_PATH = "/api";
+/**
+ * A `fetch`-shaped function.
+ *
+ * This is the injection seam every test in this package runs against: no test
+ * may require a live server (`docs/implementation.md` §9). It is
+ * constructor-injected for the same reason the credential is — a module-patched
+ * global cannot be exercised two different ways in one process.
+ *
+ * `globalThis.fetch` satisfies it (a wider parameter type is assignable to a
+ * narrower one), while a fake only has to accept a URL string.
+ */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** Constructor options for a client. Every field is optional. */
+export interface W6wClientOptions {
+    /**
+     * The **origin** of the w6w server, e.g. `https://api.example.com`. The base
+     * path (`/api`) is appended for you and is never doubled. It must be an
+     * absolute `http(s)` URL with a host: a relative value like `/api` is a
+     * browser same-origin assumption with no meaning in a library, and is
+     * rejected at construction rather than misreported as an outage later.
+     * Overrides `W6W_BASE_URL`.
+     */
+    baseUrl?: string;
+    /** Bearer token, sent on every request. Overrides `W6W_TOKEN`. */
+    token?: string;
+    /**
+     * Default project id for the project-scoped operations — `documents.*` and
+     * `workflows.list`, which read it too.
+     * Omitted, the server resolves the account's default project. There is no
+     * environment variable for this and no `project` on any `vars.*` operation —
+     * vars are not project-scoped (`docs/implementation.md` §7).
+     */
+    project?: string;
+    /** Transport override. Defaults to `globalThis.fetch`. */
+    fetch?: FetchLike;
+}
+/**
+ * Configuration after resolution — the value the transport actually runs on.
+ *
+ * Held as **instance** state on the client, never in a module-level variable:
+ * two clients in one process must be able to hold different credentials and
+ * point at different servers with no interference (`docs/implementation.md` §2).
+ */
+export interface ResolvedConfig {
+    /**
+     * Fully joined base, e.g. `https://api.example.com/api`. Never
+     * trailing-slashed, and never relative — {@linkcode joinBaseUrl} rejects a
+     * value that is not an absolute `http(s)` URL with a host.
+     */
+    readonly baseUrl: string;
+    /** The bearer token, or `null` when none was configured. */
+    readonly token: string | null;
+    /** Default project id, or `null`. */
+    readonly project: string | null;
+}
+/**
+ * Validate a configured origin and join it with the API base path.
+ *
+ * **This is the one and only base-URL code path.** {@linkcode resolveConfig}
+ * calls this function and normalises nothing itself, so a caller who imports
+ * the helper gets exactly the answer their client will use — including the same
+ * errors. A helper that were merely *similar* to the client's path (skipping the
+ * whitespace trim, say) would answer differently for the same input, which is
+ * worse than having no helper at all. The python lane found and fixed the
+ * identical divergence in its own draft; this mirrors its resolution.
+ *
+ * The join rule is pinned by `docs/implementation.md` §2 and mirrors the house
+ * helper that the operator console already uses against this same API, so all
+ * clients agree on what `W6W_BASE_URL` means:
+ *
+ * 1. strip surrounding whitespace, then **all** trailing slashes;
+ * 2. reject anything that is not an absolute `http`/`https` URL with a host;
+ * 3. if the result already ends with the base path, use it as-is — **never
+ *    double it**;
+ * 4. otherwise append the base path.
+ *
+ * ```
+ * https://api.example.com      → https://api.example.com/api
+ * https://api.example.com/     → https://api.example.com/api
+ * https://api.example.com///   → https://api.example.com/api
+ * https://api.example.com/api  → https://api.example.com/api
+ * https://api.example.com/api/ → https://api.example.com/api
+ * ```
+ *
+ * Step 2 exists because a **relative** base URL has to fail *here*, as
+ * configuration, with a message about configuration. Blank-is-absent
+ * (`src/env.ts`) already stops `""` from joining to the relative `"/api"`; with
+ * no absoluteness check, `W6W_BASE_URL=/foo` walked straight past that guard to
+ * `"/foo/api"` and then failed on the first request as "the server may be down"
+ * — the same hole, reopened by another route, and misdiagnosed. Closing only one
+ * of the two leaves the other open.
+ *
+ * @param origin - The configured origin. Surrounding whitespace and trailing slashes are tolerated.
+ * @returns The joined base URL.
+ * @throws {ConfigError} When the origin is blank, relative, hostless or not `http(s)`.
+ */
+export declare function joinBaseUrl(origin: string): string;
+/**
+ * Resolve constructor options and the environment into one config value.
+ *
+ * Precedence is **explicit argument > environment variable**, always; there is
+ * no default base URL. An explicitly passed empty string is an *explicit*
+ * value, not "unset" — it does not fall through to the environment, and an
+ * empty base URL is a configuration error either way. Only an absent
+ * (`undefined`) argument consults the environment.
+ *
+ * An **empty or whitespace-only environment variable is absent** and falls
+ * through (see `src/env.ts`), so `W6W_BASE_URL=`, `W6W_BASE_URL="  "` and an
+ * unset `W6W_BASE_URL` all end here, in the same configuration error — never in
+ * a relative `"/api"`.
+ *
+ * @param options - Constructor options; `fetch` is ignored here (the client owns it).
+ * @returns The resolved configuration.
+ * @throws {ConfigError} When no usable base URL was supplied, naming `W6W_BASE_URL`.
+ */
+export declare function resolveConfig(options?: W6wClientOptions): ResolvedConfig;
+/**
+ * The token, or a {@linkcode ConfigError} naming `W6W_TOKEN`.
+ *
+ * A client may be *constructed* without a token so that a CLI's `--help` and
+ * `--version` work offline; the error surfaces on the first request instead.
+ * There are no anonymous operations in this surface
+ * (`docs/implementation.md` §2).
+ *
+ * A blank token counts as no token, for the same reason a blank base URL does:
+ * `W6W_TOKEN=` is how a shell or a Dockerfile spells "I meant to set this and
+ * did not", and `Authorization: Bearer ` would turn that into an opaque 401
+ * instead of the one message that explains it.
+ *
+ * @param config - The resolved configuration.
+ * @returns The configured token, verbatim.
+ * @throws {ConfigError} When no non-blank token is configured.
+ */
+export declare function requireToken(config: ResolvedConfig): string;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH;;;;GAIG;AACH,eAAO,MAAM,SAAS,SAAS,CAAC;AAEhC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEjF,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAuBlD;AAkBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,gBAAqB,GAAG,cAAc,CAS5E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAS3D"}

package/dist/src/config.js

@@ -0,0 +1,161 @@
+/**
+ * Configuration resolution: what server, what credential, what project.
+ *
+ * This module turns whatever the caller supplied — plus the environment, read
+ * through the single seam in `src/env.ts` — into one plain {@linkcode
+ * ResolvedConfig} value. It is resolved **once, at client construction**, and
+ * handed to the transport; nothing downstream re-reads the environment.
+ *
+ * @module
+ */
+import { ENV_BASE_URL, ENV_TOKEN, readEnv } from "./env.js";
+import { ConfigError } from "./errors.js";
+/**
+ * The API's base path, from the shared contract's `basePath`
+ * (`packages/wrappers/endpoints.json`). It is appended to the configured
+ * origin by {@linkcode joinBaseUrl}; users never type it.
+ */
+export const BASE_PATH = "/api";
+/**
+ * An absolute `http(s)` origin, spelled with a real authority.
+ *
+ * Deliberately checked *before* `new URL`, because the WHATWG parser silently
+ * repairs the one spelling this rule most needs to catch: `new URL("http:///foo")`
+ * does **not** fail and does **not** yield an empty host — it collapses the extra
+ * slash and resolves to `http://foo/`, so a host check alone would accept a
+ * hostless value and then request a different server than the one the user typed.
+ * Measured in the api container, not assumed. The pattern therefore requires the
+ * authority to start with a character that is not a slash, backslash, `?` or `#`.
+ */
+const ABSOLUTE_HTTP_ORIGIN = /^https?:\/\/[^/\\?#]/i;
+/**
+ * Validate a configured origin and join it with the API base path.
+ *
+ * **This is the one and only base-URL code path.** {@linkcode resolveConfig}
+ * calls this function and normalises nothing itself, so a caller who imports
+ * the helper gets exactly the answer their client will use — including the same
+ * errors. A helper that were merely *similar* to the client's path (skipping the
+ * whitespace trim, say) would answer differently for the same input, which is
+ * worse than having no helper at all. The python lane found and fixed the
+ * identical divergence in its own draft; this mirrors its resolution.
+ *
+ * The join rule is pinned by `docs/implementation.md` §2 and mirrors the house
+ * helper that the operator console already uses against this same API, so all
+ * clients agree on what `W6W_BASE_URL` means:
+ *
+ * 1. strip surrounding whitespace, then **all** trailing slashes;
+ * 2. reject anything that is not an absolute `http`/`https` URL with a host;
+ * 3. if the result already ends with the base path, use it as-is — **never
+ *    double it**;
+ * 4. otherwise append the base path.
+ *
+ * ```
+ * https://api.example.com      → https://api.example.com/api
+ * https://api.example.com/     → https://api.example.com/api
+ * https://api.example.com///   → https://api.example.com/api
+ * https://api.example.com/api  → https://api.example.com/api
+ * https://api.example.com/api/ → https://api.example.com/api
+ * ```
+ *
+ * Step 2 exists because a **relative** base URL has to fail *here*, as
+ * configuration, with a message about configuration. Blank-is-absent
+ * (`src/env.ts`) already stops `""` from joining to the relative `"/api"`; with
+ * no absoluteness check, `W6W_BASE_URL=/foo` walked straight past that guard to
+ * `"/foo/api"` and then failed on the first request as "the server may be down"
+ * — the same hole, reopened by another route, and misdiagnosed. Closing only one
+ * of the two leaves the other open.
+ *
+ * @param origin - The configured origin. Surrounding whitespace and trailing slashes are tolerated.
+ * @returns The joined base URL.
+ * @throws {ConfigError} When the origin is blank, relative, hostless or not `http(s)`.
+ */
+export function joinBaseUrl(origin) {
+    // Surrounding whitespace is stripped before the emptiness test so a blank
+    // explicit argument fails the same way a blank environment variable does — an
+    // env file's stray "\n" must not become part of the origin.
+    const trimmed = origin.trim().replace(/\/+$/, "");
+    if (trimmed.length === 0) {
+        throw new ConfigError("No w6w base URL is configured. Pass one to the client " +
+            '(new W6wClient({ baseUrl: "https://api.example.com" })) or set the ' +
+            `${ENV_BASE_URL} environment variable. It holds the server's origin — the ` +
+            `${BASE_PATH} base path is appended for you.`);
+    }
+    if (!ABSOLUTE_HTTP_ORIGIN.test(trimmed) || !parses(trimmed)) {
+        throw new ConfigError(`The w6w base URL "${trimmed}" is not an absolute http(s) URL. ` +
+            `${ENV_BASE_URL} holds an ORIGIN, e.g. "https://api.example.com" — scheme and host, ` +
+            `with the ${BASE_PATH} base path appended for you. A relative or hostless value ` +
+            "cannot be requested and would fail later as a connection problem rather than as " +
+            "the configuration mistake it is.");
+    }
+    return trimmed.endsWith(BASE_PATH) ? trimmed : `${trimmed}${BASE_PATH}`;
+}
+/**
+ * Does the runtime's URL parser accept this origin at all?
+ *
+ * The pattern above settles *shape* (scheme, `//`, a real authority); this
+ * settles the rest — an out-of-range port, a malformed IPv6 literal, a host the
+ * parser rejects. Both have to hold, and neither subsumes the other.
+ */
+function parses(origin) {
+    try {
+        new URL(origin);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve constructor options and the environment into one config value.
+ *
+ * Precedence is **explicit argument > environment variable**, always; there is
+ * no default base URL. An explicitly passed empty string is an *explicit*
+ * value, not "unset" — it does not fall through to the environment, and an
+ * empty base URL is a configuration error either way. Only an absent
+ * (`undefined`) argument consults the environment.
+ *
+ * An **empty or whitespace-only environment variable is absent** and falls
+ * through (see `src/env.ts`), so `W6W_BASE_URL=`, `W6W_BASE_URL="  "` and an
+ * unset `W6W_BASE_URL` all end here, in the same configuration error — never in
+ * a relative `"/api"`.
+ *
+ * @param options - Constructor options; `fetch` is ignored here (the client owns it).
+ * @returns The resolved configuration.
+ * @throws {ConfigError} When no usable base URL was supplied, naming `W6W_BASE_URL`.
+ */
+export function resolveConfig(options = {}) {
+    return {
+        // Every normalisation, the emptiness test and the absoluteness check live in
+        // `joinBaseUrl` — one code path, so the exported helper and the client can
+        // never answer differently for the same input.
+        baseUrl: joinBaseUrl(options.baseUrl ?? readEnv(ENV_BASE_URL) ?? ""),
+        token: options.token ?? readEnv(ENV_TOKEN) ?? null,
+        project: options.project ?? null,
+    };
+}
+/**
+ * The token, or a {@linkcode ConfigError} naming `W6W_TOKEN`.
+ *
+ * A client may be *constructed* without a token so that a CLI's `--help` and
+ * `--version` work offline; the error surfaces on the first request instead.
+ * There are no anonymous operations in this surface
+ * (`docs/implementation.md` §2).
+ *
+ * A blank token counts as no token, for the same reason a blank base URL does:
+ * `W6W_TOKEN=` is how a shell or a Dockerfile spells "I meant to set this and
+ * did not", and `Authorization: Bearer ` would turn that into an opaque 401
+ * instead of the one message that explains it.
+ *
+ * @param config - The resolved configuration.
+ * @returns The configured token, verbatim.
+ * @throws {ConfigError} When no non-blank token is configured.
+ */
+export function requireToken(config) {
+    if (config.token === null || config.token.trim().length === 0) {
+        throw new ConfigError("No w6w API token is configured. Pass one to the client " +
+            '(new W6wClient({ token: "…" })) or set the ' +
+            `${ENV_TOKEN} environment variable. Every w6w API operation is authenticated.`);
+    }
+    return config.token;
+}
+//# sourceMappingURL=config.js.map

package/dist/src/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC;AA4DhC;;;;;;;;;;GAUG;AACH,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,0EAA0E;IAC1E,8EAA8E;IAC9E,4DAA4D;IAC5D,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAClD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,WAAW,CACnB,wDAAwD;YACtD,qEAAqE;YACrE,GAAG,YAAY,4DAA4D;YAC3E,GAAG,SAAS,iCAAiC,CAChD,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,WAAW,CACnB,qBAAqB,OAAO,oCAAoC;YAC9D,GAAG,YAAY,sEAAsE;YACrF,YAAY,SAAS,4DAA4D;YACjF,kFAAkF;YAClF,kCAAkC,CACrC,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,SAAS,EAAE,CAAC;AAC1E,CAAC;AAED;;;;;;GAMG;AACH,SAAS,MAAM,CAAC,MAAc;IAC5B,IAAI,CAAC;QACH,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,aAAa,CAAC,UAA4B,EAAE;IAC1D,OAAO;QACL,6EAA6E;QAC7E,2EAA2E;QAC3E,+CAA+C;QAC/C,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC;QACpE,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,SAAS,CAAC,IAAI,IAAI;QAClD,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,IAAI;KACjC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,YAAY,CAAC,MAAsB;IACjD,IAAI,MAAM,CAAC,KAAK,KAAK,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,WAAW,CACnB,yDAAyD;YACvD,6CAA6C;YAC7C,GAAG,SAAS,kEAAkE,CACjF,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC"}

package/dist/src/connections.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `client.connections.list()` — discovery, and nothing more.
+ *
+ * One operation in v0.1.0. It exists because without it a caller has no way to
+ * **discover** a `conn_…` id to pass to `run` (D4): the intake's surface is
+ * `run` plus the assets it needs, and an id nobody can enumerate is an id
+ * nobody can use.
+ *
+ * Everything else about connections — creating one, testing one, replacing its
+ * secret — is `outOfScope` in `endpoints.json` for this version. That is a
+ * deliberate line, not an omission: connecting an app is an interactive,
+ * secret-handling flow, and half of one in a v0.1.0 wrapper is worse than none.
+ * This namespace is therefore read-only and stays that way until the contract
+ * says otherwise.
+ *
+ * The list the server returns is a **redacted projection** — the stored secret
+ * and its refresh timestamp never leave the host — so
+ * {@linkcode ConnectionSummary} does not declare them.
+ *
+ * @module
+ */
+import type { HttpResponse, RequestOptions } from "./http.ts";
+import { type ConnectionSummary } from "./types.ts";
+/**
+ * The slice of `W6wClient` this namespace needs: the transport, and nothing
+ * else. Connections carry no `?project=` — the server scopes them by
+ * tenant/account from the credential — so, as with `vars`, this host cannot
+ * reach the client's configuration to send a scope even by accident.
+ */
+export interface ConnectionsHost {
+    /** Perform one request. */
+    request<T>(options: RequestOptions): Promise<HttpResponse<T>>;
+}
+/**
+ * The `connections` namespace on a `W6wClient`.
+ *
+ * @example
+ * ```ts
+ * for (const c of await client.connections.list()) {
+ *   if (c.state === "connected") console.log(c.id, c.appId);
+ * }
+ * ```
+ */
+export declare class ConnectionsApi {
+    #private;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host: ConnectionsHost);
+    /**
+     * List the caller's connections.
+     *
+     * @returns The connections, unwrapped from the `connections` envelope.
+     * @throws {ApiError} On any non-2xx.
+     */
+    list(): Promise<ConnectionSummary[]>;
+}
+//# sourceMappingURL=connections.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connections.d.ts","sourceRoot":"","sources":["../../src/connections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAE,KAAK,iBAAiB,EAAU,MAAM,YAAY,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;;;;;GASG;AACH,qBAAa,cAAc;;IAGzB;;OAEG;gBACS,IAAI,EAAE,eAAe;IAIjC;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;CAI3C"}

package/dist/src/connections.js

@@ -0,0 +1,52 @@
+/**
+ * `client.connections.list()` — discovery, and nothing more.
+ *
+ * One operation in v0.1.0. It exists because without it a caller has no way to
+ * **discover** a `conn_…` id to pass to `run` (D4): the intake's surface is
+ * `run` plus the assets it needs, and an id nobody can enumerate is an id
+ * nobody can use.
+ *
+ * Everything else about connections — creating one, testing one, replacing its
+ * secret — is `outOfScope` in `endpoints.json` for this version. That is a
+ * deliberate line, not an omission: connecting an app is an interactive,
+ * secret-handling flow, and half of one in a v0.1.0 wrapper is worse than none.
+ * This namespace is therefore read-only and stays that way until the contract
+ * says otherwise.
+ *
+ * The list the server returns is a **redacted projection** — the stored secret
+ * and its refresh timestamp never leave the host — so
+ * {@linkcode ConnectionSummary} does not declare them.
+ *
+ * @module
+ */
+import { unwrap } from "./types.js";
+/**
+ * The `connections` namespace on a `W6wClient`.
+ *
+ * @example
+ * ```ts
+ * for (const c of await client.connections.list()) {
+ *   if (c.state === "connected") console.log(c.id, c.appId);
+ * }
+ * ```
+ */
+export class ConnectionsApi {
+    #host;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host) {
+        this.#host = host;
+    }
+    /**
+     * List the caller's connections.
+     *
+     * @returns The connections, unwrapped from the `connections` envelope.
+     * @throws {ApiError} On any non-2xx.
+     */
+    async list() {
+        const res = await this.#host.request({ method: "GET", path: "/connections" });
+        return unwrap(res, "connections");
+    }
+}
+//# sourceMappingURL=connections.js.map

package/dist/src/connections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connections.js","sourceRoot":"","sources":["../../src/connections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAA0B,MAAM,EAAE,MAAM,YAAY,CAAC;AAa5D;;;;;;;;;GASG;AACH,MAAM,OAAO,cAAc;IAChB,KAAK,CAAkB;IAEhC;;OAEG;IACH,YAAY,IAAqB;QAC/B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI;QACR,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAC;QACvF,OAAO,MAAM,CAAsB,GAAG,EAAE,aAAa,CAAC,CAAC;IACzD,CAAC;CACF"}

package/dist/src/documents.d.ts

@@ -0,0 +1,168 @@
+/**
+ * `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 type { ResolvedConfig } from "./config.ts";
+import { type HttpResponse, type RequestOptions } from "./http.ts";
+import { type Doc, type DocFormat } from "./types.ts";
+/**
+ * The slice of `W6wClient` this namespace needs: the transport, plus
+ * the resolved configuration it reads the **default project** out of. Structural
+ * rather than a concrete client type, so the namespace stays independently
+ * constructible in a test and this module never imports the client back.
+ */
+export interface DocumentsHost {
+    /** The resolved configuration; only `project` is read. */
+    readonly config: ResolvedConfig;
+    /** Perform one request. */
+    request<T>(options: RequestOptions): Promise<HttpResponse<T>>;
+}
+/**
+ * Per-call options shared by every document operation.
+ *
+ * `project` overrides the client's default for this one call. Omitted
+ * everywhere, the server resolves the account's default project; an unknown id
+ * is `400 unknown_project`.
+ */
+export interface DocumentOptions {
+    /** Project id to scope this call to. */
+    project?: string;
+}
+/**
+ * The body of `documents.create`.
+ *
+ * Addressed by `key`, because that is how the server addresses a create (D6).
+ */
+export interface DocumentCreateInput {
+    /** Non-empty, ≤128 characters, unique per scope + project. `409 document_exists` if taken. */
+    key: string;
+    /** Raw text; stored verbatim and never parsed. */
+    content: string;
+    /** Format hint; the server defaults it to `"text"`. */
+    format?: DocFormat;
+    /** Free text. */
+    description?: string;
+}
+/**
+ * The body of `documents.update`. Every field is optional; an omitted field is
+ * left alone.
+ *
+ * **`key` is deliberately absent.** The server's PATCH body has no `key` and the
+ * key is immutable, so there is no field here to put one in — the type is what
+ * enforces it, not a comment.
+ */
+export interface DocumentPatch {
+    /** Replacement content. */
+    content?: string;
+    /** Replacement format hint. */
+    format?: DocFormat;
+    /** Replacement description. */
+    description?: string;
+}
+/**
+ * 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 declare class DocumentsApi {
+    #private;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host: DocumentsHost);
+    /**
+     * 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`.
+     */
+    list(options?: DocumentOptions): Promise<Doc[]>;
+    /**
+     * 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.
+     */
+    get(id: string, options?: DocumentOptions): Promise<Doc>;
+    /**
+     * 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.
+     */
+    getByKey(key: string, options?: DocumentOptions): Promise<Doc>;
+    /**
+     * 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.
+     */
+    create(input: DocumentCreateInput, options?: DocumentOptions): Promise<Doc>;
+    /**
+     * 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.
+     */
+    update(id: string, patch: DocumentPatch, options?: DocumentOptions): Promise<Doc>;
+    /**
+     * 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.
+     */
+    delete(id: string, options?: DocumentOptions): Promise<void>;
+}
+//# sourceMappingURL=documents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../src/documents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,KAAK,YAAY,EAAQ,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AACzE,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,SAAS,EAAU,MAAM,YAAY,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,2BAA2B;IAC3B,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,8FAA8F;IAC9F,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,iBAAiB;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,2BAA2B;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,qBAAa,YAAY;;IAGvB;;OAEG;gBACS,IAAI,EAAE,aAAa;IAa/B;;;;;;OAMG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IASrD;;;;;;;OAOG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC;IAS9D;;;;;;;;;;;;;;;;;;OAkBG;IACG,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC;IASpE;;;;;;;OAOG;IACG,MAAM,CAAC,KAAK,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC;IAkBjF;;;;;;;;;;OAUG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC;IAcvF;;;;;;;;;;;OAWG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CAOnE"}