@w6w/sdk 0.1.0

package/dist/src/http.js

@@ -0,0 +1,150 @@
+/**
+ * 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 { requireToken } from "./config.js";
+import { ApiError } from "./errors.js";
+/**
+ * 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 function path(strings, ...values) {
+    return strings.reduce((acc, fragment, i) => i === 0 ? fragment : `${acc}${encodeURIComponent(values[i - 1])}${fragment}`, "");
+}
+/**
+ * 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 function buildUrl(config, options) {
+    const params = new URLSearchParams();
+    for (const [name, value] of Object.entries(options.query ?? {})) {
+        if (value !== undefined)
+            params.set(name, String(value));
+    }
+    const query = params.toString();
+    return `${config.baseUrl}${options.path}${query ? `?${query}` : ""}`;
+}
+/**
+ * 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 async function request(config, fetchImpl, options) {
+    const url = buildUrl(config, options);
+    const headers = new Headers();
+    // Resolved per request rather than at construction: a client with no token is
+    // constructible (so a CLI's --help works offline) and fails here instead.
+    headers.set("authorization", `Bearer ${requireToken(config)}`);
+    const hasBody = options.body !== undefined;
+    if (hasBody)
+        headers.set("content-type", "application/json");
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: options.method,
+            headers,
+            body: hasBody ? JSON.stringify(options.body) : undefined,
+        });
+    }
+    catch (err) {
+        throw new ApiError(0, "network_error", `Could not reach the w6w server (${options.method} ${url}). ` +
+            `It may be down or unreachable. (${err instanceof Error ? err.message : String(err)})`);
+    }
+    // Read the body exactly once, as text, then parse it guardedly — a response
+    // body is a single-use stream, and `res.json()` on an HTML error page throws
+    // an opaque SyntaxError that loses the page.
+    const text = await res.text();
+    let data = null;
+    if (text) {
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            if (!res.ok) {
+                throw new ApiError(res.status, "bad_response", `Server returned a non-JSON ${res.status} response: ${text.slice(0, 200)}`);
+            }
+        }
+    }
+    if (!res.ok) {
+        const envelope = data?.error ?? {};
+        throw new ApiError(res.status, envelope.code ?? "error", envelope.message ?? res.statusText, data);
+    }
+    return { status: res.status, body: data };
+}
+//# sourceMappingURL=http.js.map

package/dist/src/http.js.map

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

package/dist/src/me.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `client.me()` — who the caller is, and what answered.
+ *
+ * One GET to `/auth/me` — the server's real identity route (verified live).
+ * The response body is **flat** — `{tenant, subject, account, role,
+ * versions?}` — so there is nothing for `unwrap` to do here, and this is the
+ * one read operation in the package that does not call it.
+ *
+ * The one thing this module adds to the body is `versions.wrapper`, which the
+ * server cannot know — it is this package's own published version. It is a
+ * **fill, never an overwrite**: a key the server supplied wins, including
+ * `wrapper` itself, so a future host that has a better answer is not silently
+ * overruled by the client. The server does not send a `versions` block today,
+ * so every call currently returns just `{wrapper: VERSION}` — expected, not
+ * an error.
+ *
+ * It is deliberately not a namespace class. `endpoints.json` names this
+ * operation `client.me()`, a method on the client itself, so the module exports
+ * a function over a narrow host interface and `W6wClient` delegates to it —
+ * same layering as the namespaces, without inventing a `client.me.me()`.
+ *
+ * @module
+ */
+import type { HttpResponse, RequestOptions } from "./http.ts";
+import type { Me } from "./types.ts";
+/**
+ * The slice of `W6wClient` this operation needs: the transport, and nothing
+ * else. Structural rather than a concrete client type, so it stays
+ * independently callable in a test and this module never imports the client
+ * back.
+ */
+export interface MeHost {
+    /** Perform one request. */
+    request<T>(options: RequestOptions): Promise<HttpResponse<T>>;
+}
+/**
+ * Fetch the caller's identity and the component versions behind it.
+ *
+ * The identity fields are returned exactly as they arrived — unknown ones
+ * included, since the return is an interface and not a closed schema.
+ * `versions` is normalised to always exist and to always carry a `wrapper`
+ * entry, so a caller printing a version banner never has to branch on whether
+ * the server sent the block at all.
+ *
+ * @param host - The client this operation issues its request through.
+ * @returns The caller's identity, with `versions.wrapper` filled in.
+ * @throws {ApiError} On any non-2xx, e.g. `401` when the token is not accepted.
+ * @throws {ApiError} `bad_response` when a 2xx body is not a plain object — an
+ * array included, since `typeof [] === "object"` and a spread array yields
+ * character-indexed keys rather than identity fields.
+ */
+export declare function fetchMe(host: MeHost): Promise<Me>;
+//# sourceMappingURL=me.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"me.d.ts","sourceRoot":"","sources":["../../src/me.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,YAAY,CAAC;AAGrC;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,2BAA2B;IAC3B,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC,CAuCvD"}

