@foir/sdk 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -108,6 +108,57 @@ 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

package/README.md

@@ -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,7 +119,7 @@ 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
+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
@@ -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
@@ -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 />

package/dist/app/client.d.ts

@@ -97,10 +97,11 @@ export interface AppInstallConfig {
     sources: AppBinding[];
     sinks: AppBinding[];
     /**
-     * Why the project cannot send a user an email at the level this install
-     * sits at, or null when it can. While it is set, a notification that carries
-     * an email and an opt-in to a category confirmed by email are refused
-     * (`appUserEmailUnavailableOf`), so say so before one is.
+     * Why the app's emails to users cannot link into the app at the level this
+     * install sits at, or null when they can. While it is set, a notification
+     * whose email links into the app with `{base}` is refused
+     * (`appUserEmailUnavailableOf`), so say so before one is. Every other email
+     * is sent.
      */
     userEmailUnavailable: AppUserEmailUnavailableReason | null;
     /**

package/dist/app/errors.d.ts

@@ -35,18 +35,20 @@ export declare function appUserUnlinkedOf(error: unknown): {
     identityProvider: string;
 } | null;
 /**
- * Why a project cannot send a user an email. `NO_APP_BASE_URL`: no App base
- * URL is set for the project, or for the user's organization. A reason
- * this build does not know arrives as the platform spelled it.
+ * Why a project cannot send a user an email. `NO_APP_BASE_URL`: the email
+ * links into the app with `{base}`, and no App base URL is set for the project
+ * or for the user's organization. A reason this build does not know arrives as
+ * the platform spelled it.
  */
 export type AppUserEmailUnavailableReason = 'NO_APP_BASE_URL' | (string & {});
 /** The reason as the platform sent it, or null when it sent none. */
 export declare function userEmailUnavailableReasonOf(value: unknown): AppUserEmailUnavailableReason | null;
 /**
  * A request refused because it would send a user an email the project
- * cannot send, or null for any other failure. Nothing was written and nothing
- * was queued. An opt-in to a category confirmed by email is refused this way,
- * and so is a notification that carries an email.
+ * cannot build, or null for any other failure. Nothing was written and nothing
+ * was queued. A notification whose email links into the app with `{base}` is
+ * refused this way where no App base URL is set, and so is an opt-in whose
+ * confirmation email the project's copy links into the app.
  *
  * It is about the project, not the user: the project's team fixes it,
  * and the same request goes once they have.

package/dist/auth/auth.d.ts

@@ -79,6 +79,16 @@ export declare function providerSignInRefusalOf(error: unknown): {
     code: string;
     pending?: string;
 } | null;
+/**
+ * Why a sign-in your app's own form sent was refused, as the platform said it:
+ * a stable code your app shows its own words for. `password_sign_in_off` from
+ * {@link login} or {@link register} where the project, or the app the sign-in
+ * came through, takes no password; `code_sign_in_off` from {@link requestOTP}
+ * or {@link loginWithOTP} where it takes no code. Null for any other failure.
+ */
+export declare function signInRefusalOf(error: unknown): {
+    code: string;
+} | null;
 /**
  * Finish a provider sign-in that is waiting for the code sent to its address,
  * connecting the provider to the account that holds the address. See
@@ -121,8 +131,14 @@ export declare function joinWaitlist(env: FoirEnv, email: string): Promise<Waitl
  * Send a password-reset email. Resolves `true` whether or not the address has
  * an account: the server answers identically either way, on purpose, so this
  * endpoint cannot be used to test whether someone has signed up.
+ *
+ * `clientId` names your app. Where the email's link goes to Foir's hosted
+ * reset page (the project has no App base URL), the page then sends the user
+ * to your app's initiate login URL to sign in.
  */
-export declare function requestPasswordReset(env: FoirEnv, email: string): Promise<boolean>;
+export declare function requestPasswordReset(env: FoirEnv, email: string, options?: {
+    clientId?: string;
+}): Promise<boolean>;
 /**
  * Redeem an emailed reset token and set a new password. Returns a fresh session
  * (resetting a password signs the user in), so pair it with
@@ -148,11 +164,19 @@ export declare function updatePassword(env: FoirEnv, vars: {
  */
 export declare function currentUser(env: FoirEnv, options?: AuthOpOptions): Promise<CurrentUser | null>;
 /**
- * The stored upstream provider token for the calling user, refreshed
- * transparently by the server when it has expired. `null` when there is no
- * user token on the request or none stored for that provider.
+ * The stored upstream provider token for the calling user, renewed by the
+ * server when it is due: near its stated expiry, or with no expiry stated.
+ * `null` when there is no user token on the request; `linked: false` when the
+ * user has none stored for that provider.
+ *
+ * Pass `forceRefresh` after the provider refused the token it was last given:
+ * the server renews it then, at most once a minute for one user and provider.
+ * `refresh` says what the read did, and `reauthenticate` says when only the
+ * user signing in with the provider again mends the connection.
  */
-export declare function myProviderToken(env: FoirEnv, providerKey: string, options?: AuthOpOptions): Promise<ProviderToken | null>;
+export declare function myProviderToken(env: FoirEnv, providerKey: string, options?: AuthOpOptions & {
+    forceRefresh?: boolean;
+}): Promise<ProviderToken | null>;
 /**
  * End the session server-side, revoking stored provider tokens. This does NOT
  * clear local session state — {@link signOut} is the pairing that does both.
@@ -275,8 +299,9 @@ export declare function makeRecoveryCodes(env: FoirEnv, elevatedHandle: string,
  * Answered from the calling user's own memberships: each organization they
  * hold one in and every organization beneath it, so the list is exactly the
  * set a request of theirs may name, and a user with no memberships sees an
- * empty list rather than a refusal. Requires the user's bearer; it is not the
- * project's inventory and cannot be used as one.
+ * empty list rather than a refusal. Requires the user's bearer. A user whose
+ * role holds `organizations:read` in the project is listed every organization
+ * of it instead, suspended ones included.
  *
  * A MEMBERSHIP REACHES DOWNWARD. Someone who is a member of an organization may
  * stand in any organization beneath it without holding a row of their own
@@ -295,8 +320,8 @@ export declare function myOrganizations(env: FoirEnv, vars?: {
 /**
  * Found an organization, as its first member.
  *
- * The caller decides the NAME and, optionally, where it hangs — and nothing
- * else. The founder is the user behind the bearer, the id is minted
+ * The caller decides the NAME and, optionally, where it hangs and where it
+ * lives — and nothing else. The founder is the user behind the bearer, the id is minted
  * server-side the way a project's and a tenant's are, and the role they hold in
  * the new organization is the one the PROJECT named in its settings
  * (`organizationSignupRole`). The server creates the organization and that one
@@ -310,6 +335,12 @@ export declare function myOrganizations(env: FoirEnv, vars?: {
  * not-found. Omit it to found a root, which is what every registration did
  * before organizations nested.
  *
+ * `appBaseUrl` is where the organization's app lives, so an app that finds its
+ * organization from the page address (`orgUrl`) finds this one at once. It is
+ * held to the rule every organization address is: under the project's own app
+ * address or a domain the project verified, and not one another organization
+ * of the project holds.
+ *
  * Exists on the wire only while the project's `organizationSignupEnabled` setting
  * is on; a project that never opted in has no such field, and this refuses
  * naming it. Returns the same entry `myOrganizations` would then list, role
@@ -318,6 +349,7 @@ export declare function myOrganizations(env: FoirEnv, vars?: {
 export declare function registerOrganization(env: FoirEnv, vars: {
     name: string;
     parentId?: string;
+    appBaseUrl?: string;
 }, options?: AuthOpOptions): Promise<MyOrganization>;
 /**
  * Persist an auth result to the session; returns the signed-in user.

package/dist/auth/grant-table.generated.d.ts

@@ -1,12 +1,13 @@
 export type GrantReach = 'own' | 'named' | 'all';
+export type GrantTarget = 'none' | 'model' | 'operation';
 /**
- * One permission: its name, whether a grant of it may name a target, the
- * reaches it may be granted at (none: only its bare form exists), and the
- * grants a holder of it also holds.
+ * One permission: its name, what a grant of it may name, the reaches it may be
+ * granted at (none: only its bare form exists), and the grants a holder of it
+ * also holds.
  */
 export type GrantTableRow = readonly [
     name: string,
-    takesTarget: boolean,
+    target: GrantTarget,
     reaches: readonly GrantReach[],
     implies: readonly string[]
 ];

package/dist/auth/hosted.d.ts

@@ -127,3 +127,27 @@ export type HostedSessionResult =
  * returning `null` for everything that is not a success.
  */
 export declare function fetchHostedSession(request: Request, config: HostedLoginConfig): Promise<HostedSessionResult>;
+/**
+ * What the hosted login said beside the code when it sent someone back to your
+ * app. A sign-in it refused carries a stable code (`foir_error`); one that
+ * connected a provider to the person's account on the way in names the
+ * provider (`foir_connected`). Each comes with a sentence your app can show as
+ * it is, so an app that does nothing more still shows words and never a code.
+ * Show your own words for a code by switching on `code`.
+ */
+export type HostedSignInNotice = {
+    kind: 'refused';
+    code: string;
+    message: string;
+} | {
+    kind: 'connected';
+    provider: string;
+    message: string;
+};
+/**
+ * Reads the notice off the address the hosted login sent the browser back to:
+ * your callback URL, its search string, or its parameters. `names` maps a
+ * provider's key to the name to show (from `getAuthProviders`); without it the
+ * key is shown. Null when the hosted login said nothing.
+ */
+export declare function hostedSignInNoticeOf(location: string | URL | URLSearchParams, names?: Record<string, string>): HostedSignInNotice | null;

package/dist/auth/index.d.ts

@@ -10,15 +10,15 @@
  * the caller's own manifest advertises, through the same op transport
  * `@foir/sdk/data` uses, so `graphql` is not on this module's path at all.
  */
-export { login, register, requestOTP, loginWithOTP, refreshTokens, loginWithProvider, providerCallback, providerVerifyOTP, providerSignInRefusalOf, confirmProviderLink, resendProviderLinkCode, getAuthProviders, getAuthConfig, getDefaultAuthProvider, signupContext, joinWaitlist, requestPasswordReset, resetPassword, updatePassword, verifyEmail, currentUser, myProviderToken, logout, deleteMyAccount, updateMyProfile, myAuthorizedApps, revokeAuthorizedApp, mySessions, endMySession, signOutEverywhere, createPersonalAccessToken, mySignInMethods, connectSignInMethod, disconnectSignInMethod, myFactors, beginStepUp, completeStepUp, beginFactorEnrollment, completeFactorEnrollment, removeFactor, makeRecoveryCodes, myOrganizations, registerOrganization, saveSession, clearSession, getSessionToken, getSessionUser, signInWithPassword, signUpWithPassword, signInWithOTP, resetPasswordAndSignIn, refreshSession, refreshSessionOnce, signOut, authedRequest, authedOp, requireAuth, } from './auth';
+export { login, register, requestOTP, loginWithOTP, refreshTokens, loginWithProvider, providerCallback, providerVerifyOTP, providerSignInRefusalOf, signInRefusalOf, confirmProviderLink, resendProviderLinkCode, getAuthProviders, getAuthConfig, getDefaultAuthProvider, signupContext, joinWaitlist, requestPasswordReset, resetPassword, updatePassword, verifyEmail, currentUser, myProviderToken, logout, deleteMyAccount, updateMyProfile, myAuthorizedApps, revokeAuthorizedApp, mySessions, endMySession, signOutEverywhere, createPersonalAccessToken, mySignInMethods, connectSignInMethod, disconnectSignInMethod, myFactors, beginStepUp, completeStepUp, beginFactorEnrollment, completeFactorEnrollment, removeFactor, makeRecoveryCodes, myOrganizations, registerOrganization, saveSession, clearSession, getSessionToken, getSessionUser, signInWithPassword, signUpWithPassword, signInWithOTP, resetPasswordAndSignIn, refreshSession, refreshSessionOnce, signOut, authedRequest, authedOp, requireAuth, } from './auth';
 export type { FoirAuthTokens, FoirUser, SessionAdapter, RequireAuthOptions, } from './auth';
 export { userAccess, getSessionAccess, hasRole, hasScope, requireRole, requireScope, FoirAccessDeniedError, } from './access';
 export type { FoirAccess, FoirAccessDenial } from './access';
 export { FoirAuthDowngradedError, FoirSessionExpiredError } from '../graphql/foir-request';
 export { AUTH_OPS } from './ops';
 export type { AuthOpName, AuthOpOptions } from './ops';
-export { hostedLoginUrl, hostedLogoutUrl, fetchHostedSession } from './hosted';
-export type { HostedLoginConfig, HostedSession, HostedSessionResult } from './hosted';
+export { hostedLoginUrl, hostedLogoutUrl, fetchHostedSession, hostedSignInNoticeOf } from './hosted';
+export type { HostedLoginConfig, HostedSession, HostedSessionResult, HostedSignInNotice } from './hosted';
 export { createFoirSessionClient } from './session-client';
 export type { FoirSessionClient, FoirSessionConfig, FoirSessionUser, } from './session-client';
-export type { AuthResult, ProviderLoginResult, AuthProviderPublic, ProviderLoginInput, ProviderCallbackInput, ProviderOTPVerifyInput, SignupContext, SignupMode, WaitlistJoinResult, AuthConfig, AuthConfigProvider, DefaultAuthProvider, CurrentUser, ProviderToken, DeleteAccountResult, MyOrganization, MyProfile, MyProfileChange, AuthorizedApp, MySession, NewPersonalAccessToken, MySignInMethod, MyFactor, StepUp, FactorEnrollment, } from './operations';
+export type { AuthResult, ProviderLoginResult, AuthProviderPublic, ProviderLoginInput, ProviderCallbackInput, ProviderOTPVerifyInput, SignupContext, SignupMode, WaitlistJoinResult, AuthConfig, AuthConfigProvider, DefaultAuthProvider, CurrentUser, ProviderToken, ProviderTokenRefresh, DeleteAccountResult, MyOrganization, MyProfile, MyProfileChange, AuthorizedApp, MySession, NewPersonalAccessToken, MySignInMethod, MyFactor, StepUp, FactorEnrollment, } from './operations';

package/dist/auth/operations.d.ts

@@ -123,18 +123,33 @@ export interface CurrentUser {
     /** ISO-8601. */
     createdAt: string;
 }
+/** What a provider token read did about the token's freshness. */
+export type ProviderTokenRefresh = 'NOT_ATTEMPTED' | 'REFRESHED' | 'FAILED' | 'HELD_BACK';
 /**
- * A stored upstream provider token for the calling user. `null` when there
- * is no user token on the request, or none stored for that provider.
+ * A stored upstream provider token for the calling user. `myProviderToken`
+ * answers `null` when there is no user token on the request, and
+ * `linked: false` when the user has none stored for that provider.
  */
 export interface ProviderToken {
     providerKey: string;
-    accessToken: string;
+    /** False when the user has no token for the provider; every token field is then null. */
+    linked: boolean;
+    accessToken: string | null;
     refreshToken: string | null;
     /** ISO-8601. */
     expiresAt: string | null;
     /** Space-separated provider scopes, as the provider issued them. */
     scopes: string | null;
+    /**
+     * What the read did: `REFRESHED` renewed it, `FAILED` tried and served the
+     * stored token, `HELD_BACK` had tried within the last minute, and
+     * `NOT_ATTEMPTED` found it fresh or had nothing to renew it with.
+     */
+    refresh: ProviderTokenRefresh | null;
+    /** Where a failed refresh failed, such as `"refresh grant"`. */
+    refreshFailure: string | null;
+    /** Only the user signing in with the provider again mends the connection. */
+    reauthenticate: boolean;
 }
 /** What a self-serve account deletion removed. */
 export interface DeleteAccountResult {
@@ -205,7 +220,10 @@ export interface MyFactor {
     kind: string;
     /** What {@link removeFactor} takes. */
     id: string;
-    /** A security key's or passkey's name. */
+    /**
+     * A security key's or passkey's name. A passkey made on the project's own
+     * login domain is named by that domain, the only one it signs in on.
+     */
     name: string | null;
     /** ISO-8601. */
     addedAt: string | null;
@@ -314,6 +332,12 @@ export interface MyOrganization {
      * sees part of what the next request is allowed and not the whole of it.
      */
     role: MyOrganizationRole | null;
+    /**
+     * Where the list goes on from: pass the last entry's cursor as `after` to
+     * read the next page. Null on an entry no list gave, such as the one
+     * `registerOrganization` returns.
+     */
+    cursor: string | null;
 }
 /** A role as `myOrganizations` reports it: enough to match a policy and to render. */
 export interface MyOrganizationRole {