@w6w/sdk 0.6.0 → 0.9.9

package/dist/src/team.d.ts

@@ -0,0 +1,204 @@
+/**
+ * `client.team.*` — the caller's account team, self-service.
+ *
+ * Six operations, one HTTP call each: list the roster, invite someone (or mint
+ * an open, shareable invite link), list open invites, revoke one, change a
+ * member's role, remove a member. Nothing here composes two requests or
+ * filters a list client-side — `team.invites()` returns only OPEN invites
+ * because the **server** filters them, not because this module scans the
+ * account's whole invite history and drops the closed ones
+ * (`docs/implementation.md`'s "what a wrapper is" rule, mirrored from
+ * `documents.ts`'s header).
+ *
+ * **Not project-scoped.** Team membership is an account-wide concept, so
+ * (unlike `documents`) this namespace carries no `?project=` anywhere and is
+ * handed the transport only — the same narrow host `connections.ts` and
+ * `vars.ts` use, so a caller cannot even accidentally reach a default project
+ * to send.
+ *
+ * `docs/team.md`'s pinned wire contract (mirrored in this task's `plan.md`
+ * §"Pinned wire contract") is the source these six methods transcribe:
+ *
+ * ```
+ * GET    /me/account/members                      → 200 { members: TeamMember[] }
+ * POST   /me/account/invites   { email?, role? }  → 201 { invite: TeamInviteWithLink }
+ * GET    /me/account/invites                      → 200 { invites: TeamInvite[] }
+ * DELETE /me/account/invites/:id                  → 200 { ok: true }
+ * PATCH  /me/account/members/:userId  { role }    → 200 { member: TeamMember }
+ * DELETE /me/account/members/:userId              → 200 { ok: true }
+ * ```
+ *
+ * This module implements the client half of the server's live
+ * `/me/account/...` routes (`endpoints.json`: `status: "required"` for each).
+ * Calling any of these against a server that has not shipped T1.2.1 yet
+ * answers `404`, which reaches the caller as an ordinary `ApiError`.
+ *
+ * @module
+ */
+import { type HttpResponse, type RequestOptions } from "./http.ts";
+/**
+ * The slice of `W6WClient` this namespace needs: the transport, and nothing
+ * else. Team operations carry no per-call scope to resolve, so — as with
+ * `connections` and `vars` — this host cannot reach the client's
+ * configuration even by accident.
+ */
+export interface TeamHost {
+    /** Perform one request. */
+    request<T>(options: RequestOptions): Promise<HttpResponse<T>>;
+}
+/**
+ * One member of the caller's account team, as the roster projects it.
+ *
+ * `email`/`displayName` are nullable rather than defaulted to `""`: a member
+ * whose profile carries neither is a real, distinct state (a machine
+ * principal, or a user who has set up neither) and flattening it to an empty
+ * string would make "no display name" indistinguishable from "the server sent
+ * an empty one".
+ */
+export interface TeamMember {
+    /** The member's `usr_…` id — addresses `setRole` and `removeMember`. */
+    userId: string;
+    /** The member's email, or `null` when the profile carries none. */
+    email: string | null;
+    /** The member's display name, or `null` when unset. */
+    displayName: string | null;
+    /** The member's role within the account, e.g. `"owner"`, `"admin"`, `"member"`. */
+    role: string;
+    /** ISO-8601 timestamp: when this membership began. */
+    createdAt: string;
+}
+/**
+ * One invite, as `team.invites()` lists it.
+ *
+ * Deliberately carries no `token` — see {@linkcode TeamInviteWithLink}, the
+ * only response that does, and only once.
+ */
+export interface TeamInvite {
+    /** The invite's own id — addresses `revokeInvite`. */
+    id: string;
+    /** The account this invite joins. */
+    account: string;
+    /** The invited email, or `null` for an open (link-only) invite. */
+    email: string | null;
+    /** The role the invite grants on redemption, or `null` (server defaults to `"member"`). */
+    role: string | null;
+    /** ISO-8601 expiry, or `null` for an invite that does not expire. */
+    expiresAt: string | null;
+    /** ISO-8601 timestamp: when this invite was created. */
+    createdAt: string;
+}
+/**
+ * What `team.invite()` returns: a {@linkcode TeamInvite} plus the redemption
+ * material, present **only** in this one response.
+ *
+ * The server never re-sends `token` or `redemptionLink` from any other route
+ * — `team.invites()` lists the invite without them — so a caller that drops
+ * this return value cannot recover it and must revoke and re-invite instead.
+ */
+export interface TeamInviteWithLink extends TeamInvite {
+    /** The plaintext redemption token. Shown once. */
+    token: string;
+    /** The ready-to-share redemption URL, built around `token`. Shown once. */
+    redemptionLink: string;
+}
+/**
+ * The body of `team.invite()`.
+ *
+ * Both fields are optional: an omitted `email` mints an OPEN invite (a
+ * shareable link with no target address), and an omitted `role` defaults
+ * server-side to `"member"`. `"owner"` is refused — there is no self-service
+ * path to a second owner.
+ */
+export interface TeamInviteInput {
+    /** The address to invite. Omitted for an open, shareable invite. */
+    email?: string;
+    /** The role the invite grants on redemption. Omitted defaults to `"member"`. */
+    role?: string;
+}
+/**
+ * The `team` namespace on a `W6WClient`.
+ *
+ * @example
+ * ```ts
+ * const members = await client.team.members();
+ * const { redemptionLink } = await client.team.invite({ role: "admin" });
+ * await client.team.setRole(members[0].userId, "admin");
+ * ```
+ */
+export declare class TeamApi {
+    #private;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host: TeamHost);
+    /**
+     * List the caller's account team.
+     *
+     * Member-readable: any active member of the account may call this,
+     * regardless of role — only the write operations below require
+     * `canManageMembers`.
+     *
+     * @returns The team, unwrapped from the `members` envelope.
+     * @throws {ApiError} On any non-2xx.
+     */
+    members(): Promise<TeamMember[]>;
+    /**
+     * Invite someone to the account, or mint an open, shareable invite link.
+     *
+     * @param input - `email` and `role`, both optional.
+     * @returns The created invite, including its one-time `token` and `redemptionLink`.
+     * @throws {ApiError} `403 forbidden` without `canManageMembers`.
+     * @throws {ApiError} `400 invalid_role` for `role: "owner"` or an unrecognised role.
+     */
+    invite(input?: TeamInviteInput): Promise<TeamInviteWithLink>;
+    /**
+     * List the account's open (pending, unrevoked, unexpired) invites.
+     *
+     * The filtering happens server-side — this is one `GET`, never a
+     * list-then-filter over the account's whole invite history.
+     *
+     * @returns The open invites, unwrapped from the `invites` envelope.
+     * @throws {ApiError} `403 forbidden` without `canManageMembers`.
+     */
+    invites(): Promise<TeamInvite[]>;
+    /**
+     * Revoke a pending invite before it is redeemed.
+     *
+     * Not idempotent: revoking an invite that is already used or already
+     * revoked is a rejected request, not a silent success.
+     *
+     * @param id - The invite's own id (see: `team.invites()`).
+     * @throws {ApiError} `403 forbidden` without `canManageMembers`.
+     * @throws {ApiError} `404 invite_not_found` for an unknown id.
+     * @throws {ApiError} `409 invite_not_open` when it was already used or revoked.
+     */
+    revokeInvite(id: string): Promise<void>;
+    /**
+     * Change a team member's role.
+     *
+     * @param userId - The member's `usr_…` id (see: `team.members()`).
+     * @param role - The role to set.
+     * @returns The updated member.
+     * @throws {ApiError} `403 forbidden` without `canManageMembers`.
+     * @throws {ApiError} `403 cannot_change_owner_role` for `role: "owner"` or when
+     * `userId` is the account's current owner — there is no self-service ownership transfer.
+     * @throws {ApiError} `400 invalid_role` for an unrecognised role.
+     * @throws {ApiError} `404 member_not_found` for an unknown `userId`.
+     */
+    setRole(userId: string, role: string): Promise<TeamMember>;
+    /**
+     * Remove a member from the account.
+     *
+     * Tombstones the membership server-side rather than deleting it outright
+     * (D-R3), but that is a server implementation detail this method does not
+     * surface — it returns nothing, the same pin as `documents.delete`.
+     *
+     * @param userId - The member's `usr_…` id (see: `team.members()`).
+     * @throws {ApiError} `403 forbidden` without `canManageMembers`.
+     * @throws {ApiError} `403 cannot_remove_owner` when `userId` is the account's owner.
+     * @throws {ApiError} `404 member_not_found` for an unknown `userId`.
+     * @throws {ApiError} `409 last_member` when `userId` is the account's only active member.
+     */
+    removeMember(userId: string): Promise<void>;
+}
+//# sourceMappingURL=team.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"team.d.ts","sourceRoot":"","sources":["../../src/team.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAQ,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAGzE;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,2BAA2B;IAC3B,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,uDAAuD;IACvD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,2FAA2F;IAC3F,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,qEAAqE;IACrE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,qBAAa,OAAO;;IAGlB;;OAEG;gBACS,IAAI,EAAE,QAAQ;IAI1B;;;;;;;;;OASG;IACG,OAAO,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAKtC;;;;;;;OAOG;IACG,MAAM,CAAC,KAAK,GAAE,eAAoB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAYtE;;;;;;;;OAQG;IACG,OAAO,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAKtC;;;;;;;;;;OAUG;IACG,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7C;;;;;;;;;;;OAWG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAShE;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAMlD"}

