@foir/sdk 0.22.0 → 0.24.0

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

@@ -17,7 +17,7 @@
  */
 import { type FoirEnv } from '../graphql/foir-request';
 import { type AuthOpName, type AuthOpOptions } from './ops';
-import { type AuthConfig, type AuthProviderPublic, type CurrentUser, type AuthResult, type DefaultAuthProvider, type AuthorizedApp, type DeleteAccountResult, type MyOrganization, type MyProfile, type MyProfileChange, type MySession, type MyFactor, type StepUp, type FactorEnrollment, type MySignInMethod, type NewPersonalAccessToken, type ProviderCallbackInput, type ProviderLoginInput, type ProviderLoginResult, type ProviderOTPVerifyInput, type ProviderToken, type SignupContext, type WaitlistJoinResult } from './operations';
+import { type AuthConfig, type AuthProviderPublic, type CurrentUser, type AuthResult, type DefaultAuthProvider, type AuthorizedApp, type DeleteAccountResult, type MyOrganization, type MyProfile, type MyProfileChange, type MySession, type MyFactor, type StepUp, type FactorEnrollment, type MySignInMethod, type NewPersonalAccessToken, type ProviderCallbackInput, type ProviderLoginInput, type ProviderLoginResult, type ProviderOTPVerifyInput, type ProviderToken, type SignupContext } from './operations';
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
 /** An access token + its rotating refresh token. */
 export interface FoirAuthTokens {
@@ -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
@@ -115,14 +125,26 @@ export declare function getDefaultAuthProvider(env: FoirEnv): Promise<DefaultAut
  * so a self-hosted frontend can render the right signup surface proactively.
  */
 export declare function signupContext(env: FoirEnv): Promise<SignupContext>;
-/** Join the project's signup waitlist. The project must be in waitlist mode. */
-export declare function joinWaitlist(env: FoirEnv, email: string): Promise<WaitlistJoinResult>;
+/**
+ * Join the project's sign-up waitlist. The project must be in waitlist mode.
+ * Resolves `true` for every address: the server answers identically whether
+ * the address was queued, was already let in, or already has an account, on
+ * purpose, so this endpoint cannot be used to test what an address holds. What
+ * differs is only the email the address is sent.
+ */
+export declare function joinWaitlist(env: FoirEnv, email: string): Promise<boolean>;
 /**
  * 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
@@ -132,8 +154,6 @@ export declare function resetPassword(env: FoirEnv, vars: {
     token: string;
     newPassword: string;
 }): Promise<AuthResult>;
-/** Redeem an emailed verification token. */
-export declare function verifyEmail(env: FoirEnv, token: string): Promise<boolean>;
 /**
  * Change the calling user's password. Requires the current password as well
  * as the bearer, so a stolen token alone cannot take the account over.
@@ -148,14 +168,25 @@ 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 token of the provider the calling user signed in through, kept for the
+ * sign-in the request belongs to and 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` with `reauthenticate: true` when
+ * nothing is kept for this sign-in (it did not pass through the provider, or
+ * its token was ended), and the user signs in through the provider again.
+ *
+ * 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.
+ * End the sign-in's provider tokens server-side: this device's, and no other
+ * device's. This does NOT clear local session state — {@link signOut} is the
+ * pairing that does both.
  */
 export declare function logout(env: FoirEnv, options?: AuthOpOptions): Promise<boolean>;
 /**
@@ -275,8 +306,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,21 +327,27 @@ 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
  * membership together.
  *
  * `parentId` FOUNDS A CHILD, which is what lets the people you serve create their own
- * sub-tenants with no administrator in the loop — a reseller adding a client, a
+ * sub-tenants with no manager in the loop — a reseller adding a client, a
  * franchise adding a branch. It is resolved against the caller's own
  * MEMBERSHIPS, not merely against the project: on this lane "an organization
  * that exists" is not the question, "one you operate" is, and anything else is
  * 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 +356,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

@@ -21,6 +21,11 @@ export interface HostedLoginConfig {
     sessionPath?: string;
     /** RP-initiated logout path on the front door. Default `/session/end-session`. */
     endSessionPath?: string;
+    /**
+     * The app the bearer is for, when it is not the app the login domain fronts.
+     * Default: the domain's own app.
+     */
+    clientId?: string;
 }
 /**
  * Build the redirect URL to the hosted front door, forwarding a best-effort
@@ -127,3 +132,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, 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, 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

@@ -76,13 +76,6 @@ export type SignupMode = 'PUBLIC' | 'RESTRICTED' | 'WAITLIST' | 'CLOSED';
 export interface SignupContext {
     signupMode: SignupMode;
 }
-/** The queued (or existing pending) entry a waitlist join returns. */
-export interface WaitlistJoinResult {
-    id: string;
-    email: string;
-    /** Waitlist lifecycle status; PENDING on a fresh join. */
-    status: string;
-}
 /** One provider as it appears inside {@link AuthConfig}. */
 export interface AuthConfigProvider {
     key: string;
@@ -123,18 +116,39 @@ 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.
+ * The token of the provider the calling user signed in through. It belongs to
+ * the sign-in that obtained it: a sign-in on another device keeps its own, and
+ * signing out ends it. `myProviderToken` answers `null` when there is no user
+ * token on the request, and `linked: false` with `reauthenticate: true` when
+ * nothing is kept for this sign-in.
  */
 export interface ProviderToken {
     providerKey: string;
-    accessToken: string;
+    /** False when nothing is kept for the sign-in the request belongs to; 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:
+     * nothing is kept for this sign-in, or the provider will not renew it. Show
+     * them the way to sign in through the provider, not an empty page.
+     */
+    reauthenticate: boolean;
 }
 /** What a self-serve account deletion removed. */
 export interface DeleteAccountResult {
@@ -205,7 +219,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 +331,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 {

package/dist/auth/ops.d.ts

@@ -55,7 +55,6 @@ export declare const AUTH_OPS: {
     readonly requestPasswordReset: "requestPasswordReset";
     readonly resetPassword: "resetPassword";
     readonly updatePassword: "updatePassword";
-    readonly verifyEmail: "verifyEmail";
     readonly deleteMyAccount: "deleteMyAccount";
     readonly updateMyProfile: "updateMyProfile";
     readonly myAuthorizedApps: "myAuthorizedApps";

package/dist/auth/session-client.d.ts

@@ -37,6 +37,11 @@ export interface FoirSessionConfig {
     sessionPath?: string;
     /** Logout path. Default `/session/logout`. */
     logoutPath?: string;
+    /**
+     * The app the bearer is for, when it is not the app the login domain fronts.
+     * Default: the domain's own app.
+     */
+    clientId?: string;
     /** Seconds before expiry to re-exchange. Default 60. */
     refreshSkewSeconds?: number;
     /**

package/dist/auth-session.js

@@ -5,8 +5,9 @@ var DEFAULT_REFRESH_SKEW_SECONDS = 60;
 var MIN_REFRESH_DELAY_MS = 5e3;
 var CSRF_HEADER = { "X-Foir-Session": "1" };
 function createFoirSessionClient(config) {
-  const sessionUrl = `${trimSlash(config.loginOrigin)}${config.sessionPath ?? DEFAULT_SESSION_PATH}`;
-  const logoutUrl = `${trimSlash(config.loginOrigin)}${config.logoutPath ?? DEFAULT_LOGOUT_PATH}`;
+  const forApp = config.clientId ? `?client_id=${encodeURIComponent(config.clientId)}` : "";
+  const sessionUrl = `${trimSlash(config.loginOrigin)}${config.sessionPath ?? DEFAULT_SESSION_PATH}${forApp}`;
+  const logoutUrl = `${trimSlash(config.loginOrigin)}${config.logoutPath ?? DEFAULT_LOGOUT_PATH}${forApp}`;
   const skewMs = (config.refreshSkewSeconds ?? DEFAULT_REFRESH_SKEW_SECONDS) * 1e3;
   let cached = null;
   let inflight = null;