@foir/sdk 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,325 @@
+# Changelog
+
+All notable changes to `@foir/sdk`.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning follows the policy below.
+
+---
+
+## Semver policy
+
+`@foir/sdk` is published to npm and installed by people outside this repo. Its
+**public API is the set of named exports reachable through the subpaths in
+`package.json#exports`** — nothing else. Anything reachable only by deep-importing
+`@foir/sdk/dist/...` is private and may change in any release without notice.
+
+That surface is pinned in [`public-exports.snapshot.json`](./public-exports.snapshot.json)
+and enforced on every build by `scripts/assert-public-exports.mjs`. If a change
+reds that guard, it belongs in this file.
+
+### Pre-1.0 note — breaking changes bump the MINOR
+
+While the version is `0.x`, a breaking change bumps the **minor** (`0.5.0` →
+`0.6.0`), not the major. This is not laziness about semver, it is what actually
+protects consumers: npm resolves `^0.5.0` to `>=0.5.0 <0.6.0`, so for a `0.x`
+package the minor — not the major — is the boundary an existing `pnpm install`
+will not cross on its own. Once `1.0.0` ships, breaking changes move to the
+major and this note goes away.
+
+Read "MAJOR" below as "minor, while we are pre-1.0".
+
+### MAJOR — breaking
+
+A change is breaking if code that compiled and ran against the previous version
+can stop compiling, stop resolving, or start behaving differently:
+
+- **Removing a named export** from any published subpath.
+- **Renaming a named export.** A rename is a removal plus an addition; shipping
+  the old name as a deprecated alias for at least one minor is preferred.
+- **Removing a subpath** from `package.json#exports`, or repointing one at a
+  module with a different surface.
+- **Demoting a value export to type-only** (`export { X }` → `export type { X }`).
+  The type-checker stays happy at the re-export site and the runtime import
+  starts throwing, which is the worst possible failure shape.
+- **Narrowing a type**: making an optional parameter or property required,
+  removing a member from a union or an enum, tightening a parameter's accepted
+  type, widening a return type, or adding a required field to an options object.
+  Rule of thumb — narrowing what we *accept* or widening what we *return* is
+  breaking; the reverse is not.
+- **Changing the runtime behaviour of an existing call**: different network
+  endpoint, different request or response shape on the wire, different default
+  value, throwing where it used to return, returning where it used to throw, or
+  a change in what gets persisted (cookie name, storage key, header name).
+- **Raising the floor**: a higher minimum Node version, a higher required
+  version of a peer dependency, or making an optional peer dependency required.
+
+Every breaking change needs a `### Removed` or `### Changed` entry below that
+**names each affected symbol** and states the migration.
+
+### MINOR — additive
+
+- A new subpath, a new named export, or a new optional parameter/property.
+- Widening what an existing call accepts, or narrowing what it returns.
+- Promoting a type-only export to a value export.
+- A new optional peer dependency.
+- Deprecating something (the deprecation itself is additive; the eventual
+  removal is the breaking part).
+
+Additive changes still red the export-surface guard — deliberately, so the
+snapshot cannot rot into a rubber stamp. Refresh it with
+`pnpm --filter @foir/sdk run snapshot:exports` and commit the result.
+
+### PATCH — fixes
+
+- A bug fix that moves behaviour **toward** what the types and docs already
+  promised. If a caller could reasonably have been depending on the buggy
+  behaviour, it is a MAJOR, not a PATCH.
+- Internal refactors, build/bundling changes, dependency bumps and performance
+  work with no observable change to the public surface.
+- Documentation, comments and JSDoc.
+
+### Releasing
+
+Bump `packages/sdk/package.json#version`, move `Unreleased` into a dated
+section here, then push a `sdk-v<version>` tag — the tag, not the commit,
+triggers `.github/workflows/sdk-publish.yml`.
+
+`pnpm --filter @foir/sdk release:minor` does the bump and the tag together, but
+only because `packages/sdk/.npmrc` sets `tag-version-prefix=sdk-v`. Without it
+`pnpm version` tags `v<version>`, which does **not** match the workflow's
+`sdk-v*` trigger — the bump would land and no publish would ever run. If you
+move or drop that `.npmrc`, tag by hand:
+
+```sh
+git tag sdk-v<version> && git push origin sdk-v<version>
+```
+
+The tag must point at a commit on `main`: `main` is what is released, and a tag
+on `dev` would publish unreviewed work to npm.
+
+---
+
+## [Unreleased]
+
+Changes on `dev` that have not been published to npm.
+
+---
+
+## [0.7.0] — 2026-08-08
+
+Everything additive, so a MINOR per the pre-1.0 note.
+
+Ships 0.6.0 with it. That version was cut in the changelog and in
+`package.json` on 2026-07-27 but no `sdk-v0.6.0` tag was ever pushed, and the
+tag is what publishes, so npm went straight from 0.5.0 to here. The 0.6.0
+section below is left as written rather than folded in, so the history says what
+actually happened.
+
+### Added
+
+- **Failure classification on `@foir/sdk/client`** — `isFoirRateLimited`,
+  `isFoirUnauthenticated`, `isFoirForbidden`, `isFoirNotFound`, plus `code`,
+  `requestId`, `retryable` and `retryAfterMs` on `FoirRequestError`, and the
+  `FoirErrorCode` / `FoirErrorExtensions` types behind them.
+
+  `FoirGraphQLErrorItem` now carries `extensions`, which is what makes any of
+  this possible: the platform has been sending `extensions.code` on every
+  rejection and the SDK's error type had nowhere to put it, so the only way to
+  tell one failure from another was to match the message.
+
+- **Retry, on by default, in `createFoirContentClient`** — `withFoirRetry` and
+  `foirRetryDelayMs` are exported for callers running their own loop.
+
+  It covers no-response, `5xx`, and **`429`**. The last one is the reason this
+  is in the SDK rather than in a docs snippet. A 429 sits among the 4xx statuses
+  that are permanent, so the rule everyone writes — retry 5xx, never retry 4xx —
+  excludes the one failure in that family that clears on its own. A storefront
+  wrote exactly that rule; when its key saturated, every read failed on the
+  first attempt for an hour and the site served empty pages while the API was
+  healthy.
+
+  A server-stated `Retry-After` wins over backoff, capped by `maxDelayMs`
+  (default 20s) so an hour-long window does not block a render. Opt out with
+  `retry: { attempts: 1 }`.
+
+- **`onRateLimit`** on `createFoirContentClient` and on `FoirRequestOptions`,
+  with `readFoirRateLimit` and the `FoirRateLimitSnapshot` type. Called with the
+  `X-RateLimit-*` headers of every response, so an app can log that a key is
+  approaching its ceiling instead of finding out when it hits one.
+
+- **New subpath `@foir/sdk/auth/session`** — `createFoirSessionClient` and its
+  types (`FoirSessionClient`, `FoirSessionConfig`, `FoirSessionUser`) on their
+  own, without the rest of `./auth`.
+
+  Purely additive: `./auth` keeps exporting all four, unchanged, and nothing is
+  moved or renamed. What changes is the cost of reaching them. `./auth` also
+  exports the customer-auth GraphQL documents, which build their
+  TypedDocumentNodes with a top-level `parse()` that no bundler can treat as
+  pure — so a browser app importing only `createFoirSessionClient` was shipping
+  the whole `graphql` package to get it. `src/auth/session-client.ts` imports
+  nothing at all, and this subpath bundles it alone.
+
+  Like `./data`, it adds **no dependency and no peer dependency**:
+  `dist/auth-session.js` has no imports. An app on this subpath needs `graphql`
+  neither installed nor bundled. Use `./auth` when you want the login /
+  register / OTP / provider flows too; use this one for a backend-less SPA whose
+  only credential is the Fóir-hosted session cookie.
+
+- **New subpath `@foir/sdk/data`** — the typed data client over
+  `POST /v1/query` (TTS-874). `createFoirClient<FoirSchema>({ apiUrl, apiKey })`
+  gives `foir.<model>.<op>(…)`, `foir.ns.<namespace>.<op>(…)` and an untyped
+  `foir.raw(op)`. The client's surface is shaped by the credential: an op that
+  is not in that key's manifest is not on the type, so `foir.page.create(…)`
+  under a `pk_` key is a compile error rather than a 400.
+
+  Selection is complete-by-default — every scalar always arrives, so the model
+  type is unconditionally true — with `include` to opt into relations and
+  `omit` to drop a heavy field. `_id` is not omittable, matching the server.
+
+  **This subpath has no `graphql` dependency**: it imports neither `graphql`,
+  `@graphql-typed-document-node/core` nor `@graphql-codegen/*`, and adds no new
+  peer dependency, required or optional. `dist/data.js` has no imports at all.
+
+  New exports on `./data`: `createFoirClient`, `createFoirClientFromEnv`,
+  `fetchFoirManifest`, `foirDataEndpoint`, `FoirRequestError`, and the type
+  surface (`FoirSchemaDefinition`, `FoirModelDefinition`,
+  `FoirRelationDefinition`, `FoirOpDefinition`, `FoirReturnDefinition`,
+  `FoirNamespaceDefinition`, `FoirNamespaceOpDefinition`, `FoirFieldsShape`,
+  `FoirConnection`, `FoirClient`, `FoirClientCore`, `FoirClientConfig`,
+  `FoirModelClient`, `FoirNamespaceClient`, `FoirModelOperation`,
+  `FoirNamespaceOperation`, `FoirQuery`, `FoirInclude`, `FoirOmittableKey`,
+  `FoirRecordResult`, `FoirOpResult`, `FoirRawOp`, `FoirSchemaDrift`,
+  `FoirManifest` + its members, and `FoirEnv` / `FoirGraphQLErrorItem` /
+  `FoirTokenProvider` re-exported for `./data`-only consumers).
+
+  Additive, so a MINOR bump at release time. No existing subpath's surface
+  changed — the export snapshot diff for this change is one new subpath and
+  nothing else.
+
+### Changed
+
+- Internal only, no public surface change: the `graphql`-free half of
+  `src/graphql/foir-request.ts` moved to `src/transport/foir-http.ts` so
+  `./data` and `./client` share one header builder and one `FoirRequestError`
+  rather than forking the transport. `@foir/sdk/client` re-exports every symbol
+  it exported before, unchanged, and `FoirTokenProvider` is now declared in the
+  shared module and re-exported from its old home.
+
+---
+
+## [0.6.0] — 2026-07-27
+
+First release since the public surface was pinned. Everything in it is
+additive, so per the pre-1.0 note this is a MINOR: `^0.5.0` will not pick it up
+on its own, which is the intended behaviour for a release that adds exports.
+
+### Added
+
+- `@foir/sdk/auth`: `customerSignupContext` and `customerJoinWaitlist`, plus the
+  `SignupContext`, `SignupMode` and `WaitlistJoinResult` types — waitlist and
+  restricted-signup flows for projects that are not open-registration.
+- A pinned public-export surface: `public-exports.snapshot.json` plus
+  `scripts/assert-public-exports.mjs`, wired into `pnpm build`. Deleting a named
+  export previously passed the full SDK CI lane — 125 tests and the export-map
+  guard all green — because nothing checked the contents of the declared files,
+  only that they existed.
+- This changelog, and the semver policy above.
+
+### Changed
+
+- Type declarations are emitted by a dedicated `tsc --emitDeclarationOnly` pass
+  instead of `tsup`'s built-in `dts`, whose parallel rollup workers
+  intermittently failed to flush a subpath's `.d.ts`; consumers saw
+  "Could not find a declaration file for module '@foir/sdk/realtime'".
+  `scripts/assert-export-types.mjs` now fails the build if any file the export
+  map promises is missing. No change to the public surface.
+- The test suite pins `NODE_ENV=test` so an inherited `NODE_ENV=production`
+  cannot load React's production build and break every render test. Internal.
+
+---
+
+## [0.5.0] — 2026-07-15
+
+### Added
+
+- `@foir/sdk/client`: `createFoirContentClient` — forwards the customer bearer
+  token on content reads, so authenticated and segment-targeted content works
+  without hand-rolling the header.
+
+## [0.4.0] — 2026-07-12
+
+### Added
+
+- `@foir/sdk/auth`: `createFoirSessionClient`, plus the `FoirSessionClient`,
+  `FoirSessionConfig` and `FoirSessionUser` types — Foir-hosted first-party
+  sessions for backend-less SPAs, over the `fetchHostedSession` /
+  `hostedLoginUrl` hosted-login bridge that already shipped in 0.1.0 (EID-516).
+
+## [0.3.0] — 2026-07-12
+
+### Added
+
+- **New subpath `@foir/sdk/react`** — drop-in React customer auth: `FoirProvider`,
+  `SignIn`, `OAuthButtons`, `UserButton`, `useFoirAuth`, `useFoirSession`,
+  `useFoirUser` (EID-515).
+- **New subpath `@foir/sdk/next`** — Next.js App Router BFF auth adapter: cookie
+  session store, `createFoirMiddleware`, server-side sign-in/out actions and the
+  provider callback handler (EID-515).
+
+## [0.2.0] — 2026-07-10
+
+### Added
+
+- **New subpath `@foir/sdk/push`** — native Web Push (VAPID) enrolment:
+  `enableWebPush`, `disableWebPush`, `isWebPushSupported`.
+- `@foir/sdk/server`: `requireScopedToken` — a one-line ingress guard for
+  operation BFF routes, over the existing `verifyScopedToken` (EID-498).
+
+## [0.1.0] — 2026-06-23
+
+First public release. Ten subpaths:
+
+- `@foir/sdk` — editor iframe client: `EditorProvider`, `useEditor`, the
+  host↔editor message protocol, and `createPlatformClient` (EID-88, EID-91).
+- `@foir/sdk/server` — server-side platform helpers for config API backends:
+  `createServerClient`, scoped-token verification, `verifyWebhookSignature`.
+- `@foir/sdk/client` — React-free GraphQL transport for SSR/edge (`foirRequest`).
+- `@foir/sdk/media` — progressive media components and adapters (EID-94).
+- `@foir/sdk/content` — `createContentRenderer` and `RichTextRenderer` with
+  injected typography tokens (EID-93).
+- `@foir/sdk/auth` — customer auth flows, token lifecycle, hosted-login bridge
+  (EID-95).
+- `@foir/sdk/realtime` — `createCollabSession`, a thin y-websocket helper
+  (EID-103, EID-104).
+- `@foir/sdk/codegen`, `@foir/sdk/codegen/block-registry`,
+  `@foir/sdk/codegen/block-scaffold` — the `foirCodegen` preset and the
+  graphql-codegen plugins (EID-92).
+
+---
+
+### A note on the backfilled entries
+
+`@foir/sdk` shipped 0.1.0 through 0.5.0 with no changelog. The five sections
+above were reconstructed after the fact from sources that can be re-checked:
+the `sdk-v*` git tags, the `packages/sdk/package.json#exports` map read at each
+of those tags, the commits between consecutive tags that touch `packages/sdk/`,
+and the npm registry's publish timestamps (`npm view @foir/sdk time`), which is
+where the dates come from.
+
+They are **headline-level, not exhaustive**. They record subpath additions and
+the named feature of each release; they do not claim to list every symbol added,
+because no per-symbol record was kept at the time and reconstructing one would
+mean guessing. Nothing above is asserted that could not be read out of the tags
+and the commit history.
+
+`Unreleased` and every section after it are authored at the time of the change
+and are exhaustive for the public surface, which is what the export-surface
+guard exists to keep true.
+
+[Unreleased]: https://github.com/foir-io/clients/compare/sdk-v0.5.0...dev
+[0.5.0]: https://github.com/foir-io/clients/compare/sdk-v0.4.0...sdk-v0.5.0
+[0.4.0]: https://github.com/foir-io/clients/compare/sdk-v0.3.0...sdk-v0.4.0
+[0.3.0]: https://github.com/foir-io/clients/compare/sdk-v0.2.0...sdk-v0.3.0
+[0.2.0]: https://github.com/foir-io/clients/compare/sdk-v0.1.0...sdk-v0.2.0
+[0.1.0]: https://github.com/foir-io/clients/releases/tag/sdk-v0.1.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 `POST /v1/query` — `createFoirClient`, per-key-shaped ops, `include`/`omit`, `fetchFoirManifest` | **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,68 @@ pnpm add yjs y-websocket    # for @foir/sdk/realtime
 
 ## Usage
 
