@foir/sdk 0.8.0 → 0.10.0

package/dist/data/builtins.d.ts

@@ -20,10 +20,10 @@
  *     `models[key]` would skip them (an inexhaustive union, silently wrong at
  *     runtime) or emit `never`.
  *
- * # These are ONE set, not two (TTS-1391)
+ * # These are ONE set, not two
  *
  * 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
+ * `<Name>Block` wrapper for the same thing inside a flexible field. The rename
  * 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
@@ -78,7 +78,7 @@ 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
+     * the rename, 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.
@@ -132,6 +132,73 @@ export interface Richtext {
     json: FoirJsonValue | null;
     markdown: string | null;
 }
+/**
+ * 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 RecordAncestor {
+    __typename?: 'RecordAncestor';
+    _id: string;
+    _naturalKey: string | null;
+    _modelKey: string | null;
+}
 /**
  * A reference whose target model is not pinned by the field's declaration.
  *
@@ -148,7 +215,7 @@ export interface Richtext {
  * 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
+ * `_id` and `_type` are NOT here, and their absence is the 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
@@ -219,10 +286,10 @@ export interface CollabInfo {
  * 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
+ *   - `MediaBlock` — `media` stopped being a primitive. 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
+ *   - `TextBlock` — removed as well. 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.
@@ -300,7 +367,7 @@ export interface FoirDegraded<TTypename extends string = string> {
  * 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 /
+ * 618 at 3. Those levels all fit now — 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
@@ -362,7 +429,8 @@ export interface FoirUpdateManyPayload {
     ids: string[];
 }
 /**
- * What a note is ABOUT — the closed set the platform's write path enforces.
+ * What a customer's note can be ABOUT: the customer-plane subset of 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
@@ -373,10 +441,14 @@ export interface FoirUpdateManyPayload {
  * 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.
+ * The platform set also holds `project` and `organization`, and this union
+ * deliberately does not. Both are operator constructs: the platform answers a
+ * note about either through a row policy no customer claim passes, so no note
+ * this surface reads or writes can carry them. This mirrors the part of the
+ * platform set a customer can reach, and the obligation that comes with a mirror
+ * (see the file header) applies: a kind the platform opens to customers widens
+ * this union in a minor release, and until then a value outside it is a row no
+ * customer writer could have produced.
  */
 export type FoirNoteSubjectType = 'record' | 'file' | 'model' | 'operation' | 'schedule' | 'customer';
 /**
@@ -483,6 +555,53 @@ export interface FoirCreateMyNoteArgs {
      */
     attachmentFileIds?: string[];
 }