package/dist/src/me.js

@@ -0,0 +1,77 @@
+/**
+ * `client.me()` — who the caller is, and what answered.
+ *
+ * One GET to `/auth/me` — the server's real identity route (verified live).
+ * The response body is **flat** — `{tenant, subject, account, role,
+ * versions?}` — so there is nothing for `unwrap` to do here, and this is the
+ * one read operation in the package that does not call it.
+ *
+ * The one thing this module adds to the body is `versions.wrapper`, which the
+ * server cannot know — it is this package's own published version. It is a
+ * **fill, never an overwrite**: a key the server supplied wins, including
+ * `wrapper` itself, so a future host that has a better answer is not silently
+ * overruled by the client. The server does not send a `versions` block today,
+ * so every call currently returns just `{wrapper: VERSION}` — expected, not
+ * an error.
+ *
+ * It is deliberately not a namespace class. `endpoints.json` names this
+ * operation `client.me()`, a method on the client itself, so the module exports
+ * a function over a narrow host interface and `W6wClient` delegates to it —
+ * same layering as the namespaces, without inventing a `client.me.me()`.
+ *
+ * @module
+ */
+import { ApiError } from "./errors.js";
+import { VERSION } from "./version.js";
+/**
+ * Fetch the caller's identity and the component versions behind it.
+ *
+ * The identity fields are returned exactly as they arrived — unknown ones
+ * included, since the return is an interface and not a closed schema.
+ * `versions` is normalised to always exist and to always carry a `wrapper`
+ * entry, so a caller printing a version banner never has to branch on whether
+ * the server sent the block at all.
+ *
+ * @param host - The client this operation issues its request through.
+ * @returns The caller's identity, with `versions.wrapper` filled in.
+ * @throws {ApiError} On any non-2xx, e.g. `401` when the token is not accepted.
+ * @throws {ApiError} `bad_response` when a 2xx body is not a plain object — an
+ * array included, since `typeof [] === "object"` and a spread array yields
+ * character-indexed keys rather than identity fields.
+ */
+export async function fetchMe(host) {
+    const res = await host.request({ method: "GET", path: "/auth/me" });
+    const body = res.body;
+    // A body that is not an object cannot be identity data. Raise rather than
+    // spread it — the same `bad_response` class the envelope reader uses for the
+    // keyed routes — so a proxy answering `200 "ok"` fails here instead of
+    // returning a `Me` whose only populated field is the one this client just
+    // added.
+    //
+    // `Array.isArray` is load-bearing, not belt-and-braces: `typeof [] === "object"`
+    // and `[] !== null`, so without it a `200 []` spread into exactly the degenerate
+    // value described above — measured, `{"versions":{"wrapper":"0.1.0"}}` — and
+    // `200 [{...}]` produced character-indexed keys. It also keeps this lane in step
+    // with python, whose natural `isinstance(body, dict)` excludes a list already.
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+        throw new ApiError(res.status, "bad_response", `Server returned a ${res.status} whose body is not an identity object.`, body);
+    }
+    // Same reasoning one level down: `versions` is typed `Record<string, string>`,
+    // but the wire can carry anything, and spreading a string produces
+    // character-indexed junk (`"1.2.3"` → `{"0":"1","1":".",…}`) that satisfies the
+    // type and so is invisible to the compiler. A `versions` that is not a plain
+    // object is dropped in favour of the client's own fill rather than merged —
+    // this operation reports identity, and inventing keys out of a malformed block
+    // would be worse than reporting only what this client actually knows.
+    const versions = body.versions;
+    const merged = typeof versions === "object" && versions !== null && !Array.isArray(versions)
+        ? versions
+        : undefined;
+    return {
+        ...body,
+        // Spread order is the policy: the wrapper's own version is the DEFAULT and
+        // every key the server sent lands on top of it, `wrapper` included.
+        versions: { wrapper: VERSION, ...merged },
+    };
+}
+//# sourceMappingURL=me.js.map

