@foir/sdk 0.9.0 → 0.11.0

package/dist/data/index.d.ts

@@ -37,21 +37,31 @@
  * const anything = await foir.raw('{ designTokens { name value } }');
  * ```
  *
- * `FoirSchema` comes from `foir types` (TTS-875). The contract it generates
+ * Inside an operation endpoint the client is built from the dispatch instead of
+ * a key, and calls Foir as the operation, with the module `foir types
+ * --operation <key>` generated for that operation:
+ *
+ * ```ts
+ * const { dispatch } = await requireScopedToken(request, { expectedProjectId });
+ * const foir = createFoirClient({ apiUrl, dispatch, generated });
+ * ```
+ *
+ * `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 { FoirManifestRequestOptions } 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, Passage, Prose, ProseSpan, RecordAncestor, 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, FoirRecordOwner, 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 +70,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 type { FoirClientConfig, FoirGeneratedModule, FoirLane, FoirLaneReason, FoirRouteDecision, FoirRouteInput, FoirSchemaDrift, } from './transport';
+export { FoirSchemaDriftError, foirDataEndpoint, foirRoute } from './transport';
+export type { FoirClientConfig, FoirDispatchClientConfig, FoirDispatchCredential, FoirGeneratedModule, FoirKeyClientConfig, FoirKeyGeneratedModule, FoirLane, FoirLaneReason, FoirOperationCredential, FoirOperationGeneratedModule, FoirRequestConfig, 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 type { FoirInclude, FoirModelOperation, FoirNamespaceOperation, FoirOmittableKey, FoirOpResult, FoirQuery, FoirRecordResult, FoirWriteResult, } 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.
@@ -14,7 +14,7 @@
  * (`api-public/internal/schema/manifest.go`) field for field; where the two
  * disagree the platform is right and this file is the bug.
  */
-import { type FoirClientConfig } from './transport';
+import { type FoirRequestConfig } from './transport';
 export interface FoirManifestScalar {
     key: string;
     /**
@@ -273,8 +273,34 @@ export interface FoirManifestNamespace {
     ops?: Record<string, FoirManifestOp>;
 }
 export interface FoirManifest {
+    /**
+     * The invalidation counter for this project and channel. Every write that
+     * could change a response moves it, including the many that change nothing
+     * here, so it keys the ETag and the server's caches and nothing on the client
+     * is pinned to it.
+     */
     schemaVersion: number;
+    /**
+     * A hash over exactly the sections `foir types` reads, so it moves if and only
+     * if regenerating the types would write a different file. The generated
+     * module records it, and the drift check compares the two.
+     */
+    surfaceVersion: string;
+    /**
+     * The components `surfaceVersion` is folded from, keyed by where each sits in
+     * this body: `models.<key>`, `namespaces.<name>`, `selectionUnions.<name>`,
+     * `subscriptions`, `composedFor`. A drift names what moved by comparing these.
+     */
+    surfaceHashes: Record<string, string>;
     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`,
@@ -433,11 +459,21 @@ export interface FoirManifestSelectionMember {
     typeName: string;
     fields: FoirManifestSelectionField[];
 }
+/** What a manifest request asks for beyond the credential's own surface. */
+export interface FoirManifestRequestOptions {
+    /**
+     * Describe the surface this operation's dispatch token is served instead of
+     * the credential's own (`GET /v1/manifest?operation=<key>`). Answered to a
+     * credential that can author the operation (one holding `operations:write`)
+     * and refused to any other. `foir types --operation` sends it.
+     */
+    operation?: string;
+}
 /**
  * Fetch the manifest for the credential in `config`.
  *
  * Exported because two things outside this file need it: `foir types` reads it
  * to generate `FoirSchema`, and the client's drift check reads its
- * `schemaVersion`. Both would otherwise hand-roll the same fetch.
+ * `surfaceVersion`. Both would otherwise hand-roll the same fetch.
  */
-export declare function fetchFoirManifest(config: FoirClientConfig): Promise<FoirManifest>;
+export declare function fetchFoirManifest(config: FoirRequestConfig, options?: FoirManifestRequestOptions): Promise<FoirManifest>;

package/dist/data/schema.d.ts

@@ -2,7 +2,7 @@
  * THE `FoirSchema` CONTRACT.
  *
  * `createFoirClient<FoirSchema>()` is parameterised by a type that `foir types`
- * (TTS-875) emits from `GET /v1/manifest`. This file is that contract: the
+ * emits from `GET /v1/manifest`. This file is that contract: the
  * shape the generator writes and the shape the client reads. It is the only
  * coupling between the two, so it is written down here rather than living in
  * the generator's head.
@@ -19,7 +19,7 @@
  * ```
  *
  * A `.ts` and not a `.d.ts` because the file has a runtime half — the selection
- * trees, `foirSchemaVersion`, and `foirSchemaType`, which is what carries
+ * trees, `foirSurfaceVersion`, and `foirSchemaType`, which is what carries
  * `FoirSchema` across the type/value boundary so the client can infer it (a
  * namespace import carries values; an interface erases). `FoirGeneratedModule`
  * in `transport.ts` is the shape those exports have to satisfy, and it requires
@@ -30,8 +30,9 @@
  * // foir.generated.ts — DO NOT EDIT. Generated by `foir types`.
  * import type { FoirSchemaDefinition } from '@foir/sdk/data';
  *
- * /** `schemaVersion` from the manifest these types were generated from. *\/
- * export const foirSchemaVersion = 317;
+ * /** The surface these types were generated from. *\/
+ * export const foirSurfaceVersion = '6f1c0d2a9b8e4f7c3a5d1e0b2c4f6a8d';
+ * export const foirSurfaceHashes: Record<string, string> = { 'models.tilly_block': '…' };
  * export const foirSchemaChannel = 'published';
  *
  * // `<D>` ONLY on the types between the record and a union stopping point —
@@ -71,7 +72,7 @@
  * }
  *
  * export interface FoirSchema extends FoirSchemaDefinition {
- *   schemaVersion: typeof foirSchemaVersion;
+ *   surfaceVersion: typeof foirSurfaceVersion;
  *   channel: 'published';
  *   models: {
  *     tilly_block: {
@@ -161,7 +162,7 @@
  * 8. **`raw` and `ns` are reserved top-level names.** They are the escape hatch
  *    and the namespace accessor on the client object. A model whose key is
  *    `raw` or `ns` would collide; the server should reject those model keys at
- *    create time (noted in TTS-868's "Known limits").
+ *    create time (a known limit).
  *
  * 9. **`models` and `namespaces` must be object type LITERALS, not named
  *    `interface`s.** TypeScript gives an implicit index signature to object
@@ -211,10 +212,16 @@ export interface FoirRelationDefinition {
     /** True when the relation itself can resolve null. */
     readonly nullable: boolean;
 }
-/** How an op's result wraps (or does not wrap) the model. */
+/**
+ * How an op's result wraps (or does not wrap) the model. `write` is a record
+ * write's result: the record, and whether the answer is a replay (see
+ * `FoirWriteResult`).
+ */
 export type FoirReturnDefinition = {
     readonly kind: 'record';
     readonly nullable: boolean;
+} | {
+    readonly kind: 'write';
 } | {
     readonly kind: 'connection';
 } | {
@@ -282,12 +289,12 @@ export interface FoirNamespaceDefinition {
  */
 export interface FoirSchemaDefinition {
     /**
-     * `schemaVersion` from the manifest these types were generated from. Kept as
+     * `surfaceVersion` from the manifest these types were generated from. Kept as
      * a literal so a human reading the generated file sees it, and mirrored by a
-     * runtime `foirSchemaVersion` const for drift detection — the type cannot be
-     * read at runtime.
+     * runtime `foirSurfaceVersion` const for drift detection, because the type
+     * cannot be read at runtime.
      */
-    readonly schemaVersion: number;
+    readonly surfaceVersion: string;
     readonly channel: 'published' | 'draft';
     readonly models: Readonly<Record<string, FoirModelDefinition>>;
     readonly namespaces: Readonly<Record<string, FoirNamespaceDefinition>>;

package/dist/data/selection.d.ts

@@ -428,11 +428,26 @@ type WrapRelation<R extends FoirRelationDefinition, T> = R['list'] extends true
 export type FoirRecordResult<S extends FoirSchemaDefinition, M extends FoirModelDefinition, Q, D extends number = IncludeDepth, Depth extends number = DepthOf<Q>> = Q extends {
     include: infer I;
 } ? ApplySelection<M, Q, Depth> & IncludedRelations<S, M, I, D, Depth> : ApplySelection<M, Q, Depth>;
+/**
+ * What a record write (`create`, `update`, `rename`) answers with.
+ *
+ * `replayed` is true when the call carried an `idempotencyKey` an earlier
+ * attempt of the same write already used: the platform wrote nothing this time
+ * and `record` is as that first attempt left it. A caller that acts on the
+ * result (a stock count read back after a take, say) checks it, because a
+ * replayed answer looks exactly like a fresh one.
+ */
+export interface FoirWriteResult<R> {
+    record: R;
+    replayed: boolean;
+}
 /** Apply an op's return wrapper to the shaped record. */
 export type FoirOpResult<S extends FoirSchemaDefinition, M extends FoirModelDefinition, O extends FoirOpDefinition, Q> = O['returns'] extends {
     kind: 'opaque';
     type: infer T;
 } ? T : O['returns'] extends {
+    kind: 'write';
+} ? FoirWriteResult<FoirRecordResult<S, M, Q>> : O['returns'] extends {
     kind: 'connection';
 } ? FoirConnection<FoirRecordResult<S, M, Q>> : O['returns'] extends {
     kind: 'list';

package/dist/data/subscriptions.d.ts

@@ -38,13 +38,17 @@
  * carries a resolved selection tree, which `subscription-document.ts` prints
  * with the same walk the query path prints models with.
  *
- * A subscribing client therefore fetches the descriptor once even when
- * `config.selections` was supplied, because `selections` carries MODEL trees and
- * nothing generates subscription ones yet. That is a real cost and it is stated
- * rather than hidden — but it is ONE fetch, memoised across every subscription
- * and shared with the query path, sitting behind a long-lived socket. `client.ts`
- * rejects a round trip in front of every query for good reason; in front of a
- * socket that will live for minutes it is noise.
+ * A client built with `foirSubscriptions` makes no request at all: `client.ts`
+ * hands this an already-resolved descriptor instead of the fetcher, and the
+ * printer cannot tell the difference — it is the same shape either way, which is
+ * why nothing in this file changed when that landed.
+ *
+ * Without them it fetches once, which is what every client did before `foir
+ * types` emitted subscription trees and what a module generated before that
+ * still does. It is ONE fetch, memoised across every subscription and shared
+ * with the query path, sitting behind a long-lived socket. `client.ts` rejects a
+ * round trip in front of every query for good reason; in front of a socket that
+ * will live for minutes it is noise.
  */
 import type { FoirManifest } from './manifest';
 import type { FoirClientConfig } from './transport';
@@ -88,8 +92,12 @@ export interface FoirJobProgressEvent {
 /** `operationExecution` / `operation{Op}Execution` — one execution's progress. */
 export interface FoirOperationExecutionEvent {
     id: string;
-    /** `pending`, `dispatched`, `running`, `completed`, `failed`, `cancelled` or `timed_out`. */
-    status: string;
+    /**
+     * The same spelling `operationExecution` and `operationExecutions` return for
+     * the run, so one comparison serves a read and an event. The socket carries
+     * the platform's lowercase value; this client hands it over as the enum name.
+     */
+    status: 'PENDING' | 'DISPATCHED' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'TIMED_OUT';
     /** 0-100; null on terminal events. */
     progressPct?: number | null;
     progressMessage?: string | null;
@@ -117,6 +125,24 @@ export type FoirExecutionSubscribeOptions = FoirSubscriptionHandlers<FoirOperati
      */
     operation?: string;
 };
+/**
+ * What `onChange` takes: the handlers, plus the optional resume cursor.
+ *
+ * `after` is the highest `seq` this consumer has already applied. Passing it
+ * makes the stream cursor-resumable — the server replays what came after it
+ * from the durable log before continuing live, so a message lost anywhere
+ * upstream is repaired by the next connect rather than left as a permanently
+ * stale cache entry. Omitting it is the stream as it has always been: live from
+ * the moment you connect.
+ *
+ * The two refusals it can produce — a cursor older than the retention window,
+ * or one further behind than the surface will page — arrive on `onError` with a
+ * machine-readable code, and both mean the cache must be thrown away rather
+ * than partially repaired. `@foir/sdk/live` classifies them.
+ */
+export type FoirChangeSubscribeOptions = FoirSubscriptionHandlers<FoirRecordChangedEvent> & {
+    after?: number;
+};
 /** The subscriptions a model accessor carries. */
 export interface FoirModelSubscriptions {
     /**
@@ -125,7 +151,7 @@ export interface FoirModelSubscriptions {
      * The socket refuses a model this credential may not read, but the model is
      * not in `FoirSchema` in that case, so the refusal is a type error first.
      */
-    onChange(handlers: FoirSubscriptionHandlers<FoirRecordChangedEvent>): FoirSubscription;
+    onChange(options: FoirChangeSubscribeOptions): FoirSubscription;
 }
 /**
  * The subscriptions one namespace carries, by name.