@foir/sdk 0.10.0 → 0.12.0

package/dist/codegen/preset.d.ts

@@ -21,9 +21,10 @@ export interface FoirCodegenOptions {
      */
     apiKey?: string;
     /**
-     * Preview (`sk_`) key with `drafts:read`. Reads the DRAFT schema channel so
+     * Preview key holding `drafts:read`. Reads the DRAFT schema channel so
      * freshly pushed (un-promoted) model changes are visible to codegen.
-     * Strongly preferred — a `pk_` key only sees the published schema.
+     * Strongly preferred: a key without `drafts:read` only sees the published
+     * schema.
      */
     previewKey?: string;
     /** Output directory for the generated client types. Default `./app/gql/foir/`. */

package/dist/data/builtins.d.ts

@@ -423,10 +423,26 @@ 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 customer's note can be ABOUT: the customer-plane subset of the closed

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.
@@ -230,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';
@@ -241,7 +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/document.d.ts

@@ -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.
  *

package/dist/data/index.d.ts

@@ -37,6 +37,15 @@
  * const anything = await foir.raw('{ designTokens { name value } }');
  * ```
  *
+ * 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.
@@ -44,12 +53,13 @@
 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, 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';
+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-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
@@ -61,15 +71,15 @@ export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAcces
  */
 export type { FileBlock, GeoPointValue, ImageBlock, ImageValue, ReferenceBlock, ReferenceValue, RichtextBlock, RichtextValue, VideoBlock, VideoValue, } from './builtins';
 export { FoirSchemaDriftError, foirDataEndpoint, foirRoute } from './transport';
-export type { FoirClientConfig, FoirGeneratedModule, FoirLane, FoirLaneReason, FoirRouteDecision, FoirRouteInput, FoirSchemaDrift, } 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 { 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, FoirAuthDowngrade, } from '../transport/foir-http';
+export { FoirRequestError, FoirAuthDowngradedError, FoirSessionExpiredError, FOIR_VISITOR_IP_HEADER, } from '../transport/foir-http';
+export type { FoirEnv, FoirGraphQLErrorItem, FoirTokenProvider, FoirAuthDowngrade, FoirVisitorSource, } from '../transport/foir-http';

package/dist/data/manifest.d.ts

@@ -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,7 +273,25 @@ 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
@@ -441,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

@@ -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: {
@@ -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';