package/dist/src/me.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"me.js","sourceRoot":"","sources":["../../src/me.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAavC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAY;IACxC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAK,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;IACxE,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,0EAA0E;IAC1E,6EAA6E;IAC7E,uEAAuE;IACvE,0EAA0E;IAC1E,SAAS;IACT,EAAE;IACF,iFAAiF;IACjF,iFAAiF;IACjF,6EAA6E;IAC7E,iFAAiF;IACjF,+EAA+E;IAC/E,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,QAAQ,CAChB,GAAG,CAAC,MAAM,EACV,cAAc,EACd,qBAAqB,GAAG,CAAC,MAAM,wCAAwC,EACvE,IAAI,CACL,CAAC;IACJ,CAAC;IACD,+EAA+E;IAC/E,mEAAmE;IACnE,gFAAgF;IAChF,6EAA6E;IAC7E,4EAA4E;IAC5E,+EAA+E;IAC/E,sEAAsE;IACtE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAC/B,MAAM,MAAM,GAAG,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;QAC1F,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,SAAS,CAAC;IACd,OAAO;QACL,GAAG,IAAI;QACP,2EAA2E;QAC3E,oEAAoE;QACpE,QAAQ,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,EAAE;KAC1C,CAAC;AACJ,CAAC"}

package/dist/src/run.d.ts

