@foir/sdk 0.9.0 → 0.11.0

package/dist/content/content-renderer.d.ts

@@ -15,7 +15,7 @@
  *
  * The "switch" is a typed object lookup. Exhaustiveness is enforced where the
  * registry is BUILT — against the exhaustive `ItemRegistry` type the codegen
- * plugin (EID-92) generates per project, so omitting an item type is a compile
+ * plugin generates per project, so omitting an item type is a compile
  * error there, not a runtime surprise here. The consumer can supply different
  * registries per surface (e.g. web vs email).
  *
@@ -24,8 +24,7 @@
  * A prose field holds ENTRIES. A modeller may name the field `blocks`,
  * `sections`, `modules` or anything else, and this renderer must not care:
  * dispatch is on `__typename` and never on a field name. The `Block*` spellings
- * below are deprecated aliases kept so existing consumers compile — see
- * TTS-1391.
+ * below are deprecated aliases kept so existing consumers compile.
  */
 import { type ReactNode } from 'react';
 import { type PassageLike } from './richtext';
@@ -41,7 +40,7 @@ export interface ItemComponentProps<TItem, TCtx = unknown> {
     /**
      * The same value as `item`.
      *
-     * @deprecated Use `item`. Kept so components scaffolded before TTS-1391
+     * @deprecated Use `item`. Kept so components scaffolded before the rename
      * keep compiling; it is passed on every render and will be removed in a
      * future major.
      */
@@ -67,7 +66,7 @@ export interface EntriesLike {
  * The prose field's entries — the projection wrapper (`{ entries }`), or a
  * plain array — plus the context threaded to every component.
  *
- * `items` is canonical. `blocks` is the pre-TTS-1391 spelling and still
+ * `items` is canonical. `blocks` is the pre-rename spelling and still
  * accepted; passing both is a type error rather than a silent precedence rule,
  * because a caller who set both cannot be told which one this honoured.
  */

package/dist/content/index.d.ts

@@ -9,7 +9,7 @@
 export { createContentRenderer } from './content-renderer';
 export type { ItemLike, EntriesLike, ItemComponent, ItemComponentProps, ItemRegistry, ContentRendererProps, ContentRendererOptions, PassageRunProps, } from './content-renderer';
 /**
- * Pre-TTS-1391 spellings. `Block` was one project's name for a flexible field,
+ * Pre-rename spellings. `Block` was one project's name for a flexible field,
  * never a platform concept; these are kept so existing consumers compile and
  * will be removed in a future major.
  */

package/dist/content/richtext.d.ts

@@ -25,7 +25,7 @@
 import { type ReactNode, type JSX } from 'react';
 /**
  * safeHref allow-lists link schemes so stored prose can't smuggle a
- * `javascript:` (or `data:`/`vbscript:`) URL that executes on click (EID-207).
+ * `javascript:` (or `data:`/`vbscript:`) URL that executes on click.
  * Relative URLs, anchors, and the http(s)/mailto/tel schemes pass; anything
  * else collapses to '#'. Editors are not fully trusted, so this runs on the
  * structured render path, not only the html fallback.

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.
@@ -215,7 +215,7 @@ export interface RecordAncestor {
  * 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
@@ -286,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.
@@ -367,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
@@ -423,13 +423,30 @@ export interface FoirResourceAccess {
     public: boolean;
     visibility: FoirVisibility;
 }
-/** `updateMany` — how many rows moved, and which. */
+/**
+ * `updateMany`: how many rows moved, and which. `replayed` is true when the
+ * call's `idempotencyKey` was already used by an earlier attempt of the same
+ * update: nothing moved this time, and `count` and `ids` are that attempt's.
+ */
 export interface FoirUpdateManyPayload {
     count: number;
     ids: string[];
+    replayed: boolean;
+}
+/**
+ * `setOwner`: who the record belongs to after an operation handed it to
+ * another customer. It carries the owner and not the record, because the
+ * operation may have been acting for the previous holder, who can no longer
+ * read it. `ownerKind` is always `'customer'` from this op.
+ */
+export interface FoirRecordOwner {
+    id: string;
+    ownerId: string;
+    ownerKind: 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
@@ -440,10 +457,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';
 /**
@@ -550,6 +571,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

@@ -23,8 +23,9 @@
  * 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 individual fields (`surfaceVersion`, `surfaceHashes`, `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
@@ -47,7 +48,7 @@
  * ---------------------------------------------------------------------------
  *
  * The trees ARE runtime data — that is the one thing the generated module has to
- * carry across the type/value boundary, alongside `foirSchemaVersion`. Passing
+ * carry across the type/value boundary, alongside `foirSurfaceVersion`. Passing
  * them in costs nothing and is the intended path.
  *
  * When they are absent the client fetches `GET /v1/manifest` once, at first use,
@@ -75,7 +76,7 @@
 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 FoirClientConfig, type FoirKeyGeneratedModule, type FoirKeyClientConfig } from './transport';
 import { type FoirModelSubscriptions, type FoirNamespaceSubscriptions } from './subscriptions';
 /**
  * The ops available on one model for this credential, plus its subscriptions.
@@ -95,6 +96,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 +195,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.
      *
@@ -150,8 +231,9 @@ export declare function createFoirClient<S extends FoirSchemaDefinition = FoirSc
  * `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.
+ * set of variables. Preview picks `PLATFORM_PREVIEW_API_KEY`, the preview
+ * environment's own key holding `drafts:read`, and the draft schema channel,
+ * exactly as `foirRequest` does.
  *
  * ```ts
  * import * as generated from './foir.generated';
@@ -161,6 +243,7 @@ export declare function createFoirClient<S extends FoirSchemaDefinition = FoirSc
  * `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>;
+export declare function createFoirClientFromEnv<S extends FoirSchemaDefinition = FoirSchemaDefinition>(env: FoirEnv, overrides?: Omit<FoirKeyClientConfig, 'apiUrl' | 'apiKey' | 'channel' | 'generated'> & {
+    generated?: FoirKeyGeneratedModule<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.
@@ -237,6 +237,19 @@ export interface FoirNamespaceCall {
  * shape for, and inventing one is what this design exists to stop.
  */
 export declare function planFoirModelCall(source: FoirSelectionSource, call: FoirCall): FoirDocumentPlan;
+/**
+ * A create's arguments with an idempotency key, when the server's create takes
+ * one and the caller sent none.
+ *
+ * The key is made here, before the first attempt, so a retry of the same call
+ * carries the same key and the platform answers it with the record the first
+ * attempt made rather than making a second. A key made on the server would be
+ * new on every attempt, and one derived from the request would merge two
+ * deliberate, identical creates into one. A caller that sends its own key keeps
+ * it, and an update is left alone: an increment's key is the caller's to
+ * choose, since only the caller knows which calls are the same one.
+ */
+export declare function withCreateIdempotencyKey(source: FoirSelectionSource, model: string, op: string, args: Record<string, unknown>): Record<string, unknown>;
 /**
  * Turn a namespace call into a document.
  *