@relyio/sdk 0.18.0 → 0.20.0

package/dist/{index-M3luH06A.d.ts → index-IjSyBr8f.d.ts}

@@ -1,6 +1,6 @@
-import { e as ApiPath, f as ApiMethod, Q as QueryOf, W as Wire, H as HttpClient, A as AnySchemaDefinition, l as RecordsClient, B as BaseRecord, y as RecordBatchOperation, C as RecordBatchOptions, b as RecordBatchResult, R as RegisteredSchema } from './register-B53i97A9.js';
-import { aU as EntryMetadata, ax as Reading, cQ as BaseContent, at as CheckedIncludes, dp as ReadWhere, cV as WhereClause, cw as components, ay as ReadWith, d4 as UpdateInput, aB as UntypedReading, c_ as RevisedContent, cY as CreateInput, cZ as CreatedContent, d3 as ContentVersionRow, d2 as ContentVersion, d1 as RestoredContent, cJ as SDKError, dl as BaseValidationError, dk as ValidationViolation, ba as AssetServedBlocks, dq as CheckedInclude, cU as WhereFieldCondition, cO as AssetFileBlock, cR as BaseSingleton, c$ as WrittenSingleton, cS as BaseSettingsGroup, d0 as WrittenSettingsGroup, aV as InferContentType, av as ContentReading, a$ as InferSingleton, cF as paths, cK as RelyIOConfig, b8 as InferAssetType, as as AssetReading, aA as SingletonReading, b4 as InferSettingsGroup, az as SettingsReading, cL as RelyIOConfigUpdate, cH as MergedRelyIOConfig } from './define-content-type-fb-WCD5e.js';
-import { a as SchemaContentTypeNames, l as SchemaEntryOf, c as SchemaLocaleCodes, h as SchemaSingletonNames, v as AggregateBlock, _ as QueryParameterValue, F as FullTextSearch, i as SchemaQueryNames, Z as InferQueryParams, $ as AnyQueryParameters, S as SchemaRecordTypeNames, I as InferRecordType, R as RecordWriteFieldsOf, d as RecordUpdateFieldsOf, k as SchemaAssetTypeNames, j as SchemaSettingsGroupNames } from './define-schema-Dlwh6l_J.js';
+import { b as ApiPath, c as ApiMethod, Q as QueryOf, W as Wire, H as HttpClient, F as FunctionFieldValues, R as Register, A as AnySchemaDefinition, h as RecordsClient, B as BaseRecord, v as RecordBatchOperation, x as RecordBatchOptions, y as RecordBatchResult, a as RegisteredSchema } from './index-D1fiaQlK.js';
+import { bi as EntryMetadata, aZ as Reading, da as BaseContent, aV as CheckedIncludes, dL as ReadWhere, df as WhereClause, ap as components, a_ as ReadWith, dr as UpdateInput, b1 as UntypedReading, dk as RevisedContent, di as CreateInput, dj as CreatedContent, dq as ContentVersionRow, dp as ContentVersion, dn as RestoredContent, d3 as SDKError, dI as BaseValidationError, dH as ValidationViolation, bw as AssetServedBlocks, dM as CheckedInclude, de as WhereFieldCondition, d8 as AssetFileBlock, db as BaseSingleton, dl as WrittenSingleton, dc as BaseSettingsGroup, dm as WrittenSettingsGroup, s as KeyedMembers, aB as InferContentType, aX as ContentReading, bn as InferSingleton, cW as paths, d4 as RelyIOConfig, bu as InferAssetType, aU as AssetReading, b0 as SingletonReading, br as InferSettingsGroup, a$ as SettingsReading, d5 as RelyIOConfigUpdate, cY as MergedRelyIOConfig } from './define-content-type-CVLUusfx.js';
+import { SchemaContentTypeNames, SchemaEntryOf, SchemaLocaleCodes, SchemaSingletonNames, AggregateBlock, QueryParameterValue, FullTextSearch, SchemaQueryNames, InferQueryParams, AnyQueryParameters, SchemaRecordTypeNames, InferRecordType, RecordWriteFieldsOf, RecordUpdateFieldsOf, SchemaAssetTypeNames, SchemaSettingsGroupNames } from './schema/index.js';
 import { DevUnreadableReason } from './dev-handshake/index.js';
 
 /**
@@ -65,70 +65,6 @@ type ActiveSandbox = Extract<SandboxState, {
     state: 'active';
 }>;
 
-/**
- * API4's two request headers, as the SDK's writes send them.
- *
- * `Idempotency-Key` is an option on every write whose route declares it (`idempotencyKey`), and the
- * SDK mints one when none is given. `If-Match` is never an option: a checked write builds it from
- * the entry it was read as (`versionCheckOf`), from the `_metadata` every read carries in its body
- * whether or not the edge cache served it (REL-2418). The SDK does not read the separate
- * `X-Entity-Tag` header, which the edge removes from what it stores; the API keeps sending it for
- * callers using plain HTTP (REL-2427). A batch operation carries its check in its own body, as
- * `ifMatch` (`batch/batch-operations.ts`, REL-2421).
- */
-interface RetryableWriteOptions {
-    /**
-     * A key that makes a retry of **this** write safe.
-     *
-     * A replay inside the service's window returns the original outcome rather
-     * than applying twice. The service derives that response from committed state
-     * pinned to the recorded version — it does not store bytes — so a replay after
-     * the version has been pruned is refused `RESOURCE_EXPIRED` rather than
-     * answered from a stale copy.
-     *
-     * **The SDK mints one when you do not.** It used to be caller-supplied and
-     * nothing else, which meant the default write carried no key while the retry
-     * loop replayed it anyway — the one mechanism that makes a replay safe was
-     * optional on the one path that needed it. Supply your own to make a key
-     * outlive the process: a job that may be restarted wants a key derived from
-     * the work, not one minted per call.
-     */
-    idempotencyKey?: string;
-}
-/**
- * An entry a read handed back, as much of it as a version check needs: its `_metadata`'s id, the
- * locale it was read in and the two counters it was read at (REL-2418).
- *
- * Every read carries these in its body, whether origin or the edge cache served it — the edge
- * removes only the separate `X-Entity-Tag` header from what it stores, so a check taken from that
- * header vanished after a cached read. A `Pick` of the document's `EntryMetadata`, so a counter the
- * API stops reporting stops compiling here.
- */
-interface ReadEntry {
-    readonly _metadata: Pick<EntryMetadata, 'id' | 'locale' | 'version' | 'sharedVersion'>;
-}
-/**
- * The version check a write takes from the entry it was read as: the entry's id, the locale it was
- * read in — which the write addresses, so a read negotiated from `Accept-Language` is written back
- * to that locale — and the `If-Match` tag over its two counters, spelled as the API mints it.
- */
-declare function versionCheckOf(entry: ReadEntry): {
-    id: string;
-    locale: string;
-    ifMatch: string;
-};
-
-/**
- * The client's locale as a sub-client holds it: a function it asks on every call, or a locale fixed
- * when it was built.
- *
- * `TypedRelyIOClient` hands every sub-client and builder a function over the configuration it holds,
- * so one taken before `updateConfig({ locale })` sends the locale the client holds when the call is
- * made, and none once `updateConfig({ locale: null })` has cleared it (REL-1453). A string is a locale
- * fixed at construction — a handle built directly, as the tests build one — and stays what it was.
- */
-type ClientLocale = string | (() => string | undefined);
-
 /**
  * Site-visitor live, declared once for everyone who speaks it (`live-layer-spec.md` decisions 15, 19
  * and 20; phase LV5): the wire a visitor's browser meets at `live.relyio.com`, and the two internal
@@ -229,6 +165,70 @@ type VisitorResyncReason = VisitorLedgerResyncReason | 'too-far-behind';
  */
 type VisitorRetry = 'stop' | 'retry' | 'back-off';
 
