@w6w/sdk 0.5.0 → 0.6.0

package/dist/src/functions.d.ts

@@ -0,0 +1,88 @@
+/**
+ * `client.functions.*` — run a Function by the name you gave it.
+ *
+ * A Function is a canonical, vendor-stable interface bound to one swappable app
+ * Action. Before this namespace existed, calling one meant the URN operation:
+ *
+ * ```ts
+ * await client.run({ urn: "fn_a9b39917-cd4e-4eea-ab89-c3d079684193", payload });
+ * ```
+ *
+ * — an opaque id, buried inside an object, for a Function the user named
+ * `send-email`. `client.run` is still the right tool when the caller is
+ * *dispatching* something whose kind it does not know; it is the wrong tool for
+ * "call my send-email Function", which is what this is:
+ *
+ * ```ts
+ * await client.functions.run("send-email", { payload: { to, subject, html } });
+ * ```
+ *
+ * The name is the FIRST argument, matching `workflows.run(id, opts?)` — the
+ * namespace already shaped this way — so all three runnable kinds read alike.
+ *
+ * ID OR KEY, one argument. The server's `/functions/{idOrKey}/invoke` accepts
+ * either, because the two shapes cannot collide: an id carries a kind prefix and
+ * therefore an underscore, and a key is kebab-case, which forbids one. So this
+ * takes no flag and no prefix to say which you meant — pass whichever you have.
+ */
+import type { ResolvedConfig } from "./config.ts";
+import { type HttpResponse, type RequestOptions } from "./http.ts";
+/**
+ * What this namespace needs from the client — the same narrow seam
+ * `WorkflowsApi` takes, so it is constructible in a test and this module never
+ * imports the client back.
+ */
+export interface FunctionsHost {
+    /** The resolved configuration. */
+    readonly config: ResolvedConfig;
+    /** Perform one request. */
+    request<T>(options: RequestOptions): Promise<HttpResponse<T>>;
+}
+/** Per-call options for `functions.run`. */
+export interface FunctionRunOptions {
+    /**
+     * The Function's canonical inputs, by input key.
+     *
+     * Named `payload` rather than `inputs` so every runnable kind in this SDK
+     * takes the same word — the wire spells it `inputs` for a Function and
+     * `input` for an Endpoint, and reconciling that is exactly the job of a
+     * wrapper. Defaults to `{}` rather than being omitted: the server's parameter
+     * schemas are written against an object, and `{}` says "no input" where an
+     * absent key says "I forgot".
+     */
+    payload?: Record<string, unknown>;
+}
+/**
+ * The `functions` namespace on a `W6WClient`.
+ *
+ * @example
+ * ```ts
+ * const output = await client.functions.run("send-email", {
+ *   payload: { to: "ada@example.com", subject: "Hi", html: "<p>Hello</p>" },
+ * });
+ * ```
+ */
+export declare class FunctionsApi {
+    #private;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host: FunctionsHost);
+    /**
+     * Run one Function and return its output.
+     *
+     * Returns the Function's OUTPUT, not an envelope. `client.run` returns a
+     * `kind`-discriminated envelope because the caller does not know what the URN
+     * will resolve to; here the kind is in the method name, so the discriminant
+     * would be a field the caller has to unwrap to learn nothing.
+     *
+     * @param name - The Function's key (`"send-email"`) or its `fn_…` id. Percent-encoded into the path.
+     * @param options - `payload`, the Function's canonical inputs.
+     * @returns The Function's output, unwrapped from the `output` envelope.
+     * @throws {ApiError} `404 unknown_function` when no Function of that name exists for the caller.
+     * @throws {ApiError} `422 function_incomplete` when the Function has no runnable `impl`.
+     * @throws {ApiError} `bad_response` when a success body carries no `output` key at all.
+     */
+    run(name: string, options?: FunctionRunOptions): Promise<unknown>;
+}
+//# sourceMappingURL=functions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"functions.d.ts","sourceRoot":"","sources":["../../src/functions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAE,KAAK,YAAY,EAAQ,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,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,4CAA4C;AAC5C,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;;GASG;AACH,qBAAa,YAAY;;IAGvB;;OAEG;gBACS,IAAI,EAAE,aAAa;IAI/B;;;;;;;;;;;;;;OAcG;IACG,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;CAyBxE"}

package/dist/src/functions.js