+### 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.
+
+```ts
+import { createFoirClient } from '@foir/sdk/data';
+// generated by `foir types` from GET /v1/manifest
+import { type FoirSchema, foirSchemaVersion } from './foir.generated';
+
+const foir = createFoirClient<FoirSchema>({
+  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
+});
+
+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({ model: 'post', op: 'findMany', args: { first: 1 } });
+```
+
+**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
+```
+
+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.
+
+Session-bound reads take a `bearerToken`, as a string or a function resolved per
+request:
+
+```ts
+const foir = createFoirClient<FoirSchema>({
+  apiUrl,
+  apiKey,
+  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.
+
 ### 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,140 @@
+/**
+ * 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.
+ */
+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 { 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 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>;
+/** 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>;
+/**
+ * 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>;
+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,15 @@
+/**
+ * `@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).
+ */
+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 type { FoirAuthTokens, FoirCustomer, FoirUser, SessionAdapter, RequireAuthOptions, RequireAdminOptions, } from './auth';
+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, } from './operations';
+export { CustomerLoginDocument, CustomerRegisterDocument, CustomerRefreshTokenDocument, CustomerRequestOTPDocument, CustomerLoginOTPDocument, CustomerLoginWithProviderDocument, CustomerProviderCallbackDocument, CustomerProviderVerifyOTPDocument, AuthProvidersDocument, } from './operations';