@w6w/sdk 0.5.0 → 0.9.8

package/dist/src/server/mod.d.ts

@@ -0,0 +1,100 @@
+/**
+ * `@w6w/sdk/server` — a backend-only token exchange, for a partner embedding
+ * w6w inside its own product.
+ *
+ * A **separate** entry point from the package root (`@w6w/sdk`) and from
+ * `@w6w/sdk/console`: deliberately excluded from `endpoints.json`'s
+ * `operations[]` and from the root barrel (`../../mod.ts`), documented
+ * instead in `docs/sdk-surface.md` (R-5). Nothing here is reachable from
+ * either of those entry points, and this module imports nothing from
+ * `../console/mod.ts`.
+ *
+ * **Egress / trust boundary.** {@linkcode exchangeToken} sends a tenant's
+ * client secret over the wire, once per call, and only as an HTTP Basic
+ * credential — never in the body, the URL or a query string. It is built on
+ * the package's existing transport (`../http.ts`'s `request`, `../config.ts`'s
+ * `resolveConfig`) with `requireAuth: false` — the same escape hatch
+ * `console.auth.login` uses for a route that authenticates itself rather than
+ * via a bearer — so this is a thin caller of the one HTTP path this package
+ * has, never a second one.
+ *
+ * This function is meant to run on a partner's OWN backend, never in a
+ * browser: the client secret it takes must never reach client-side code. See
+ * `README.md`'s "Embedding for enterprise tenants" section for the worked
+ * route this is designed to sit behind.
+ *
+ * @module
+ */
+import { type FetchLike } from "../config.ts";
+/** Options for {@linkcode exchangeToken}. */
+export interface ExchangeTokenOptions {
+    /**
+     * The w6w server's origin, e.g. `https://api.example.com`. Same rules as
+     * {@linkcode W6WClientOptions.baseUrl} — an absolute `http(s)` URL with a
+     * host.
+     */
+    baseUrl: string;
+    /** The tenant's client id. Must not contain `:` or a non-latin-1 character. */
+    clientId: string;
+    /** The tenant's client secret. Must be latin-1 encodable. */
+    clientSecret: string;
+    /**
+     * The partner's end-user id. Minted into the returned token's `sub` claim
+     * verbatim — this function does not validate or canonicalise it.
+     */
+    subject: string;
+    /**
+     * Optional account claim. **Trusted verbatim**: the server mints whatever
+     * `account` it is given into the token, so the caller — this function's own
+     * caller, on the partner's backend — is responsible for deriving it from
+     * ITS OWN membership data, never from an unauthenticated client input. See
+     * `README.md`'s embedding example.
+     */
+    account?: string;
+    /** Transport override. Defaults to `globalThis.fetch`, bound. */
+    fetch?: FetchLike;
+}
+/** The shape `POST /auth/exchange` answers with on success. */
+export interface ExchangeTokenResult {
+    /** The minted, short-lived bearer token. */
+    token: string;
+    /** The identity the token carries. */
+    user: {
+        /** The `subject` this call passed, echoed back. */
+        subject: string;
+        /** The tenant the client credentials resolved to. */
+        tenant: string;
+        /** Always `"user"` for a token minted this way. */
+        role: string;
+        /** The resolved account claim — the `account` passed, or the tenant id when omitted. */
+        account: string;
+    };
+    /** Token lifetime, in seconds. */
+    expiresIn: number;
+}
+/**
+ * Exchange a tenant's client credentials for a short-lived, per-user w6w
+ * token: `POST /auth/exchange`.
+ *
+ * Credentials travel ONLY as `Authorization: Basic base64(clientId:clientSecret)`
+ * — never in the body, the URL or a query string. The body sent is exactly
+ * `{ subject }`, or `{ subject, account }` when `account` is given; omitting
+ * `account` never puts the key in the body at all (not even as `null` or
+ * `undefined`).
+ *
+ * Every validation failure below is a local {@linkcode ConfigError}, raised
+ * **before any network call**, and none of them ever echo `clientSecret`.
+ *
+ * @param options - See {@linkcode ExchangeTokenOptions}.
+ * @returns The minted token and the identity it carries.
+ * @throws {ConfigError} Blank `clientId`/`clientSecret`/`subject`; a `clientId`
+ *   containing `:`; a `clientId`/`clientSecret` outside latin-1; no base URL;
+ *   no runtime `fetch`.
+ * @throws {ApiError} `invalid_client` (401, unknown/disabled credentials),
+ *   `invalid_body` / `invalid_subject` / `invalid_account` (400), or any of
+ *   the transport's own failure modes (`../http.ts`). Never retried: this
+ *   call always passes `requireAuth: false`, which `request()` never grants a
+ *   recovery attempt.
+ */
+export declare function exchangeToken(options: ExchangeTokenOptions): Promise<ExchangeTokenResult>;
+//# sourceMappingURL=mod.d.ts.map