@@ -0,0 +1,56 @@
+import { ApiError } from "./errors.js";
+import { path } from "./http.js";
+/**
+ * The `functions` namespace on a `W6WClient`.
+ *
+ * @example
+ * ```ts
+ * const output = await client.functions.run("send-email", {
+ *   payload: { to: "ada@example.com", subject: "Hi", html: "<p>Hello</p>" },
+ * });
+ * ```
+ */
+export class FunctionsApi {
+    #host;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host) {
+        this.#host = host;
+    }
+    /**
+     * Run one Function and return its output.
+     *
+     * Returns the Function's OUTPUT, not an envelope. `client.run` returns a
+     * `kind`-discriminated envelope because the caller does not know what the URN
+     * will resolve to; here the kind is in the method name, so the discriminant
+     * would be a field the caller has to unwrap to learn nothing.
+     *
+     * @param name - The Function's key (`"send-email"`) or its `fn_…` id. Percent-encoded into the path.
+     * @param options - `payload`, the Function's canonical inputs.
+     * @returns The Function's output, unwrapped from the `output` envelope.
+     * @throws {ApiError} `404 unknown_function` when no Function of that name exists for the caller.
+     * @throws {ApiError} `422 function_incomplete` when the Function has no runnable `impl`.
+     * @throws {ApiError} `bad_response` when a success body carries no `output` key at all.
+     */
+    async run(name, options) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: path `/functions/${name}/invoke`,
+            body: { inputs: options?.payload ?? {} },
+        });
+        // Deliberately NOT `unwrap(res, "output")`. That helper treats `null` as
+        // "the server did not send what it promised" — correct for a `documents` or
+        // `vars` envelope, where null is never a document. It is wrong here: a
+        // Function's output is an OPAQUE pass-through, and an action that returns
+        // nothing yields `{"output": null}`, which is a successful run and not a
+        // malformed response. So the guard is PRESENCE of the key, not truthiness
+        // of the value.
+        const body = res.body;
+        if (typeof body !== "object" || body === null || !("output" in body)) {
+            throw new ApiError(res.status, "bad_response", `Server returned a ${res.status} with no "output" in the response body.`, body);
+        }
+        return body.output;
+    }
+}
+//# sourceMappingURL=functions.js.map

package/dist/src/functions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"functions.js","sourceRoot":"","sources":["../../src/functions.ts"],"names":[],"mappings":"AA4BA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAqB,IAAI,EAAuB,MAAM,WAAW,CAAC;AA6BzE;;;;;;;;;GASG;AACH,MAAM,OAAO,YAAY;IACd,KAAK,CAAgB;IAE9B;;OAEG;IACH,YAAY,IAAmB;QAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,GAAG,CAAC,IAAY,EAAE,OAA4B;QAClD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAA,cAAc,IAAI,SAAS;YACrC,IAAI,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,EAAE;SACzC,CAAC,CAAC;QAEH,yEAAyE;QACzE,4EAA4E;QAC5E,uEAAuE;QACvE,0EAA0E;QAC1E,yEAAyE;QACzE,0EAA0E;QAC1E,gBAAgB;QAChB,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;QACtB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,QAAQ,IAAI,IAAI,CAAC,EAAE,CAAC;YACrE,MAAM,IAAI,QAAQ,CAChB,GAAG,CAAC,MAAM,EACV,cAAc,EACd,qBAAqB,GAAG,CAAC,MAAM,yCAAyC,EACxE,IAAI,CACL,CAAC;QACJ,CAAC;QACD,OAAQ,IAA4B,CAAC,MAAM,CAAC;IAC9C,CAAC;CACF"}

package/dist/src/run.d.ts

@@ -2,8 +2,9 @@
  * `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:
+ * `conn_…`, `wf_…`, `fn_…` and `ep_…` arms (D16), and, additionally, an
+ * account-scoped alias name (kebab-slug, `_`-free, which is why no flag is
+ * needed to disambiguate the two) — and the answer says which one it hit:
  *
  * | `kind` | Field | HTTP |
  * |---|---|---|
@@ -63,7 +64,11 @@ export interface RunHost {
  * uses it for its `wf_…` id.)
  */
 export interface RunInput {
-    /** What to run: `conn_…`, `wf_…`, `fn_…` or `ep_…`. */
+    /**
+     * What to run: `conn_…`, `wf_…`, `fn_…`, `ep_…`, or, additionally, an
+     * account-scoped alias name (kebab-slug, `_`-free, which is why no flag is
+     * needed to disambiguate the two).
+     */
     urn: string;
     /**
      * Which action to invoke. Optional, because a workflow, function or endpoint

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

@@ -1 +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"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;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;;;;OAIG;IACH,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

@@ -2,8 +2,9 @@
  * `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:
+ * `conn_…`, `wf_…`, `fn_…` and `ep_…` arms (D16), and, additionally, an
+ * account-scoped alias name (kebab-slug, `_`-free, which is why no flag is
+ * needed to disambiguate the two) — and the answer says which one it hit:
  *
  * | `kind` | Field | HTTP |
  * |---|---|---|

package/dist/src/run.js.map

@@ -1 +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"}
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAwCvC;;;;;;;;;;;;;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"}

package/dist/src/version.js

@@ -10,5 +10,5 @@
  * this file as TypeScript source and rejects inferred public types ("no slow
  * types").
  */
-export const VERSION = "0.5.0";
+export const VERSION = "0.6.0";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@w6w/sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Typed client for the w6w HTTP API. Thin transport, auth and error mapping — nothing else.",
   "license": "MIT",
   "repository": {