@foir/sdk 0.5.0 → 0.8.0

package/dist/data/builtins.d.ts

@@ -0,0 +1,506 @@
+/**
+ * The platform-owned types `foir types` does NOT generate.
+ *
+ * Two closed sets live here, and they are here rather than in the generated
+ * file for the same reason: they are identical in every project, so generating
+ * them per project would emit the same 200 lines into every consumer's repo and
+ * give four projects four chances to disagree about `ImageValue`.
+ *
+ *  1. **Value objects.** `GET /v1/manifest` reports a scalar's `type` as a
+ *     GraphQL named type, and several of the names it can use are
+ *     platform-owned objects rather than leaves: `Image`, `Video`, `FileValue`,
+ *     `Richtext`, `GeoPoint`, `Reference`, `CollabInfo`. They are structurally
+ *     nested but behave as leaves — always present, never lazily hydrated,
+ *     never `include`-able.
+ *
+ *  2. **Primitive members.** A flexible field's union members are *model keys*,
+ *     except for six lowercase tokens — `richtext`, `image`, `video`, `file`,
+ *     `reference`, `geopoint` — which are members of the real GraphQL union but
+ *     have **no entry in `models`**. A generator that resolved every member to
+ *     `models[key]` would skip them (an inexhaustive union, silently wrong at
+ *     runtime) or emit `never`.
+ *
+ * # These are ONE set, not two (TTS-1391)
+ *
+ * They used to be two: a value object for a plain field, and a separate
+ * `<Name>Block` wrapper for the same thing inside a flexible field. TTS-1391
+ * removed the wrapper — an item IS its value — so a plain `image` field and an
+ * `image` inside a flexible field are the SAME GraphQL type, `Image`. There is
+ * no `ImageValue` in a real schema and never will be again; the only difference
+ * between the two positions is whether `__typename` was selected.
+ *
+ * ---------------------------------------------------------------------------
+ * The obligation that comes with a static table
+ * ---------------------------------------------------------------------------
+ *
+ * This IS a mirror of a platform-side table, and mirrors drift. What keeps it
+ * honest is that the generator refuses to guess: a union member key that is
+ * neither in `models` nor in this table makes `foir types` fail loudly naming
+ * the member, rather than emitting a union that silently lacks a branch. So the
+ * failure mode of drift is a red build with the missing name in it.
+ *
+ * `apps/cli/src/lib/__tests__/types-codegen.test.ts` asserts that against both
+ * committed live-captured manifests.
+ *
+ * Field shapes verified against deployed dev's introspection on 2026-07-28 and
+ * against `api-public/internal/schema/field_mapping.go`.
+ */
+import type { FoirConnection } from './schema';
+/** A `JSON` scalar. Deliberately not `any`: reading through it needs a check. */
+export type FoirJsonValue = string | number | boolean | null | FoirJsonValue[] | {
+    [key: string]: FoirJsonValue;
+};
+export type ImageFormat = 'WEBP' | 'AVIF' | 'JPEG' | 'PNG';
+/** One rendition of an image at a named tier, in a single format. */
+export interface ImageVariant {
+    size: string;
+    format: ImageFormat;
+    url: string;
+    width: number | null;
+    height: number | null;
+}
+/**
+ * The curated tier set for one format. `_2xl`/`_3xl`/`_4xl` carry the
+ * underscore because a GraphQL identifier cannot start with a digit.
+ */
+export interface ImageVariantSet {
+    thumbnail: ImageVariant | null;
+    small: ImageVariant | null;
+    medium: ImageVariant | null;
+    large: ImageVariant | null;
+    xlarge: ImageVariant | null;
+    _2xl: ImageVariant | null;
+    _3xl: ImageVariant | null;
+    _4xl: ImageVariant | null;
+}
+export interface Image {
+    /**
+     * `String` on the wire, not `String!`.
+     *
+     * It was non-null here and nullable on the flexible-field member until
+     * TTS-1391, which is a §5.3.2 response-shape conflict the moment both are one
+     * type. The platform relaxed rather than tightened, because nullable is the
+     * honest form — its own public `File` asset type already declares
+     * `url: String` — so this follows.
+     */
+    __typename?: 'Image';
+    url: string | null;
+    width: number | null;
+    height: number | null;
+    alt: string | null;
+    blurhash: string | null;
+    dominantColor: string | null;
+    mimeType: string | null;
+    fileSize: number | null;
+    focalPoint: FoirJsonValue | null;
+    crop: FoirJsonValue | null;
+    variants: ImageVariantSet | null;
+    /** WebP tier set (universal support). Pair with `avif` in a `<picture>`. */
+    webp: ImageVariantSet | null;
+    /** AVIF tier set (smaller, narrower support). The preferred `<picture>` source. */
+    avif: ImageVariantSet | null;
+}
+export interface Video {
+    __typename?: 'Video';
+    url: string | null;
+    thumbnailUrl: string | null;
+    previewUrl: string | null;
+    hlsManifestUrl: string | null;
+    width: number | null;
+    height: number | null;
+    duration: number | null;
+    blurhash: string | null;
+    dominantColor: string | null;
+    mimeType: string | null;
+    fileSize: number | null;
+}
+export interface FileValue {
+    __typename?: 'FileValue';
+    url: string | null;
+    filename: string | null;
+    mimeType: string | null;
+    size: number | null;
+}
+export interface GeoPoint {
+    __typename?: 'GeoPoint';
+    lat: number | null;
+    lng: number | null;
+}
+export interface Richtext {
+    __typename?: 'Richtext';
+    html: string | null;
+    json: FoirJsonValue | null;
+    markdown: string | null;
+}
+/**
+ * A reference whose target model is not pinned by the field's declaration.
+ *
+ * A reference field that declares ONE `referenceTypes` entry resolves to that
+ * model's own type, and one declaring several resolves to a `<Members>Ref`
+ * union — so this type is what an undeclared reference resolves to, and what a
+ * flexible field's `reference` member is.
+ *
+ * # What makes it followable
+ *
+ * `_targetModelKey` names the model and `_targetId` OR `_targetNaturalKey`
+ * identifies the row within it: `foir[_targetModelKey].findUnique({ where: { _id:
+ * _targetId } })`. Both identifier shapes are live — on the dev database 101 of
+ * 193 stored reference values carry an id and 92 carry a natural key and no id
+ * — so a consumer must handle either.
+ *
+ * `_id` and `_type` are NOT here, and their absence is the TTS-1391 correction
+ * rather than an omission. They were the wrapper's own metadata: `_id` was the
+ * ITEM's id (never the target's, which is why `_targetId` exists separately) and
+ * `_type` was the union discriminator, reading `"reference"` on every reference
+ * ever stored. The wrapper is gone, so neither field is in the schema, and a
+ * consumer selecting them got `undefined` while the types promised a string.
+ */
+export interface Reference<TRecord = FoirUnexpandedRecord> {
+    __typename?: 'Reference';
+    /** The model to fetch the target from. Null when the target no longer exists. */
+    _targetModelKey: string | null;
+    /** The target's id, when the reference stored one. */
+    _targetId: string | null;
+    /** The target's natural key, when the reference names its target that way. */
+    _targetNaturalKey: string | null;
+    /**
+     * The resolved target, over the project's `Record` union — every model in the
+     * project. Left as a type parameter so the generated file can name that
+     * union; the default is the honest answer for a consumer who has not narrowed
+     * it.
+     */
+    record: TRecord | null;
+    /** A stored SPELLING of the model. Read as an input to `_targetModelKey`. */
+    _schema: string | null;
+    naturalKey: string | null;
+    _preview: FoirJsonValue | null;
+}
+/** Inline media embedded in a content field — polymorphic per `mediaType`. */
+export interface MediaValue {
+    mediaType: string | null;
+    url: string | null;
+    mimeType: string | null;
+    fileId: string | null;
+    fileSize: number | null;
+    filename: string | null;
+    width: number | null;
+    height: number | null;
+    blurhash: string | null;
+    dominantColor: string | null;
+    duration: number | null;
+    hlsManifestUrl: string | null;
+    previewUrl: string | null;
+    thumbnailUrl: string | null;
+    variants: FoirJsonValue | null;
+    crop: FoirJsonValue | null;
+    focalPoint: FoirJsonValue | null;
+}
+/** Collaborative-editing discovery. */
+export interface CollabInfo {
+    enabled: boolean;
+    wsUrl: string;
+    roomName: string;
+}
+/**
+ * `Image`, `Video`, `FileValue`, `Richtext`, `GeoPoint` and `Reference` above
+ * ARE the members. There is no separate item type, because an item is its
+ * value: `... on Image { url }` means the same thing inside a flexible field
+ * and at a plain `image` field, and one fragment reads it in both positions.
+ *
+ * `__typename` is optional on each, matching what graphql-codegen emits: it is
+ * present whenever selected, and the op compiler always selects it on a union's
+ * own selection set — it is the one field no `omit` path can name. Narrowing on
+ * it is exact regardless, because the literal types are disjoint.
+ *
+ * `_type` was the second discriminant and is gone with the envelope. It was
+ * never protected from `omit` anyway, so `__typename` was always the one to
+ * prefer.
+ *
+ * The three wrappers below have no replacement, because the things they
+ * described no longer exist:
+ *
+ *   - `MediaBlock` — `media` stopped being a primitive at TTS-1391. It was
+ *     never in the proto FieldType enum, and it is the one primitive name a
+ *     project had also used as a model key.
+ *   - `TextBlock` — TTS-1406 removed it. GraphQL requires a union member to be
+ *     an object type and a text item's value is a bare scalar, which is the
+ *     whole reason a wrapper existed. An inline model with a text field is how
+ *     a text slot is authored.
+ *   - `FlexibleBlock` — there is no fallback member. An item whose `_type`
+ *     names nothing is nulled out of its list and reported, which is what a
+ *     stored null already read as.
+ */
+/** @deprecated Renamed to {@link Image}. The wrapper is gone; this IS the image. */
+export type ImageBlock = Image;
+/** @deprecated Renamed to {@link Video}. */
+export type VideoBlock = Video;
+/** @deprecated Renamed to {@link FileValue}. */
+export type FileBlock = FileValue;
+/** @deprecated Renamed to {@link Richtext}. */
+export type RichtextBlock = Richtext;
+/** @deprecated Renamed to {@link GeoPoint}. */
+export type GeoPointValue = GeoPoint;
+/** @deprecated Renamed to {@link Image}. */
+export type ImageValue = Image;
+/** @deprecated Renamed to {@link Video}. */
+export type VideoValue = Video;
+/** @deprecated Renamed to {@link Richtext}. */
+export type RichtextValue = Richtext;
+/** @deprecated Renamed to {@link Reference}. */
+export type ReferenceValue<TRecord = FoirUnexpandedRecord> = Reference<TRecord>;
+/** @deprecated Renamed to {@link Reference}. */
+export type ReferenceBlock<TRecord = FoirUnexpandedRecord> = Reference<TRecord>;
+/**
+ * What a nested union or a re-entered object resolves to.
+ *
+ * The op compiler enforces a termination rule — *never expand a type, object or
+ * union, that is already on the current path; degrade it to `__typename`
+ * instead* — because `Block` contains members that contain `Block`, and a
+ * `tilly_page.blocks → TillyPageBlock.blocks` cycle is reachable in two hops
+ * with no `include` and no caller input at all. At a degraded position the
+ * response carries `__typename` and nothing else, so that is what the generated
+ * type says.
+ *
+ * # Reading past one
+ *
+ * A stopping point in front of a UNION can be spent a level on:
+ * `foir.product.findMany({ depth: 2 })` expands one more, and the response then
+ * carries that union's members here rather than `__typename` alone. A level
+ * costs one more expansion at each stopping point inside the expansion — so it
+ * compounds where there are several, and costs nothing per union MEMBER — and
+ * the call is refused client-side, with the arithmetic, when it would cross the
+ * server's field ceiling. See `FoirNamespaceCall.depth`.
+ *
+ * The TYPE follows the level. A generated composite on the path to a stopping
+ * point takes a `<D>` level parameter (see `FoirDepthLevel`), so at `depth: 2`
+ * the position resolves to the expanded union — `<Field>Blocks`, the type
+ * exported beside the `<Field>BlocksDegraded` named here — rather than to this
+ * one. The caller narrows on `__typename` and reads the member's own field; no
+ * cast, and no hand-written widening.
+ *
+ * `D` defaults to `1`, so a call passing no `depth` reaches THIS type at the
+ * stopping point exactly as it always did.
+ *
+ * A stopping point that is a composite CYCLE rather than a union — `menu.items
+ * .children` — has no union to expand and stays `__typename` at every depth.
+ */
+export interface FoirDegraded<TTypename extends string = string> {
+    __typename: TTypename;
+}
+/**
+ * The union levels the generated types describe — the type-level half of
+ * `depth`.
+ *
+ * A generated composite on the path to a stopping point takes one of these as
+ * a parameter, defaulted to `1`, and the model's shape at each level is named
+ * under `FoirModelDefinition.atDepth`. `1` is the complete-by-default document
+ * and is what every existing reference to a generated interface resolves to,
+ * which is why adding the parameter changed no result type.
+ *
+ * Four because depth is a budget against the server's 10,000-field ceiling and
+ * four is past what a generated module usefully describes: on the live dev
+ * project `product.findUnique` measures 318 fields at the default, 468 at 2 and
+ * 618 at 3. Those levels all fit since TTS-1448 — they read 1,203 / 4,308 /
+ * 13,623 when a union position was charged for every member — so the bound here
+ * is about how much generated type surface is worth emitting, not about what
+ * the server will run. A call
+ * asking for more is not an error: `atDepth` simply has no entry, the result
+ * falls back to the default shape, and the caller narrows by hand exactly as
+ * they did before. Under-promising is the safe direction, and the wire is
+ * unaffected — the printer's budget is a runtime number with no cap here.
+ */
+export type FoirDepthLevel = 1 | 2 | 3 | 4;
+/**
+ * `FoirDepthBelow[3] === 2` — one union level spent.
+ *
+ * Mirrors the printer's `depth - 1` at an expanded stopping point
+ * (`document.ts`, `printFields`), and lives beside `FoirDepthLevel` so the two
+ * cannot disagree about how many levels exist.
+ */
+export type FoirDepthBelow = [never, never, 1, 2, 3];
+/** A `Record`-union value the compiler did not expand. See `FoirDegraded`. */
+export type FoirUnexpandedRecord = FoirDegraded;
+/**
+ * The results of the ops that do NOT return the model.
+ *
+ * `foir types` classifies these as `opaque`, so the client offers no
+ * `include` / `omit` for them and uses the type below verbatim. They are here
+ * for the same reason the value objects are: platform-owned, fixed, and
+ * identical in every project.
+ */
+export type FoirVisibility = 'PRIVATE' | 'PUBLIC';
+export type FoirAccessLevel = 'READ' | 'WRITE' | 'DELETE';
+export type FoirAccessSource = 'PUBLIC' | 'OWNER' | 'GRANT' | 'ROLE';
+export type FoirGranteeKind = 'CUSTOMER' | 'ADMIN';
+/** `myAccess` — this principal's effective access to one record. */
+export interface FoirMyAccess {
+    access: FoirAccessLevel;
+    source: FoirAccessSource;
+}
+export interface FoirAccessGrant {
+    access: FoirAccessLevel;
+    createdAt: string;
+    granteeId: string;
+    granteeKind: FoirGranteeKind;
+}
+export interface FoirAccessor {
+    access: FoirAccessLevel;
+    granteeId: string;
+    granteeKind: FoirGranteeKind;
+    source: FoirAccessSource;
+}
+/** `access` — the full ACL of one record. */
+export interface FoirResourceAccess {
+    accessors: FoirAccessor[];
+    grants: FoirAccessGrant[];
+    public: boolean;
+    visibility: FoirVisibility;
+}
+/** `updateMany` — how many rows moved, and which. */
+export interface FoirUpdateManyPayload {
+    count: number;
+    ids: string[];
+}
+/**
+ * What a note is ABOUT — the closed set the platform's write path enforces.
+ *
+ * On the wire it is `String!`, not a GraphQL enum, so the manifest publishes no
+ * `enumValues` for it and `foir types` cannot generate this union. It is here
+ * for the same reason the value objects are: platform-owned, identical in every
+ * project, and otherwise hand-written once per consumer.
+ *
+ * It is never a MODEL KEY. Model keys are the project's to choose, so a project
+ * with a model keyed `file` would make one value mean two things; a note on a
+ * record is `'record'` plus the model key on `subjectModelKey`.
+ *
+ * This mirrors a platform-side set, and the obligation that comes with a mirror
+ * (see the file header) applies: a kind added there widens this union in a
+ * minor release, and until then a value outside it is a row no writer could
+ * have produced.
+ */
+export type FoirNoteSubjectType = 'record' | 'file' | 'model' | 'operation' | 'schedule' | 'customer';
+/**
+ * One file the customer submitted with their note.
+ *
+ * The file's own facts, and nothing about the platform's handling of it: when
+ * the link row was written and which retention clock it starts are not the
+ * author's business. What is here is enough to render "you sent this".
+ */
+export interface FoirCustomerNoteAttachment {
+    /** The file's id — the same one `createMyNote` was given. */
+    fileId: string;
+    filename: string;
+    mimeType: string;
+    /** Size in bytes, as stored. Authoritative; not the number the uploader declared. */
+    size: number;
+    url: string;
+}
+/**
+ * One note on the customer plane — `foir.ns.notes.myNotes` and
+ * `foir.ns.notes.createMyNote`.
+ *
+ * Deliberately narrower than the note your team sees in the dashboard. There is
+ * no visibility, no resolution note, no mentions and no metadata: those are the
+ * project's view of a thread, not the author's, and the customer-facing type
+ * does not merely omit them from the document — the surface does not carry them.
+ */
+export interface FoirCustomerNote {
+    id: string;
+    /** The note's prose. */
+    body: string | null;
+    subjectType: FoirNoteSubjectType;
+    subjectId: string;
+    /** The record's model key. Present only on a `record` subject. */
+    subjectModelKey: string | null;
+    /** Set when this note is a reply within a thread. */
+    parentNoteId: string | null;
+    threadRootId: string | null;
+    isResolved: boolean;
+    /**
+     * The files submitted with this note. Empty when there are none.
+     *
+     * The one place the customer surface is WIDER than "the author's own prose",
+     * and deliberately: an author who attached a screenshot has to be able to see
+     * that it arrived, or the only readings left to them are that it failed
+     * silently or that it was taken away.
+     */
+    attachments: FoirCustomerNoteAttachment[];
+    /** ISO-8601. */
+    createdAt: string;
+}
+/**
+ * What a note surface has to know about the project before it renders anything
+ * — `foir.ns.notes.noteConfig`.
+ *
+ * Charged `notes:write` rather than `notes:read`, and refused to a caller with
+ * no customer session, because the only caller it is useful to is one that can
+ * submit. So a composer can read it as its single readiness probe: an answer
+ * means this visitor may write, and a refusal names which half is missing.
+ */
+export interface FoirNoteConfig {
+    /**
+     * Whether this project's note surfaces may OFFER to capture a screenshot.
+     *
+     * It gates the offer, not the storing. Capture stays opt-in per submission —
+     * the browser's own picker is the consent gate and it cannot be bypassed.
+     */
+    screenshotsEnabled: boolean;
+}
+/** `myNotes` arguments. Forward-only cursor pagination, like every list read. */
+export interface FoirMyNotesArgs {
+    first?: number;
+    after?: string;
+    /** Narrow to one kind of subject. */
+    subjectType?: FoirNoteSubjectType;
+    /** Narrow to one subject — a record id, a file id, a model key. */
+    subjectId?: string;
+    /** Read one thread. Returns only the notes in it this caller can see. */
+    threadRootId?: string;
+}
+/**
+ * `myNotes` — the notes this customer wrote, plus the replies your team
+ * deliberately sent them. Never another customer's, and never an operator's
+ * internal ones.
+ */
+export type FoirMyNotesResult = FoirConnection<FoirCustomerNote>;
+/** `createMyNote` arguments. */
+export interface FoirCreateMyNoteArgs {
+    subjectType: FoirNoteSubjectType;
+    subjectId: string;
+    /** Required when `subjectType` is `'record'`, refused otherwise. */
+    subjectModelKey?: string;
+    body: string;
+    /** Reply within an existing thread. */
+    parentNoteId?: string;
+    /**
+     * Files to submit with this note, already uploaded through
+     * `createFileUpload` / `confirmFileUpload`.
+     *
+     * A file this caller cannot read is REFUSED and the note is not written. That
+     * is not a rough edge to code around: a create that accepted the note and
+     * dropped the attachment would leave the author believing they sent a
+     * screenshot nobody has.
+     */
+    attachmentFileIds?: string[];
+}
+export type FoirDeviceType = 'DESKTOP' | 'MOBILE' | 'TABLET';
+export type FoirPlatformType = 'IOS' | 'ANDROID' | 'WEB';
+/**
+ * The `contexts` argument on every typed read.
+ *
+ * **It is an object, not a list**, despite the plural name — `ResolveContextInput`
+ * on the wire, verified against deployed dev's introspection on both projects:
+ * `contexts: ResolveContextInput` with no LIST wrapper, four optional fields.
+ *
+ * Worth the paragraph because the plural reads like `string[]` and typing it
+ * that way compiles fine and then sends a body the server rejects. The
+ * `FoirSchemaDefinition` sketch in `schema.ts` had exactly that error, and it
+ * was found by the docs lane running the call rather than by anyone reading the
+ * contract.
+ */
+export interface FoirResolveContext {
+    device?: FoirDeviceType | null;
+    locale?: string | null;
+    platform?: FoirPlatformType | null;
+    preview?: boolean | null;
+}

