@foir/sdk 0.21.0 → 0.22.0

package/dist/auth/access.d.ts

@@ -1,5 +1,5 @@
 /**
- * What the signed-in customer may see: the roles they hold and the scopes those
+ * What the signed-in user may see: the roles they hold and the scopes those
  * roles resolve to, as the platform resolved them for the request that asked.
  *
  * Use it to decide what to SHOW: a staff menu, an edit button. It guards
@@ -14,48 +14,48 @@ import { type AuthOpOptions } from './ops';
 import { type SessionAdapter } from './auth';
 import type { FoirEnv } from '../graphql/foir-request';
 /**
- * A signed-in customer's access, as the platform resolved it. Plain data, so it
+ * A signed-in user's access, as the platform resolved it. Plain data, so it
  * can be returned from a loader or a server component and read on the other
  * side with {@link hasRole} and {@link hasScope}.
  */
 export interface FoirAccess {
-    /** The signed-in customer. */
-    customerId: string;
+    /** The signed-in user. */
+    userId: string;
     /**
-     * The keys of the roles the customer holds here, now: across the project, and
+     * The keys of the roles the user holds here, now: across the project, and
      * in the organization they stand in. An empty list means they hold none.
      *
      * `null` means the platform did not say, which is not the same thing: treat it
      * as not known, never as "holds no role". {@link hasRole} answers false for
      * it, and {@link requireRole} refuses with `roles_unknown` so an outage is not
-     * mistaken for a customer who is not staff.
+     * mistaken for a user who holds no role.
      */
     roles: string[] | null;
     /**
-     * Everything the customer may do through this key: the set the platform's own
+     * Everything the user may do through this key: the set the platform's own
      * checks read for the request. Ask it with {@link hasScope} and not by looking
      * for a string, because a wider grant covers a narrower one.
      */
     scopes: string[];
 }
 /**
- * The access of the customer a token belongs to, or `null` when the request
- * carries no customer. Pass the customer's access token as
+ * The access of the user a token belongs to, or `null` when the request
+ * carries no user. Pass the user's access token as
  * `options.bearerToken`.
  */
-export declare function customerAccess(env: FoirEnv, options?: AuthOpOptions): Promise<FoirAccess | null>;
+export declare function userAccess(env: FoirEnv, options?: AuthOpOptions): Promise<FoirAccess | null>;
 /**
- * The access of the session's customer, or `null` when nobody is signed in.
+ * The access of the session's user, or `null` when nobody is signed in.
  * Renews a lapsed session once, as every signed-in read does.
  */
 export declare function getSessionAccess(adapter: SessionAdapter, env: FoirEnv): Promise<FoirAccess | null>;
 /**
- * Whether the customer holds the role with this key. False when nobody is
+ * Whether the user holds the role with this key. False when nobody is
  * signed in, and false when their roles are not known.
  */
 export declare function hasRole(access: FoirAccess | null | undefined, key: string): boolean;
 /**
- * Whether the customer's scopes cover this one, by the platform's rule: a wider
+ * Whether the user's scopes cover this one, by the platform's rule: a wider
  * reach covers a narrower one (`records:read.all` covers `records:read`), a
  * grant for every model covers one model (`records:write` covers
  * `records:write:post`), and never the other way round. A scope that is not a
@@ -66,11 +66,11 @@ export declare function hasScope(access: FoirAccess | null | undefined, scope: s
 export type FoirAccessDenial = 
 /** Nobody is signed in. */
 'signed_out'
-/** The customer does not hold the role. */
+/** The user does not hold the role. */
  | 'role_not_held'
-/** The platform did not say which roles the customer holds. */
+/** The platform did not say which roles the user holds. */
  | 'roles_unknown'
