@foir/sdk 0.5.0 → 0.8.0

package/README.md

@@ -24,6 +24,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/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` |
@@ -35,6 +36,99 @@ pnpm add yjs y-websocket    # for @foir/sdk/realtime
 
 ## Usage
 
+### Typed data client (no GraphQL, no codegen step)
+
+`@foir/sdk/data` executes over the same `/graphql` endpoint every other consumer
+uses — one execution surface, one executor, one set of scope checks, one response
+cache. What you skip is writing the documents: the client loads the selection
+tree `GET /v1/manifest` publishes for that op, applies your `include`/`omit`, and
+prints one.
+
+Printing a pre-resolved tree is string building, so the package still needs **no
+`graphql` dependency at all** — no `graphql`, no
+`@graphql-typed-document-node/core`, no `@graphql-codegen/*`, and no new peer.
+
+```ts
+import { createFoirClient } from '@foir/sdk/data';
+// generated by `foir types` from GET /v1/manifest
+import * as generated from './foir.generated';
+
+const foir = createFoirClient({
+  apiUrl: process.env.PLATFORM_API_URL!,   // a bare origin or the /graphql URL
+  apiKey: process.env.PLATFORM_API_KEY!,
+  generated,                               // the whole module: types, trees, version
+});
+
+const post = await foir.post.findUnique({
+  naturalKey: 'hello',
+  include: { author: true },   // relations opt in
+  omit: ['bodyRichtext'],      // drop the heavy field
+});
+
+const posts = await foir.post.findMany({ first: 10 });   // a Relay connection
+const hits  = await foir.ns.search.searchRecords({ query: 'shoes' });
+const other = await foir.raw('{ designTokens { colors } }');  // any document, any root field
+```
+
+**One import, no type parameter.** `generated` carries both halves of what
+`foir types` writes — the `FoirSchema` type and the runtime selection trees the
+documents are printed from — so `FoirSchema` is inferred rather than restated,
+and an artifact added to the generator later costs your call site nothing. A
+module missing one of those exports is a compile error naming it, not a quiet
+degrade: pass it whole, or do not pass it.
+
+The four fields it replaces (`schemaVersion`, `selections`,
+`namespaceSelections`, `selectionUnions`) still work and still win where both
+are given, so an existing client keeps compiling and behaving exactly as it did.
+
+**Scalars are always complete**, so `post.title` is typed present and *is*
+present — there is no partial-`select` footgun. `include` adds a relation key,
+`omit` removes a scalar, and polymorphic fields are discriminated unions on
+`__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
+call:
+
+```ts
+foir.post.create({ data });   // ✗ compile error under a pk_ key — not in its manifest
+```
+
+`generated` is optional. Without it — and without `selections` — the client
+fetches `GET /v1/manifest` once at first use and reads the same trees off it. A
+fallback, so a zero-codegen start works, at the cost of a round trip in front of
+the first query on every cold invocation. It says so, once, when it is built
+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`.
+
+`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
+the client carries no runtime schema to tell a namespace from a model. `ns` and
+`raw` are the only reserved names.
+
+Session-bound reads take a `bearerToken`, as a string or a function resolved per
+request:
+
+```ts
+const foir = createFoirClient({
+  apiUrl,
+  apiKey,
+  generated,
+  bearerToken: () => session.get('foir_access_token'),
+});
+```
+
+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.
+
 ### Typed GraphQL from a server loader
 
 `foirRequest` is a typed `fetch` wrapper, not a GraphQL client: it carries the

package/dist/auth/auth.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Foir customer auth — 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.
+ *
+ * TRANSPORT. Every flow below addresses the server's generated `auth` namespace
+ * through `./ops`, which is `@foir/sdk/data`'s op transport. This module holds
+ * no GraphQL documents and issues no requests of its own. What it does hold is
+ * the part a generated namespace does not give you and never could: where the
+ * tokens live, when they rotate, what a 401 means, and what to clear when a
+ * session ends.
+ */
+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 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. */
+export interface FoirUser {
+    id: string;
+    email: string;
+    isAdmin: boolean;
+}
+/**
+ * Injected session store. Methods may be sync or async so consumers can plug
+ * in a cookie session (Hydrogen/Remix), a KV store, etc.
+ */
+export interface SessionAdapter {
+    get(key: string): string | null | undefined | Promise<string | null | undefined>;
+    set(key: string, value: string): void | Promise<void>;
+    unset(key: string): void | Promise<void>;
+}
+/** Login with email + password. Requires the project to have passwords enabled. */
+export declare function customerLogin(env: FoirEnv, vars: {
+    email: string;
+    password: string;
+}): Promise<CustomerAuthResult>;
+/** Register a new customer with email + password. */
+export declare function customerRegister(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>;
+/** Complete an OTP login. */
+export declare function customerLoginOTP(env: FoirEnv, vars: {
+    email: string;
+    otp: string;
+}): Promise<CustomerAuthResult>;
+/** Rotate an access token using a refresh token. */
+export declare function customerRefreshToken(env: FoirEnv, refreshToken: string): Promise<CustomerAuthResult>;
+/**
+ * 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>;
+/** Complete a provider login from the OAuth callback (`code`/`state`). */
+export declare function customerProviderCallback(env: FoirEnv, input: ProviderCallbackInput): Promise<CustomerAuthResult>;
+/** Verify an OTP issued by an external provider. */
+export declare function customerProviderVerifyOTP(env: FoirEnv, input: ProviderOTPVerifyInput): Promise<CustomerAuthResult>;
+/** 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.
+ */
+export declare function getAuthConfig(env: FoirEnv): Promise<AuthConfig>;
+/**
+ * The provider a login screen should default to, or `null` when the project has
+ * configured none.
+ */
+export declare function getDefaultAuthProvider(env: FoirEnv): Promise<DefaultAuthProvider | null>;
+/**
+ * Read the project's customer 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>;
+/** Join the project's signup waitlist. The project must be in waitlist mode. */
+export declare function customerJoinWaitlist(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>;
+/**
+ * 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
+ * {@link saveSession}, or use {@link resetPasswordAndSignIn} which does both.
+ */
+export declare function customerResetPassword(env: FoirEnv, vars: {
+    token: string;
+    newPassword: string;
+}): Promise<CustomerAuthResult>;
+/** Redeem an emailed verification token. */
+export declare function customerVerifyEmail(env: FoirEnv, token: string): Promise<boolean>;
+/**
+ * Change the calling customer'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: {
+    currentPassword: string;
+    newPassword: string;
+}, options?: AuthOpOptions): Promise<boolean>;
+/**
+ * The calling customer, or `null` when the request carried no customer 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
+ * transparently by the server when it has expired. `null` when there is no
+ * customer 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>;
+/**
+ * Delete the calling customer'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.
+ */
+export declare function deleteMyAccount(env: FoirEnv, vars: {
+    confirm: boolean;
+    password?: string;
+}, options?: AuthOpOptions): Promise<DeleteAccountResult>;
+/** Persist an auth result to the session; returns the customer identity. */
+export declare function saveSession(adapter: SessionAdapter, result: CustomerAuthResult): Promise<FoirCustomer>;
+/** 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>;
+/** Login with email + password and persist the session. */
+export declare function loginWithPassword(adapter: SessionAdapter, env: FoirEnv, vars: {
+    email: string;
+    password: string;
+}): Promise<FoirCustomer>;
+/** Register with email + password and persist the session. */
+export declare function registerWithPassword(adapter: SessionAdapter, env: FoirEnv, vars: {
+    email: string;
+    password: string;
+}): Promise<FoirCustomer>;
+/** Complete an OTP login and persist the session. */
+export declare function loginWithOTP(adapter: SessionAdapter, env: FoirEnv, vars: {
+    email: string;
+    otp: string;
+}): Promise<FoirCustomer>;
+/**
+ * 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.
+ */
+export declare function resetPasswordAndSignIn(adapter: SessionAdapter, env: FoirEnv, vars: {
+    token: string;
+    newPassword: string;
+}): Promise<FoirCustomer>;
+/**
+ * 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
+ * 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
+ * better than the failure mode of not (a signed-in browser the user believes is
+ * signed out).
+ */
+export declare function signOut(adapter: SessionAdapter, env: FoirEnv): Promise<void>;
+/**
+ * Refresh the access token from the stored refresh token, persisting the
+ * rotated pair. Returns the new tokens, or null when there's no refresh token
+ * or the refresh fails (the session is cleared in that case).
+ */
+export declare function refreshSession(adapter: SessionAdapter, env: FoirEnv): Promise<FoirAuthTokens | null>;
+/**
+ * Run a bearer-authed GraphQL operation with refresh-with-retry: uses the
+ * stored access token, and on a 401-shaped failure (rejected/expired bearer)
+ * attempts a single token refresh and retries once. Any other error — network
+ * blips, server errors, validation — propagates without a retry so transient
+ * mutation failures can't be duplicated. Throws the original error if there's
+ * no refresh path.
+ */
+export declare function authedRequest<TData, TVariables>(adapter: SessionAdapter, env: FoirEnv, document: TypedDocumentNode<TData, TVariables>, variables?: TVariables): Promise<TData>;
+/**
+ * {@link authedRequest}'s twin for the generated `auth` namespace: run a
+ * post-credential auth op with the stored access token, refreshing once and
+ * retrying once on a 401-shaped failure.
+ *
+ * The two exist side by side because they serve different documents, not
+ * different transports. `authedRequest` runs the CONSUMER's document — the
+ * project's own `myProfile` and friends, whose shape the SDK cannot know — and
+ * this runs a root field the server generated. Refresh-with-retry is the same
+ * behaviour in both, and it is the reason either is worth having: it is session
+ * 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 {
+    /**
+     * 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`.
+     */
+    resolveUser?: (ctx: {
+        token: string;
+        customer: FoirCustomer;
+    }) => FoirUser | Promise<FoirUser>;
+    /**
+     * Called when there's no valid session — throw your framework's redirect
+     * (e.g. `throw redirect(loginUrl)`). Must not return.
+     */
+    onUnauthenticated: () => never | Promise<never>;
+}
+/**
+ * Require a signed-in customer. Resolves the {@link FoirUser} via
+ * `resolveUser` (or a minimal identity), 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>;

package/dist/auth/hosted.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Hosted-login bridge — for storefronts that delegate sign-in to a Foir
+ * white-label front door (the `customerLoginWithFoir` flow) instead of
+ * rendering their own login UI.
+ *
+ * The front door sets a first-party session cookie on the registrable domain;
+ * because that domain is shared, the cookie reaches the storefront, which
+ * exchanges it server-side for a short-lived customer bearer + identity. The
+ * cookie is the durable credential (re-exchanged on bearer expiry) — there's
+ * no separate refresh token in this flow.
+ *
+ * Every URL/cookie/path is CONFIG, not a constant, so a domain restructure
+ * is a config change, not a code change.
+ */
+export interface HostedLoginConfig {
+    /** White-label front-door origin, e.g. `https://login.example.com`. */
+    loginOrigin: string;
+    /** Session cookie name set on the registrable domain. Default `foir_customer_session`. */
+    cookieName?: string;
+    /** Session-exchange path on the front door. Default `/session/token`. */
+    sessionPath?: string;
+}
+/**
+ * Build the redirect URL to the hosted front door, forwarding a best-effort
+ * absolute `returnTo` (honoured if the front door supports it).
+ */
+export declare function hostedLoginUrl(config: HostedLoginConfig, returnTo?: string): string;
+/** The identity + bearer returned by a successful hosted-session exchange. */
+export interface HostedSession {
+    token: string;
+    customerId: string;
+    email: string;
+}
+/**
+ * Exchange the hosted-login cookie on an incoming request for a customer
+ * bearer + identity (server-to-server: forwards the cookie to the front
+ * door's session endpoint with the CSRF header). Returns null when there's no
+ * cookie or it's expired/revoked.
+ */
+export declare function fetchHostedSession(request: Request, config: HostedLoginConfig): Promise<HostedSession | null>;

package/dist/auth/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@foir/sdk/auth` — framework-agnostic Foir customer auth.
+ *
+ * The whole customer auth surface — login, register, OTP, external providers,
+ * refresh, password management, email verification and account deletion — over
+ * the server's generated `auth` namespace, plus token lifecycle with an
+ * injected `SessionAdapter`, guards, and the optional hosted-login bridge.
+ *
+ * There are no operation documents here any more. The flows address root fields
+ * 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 { customerLogin, customerRegister, customerRequestOTP, customerLoginOTP, customerRefreshToken, customerLoginWithProvider, customerProviderCallback, customerProviderVerifyOTP, getAuthProviders, getAuthConfig, getDefaultAuthProvider, customerSignupContext, customerJoinWaitlist, customerRequestPasswordReset, customerResetPassword, customerUpdatePassword, customerVerifyEmail, currentUser, myProviderToken, customerLogout, deleteMyAccount, saveSession, clearSession, getSessionToken, getSessionCustomer, loginWithPassword, registerWithPassword, loginWithOTP, resetPasswordAndSignIn, refreshSession, signOut, authedRequest, authedOp, requireAuth, requireAdmin, } from './auth';
+export type { FoirAuthTokens, FoirCustomer, FoirUser, SessionAdapter, RequireAuthOptions, RequireAdminOptions, } from './auth';
+export { AUTH_OPS } from './ops';
+export type { AuthOpName, AuthOpOptions } from './ops';
+export { hostedLoginUrl, fetchHostedSession } from './hosted';
+export type { HostedLoginConfig, HostedSession } from './hosted';
+export { createFoirSessionClient } from './session-client';
+export type { FoirSessionClient, FoirSessionConfig, FoirSessionUser, } from './session-client';
+export type { CustomerAuthResult, ProviderLoginResult, AuthProviderPublic, ProviderLoginInput, ProviderCallbackInput, ProviderOTPVerifyInput, SignupContext, SignupMode, WaitlistJoinResult, AuthConfig, AuthConfigProvider, DefaultAuthProvider, CurrentUser, ProviderToken, DeleteAccountResult, } from './operations';

package/dist/auth/operations.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Foir customer-auth result and input types.
+ *
+ * These are PLATFORM-STABLE primitives — login / register / refresh / OTP /
+ * provider login / password management / account lifecycle are fixed-shape
+ * operations served by api-public for every project (gated per-project by the
+ * password / OTP / provider flags, but identical in shape when present). Unlike
+ * per-project model types they do not vary by configured models, so the SDK
+ * owns these declarations directly rather than relying on the consumer's
+ * codegen.
+ *
+ * WHAT USED TO BE HERE. This file also held eleven hand-written GraphQL
+ * documents, `parse()`d at module load. They are gone. Every flow in `./auth`
+ * now addresses the server's generated `auth` namespace through the same op
+ * transport `@foir/sdk/data` uses, so the SDK has one execution surface rather
+ * than a private one for auth and a shared one for everything else. Two
+ * consequences worth knowing:
+ *
+ *   - the shapes below are no longer a document's selection set. They describe
+ *     what the server's own payload writer selects for these fields, which is
+ *     every scalar the type has. `authNamespaceOpShapes` in `./ops` is the
+ *     machine-checked version of that sentence.
+ *   - `graphql` is no longer imported here, or anywhere under `./auth`'s flow
+ *     path. The top-level `parse()` calls were what no bundler could shake out,
+ *     and they are the reason `@foir/sdk/auth/session` had to exist as a
+ *     separate graphql-free door.
+ *
+ * The project-specific customer PROFILE (e.g. `myProfile.isAdmin`) is still NOT
+ * here — that shape varies per project, so it stays consumer-injected (see
+ * `requireAuth`'s `resolveUser`).
+ */
+/** The common auth result every login/register/refresh mutation returns. */
+export interface CustomerAuthResult {
+    token: string;
+    refreshToken: string;
+    customerId: string;
+    email: string;
+}
+/** Result of initiating a provider login — a redirect URL or an inline token. */
+export interface ProviderLoginResult {
+    /** OAuth/OIDC authorization URL to redirect the user to (redirect flows). */
+    redirectUrl: string | null;
+    /** Inline access token (non-redirect provider flows). */
+    token: string | null;
+}
+/** A configured auth provider, as exposed to unauthenticated callers. */
+export interface AuthProviderPublic {
+    key: string;
+    name: string;
+    /** OAUTH2 | TOKEN_SSO | SAML | OIDC | EXTERNAL */
+    type: string;
+    isDefault: boolean | null;
+}
+export interface ProviderLoginInput {
+    providerKey: string;
+    email?: string;
+    returnTo?: string;
+    /** Override the provider's default redirect_uri (must be allow-listed). */
+    redirectUri?: string;
+}
+export interface ProviderCallbackInput {
+    providerKey: string;
+    code?: string;
+    state?: string;
+    email?: string;
+    idToken?: string;
+}
+export interface ProviderOTPVerifyInput {
+    providerKey: string;
+    email: string;
+    otp: string;
+}
+/** The project's customer signup mode. */
+export type SignupMode = 'PUBLIC' | 'RESTRICTED' | 'WAITLIST' | 'CLOSED';
+/** The signup surface a self-hosted frontend reads to render the right UI. */
+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;
+    name: string;
+    /** OAUTH2 | TOKEN_SSO | SAML | OIDC | EXTERNAL */
+    type: string;
+}
+/**
+ * The project's public auth configuration: which built-in methods are on, and
+ * which external providers a login screen should offer. Readable before any
+ * customer token exists — it is what a login screen renders itself from.
+ */
+export interface AuthConfig {
+    passwordEnabled: boolean;
+    otpEnabled: boolean;
+    providers: AuthConfigProvider[] | null;
+}
+/**
+ * The provider a login screen should default to, or `null` when the project has
+ * configured none.
+ */
+export interface DefaultAuthProvider {
+    key: string | null;
+    name: string | null;
+    type: string | null;
+}
+/**
+ * The calling customer, resolved from the bearer token. `null` when the request
+ * carried no customer token — an absent session is an answer, not a failure.
+ */
+export interface CurrentUser {
+    id: string;
+    email: string;
+    /** ACTIVE | PENDING | SUSPENDED | … */
+    status: string;
+    /** ISO-8601, or null when the address is unverified. */
+    emailVerifiedAt: string | null;
+    /** ISO-8601. */
+    createdAt: string;
+}
+/**
+ * A stored upstream provider token for the calling customer. `null` when there
+ * is no customer token on the request, or none stored for that provider.
+ */
+export interface ProviderToken {
+    providerKey: string;
+    accessToken: string;
+    refreshToken: string | null;
+    /** ISO-8601. */
+    expiresAt: string | null;
+    /** Space-separated provider scopes, as the provider issued them. */
+    scopes: string | null;
+}
+/** What a self-serve account deletion removed. */
+export interface DeleteAccountResult {
+    success: boolean;
+    recordsDeleted: number;
+    filesDeleted: number;
+}

package/dist/auth/ops.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The auth client's execution path: the server's generated `auth` namespace.
+ *
+ * `@foir/sdk/auth` used to carry its own transport — eleven hand-written
+ * GraphQL documents `parse()`d at module load and posted to `/graphql`. That was
+ * a second wire protocol for one substrate inside one package, and it had the
+ * cost such things always have: the hand-written set covered nine of the
+ * surface's root fields and the other eleven — the whole of password
+ * management, email verification and account deletion — were reachable nowhere
+ * in the SDK, so "forgot password" meant dropping to hand-written GraphQL.
+ *
+ * Now every flow addresses a root field the caller's own manifest advertises,
+ * printed and executed by the same functions `@foir/sdk/data` runs every model
+ * op through. ONE transport, and the auth client's remaining job is the half
+ * that was always the hard part: token storage, refresh, redirects and the
+ * React context.
+ *
+ * WHAT THIS FILE IS NOT. It is not a schema. It names root fields and nothing
+ * else — no types, no selection sets, no argument coercion. The SHAPE of what an
+ * op selects comes from `namespaces.auth.ops.<op>.payload` in the caller's own
+ * manifest, and the argument types from `argTypes` beside it; if this file ever
+ * needed to know a field's type itself, the op vocabulary would be
+ * under-specified and the fix would belong on the server.
+ *
+ * ORDERING, and it is load-bearing: these ops resolve against the manifest the
+ * deployed api-public serves. A server that does not publish per-op payloads for
+ * the `auth` namespace answers every op below with a refusal naming the op. The
+ * server half ships first.
+ */
+import { type FoirEnv } from '../transport/foir-http';
+/**
+ * The `auth` namespace's root field names, as the manifest lists them.
+ *
+ * Written out rather than derived so a typo is a compile error at the call site
+ * instead of a 400 at runtime, and so this file is the one place to read what
+ * the auth client addresses. The names are the server's, unmodified — the op
+ * vocabulary for every namespace except `operations` IS the root field name, so
+ * nothing here is constructed and nothing can drift into a different name.
+ */
+export declare const AUTH_OPS: {
+    readonly authConfig: "authConfig";
+    readonly authProviders: "authProviders";
+    readonly defaultAuthProvider: "defaultAuthProvider";
+    readonly customerSignupContext: "customerSignupContext";
+    readonly currentUser: "currentUser";
+    readonly myProviderToken: "myProviderToken";
+    readonly customerLogin: "customerLogin";
+    readonly customerRegister: "customerRegister";
+    readonly customerRequestOTP: "customerRequestOTP";
+    readonly customerLoginOTP: "customerLoginOTP";
+    readonly customerRefreshToken: "customerRefreshToken";
+    readonly customerLogout: "customerLogout";
+    readonly customerJoinWaitlist: "customerJoinWaitlist";
+    readonly customerRequestPasswordReset: "customerRequestPasswordReset";
+    readonly customerResetPassword: "customerResetPassword";
+    readonly customerUpdatePassword: "customerUpdatePassword";
+    readonly customerVerifyEmail: "customerVerifyEmail";
+    readonly deleteMyAccount: "deleteMyAccount";
+    readonly customerLoginWithProvider: "customerLoginWithProvider";
+    readonly customerProviderCallback: "customerProviderCallback";
+    readonly customerProviderVerifyOTP: "customerProviderVerifyOTP";
+};
+/** One of the auth namespace's root field names. */
+export type AuthOpName = (typeof AUTH_OPS)[keyof typeof AUTH_OPS];
+/** Per-call overrides for an auth op. */
+export interface AuthOpOptions {
+    /**
+     * Customer bearer token. api-public still needs the `x-api-key` to resolve
+     * the project; the bearer adds the customer identity the post-credential ops
+     * (`currentUser`, `customerUpdatePassword`, `deleteMyAccount`, …) are
+     * authorised by. Ignored by the pre-credential ops, which mint it.
+     */
+    bearerToken?: string;
+    /**
+     * `fetch` implementation. Defaults to `globalThis.fetch`. Injectable for
+     * tests and for runtimes that hand you a bound `fetch` (Hydrogen/Oxygen).
+     */
+    fetch?: typeof globalThis.fetch;
+    /** Extra headers, applied last so they can override the ones above. */
+    headers?: Readonly<Record<string, string>>;
+}
+/**
+ * Forget every memoised descriptor.
+ *
+ * For tests and for a long-lived process that has rotated a key. Not part of a
+ * normal flow — the descriptor is refetched on schema change by the drift check
+ * on the data client, and auth ops are not where that is noticed.
+ */
+export declare function clearAuthManifestCache(): void;
+/**
+ * Execute one auth op and return the root field's value.
+ *
+ * Arguments are sent as GraphQL variables, typed from the op's published
+ * `argTypes`. `undefined` entries are dropped rather than sent as null: a
+ * GraphQL argument that is absent and one that is explicitly null mean different
+ * things to the resolvers below (`deleteMyAccount`'s optional `password` is the
+ * live example).
+ */
+export declare function authOp<T>(env: FoirEnv, op: AuthOpName, args?: Record<string, unknown>, options?: AuthOpOptions): Promise<T>;