@farthershore/farthershore-js 0.33.0 → 0.35.0

package/CHANGELOG.md

@@ -3,7 +3,128 @@
 All notable changes to `@farthershore/farthershore-js` are documented here.
 This project adheres to Semantic Versioning (pre-1.0: minors may break).
 
-## [Unreleased]
+## [0.35.0] - 2026-10-07
+
+### Added
+
+- `toPublicMessage(err, fallback?)`, from the package root and `/errors`:
+  the text to show a visitor for a caught error. A `4xx` that carried a
+  message reads as itself, a `401` asks the visitor to sign in again, and a
+  network failure, any `5xx` or an error the SDK did not mint becomes neutral
+  copy. Use it in custom UI over the hooks' `error`.
+- `FartherShoreConfigError` takes an optional `cause`.
+- `fs.team.roles` (`TeamRolesResource`): the team roles each member holds —
+  what they can do in the account (billing, API keys, invites, team
+  settings). `list()` (`GET /me/team-roles`: the permission catalog, every
+  role with its member count and, for Admin / Member, the platform defaults,
+  and its governed permission `version`, plus `caller` — what the signed-in member may grant and whether they hold
+  owner authority; `caller.independentOwner` distinguishes organization ownership
+  that survives changing the caller's subscriber seat), `create()`, `update()`, `remove()` (its members move to
+  Member) and `assign()` (`PATCH /me/team/:id { teamRole }`). Types:
+  `TeamRoleKind`, `TeamRoleDefinition`, `TeamPermissionGroup`, `TeamRoles`,
+  `TeamRoleCaller`, `CreateTeamRoleInput`, `UpdateTeamRoleInput`,
+  `TeamRoleDeleted`. `TeamMember`, `TeamInvitation` and
+  `TeamInvitationAccepted` gain `teamRole` (`owner` / `admin` / `member` / a
+  custom key), and `team.invites.create()` accepts `teamRole`.
+  `TeamMemberRoleUpdated` and `TeamMemberProductRolesUpdated` describe the
+  exact member PATCH projections; refetch `team.list()` for the full row.
+  `update()` and `remove()` require the opaque `expectedRevision` captured when
+  editing. Revisions bind to the role instance and advance on every write,
+  including renames; deleting and recreating a key cannot reuse a draft. Stale writes
+  return `ROLE_VERSION_CONFLICT` (409). The editor keeps its opening baseline,
+  sends only edited fields, and closes stale actions so retrying requires reopening.
+  Edit, rename, permission, restore-defaults and delete actions capture an immutable
+  opening snapshot. Background refreshes show a change notice without retargeting
+  the action; a removed role closes its action with an explanatory sentence. Product-role
+  definition and assignment writes refresh caller authority. Product settings writes
+  preserve an unrelated open team-role action. Request-access and approval controls
+  obey inherited read-only gates.
+  The key helpers `deriveTeamRoleKey`, `customTeamRoleKeyProblem`,
+  `TEAM_ROLE_KEY_PATTERN`, `RESERVED_TEAM_ROLE_KEYS` and
+  `MAX_CUSTOM_TEAM_ROLES` are public and pinned to the platform rules.
+  The mock transport implements role CRUD, caller authority, assignments,
+  invitations and typed failures; `createMockFartherShoreClient` accepts
+  a team seed for the same behaviour (`MockFartherShoreClientOptions`,
+  `MockTeamOptions`). Organization owners can be seeded separately with
+  `organizationOwnerUserIds`. Caller seeds contain identity only; team actions,
+  owner tier and grant ceilings derive from current membership, team roles,
+  direct grants and assigned product roles on every request. `rbacSettings` seeds
+  the enabled default product role for members without an explicit assignment;
+  settings reads and writes share that authority state. The same resolver
+  checks deferred invitations. The old caller authority and `permissions` seed
+  fields have been removed; seed role/member grants instead.
+- Team-role caller metadata separates `actions` (what the caller may do) from
+  `grantable` (the permission ceiling). Direct action grants expose authorized
+  controls without widening role options or editable permissions.
+- The access-request inbox uses `team:manage_rbac` independently of invitations.
+  Role writes preserve invitation drafts, manual acceptance links and pending
+  sends within the current team. Inherited read-only gates suppress team writes.
+
+### Removed
+
+- **Breaking (pre-1.0 minor):** `team.updateRole(membershipId, role)` and
+  `useTeam().updateRole` are removed, as is the legacy `{ role }` input to
+  `team.invites.create`. Use `team.roles.assign(membershipId, teamRole)`
+  and `team.invites.create({ email, teamRole })`; the built-in keys are
+  `owner`, `admin` and `member` (formerly `OWNER`, `ADMIN`, `VIEWER`).
+  Call `useTeam().refetch()` after a direct assignment when using the hook.
+  Member and invitation `role` remains a read-only stored tier; every row's
+  `teamRole` is the authoritative team role.
+
+### Changed
+
+- `<FsTeam/>` is the redesigned Team page: **Members** (an invite bar with
+  inline validation over one table of members and pending invites — inline
+  team-role select, product-role chips, last-owner protection, two-step
+  Remove / Revoke) and **Roles & permissions** (a card per team role with a
+  coverage bar, per-resource chips and member count; an inline grouped
+  permission editor with changed-dots, Select all / Clear all, Restore
+  defaults for Admin / Member and an unsaved-change count; "+ New role" with
+  the platform's key preview; delete; then the product-role block), plus the
+  access-request inbox, the request-access form and component access.
+  Permissions the viewer can't grant are locked ("You can only grant
+  permissions you have"); a viewer with `team:read` but not
+  `team:manage_rbac` sees the roles read-only. Role-write failures map to one
+  clear sentence per platform error code. `FsTeam` now includes the invite
+  flow; `FsTeamMembersSection` gains `onMembersChanged` and
+  `FsTeamRolesSection` gains `refreshSignal` (member counts stay current).
+  Standalone `TeamPanel`, `FsMemberRoles` and `FsInviteMembers` also use
+  `teamRole` and live caller authority, and keep their existing layouts.
+
+- Portal visitors no longer see platform plumbing. A request that never
+  reaches the platform now throws `FartherShoreNetworkError` with "We
+  couldn't connect. Check your internet connection and try again." instead of
+  `Core request failed: <transport error>` and its Gateway and `fs.fetch`
+  variants; the transport error stays on `cause`. A managed portal without its platform route throws
+  `FartherShoreConfigError` with "This portal is temporarily unavailable.
+  Please try again later." and keeps the diagnostic on `cause`. Code that
+  matched the old message text must use `instanceof` instead.
+- Every managed component renders failures through `toPublicMessage`: no
+  `5xx` message, payment-provider error text (such as "No such customer" on
+  Add funds) or render-crash message reaches the page — including a crash
+  inside a product docs page, which `SafeDocsMarkdown` catches itself. Each
+  says what failed and that the visitor can try again.
+- `<AuditLogTable>` labels actors in product terms, in the table and the CSV,
+  and keeps credentials distinguishable without database ids: the person's
+  name; an API key as `API key "<name>" (<keyPrefix>…)`; a maker token as
+  `Maker token ••••<last4>`; else a teammate's user id, "Business team" for
+  the business's own people, and "Automated platform action" for platform
+  services — never a raw `actorType:actorUserId` such as `gateway:gw-node-7`.
+  `AuditLogEntry.actorCredential` (new type `AuditLogActorCredential`) carries
+  the handle Core resolves.
+
+## [0.34.0] - 2026-10-03
+
+### Removed
+
+- **Breaking:** the Idempotency-Key request mechanism is gone from the
+  platform, so the SDK no longer sends an `idempotency-key` header.
+  `CoreRequest.idempotencyKey` is removed, and so is the trailing
+  `options: ServiceAccountMutationOptions` argument of
+  `serviceAccounts.create()` / `serviceAccounts.update()`. Drop that argument. Repeating
+  the same `create` lands on the pending approval it already opened, or
+  resumes a still-pending activation of that name. It never mints a second
+  credential.
 
 ## [0.33.0] - 2026-10-03
 

package/README.md

@@ -3,7 +3,7 @@
 The **Farther Shore Frontend SDK** — the browser + React integration layer for
 your product's subscriber portal.
 
-> **Status: `0.33.0` (pre-1.0).** Pin the version you build against and read
+> **Status: `0.35.0` (pre-1.0).** Pin the version you build against and read
 > [`CHANGELOG.md`](./CHANGELOG.md) before upgrading.
 
 ```bash
@@ -61,12 +61,14 @@ ecosystem shape — `{ data, error, isLoading, isError, isSuccess, refetch,
 queryKey }` — plus its mutations:
 
 ```tsx
+import { toPublicMessage } from "@farthershore/farthershore-js";
 import { useApiKeys } from "@farthershore/farthershore-js/react";
 
 function ApiKeys() {
   const { data, isLoading, isError, error, refetch } = useApiKeys();
   if (isLoading) return <p>Loading…</p>;
-  if (isError) return <p>Failed to load keys: {error?.message}</p>;
+  if (isError)
+    return <p>{toPublicMessage(error, "We couldn't load your keys.")}</p>;
   return (
     <ul>
       {data?.map((k) => (
@@ -370,6 +372,13 @@ The full taxonomy — throttle subclasses (`ConcurrencyLimitError`,
 `AdaptiveThrottleError`), deny-envelope parsers, `makeApiError`, secure-fetch
 codes, and more — lives at the `@farthershore/farthershore-js/errors` subpath.
 
+To show an error to a visitor, render `toPublicMessage(err, fallback)` rather
+than `err.message`. A `4xx` that carried a message (a validation refusal, a
+missing permission) reads as itself and a `401` asks the visitor to sign in
+again; a network failure, any `5xx` or an unrecognized error becomes neutral
+copy, so platform and provider detail never reaches the page. The managed
+components all render failures this way.
+
 ## Display helpers
 
 Pure catalog display helpers (declared plan kind, recurring price, quotas,
@@ -422,3 +431,11 @@ Core or the Gateway.
 See the platform docs for the full guide to building, publishing, and operating a
 product on Farther Shore. Breaking changes within `0.x` are recorded in
 [`CHANGELOG.md`](./CHANGELOG.md) — read it before bumping.
+
+Team roles use one write surface: `fs.team.roles.assign(membershipId, teamRole)`
+assigns `owner`, `admin`, `member` or a custom key. Invite with
+`fs.team.invites.create({ email, teamRole })`; omit `teamRole` to invite a
+Member. The legacy `{ role }` invite input and `team.updateRole` were removed
+in 0.35.0. `role` on returned rows is the stored tier, while `teamRole` is
+the member's actual role. Assignment returns `TeamMemberRoleUpdated`; refetch
+`team.list()` for the full roster row.

package/dist/components/access-control.d.ts

@@ -2,6 +2,10 @@
  *  (apps/core/src/routes/portal-customer/rbac.ts → `requirePermission(…,
  *  "team:manage_rbac")`). Used as the default editor gate. */
 export declare const MANAGE_RBAC_PERMISSION = "team:manage_rbac";
+/** Read the signed-in member's external id from `GET /me` — the value the
+ *  roster matches against `member.userExternalId` to find "self" (mirrors the
+ *  template's readUserId). */
+export declare function readUserExternalId(subscriber: unknown): string | null;
 export interface FsRoleEditorProps {
     /** Appended to the root card. */
     className?: string;
@@ -21,14 +25,14 @@ export interface FsRoleEditorProps {
  * settings/catalog/roles under <FartherShoreRoot>; renders nothing when the
  * product doesn't enable RBAC or the caller can't read the config.
  */
-export declare function FsRoleEditor({ className, canManage, onRolesChanged, }?: FsRoleEditorProps): import("react").JSX.Element | null;
+export declare function FsRoleEditor(props?: FsRoleEditorProps): import("react").JSX.Element;
 export interface FsMemberRolesProps {
     /** Appended to the root card. */
     className?: string;
     /** Whether the viewer may change roles/assignments. Defaults to the viewer's
      *  team role (OWNER/ADMIN) resolved from the team read. */
     canManage?: boolean;
-    /** Whether the viewer may remove members. Defaults to OWNER only. */
+    /** Whether the viewer may remove members. Defaults to the live caller's removal action. */
     canRemove?: boolean;
     /** Heading text. Defaults to "Team members". */
     title?: string;
@@ -36,15 +40,16 @@ export interface FsMemberRolesProps {
      *  after a role create/delete so the product-role columns pick up the
      *  change). Ignored when unchanged / undefined. */
     refreshSignal?: number;
+    /** Notify composed sections after a successful product assignment. */
+    onMembersChanged?: () => void;
 }
 /**
- * The member roster with Managed-RBAC assignment: platform-role select
- * (OWNER/ADMIN/VIEWER), the org's product-role assignment checkboxes,
+ * The member roster with Managed-RBAC assignment: team-role select, the org's product-role assignment checkboxes,
  * stale-role warnings, and remove. Self-fetches the team roster + `GET /me`
  * (to find "self") under <FartherShoreRoot>. A failed team read degrades to a
  * read-only roster with the server's reason (team-panel precedent).
  */
-export declare function FsMemberRoles({ className, canManage, canRemove, title, refreshSignal, }?: FsMemberRolesProps): import("react").JSX.Element;
+export declare function FsMemberRoles({ className, canManage, canRemove, title, refreshSignal, onMembersChanged, }?: FsMemberRolesProps): import("react").JSX.Element;
 export interface FsInviteMembersProps {
     /** Appended to the root card. */
     className?: string;
@@ -61,12 +66,12 @@ export interface FsInviteMembersProps {
 }
 /**
  * Track T2 — the subscriber-team invitation piece: a create form (email +
- * platform role + optional product-role grants) and the pending-invitation list
+ * team role + optional product-role grants) and the pending-invitation list
  * with revoke. Self-fetches `fs.team.invites.list()` under <FartherShoreRoot>.
  * Renders nothing for non-managers (canManage=false). The raw token from a
  * successful create is surfaced once (email is the primary delivery channel).
  */
-export declare function FsInviteMembers({ className, canManage, availableRoles, }?: FsInviteMembersProps): import("react").JSX.Element | null;
+export declare function FsInviteMembers(props?: FsInviteMembersProps): import("react").JSX.Element;
 export interface FsAcceptInviteProps {
     /** Appended to the root card. */
     className?: string;
@@ -113,10 +118,10 @@ export interface FsAccessControlProps {
     className?: string;
     /** Whether the viewer may mutate settings/roles/assignments. When omitted the
      *  role editor defaults to the `team:manage_rbac` claim and the roster to the
-     *  viewer's team role; pass an explicit value to gate both off one signal
-     *  (e.g. the template's OWNER/ADMIN derivation). */
+     *  server-resolved team authority; pass an explicit value to gate both off one signal
+     *  (e.g. the template's permission derivation). */
     canManage?: boolean;
-    /** Whether the viewer may remove members. Defaults to OWNER only. */
+    /** Whether the viewer may remove members. Defaults to the live caller's removal action. */
     canRemove?: boolean;
 }
 /**

package/dist/components/access-control.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"access-control.d.ts","sourceRoot":"","sources":["../../src/components/access-control.tsx"],"names":[],"mappings":"AA8CA;;8DAE8D;AAC9D,eAAO,MAAM,sBAAsB,qBAAqB,CAAC;AAyEzD,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;6EAGyE;IACzE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;oDACgD;IAChD,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,EAC3B,SAAS,EACT,SAAS,EACT,cAAc,GACf,GAAE,iBAAsB,sCAuexB;AAID,MAAM,WAAW,kBAAkB;IACjC,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;+DAC2D;IAC3D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;uDAEmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,EAC5B,SAAS,EACT,SAAS,EACT,SAAS,EACT,KAAsB,EACtB,aAAa,GACd,GAAE,kBAAuB,+BA6PzB;AAMD,MAAM,WAAW,oBAAoB;IACnC,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;sCAEkC;IAClC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;0DACsD;IACtD,cAAc,CAAC,EAAE,SAAS;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAC9B,SAAS,EACT,SAAiB,EACjB,cAAmB,GACpB,GAAE,oBAAyB,sCAgM3B;AAID,MAAM,WAAW,mBAAmB;IAClC,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;iEAC6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,EAC7B,SAAS,EACT,KAAK,EAAE,SAAS,EAChB,UAAU,GACX,GAAE,mBAAwB,+BA+D1B;AAID,MAAM,WAAW,oBAAoB;IACnC,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAAE,SAAS,EAAE,GAAE,oBAAyB,sCAqJvE;AAID,MAAM,WAAW,0BAA0B;IACzC,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,SAAS,EACT,SAAiB,GAClB,GAAE,0BAA+B,sCAoGjC;AAID,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;wDAGoD;IACpD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,EAC9B,SAAS,EACT,SAAS,EACT,SAAS,GACV,GAAE,oBAAyB,+BAyC3B"}
+{"version":3,"file":"access-control.d.ts","sourceRoot":"","sources":["../../src/components/access-control.tsx"],"names":[],"mappings":"AAoDA;;8DAE8D;AAC9D,eAAO,MAAM,sBAAsB,qBAAqB,CAAC;AAoBzD;;8BAE8B;AAC9B,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAMrE;AA+CD,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;6EAGyE;IACzE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;oDACgD;IAChD,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,GAAE,iBAAsB,+BAQzD;AA8iBD,MAAM,WAAW,kBAAkB;IACjC,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;+DAC2D;IAC3D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;uDAEmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAC5B,SAAS,EACT,SAAS,EACT,SAAS,EACT,KAAsB,EACtB,aAAa,EACb,gBAAgB,GACjB,GAAE,kBAAuB,+BA8UzB;AAID,MAAM,WAAW,oBAAoB;IACnC,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;sCAEkC;IAClC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;0DACsD;IACtD,cAAc,CAAC,EAAE,SAAS;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,GAAE,oBAAyB,+BAQ/D;AAgPD,MAAM,WAAW,mBAAmB;IAClC,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;iEAC6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,EAC7B,SAAS,EACT,KAAK,EAAE,SAAS,EAChB,UAAU,GACX,GAAE,mBAAwB,+BA+D1B;AAID,MAAM,WAAW,oBAAoB;IACnC,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAAE,SAAS,EAAE,GAAE,oBAAyB,sCAsJvE;AAID,MAAM,WAAW,0BAA0B;IACzC,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,SAAS,EACT,SAAiB,GAClB,GAAE,0BAA+B,sCAsGjC;AAID,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;uDAGmD;IACnD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,EAC9B,SAAS,EACT,SAAS,EACT,SAAS,GACV,GAAE,oBAAyB,+BAqC3B"}