@meetreeve/module-team 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# @meetreeve/module-team
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Reeve.Team module (DEV-9998, C2 of epic DEV-9983). Two halves:
+
+* **`.` / `./client`**: a framework-agnostic, server-safe typed client,
+  `createTeamClient({ fetch })`, over the org-members routes. No React, no
+  Next.js.
+* **`./config`**: `TeamMembersPanel`, the operator surface: members with a
+  role picker and remove, the invite dialog, pending invitations with
+  revoke/resend, and the seat count.
+
+Versioned in lockstep with the Python `reeve-module-team` package. Both ship
+the same MAJOR.MINOR.PATCH.
+
+| Method | Route |
+| --- | --- |
+| `listMembers(orgId)` | `GET /api/org/members` |
+| `updateMemberRole(orgId, memberId, role)` | `PUT /api/org/members/{id}/role` |
+| `removeMember(orgId, memberId)` | `DELETE /api/org/members/{id}` |
+| `inviteMember(orgId, email, role, spaces?)` | `POST /api/org/invite` (`spaces` sent whenever passed, `[]` included) |
+| `listInvitations(orgId)` | `GET /api/org/invitations` |
+| `revokeInvitation(orgId, invitationId)` | `DELETE /api/org/invitations/{id}` |
+| `resendInvitation(orgId, invitationId)` | `POST /api/org/invitations/{id}/resend` |
+
+## The transport is the host's
+
+`createTeamClient` takes a JSON fetcher, `(path, init) => Promise<body>`,
+that resolves the parsed body and rejects on a non-2xx. reeve-frontend's
+`productFetch` already has that shape, and it owns auth, the 401 refresh and
+timeouts. A spawned tenant passes its own.
+
+## The org is never ambient (DEV-8592)
+
+Every client method takes the org it acts on and sends it as
+`X-Reeve-Org-Id`. `TeamMembersPanel` requires `orgId` and keys its stateful
+body on it. Switching orgs remounts the panel, so the previous org's
+members, open dialogs and notices are dropped at once. A response for the
+previous org that lands late is discarded.
+
+```tsx
+import { createTeamClient } from "@meetreeve/module-team/client";
+import { TeamMembersPanel } from "@meetreeve/module-team/config";
+
+const client = createTeamClient({ fetch: (path, init) => productFetch(path, init) });
+
+<TeamMembersPanel
+  client={client}
+  orgId={activeOrgId}
+  inviteRoles={["admin", "member"]}         // default: admin, member, viewer
+  currentUserEmail={user?.email}
+  renderMemberActions={(m) => <BudgetButton member={m} />}  // host-only extras
+  onNotice={(n) => toast[n.kind](n.message)}                // optional; also shown inline
+/>;
+```
+
+Spaces (0.2.0, DEV-15988; 0.3.0, DEV-16808): pass
+`loadSpaceOptions={() => Promise<SpaceOption[]>}` and the invite dialog lists
+every space, the default one included (nobody joins a space automatically).
+With 2+ spaces at least one must be checked; with one there is no picker, the
+dialog says "They'll get access to <Space>" and sends `spaces: []`. The invite
+is held until the options load. `can_manage: false` spaces are shown
+disabled. A server refusal (e.g. 422 `spaces_required`) shows inside the
+dialog. `renderInvitationActions={(inv, { reload }) => ...}` is the
+pending-invite twin of `renderMemberActions`; call `reload` after a change
+the row shows (an invitation's `spaces` are listed on its row).
+
+`inviteRoles` scopes both the invite dialog and the per-member role picker.
+Owners get no role picker and no remove control. The role picker also offers
+only the changes the backend accepts from the signed-in user, whose role is
+read from the roster row matching `currentUserEmail`: an owner may move a
+member to any offered role, an admin only to roles below admin and only on
+rows ranked below admin, and anyone else gets plain role labels. Without a
+matching `currentUserEmail` every role is a plain label. A refused change
+shows the backend's `detail`. The backend still enforces every rule.
+
+The panel has no runtime dependencies beyond `react`/`react-dom`. It is
+styled with Tailwind utility classes over shadcn tokens (`bg-card`,
+`text-muted-foreground`, `border-border`, ...), so the host's Tailwind must
+scan this package.
+
+## Development
+
+```bash
+npm ci && npm test && npm run typecheck && npm run build && npm run check:esm
+```
+
+reeve-frontend aliases `@meetreeve/module-team/{config,client}` to this
+package's source until the first publish. Running `npm ci` here installs a
+second React under `packages/module-team/node_modules`. Move that directory
+aside before you run the root vitest suite.

package/dist/client/index.d.mts

@@ -0,0 +1,141 @@
+/**
+ * Roles the org-members router knows. `billing_manager` is a legacy alias
+ * the backend still accepts; no surface offers it from the invite dialog.
+ * Rows may still carry a role this union doesn't name, so row fields are
+ * typed `string` and the panel renders unknown roles verbatim.
+ */
+type TeamRole = "owner" | "admin" | "billing_manager" | "member" | "viewer";
+/** A role the invite dialog and the role picker can hand out (never `owner`). */
+type AssignableRole = Exclude<TeamRole, "owner" | "billing_manager">;
+/** One live member of the org (`OrganizationMember` row). `GET /api/org/members`. */
+interface TeamMember {
+    /** OrganizationMember.id — the id every member route takes. */
+    id: string;
+    user_id: string;
+    email: string | null;
+    role: string;
+    is_default: boolean;
+    /** ISO-8601. */
+    created_at: string;
+}
+/** One invitation record. `GET /api/org/invitations`. */
+interface Invitation {
+    id: string;
+    email: string;
+    role: string;
+    invited_by_email: string | null;
+    /** pending | accepted | expired | revoked */
+    status: string;
+    /** ISO-8601. */
+    created_at: string;
+    /** ISO-8601. */
+    expires_at: string;
+    accepted_at: string | null;
+    /**
+     * Spaces the invitee joins on accept (DEV-15988 / reeve-services DEV-15559).
+     * The backend always sends it; optional so a backend that predates it
+     * still type-checks as "no pre-set spaces".
+     */
+    spaces?: InvitationSpace[];
+}
+/** A space role. */
+type SpaceRole = "member" | "admin";
+/** One pre-set space on an invitation (`GET /api/org/invitations` item). */
+interface InvitationSpace {
+    id: string;
+    name: string;
+    role: SpaceRole;
+}
+/** One space an invite (or a pending invitation) should land the invitee in. */
+interface InviteSpace {
+    space_id: string;
+    role: SpaceRole;
+}
+/**
+ * One of the org's spaces, as the invite dialog's Spaces picker lists it
+ * (reeve-frontend maps `GET /api/org/rbac/spaces` onto this). Every space is
+ * offered, the default one included: nobody joins a space automatically
+ * (DEV-16808). `can_manage: false` rows are shown disabled.
+ */
+interface SpaceOption {
+    id: string;
+    name: string;
+    kind?: string;
+    is_default: boolean;
+    can_manage: boolean;
+}
+/** `POST /api/org/invite`. */
+interface InviteMemberResponse {
+    message: string;
+    email: string;
+    role: string;
+    invitation_id?: string;
+}
+/**
+ * The data-access boundary the panel is built against. Every method takes
+ * the org it acts on: there is no ambient "current org" anywhere in this
+ * package, so a request can never be issued for an org other than the one
+ * the caller named (DEV-8592). `createTeamClient` is the reference
+ * implementation; a host may supply its own.
+ */
+interface TeamClient {
+    listMembers(orgId: string): Promise<TeamMember[]>;
+    updateMemberRole(orgId: string, memberId: string, role: string): Promise<void>;
+    removeMember(orgId: string, memberId: string): Promise<void>;
+    /**
+     * `spaces` goes in the body whenever it is passed, `[]` included (a
+     * one-space org sends `[]`, DEV-16808); omitted keeps the pre-DEV-15988
+     * request.
+     */
+    inviteMember(orgId: string, email: string, role: string, spaces?: InviteSpace[]): Promise<InviteMemberResponse>;
+    listInvitations(orgId: string): Promise<Invitation[]>;
+    revokeInvitation(orgId: string, invitationId: string): Promise<void>;
+    resendInvitation(orgId: string, invitationId: string): Promise<void>;
+}
+
+/**
+ * Framework-agnostic Reeve.Team client (DEV-9998, C2 of epic DEV-9983).
+ *
+ * The server-safe half: no React, no Next.js. The only import is type-only,
+ * erased at build time.
+ *
+ * Contract: reeve-services' org-members router, ported route-for-route from
+ * reeve-frontend's `src/lib/api/team.ts`:
+ *
+ *   GET    /api/org/members                      -> TeamMember[]
+ *   PUT    /api/org/members/{id}/role   {role}   -> 2xx
+ *   DELETE /api/org/members/{id}                 -> 2xx
+ *   POST   /api/org/invite        {email, role, spaces?}  -> InviteMemberResponse
+ *   GET    /api/org/invitations                  -> Invitation[]
+ *   DELETE /api/org/invitations/{id}             -> 2xx
+ *   POST   /api/org/invitations/{id}/resend      -> 2xx (resets the 7-day expiry)
+ *
+ * Transport is the HOST's: `createTeamClient({ fetch })` takes a JSON
+ * fetcher (reeve-frontend passes `productFetch`, which owns auth, 401
+ * refresh and timeouts). The org is never ambient. Every method takes the
+ * org it acts on and stamps it as `X-Reeve-Org-Id`, the header the backend's
+ * tenant resolver reads, so a request is keyed on the org its caller named
+ * rather than on whatever org a global pin held when it went out (DEV-8592).
+ */
+
+/** The request header the backend tenant resolver reads the org assertion from. */
+declare const ORG_HEADER = "X-Reeve-Org-Id";
+/** What the client hands the host fetcher. `path` is relative to the API origin. */
+type TeamRequestInit = {
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    headers: Record<string, string>;
+    /** JSON-encoded, present only on requests that carry a body. */
+    body?: string;
+};
+/**
+ * A host-supplied JSON fetcher: resolve with the parsed response body (any
+ * value for an empty 2xx), reject on a non-2xx. reeve-frontend's
+ * `productFetch` has exactly this shape.
+ */
+type TeamFetch = (path: string, init: TeamRequestInit) => Promise<unknown>;
+type TeamClientOptions = {
+    fetch: TeamFetch;
+};
+declare function createTeamClient({ fetch }: TeamClientOptions): TeamClient;
+
+export { type AssignableRole, type Invitation, type InvitationSpace, type InviteMemberResponse, type InviteSpace, ORG_HEADER, type SpaceOption, type SpaceRole, type TeamClient, type TeamClientOptions, type TeamFetch, type TeamMember, type TeamRequestInit, type TeamRole, createTeamClient };

package/dist/client/index.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Roles the org-members router knows. `billing_manager` is a legacy alias
+ * the backend still accepts; no surface offers it from the invite dialog.
+ * Rows may still carry a role this union doesn't name, so row fields are
+ * typed `string` and the panel renders unknown roles verbatim.
+ */
+type TeamRole = "owner" | "admin" | "billing_manager" | "member" | "viewer";
+/** A role the invite dialog and the role picker can hand out (never `owner`). */
+type AssignableRole = Exclude<TeamRole, "owner" | "billing_manager">;
+/** One live member of the org (`OrganizationMember` row). `GET /api/org/members`. */
+interface TeamMember {
+    /** OrganizationMember.id — the id every member route takes. */
+    id: string;
+    user_id: string;
+    email: string | null;
+    role: string;
+    is_default: boolean;
+    /** ISO-8601. */
+    created_at: string;
+}
+/** One invitation record. `GET /api/org/invitations`. */
+interface Invitation {
+    id: string;
+    email: string;
+    role: string;
+    invited_by_email: string | null;
+    /** pending | accepted | expired | revoked */
+    status: string;
+    /** ISO-8601. */
+    created_at: string;
+    /** ISO-8601. */
+    expires_at: string;
+    accepted_at: string | null;
+    /**
+     * Spaces the invitee joins on accept (DEV-15988 / reeve-services DEV-15559).
+     * The backend always sends it; optional so a backend that predates it
+     * still type-checks as "no pre-set spaces".
+     */
+    spaces?: InvitationSpace[];
+}
+/** A space role. */
+type SpaceRole = "member" | "admin";
+/** One pre-set space on an invitation (`GET /api/org/invitations` item). */
+interface InvitationSpace {
+    id: string;
+    name: string;
+    role: SpaceRole;
+}
+/** One space an invite (or a pending invitation) should land the invitee in. */
+interface InviteSpace {
+    space_id: string;
+    role: SpaceRole;
+}
+/**
+ * One of the org's spaces, as the invite dialog's Spaces picker lists it
+ * (reeve-frontend maps `GET /api/org/rbac/spaces` onto this). Every space is
+ * offered, the default one included: nobody joins a space automatically
+ * (DEV-16808). `can_manage: false` rows are shown disabled.
+ */
+interface SpaceOption {
+    id: string;
+    name: string;
+    kind?: string;
+    is_default: boolean;
+    can_manage: boolean;
+}
+/** `POST /api/org/invite`. */
+interface InviteMemberResponse {
+    message: string;
+    email: string;
+    role: string;
+    invitation_id?: string;
+}
+/**
+ * The data-access boundary the panel is built against. Every method takes
+ * the org it acts on: there is no ambient "current org" anywhere in this
+ * package, so a request can never be issued for an org other than the one
+ * the caller named (DEV-8592). `createTeamClient` is the reference
+ * implementation; a host may supply its own.
+ */
+interface TeamClient {
+    listMembers(orgId: string): Promise<TeamMember[]>;
+    updateMemberRole(orgId: string, memberId: string, role: string): Promise<void>;
+    removeMember(orgId: string, memberId: string): Promise<void>;
+    /**
+     * `spaces` goes in the body whenever it is passed, `[]` included (a
+     * one-space org sends `[]`, DEV-16808); omitted keeps the pre-DEV-15988
+     * request.
+     */
+    inviteMember(orgId: string, email: string, role: string, spaces?: InviteSpace[]): Promise<InviteMemberResponse>;
+    listInvitations(orgId: string): Promise<Invitation[]>;
+    revokeInvitation(orgId: string, invitationId: string): Promise<void>;
+    resendInvitation(orgId: string, invitationId: string): Promise<void>;
+}
+
+/**
+ * Framework-agnostic Reeve.Team client (DEV-9998, C2 of epic DEV-9983).
+ *
+ * The server-safe half: no React, no Next.js. The only import is type-only,
+ * erased at build time.
+ *
+ * Contract: reeve-services' org-members router, ported route-for-route from
+ * reeve-frontend's `src/lib/api/team.ts`:
+ *
+ *   GET    /api/org/members                      -> TeamMember[]
+ *   PUT    /api/org/members/{id}/role   {role}   -> 2xx
+ *   DELETE /api/org/members/{id}                 -> 2xx
+ *   POST   /api/org/invite        {email, role, spaces?}  -> InviteMemberResponse
+ *   GET    /api/org/invitations                  -> Invitation[]
+ *   DELETE /api/org/invitations/{id}             -> 2xx
+ *   POST   /api/org/invitations/{id}/resend      -> 2xx (resets the 7-day expiry)
+ *
+ * Transport is the HOST's: `createTeamClient({ fetch })` takes a JSON
+ * fetcher (reeve-frontend passes `productFetch`, which owns auth, 401
+ * refresh and timeouts). The org is never ambient. Every method takes the
+ * org it acts on and stamps it as `X-Reeve-Org-Id`, the header the backend's
+ * tenant resolver reads, so a request is keyed on the org its caller named
+ * rather than on whatever org a global pin held when it went out (DEV-8592).
+ */
+
+/** The request header the backend tenant resolver reads the org assertion from. */
+declare const ORG_HEADER = "X-Reeve-Org-Id";
+/** What the client hands the host fetcher. `path` is relative to the API origin. */
+type TeamRequestInit = {
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    headers: Record<string, string>;
+    /** JSON-encoded, present only on requests that carry a body. */
+    body?: string;
+};
+/**
+ * A host-supplied JSON fetcher: resolve with the parsed response body (any
+ * value for an empty 2xx), reject on a non-2xx. reeve-frontend's
+ * `productFetch` has exactly this shape.
+ */
+type TeamFetch = (path: string, init: TeamRequestInit) => Promise<unknown>;
+type TeamClientOptions = {
+    fetch: TeamFetch;
+};
+declare function createTeamClient({ fetch }: TeamClientOptions): TeamClient;
+
+export { type AssignableRole, type Invitation, type InvitationSpace, type InviteMemberResponse, type InviteSpace, ORG_HEADER, type SpaceOption, type SpaceRole, type TeamClient, type TeamClientOptions, type TeamFetch, type TeamMember, type TeamRequestInit, type TeamRole, createTeamClient };

package/dist/client/index.js

@@ -0,0 +1,100 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client.ts
+var client_exports = {};
+__export(client_exports, {
+  ORG_HEADER: () => ORG_HEADER,
+  createTeamClient: () => createTeamClient
+});
+module.exports = __toCommonJS(client_exports);
+var ORG_HEADER = "X-Reeve-Org-Id";
+var ORG_ID_SHAPE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+function orgHeaders(orgId) {
+  if (typeof orgId !== "string" || !ORG_ID_SHAPE.test(orgId)) {
+    throw new Error(`orgId must be a plausible org id, got ${JSON.stringify(orgId)}`);
+  }
+  return { [ORG_HEADER]: orgId };
+}
+function segment(value, name) {
+  if (typeof value !== "string" || value === "") {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+  return encodeURIComponent(value);
+}
+function hasStringId(row) {
+  return typeof row === "object" && row !== null && typeof row.id === "string" && row.id !== "";
+}
+function rows(data, what) {
+  if (!Array.isArray(data) || !data.every(hasStringId)) {
+    throw new Error(`team: malformed ${what} response`);
+  }
+  return data;
+}
+function createTeamClient({ fetch }) {
+  if (typeof fetch !== "function") {
+    throw new Error("createTeamClient: `fetch` must be a function");
+  }
+  const send = (orgId, method, path, body) => {
+    const headers = orgHeaders(orgId);
+    const init = { method, headers };
+    if (body !== void 0) {
+      headers["Content-Type"] = "application/json";
+      init.body = JSON.stringify(body);
+    }
+    return fetch(path, init);
+  };
+  return {
+    listMembers: (orgId) => send(orgId, "GET", "/api/org/members").then((d) => rows(d, "members")),
+    updateMemberRole: (orgId, memberId, role) => {
+      segment(role, "role");
+      return send(orgId, "PUT", `/api/org/members/${segment(memberId, "memberId")}/role`, {
+        role
+      }).then(() => void 0);
+    },
+    removeMember: (orgId, memberId) => send(orgId, "DELETE", `/api/org/members/${segment(memberId, "memberId")}`).then(
+      () => void 0
+    ),
+    inviteMember: (orgId, email, role, spaces) => {
+      if (typeof email !== "string" || email.trim() === "") {
+        throw new Error("email must be a non-empty string");
+      }
+      segment(role, "role");
+      const body = { email: email.trim(), role };
+      if (spaces) body.spaces = spaces;
+      return send(orgId, "POST", "/api/org/invite", body).then(
+        (d) => d
+      );
+    },
+    listInvitations: (orgId) => send(orgId, "GET", "/api/org/invitations").then((d) => rows(d, "invitations")),
+    revokeInvitation: (orgId, invitationId) => send(orgId, "DELETE", `/api/org/invitations/${segment(invitationId, "invitationId")}`).then(
+      () => void 0
+    ),
+    resendInvitation: (orgId, invitationId) => send(
+      orgId,
+      "POST",
+      `/api/org/invitations/${segment(invitationId, "invitationId")}/resend`
+    ).then(() => void 0)
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ORG_HEADER,
+  createTeamClient
+});

package/dist/client/index.mjs

@@ -0,0 +1,74 @@
+// src/client.ts
+var ORG_HEADER = "X-Reeve-Org-Id";
+var ORG_ID_SHAPE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+function orgHeaders(orgId) {
+  if (typeof orgId !== "string" || !ORG_ID_SHAPE.test(orgId)) {
+    throw new Error(`orgId must be a plausible org id, got ${JSON.stringify(orgId)}`);
+  }
+  return { [ORG_HEADER]: orgId };
+}
+function segment(value, name) {
+  if (typeof value !== "string" || value === "") {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+  return encodeURIComponent(value);
+}
+function hasStringId(row) {
+  return typeof row === "object" && row !== null && typeof row.id === "string" && row.id !== "";
+}
+function rows(data, what) {
+  if (!Array.isArray(data) || !data.every(hasStringId)) {
+    throw new Error(`team: malformed ${what} response`);
+  }
+  return data;
+}
+function createTeamClient({ fetch }) {
+  if (typeof fetch !== "function") {
+    throw new Error("createTeamClient: `fetch` must be a function");
+  }
+  const send = (orgId, method, path, body) => {
+    const headers = orgHeaders(orgId);
+    const init = { method, headers };
+    if (body !== void 0) {
+      headers["Content-Type"] = "application/json";
+      init.body = JSON.stringify(body);
+    }
+    return fetch(path, init);
+  };
+  return {
+    listMembers: (orgId) => send(orgId, "GET", "/api/org/members").then((d) => rows(d, "members")),
+    updateMemberRole: (orgId, memberId, role) => {
+      segment(role, "role");
+      return send(orgId, "PUT", `/api/org/members/${segment(memberId, "memberId")}/role`, {
+        role
+      }).then(() => void 0);
+    },
+    removeMember: (orgId, memberId) => send(orgId, "DELETE", `/api/org/members/${segment(memberId, "memberId")}`).then(
+      () => void 0
+    ),
+    inviteMember: (orgId, email, role, spaces) => {
+      if (typeof email !== "string" || email.trim() === "") {
+        throw new Error("email must be a non-empty string");
+      }
+      segment(role, "role");
+      const body = { email: email.trim(), role };
+      if (spaces) body.spaces = spaces;
+      return send(orgId, "POST", "/api/org/invite", body).then(
+        (d) => d
+      );
+    },
+    listInvitations: (orgId) => send(orgId, "GET", "/api/org/invitations").then((d) => rows(d, "invitations")),
+    revokeInvitation: (orgId, invitationId) => send(orgId, "DELETE", `/api/org/invitations/${segment(invitationId, "invitationId")}`).then(
+      () => void 0
+    ),
+    resendInvitation: (orgId, invitationId) => send(
+      orgId,
+      "POST",
+      `/api/org/invitations/${segment(invitationId, "invitationId")}/resend`
+    ).then(() => void 0)
+  };
+}
+export {
+  ORG_HEADER,
+  createTeamClient
+};