package/dist/src/server/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../src/server/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAiB,MAAM,cAAc,CAAC;AAI7D,6CAA6C;AAC7C,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,IAAI,EAAE;QACJ,mDAAmD;QACnD,OAAO,EAAE,MAAM,CAAC;QAChB,qDAAqD;QACrD,MAAM,EAAE,MAAM,CAAC;QACf,mDAAmD;QACnD,IAAI,EAAE,MAAM,CAAC;QACb,wFAAwF;QACxF,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;CACnB;AAsDD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAwB9B"}

package/dist/src/server/mod.js

@@ -0,0 +1,121 @@
+/**
+ * `@w6w/sdk/server` — a backend-only token exchange, for a partner embedding
+ * w6w inside its own product.
+ *
+ * A **separate** entry point from the package root (`@w6w/sdk`) and from
+ * `@w6w/sdk/console`: deliberately excluded from `endpoints.json`'s
+ * `operations[]` and from the root barrel (`../../mod.ts`), documented
+ * instead in `docs/sdk-surface.md` (R-5). Nothing here is reachable from
+ * either of those entry points, and this module imports nothing from
+ * `../console/mod.ts`.
+ *
+ * **Egress / trust boundary.** {@linkcode exchangeToken} sends a tenant's
+ * client secret over the wire, once per call, and only as an HTTP Basic
+ * credential — never in the body, the URL or a query string. It is built on
+ * the package's existing transport (`../http.ts`'s `request`, `../config.ts`'s
+ * `resolveConfig`) with `requireAuth: false` — the same escape hatch
+ * `console.auth.login` uses for a route that authenticates itself rather than
+ * via a bearer — so this is a thin caller of the one HTTP path this package
+ * has, never a second one.
+ *
+ * This function is meant to run on a partner's OWN backend, never in a
+ * browser: the client secret it takes must never reach client-side code. See
+ * `README.md`'s "Embedding for enterprise tenants" section for the worked
+ * route this is designed to sit behind.
+ *
+ * @module
+ */
+import { resolveConfig } from "../config.js";
+import { ConfigError } from "../errors.js";
+import { request } from "../http.js";
+/** Non-blank after trimming. */
+function required(value, field) {
+    if (value.trim().length === 0) {
+        throw new ConfigError(`exchangeToken: \`${field}\` must not be blank.`);
+    }
+}
+/**
+ * Base64-encode `clientId:clientSecret` the way the server decodes it:
+ * latin-1 (`atob`'s own alphabet), via `btoa`.
+ *
+ * `btoa` itself rejects any character outside latin-1 (U+0000–U+00FF),
+ * raising for us — this is NOT re-implemented with a UTF-8 path, because that
+ * would silently encode a secret the server's `atob` could never decode back
+ * to the same bytes.
+ *
+ * @throws {ConfigError} When `clientId` contains `:` (indistinguishable from
+ *   the Basic separator on decode) or either value is not latin-1.
+ */
+function basicAuthHeader(clientId, clientSecret) {
+    if (clientId.includes(":")) {
+        throw new ConfigError('exchangeToken: `clientId` must not contain ":" — the server splits a ' +
+            "decoded Basic credential on the FIRST colon, so a colon in `clientId` " +
+            "would be read as part of the secret instead.");
+    }
+    try {
+        return btoa(`${clientId}:${clientSecret}`);
+    }
+    catch {
+        throw new ConfigError("exchangeToken: `clientId`/`clientSecret` must be representable as " +
+            "latin-1 (ISO-8859-1) — the server decodes the Basic header with " +
+            "`atob`, which cannot represent a wider character set.");
+    }
+}
+function resolveFetch(fetchOption) {
+    if (fetchOption)
+        return fetchOption;
+    const global = globalThis.fetch;
+    if (typeof global !== "function") {
+        throw new ConfigError("This runtime has no global fetch. Pass an implementation " +
+            "(exchangeToken({ ..., fetch })) or run on Node 18+, Deno or Bun.");
+    }
+    // Bound, so it keeps working when called as a bare function reference —
+    // exactly W6WClient's own default (../client.ts).
+    return global.bind(globalThis);
+}
+/**
+ * Exchange a tenant's client credentials for a short-lived, per-user w6w
+ * token: `POST /auth/exchange`.
+ *
+ * Credentials travel ONLY as `Authorization: Basic base64(clientId:clientSecret)`
+ * — never in the body, the URL or a query string. The body sent is exactly
+ * `{ subject }`, or `{ subject, account }` when `account` is given; omitting
+ * `account` never puts the key in the body at all (not even as `null` or
+ * `undefined`).
+ *
+ * Every validation failure below is a local {@linkcode ConfigError}, raised
+ * **before any network call**, and none of them ever echo `clientSecret`.
+ *
+ * @param options - See {@linkcode ExchangeTokenOptions}.
+ * @returns The minted token and the identity it carries.
+ * @throws {ConfigError} Blank `clientId`/`clientSecret`/`subject`; a `clientId`
+ *   containing `:`; a `clientId`/`clientSecret` outside latin-1; no base URL;
+ *   no runtime `fetch`.
+ * @throws {ApiError} `invalid_client` (401, unknown/disabled credentials),
+ *   `invalid_body` / `invalid_subject` / `invalid_account` (400), or any of
+ *   the transport's own failure modes (`../http.ts`). Never retried: this
+ *   call always passes `requireAuth: false`, which `request()` never grants a
+ *   recovery attempt.
+ */
+export async function exchangeToken(options) {
+    const { baseUrl, clientId, clientSecret, subject, account } = options;
+    required(clientId, "clientId");
+    required(clientSecret, "clientSecret");
+    required(subject, "subject");
+    const basic = basicAuthHeader(clientId, clientSecret);
+    const config = resolveConfig({ baseUrl });
+    const fetchImpl = resolveFetch(options.fetch);
+    const body = { subject };
+    if (account !== undefined) {
+        body.account = account;
+    }
+    const res = await request(config, fetchImpl, {
+        method: "POST",
+        path: "/auth/exchange",
+        body,
+        headers: { authorization: `Basic ${basic}` },
+        requireAuth: false,
+    });
+    return res.body;
+}
+//# sourceMappingURL=mod.js.map