package/dist/src/team.js

@@ -0,0 +1,161 @@
+/**
+ * `client.team.*` — the caller's account team, self-service.
+ *
+ * Six operations, one HTTP call each: list the roster, invite someone (or mint
+ * an open, shareable invite link), list open invites, revoke one, change a
+ * member's role, remove a member. Nothing here composes two requests or
+ * filters a list client-side — `team.invites()` returns only OPEN invites
+ * because the **server** filters them, not because this module scans the
+ * account's whole invite history and drops the closed ones
+ * (`docs/implementation.md`'s "what a wrapper is" rule, mirrored from
+ * `documents.ts`'s header).
+ *
+ * **Not project-scoped.** Team membership is an account-wide concept, so
+ * (unlike `documents`) this namespace carries no `?project=` anywhere and is
+ * handed the transport only — the same narrow host `connections.ts` and
+ * `vars.ts` use, so a caller cannot even accidentally reach a default project
+ * to send.
+ *
+ * `docs/team.md`'s pinned wire contract (mirrored in this task's `plan.md`
+ * §"Pinned wire contract") is the source these six methods transcribe:
+ *
+ * ```
+ * GET    /me/account/members                      → 200 { members: TeamMember[] }
+ * POST   /me/account/invites   { email?, role? }  → 201 { invite: TeamInviteWithLink }
+ * GET    /me/account/invites                      → 200 { invites: TeamInvite[] }
+ * DELETE /me/account/invites/:id                  → 200 { ok: true }
+ * PATCH  /me/account/members/:userId  { role }    → 200 { member: TeamMember }
+ * DELETE /me/account/members/:userId              → 200 { ok: true }
+ * ```
+ *
+ * This module implements the client half of the server's live
+ * `/me/account/...` routes (`endpoints.json`: `status: "required"` for each).
+ * Calling any of these against a server that has not shipped T1.2.1 yet
+ * answers `404`, which reaches the caller as an ordinary `ApiError`.
+ *
+ * @module
+ */
+import { path } from "./http.js";
+import { unwrap } from "./types.js";
+/**
+ * The `team` namespace on a `W6WClient`.
+ *
+ * @example
+ * ```ts
+ * const members = await client.team.members();
+ * const { redemptionLink } = await client.team.invite({ role: "admin" });
+ * await client.team.setRole(members[0].userId, "admin");
+ * ```
+ */
+export class TeamApi {
+    #host;
+    /**
+     * @param host - The client this namespace issues requests through.
+     */
+    constructor(host) {
+        this.#host = host;
+    }
+    /**
+     * List the caller's account team.
+     *
+     * Member-readable: any active member of the account may call this,
+     * regardless of role — only the write operations below require
+     * `canManageMembers`.
+     *
+     * @returns The team, unwrapped from the `members` envelope.
+     * @throws {ApiError} On any non-2xx.
+     */
+    async members() {
+        const res = await this.#host.request({ method: "GET", path: "/me/account/members" });
+        return unwrap(res, "members");
+    }
+    /**
+     * Invite someone to the account, or mint an open, shareable invite link.
+     *
+     * @param input - `email` and `role`, both optional.
+     * @returns The created invite, including its one-time `token` and `redemptionLink`.
+     * @throws {ApiError} `403 forbidden` without `canManageMembers`.
+     * @throws {ApiError} `400 invalid_role` for `role: "owner"` or an unrecognised role.
+     */
+    async invite(input = {}) {
+        const res = await this.#host.request({
+            method: "POST",
+            path: "/me/account/invites",
+            // Assembled field by field, exactly the two documented fields: an
+            // `undefined` one is dropped by JSON serialisation rather than sent as
+            // an explicit `null`.
+            body: { email: input.email, role: input.role },
+        });
+        return unwrap(res, "invite");
+    }
+    /**
+     * List the account's open (pending, unrevoked, unexpired) invites.
+     *
+     * The filtering happens server-side — this is one `GET`, never a
+     * list-then-filter over the account's whole invite history.
+     *
+     * @returns The open invites, unwrapped from the `invites` envelope.
+     * @throws {ApiError} `403 forbidden` without `canManageMembers`.
+     */
+    async invites() {
+        const res = await this.#host.request({ method: "GET", path: "/me/account/invites" });
+        return unwrap(res, "invites");
+    }
+    /**
+     * Revoke a pending invite before it is redeemed.
+     *
+     * Not idempotent: revoking an invite that is already used or already
+     * revoked is a rejected request, not a silent success.
+     *
+     * @param id - The invite's own id (see: `team.invites()`).
+     * @throws {ApiError} `403 forbidden` without `canManageMembers`.
+     * @throws {ApiError} `404 invite_not_found` for an unknown id.
+     * @throws {ApiError} `409 invite_not_open` when it was already used or revoked.
+     */
+    async revokeInvite(id) {
+        await this.#host.request({
+            method: "DELETE",
+            path: path `/me/account/invites/${id}`,
+        });
+    }
+    /**
+     * Change a team member's role.
+     *
+     * @param userId - The member's `usr_…` id (see: `team.members()`).
+     * @param role - The role to set.
+     * @returns The updated member.
+     * @throws {ApiError} `403 forbidden` without `canManageMembers`.
+     * @throws {ApiError} `403 cannot_change_owner_role` for `role: "owner"` or when
+     * `userId` is the account's current owner — there is no self-service ownership transfer.
+     * @throws {ApiError} `400 invalid_role` for an unrecognised role.
+     * @throws {ApiError} `404 member_not_found` for an unknown `userId`.
+     */
+    async setRole(userId, role) {
+        const res = await this.#host.request({
+            method: "PATCH",
+            path: path `/me/account/members/${userId}`,
+            body: { role },
+        });
+        return unwrap(res, "member");
+    }
+    /**
+     * Remove a member from the account.
+     *
+     * Tombstones the membership server-side rather than deleting it outright
+     * (D-R3), but that is a server implementation detail this method does not
+     * surface — it returns nothing, the same pin as `documents.delete`.
+     *
+     * @param userId - The member's `usr_…` id (see: `team.members()`).
+     * @throws {ApiError} `403 forbidden` without `canManageMembers`.
+     * @throws {ApiError} `403 cannot_remove_owner` when `userId` is the account's owner.
+     * @throws {ApiError} `404 member_not_found` for an unknown `userId`.
+     * @throws {ApiError} `409 last_member` when `userId` is the account's only active member.
+     */
+    async removeMember(userId) {
+        await this.#host.request({
+            method: "DELETE",
+            path: path `/me/account/members/${userId}`,
+        });
+    }
+}
+//# sourceMappingURL=team.js.map

