@foir/sdk 0.7.0 → 0.8.0

package/dist/data/builtins.d.ts

@@ -7,24 +7,27 @@
  * 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 eight of the names it can use are platform-owned
- *     objects rather than leaves: `ImageValue`, `VideoValue`, `FileValue`,
- *     `MediaValue`, `RichtextValue`, `GeoPointValue`, `ReferenceValue`,
- *     `CollabInfo`. They are structurally nested but behave as leaves — always
- *     present, never lazily hydrated, never `include`-able.
- *
- *  2. **Block primitives.** A block union's members are *model keys*, except
- *     for eight lowercase tokens — `text`, `image`, `video`, `file`,
- *     `richtext`, `media`, `reference`, `flexible` — which are members of the
- *     real GraphQL union but have **no entry in `models`**. On the live dev
- *     Marketing project, 7 of `tilly_page.blocks`'s 29 members are these. A
- *     generator that resolved every member to `models[key]` would skip them
- *     (an inexhaustive union, silently wrong at runtime) or emit `never`.
- *
- * Both sets are the manifest's own prescription, not this file's invention: the
- * payload reference says of the value objects that a client "ships static types
- * for them rather than generating them per project", and names the eight block
- * tokens as having no `models` entry by design.
+ *     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
@@ -42,6 +45,7 @@
  * 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;
@@ -69,8 +73,18 @@ export interface ImageVariantSet {
     _3xl: ImageVariant | null;
     _4xl: ImageVariant | null;
 }