@@ -0,0 +1,92 @@
+/**
+ * `client.run({urn, action, payload})` — run anything a URN addresses.
+ *
+ * One POST, one kind-tagged body, no envelope key. The URN resolves over the
+ * four runnable arms — `conn_…`, `wf_…`, `fn_…`, `ep_…` (D16) — and the answer
+ * says which one it hit:
+ *
+ * | `kind` | Field | HTTP |
+ * |---|---|---|
+ * | `"action"` | `value` | `200` |
+ * | `"function"` | `output` | `200` |
+ * | `"workflow"` | `runId` + `status` | `202` |
+ *
+ * `value` and `output` are **deliberately different names** and are never
+ * normalised into one field: the discrimination is the whole point of the
+ * operation (D3). `202` on the workflow arm is **success** — the run is queued
+ * and `runId` is how the caller follows it.
+ *
+ * ── The unknown fourth kind ──
+ * A `kind` this release has never heard of is **returned verbatim**, never
+ * raised (`docs/implementation.md` §5). `run` dispatches on whatever a URN
+ * resolves to, and the server can grow a new kind before the wrappers do — a
+ * purely additive change. Raising would turn that into a hard breakage for every
+ * installed client on the one operation whose entire job is dispatch, and would
+ * leave the caller with an exception instead of a payload this module had
+ * already parsed and held. Callers discriminate with `isActionRun`,
+ * `isFunctionRun` and `isWorkflowRun` (`src/types.ts`), which narrow properly —
+ * a bare `env.kind === "action"` check does not, because the union is open.
+ *
+ * `POST /api/run` (verified live 2026-07-28): the URN resolver dispatches to
+ * the same runner each dedicated route already uses — no new execution path.
+ *
+ * ── Why this is not folded into `workflows.run` ──
+ * D4: `?wait=`, `variables` and `trigger` have no slot in the three-field
+ * `{urn, action, payload}` shape, and a workflow has no `action`. The two
+ * operations ship side by side — this one dispatches, `workflows.run` is the
+ * typed path.
+ *
+ * Like `me`, this is a function over a narrow host interface rather than a
+ * namespace class, because `endpoints.json` names the symbol `client.run(input)`
+ * — a method on the client itself, not a `client.run.run()`.
+ *
+ * @module
+ */
+import type { HttpResponse, RequestOptions } from "./http.ts";
+import type { RunEnvelope } from "./types.ts";
+/**
+ * The slice of `W6wClient` this operation needs: the transport, and nothing
+ * else. Structural rather than a concrete client type, so it stays
+ * independently callable in a test and this module never imports the client
+ * back.
+ */
+export interface RunHost {
+    /** Perform one request. */
+    request<T>(options: RequestOptions): Promise<HttpResponse<T>>;
+}
+/**
+ * The body of `client.run()`.
+ *
+ * All three fields travel in the **request body**, so none of them is
+ * percent-encoded: `/run` is a fixed path with no interpolation, and a URN in
+ * JSON needs no escaping. (The `path` tag is for path segments — `workflows.run`
+ * uses it for its `wf_…` id.)
+ */
+export interface RunInput {
+    /** What to run: `conn_…`, `wf_…`, `fn_…` or `ep_…`. */
+    urn: string;
+    /**
+     * Which action to invoke. Optional, because a workflow, function or endpoint
+     * URN has no action; required in practice for a `conn_…` URN, and the server
+     * is what says so — this client does not second-guess the URN's arm.
+     */
+    action?: string;
+    /** Input to the run. Defaults to `{}`. Opaque pass-through. */
+    payload?: Record<string, unknown>;
+}
+/**
+ * Run whatever a URN addresses.
+ *
+ * @param host - The client this operation issues its request through.
+ * @param input - The URN, the optional action, and the payload.
+ * @returns The kind-tagged envelope, with `kind` and the arm's field verbatim.
+ * @throws {ApiError} On any non-2xx — `404` for an unresolvable URN, `424` when
+ * the app or its upstream vendor failed during execute (a 4xx on purpose, so
+ * Cloudflare cannot swallow the message; never normalised into a transport
+ * error).
+ * @throws {ApiError} `bad_response` when a success body carries no `kind` at all
+ * — that is a malformed dispatch response, not a new arm, and it is the one
+ * shape a caller cannot do anything with.
+ */
+export declare function runUrn(host: RunHost, input: RunInput): Promise<RunEnvelope>;
+//# sourceMappingURL=run.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,2BAA2B;IAC3B,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC,CA8BjF"}

package/dist/src/run.js