package/dist/data/client.d.ts

@@ -0,0 +1,166 @@
+/**
+ * `createFoirClient` — the typed data client.
+ *
+ * ```ts
+ * import { createFoirClient } from '@foir/sdk/data';
+ * import * as generated from './foir.generated';
+ *
+ * const foir = createFoirClient({
+ *   apiUrl: process.env.PLATFORM_API_URL!,
+ *   apiKey: process.env.PLATFORM_API_KEY!,
+ *   generated,
+ * });
+ *
+ * const block = await foir.tilly_block.findUnique({
+ *   id: 'a3pr8x0j10rigx8u6t1xthbr',
+ *   include: { noteId: true },
+ *   omit: ['aiSummary'],
+ * });
+ * ```
+ *
+ * One import and one call. `FoirSchema` is inferred from the module rather than
+ * restated, and the four runtime exports the client reads are read off it rather
+ * than named one at a time at every call site — see `resolveGeneratedConfig`
+ * below for why that indirection is worth having.
+ *
+ * The individual fields (`schemaVersion`, `selections`, `namespaceSelections`,
+ * `selectionUnions`) still work, and still win where both are given.
+ *
+ * The call is the same call it always was. What changed underneath is what goes
+ * on the wire: the client loads that op's selection tree, applies
+ * `omit`/`pick`/`include`, prints a GraphQL document, hashes it and sends the
+ * hash. See `document.ts` for the printer and `transport.ts` for the routing.
+ *
+ * ---------------------------------------------------------------------------
+ * Why this is a Proxy
+ * ---------------------------------------------------------------------------
+ *
+ * `FoirSchema` is a TYPE. `foir types` emits interfaces, and interfaces do not
+ * exist at runtime, so the client is handed the full shape of the API at
+ * compile time and nothing at all at run time. There is no model list to build
+ * an object from — `foir.tilly_block.findMany` has to be resolved when it is
+ * reached. A two-level `Proxy` does that in a few lines and costs one property
+ * lookup per call.
+ *
+ * ---------------------------------------------------------------------------
+ * Why `selections` is a config field and not a fetch
+ * ---------------------------------------------------------------------------
+ *
+ * The trees ARE runtime data — that is the one thing the generated module has to
+ * carry across the type/value boundary, alongside `foirSchemaVersion`. Passing
+ * them in costs nothing and is the intended path.
+ *
+ * When they are absent the client fetches `GET /v1/manifest` once, at first use,
+ * and reads the same trees off it. That is a FALLBACK and never the default,
+ * for the reason this file has always given: it puts a round trip in front of
+ * the first query on every cold edge invocation, to learn something the
+ * generated file already knows. What it buys is that `@foir/sdk/data` still
+ * works with zero codegen, which keeps the getting-started path honest.
+ *
+ * It has to stay reachable, and it must not be reachable by ACCIDENT. Those
+ * pull in opposite directions and the split is: a client built with no generated
+ * module and no `selections` has chosen the fallback, and says so once; a client
+ * built with a `generated` module that cannot serve the printer is refused where
+ * it was constructed. There is no input that quietly produces the round trip.
+ *
+ * ---------------------------------------------------------------------------
+ * Why namespaces live under `.ns`
+ * ---------------------------------------------------------------------------
+ *
+ * Since there is no runtime schema (above), the client cannot tell whether
+ * `foir.search` means a model or a namespace. So the addressing carries it:
+ * `foir.<model>.<op>()` addresses a model, `foir.ns.<namespace>.<op>()` a
+ * namespace. `ns` and `raw` are therefore reserved top-level names.
+ */
+import type { FoirModelDefinition, FoirNamespaceOpDefinition, FoirOpDefinition, FoirSchemaDefinition } from './schema';
+import type { FoirModelOperation, FoirNamespaceOperation } from './selection';
+import { type FoirEnv } from '../transport/foir-http';
+import { type FoirClientConfig, type FoirGeneratedModule } from './transport';
+import { type FoirModelSubscriptions, type FoirNamespaceSubscriptions } from './subscriptions';
+/**
+ * The ops available on one model for this credential, plus its subscriptions.
+ *
+ * `onChange` is on every model rather than gated on a generated flag, and that
+ * is correct rather than lazy: `recordChanged` charges
+ * `records:read:<modelKey>`, which is the SAME scope that put the model in
+ * `FoirSchema` at all. A model this credential cannot watch is a model it
+ * cannot read, so it is already absent from `S['models']` and the accessor
+ * cannot be reached.
+ */
+export type FoirModelClient<S extends FoirSchemaDefinition, M extends FoirModelDefinition> = {
+    [OK in keyof M['ops']]: M['ops'][OK] extends FoirOpDefinition ? FoirModelOperation<S, M, M['ops'][OK]> : never;
+} & FoirModelSubscriptions;
+export type FoirNamespaceClient<N extends {
+    ops: object;
+}> = {
+    [OK in keyof N['ops']]: N['ops'][OK] extends FoirNamespaceOpDefinition ? FoirNamespaceOperation<N['ops'][OK]> : never;
+};
+export interface FoirClientCore<S extends FoirSchemaDefinition> {
+    /**
+     * Non-model root namespaces (`search`, `customers`, `notifications`).
+     * Separate accessor because the addressing has to distinguish a model from a
+     * namespace and the client has no runtime schema to disambiguate with.
+     */
+    readonly ns: {
+        [NK in keyof S['namespaces']]: FoirNamespaceClient<S['namespaces'][NK]> & FoirNamespaceSubscriptions<NK>;
+    };
+    /**
+     * Untyped passthrough — a raw GraphQL document, executed on this credential.
+     *
+     * It changed meaning with the transport, and deliberately so. It used to take
+     * a JSON op because that was the wire; now the wire is GraphQL, and an escape
+     * hatch that could only say what the JSON op could say would be an escape from
+     * nothing. As a document it reaches everything the credential can reach —
+     * including the root fields no model or namespace claims (`designTokens`,
+     * `record`, `locales`, `resolvedLocale`, the whole customer-auth mutation
+     * set), which the JSON op could not address at all.
+     *
+     * Returns the whole `data` object rather than a single root field, because a
+     * hand-written document may legitimately have several. Routing, the persisted
+     * -query handshake and `FoirRequestError` are exactly as on the typed path.
+     *
+     * ```ts
+     * const { pages } = await foir.raw<{ pages: { totalCount: number } }>(
+     *   'query Recent($n: Int) { pages(first: $n, orderBy: { createdAt: DESC }) { totalCount } }',
+     *   { n: 5 },
+     * );
+     * ```
+     */
+    raw<T = unknown>(document: string, variables?: Record<string, unknown>): Promise<T>;
+    /**
+     * Close the subscription socket and drop every live subscription.
+     *
+     * Only needed by a long-lived process that discards a client — a browser tab
+     * or an edge invocation just goes away. The socket is lazy and self-closing
+     * (it opens on the first subscription and closes when the last is cancelled),
+     * so a client that only queries never has one to dispose of.
+     */
+    dispose(): void;
+}
+/**
+ * The client, shaped by the credential's manifest. An op that is not in
+ * `FoirSchema` is not on this type, so `foir.tilly_block.create(...)` under a
+ * read-only `pk_` key is a compile error rather than a 400.
+ */
+export type FoirClient<S extends FoirSchemaDefinition> = FoirClientCore<S> & {
+    [MK in keyof S['models']]: FoirModelClient<S, S['models'][MK]>;
+};
+export declare function createFoirClient<S extends FoirSchemaDefinition = FoirSchemaDefinition>(clientConfig: FoirClientConfig<S>): FoirClient<S>;
+/**
+ * `createFoirClient` from the `PLATFORM_API_URL` / `PLATFORM_API_KEY` /
+ * `FOIR_PREVIEW` convention `@foir/sdk/client` already uses, so a storefront
+ * that has an env wired for GraphQL can add the data client without a second
+ * set of variables. Preview picks the `sk_` `PLATFORM_PREVIEW_API_KEY` and the
+ * draft schema channel, exactly as `foirRequest` does.
+ *
+ * ```ts
+ * import * as generated from './foir.generated';
+ * const foir = createFoirClientFromEnv(env, { generated });
+ * ```
+ *
+ * `generated` is spelled out in the overrides type rather than left inside the
+ * `Omit<…>` so `S` is inferred from it here exactly as it is on `createFoirClient`.
+ */
+export declare function createFoirClientFromEnv<S extends FoirSchemaDefinition = FoirSchemaDefinition>(env: FoirEnv, overrides?: Omit<FoirClientConfig, 'apiUrl' | 'apiKey' | 'channel' | 'generated'> & {
+    generated?: FoirGeneratedModule<S>;
+}): FoirClient<S>;