@foir/sdk 0.7.0 → 0.9.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,129 @@ 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.
+ * One run of styled text inside a passage.
+ *
+ * `marks` are named — `strong`, `em`, `code`, or a key into the passage's
+ * `markDefs` for anything that carries data (a link, and nothing else today).
+ * The bitmask the old editor stored is gone.
+ */
+export interface ProseSpan {
+    __typename?: 'ProseSpan';
+    text: string | null;
+    marks: Array<string | null> | null;
+}
+/**
+ * A text entry in a prose flow — a paragraph, a heading, a quote, a list item.
+ *
+ * `kind` is the semantic shape and `token` is the design-token override that
+ * beats it when set. `list` + `level` carry list nesting flat rather than as a
+ * tree. A soft break inside a passage is a `\n` in a span's text, not a
+ * separate entry.
+ *
+ * `markDefs` stays an open JSON leaf by declaration: def types are extensible,
+ * and a typed object over an open shape would drop what it does not know.
+ */
+export interface Passage {
+    __typename?: 'Passage';
+    _key: string | null;
+    kind: string | null;
+    token: string | null;
+    align: string | null;
+    list: string | null;
+    level: number | null;
+    language: string | null;
+    spans: Array<ProseSpan | null> | null;
+    markDefs: FoirJsonValue | null;
+}
+/**
+ * A prose field's read projection.
+ *
+ * `entries` is the typed reading and the one that keeps prose structured —
+ * `Passage` for a text-only field, and a union of `Passage` with the field's
+ * admitted embeds for one that places models. `html` and `markdown` are the
+ * passages only: an embed is omitted from both BY DECLARATION rather than
+ * rendered as invented markup, so a consumer that wants the embeds reads
+ * `entries`. `json` is the declared flow verbatim — the lossless escape hatch
+ * where an entry nobody recognises always survives.
+ *
+ * `E` is the entries element, filled in per field by `foir types`.
+ */
+export interface Prose<E = Passage> {
+    html: string | null;
+    markdown: string | null;
+    json: FoirJsonValue | null;
+    entries: Array<E | null> | null;
+}
+/**
+ * One ancestor of a hierarchy record, root-first.
+ *
+ * Identity only, by design: a child's public URL already exposes every
+ * ancestor's slug, so the walk never widens content visibility. Anything more
+ * than identity goes through the `parent` reference like any other read.
  */
-export interface ReferenceValue {
-    _id: string | null;
-    _type: string | null;
+export interface RecordAncestor {
+    __typename?: 'RecordAncestor';
+    _id: string;
+    _naturalKey: string | null;
+    _modelKey: 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;
@@ -153,69 +269,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 +326,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 +428,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';
 /**