@w6w/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 w6w-io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# @w6w/sdk
+
+The TypeScript client for the [w6w](https://w6w.dev) HTTP API.
+
+It is a **thin** client: transport, auth, error mapping, and typed request/response shapes. No
+business logic, no client-side polling, no hidden retries. If something useful needs two calls
+composed, that composition belongs in the API, not here.
+
+The package is authored as runtime-neutral TypeScript against Web standards (`fetch`, `Headers`,
+`URL`, `AbortController`), so the same build runs under Node 18+, Deno and Bun.
+
+- **License:** MIT (see [LICENSE](./LICENSE)).
+- **Version:** `0.1.0`.
+
+## Install
+
+npm (compiled ESM + type declarations):
+
+```bash
+npm install @w6w/sdk
+```
+
+JSR (the TypeScript source, published verbatim):
+
+```bash
+deno add jsr:@w6w/sdk
+```
+
+Both registries publish the **same version at the same time** — `@w6w/sdk`, `@w6w/cli` and the
+Python `w6w` package share one version number and are released together. A given version means the
+same set of operations in every language.
+
+## Configuration
+
+Two environment variables, both read only at client construction:
+
+| Variable       | Meaning                                                                                                                               | Required |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------- |
+| `W6W_BASE_URL` | The **origin** of your w6w server, e.g. `https://api.example.com`. The API's base path is appended by the client — do not include it. | Yes      |
+| `W6W_TOKEN`    | The bearer token, sent as `Authorization: Bearer <token>` on every request.                                                           | Yes      |
+
+Explicit constructor arguments always win over the environment, and credentials are **instance
+state**: two clients in one process can hold different tokens and point at different servers with no
+interference. There is no default base URL — a client built without one and without `W6W_BASE_URL`
+raises a configuration error naming the variable.
+
+```ts
+import { W6wClient } from "@w6w/sdk";
+
+// Everything from the environment.
+const client = new W6wClient();
+
+// Explicit arguments override W6W_BASE_URL and W6W_TOKEN.
+const other = new W6wClient({ baseUrl: "https://api.example.com", token: "…" });
+```
+
+### `W6W_BASE_URL` is an origin
+
+The client appends the API's base path (`/api`) itself, and never doubles it — so a value that
+already carries the prefix is left alone, and trailing slashes never matter:
+
+| `W6W_BASE_URL`                | Requests go to                  |
+| ----------------------------- | ------------------------------- |
+| `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/…` |
+
+A variable that is **set but empty** — or whitespace-only — counts as **unset**, in both variables.
+`W6W_BASE_URL=` is how a shell or a Dockerfile spells "I meant to set this and did not", so it
+raises the same configuration error as an absent one rather than quietly producing a relative URL.
+An empty string passed _explicitly_ to the constructor is likewise an error, and does not fall back
+to the environment.
+
+### `W6W_TOKEN`
+
+Sent as `Authorization: Bearer <token>` on **every** request — there are no anonymous operations on
+this API. A client with no token can still be constructed (so tools that only print help or a
+version work offline); the configuration error naming `W6W_TOKEN` surfaces on the first request.
+
+## Errors
+
+Two error types, and the difference between them is diagnostic:
+
+- **`ConfigError`** — the client never got as far as a request: no base URL, or no token.
+- **`ApiError`** — carries `status`, `code`, `message` and `raw` (the parsed response body, kept
+  because an error body carries fields the message drops). It covers exactly three cases: a
+  transport failure (`status: 0`, code `network_error`), a non-JSON body on a failing status (code
+  `bad_response`, with a snippet of what actually came back — usually a proxy's HTML error page),
+  and the server's own error envelope (its `code` and `message`, verbatim).
+
+Classify by `status`, and by a **prefix** of `code` (`unknown_*`, `invalid_*`, `*_exists`) — never
+by an exhaustive list of codes, which the server extends freely. Note that a `424` means the target
+app or its upstream vendor failed, not that w6w did; it is passed through untouched.
+
+Nothing is retried, no token is refreshed, and a `401` has no side effect beyond the raised error.
+
+## The surface
+
+What operations exist is not decided in this repo. It is defined by the shared machine-readable
+contract **`endpoints.json`**, which all three w6w wrappers implement and which each one's
+conformance test reads directly — the same file, never a vendored copy. An operation missing from a
+wrapper is a failing test, not a preference.
+
+Some operations are marked `planned` in that contract: they are implemented and unit-tested here,
+but the corresponding server route is not live yet, so calling them against a server today returns
+`404`. The marker records **server** readiness, not wrapper completeness.
+
+## Versioning
+
+The version is a shared fact across all three wrappers, so a release may go out for this package
+even when nothing in it changed — a divergent version is far more expensive than an empty release.
+
+Below `1.0.0`, **breaking changes may land in a minor bump.** That grace ends at `1.0.0`; do not
+plan around it.
+
+## Development
+
+The gates are Deno tasks. They need no network and no server:
+
+```bash
+deno task check      # typecheck mod.ts, src/ and tests/
+deno task lint
+deno task fmt:check
+deno task test       # every test runs against a mocked transport
+deno task cov        # test with coverage, then report it
+```
+
+Tests **never** require a live server. The npm `dist/` build (`npm run build`, i.e.
+`tsc -p tsconfig.build.json`) runs in CI only; `src/*.ts` is the single authored source for both
+registries.

package/dist/mod.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `@w6w/sdk` — the package barrel.
+ *
+ * This file is the package's single public entry point. `deno.json` exports it to
+ * JSR as `./mod.ts` (TypeScript source, verbatim) and `tsconfig.build.json`
+ * compiles it to `dist/mod.js` + `dist/mod.d.ts` for npm. One authored source
+ * tree, two registries (D7).
+ *
+ * **Every operation module must be re-exported here.** A module that is not
+ * re-exported from this barrel is not part of the published surface: JSR and npm
+ * consumers can only reach what this file exports, and the conformance runner
+ * walks the client built from these exports. Adding an operation therefore means
+ * adding its export line here in the same change.
+ *
+ * @module
+ */
+export { VERSION } from "./src/version.ts";
+export { W6wClient } from "./src/client.ts";
+export { ApiError, ConfigError } from "./src/errors.ts";
+export { BASE_PATH, type FetchLike, joinBaseUrl, type ResolvedConfig, type W6wClientOptions, } from "./src/config.ts";
+export type { HttpMethod, HttpResponse, QueryParams, RequestOptions } from "./src/http.ts";
+export { path } from "./src/http.ts";
+export { DocumentsApi } from "./src/documents.ts";
+export type { DocumentCreateInput, DocumentOptions, DocumentPatch, DocumentsHost, } from "./src/documents.ts";
+export { VarsApi } from "./src/vars.ts";
+export type { VarCreateInput, VarPatch, VarsHost } from "./src/vars.ts";
+export { fetchMe } from "./src/me.ts";
+export type { MeHost } from "./src/me.ts";
+export { ConnectionsApi } from "./src/connections.ts";
+export type { ConnectionsHost } from "./src/connections.ts";
+export { WorkflowsApi } from "./src/workflows.ts";
+export type { WorkflowListOptions, WorkflowRunOptions, WorkflowRunResult, WorkflowsHost, } from "./src/workflows.ts";
+export { runUrn } from "./src/run.ts";
+export type { RunHost, RunInput } from "./src/run.ts";
+export { isActionRun, isFunctionRun, isTerminalRunStatus, isWorkflowRun } from "./src/types.ts";
+export type { ActionRunEnvelope, ConnectionState, ConnectionSummary, Doc, DocFormat, FunctionRunEnvelope, Me, RunEnvelope, RunResult, RunStatus, StepError, UnknownRunEnvelope, Var, VarType, WorkflowRunEnvelope, WorkflowStatus, WorkflowSummary, } from "./src/types.ts";
+//# sourceMappingURL=mod.d.ts.map

package/dist/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAG3C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EACL,SAAS,EACT,KAAK,SAAS,EACd,WAAW,EACX,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAK3F,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAMrC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EACV,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,aAAa,GACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAOxE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,GACd,MAAM,oBAAoB,CAAC;AAK5B,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAOtD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEhG,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,GAAG,EACH,SAAS,EACT,mBAAmB,EACnB,EAAE,EACF,WAAW,EACX,SAAS,EACT,SAAS,EACT,SAAS,EACT,kBAAkB,EAClB,GAAG,EACH,OAAO,EACP,mBAAmB,EACnB,cAAc,EACd,eAAe,GAChB,MAAM,gBAAgB,CAAC"}

package/dist/mod.js

@@ -0,0 +1,51 @@
+/**
+ * `@w6w/sdk` — the package barrel.
+ *
+ * This file is the package's single public entry point. `deno.json` exports it to
+ * JSR as `./mod.ts` (TypeScript source, verbatim) and `tsconfig.build.json`
+ * compiles it to `dist/mod.js` + `dist/mod.d.ts` for npm. One authored source
+ * tree, two registries (D7).
+ *
+ * **Every operation module must be re-exported here.** A module that is not
+ * re-exported from this barrel is not part of the published surface: JSR and npm
+ * consumers can only reach what this file exports, and the conformance runner
+ * walks the client built from these exports. Adding an operation therefore means
+ * adding its export line here in the same change.
+ *
+ * @module
+ */
+export { VERSION } from "./src/version.js";
+// Transport core (T2.1.2): the client, its configuration and the error model.
+export { W6wClient } from "./src/client.js";
+export { ApiError, ConfigError } from "./src/errors.js";
+export { BASE_PATH, joinBaseUrl, } from "./src/config.js";
+// Exported because `W6wClient.request` is public: a host reaching an endpoint
+// this version does not model yet must have the same encoding-at-interpolation
+// tag the operation modules use, or it will concatenate a caller value into a
+// path by hand — the one bug the encoding pin exists to prevent.
+export { path } from "./src/http.js";
+// Asset operations (T2.1.3): documents and vars. The namespace classes are
+// exported alongside their input types because a host that types a helper
+// around `client.documents` needs to name them; they are reached through a
+// client, never constructed directly.
+export { DocumentsApi } from "./src/documents.js";
+export { VarsApi } from "./src/vars.js";
+// Identity and discovery (T2.1.4): `me`, plus the two list operations that make
+// a `conn_…` / `wf_…` id discoverable in the first place (D4). `me` is a method
+// on the client, so what is exported here is its host interface and the
+// standalone function the client delegates to — a host wiring its own transport
+// can call it without constructing a client.
+export { fetchMe } from "./src/me.js";
+export { ConnectionsApi } from "./src/connections.js";
+export { WorkflowsApi } from "./src/workflows.js";
+// Execution (T2.1.5): the URN-addressed `run`. `client.run(input)` is a method
+// on the client, so what is exported is its host interface, its input type and
+// the standalone function the client delegates to.
+export { runUrn } from "./src/run.js";
+// The `kind` discriminators. Exported deliberately and not as an afterthought:
+// `RunEnvelope`'s fourth arm is open (so an unknown `kind` can be handed back
+// rather than raised), and an open union means a bare `env.kind === "workflow"`
+// check does NOT narrow — `env.status` would come out `unknown`. These
+// predicates are how a caller, and the CLI, get typed access to an arm.
+export { isActionRun, isFunctionRun, isTerminalRunStatus, isWorkflowRun } from "./src/types.js";
+//# sourceMappingURL=mod.js.map

package/dist/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE3C,8EAA8E;AAC9E,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EACL,SAAS,EAET,WAAW,GAGZ,MAAM,iBAAiB,CAAC;AAEzB,8EAA8E;AAC9E,+EAA+E;AAC/E,8EAA8E;AAC9E,iEAAiE;AACjE,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAErC,2EAA2E;AAC3E,0EAA0E;AAC1E,2EAA2E;AAC3E,sCAAsC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAOlD,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAGxC,gFAAgF;AAChF,gFAAgF;AAChF,wEAAwE;AACxE,gFAAgF;AAChF,6CAA6C;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEtC,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAQlD,+EAA+E;AAC/E,+EAA+E;AAC/E,mDAAmD;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAGtC,+EAA+E;AAC/E,8EAA8E;AAC9E,gFAAgF;AAChF,uEAAuE;AACvE,wEAAwE;AACxE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/src/client.d.ts

@@ -0,0 +1,134 @@
+/**
+ * `W6wClient` — the object every operation hangs off.
+ *
+ * It holds three things and no behaviour of its own: the resolved
+ * configuration, the transport, and (from T2.1.3 onward) the operation
+ * namespaces. All of it is **instance** state.
+ *
+ * That is a mechanism pin, not a style choice (`docs/implementation.md` §2).
+ * The browser client this package transcribes keeps its token in a mutable
+ * module variable, which is fine for one page and an outright bug for a
+ * server-side SDK: two clients in one process would share one credential, so a
+ * host juggling tenants would silently issue requests as whichever tenant
+ * constructed a client last. Nothing in `src/` holds mutable module state.
+ *
+ * @module
+ */
+import { type ResolvedConfig, type W6wClientOptions } from "./config.ts";
+import { ConnectionsApi } from "./connections.ts";
+import { DocumentsApi } from "./documents.ts";
+import { type HttpResponse, type RequestOptions } from "./http.ts";
+import { type RunInput } from "./run.ts";
+import type { Me, RunEnvelope } from "./types.ts";
+import { VarsApi } from "./vars.ts";
+import { WorkflowsApi } from "./workflows.ts";
+/**
+ * A client for the w6w HTTP API.
+ *
+ * Construction resolves configuration once — explicit arguments first, then the
+ * environment (`W6W_BASE_URL`, `W6W_TOKEN`) — and never consults the
+ * environment again. A missing base URL raises here; a missing token raises on
+ * the first request, so a CLI can print `--help` offline.
+ *
+ * @example
+ * ```ts
+ * // From the environment.
+ * const client = new W6wClient();
+ *
+ * // Explicit, overriding the environment. Two clients, two credentials, one
+ * // process — no interference.
+ * const other = new W6wClient({ baseUrl: "https://api.example.com", token: "t_2" });
+ * ```
+ */
+export declare class W6wClient {
+    #private;
+    /**
+     * The resolved base URL, credential and default project. Exposed read-only
+     * so a host can log *which server* it is talking to without re-deriving the
+     * join rule.
+     */
+    readonly config: ResolvedConfig;
+    /**
+     * The document store: `list`, `get`, `getByKey`, `create`, `update`,
+     * `delete`. Project-scoped — every call accepts an optional `project` that
+     * overrides this client's default.
+     */
+    readonly documents: DocumentsApi;
+    /**
+     * Typed variables: `list`, `get`, `getByName`, `create`, `update`, `delete`.
+     * **No `project` option anywhere** — variables are scoped by tenant/subject
+     * only, and the namespace is constructed without this client's configuration
+     * so it cannot reach a default scope to send (`docs/implementation.md` §7).
+     */
+    readonly vars: VarsApi;
+    /**
+     * Connections: `list` only in this version. Read-only on purpose — creating
+     * or testing a connection is an interactive, secret-handling flow that
+     * `endpoints.json` puts out of scope for v0.1.0.
+     */
+    readonly connections: ConnectionsApi;
+    /**
+     * Workflows: `list` and `run`. `list` is project-scoped and accepts an
+     * optional `project` that overrides this client's default; `run` is addressed
+     * by `wf_…` id and takes `wait`, `variables` and `trigger`.
+     */
+    readonly workflows: WorkflowsApi;
+    /**
+     * @param options - Explicit configuration; anything omitted falls back to the environment.
+     * @throws {ConfigError} When no base URL is configured, or the host has no `fetch`.
+     */
+    constructor(options?: W6wClientOptions);
+    /**
+     * Who this client's credential says you are, plus the versions of the
+     * components that answered.
+     *
+     * A method on the client rather than a namespace, because that is the symbol
+     * `endpoints.json` names (`client.me()`). The response body is flat and
+     * carries no envelope; the only thing added to it locally is
+     * `versions.wrapper`, this package's own version, which is filled in and
+     * never overwrites a key the server supplied.
+     *
+     * @returns The caller's identity.
+     * @throws {ConfigError} When no token is configured.
+     * @throws {ApiError} On any non-2xx, e.g. a `401` when the token is rejected.
+     */
+    me(): Promise<Me>;
+    /**
+     * Run whatever a URN addresses — a connection action, a function, an endpoint
+     * or a workflow — and get back the kind-tagged envelope.
+     *
+     * A method on the client rather than a namespace, because that is the symbol
+     * `endpoints.json` names (`client.run(input)`). It is the dispatching
+     * counterpart to `workflows.run`, which stays separate because `?wait=`,
+     * `variables` and `trigger` have no slot in this three-field shape (D4).
+     *
+     * Discriminate the result with `isActionRun` / `isFunctionRun` /
+     * `isWorkflowRun`; a `kind` this version has never heard of is handed back
+     * verbatim rather than raised.
+     *
+     * `POST /api/run` (verified live 2026-07-28).
+     *
+     * @param input - The URN, an optional `action`, and the payload.
+     * @returns The `RunEnvelope`, exactly as it arrived.
+     * @throws {ConfigError} When no token is configured.
+     * @throws {ApiError} On any non-2xx, e.g. `404` for an unresolvable URN or
+     * `424` when the target app failed during execute.
+     */
+    run(input: RunInput): Promise<RunEnvelope>;
+    /**
+     * Perform one request against this client's server, with this client's
+     * credential.
+     *
+     * This is the seam the operation modules are built on; it is public so a host
+     * can also reach an endpoint this version does not model yet, rather than
+     * constructing a second client by hand. It returns the status alongside the
+     * body — a `202` is success on this API.
+     *
+     * @param options - The request to make.
+     * @returns The status and parsed body.
+     * @throws {ConfigError} When no token is configured.
+     * @throws {ApiError} On a transport failure, a non-JSON error body, or an error envelope.
+     */
+    request<T>(options: RequestOptions): Promise<HttpResponse<T>>;
+}
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACtB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,KAAK,YAAY,EAAW,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAE5E,OAAO,EAAE,KAAK,QAAQ,EAAU,MAAM,UAAU,CAAC;AACjD,OAAO,KAAK,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,SAAS;;IACpB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAEhC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IAEjC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC;IAErC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IAIjC;;;OAGG;gBACS,OAAO,GAAE,gBAAqB;IA4B1C;;;;;;;;;;;;;OAaG;IACH,EAAE,IAAI,OAAO,CAAC,EAAE,CAAC;IAIjB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,GAAG,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC;IAI1C;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;CAG9D"}

package/dist/src/client.js

@@ -0,0 +1,165 @@
+/**
+ * `W6wClient` — the object every operation hangs off.
+ *
+ * It holds three things and no behaviour of its own: the resolved
+ * configuration, the transport, and (from T2.1.3 onward) the operation
+ * namespaces. All of it is **instance** state.
+ *
+ * That is a mechanism pin, not a style choice (`docs/implementation.md` §2).
+ * The browser client this package transcribes keeps its token in a mutable
+ * module variable, which is fine for one page and an outright bug for a
+ * server-side SDK: two clients in one process would share one credential, so a
+ * host juggling tenants would silently issue requests as whichever tenant
+ * constructed a client last. Nothing in `src/` holds mutable module state.
+ *
+ * @module
+ */
+import { resolveConfig, } from "./config.js";
+import { ConnectionsApi } from "./connections.js";
+import { DocumentsApi } from "./documents.js";
+import { ConfigError } from "./errors.js";
+import { request } from "./http.js";
+import { fetchMe } from "./me.js";
+import { runUrn } from "./run.js";
+import { VarsApi } from "./vars.js";
+import { WorkflowsApi } from "./workflows.js";
+/**
+ * A client for the w6w HTTP API.
+ *
+ * Construction resolves configuration once — explicit arguments first, then the
+ * environment (`W6W_BASE_URL`, `W6W_TOKEN`) — and never consults the
+ * environment again. A missing base URL raises here; a missing token raises on
+ * the first request, so a CLI can print `--help` offline.
+ *
+ * @example
+ * ```ts
+ * // From the environment.
+ * const client = new W6wClient();
+ *
+ * // Explicit, overriding the environment. Two clients, two credentials, one
+ * // process — no interference.
+ * const other = new W6wClient({ baseUrl: "https://api.example.com", token: "t_2" });
+ * ```
+ */
+export class W6wClient {
+    /**
+     * The resolved base URL, credential and default project. Exposed read-only
+     * so a host can log *which server* it is talking to without re-deriving the
+     * join rule.
+     */
+    config;
+    /**
+     * The document store: `list`, `get`, `getByKey`, `create`, `update`,
+     * `delete`. Project-scoped — every call accepts an optional `project` that
+     * overrides this client's default.
+     */
+    documents;
+    /**
+     * Typed variables: `list`, `get`, `getByName`, `create`, `update`, `delete`.
+     * **No `project` option anywhere** — variables are scoped by tenant/subject
+     * only, and the namespace is constructed without this client's configuration
+     * so it cannot reach a default scope to send (`docs/implementation.md` §7).
+     */
+    vars;
+    /**
+     * Connections: `list` only in this version. Read-only on purpose — creating
+     * or testing a connection is an interactive, secret-handling flow that
+     * `endpoints.json` puts out of scope for v0.1.0.
+     */
+    connections;
+    /**
+     * Workflows: `list` and `run`. `list` is project-scoped and accepts an
+     * optional `project` that overrides this client's default; `run` is addressed
+     * by `wf_…` id and takes `wait`, `variables` and `trigger`.
+     */
+    workflows;
+    #fetch;
+    /**
+     * @param options - Explicit configuration; anything omitted falls back to the environment.
+     * @throws {ConfigError} When no base URL is configured, or the host has no `fetch`.
+     */
+    constructor(options = {}) {
+        this.config = resolveConfig(options);
+        if (options.fetch) {
+            this.#fetch = options.fetch;
+        }
+        else {
+            const global = globalThis.fetch;
+            if (typeof global !== "function") {
+                throw new ConfigError("This runtime has no global fetch. Pass an implementation " +
+                    "(new W6wClient({ fetch })) or run on Node 18+, Deno or Bun.");
+            }
+            // Bound, so the default keeps working when it is called as a bare
+            // function reference rather than as a method of the global object.
+            this.#fetch = global.bind(globalThis);
+        }
+        // Namespaces are per-instance and hold this client, so they inherit its
+        // credential and base URL — never a module-level one. `vars` and
+        // `connections` are handed the transport only; `documents` and `workflows`
+        // additionally see the configuration, because they are the project-scoped
+        // half of the surface and have a default project to apply.
+        this.documents = new DocumentsApi(this);
+        this.vars = new VarsApi(this);
+        this.connections = new ConnectionsApi(this);
+        this.workflows = new WorkflowsApi(this);
+    }
+    /**
+     * Who this client's credential says you are, plus the versions of the
+     * components that answered.
+     *
+     * A method on the client rather than a namespace, because that is the symbol
+     * `endpoints.json` names (`client.me()`). The response body is flat and
+     * carries no envelope; the only thing added to it locally is
+     * `versions.wrapper`, this package's own version, which is filled in and
+     * never overwrites a key the server supplied.
+     *
+     * @returns The caller's identity.
+     * @throws {ConfigError} When no token is configured.
+     * @throws {ApiError} On any non-2xx, e.g. a `401` when the token is rejected.
+     */
+    me() {
+        return fetchMe(this);
+    }
+    /**
+     * Run whatever a URN addresses — a connection action, a function, an endpoint
+     * or a workflow — and get back the kind-tagged envelope.
+     *
+     * A method on the client rather than a namespace, because that is the symbol
+     * `endpoints.json` names (`client.run(input)`). It is the dispatching
+     * counterpart to `workflows.run`, which stays separate because `?wait=`,
+     * `variables` and `trigger` have no slot in this three-field shape (D4).
+     *
+     * Discriminate the result with `isActionRun` / `isFunctionRun` /
+     * `isWorkflowRun`; a `kind` this version has never heard of is handed back
+     * verbatim rather than raised.
+     *
+     * `POST /api/run` (verified live 2026-07-28).
+     *
+     * @param input - The URN, an optional `action`, and the payload.
+     * @returns The `RunEnvelope`, exactly as it arrived.
+     * @throws {ConfigError} When no token is configured.
+     * @throws {ApiError} On any non-2xx, e.g. `404` for an unresolvable URN or
+     * `424` when the target app failed during execute.
+     */
+    run(input) {
+        return runUrn(this, input);
+    }
+    /**
+     * Perform one request against this client's server, with this client's
+     * credential.
+     *
+     * This is the seam the operation modules are built on; it is public so a host
+     * can also reach an endpoint this version does not model yet, rather than
+     * constructing a second client by hand. It returns the status alongside the
+     * body — a `202` is success on this API.
+     *
+     * @param options - The request to make.
+     * @returns The status and parsed body.
+     * @throws {ConfigError} When no token is configured.
+     * @throws {ApiError} On a transport failure, a non-JSON error body, or an error envelope.
+     */
+    request(options) {
+        return request(this.config, this.#fetch, options);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/src/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAEL,aAAa,GAGd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAqB,OAAO,EAAuB,MAAM,WAAW,CAAC;AAC5E,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAiB,MAAM,EAAE,MAAM,UAAU,CAAC;AAEjD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,SAAS;IACpB;;;;OAIG;IACM,MAAM,CAAiB;IAEhC;;;;OAIG;IACM,SAAS,CAAe;IAEjC;;;;;OAKG;IACM,IAAI,CAAU;IAEvB;;;;OAIG;IACM,WAAW,CAAiB;IAErC;;;;OAIG;IACM,SAAS,CAAe;IAExB,MAAM,CAAY;IAE3B;;;OAGG;IACH,YAAY,UAA4B,EAAE;QACxC,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAC9B,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC;YAChC,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;gBACjC,MAAM,IAAI,WAAW,CACnB,2DAA2D;oBACzD,6DAA6D,CAChE,CAAC;YACJ,CAAC;YACD,kEAAkE;YAClE,mEAAmE;YACnE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACxC,CAAC;QAED,wEAAwE;QACxE,iEAAiE;QACjE,2EAA2E;QAC3E,0EAA0E;QAC1E,2DAA2D;QAC3D,IAAI,CAAC,SAAS,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC,WAAW,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,CAAC,SAAS,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,EAAE;QACA,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,GAAG,CAAC,KAAe;QACjB,OAAO,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAI,OAAuB;QAChC,OAAO,OAAO,CAAI,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvD,CAAC;CACF"}