@foir/sdk 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -108,6 +108,140 @@ nobody asking for `@foir/sdk` gets it early. The push that carries the commit to
 
 Changes on `dev` that have not been published to npm.
 
+## [0.23.0] — 2026-10-16
+
+### Added
+
+- **`signInRefusalOf(error)`** (`@foir/sdk/auth`) reads why a sign-in your app's
+  own form sent was refused, as a stable code: `password_sign_in_off` from
+  `login` or `register` where the project, or the app the sign-in came through,
+  takes no password, and `code_sign_in_off` from `requestOTP` or `loginWithOTP`
+  where it takes no code. Null for any other failure.
+- **`hostedSignInNoticeOf` reads what the hosted login sent back** (`@foir/sdk/auth`).
+  A refused sign-in's `foir_error` code, or the provider a sign-in connected to
+  the account (`foir_connected`), each with a sentence your app can show as it
+  is. A code it has no words for reads as a general sentence, never the code.
+- **`myProviderToken` says what it did about the token** (`@foir/sdk/auth`).
+  `refresh` is `REFRESHED`, `FAILED` (with `refreshFailure` saying where),
+  `HELD_BACK` or `NOT_ATTEMPTED`; `reauthenticate` is true when only signing in
+  with the provider again mends the connection; and `linked: false` answers a
+  signed-in user with nothing stored for the provider. Pass `forceRefresh`
+  after the provider refused the token it was given. A token whose provider
+  stated no expiry is now renewed when read, and two reads at once renew it
+  once. New type: `ProviderTokenRefresh`.
+- **`requestPasswordReset` takes a `clientId`** (`@foir/sdk/auth`). Where the
+  project has no App base URL, the reset email links to Foir's hosted reset
+  page, and naming your app sends the user to its initiate login URL to sign in
+  once the password is changed.
+- **`registerOrganization` takes an `appBaseUrl`** (`@foir/sdk/auth`), so an
+  organization a user founds has its address from the first request and an app
+  that finds its organization by `orgUrl` finds this one at once. The address
+  sits under the project's own app address or a domain it verified, and one
+  another organization holds is refused.
+
+### Changed
+
+- **Breaking: `myOrganizations` pages from an entry's `cursor`** (`@foir/sdk/auth`).
+  Each `MyOrganization` it lists carries `cursor`; pass the last one's as
+  `after` for the next page. `after` no longer takes an organization's id. A
+  user whose role holds `organizations:read` in the project is listed every
+  organization of it, suspended ones included.
+
+- **`ProviderToken.accessToken` may be `null`**, when `linked` is false.
+- **`holds` reads a grant that names one field** (`@foir/sdk/auth`), as
+  `records:read:<model>.<field>` or `records:write:<model>.<field>`, the way the
+  platform does. A guarded field is covered by the grant that names it and by
+  one over every owner's records of every model, and not by its model's grant,
+  so `holds(['records:read'], 'records:read:order.taxId')` is `false`.
+- **Breaking: a key in an older format is refused.** Foir answers `401` to a
+  key that begins `pk_`, `sk_` or `tc_` and says it no longer reads that format,
+  and the SDK reads a kind only from `foir_pub_`, `foir_srv_` and `foir_adm_`.
+  Make a key of its kind in its place: see
+  [Credentials](https://docs.foir.dev/credentials).
+
+## [0.22.0] — 2026-10-15
+
+### Added
+
+- **A signed-in user manages their own account** (`@foir/sdk/auth`), in any
+  pool. `updateMyProfile` changes their name, picture or language and asks no
+  permission. `mySessions`, `endMySession` and `signOutEverywhere` list and end
+  their sessions. `createPersonalAccessToken` makes a token that begins
+  `foir_pat_`, answered once (`NewPersonalAccessToken`). `mySignInMethods`, `connectSignInMethod` and
+  `disconnectSignInMethod` list, add and remove the ways they sign in.
+  `myAuthorizedApps` and `revokeAuthorizedApp` list the apps they have let in
+  and take one back. New types: `MyProfile`, `MyProfileChange`, `MySession`,
+  `MySignInMethod`, `AuthorizedApp`.
+- **Second factors and recovery codes** (`@foir/sdk/auth`). `myFactors` lists
+  what a user holds. `beginStepUp` and `completeStepUp` prove a factor and
+  answer an elevated handle for one change in the next ten minutes, which
+  `beginFactorEnrollment`, `completeFactorEnrollment`, `removeFactor` and
+  `makeRecoveryCodes` take. A factor is `totp`, `webauthn` or `passkey`. New
+  types: `MyFactor`, `FactorEnrollment`, `StepUp`.
+- **An organisation that signs its own people in** (`@foir/sdk/app`).
+  `organizations.provision({ ..., ownPool: true })` starts a pool of its own
+  with the organisation, apart from its parent's and the project's; its
+  descendants share it unless one starts another.
+- All of the above need the platform release that serves them.
+
+### Changed
+
+- **Breaking: everyone who signs in is a user, and nothing says customer or
+  admin as a kind.** It needs the platform release that serves the same
+  names; an earlier platform refuses every call below by name.
+  - `@foir/sdk/auth`: the raw calls take the server's op names: `login`,
+    `register`, `requestOTP`, `loginWithOTP`, `refreshTokens` (the
+    `refreshToken` op), `logout`, `joinWaitlist`, `signupContext`,
+    `requestPasswordReset`, `resetPassword`, `updatePassword`, `verifyEmail`,
+    `loginWithProvider`, `providerCallback`, `providerVerifyOTP` (were
+    `customerLogin` and the rest), and `registerOrganization` founds an
+    organization over the `registerOrganization` op (was
+    `registerOperatorOrganization`). The helpers that save a session are
+    `signInWithPassword`, `signUpWithPassword` and `signInWithOTP` (were
+    `loginWithPassword`, `registerWithPassword`, `loginWithOTP`), beside
+    `signOut`. `getSessionCustomer` is `getSessionUser`, `customerAccess` is
+    `userAccess`, `CustomerAuthResult` is `AuthResult` and carries `userId`,
+    `FoirCustomer` is `FoirUser` (`{ id, email }`), and `FoirAccess.customerId`
+    is `userId`. A session is stored under `foir:userId`, so one saved by an
+    earlier version reads as signed out once.
+  - `@foir/sdk/auth`: a provider sign-in that names an address somebody
+    already holds waits for the code sent to it: `providerSignInRefusalOf`
+    reads the refusal (`link_code_sent` with its `pending`), and
+    `confirmProviderLink` and `resendProviderLinkCode` finish it.
+  - `@foir/sdk/auth`: the hosted session answers `userId`
+    (`HostedSession.userId`, `FoirSessionUser.userId`), from the platform's
+    `user_id`, and its cookie is `foir_session`.
+  - `@foir/sdk/react`: `useFoirSession()` answers `user` (was `customer`).
+  - `@foir/sdk/app`: `records.user` and `users` (were `records.customer` and
+    `customers`), over the platform's `saveUserRecord`, `userRecordByIdentity`,
+    `eraseUserRecord`, `createUser`, `user`, `users`, `userByIdentity` and
+    `userIdentitiesById`. `users.list()` answers `{ users }`. `AppUser`,
+    `AppUserList`, `AppUserSaveResult` (`userCreated`), `AppUserEraseResult`
+    (`userDeleted`, `userKeptBecause`), `AppUserEmailUnavailableReason`,
+    `appUserUnlinkedOf` and `appUserEmailUnavailableOf` replace the
+    `AppCustomer` names. A notification, a consent change and an
+    organization's first member name `userId`.
+  - `@foir/sdk/server`: an operation's context names who started the run as
+    `actorId` and the user it acts for as `userId` (was `userId` and
+    `customerId`). `ScopedTokenIngress.userId` was `customerId`.
+  - `@foir/sdk/data`: `FoirGranteeKind` is `'USER'`, a note's subject may be
+    `'user'`, `FoirUserNote` and `FoirUserNoteAttachment` replace the
+    `FoirCustomerNote` names, and `FoirAuthDowngrade.userToken` was
+    `customerToken`.
+
+### Removed
+
+- **Breaking: `selectOrganization` and `SelectedOrganization`**
+  (`@foir/sdk/auth`). Nothing stores where a user stands: a request names the
+  organization it acts in (`orgId` or `orgUrl`), and the platform checks they
+  stand there on that request. `myOrganizations` still lists where they may.
+- **Breaking: `requireAdmin` and `RequireAdminOptions`, and `isAdmin` on
+  `FoirUser`** (`@foir/sdk/auth`). What a user may do is a role or a scope:
+  guard on it with `requireRole` or `requireScope`. `requireAuth` takes the
+  type `resolveUser` answers, for a project that reads its own profile.
+
+## [0.21.0] — 2026-10-13
+
 ### Added
 
 - **An operation provisions an organization** (`@foir/sdk/app`).
@@ -1125,7 +1259,7 @@ returns a result object rather than `HostedSession | null`, and
   silent wrong answer for a thrown one that discards the answer. Nothing changes
   for a caller that does not pass it.
 
-- `registerOrganization(env, { key, name }, { bearerToken })` on `@foir/sdk/auth`: a customer founds an organization of their own and becomes its first member, holding the role the project's `operatorSignupRole` setting names. Returns the same `MyOrganization` entry `myOrganizations` lists. Present on the wire only while the project's `operatorSignupEnabled` setting is on.
+- `registerOrganization(env, { key, name }, { bearerToken })` on `@foir/sdk/auth`: a customer founds an organization of their own and becomes its first member, holding the role the project's `organizationSignupRole` setting names. Returns the same `MyOrganization` entry `myOrganizations` lists. Present on the wire only while the project's `organizationSignupEnabled` setting is on.
 - **The operator's organization context, on `@foir/sdk/auth`** — `myOrganizations`
   and `selectOrganization`, plus the types `MyOrganization` and
   `SelectedOrganization`, and two entries on `AUTH_OPS`.

package/README.md

@@ -1,6 +1,6 @@
 # @foir/sdk
 
-Official Foir SDK — client-agnostic typed GraphQL transport, customer auth,
+Official Foir SDK — client-agnostic typed GraphQL transport, sign-in for your app's users,
 progressive media, content rendering, realtime collaboration, and editor/server
 helpers for building apps on the [Foir](https://foir.dev) platform.
 
@@ -25,7 +25,7 @@ pnpm add yjs y-websocket    # for @foir/sdk/realtime
 | `@foir/sdk` | Editor iframe client — `EditorProvider`, `useEditor`, `useAutoResize`, `createPlatformClient`, host↔editor message protocol | `react` |
 | `@foir/sdk/client` | Client-agnostic GraphQL transport for SSR/edge loaders — `foirRequest`, `isFoirPreview`, `absolutiseFoirMediaUrl` | `graphql` |
 | `@foir/sdk/data` | Typed data client over `/graphql` — `createFoirClient`, per-key-shaped ops, `include`/`omit`, `fetchFoirManifest`; prints the document for you, so still no `graphql` | **none** |
-| `@foir/sdk/auth` | Framework-agnostic customer auth — login/register/OTP/provider flows, token lifecycle (`SessionAdapter`), `createFoirSessionClient` (Foir-hosted cookie sessions), `authedRequest`, guards | `graphql` |
+| `@foir/sdk/auth` | Framework-agnostic sign-in for your app's users: login/register/OTP/provider flows, token lifecycle (`SessionAdapter`), `createFoirSessionClient` (Foir-hosted cookie sessions), `authedRequest`, guards | `graphql` |
 | `@foir/sdk/react` | Drop-in React auth — `<FoirProvider>` (token or `hostedSession` mode), `useFoirSession`/`useFoirUser`/`useFoirAuth`, `<SignIn>`, `<OAuthButtons>`, `<UserButton>` | `react`, `graphql` |
 | `@foir/sdk/next` | Next.js App Router BFF auth — `createFoirCookieAdapter`, `getFoirSession`, `foirSignIn*`, `completeFoirProviderLogin`, `createFoirMiddleware` | `graphql` |
 | `@foir/sdk/server` | Server-side helpers for extension/config API backends — `createServerClient`, `verifyWebhookSignature`, `verifyScopedToken`, callback client | — |
@@ -104,11 +104,11 @@ present — there is no partial-`select` footgun. `include` adds a relation key,
 `__typename` that narrow under an exhaustive `switch` with no casts.
 
 **The client is shaped by your credential.** The generated `FoirSchema` contains
-only what that key's manifest lists, so a read-only `pk_` key has no `create` to
+only what that key's manifest lists, so a read-only publishable key has no `create` to
 call:
 
 ```ts
-foir.post.create({ data });   // ✗ compile error under a pk_ key — not in its manifest
+foir.post.create({ data });   // ✗ compile error under a publishable key: not in its manifest
 ```
 
 `generated` is optional. Without it — and without `selections` — the client
@@ -119,14 +119,14 @@ that way; silence it with `announceManifestFallback: false`.
 
 Reads that can be shared are sent to `GET /cdn/graphql` with only the
 persisted-query hash in the URL, so a CDN in front of you can serve the next
-visitor without reaching origin. That is a query, on a `pk_` key, with no
-customer bearer, on the published channel; everything else is a `POST /graphql`.
+visitor without reaching origin. That is a query, on a publishable key, with no
+user bearer, on the published channel; everything else is a `POST /graphql`.
 
 `foir.raw()` is the escape hatch, and it takes a **GraphQL document** — it
 reaches anything the credential can, including root fields no model or namespace
 claims. It returns the whole `data` object.
 
-Namespaces (`search`, `customers`, `notifications`) live under `foir.ns` because
+Namespaces (`search`, `users`, `notifications`) live under `foir.ns` because
 the client carries no runtime schema to tell a namespace from a model. `ns` and
 `raw` are the only reserved names.
 
@@ -144,7 +144,7 @@ const foir = createFoirClient({
 
 Already have `PLATFORM_API_URL` / `PLATFORM_API_KEY` / `FOIR_PREVIEW` wired for
 the GraphQL path? `createFoirClientFromEnv(env, { generated })` reuses them,
-including the preview `sk_` key and the draft schema channel.
+including the preview key and the draft schema channel.
 
 A product built on organizations names the one a request acts in with `orgId`,
 which the client sends as `X-Org-Id` on every request. This is for the PROJECT
@@ -178,18 +178,18 @@ export async function loader({ context }: LoaderArgs) {
 }
 ```
 
-### Customer auth
+### Signing your users in
 
 ```ts
 import {
-  loginWithPassword,
+  signInWithPassword,
   authedRequest,
   type SessionAdapter,
 } from '@foir/sdk/auth';
 import { MyProfileDocument } from './generated/graphql';
 
 // SessionAdapter = { get, set, delete } over your session store (cookie, KV…).
-const customer = await loginWithPassword(adapter, env, { email, password });
+const user = await signInWithPassword(adapter, env, { email, password });
 
 // Bearer-authed request with automatic refresh-and-retry on expired sessions.
 const { myProfile } = await authedRequest(adapter, env, MyProfileDocument);
@@ -207,7 +207,7 @@ import { FoirProvider, SignIn, UserButton, useFoirSession } from '@foir/sdk/reac
 
 const env = {
   PLATFORM_API_URL: process.env.NEXT_PUBLIC_PLATFORM_API_URL,
-  PLATFORM_API_KEY: process.env.NEXT_PUBLIC_PLATFORM_API_KEY, // a publishable pk_ key
+  PLATFORM_API_KEY: process.env.NEXT_PUBLIC_PLATFORM_API_KEY, // a publishable key
 };
 
 export function App() {
@@ -241,7 +241,7 @@ backend.
 
 ```tsx
 <FoirProvider
-  env={{ PLATFORM_API_URL: 'https://api.foir.dev/graphql', PLATFORM_API_KEY: 'pk_…' }}
+  env={{ PLATFORM_API_URL: 'https://api.foir.dev/graphql', PLATFORM_API_KEY: 'foir_pub_…' }}
   hostedSession={{ loginOrigin: 'https://login.acme.com' }}
 >
   <App />
@@ -282,8 +282,8 @@ import { cookies } from 'next/headers';
 import { getFoirSession } from '@foir/sdk/next';
 
 export default async function Dashboard() {
-  const customer = await getFoirSession(await cookies());
-  return <p>Signed in as {customer?.email}</p>;
+  const user = await getFoirSession(await cookies());
+  return <p>Signed in as {user?.email}</p>;
 }
 ```