+/**
+ * `submitAnonymousNote` arguments — feedback from a visitor with no account.
+ *
+ * Present on the project's schema only while the project has opted in
+ * (Notes settings → "Accept anonymous notes"). The feedback widget does NOT
+ * use this: a signed-out visitor there is still asked to sign in, so this
+ * mutation is the only path a visitor's note can take.
+ *
+ * WRITE-ONLY. Nothing reads an anonymous note back on the public plane, which
+ * is why the result is a receipt rather than the note.
+ */
+export interface FoirSubmitAnonymousNoteArgs {
+    /**
+     * Must be `'record'` — the only thing a visitor may write a note about.
+     * Narrower than `FoirCreateMyNoteArgs`, where a customer may also address a
+     * file or a model.
+     */
+    subjectType: 'record';
+    subjectId: string;
+    /**
+     * The record's model key. REQUIRED here, unlike on `createMyNote` where it is
+     * conditional: the subject is always a record on this lane, so the condition
+     * is always met.
+     */
+    subjectModelKey: string;
+    body: string;
+    /**
+     * Optional. Where the operators may reply.
+     *
+     * Captured as typed and NEVER verified — it is not treated as proof of who
+     * wrote the note, and nothing is sent to it to confirm it. Do not build a
+     * flow that assumes the address is reachable.
+     */
+    contactEmail?: string;
+}
+/** What `submitAnonymousNote` returns. */
+export interface FoirAnonymousNoteReceipt {
+    /**
+     * A reference for this submission, to quote when following it up.
+     *
+     * NOT a handle: there is no read that takes it. Showing it to the visitor is
+     * the whole of its purpose.
+     */
+    reference: string;
+    /** When the platform recorded the submission. */
+    submittedAt: string;
+}
 export type FoirDeviceType = 'DESKTOP' | 'MOBILE' | 'TABLET';
 export type FoirPlatformType = 'IOS' | 'ANDROID' | 'WEB';
 /**

package/dist/data/client.d.ts

@@ -95,6 +95,74 @@ export type FoirNamespaceClient<N extends {
 }> = {
     [OK in keyof N['ops']]: N['ops'][OK] extends FoirNamespaceOpDefinition ? FoirNamespaceOperation<N['ops'][OK]> : never;
 };
+declare const foirDocumentResult: unique symbol;
+declare const foirDocumentVariables: unique symbol;
+/**
+ * A GraphQL document string that carries its own result and variable types.
+ *
+ * `raw` returns `unknown` because a hand-written document is opaque to the
+ * client, so every call site hand-writes a result type that nothing checks. That
+ * is the cost the escape hatch was never meant to have: the sites that most need
+ * type safety, the ones the typed client could not express, are the ones with
+ * none.
+ *
+ * A branded document moves that annotation from the call site to the document,
+ * once, next to the selection it describes. It is still an assertion rather than
+ * a proof, because nothing validates it against the live schema, but it is an
+ * assertion made in ONE place that every caller then inherits, and a wrong one
+ * is wrong somewhere a reader is looking at the query.
+ *
+ * The brands are phantom: they exist only in the type system, so a
+ * `TypedFoirDocument` is a plain string at runtime and can be logged, hashed or
+ * sent anywhere a string goes.
+ */
+export type TypedFoirDocument<TResult, TVariables = Record<string, unknown>> = string & {
+    readonly [foirDocumentResult]: TResult;
+    readonly [foirDocumentVariables]: TVariables;
+};
+/**
+ * Brand a GraphQL document with the shape it returns.
+ *
+ * ```ts
+ * const RECENT = graphql<{ pages: { totalCount: number } }, { n: number }>(`
+ *   query Recent($n: Int) { pages(first: $n) { totalCount } }
+ * `);
+ *
+ * const { pages } = await foir.raw(RECENT, { n: 5 });
+ * //      ^? { totalCount: number }
+ * ```
+ *
+ * It does nothing at runtime beyond returning the string it was given. The value
+ * is entirely in the type, and in the fact that the type now lives beside the
+ * document rather than being retyped at each call.
+ *
+ * This does NOT make a bespoke selection type-checked against the schema. That
+ * is the larger half and wants generated documents rather than a helper. What it
+ * removes is the retyping, which is where the two real bugs came from: a result
+ * type that drifted from the selection it claimed to describe.
+ */
+export declare function graphql<TResult = unknown, TVariables = Record<string, unknown>>(document: string): TypedFoirDocument<TResult, TVariables>;
+/**
+ * Per-call options for {@link FoirClient.raw}.
+ */
+export interface FoirRawOptions {
+    /**
+     * Treat a partial response as a failure.
+     *
+     * A GraphQL response can carry `errors` AND `data` together, and the default
+     * is to warn and return the data: a field the server could not resolve should
+     * not blank a whole page, and forward compatibility rests on it.
+     *
+     * On a hand-written document that default is the expensive one. There is no
+     * generated selection to have caught a wrong field name first, so selecting
+     * something that does not exist returns everything else and logs — a typo
+     * reads as a missing feature rather than a failure, and the hand-written
+     * result type asserts it was fine. `strict: true` turns that into a thrown
+     * `FoirRequestError`, which still carries the data on `partialData` so a
+     * caller can log what it declined to render.
+     */
+    strict?: boolean;
+}
 export interface FoirClientCore<S extends FoirSchemaDefinition> {
     /**
      * Non-model root namespaces (`search`, `customers`, `notifications`).
@@ -126,7 +194,19 @@ export interface FoirClientCore<S extends FoirSchemaDefinition> {
      * );
      * ```
      */
-    raw<T = unknown>(document: string, variables?: Record<string, unknown>): Promise<T>;
+    raw<TResult, TVariables extends Record<string, unknown>>(document: TypedFoirDocument<TResult, TVariables>, variables?: TVariables, options?: FoirRawOptions): Promise<TResult>;
+    /**
+     * The untyped form, for a document with no brand.
+     *
+     * The document type excludes a branded one deliberately. Without that, a
+     * branded call whose VARIABLES do not match falls through to this overload,
+     * whose `Record<string, unknown>` accepts anything, and the mistake compiles.
+     * The result would still be typed, so the call site reads as checked while the
+     * variables are not, which is the failure mode a brand exists to prevent.
+     */
+    raw<T = unknown>(document: string & {
+        readonly [foirDocumentResult]?: undefined;
+    }, variables?: Record<string, unknown>, options?: FoirRawOptions): Promise<T>;
     /**
      * Close the subscription socket and drop every live subscription.
      *
@@ -164,3 +244,4 @@ export declare function createFoirClient<S extends FoirSchemaDefinition = FoirSc
 export declare function createFoirClientFromEnv<S extends FoirSchemaDefinition = FoirSchemaDefinition>(env: FoirEnv, overrides?: Omit<FoirClientConfig, 'apiUrl' | 'apiKey' | 'channel' | 'generated'> & {
     generated?: FoirGeneratedModule<S>;
 }): FoirClient<S>;
+export {};

package/dist/data/decimal.d.ts

@@ -0,0 +1,212 @@
+/**
+ * `FoirDecimal` — the exact numeric type a `decimal` field arrives as.
+ *
+ * A `decimal` field travels as a STRING on the wire, because JSON has one
+ * number type and every JavaScript consumer parses it into an IEEE-754 double
+ * whatever the server meant. Supabase demonstrates the failure: Postgres stores
+ * `numeric` exactly, PostgREST serialises it as a JSON number, and precision
+ * dies in `JSON.parse` before any application code runs. Exact storage with a
+ * lossy wire format buys nothing.
+ *
+ * So the string is the transport. It is deliberately NOT what you are handed:
+ * `"19.99" + "2.00"` is `"19.992.00"`, silently. This class is the thing that
+ * makes that unrepresentable.
+ *
+ * ---------------------------------------------------------------------------
+ * Representation
+ * ---------------------------------------------------------------------------
+ *
+ * A scaled `bigint`: `value = units / 10 ** scale`. `19.99` is
+ * `{ units: 1999n, scale: 2 }`. All arithmetic is integer arithmetic on
+ * `units`, so it is exact by construction rather than exact by care.
+ *
+ * `bigint` is ES2020 and the package targets ES2022, so this has NO dependency.
+ * That is deliberate: Prisma ships `Decimal.js` instances and prisma/prisma#16397
+ * has run for years because callers cannot get a `Decimal.js` whose version
+ * matches Prisma's. A type that crosses a package boundary should not carry a
+ * third party's identity with it.
+ *
+ * ---------------------------------------------------------------------------
+ * Scale is preserved, equality is numeric
+ * ---------------------------------------------------------------------------
+ *
+ * `decimal('19.90')` renders as `"19.90"`, not `"19.9"`. Trailing zeros are
+ * significant to anyone displaying money, and dropping them would make the
+ * round trip lossy in the one way people actually notice.
+ *
+ * But `equals` compares VALUES: `decimal('1.0').equals(decimal('1.00'))` is
+ * `true`. Textual comparison would be a trap of a different shape.
+ *
+ * ---------------------------------------------------------------------------
+ * Why `+` throws instead of concatenating
+ * ---------------------------------------------------------------------------
+ *
+ * `Symbol.toPrimitive` answers the `'string'` hint and throws on every other
+ * one. So:
+ *
+ * ```ts
+ * `Total: ${price}`     // "Total: 19.99"  — string hint, fine
+ * price + tax           // TypeError, naming .add()
+ * price > limit         // TypeError, naming .cmp()
+ * Number(price)         // TypeError, naming .toNumber()
+ * ```
+ *
+ * TypeScript already rejects `price + tax` at compile time. The throw is for
+ * JavaScript callers and for anything that reaches this through `any`, where a
+ * silent `"19.992.00"` would otherwise reach a customer. Loud beats quiet: the
+ * whole reason this type exists is that the float bug was silent.
+ *
+ * `JSON.stringify` is answered by `toJSON`, so a decimal serialises back to the
+ * canonical string it arrived as — `{"price":"19.99"}`, never `{"price":{}}`.
+ * Prisma's most common support thread is that this behaviour was left implicit;
+ * it is pinned by a test here.
+ *
+ * ---------------------------------------------------------------------------
+ * If you are caching, cloning or comparing these, read this
+ * ---------------------------------------------------------------------------
+ *
+ * **Treat a decimal as an opaque leaf.** The state lives in `#`-private fields,
+ * which are invisible to every structural walk:
+ *
+ * ```ts
+ * Object.keys(price)                   // []
+ * Object.keys(structuredClone(price))  // []   <- no throw. silently {}.
+ * ```
+ *
+ * So a generic deep-clone, structural-share or deep-equal sees an EMPTY OBJECT.
+ * `structuredClone` does not throw, it just returns `{}`, and any equality that
+ * walks own enumerable keys calls two different decimals equal. This is the one
+ * that fails quietly, which on money is the worst place for it.
+ *
+ * Identity is `instanceof`. Equality is `.equals()`. Cloning is unnecessary —
+ * every operation returns a new instance and nothing mutates, so share the
+ * reference.
+ *
+ * **A JSON round trip returns a string, not a decimal.** Lossless in value,
+ * lossy in type:
+ *
+ * ```ts
+ * JSON.parse(JSON.stringify(price))    // "19.99", a string
+ * ```
+ *
+ * Rehydrate at the boundary — `decimal(value)` takes the string, and the
+ * generated types say which fields are decimals, so the revive is keyed on the
+ * schema rather than sniffed.
+ *
+ * **Scale is display, not identity — so normalise KEYS, never PAYLOADS.**
+ * `decimal('1.0').equals(decimal('1.00'))` is true while their `toString()`
+ * differs. Two consequences that pull in opposite directions:
+ *
+ * - Keying a cache on `toString()` splits one value into two entries. If you
+ *   need a canonical key, `rescale()` to a fixed scale first.
+ * - But `rescale()` on a value you will SERVE rewrites what the author entered:
+ *   `19.90` becomes `19.9`, and a price changes how it displays. Never
+ *   normalise a stored payload.
+ *
+ * The cleanest way to hold both is to store the raw wire string and hydrate at
+ * the read boundary. The store then never holds two instances to choose
+ * between, and persistence is correct by construction.
+ */
+/**
+ * How to resolve a value sitting exactly halfway between two representable
+ * results. Only `div`, `toFixed` and `rescale` can produce one — `add`, `sub`
+ * and `mul` are always exact.
+ *
+ * - `half-even` — banker's rounding. Ties go to the even neighbour, so a long
+ *   run of them does not drift upward. The default for `div`, where the result
+ *   is usually an intermediate value that will be summed.
+ * - `half-up` — ties go away from zero. What a person means by "round to 2dp",
+ *   and the default for `toFixed`, which is a display operation.
+ * - `down` — truncate toward zero. Never rounds up, for the cases where over-
+ *   stating is the expensive direction.
+ */
+export type FoirDecimalRounding = 'half-even' | 'half-up' | 'down';
+/** Options for {@link FoirDecimal.div}. */
+export interface FoirDecimalDivOptions {
+    /**
+     * Decimal places in the result. Division is the one operation that cannot be
+     * exact — `1/3` has no finite decimal expansion — so a scale has to be named.
+     * Defaults to 20, which is wider than any currency and narrow enough to stay
+     * cheap.
+     */
+    scale?: number;
+    /** Defaults to `half-even`. */
+    rounding?: FoirDecimalRounding;
+}
+/** Anything that can be widened to a decimal without losing precision. */
+export type FoirDecimalInput = string | bigint | FoirDecimal;
+/**
+ * An exact decimal number.
+ *
+ * Construct from a string (the wire form), a `bigint`, or another decimal.
+ * A `number` is refused — see {@link FoirDecimal.fromNumber}.
+ */
+export declare class FoirDecimal {
+    #private;
+    constructor(value: FoirDecimalInput);
+    /**
+     * Build a decimal from a JavaScript number, accepting the precision that
+     * number may already have lost.
+     *
+     * Deliberately not the constructor. It is for interop — a value read from a
+     * third-party JSON API that emitted a float — and naming it at every call
+     * site is the point. `fromNumber(0.1 + 0.2)` gives `0.30000000000000004`,
+     * because that is genuinely the value it was handed.
+     */
+    static fromNumber(value: number): FoirDecimal;
+    /** `true` if `value` parses as a decimal. Does not throw. */
+    static isDecimalString(value: unknown): value is string;
+    /** Decimal places carried by this value. `19.90` has scale 2. */
+    get scale(): number;
+    /** Re-express at `scale`, rounding away any digits that no longer fit. */
+    rescale(scale: number, rounding?: FoirDecimalRounding): FoirDecimal;
+    add(other: FoirDecimalInput): FoirDecimal;
+    sub(other: FoirDecimalInput): FoirDecimal;
+    /** Exact: scales add, so `1.10 × 1.10` is `1.2100` rather than `1.21`. */
+    mul(other: FoirDecimalInput): FoirDecimal;
+    /** The only inexact operation — see {@link FoirDecimalDivOptions}. */
+    div(other: FoirDecimalInput, options?: FoirDecimalDivOptions): FoirDecimal;
+    abs(): FoirDecimal;
+    neg(): FoirDecimal;
+    isZero(): boolean;
+    isNegative(): boolean;
+    /** `-1`, `0` or `1`. Use this rather than `<`, which throws. */
+    cmp(other: FoirDecimalInput): -1 | 0 | 1;
+    /** Numeric equality: `1.0` equals `1.00`. Scale is display, not identity. */
+    equals(other: FoirDecimalInput): boolean;
+    /**
+     * Fixed-place string, rounding `half-up` by default because this is the
+     * display operation and that is what a person means by "to 2dp".
+     */
+    toFixed(places: number, rounding?: FoirDecimalRounding): string;
+    /**
+     * The canonical wire form, preserving scale. Never exponent notation, so the
+     * output always parses back to an equal value.
+     */
+    toString(): string;
+    /** `JSON.stringify` emits the canonical string, not an object. Pinned by test. */
+    toJSON(): string;
+    /**
+     * Explicitly lossy — this is the boundary back into float, and naming it is
+     * the point. Fine for a chart axis; never for money you will add up.
+     */
+    toNumber(): number;
+    /**
+     * Answers the `'string'` hint so template literals work, and throws on every
+     * other hint so `+`, `<` and `Number()` fail loudly instead of silently
+     * concatenating or truncating.
+     */
+    [Symbol.toPrimitive](hint: string): string;
+    get [Symbol.toStringTag](): string;
+}
+/**
+ * Shorthand for `new FoirDecimal(value)`.
+ *
+ * ```ts
+ * import { decimal } from '@foir/sdk/data';
+ *
+ * const total = decimal(product.price).mul('3').add(shipping);
+ * console.log(total.toFixed(2)); // "62.97"
+ * ```
+ */
+export declare function decimal(value: FoirDecimalInput): FoirDecimal;

package/dist/data/document.d.ts

@@ -215,7 +215,7 @@ export interface FoirNamespaceCall {
      * stopped in front of. Each level above 1 spends one of those stopping points.
      *
      * It is a BUDGET rather than a setting, though a much larger one since
-     * TTS-1448: on a real project the same op measures 318 fields at level 1, 468
+     * On a real project the same op measures 318 fields at level 1, 468
      * at level 2 and 618 at level 3, against a server ceiling of 10,000. Those
      * were 837 / 3,513 / 14,217 while a union position was charged every member it
      * could hold rather than the one a value can be.

package/dist/data/index.d.ts

@@ -37,21 +37,21 @@
  * const anything = await foir.raw('{ designTokens { name value } }');
  * ```
  *
- * `FoirSchema` comes from `foir types` (TTS-875). The contract it generates
+ * `FoirSchema` comes from `foir types`. The contract it generates
  * against is written down in `schema.ts` — read that file before changing
  * anything here, because a generator is written against it.
  */
-export { createFoirClient, createFoirClientFromEnv } from './client';
-export type { FoirClient, FoirClientCore, FoirModelClient, FoirNamespaceClient } from './client';
+export { createFoirClient, createFoirClientFromEnv, graphql } from './client';
+export type { FoirClient, FoirClientCore, FoirModelClient, FoirNamespaceClient, FoirRawOptions, TypedFoirDocument, } from './client';
 export { fetchFoirManifest } from './manifest';
-export type { FoirManifest, FoirManifestComposite, FoirManifestModel, FoirManifestNamespace, FoirManifestOp, FoirManifestOpPayload, FoirManifestRelation, FoirManifestScalar, FoirManifestSelection, FoirManifestSelectionField, FoirManifestSelectionMember, FoirManifestSelectionUnion, FoirManifestSubscription, FoirManifestSubscriptionArgScope, FoirManifestUnclassifiedField, } from './manifest';
+export type { FoirManifest, FoirManifestComposite, FoirManifestModel, FoirManifestNamespace, FoirManifestOp, FoirManifestOpPayload, FoirManifestRelation, FoirManifestScalar, FoirManifestSelection, FoirManifestSelectionField, FoirManifestSelectionMember, FoirManifestSelectionUnion, FoirManifestStructural, FoirManifestSubscription, FoirManifestSubscriptionArgScope, FoirManifestUnclassifiedField, } from './manifest';
 export { planFoirModelCall, planFoirNamespaceCall } from './document';
 export type { FoirCall, FoirDocumentPlan, FoirNamespaceCall, FoirNamespaceSelections, FoirRecordPath, FoirSelectionModel, FoirSelectionNamespace, FoirSelections, FoirSelectionSource, FoirSelectionUnions, } from './document';
 export { createFoirSubjectRegistry, recordFoirSubjects } from './subjects';
 export type { FoirSubject, FoirSubjectEntry, FoirSubjectOptions, FoirSubjectOrigin, FoirSubjectRegistry, } from './subjects';
-export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirCreateMyNoteArgs, FoirCustomerNote, FoirCustomerNoteAttachment, FoirDegraded, FoirDepthBelow, FoirDepthLevel, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirMyNotesArgs, FoirMyNotesResult, FoirNoteConfig, FoirNoteSubjectType, FoirPlatformType, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPoint, Image, ImageFormat, ImageVariant, ImageVariantSet, MediaValue, Reference, Richtext, Video, } from './builtins';
+export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirCreateMyNoteArgs, FoirSubmitAnonymousNoteArgs, FoirAnonymousNoteReceipt, FoirCustomerNote, FoirCustomerNoteAttachment, FoirDegraded, FoirDepthBelow, FoirDepthLevel, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirMyNotesArgs, FoirMyNotesResult, FoirNoteConfig, FoirNoteSubjectType, FoirPlatformType, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPoint, Image, ImageFormat, ImageVariant, ImageVariantSet, MediaValue, Passage, Prose, ProseSpan, RecordAncestor, Reference, Richtext, Video, } from './builtins';
 /**
- * Pre-TTS-1391 spellings. The `<Name>Block` wrappers and the `<Name>Value`
+ * Pre-rename spellings. The `<Name>Block` wrappers and the `<Name>Value`
  * split are the same thing as the types above — an item IS its value — so each
  * of these is an alias, not a separate shape.
  *
@@ -60,14 +60,16 @@ export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAcces
  * emits, so there is nothing for them to alias. See `builtins.ts`.
  */
 export type { FileBlock, GeoPointValue, ImageBlock, ImageValue, ReferenceBlock, ReferenceValue, RichtextBlock, RichtextValue, VideoBlock, VideoValue, } from './builtins';
-export { foirDataEndpoint, foirRoute } from './transport';
+export { FoirSchemaDriftError, foirDataEndpoint, foirRoute } from './transport';
 export type { FoirClientConfig, FoirGeneratedModule, FoirLane, FoirLaneReason, FoirRouteDecision, FoirRouteInput, FoirSchemaDrift, } from './transport';
 export { foirSocketEndpoint, FoirSocketTransport } from './ws-transport';
 export type { FoirReconnectPolicy, FoirSubscribeRequest, FoirSubscription, FoirSubscriptionHandlers, FoirWebSocketFactory, FoirWebSocketLike, } from './ws-transport';
 export { printSubscriptionDocument } from './subscription-document';
 export type { FoirSubscriptionArgument, PrintSubscriptionDocumentInput, } from './subscription-document';
-export type { FoirExecutionSubscribeOptions, FoirJobProgressEvent, FoirModelSubscriptions, FoirNamespaceSubscriptions, FoirNotificationEvent, FoirOperationExecutionEvent, FoirRecordChangedEvent, } from './subscriptions';
+export type { FoirChangeSubscribeOptions, FoirExecutionSubscribeOptions, FoirJobProgressEvent, FoirModelSubscriptions, FoirNamespaceSubscriptions, FoirNotificationEvent, FoirOperationExecutionEvent, FoirRecordChangedEvent, } from './subscriptions';
 export type { FoirConnection, FoirFieldsShape, FoirModelDefinition, FoirNamespaceDefinition, FoirNamespaceOpDefinition, FoirOpDefinition, FoirRelationDefinition, FoirReturnDefinition, FoirSchemaDefinition, } from './schema';
 export type { FoirInclude, FoirModelOperation, FoirNamespaceOperation, FoirOmittableKey, FoirOpResult, FoirQuery, FoirRecordResult, } from './selection';
+export { FoirDecimal, decimal } from './decimal';
+export type { FoirDecimalDivOptions, FoirDecimalInput, FoirDecimalRounding, } from './decimal';
 export { FoirRequestError } from '../transport/foir-http';
-export type { FoirEnv, FoirGraphQLErrorItem, FoirTokenProvider, } from '../transport/foir-http';
+export type { FoirEnv, FoirGraphQLErrorItem, FoirTokenProvider, FoirAuthDowngrade, } from '../transport/foir-http';

package/dist/data/manifest.d.ts

@@ -2,7 +2,7 @@
  * `GET /v1/manifest` — the per-caller surface descriptor, as a runtime type.
  *
  * This is the *runtime* mirror of `schema.ts`'s compile-time contract: what the
- * server actually sends, verbatim, so `foir types` (TTS-875) has a typed thing
+ * server actually sends, verbatim, so `foir types` has a typed thing
  * to read and the drift check has a version to compare. The manifest is already
  * the projection of `CachedSchema.SchemaForCaller(scopes)`, so what it lists is
  * exactly what this credential may do — no client-side filtering anywhere.
@@ -139,6 +139,23 @@ export interface FoirManifestOpPayload {
      */
     error?: string;
 }
+/**
+ * A platform-owned structural field: a prose wrapper, or the hierarchy walk's
+ * `ancestors`. Nested and always returned, like a composite — but there is no
+ * model behind it, so the entry names its TYPE (`Prose`, `ProseCta`,
+ * `RecordAncestor`) and the shape is `builtins.ts`'s.
+ *
+ * ABSENT on a server that predates the bucket, where these fields landed in
+ * `unclassifiedFields` and dropped out of the selection entirely. Widen on
+ * absent, as everywhere else in this file.
+ */
+export interface FoirManifestStructural {
+    key: string;
+    type: string;
+    list: boolean;
+    nullable: boolean;
+    deprecated?: boolean;
+}
 /** A built field the projection has no bucket for. Reported rather than dropped. */
 export interface FoirManifestUnclassifiedField {
     key: string;
@@ -172,12 +189,14 @@ export interface FoirManifestModel {
     scalars: FoirManifestScalar[];
     relations: FoirManifestRelation[];
     composites: FoirManifestComposite[];
+    /** Platform-owned structural fields — prose wrappers, `ancestors`. */
+    structurals?: FoirManifestStructural[];
     /**
-     * Block-union field key → member model keys. Members that are built-in block
-     * primitives appear under their lowercase token (`text`, `image`, `video`,
-     * `file`, `richtext`, `media`, `reference`, `flexible`) and have NO entry in
-     * `models` — they are platform-owned, identical in every project, and typed
-     * statically by `builtins.ts`.
+     * Union field key → member model keys. Members that are platform primitives
+     * appear under their lowercase token (`richtext`, `image`, `video`, `file`,
+     * `reference`, `geopoint`) and have NO entry in `models` — they are
+     * platform-owned, identical in every project, and typed statically by
+     * `builtins.ts`.
      */
     unions?: Record<string, string[]>;
     /** Op names of this model's typed lookups. Each also appears in `ops`. */
@@ -256,6 +275,14 @@ export interface FoirManifestNamespace {
 export interface FoirManifest {
     schemaVersion: number;
     channel: 'published' | 'draft';
+    /**
+     * The organisation whose composition this surface is, absent for the
+     * project's own. A credential confined to an organisation is served that
+     * organisation's surface without naming it, so this is how a reader of the
+     * manifest, or of a module generated from it, tells whose definitions it
+     * describes.
+     */
+    composedFor?: string;
     models: Record<string, FoirManifestModel>;
     /**
      * Keyed by namespace name (`auth`, `customers`, `files`, `notifications`,