-/** The customer's scopes do not cover the scope. */
+/** The user's scopes do not cover the scope. */
  | 'scope_not_held';
 /**
  * What {@link requireRole} and {@link requireScope} throw. Catch it by class or
@@ -90,16 +90,16 @@ export declare class FoirAccessDeniedError extends Error {
     });
 }
 /**
- * Require a signed-in customer who holds the role with this key, in a server
+ * Require a signed-in user who holds the role with this key, in a server
  * route or a loader. Returns their access; throws
  * {@link FoirAccessDeniedError} otherwise.
  *
- * This keeps a page from rendering for the wrong customer. It is not what
+ * This keeps a page from rendering for the wrong user. It is not what
  * protects the data: the platform checks every request the page then makes.
  */
 export declare function requireRole(adapter: SessionAdapter, env: FoirEnv, key: string): Promise<FoirAccess>;
 /**
- * Require a signed-in customer whose scopes cover this one, by the rule
+ * Require a signed-in user whose scopes cover this one, by the rule
  * {@link hasScope} reads. Returns their access; throws
  * {@link FoirAccessDeniedError} otherwise.
  */

package/dist/auth/auth.d.ts

@@ -1,11 +1,12 @@
 /**
- * Foir customer auth — framework-agnostic flows, token lifecycle, and guards.
+ * Foir sign-in for your app's users: framework-agnostic flows, token
+ * lifecycle, and guards.
  *
  * Session I/O is injected via {@link SessionAdapter} (no Hydrogen/React-Router
  * coupling). Pre-login flows authenticate with the project `x-api-key`;
- * post-login reads add the customer bearer. The project-specific profile (e.g.
- * `isAdmin`) is resolved by a consumer-supplied `resolveUser` — the SDK never
- * hardcodes the per-project customer profile shape.
+ * post-login reads add the user's bearer. Anything project-specific about the
+ * user (a profile record, say) is resolved by a consumer-supplied
+ * `resolveUser`: the SDK never hardcodes a per-project profile shape.
  *
  * TRANSPORT. Every flow below addresses the server's generated `auth` namespace
  * through `./ops`, which is `@foir/sdk/data`'s op transport. This module holds
@@ -16,23 +17,17 @@
  */
 import { type FoirEnv } from '../graphql/foir-request';
 import { type AuthOpName, type AuthOpOptions } from './ops';
-import { type AuthConfig, type AuthProviderPublic, type CurrentUser, type CustomerAuthResult, type DefaultAuthProvider, type DeleteAccountResult, type MyOrganization, type SelectedOrganization, 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, type WaitlistJoinResult } from './operations';
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
 /** An access token + its rotating refresh token. */
 export interface FoirAuthTokens {
     token: string;
     refreshToken: string;
 }
-/** The customer identity carried by an auth result. */
-export interface FoirCustomer {
-    id: string;
-    email: string;
-}
-/** The resolved customer for a guarded surface. */
+/** The signed-in user an auth result and a session carry. */
 export interface FoirUser {
     id: string;
     email: string;
-    isAdmin: boolean;
 }
 /**
  * Injected session store. Methods may be sync or async so consumers can plug
@@ -44,39 +39,70 @@ export interface SessionAdapter {
     unset(key: string): void | Promise<void>;
 }
 /** Login with email + password. Requires the project to have passwords enabled. */
-export declare function customerLogin(env: FoirEnv, vars: {
+export declare function login(env: FoirEnv, vars: {
     email: string;
     password: string;
-}): Promise<CustomerAuthResult>;
-/** Register a new customer with email + password. */
-export declare function customerRegister(env: FoirEnv, vars: {
+}): Promise<AuthResult>;
+/** Register a new user with email + password. */
+export declare function register(env: FoirEnv, vars: {
     email: string;
     password: string;
-}): Promise<CustomerAuthResult>;
-/** Request a one-time password be emailed to the customer. */
-export declare function customerRequestOTP(env: FoirEnv, email: string): Promise<boolean>;
+}): Promise<AuthResult>;
+/** Request a one-time password be emailed to the user. */
+export declare function requestOTP(env: FoirEnv, email: string): Promise<boolean>;
 /** Complete an OTP login. */
-export declare function customerLoginOTP(env: FoirEnv, vars: {
+export declare function loginWithOTP(env: FoirEnv, vars: {
     email: string;
     otp: string;
-}): Promise<CustomerAuthResult>;
+}): Promise<AuthResult>;
 /** Rotate an access token using a refresh token. */