-export interface ImageValue {
-    url: string;
+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;
@@ -86,8 +100,9 @@ export interface ImageValue {
     /** AVIF tier set (smaller, narrower support). The preferred `<picture>` source. */
     avif: ImageVariantSet | null;
 }
-export interface VideoValue {
-    url: string;
+export interface Video {
+    __typename?: 'Video';
+    url: string | null;
     thumbnailUrl: string | null;
     previewUrl: string | null;
     hlsManifestUrl: string | null;
@@ -100,28 +115,62 @@ export interface VideoValue {
     fileSize: number | null;
 }
 export interface FileValue {
+    __typename?: 'FileValue';
     url: string | null;
     filename: string | null;
     mimeType: string | null;
     size: number | null;
 }
-export interface GeoPointValue {
+export interface GeoPoint {
+    __typename?: 'GeoPoint';
     lat: number | null;
     lng: number | null;
 }
-export interface RichtextValue {
+export interface Richtext {
+    __typename?: 'Richtext';
     html: string | null;
     json: FoirJsonValue | null;
     markdown: string | null;
 }
 /**
- * A foreign key, and the reason a consumer never writes `include` to get one:
- * this arrives with the record, complete, under the complete-by-default
- * selection model. `post.author._id` is always there and always typed present.
+ * 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 ReferenceValue {
-    _id: string | null;
-    _type: string | null;
+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;
@@ -153,69 +202,54 @@ export interface CollabInfo {
     roomName: string;
 }
 /**
- * The metadata every block member carries, and the two discriminants an
- * exhaustive `switch` narrows on.
- *
- * `__typename` is the one to prefer. The op compiler emits it on the union's
- * own selection set for every union it expands, and it is the only field that
- * cannot be `omit`ed (no omit path can name it). `_type` is the foir block-type
- * token — the model key for a model-derived member, the lowercase primitive
- * token otherwise — and is deliberately NOT protected from `omit` by the
- * server, so a caller who omits it loses the second discriminant while keeping
- * the first.
- */
-export interface FoirBlockMeta<TType extends string, TTypename extends string> {
-    __typename: TTypename;
-    _type: TType;
-    _id: string | null;
-    _key: string | null;
-    _label: string | null;
-}
-export interface RichtextBlock extends FoirBlockMeta<'richtext', 'RichtextBlock'>, RichtextValue {
-}
-export interface ImageBlock extends FoirBlockMeta<'image', 'ImageBlock'>, Omit<ImageValue, 'url'> {
-    /**
-     * Nullable here, `String!` on `ImageValue`. Wrapping a value type as a block
-     * drops NonNull (`wrapValueFieldsAsBlock`), and reporting it non-null would
-     * be a lie a consumer's generated types cannot recover from.
-     */
-    url: string | null;
-}
-export interface VideoBlock extends FoirBlockMeta<'video', 'VideoBlock'>, Omit<VideoValue, 'url'> {
-    /** Nullable here, `String!` on `VideoValue` — see `ImageBlock.url`. */
-    url: string | null;
-}
-export interface FileBlock extends FoirBlockMeta<'file', 'FileBlock'>, FileValue {
-}
-export interface MediaBlock extends FoirBlockMeta<'media', 'MediaBlock'>, MediaValue {
-}
-export interface TextBlock extends FoirBlockMeta<'text', 'TextBlock'> {
-    value: string | null;
-}
-/**
- * A reference to another record.
+ * `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.
  *
- * `record` is the resolved target, over the project's `Record` union — every
- * model in the project. It is 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.
- */
-export interface ReferenceBlock<TRecord = FoirUnexpandedRecord> extends FoirBlockMeta<'reference', 'ReferenceBlock'>, Omit<ReferenceValue, '_id' | '_type'> {
-    record: TRecord | null;
-}
-/**
- * The fallback member, for a `flexible` field in a project with no block types
- * to offer. Its `_type` is whatever the stored value carried, so — uniquely
- * among the primitives — it is not a literal.
+ * `__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.
  */
-export interface FlexibleBlock {
-    __typename: 'FlexibleBlock';
-    _type: string | null;
-    _id: string | null;
-    _key: string | null;
-    _label: string | null;
-    value: FoirJsonValue | null;
-}
+/** @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.
  *
@@ -225,11 +259,65 @@ export interface FlexibleBlock {
  * `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. Reach the rest with `foir.raw()`.
+ * 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;
 /**
@@ -273,6 +361,128 @@ 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';
 /**

package/dist/data/client.d.ts

@@ -3,12 +3,12 @@
  *
  * ```ts
  * import { createFoirClient } from '@foir/sdk/data';
- * 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!,
  *   apiKey: process.env.PLATFORM_API_KEY!,
- *   schemaVersion: foirSchemaVersion,
+ *   generated,
  * });
  *
  * const block = await foir.tilly_block.findUnique({
@@ -18,6 +18,19 @@
  * });
  * ```
  *
+ * 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
  * ---------------------------------------------------------------------------
@@ -29,28 +42,54 @@
  * reached. A two-level `Proxy` does that in a few lines and costs one property
  * lookup per call.
  *
- * The alternative — fetching `/v1/manifest` at construction — would put a
- * round trip in front of the first query on every cold edge invocation, to
- * learn something the types already know.
+ * ---------------------------------------------------------------------------
+ * 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`
  * ---------------------------------------------------------------------------
  *
- * `POST /v1/query` takes `model` OR `namespace`, never both, and refuses the
- * request if you send both. Since there is no runtime schema (above), the
- * client cannot tell which one `foir.search` means. So the addressing carries
- * it: `foir.<model>.<op>()` sends `model`, `foir.ns.<namespace>.<op>()` sends
- * `namespace`. `ns` and `raw` are therefore reserved top-level names.
+ * 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 FoirRawOp } from './transport';
-/** The ops available on one model for this credential. */
+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;
 }> = {
@@ -59,21 +98,44 @@ export type FoirNamespaceClient<N extends {
 export interface FoirClientCore<S extends FoirSchemaDefinition> {
     /**
      * Non-model root namespaces (`search`, `customers`, `notifications`).
-     * Separate accessor because the wire distinguishes `model` from `namespace`
-     * and the client has no runtime schema to disambiguate with.
+     * 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]>;
+        [NK in keyof S['namespaces']]: FoirNamespaceClient<S['namespaces'][NK]> & FoirNamespaceSubscriptions<NK>;
     };
     /**
-     * Untyped passthrough to `POST /v1/query`.
+     * 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.
      *
-     * Every generated-type system needs an escape hatch; shipping one
-     * deliberately is better than people forking the client when the generated
-     * types cannot express something. Returns the single root field, same as a
-     * typed call, and throws the same `FoirRequestError`.
+     * 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.
      */
-    raw<T = unknown>(op: FoirRawOp): Promise<T>;
+    dispose(): void;
 }
 /**
  * The client, shaped by the credential's manifest. An op that is not in
@@ -83,12 +145,22 @@ export interface FoirClientCore<S extends FoirSchemaDefinition> {
 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>(config: FoirClientConfig): FoirClient<S>;
+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>(env: FoirEnv, overrides?: Omit<FoirClientConfig, 'apiUrl' | 'apiKey' | 'channel'>): FoirClient<S>;
+export declare function createFoirClientFromEnv<S extends FoirSchemaDefinition = FoirSchemaDefinition>(env: FoirEnv, overrides?: Omit<FoirClientConfig, 'apiUrl' | 'apiKey' | 'channel' | 'generated'> & {
+    generated?: FoirGeneratedModule<S>;
+}): FoirClient<S>;