+/**
+ * API4's two request headers, as the SDK's writes send them.
+ *
+ * `Idempotency-Key` is an option on every write whose route declares it (`idempotencyKey`), and the
+ * SDK mints one when none is given. `If-Match` is never an option: a checked write builds it from
+ * the entry it was read as (`versionCheckOf`), from the `_metadata` every read carries in its body
+ * whether or not the edge cache served it (REL-2418). The SDK does not read the separate
+ * `X-Entity-Tag` header, which the edge removes from what it stores; the API keeps sending it for
+ * callers using plain HTTP (REL-2427). A batch operation carries its check in its own body, as
+ * `ifMatch` (`batch/batch-operations.ts`, REL-2421).
+ */
+interface RetryableWriteOptions {
+    /**
+     * A key that makes a retry of **this** write safe.
+     *
+     * A replay inside the service's window returns the original outcome rather
+     * than applying twice. The service derives that response from committed state
+     * pinned to the recorded version — it does not store bytes — so a replay after
+     * the version has been pruned is refused `RESOURCE_EXPIRED` rather than
+     * answered from a stale copy.
+     *
+     * **The SDK mints one when you do not.** It used to be caller-supplied and
+     * nothing else, which meant the default write carried no key while the retry
+     * loop replayed it anyway — the one mechanism that makes a replay safe was
+     * optional on the one path that needed it. Supply your own to make a key
+     * outlive the process: a job that may be restarted wants a key derived from
+     * the work, not one minted per call.
+     */
+    idempotencyKey?: string;
+}
+/**
+ * An entry a read handed back, as much of it as a version check needs: its `_metadata`'s id, the
+ * locale it was read in and the two counters it was read at (REL-2418).
+ *
+ * Every read carries these in its body, whether origin or the edge cache served it — the edge
+ * removes only the separate `X-Entity-Tag` header from what it stores, so a check taken from that
+ * header vanished after a cached read. A `Pick` of the document's `EntryMetadata`, so a counter the
+ * API stops reporting stops compiling here.
+ */
+interface ReadEntry {
+    readonly _metadata: Pick<EntryMetadata, 'id' | 'locale' | 'version' | 'sharedVersion'>;
+}
+/**
+ * The version check a write takes from the entry it was read as: the entry's id, the locale it was
+ * read in — which the write addresses, so a read negotiated from `Accept-Language` is written back
+ * to that locale — and the `If-Match` tag over its two counters, spelled as the API mints it.
+ */
+declare function versionCheckOf(entry: ReadEntry): {
+    id: string;
+    locale: string;
+    ifMatch: string;
+};
+
+/**
+ * The client's locale as a sub-client holds it: a function it asks on every call, or a locale fixed
+ * when it was built.
+ *
+ * `TypedRelyIOClient` hands every sub-client and builder a function over the configuration it holds,
+ * so one taken before `updateConfig({ locale })` sends the locale the client holds when the call is
+ * made, and none once `updateConfig({ locale: null })` has cleared it (REL-1453). A string is a locale
+ * fixed at construction — a handle built directly, as the tests build one — and stays what it was.
+ */
+type ClientLocale = string | (() => string | undefined);
+
 /**
  * Two read terms every read that takes them writes the same way: the children an entry embeds,
  * and the refusal of a condition on `_metadata`. Here once, for the list and entry reads
@@ -803,7 +803,7 @@ declare class FileValidationError extends BaseValidationError {
 }
 /** Constraints `validateFile` checks a file against (subset of the schema upload gate). */
 interface FileValidationConstraints {
-    /** Allowed MIME types (exact match). */
+    /** Allowed MIME types: exact (`image/png`) or a wildcard pattern (`image/*`), as a schema declares them. */
     allowedMimeTypes?: string[];
     /** Max size in bytes. */
     maxSizeBytes?: number;
@@ -1479,9 +1479,11 @@ declare class SettingsClient<T = BaseSettingsGroup, R extends Reading = UntypedR
  * runs the Function `checkout` that the key's Branch runs, on the key's Dataset, and answers its
  * output.
  *
- * Call it from your server with a secret key: a publishable key is refused
- * (`PublishableKeyRefusedError`), and a read-only key runs only a Function whose reach writes
- * nothing (`ReadOnlyKeyError`). A run whose code threw or was ended at a limit throws
+ * Call it from your server with a secret key. A publishable key calls only a Function declaring
+ * `endUsers` (spec 4, REL-3892) — with a signed-in End user's token (`getToken`) when it says
+ * `'required'` — and is refused any other (`PublishableKeyRefusedError`); a read-only secret key
+ * runs only a Function whose reach writes nothing (`ReadOnlyKeyError`). A call carrying an End
+ * user's token hands the run `run.endUser`, whatever the key. A run whose code threw or was ended at a limit throws
  * `FunctionRunFailedError`, and one that outlived the service's five-minute wait
  * `FunctionRunTimedOutError` — each naming the run (`runId`), whose record and console output Manage
  * serves. A call is never retried: a Function may write, and a second call would be a second run.
@@ -1502,15 +1504,56 @@ interface FunctionCallOptions {
      */
     idempotencyKey?: string;
 }
-/** One Function, called: its input, as its input Fields declare it, and its output. */
+/** One Function, called, before `Register` names the project's Functions: any input, any answer. */
 type FunctionCall = (input?: Record<string, unknown>, options?: FunctionCallOptions) => Promise<unknown>;
 /**
- * `relyio.functions`: every Function the key's Branch runs, by name. A name the Branch does not run
- * is refused by the service (`ResourceNotFoundError`), not here.
+ * One Function's input and output Fields, as the generated `schema.ts` registers them (REL-4059): the
+ * keyed record its file declares under `input`, and under `output` when it declares one.
  */
-type FunctionsAccessor = {
+interface RegisteredFunctionFields {
+    readonly input: KeyedMembers;
+    readonly output?: KeyedMembers;
+}
+/** What a registered Function's call answers: its output's values, or what its run returned when it declares none. */
+type OutputOf<F extends RegisteredFunctionFields> = F extends {
+    readonly output: infer O extends KeyedMembers;
+} ? FunctionFieldValues<O> : unknown;
+/**
+ * What a registered Function's call takes: its input Fields' values. A Function declaring no input
+ * field takes none — `{}` would take any key, since an empty object type has no excess-property check.
+ */
+type InputOf<F extends RegisteredFunctionFields> = [keyof FunctionFieldValues<F['input']>] extends [
+    never
+] ? {
+    readonly [field: string]: never;
+} : FunctionFieldValues<F['input']>;
+/**
+ * One registered Function, called: its input as its input Fields declare them — required when a
+ * field of it is, so a missing, misnamed or mistyped field is a type error — and its output.
+ */
+type TypedFunctionCall<F extends RegisteredFunctionFields> = {} extends InputOf<F> ? (input?: InputOf<F>, options?: FunctionCallOptions) => Promise<OutputOf<F>> : (input: InputOf<F>, options?: FunctionCallOptions) => Promise<OutputOf<F>>;
+/**
+ * `relyio.functions` over a project's Functions: exactly those registered, each typed by its Fields,
+ * or any name before `relyio generate-types` registered any. Generic on purpose, as
+ * `FunctionRecordTypeName` is: written over `Register` directly, the conditional can be resolved
+ * before the program's augmentation is in view.
+ */
+type FunctionsAccessorOf<R> = R extends {
+    readonly functions: infer F extends {
+        readonly [name: string]: RegisteredFunctionFields;
+    };
+} ? {
+    readonly [N in keyof F]: TypedFunctionCall<F[N]>;
+} : {
     readonly [name: string]: FunctionCall;
 };
+/**
+ * `relyio.functions`: every Function the key's Branch runs, by name. Once `relyio generate-types`
+ * has registered the project's Functions (`Register`'s `functions`), only those names are on it and
+ * each call is typed by its input and output Fields; before, any name, untyped. A name the Branch
+ * does not run is refused by the service (`ResourceNotFoundError`), not here.
+ */
+type FunctionsAccessor = FunctionsAccessorOf<Register>;
 
 /**
  * What the search family's routes answer, read from the committed document, and what a search over
@@ -2430,11 +2473,19 @@ interface DeployedContentType {
 }
 /**
  * The defaults `client.with()` gives the client it makes (REL-2417, Q9): the locale and the dataset
- * its reads and writes are in unless a call names its own. A locale is one the schema declares.
+ * its reads and writes are in unless a call names its own, and the End user's token function its
+ * requests ask in place of the parent's (REL-3882). A locale is one the schema declares.
  */
 interface ClientDefaults<TSchema extends AnySchemaDefinition | undefined = undefined> {
     readonly locale?: LocaleCodeOf<TSchema>;
     readonly dataset?: string;
+    /**
+     * The signed-in End user's token, asked for on every request this client sends — and every
+     * request of a client `with()` makes from it that names none — in place of the parent's
+     * `getToken`. `@relyio/react`'s provider hands it Clerk's `useAuth().getToken`. See
+     * `RelyIOConfig.getToken`.
+     */
+    readonly getToken?: () => Promise<string | null>;
 }
 /** The locale codes a client's reads may name: the schema's, or any where no schema types it. */
 type LocaleCodeOf<TSchema extends AnySchemaDefinition | undefined> = TSchema extends AnySchemaDefinition ? SchemaLocaleCodes<TSchema> : string;
@@ -2509,7 +2560,10 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * `createClient()` made, which reads its own.
      */
     private parent;
-    /** What `with()` gave this client over its parent's: the locale and dataset it names, and no other. */
+    /**
+     * What `with()` gave this client over its parent's: the locale, dataset and End user's token
+     * function it names, and no other.
+     */
     private defaults;
     /** The live edge's poll client id: chosen once, when first needed, and kept for this client's life. */
     private _liveClientId;
@@ -2565,7 +2619,9 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * all or none (REL-3774).
      *
      * A Record is an app's data, written by your server with a secret key and live the moment it
-     * lands; a publishable key is refused on every Record route (`PUBLISHABLE_KEY_REFUSED`).
+     * lands. A publishable key reads the Records a Record type's read Policy grants it (spec 4,
+     * REL-3883), and writes them only for the End user whose token it carries, as the type's write
+     * Policy allows (REL-3884); with no token it writes nothing (`PUBLISHABLE_KEY_REFUSED`).
      *
      * @example
      * ```typescript
@@ -2585,9 +2641,13 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * `FunctionRunFailedError` and one past five minutes `FunctionRunTimedOutError`, each naming the
      * run. Never retried: a Function may write.
      *
+     * Once `relyio generate-types` has run, its `schema.ts` registers each Function's input and output
+     * Fields (REL-4059): only the project's Functions are named here, and each call takes and answers
+     * what its Fields declare, so a misnamed or mistyped input field is a type error.
+     *
      * @example
      * ```typescript
-     * const { orderId } = (await relyio.functions.checkout({ cartId })) as { orderId: string }
+     * const { orderId } = await relyio.functions.checkout({ cartId })
      * ```
      */
     readonly functions: FunctionsAccessor;
@@ -2935,6 +2995,9 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * const { data } = await staging.content('post').list({ limit: 10 })
      *
      * const french = relyio.with({ locale: 'fr-FR' }) // ← autocompletes the schema's locales
+     *
+     * // Every request this one sends carries the signed-in End user's token (REL-3882)
+     * const visitor = relyio.with({ getToken: () => session.getToken() })
      * ```
      */
     with(defaults: ClientDefaults<TSchema>): TypedRelyIOClient<TSchema>;