-export declare function customerRefreshToken(env: FoirEnv, refreshToken: string): Promise<CustomerAuthResult>;
+export declare function refreshTokens(env: FoirEnv, refreshToken: string): Promise<AuthResult>;
 /**
  * Initiate provider (OAuth/OIDC) login — returns a `redirectUrl` to send the
  * user to, or an inline `token` for non-redirect providers.
  */
-export declare function customerLoginWithProvider(env: FoirEnv, input: ProviderLoginInput): Promise<ProviderLoginResult>;
+export declare function loginWithProvider(env: FoirEnv, input: ProviderLoginInput): Promise<ProviderLoginResult>;
 /** Complete a provider login from the OAuth callback (`code`/`state`). */
-export declare function customerProviderCallback(env: FoirEnv, input: ProviderCallbackInput): Promise<CustomerAuthResult>;
+export declare function providerCallback(env: FoirEnv, input: ProviderCallbackInput): Promise<AuthResult>;
 /** Verify an OTP issued by an external provider. */
-export declare function customerProviderVerifyOTP(env: FoirEnv, input: ProviderOTPVerifyInput): Promise<CustomerAuthResult>;
+export declare function providerVerifyOTP(env: FoirEnv, input: ProviderOTPVerifyInput): Promise<AuthResult>;
+/**
+ * Why a provider sign-in did not finish, as the platform said it: a stable code
+ * your app shows its own words for (`signup_closed`, `provider_named_no_address`,
+ * `account_unavailable`, ...). When the code is `link_code_sent`, the sign-in
+ * named an address somebody already holds, through a provider that does not
+ * prove the address is theirs, and a code was sent to it: `pending` names the
+ * wait, and {@link confirmProviderLink} finishes the sign-in with that code.
+ * Null for any other failure.
+ */
+export declare function providerSignInRefusalOf(error: unknown): {
+    code: string;
+    pending?: 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
+ * {@link providerSignInRefusalOf}.
+ */
+export declare function confirmProviderLink(env: FoirEnv, input: {
+    pending: string;
+    code: string;
+}): Promise<AuthResult>;
+/**
+ * Send a new code for a provider sign-in that is waiting for one. The new code
+ * replaces the one before, and the answer names the new wait.
+ */
+export declare function resendProviderLinkCode(env: FoirEnv, input: {
+    pending: string;
+}): Promise<{
+    pending: string;
+}>;
 /** List the project's configured auth providers (for a login UI). */
 export declare function getAuthProviders(env: FoirEnv): Promise<AuthProviderPublic[]>;
 /**
  * Read the project's public auth configuration — which built-in methods are
  * enabled and which external providers to offer. This is what a login screen
- * renders itself from, before any customer token exists.
+ * renders itself from, before any user token exists.
  */
 export declare function getAuthConfig(env: FoirEnv): Promise<AuthConfig>;
 /**
@@ -85,55 +111,55 @@ export declare function getAuthConfig(env: FoirEnv): Promise<AuthConfig>;
  */
 export declare function getDefaultAuthProvider(env: FoirEnv): Promise<DefaultAuthProvider | null>;
 /**
- * Read the project's customer signup mode (public/restricted/waitlist/closed)
+ * Read the project's signup mode (public/restricted/waitlist/closed)
  * so a self-hosted frontend can render the right signup surface proactively.
  */
-export declare function customerSignupContext(env: FoirEnv): Promise<SignupContext>;
+export declare function signupContext(env: FoirEnv): Promise<SignupContext>;
 /** Join the project's signup waitlist. The project must be in waitlist mode. */
-export declare function customerJoinWaitlist(env: FoirEnv, email: string): Promise<WaitlistJoinResult>;
+export declare function joinWaitlist(env: FoirEnv, email: string): Promise<WaitlistJoinResult>;
 /**
  * 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.
  */
-export declare function customerRequestPasswordReset(env: FoirEnv, email: string): Promise<boolean>;
+export declare function requestPasswordReset(env: FoirEnv, email: string): Promise<boolean>;
 /**
  * Redeem an emailed reset token and set a new password. Returns a fresh session
- * — resetting a password signs the customer in — so pair it with
+ * (resetting a password signs the user in), so pair it with
  * {@link saveSession}, or use {@link resetPasswordAndSignIn} which does both.
  */
-export declare function customerResetPassword(env: FoirEnv, vars: {
+export declare function resetPassword(env: FoirEnv, vars: {
     token: string;
     newPassword: string;
-}): Promise<CustomerAuthResult>;
+}): Promise<AuthResult>;
 /** Redeem an emailed verification token. */
-export declare function customerVerifyEmail(env: FoirEnv, token: string): Promise<boolean>;
+export declare function verifyEmail(env: FoirEnv, token: string): Promise<boolean>;
 /**
- * Change the calling customer's password. Requires the current password as well
+ * 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.
  */
-export declare function customerUpdatePassword(env: FoirEnv, vars: {
+export declare function updatePassword(env: FoirEnv, vars: {
     currentPassword: string;
     newPassword: string;
 }, options?: AuthOpOptions): Promise<boolean>;
 /**
- * The calling customer, or `null` when the request carried no customer token.
+ * The calling user, or `null` when the request carried no user token.
  * An absent session is an answer rather than a failure, so this does not throw.
  */
 export declare function currentUser(env: FoirEnv, options?: AuthOpOptions): Promise<CurrentUser | null>;
 /**
- * The stored upstream provider token for the calling customer, refreshed
+ * The stored upstream provider token for the calling user, refreshed
  * transparently by the server when it has expired. `null` when there is no
- * customer token on the request or none stored for that provider.
+ * user token on the request or none stored for that provider.
  */
 export declare function myProviderToken(env: FoirEnv, providerKey: string, options?: AuthOpOptions): 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.
  */
-export declare function customerLogout(env: FoirEnv, options?: AuthOpOptions): Promise<boolean>;
+export declare function logout(env: FoirEnv, options?: AuthOpOptions): Promise<boolean>;
 /**
- * Delete the calling customer's account and their owned records and files.
+ * Delete the calling user's account and their owned records and files.
  * Irreversible. `password` is required for password accounts and omitted for
  * provider-only ones; the server enforces the actual re-auth gate and fails
  * closed, so omitting it is refused rather than allowed.
@@ -143,60 +169,140 @@ export declare function deleteMyAccount(env: FoirEnv, vars: {
     password?: string;
 }, options?: AuthOpOptions): Promise<DeleteAccountResult>;
 /**
- * The organizations this operator may stand in.
+ * Change the calling user's own name, picture or language. It asks no
+ * permission: these are theirs.
+ */
+export declare function updateMyProfile(env: FoirEnv, change: MyProfileChange, options?: AuthOpOptions): Promise<MyProfile>;
+/**
+ * The apps the calling user has agreed may act for them, and what each may
+ * carry: the list an account page shows with a way to take each one back.
+ */
+export declare function myAuthorizedApps(env: FoirEnv, options?: AuthOpOptions): Promise<AuthorizedApp[]>;
+/**
+ * Take back an app's authority to act for the calling user. Its tokens for
+ * them stop working at once, and it has to ask them again.
+ */
+export declare function revokeAuthorizedApp(env: FoirEnv, id: string, options?: AuthOpOptions): Promise<boolean>;
+/** Where the calling user is signed in, and the personal access tokens they hold. */
+export declare function mySessions(env: FoirEnv, options?: AuthOpOptions): Promise<MySession[]>;
+/** Sign the calling user out of one session, or revoke one of their tokens, by its id. */
+export declare function endMySession(env: FoirEnv, id: string, options?: AuthOpOptions): Promise<boolean>;
+/**
+ * Sign the calling user out of every session and every app, and answer how
+ * many sessions ended. Their personal access tokens stay. `keepThis` keeps the
+ * session making the request.
+ */
+export declare function signOutEverywhere(env: FoirEnv, vars?: {
+    keepThis?: boolean;
+}, options?: AuthOpOptions): Promise<number>;
+/**
+ * Make a personal access token for the calling user: a standing credential
+ * they present beside the app's key, as `Authorization: Bearer`. Its value is
+ * answered here once.
+ */
+export declare function createPersonalAccessToken(env: FoirEnv, vars: {
+    name: string;
+    expiresInDays: number;
+}, options?: AuthOpOptions): Promise<NewPersonalAccessToken>;
+/** The providers the calling user signs in with. */
+export declare function mySignInMethods(env: FoirEnv, options?: AuthOpOptions): Promise<MySignInMethod[]>;
+/**
+ * Start connecting one of the project's providers to the calling user's
+ * account, and answer the provider's address to send the browser to. It comes
+ * back to `returnTo` with `connected` or `connect_error` added.
+ */
+export declare function connectSignInMethod(env: FoirEnv, vars: {
+    provider: string;
+    returnTo: string;
+}, options?: AuthOpOptions): Promise<string>;
+/** Disconnect a provider from the calling user's account. */
+export declare function disconnectSignInMethod(env: FoirEnv, provider: string, options?: AuthOpOptions): Promise<boolean>;
+/** The second factors, passkeys and recovery codes the calling user holds. */
+export declare function myFactors(env: FoirEnv, options?: AuthOpOptions): Promise<MyFactor[]>;
+/**
+ * Begin proving a second factor with the calling user's password.
+ * {@link completeStepUp} finishes it; for a user who holds none, the answer's
+ * `elevatedHandle` is already the proof.
+ */
+export declare function beginStepUp(env: FoirEnv, password: string, options?: AuthOpOptions): Promise<StepUp>;
+/**
+ * Prove a second factor with exactly one of a passkey's or security key's
+ * assertion, an authenticator app's code or a recovery code, which is then
+ * spent. The session making the request counts as two factors from here, and
+ * the answer is an elevated handle for one change to the user's factors in
+ * the next ten minutes.
+ */
+export declare function completeStepUp(env: FoirEnv, vars: {
+    handle: string;
+    webauthnAssertionJson?: string;
+    totpCode?: string;
+    recoveryCode?: string;
+}, options?: AuthOpOptions): Promise<string>;
+/**
+ * Begin adding `totp` (an authenticator app), `webauthn` (a security key held
+ * as a second factor) or `passkey` (a passkey that signs the user in on its
+ * own), with the `elevatedHandle` {@link beginStepUp} or
+ * {@link completeStepUp} answered.
+ */
+export declare function beginFactorEnrollment(env: FoirEnv, vars: {
+    method: 'webauthn' | 'totp' | 'passkey';
+    elevatedHandle: string;
+}, options?: AuthOpOptions): Promise<FactorEnrollment>;
+/**
+ * Finish adding a second factor, with the `navigator.credentials.create`
+ * result or the authenticator app's code.
+ */
+export declare function completeFactorEnrollment(env: FoirEnv, vars: {
+    handle: string;
+    webauthnAttestationJson?: string;
+    totpCode?: string;
+    name?: string;
+}, options?: AuthOpOptions): Promise<boolean>;
+/** Remove one of the calling user's factors, with an elevated handle from {@link completeStepUp}. */
+export declare function removeFactor(env: FoirEnv, vars: {
+    elevatedHandle: string;
+    kind: string;
+    id: string;
+}, options?: AuthOpOptions): Promise<boolean>;
+/**
+ * Make the calling user new recovery codes, with an elevated handle from
+ * {@link completeStepUp}. They replace any held and are answered here once.
+ */
+export declare function makeRecoveryCodes(env: FoirEnv, elevatedHandle: string, options?: AuthOpOptions): Promise<string[]>;
+/**
+ * The organizations this user may stand in.
  *
- * Answered from the CALLING customer's own memberships: each organization they
- * hold one in and every organization beneath it, so an operator is shown
- * exactly the set they can stand in, and a customer with no memberships sees
- * an empty list rather than a refusal. Requires the customer bearer; it is not
- * the project's inventory and cannot be used as one.
+ * 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.
+ *
+ * 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
+ * there. The reverse never works: a membership at a branch stands in no
+ * ancestor and in no sibling branch, and a request naming either is refused as
+ * not-found, the same answer an organization that does not exist gets.
+ * {@link MyOrganization.role} names ONE of the roles that apply where the
+ * person stands (the membership held in the organization itself, when there is
+ * one); their authority there is the union of every membership that reaches
+ * it, together with their own roles in the project.
  */
 export declare function myOrganizations(env: FoirEnv, vars?: {
     first?: number;
     after?: string;
 }, options?: AuthOpOptions): Promise<MyOrganization[]>;
-/**
- * Stand in one of them, for this customer, until they choose otherwise.
- *
- * Set once — not per call. The selection is stored against the customer and
- * resolved into the claim on every subsequent request, so nothing downstream
- * takes an org argument. Pass an empty `orgId` to clear it and return to the
- * project-shared view.
- *
- * The server authorises the choice against a live membership and refuses
- * otherwise, so a caller cannot select their way into an organization they do
- * not run.
- *
- * A MEMBERSHIP REACHES DOWNWARD, which is what "a live membership" means now
- * that organizations nest. Someone who is a member of an organization may stand in any
- * organization BENEATH it without holding a row of their own there, and
- * {@link myOrganizations} offers exactly that set — so any id it returned can
- * be passed here. The reverse never works: a membership at a branch stands in
- * no ancestor and in no sibling branch, and both are refused as not-found,
- * which is the same answer an organization that does not exist gets.
- *
- * WHAT STANDING THERE MEANS is every membership that reaches the organization
- * selected. Reach a client through a membership above it and the role shown is
- * that membership's; authority is the union of every membership that reaches
- * it, together with the customer's own roles in the project.
- * {@link MyOrganization.role} names ONE of those roles (the membership held in
- * the organization itself, when there is one), so it is part of what the next
- * request resolves and not the whole of it.
- */
-export declare function selectOrganization(env: FoirEnv, vars: {
-    orgId: string;
-}, options?: AuthOpOptions): Promise<SelectedOrganization>;
 /**
  * Found an organization, as its first member.
  *
  * The caller decides the NAME and, optionally, where it hangs — and nothing
- * else. The founder is the customer behind the bearer, the id is minted
+ * 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
- * (`operatorSignupRole`). The server creates the organization and that one
+ * (`organizationSignupRole`). The server creates the organization and that one
  * membership together.
  *
- * `parentId` FOUNDS A CHILD, which is what lets your own customer create its own
+ * `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
  * franchise adding a branch. It is resolved against the caller's own
  * MEMBERSHIPS, not merely against the project: on this lane "an organization
@@ -204,59 +310,59 @@ export declare function selectOrganization(env: FoirEnv, vars: {
  * not-found. Omit it to found a root, which is what every registration did
  * before organizations nested.
  *
- * Exists on the wire only while the project's `operatorSignupEnabled` setting
+ * 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
- * included, so the application can go straight to {@link selectOrganization}.
+ * included, so the application can name it on its next request.
  */
 export declare function registerOrganization(env: FoirEnv, vars: {
     name: string;
     parentId?: string;
 }, options?: AuthOpOptions): Promise<MyOrganization>;
 /**
- * Persist an auth result to the session; returns the customer identity.
+ * Persist an auth result to the session; returns the signed-in user.
  *
- * A result that names no customer keeps the identity already stored. A refresh
+ * A result that names no user keeps the identity already stored. A refresh
  * rotates the tokens of a session that already knows who it belongs to, and a
- * platform that answers a refresh without the customer must not blank that:
+ * platform that answers a refresh without the user must not blank that:
  * {@link requireAuth} reads the stored identity, so a valid token beside an
  * empty identity reads as signed out.
  */
-export declare function saveSession(adapter: SessionAdapter, result: CustomerAuthResult): Promise<FoirCustomer>;
+export declare function saveSession(adapter: SessionAdapter, result: AuthResult): Promise<FoirUser>;
 /** Clear all Foir auth keys from the session. */
 export declare function clearSession(adapter: SessionAdapter): Promise<void>;
 /** Read the stored access token (null when signed out). */
 export declare function getSessionToken(adapter: SessionAdapter): Promise<string | null>;
-/** Read the stored customer identity (null when signed out). */
-export declare function getSessionCustomer(adapter: SessionAdapter): Promise<FoirCustomer | null>;
+/** Read the stored user (null when signed out). */
+export declare function getSessionUser(adapter: SessionAdapter): Promise<FoirUser | null>;
 /** Login with email + password and persist the session. */
-export declare function loginWithPassword(adapter: SessionAdapter, env: FoirEnv, vars: {
+export declare function signInWithPassword(adapter: SessionAdapter, env: FoirEnv, vars: {
     email: string;
     password: string;
-}): Promise<FoirCustomer>;
+}): Promise<FoirUser>;
 /** Register with email + password and persist the session. */
-export declare function registerWithPassword(adapter: SessionAdapter, env: FoirEnv, vars: {
+export declare function signUpWithPassword(adapter: SessionAdapter, env: FoirEnv, vars: {
     email: string;
     password: string;
-}): Promise<FoirCustomer>;
+}): Promise<FoirUser>;
 /** Complete an OTP login and persist the session. */
-export declare function loginWithOTP(adapter: SessionAdapter, env: FoirEnv, vars: {
+export declare function signInWithOTP(adapter: SessionAdapter, env: FoirEnv, vars: {
     email: string;
     otp: string;
-}): Promise<FoirCustomer>;
+}): Promise<FoirUser>;
 /**
  * Complete a forgot-password flow: redeem the emailed token, set the new
  * password, and persist the session the server mints. The peer of
- * {@link loginWithPassword} for the branch where the customer cannot log in.
+ * {@link signInWithPassword} for the branch where the user cannot log in.
  */
 export declare function resetPasswordAndSignIn(adapter: SessionAdapter, env: FoirEnv, vars: {
     token: string;
     newPassword: string;
-}): Promise<FoirCustomer>;
+}): Promise<FoirUser>;
 /**
  * End the session on both sides: revoke it server-side, then clear local state.
  *
- * The local clear happens even when the server call fails. A customer who
+ * The local clear happens even when the server call fails. Someone who
  * pressed sign-out and got a network error must not be left holding a session
  * on the device in front of them — the token expires on its own, and the
  * failure mode of clearing anyway (one orphaned provider token) is strictly
@@ -295,16 +401,18 @@ export declare function authedRequest<TData, TVariables>(adapter: SessionAdapter
  * management, which is the half a generated namespace does not give you.
  */
 export declare function authedOp<T>(adapter: SessionAdapter, env: FoirEnv, op: AuthOpName, args?: Record<string, unknown>): Promise<T>;
-export interface RequireAuthOptions {
+export interface RequireAuthOptions<TUser = FoirUser> {
     /**
-     * Resolve the full {@link FoirUser} (including the project-specific
-     * `isAdmin`) from the session identity. Typically runs the project's
-     * `myProfile` query via {@link authedRequest}. Defaults to `isAdmin: false`.
+     * Resolve what the guarded surface needs about the user from the session:
+     * typically the project's own profile record, read through
+     * {@link authedRequest}. Without it the guard answers the {@link FoirUser}
+     * the session holds. What the user may do is a role or a scope: guard on
+     * those with {@link requireRole} and {@link requireScope}.
      */
     resolveUser?: (ctx: {
         token: string;
-        customer: FoirCustomer;
-    }) => FoirUser | Promise<FoirUser>;
+        user: FoirUser;
+    }) => TUser | Promise<TUser>;
     /**
      * Called when there's no valid session — throw your framework's redirect
      * (e.g. `throw redirect(loginUrl)`). Must not return.
@@ -319,14 +427,8 @@ export interface RequireAuthOptions {
     env?: FoirEnv;
 }
 /**
- * Require a signed-in customer. Resolves the {@link FoirUser} via
- * `resolveUser` (or a minimal identity), or invokes `onUnauthenticated` when
- * there's no session.
+ * Require a signed-in user. Answers what `resolveUser` resolves (or the
+ * session's {@link FoirUser}), or invokes `onUnauthenticated` when there's no
+ * session.
  */
-export declare function requireAuth(adapter: SessionAdapter, options: RequireAuthOptions): Promise<FoirUser>;
-export interface RequireAdminOptions extends RequireAuthOptions {
-    /** Called when the user is authenticated but not an admin. Must not return. */
-    onForbidden: () => never | Promise<never>;
-}
-/** Require a signed-in customer who is also an admin. */
-export declare function requireAdmin(adapter: SessionAdapter, options: RequireAdminOptions): Promise<FoirUser>;
+export declare function requireAuth<TUser = FoirUser>(adapter: SessionAdapter, options: RequireAuthOptions<TUser>): Promise<TUser>;