@foir/sdk 0.7.0 → 0.9.0

package/README.md

@@ -24,7 +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 `POST /v1/query` — `createFoirClient`, per-key-shaped ops, `include`/`omit`, `fetchFoirManifest` | **none** |
+| `@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` |
@@ -38,21 +38,25 @@ pnpm add yjs y-websocket    # for @foir/sdk/realtime
 
 ### Typed data client (no GraphQL, no codegen step)
 
-`@foir/sdk/data` is a second app-runtime transport. You write ops instead of
-`.graphql` documents, and the package needs **no `graphql` dependency at all** —
-no `graphql`, no `@graphql-typed-document-node/core`, no `@graphql-codegen/*`,
-and no new peer. The server compiles your op to a GraphQL document, so both
-transports run through the same executor, scope checks and response cache.
+`@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 { type FoirSchema, foirSchemaVersion } from './foir.generated';
+import * as generated from './foir.generated';
 
-const foir = createFoirClient<FoirSchema>({
+const foir = createFoirClient({
   apiUrl: process.env.PLATFORM_API_URL!,   // a bare origin or the /graphql URL
   apiKey: process.env.PLATFORM_API_KEY!,
-  schemaVersion: foirSchemaVersion,        // warns once if the server has moved on
+  generated,                               // the whole module: types, trees, version
 });
 
 const post = await foir.post.findUnique({
@@ -63,9 +67,20 @@ const post = await foir.post.findUnique({
 
 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({ model: 'post', op: 'findMany', args: { first: 1 } });
+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
@@ -79,24 +94,40 @@ call:
 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
-`/v1/query` takes `model` **or** `namespace` and the client carries no runtime
-schema to tell them apart. `ns` and `raw` are the only reserved names.
+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<FoirSchema>({
+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)` reuses them, including the
-preview `sk_` key and the draft schema channel.
+the GraphQL path? `createFoirClientFromEnv(env, { generated })` reuses them,
+including the preview `sk_` key and the draft schema channel.
 
 ### Typed GraphQL from a server loader
 

package/dist/auth/auth.d.ts

@@ -6,9 +6,17 @@
  * 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 CustomerAuthResult, type ProviderLoginResult, type AuthProviderPublic, type ProviderLoginInput, type ProviderCallbackInput, type ProviderOTPVerifyInput, type SignupContext, type WaitlistJoinResult } from './operations';