@@ -0,0 +1,83 @@
+/**
+ * `client.run({urn, action, payload})` — run anything a URN addresses.
+ *
+ * One POST, one kind-tagged body, no envelope key. The URN resolves over the
+ * four runnable arms — `conn_…`, `wf_…`, `fn_…`, `ep_…` (D16) — and the answer
+ * says which one it hit:
+ *
+ * | `kind` | Field | HTTP |
+ * |---|---|---|
+ * | `"action"` | `value` | `200` |
+ * | `"function"` | `output` | `200` |
+ * | `"workflow"` | `runId` + `status` | `202` |
+ *
+ * `value` and `output` are **deliberately different names** and are never
+ * normalised into one field: the discrimination is the whole point of the
+ * operation (D3). `202` on the workflow arm is **success** — the run is queued
+ * and `runId` is how the caller follows it.
+ *
+ * ── The unknown fourth kind ──
+ * A `kind` this release has never heard of is **returned verbatim**, never
+ * raised (`docs/implementation.md` §5). `run` dispatches on whatever a URN
+ * resolves to, and the server can grow a new kind before the wrappers do — a
+ * purely additive change. Raising would turn that into a hard breakage for every
+ * installed client on the one operation whose entire job is dispatch, and would
+ * leave the caller with an exception instead of a payload this module had
+ * already parsed and held. Callers discriminate with `isActionRun`,
+ * `isFunctionRun` and `isWorkflowRun` (`src/types.ts`), which narrow properly —
+ * a bare `env.kind === "action"` check does not, because the union is open.
+ *
+ * `POST /api/run` (verified live 2026-07-28): the URN resolver dispatches to
+ * the same runner each dedicated route already uses — no new execution path.
+ *
+ * ── Why this is not folded into `workflows.run` ──
+ * D4: `?wait=`, `variables` and `trigger` have no slot in the three-field
+ * `{urn, action, payload}` shape, and a workflow has no `action`. The two
+ * operations ship side by side — this one dispatches, `workflows.run` is the
+ * typed path.
+ *
+ * Like `me`, this is a function over a narrow host interface rather than a
+ * namespace class, because `endpoints.json` names the symbol `client.run(input)`
+ * — a method on the client itself, not a `client.run.run()`.
+ *
+ * @module
+ */
+import { ApiError } from "./errors.js";
+/**
+ * Run whatever a URN addresses.
+ *
+ * @param host - The client this operation issues its request through.
+ * @param input - The URN, the optional action, and the payload.
+ * @returns The kind-tagged envelope, with `kind` and the arm's field verbatim.
+ * @throws {ApiError} On any non-2xx — `404` for an unresolvable URN, `424` when
+ * the app or its upstream vendor failed during execute (a 4xx on purpose, so
+ * Cloudflare cannot swallow the message; never normalised into a transport
+ * error).
+ * @throws {ApiError} `bad_response` when a success body carries no `kind` at all
+ * — that is a malformed dispatch response, not a new arm, and it is the one
+ * shape a caller cannot do anything with.
+ */
+export async function runUrn(host, input) {
+    const res = await host.request({
+        method: "POST",
+        path: "/run",
+        body: {
+            urn: input.urn,
+            action: input.action,
+            // Defaulted rather than omitted: the server's parameter schemas are
+            // written against an object, and `{}` says "no input" where an absent key
+            // says "I forgot".
+            payload: input.payload ?? {},
+        },
+    });
+    const body = res.body;
+    if (typeof body !== "object" || body === null ||
+        typeof body.kind !== "string") {
+        throw new ApiError(res.status, "bad_response", `Server returned a ${res.status} with no "kind" in the response body.`, body);
+    }
+    // Returned as it arrived — no rebuild, no field renaming, no per-arm
+    // destructure. An unknown `kind` therefore reaches the caller with every
+    // sibling field intact.
+    return body;
+}
+//# sourceMappingURL=run.js.map

package/dist/src/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAoCvC;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAa,EAAE,KAAe;IACzD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAU;QACtC,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE;YACJ,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,oEAAoE;YACpE,0EAA0E;YAC1E,mBAAmB;YACnB,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;SAC7B;KACF,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,IACE,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;QACzC,OAAQ,IAA2B,CAAC,IAAI,KAAK,QAAQ,EACrD,CAAC;QACD,MAAM,IAAI,QAAQ,CAChB,GAAG,CAAC,MAAM,EACV,cAAc,EACd,qBAAqB,GAAG,CAAC,MAAM,uCAAuC,EACtE,IAAI,CACL,CAAC;IACJ,CAAC;IACD,qEAAqE;IACrE,yEAAyE;IACzE,wBAAwB;IACxB,OAAO,IAAmB,CAAC;AAC7B,CAAC"}