package/dist/src/server/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../../../src/server/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAkB,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAkDrC,gCAAgC;AAChC,SAAS,QAAQ,CAAC,KAAa,EAAE,KAAa;IAC5C,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,WAAW,CAAC,oBAAoB,KAAK,uBAAuB,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,eAAe,CAAC,QAAgB,EAAE,YAAoB;IAC7D,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,WAAW,CACnB,uEAAuE;YACrE,wEAAwE;YACxE,8CAA8C,CACjD,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,GAAG,QAAQ,IAAI,YAAY,EAAE,CAAC,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,WAAW,CACnB,oEAAoE;YAClE,kEAAkE;YAClE,uDAAuD,CAC1D,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,WAAkC;IACtD,IAAI,WAAW;QAAE,OAAO,WAAW,CAAC;IACpC,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC;IAChC,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;QACjC,MAAM,IAAI,WAAW,CACnB,2DAA2D;YACzD,kEAAkE,CACrE,CAAC;IACJ,CAAC;IACD,wEAAwE;IACxE,kDAAkD;IAClD,OAAO,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAA6B;IAE7B,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAEtE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC7B,MAAM,KAAK,GAAG,eAAe,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IAEtD,MAAM,MAAM,GAAG,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IAC1C,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAE9C,MAAM,IAAI,GAA0C,EAAE,OAAO,EAAE,CAAC;IAChE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,OAAO,CAAsB,MAAM,EAAE,SAAS,EAAE;QAChE,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,gBAAgB;QACtB,IAAI;QACJ,OAAO,EAAE,EAAE,aAAa,EAAE,SAAS,KAAK,EAAE,EAAE;QAC5C,WAAW,EAAE,KAAK;KACnB,CAAC,CAAC;IACH,OAAO,GAAG,CAAC,IAAI,CAAC;AAClB,CAAC"}

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"}