+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 {
@@ -65,6 +73,17 @@ export declare function customerProviderCallback(env: FoirEnv, input: ProviderCa
 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.
@@ -72,6 +91,57 @@ export declare function getAuthProviders(env: FoirEnv): Promise<AuthProviderPubl
 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. */
@@ -95,6 +165,26 @@ 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
@@ -110,6 +200,19 @@ export declare function refreshSession(adapter: SessionAdapter, env: FoirEnv): P
  * 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

package/dist/auth/hosted.d.ts

@@ -19,12 +19,34 @@ export interface HostedLoginConfig {
     cookieName?: string;
     /** Session-exchange path on the front door. Default `/session/token`. */
     sessionPath?: string;
+    /** RP-initiated logout path on the front door. Default `/session/end-session`. */
+    endSessionPath?: 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;
+/**
+ * Build the redirect URL that ENDS the hosted session — the mirror of
+ * `hostedLoginUrl`, and the only thing that actually signs a customer out on
+ * this flow.
+ *
+ * The cookie is the durable credential. Disposing of a bearer, clearing a
+ * local session, or calling the `customerLogout` mutation (which clears
+ * upstream provider tokens and nothing else) all leave it in place, and the
+ * next request re-establishes the customer from it. This URL points at the
+ * front door's end-session endpoint, which revokes the session row and clears
+ * the cookie before returning the browser to `returnTo`.
+ *
+ * A URL builder, deliberately: no transport, no CORS surface, no CSRF header,
+ * and no JavaScript required at the consumer. Server-side logout is
+ * `return redirect(hostedLogoutUrl(config, clientId, returnTo))`.
+ *
+ * `returnTo` must be an absolute URL on an origin registered for `clientId`;
+ * the platform refuses anything else. Omit it for a bare 204 with no redirect.
+ */
+export declare function hostedLogoutUrl(config: HostedLoginConfig, clientId: string, returnTo?: string): string;
 /** The identity + bearer returned by a successful hosted-session exchange. */
 export interface HostedSession {
     token: string;

package/dist/auth/index.d.ts

@@ -1,15 +1,21 @@
 /**
  * `@foir/sdk/auth` — framework-agnostic Foir customer auth.
  *
- * Platform-stable login/register/OTP/provider/refresh flows over api-public,
- * token lifecycle with an injected `SessionAdapter`, guards, and the optional
- * hosted-login bridge. `graphql` is an optional peer (the operation documents).
+ * 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, customerSignupContext, customerJoinWaitlist, saveSession, clearSession, getSessionToken, getSessionCustomer, loginWithPassword, registerWithPassword, loginWithOTP, refreshSession, authedRequest, requireAuth, requireAdmin, } from './auth';
+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 { hostedLoginUrl, fetchHostedSession } from './hosted';
+export { AUTH_OPS } from './ops';
+export type { AuthOpName, AuthOpOptions } from './ops';
+export { hostedLoginUrl, hostedLogoutUrl, 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, } from './operations';
-export { CustomerLoginDocument, CustomerRegisterDocument, CustomerRefreshTokenDocument, CustomerRequestOTPDocument, CustomerLoginOTPDocument, CustomerLoginWithProviderDocument, CustomerProviderCallbackDocument, CustomerProviderVerifyOTPDocument, AuthProvidersDocument, } from './operations';
+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

@@ -1,18 +1,34 @@
 /**
- * Foir customer-auth GraphQL operations + result types.
+ * Foir customer-auth result and input types.
  *
- * These are PLATFORM-STABLE primitives — `customerLogin`/`customerRegister`/
- * `customerRefreshToken`/OTP/provider login 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 don't vary by configured models, so the SDK owns the
- * documents directly rather than relying on the consumer's codegen.
+ * 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.
  *
- * The project-specific customer PROFILE (e.g. `myProfile.isAdmin`) is NOT here
- * — that shape varies per project, so it stays consumer-injected (see
+ * 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`).
  */
-import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
 /** The common auth result every login/register/refresh mutation returns. */
 export interface CustomerAuthResult {
     token: string;
@@ -55,7 +71,7 @@ export interface ProviderOTPVerifyInput {
     otp: string;
 }
 /** The project's customer signup mode. */
-export type SignupMode = "PUBLIC" | "RESTRICTED" | "WAITLIST" | "CLOSED";
+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;
@@ -67,57 +83,62 @@ export interface WaitlistJoinResult {
     /** Waitlist lifecycle status; PENDING on a fresh join. */
     status: string;
 }
-export declare const CustomerLoginDocument: TypedDocumentNode<{
-    customerLogin: CustomerAuthResult;
-}, {
-    email: string;
-    password: string;
-}>;
-export declare const CustomerRegisterDocument: TypedDocumentNode<{
-    customerRegister: CustomerAuthResult;
-}, {
-    email: string;
-    password: string;
-}>;
-export declare const CustomerRefreshTokenDocument: TypedDocumentNode<{
-    customerRefreshToken: CustomerAuthResult;
-}, {
-    refreshToken: string;
-}>;
-export declare const CustomerRequestOTPDocument: TypedDocumentNode<{
-    customerRequestOTP: boolean;
-}, {
-    email: string;
-}>;
-export declare const CustomerLoginOTPDocument: TypedDocumentNode<{
-    customerLoginOTP: CustomerAuthResult;
-}, {
-    email: string;
-    otp: string;
-}>;
-export declare const CustomerLoginWithProviderDocument: TypedDocumentNode<{
-    customerLoginWithProvider: ProviderLoginResult;
-}, {
-    input: ProviderLoginInput;
-}>;
-export declare const CustomerProviderCallbackDocument: TypedDocumentNode<{
-    customerProviderCallback: CustomerAuthResult;
-}, {
-    input: ProviderCallbackInput;
-}>;
-export declare const CustomerProviderVerifyOTPDocument: TypedDocumentNode<{
-    customerProviderVerifyOTP: CustomerAuthResult;
-}, {
-    input: ProviderOTPVerifyInput;
-}>;
-export declare const AuthProvidersDocument: TypedDocumentNode<{
-    authProviders: AuthProviderPublic[];
-}, Record<string, never>>;
-export declare const CustomerJoinWaitlistDocument: TypedDocumentNode<{
-    customerJoinWaitlist: WaitlistJoinResult;
-}, {
+/** 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;
-}>;
-export declare const CustomerSignupContextDocument: TypedDocumentNode<{
-    customerSignupContext: SignupContext;
-}, Record<string, never>>;
+    /** 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>;