package/dist/src/team.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"team.js","sourceRoot":"","sources":["../../src/team.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAAqB,IAAI,EAAuB,MAAM,WAAW,CAAC;AACzE,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAsFpC;;;;;;;;;GASG;AACH,MAAM,OAAO,OAAO;IACT,KAAK,CAAW;IAEzB;;OAEG;IACH,YAAY,IAAc;QACxB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO;QACX,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,qBAAqB,EAAE,CAAC,CAAC;QAC9F,OAAO,MAAM,CAAe,GAAG,EAAE,SAAS,CAAC,CAAC;IAC9C,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,MAAM,CAAC,QAAyB,EAAE;QACtC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,qBAAqB;YAC3B,kEAAkE;YAClE,uEAAuE;YACvE,sBAAsB;YACtB,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE;SAC/C,CAAC,CAAC;QACH,OAAO,MAAM,CAAqB,GAAG,EAAE,QAAQ,CAAC,CAAC;IACnD,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,OAAO;QACX,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,qBAAqB,EAAE,CAAC,CAAC;QAC9F,OAAO,MAAM,CAAe,GAAG,EAAE,SAAS,CAAC,CAAC;IAC9C,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,YAAY,CAAC,EAAU;QAC3B,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAChC,MAAM,EAAE,QAAQ;YAChB,IAAI,EAAE,IAAI,CAAA,uBAAuB,EAAE,EAAE;SACtC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,OAAO,CAAC,MAAc,EAAE,IAAY;QACxC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAC5C,MAAM,EAAE,OAAO;YACf,IAAI,EAAE,IAAI,CAAA,uBAAuB,MAAM,EAAE;YACzC,IAAI,EAAE,EAAE,IAAI,EAAE;SACf,CAAC,CAAC;QACH,OAAO,MAAM,CAAa,GAAG,EAAE,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,YAAY,CAAC,MAAc;QAC/B,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAU;YAChC,MAAM,EAAE,QAAQ;YAChB,IAAI,EAAE,IAAI,CAAA,uBAAuB,MAAM,EAAE;SAC1C,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/src/types.d.ts

@@ -122,6 +122,16 @@ export interface Me {
  * would be a server change that the wrapper version-bumps with.
  */
 export type ConnectionState = "pending" | "connected" | "needs_refresh" | "broken" | "revoked";
+/** The display metadata of a connection's app, inlined on each {@link ConnectionSummary}. */
+export interface ConnectionAppMeta {
+    displayName: string;
+    /** Light-theme icon, a `data:image/svg+xml;base64,…` URI. */
+    iconSvg?: string;
+    /** Dark-theme icon, a `data:image/svg+xml;base64,…` URI. */
+    iconSvgDark?: string;
+    brandColor?: string;
+    brandColorDark?: string;
+}
 /**
  * A connection, as the list route projects it.
  *
@@ -141,8 +151,10 @@ export interface ConnectionSummary {
     appId: string;
     /** Which of the app's auth methods this connection uses. */
     authKey: string;
-    /** The subject that owns the connection. */
-    owner: string;
+    /** The tenant that owns the connection. */
+    tenant: string;
+    /** The subject (the partner's user id) that owns the connection. */
+    subject: string;
     /** Human-chosen label. */
     displayName: string;
     /** Lifecycle state. */
@@ -157,6 +169,11 @@ export interface ConnectionSummary {
     createdAt: string;
     /** ISO-8601 timestamp. */
     updatedAt: string;
+    /**
+     * The connection's app, inlined so a list needs no second fetch for names and icons.
+     * `null` means the server found no app row; absent means an older server.
+     */
+    app?: ConnectionAppMeta | null;
 }
 /** Lifecycle state of a workflow: an editable draft, a published live one, or archived. */
 export type WorkflowStatus = "draft" | "active" | "archived";
@@ -170,6 +187,8 @@ export type WorkflowStatus = "draft" | "active" | "archived";
 export interface WorkflowSummary {
     /** Server-issued id, `wf_…`. This is the handle a URN addresses. */
     id: string;
+    /** The callable key, or `null` when this workflow has none yet — the normal state for every workflow that predates keys. */
+    key: string | null;
     /** Stable slug, e.g. `"welcome-email"`. */
     name: string;
     /** Human-readable label. */
@@ -185,6 +204,36 @@ export interface WorkflowSummary {
     /** ISO-8601 timestamp. */
     updatedAt: string;
 }
+/**
+ * A Function definition, as the list route projects it.
+ *
+ * `key` is the name the Function is CALLED by — `client.functions.run(key)` —
+ * and `displayName` is the label a human reads; the server falls back to the
+ * key when no display name was set, so `displayName` is never empty and never a
+ * substitute for `key`.
+ *
+ * There is no `status` here, and no lifecycle to have one: a Function is either
+ * runnable or not, which is what {@linkcode FunctionSummary.valid} answers.
+ */
+export interface FunctionSummary {
+    /** Server-issued id, `fn_…`. */
+    id: string;
+    /** The callable name, e.g. `"send-email"`. Kebab-case, never contains `_`. */
+    key: string;
+    /** Human-readable label; falls back to `key` server-side. */
+    displayName: string;
+    /** Free-text description; `""` when unset. */
+    description: string;
+    /** ISO-8601 timestamp. */
+    updatedAt: string;
+    /**
+     * Whether this Function can actually be run — server-computed, from the same
+     * single predicate the invoke path guards with (`db/repos/functions.ts`'s
+     * `isFunctionValid`). A draft with no `impl` is `false`, and running it is
+     * `422 function_incomplete`.
+     */
+    valid: boolean;
+}
 /**
  * Lifecycle state of a run.
  *
@@ -228,14 +277,67 @@ export interface RunResult {
     /** Per-step failures, when the server reports them. */
     stepErrors?: StepError[];
 }
+/**
+ * The invocation FRAME every `RunEnvelope` arm carries — the platform's own
+ * record of the attempt, as opposed to whatever the target returned.
+ *
+ * Added by the server on 2026-08-20 and purely ADDITIVE: no existing field was
+ * renamed, removed or re-typed, so code written against the three-arm shape
+ * keeps compiling and keeps working.
+ *
+ * Every field is OPTIONAL here, and that is deliberate rather than lazy: an
+ * installed SDK talks to whichever server version is deployed, and a required
+ * field would make this type a lie against any server older than the change.
+ * Treat an absent `invocationId` as "this server does not record invocations
+ * yet", never as an error.
+ */
+export interface InvocationFrame {
+    /**
+     * This attempt's id, `inv_…`. Resolves through `GET /invocations/{id}` to the
+     * stored inputs, output, error and timing.
+     *
+     * NOT the same thing as {@linkcode WorkflowRunEnvelope.runId}, and neither
+     * replaces the other: this names the CALL, `runId` names the queued workflow
+     * RUN that a call may have started. On the workflow arm both can be present
+     * and they mean different things.
+     */
+    invocationId?: string;
+    /**
+     * The PLATFORM's verdict on the attempt — `"succeeded"`, `"failed"` or, on
+     * the workflow arm, `"queued"`.
+     *
+     * Not to be confused with any status the target reported inside its own
+     * payload: a SendGrid send whose `output` reads `{statusCode: 202}` is
+     * SendGrid describing its own request, not this platform describing the call.
+     */
+    status?: "succeeded" | "failed" | "queued" | string;
+    /** When the attempt started, ISO-8601. */
+    startedAt?: string;
+    /** When it reached a terminal state, ISO-8601. */
+    finishedAt?: string;
+    /** Wall-clock duration in milliseconds. */
+    durationMs?: number;
+}
 /** `run` resolved a `conn_…` URN and executed an app action. HTTP `200`. */
-export interface ActionRunEnvelope {
+export interface ActionRunEnvelope extends InvocationFrame {
     kind: "action";
-    /** The action's return value. Opaque pass-through. */
+    /**
+     * The action's return value. Opaque pass-through.
+     *
+     * @deprecated Read {@linkcode ActionRunEnvelope.output} instead — it is the
+     * one payload field every arm agrees on. `value` carries the identical value
+     * and is not going away without a major bump, but new code should not reach
+     * for a name that only one arm has.
+     */
     value: unknown;
+    /**
+     * The action's return value, under the name every arm shares. Optional
+     * because a server older than 2026-08-20 sends only `value`.
+     */
+    output?: unknown;
 }
 /** `run` resolved a `fn_…` / `ep_…` URN and executed it. HTTP `200`. */
-export interface FunctionRunEnvelope {
+export interface FunctionRunEnvelope extends InvocationFrame {
     kind: "function";
     /** The function's output. Opaque pass-through. */
     output: unknown;
@@ -246,9 +348,14 @@ export interface FunctionRunEnvelope {
  * `202` is **success**: the run is queued, and `runId` is how the caller follows
  * it. There is no `?wait=` on this operation — use `workflows.run` for that (D4).
  */
-export interface WorkflowRunEnvelope {
+export interface WorkflowRunEnvelope extends InvocationFrame {
     kind: "workflow";
-    /** Server-issued run handle. */
+    /**
+     * Server-issued run handle — the QUEUED RUN, not the call that queued it.
+     * Follow it with `workflows.getRun`. See
+     * {@linkcode InvocationFrame.invocationId} for the other id and why they are
+     * not the same.
+     */
     runId: string;
     /** Where the run has got to; `"queued"` immediately after dispatch. */
     status: RunStatus;
@@ -269,9 +376,13 @@ export type UnknownRunEnvelope = {
 /**
  * What `client.run()` returns: three known arms plus an open one.
  *
- * `value` (action) and `output` (function) are **deliberately different names**
- * for the two synchronous arms and are never normalised into one field — the
- * discrimination is the point (D3).
+ * `value` (action) and `output` (function) were **deliberately different names**
+ * for the two synchronous arms, and the guards below still discriminate on
+ * `kind` rather than on which field is present. Since 2026-08-20 the server
+ * also sends `output` on the action arm, carrying the same value as `value` —
+ * so `output` is now the field name every arm shares and the one new code
+ * should read. `value` is kept, unchanged, for every caller written before
+ * that (D3).
  *
  * **The union is open, and narrowing on `kind` alone does not work.** Because
  * the fourth arm admits any `kind: string`, a bare `env.kind === "workflow"`
@@ -359,4 +470,26 @@ export declare function isTerminalRunStatus(status: RunStatus): boolean;
  * key, or the key is `null`.
  */
 export declare function unwrap<T>(res: HttpResponse<unknown>, key: string): T;
+/**
+ * Mint a client-side id for a definition the caller is creating.
+ *
+ * **Both `POST /workflows` and `POST /functions` REQUIRE an `id` in the body
+ * and never generate one** (`admin/workflows.ts`'s and `admin/functions.ts`'s
+ * `validateDefinition`: "`id` is required."). The id is synthetic and never
+ * user-facing — the display name is what a user sees and edits — so a caller
+ * writing `create({name: "…", steps: […]})` should not have to know that, and
+ * every consumer that does know it has ended up writing the same four lines
+ * (studio's `newWorkflowId`/`newFunctionId`, `WorkflowsPage.tsx:141` and
+ * `FunctionsPage.tsx:49`). This is that function, once.
+ *
+ * `crypto.randomUUID` is present on every runtime this package supports (Node
+ * 19+, Deno, Bun, browsers) but is guarded anyway, byte-for-byte as studio
+ * guards it: the fallback keeps `create` working on an older Node rather than
+ * throwing a `TypeError` from inside the SDK, and the ids only need to be
+ * unique per scope, not unguessable — the server owns ownership, not the id.
+ *
+ * @param prefix - The kind prefix, without its underscore: `"wf"` or `"fn"`.
+ * @returns A new id of the form `wf_…` / `fn_…`.
+ */
+export declare function mintId(prefix: string): string;
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,GAAG;IAClB,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB;IACnB,MAAM,EAAE,SAAS,CAAC;IAClB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,mFAAmF;AACnF,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAE/D;;;;;;;GAOG;AACH,MAAM,WAAW,GAAG;IAClB,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,IAAI,EAAE,OAAO,CAAC;IACd,sCAAsC;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,EAAE;IACjB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,WAAW,GAAG,eAAe,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE/F;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,KAAK,EAAE,eAAe,CAAC;IACvB,qFAAqF;IACrF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,gFAAgF;IAChF,UAAU,EAAE,OAAO,GAAG,IAAI,CAAC;IAC3B,sDAAsD;IACtD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,2FAA2F;AAC3F,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,MAAM,EAAE,cAAc,CAAC;IACvB,wBAAwB;IACxB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEnF,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACxB,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,MAAM,EAAE,SAAS,CAAC;IAClB,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4FAA4F;IAC5F,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,uDAAuD;IACvD,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;CAC1B;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,QAAQ,CAAC;IACf,sDAAsD;IACtD,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,UAAU,CAAC;IACjB,kDAAkD;IAClD,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,UAAU,CAAC;IACjB,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,MAAM,EAAE,SAAS,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,WAAW,GACnB,iBAAiB,GACjB,mBAAmB,GACnB,mBAAmB,GACnB,kBAAkB,CAAC;AAEvB;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,GAAG,IAAI,iBAAiB,CAEtE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,WAAW,GAAG,GAAG,IAAI,mBAAmB,CAE1E;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,WAAW,GAAG,GAAG,IAAI,mBAAmB,CAE1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAE9D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAcpE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/src/types.js

@@ -106,4 +106,31 @@ export function unwrap(res, key) {
     }
     throw new ApiError(res.status, "bad_response", `Server returned a ${res.status} with no "${key}" in the response body.`, body);
 }
+/**
+ * Mint a client-side id for a definition the caller is creating.
+ *
+ * **Both `POST /workflows` and `POST /functions` REQUIRE an `id` in the body
+ * and never generate one** (`admin/workflows.ts`'s and `admin/functions.ts`'s
+ * `validateDefinition`: "`id` is required."). The id is synthetic and never
+ * user-facing — the display name is what a user sees and edits — so a caller
+ * writing `create({name: "…", steps: […]})` should not have to know that, and
+ * every consumer that does know it has ended up writing the same four lines
+ * (studio's `newWorkflowId`/`newFunctionId`, `WorkflowsPage.tsx:141` and
+ * `FunctionsPage.tsx:49`). This is that function, once.
+ *
+ * `crypto.randomUUID` is present on every runtime this package supports (Node
+ * 19+, Deno, Bun, browsers) but is guarded anyway, byte-for-byte as studio
+ * guards it: the fallback keeps `create` working on an older Node rather than
+ * throwing a `TypeError` from inside the SDK, and the ids only need to be
+ * unique per scope, not unguessable — the server owns ownership, not the id.
+ *
+ * @param prefix - The kind prefix, without its underscore: `"wf"` or `"fn"`.
+ * @returns A new id of the form `wf_…` / `fn_…`.
+ */
+export function mintId(prefix) {
+    const uuid = typeof crypto !== "undefined" && "randomUUID" in crypto
+        ? crypto.randomUUID()
+        : Math.floor(Math.random() * 1e16).toString(36);
+    return `${prefix}_${uuid}`;
+}
 //# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAqSvC;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,GAAgB;IAC1C,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC;AAC/B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,GAAgB;IAC5C,OAAO,GAAG,CAAC,IAAI,KAAK,UAAU,CAAC;AACjC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,GAAgB;IAC5C,OAAO,GAAG,CAAC,IAAI,KAAK,UAAU,CAAC;AACjC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAiB;IACnD,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,UAAU,CAAC;AAChF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,MAAM,CAAI,GAA0B,EAAE,GAAW;IAC/D,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAI,IAAgC,CAAC,GAAG,CAAC,CAAC;QACrD,2EAA2E;QAC3E,6DAA6D;QAC7D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,KAAU,CAAC;IAC/D,CAAC;IACD,MAAM,IAAI,QAAQ,CAChB,GAAG,CAAC,MAAM,EACV,cAAc,EACd,qBAAqB,GAAG,CAAC,MAAM,aAAa,GAAG,yBAAyB,EACxE,IAAI,CACL,CAAC;AACJ,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAuZvC;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,GAAgB;IAC1C,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC;AAC/B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,GAAgB;IAC5C,OAAO,GAAG,CAAC,IAAI,KAAK,UAAU,CAAC;AACjC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,GAAgB;IAC5C,OAAO,GAAG,CAAC,IAAI,KAAK,UAAU,CAAC;AACjC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAiB;IACnD,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,UAAU,CAAC;AAChF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,MAAM,CAAI,GAA0B,EAAE,GAAW;IAC/D,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAI,IAAgC,CAAC,GAAG,CAAC,CAAC;QACrD,2EAA2E;QAC3E,6DAA6D;QAC7D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,KAAU,CAAC;IAC/D,CAAC;IACD,MAAM,IAAI,QAAQ,CAChB,GAAG,CAAC,MAAM,EACV,cAAc,EACd,qBAAqB,GAAG,CAAC,MAAM,aAAa,GAAG,yBAAyB,EACxE,IAAI,CACL,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,MAAM,CAAC,MAAc;IACnC,MAAM,IAAI,GAAG,OAAO,MAAM,KAAK,WAAW,IAAI,YAAY,IAAI,MAAM;QAClE,CAAC,CAAC,MAAM,CAAC,UAAU,EAAE;QACrB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAClD,OAAO,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC;AAC7B,CAAC"}