@relyio/sdk 0.18.0 → 0.19.0

package/dist/automations/index.d.ts

@@ -1,8 +1,7 @@
-import { ConditionScalar, ConditionTest, ConditionTree, ConditionTests } from '../schema/index.js';
+import { cH as ConditionScalar, cI as ConditionTest, cK as ConditionTree, cJ as ConditionTests, r as KeyedMembers, an as FieldValues, ao as DeclaredFields, s as KeyedMembersOf, cM as ExtensionSurfaces, cN as ExtensionSettingField, cO as ExtensionSurface, cP as ActionField, cQ as ExtensionValueField, y as ReferenceConfig, o as KeyedFieldOptions, n as KeyedField, cx as FileUpload } from '../define-content-type-C12jh8cY.js';
+import { A as AnySchemaDefinition, R as RegisteredSchema, B as BaseRecord, a as RecordBatchTarget, b as RecordBatchResult, c as Register, d as RecordConditionValue } from '../register-BiMQKVp-.js';
+import { i as SchemaRecordTypeNames, I as InferRecordType, b as SchemaContentTypeNames, j as SchemaEntry, f as SchemaLocaleCodes, r as RecordWriteFieldsOf, q as RecordUpdateFieldsOf } from '../define-schema-CK7TtYot.js';
 export { fields } from '../schema/index.js';
-import { A as AnySchemaDefinition, R as RegisteredSchema, B as BaseRecord, a as RecordBatchTarget, b as RecordBatchResult, c as RecordConditionValue } from '../register-B53i97A9.js';
-import { S as SchemaRecordTypeNames, I as InferRecordType, a as SchemaContentTypeNames, b as SchemaEntry, c as SchemaLocaleCodes, R as RecordWriteFieldsOf, d as RecordUpdateFieldsOf } from '../define-schema-Dlwh6l_J.js';
-import { K as KeyedMembers, F as FieldValues, D as DeclaredFields, a as KeyedMembersOf, b as FileUpload } from '../define-content-type-fb-WCD5e.js';
 import '../rich-text.d-BWc-5gX1.js';
 
 /**
@@ -600,7 +599,7 @@ interface StepWithOutput<O> extends StepHandle {
     readonly output: Ref<O>;
 }
 /** A Field set's values, as a Function's and an Agent step's output Fields declare them. */
-type ValuesOf$1<F extends KeyedMembers> = FieldValues<DeclaredFields<{
+type ValuesOf$2<F extends KeyedMembers> = FieldValues<DeclaredFields<{
     readonly fields: readonly KeyedMembersOf<F>[];
 }>>;
 /** What `step.agent` takes. */
@@ -770,9 +769,9 @@ interface StepBuilder {
      * Ask an agent to read, answer the declared Fields and propose one change to the types `propose`
      * names. Nothing it proposes is written until an Ask approves it (`step.ask(…, { approve })`).
      */
-    agent<const O extends KeyedMembers>(name: string, config: ProposingAgentStepConfig<O>): StepWithOutput<ProposingOutput<ValuesOf$1<O>>>;
+    agent<const O extends KeyedMembers>(name: string, config: ProposingAgentStepConfig<O>): StepWithOutput<ProposingOutput<ValuesOf$2<O>>>;
     /** Ask an agent to read and answer the declared Fields. It reads; it never writes or sends. */
-    agent<const O extends KeyedMembers>(name: string, config: AgentStepConfig<O>): StepWithOutput<ValuesOf$1<O>>;
+    agent<const O extends KeyedMembers>(name: string, config: AgentStepConfig<O>): StepWithOutput<ValuesOf$2<O>>;
     /** Send through an Extension's Action, from the events worker; Recorded in a Preview without its Connection. */
     action<I, O>(name: string, action: AutomationAction<I, O>, input: StepInput<I>): StepWithOutput<O>;
     /**
@@ -863,6 +862,249 @@ declare function isAutomationFile(value: unknown): value is AutomationFile;
  */
 declare function resolveAutomation(file: AutomationFile, nameOf: (fn: FunctionDefinition) => string | undefined): AutomationDefinition;
 
+/**
+ * `@relyio/sdk/extensions` — the Extensions a Project uses (spec 3, REL-3846; ADR 0019).
+ *
+ * One file, `relyio/extensions.ts`, names each Extension the Project uses and its settings — set once
+ * for the Project, never per Environment — and hands out a typed handle for each. An Automation
+ * imports the handle: its Triggers start an Automation (`on: vercel.deploymentSucceeded()`), and its
+ * Actions are what `step.action` sends through, their input and output typed by the Extension.
+ *
+ * @example
+ * // relyio/extensions.ts
+ * import { defineExtensions } from '@relyio/sdk/extensions'
+ *
+ * const extensions = defineExtensions({
+ *   slack: { defaultChannel: '#orders' },
+ *   vercel: {},
+ * })
+ * export const { slack, vercel } = extensions
+ * export default extensions
+ *
+ * **Never a secret here.** A Connection — an API key, a signing secret, a webhook URL — is made in
+ * the Dashboard, once per Environment, and sealed. A setting is text anyone reading the repository
+ * may see. Declaring an Extension connects nothing: `relyio plan` says which still need connecting
+ * in Production, and which Automations will deploy paused there until they are. Preview never pauses:
+ * an Action with no Preview Connection is Recorded with its sample result.
+ *
+ * **Typed.** Each Extension's settings, Actions and Triggers are RelyIO's own declaration of it
+ * (`@relyio/api-contract`'s `EXTENSION_SURFACES`, which the Extension catalog delivers): an Extension
+ * RelyIO does not have, a setting it does not declare, or a value its setting does not take — a
+ * Slack channel without its `#` — is a type error, and the plan refuses it again for a Manifest read
+ * as data.
+ */
+
+/** One Extension a Project uses: its settings, by key. */
+interface ExtensionUse {
+    readonly settings: Readonly<Record<string, string>>;
+}
+/** What `relyio/extensions.ts` declares, as data: every Extension the Project uses, by slug. */
+type ExtensionsDeclaration = Readonly<Record<string, ExtensionUse>>;
+/** Every Extension a Project may declare, and what its code may name of each. */
+type Surfaces = ExtensionSurfaces;
+/** The value one setting takes: one of its options, text starting with its prefix, or text. */
+type SettingValue<F extends ExtensionSettingField> = F extends {
+    readonly type: 'select';
+    readonly options: ReadonlyArray<infer Option>;
+} ? Option : F extends {
+    readonly type: 'text';
+    readonly prefix: infer Prefix extends string;
+} ? `${Prefix}${string}` : string;
+type Flatten<T> = {
+    readonly [K in keyof T]: T[K];
+};
+/** The settings an Extension takes: its required ones required, the rest optional, nothing else. */
+type SettingsFrom<F extends ExtensionSettingField> = Flatten<{
+    readonly [Field in F as Field extends {
+        readonly required: true;
+    } ? Field['key'] : never]: SettingValue<Field>;
+} & {
+    readonly [Field in F as Field extends {
+        readonly required: true;
+    } ? never : Field['key']]?: SettingValue<Field>;
+}>;
+/**
+ * The settings `defineExtensions` takes for Extension `S`. An Extension with none takes `{}` and
+ * nothing in it.
+ */
+type ExtensionSettings<S extends keyof Surfaces> = [
+    Surfaces[S]['settings'][number]
+] extends [never] ? Readonly<Record<string, never>> : SettingsFrom<Surfaces[S]['settings'][number]>;
+/** What `defineExtensions` takes: each Extension the Project uses, by slug, with its settings. */
+type ExtensionsConfig = {
+    readonly [S in keyof Surfaces]?: ExtensionSettings<S>;
+};
+/** A value field's JSON type, as TypeScript reads it. */
+type JsonOf<T extends ExtensionValueField['type']> = T extends 'string' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : T extends 'array' ? readonly unknown[] : Readonly<Record<string, unknown>>;
+/** A dot-separated path's first segment. */
+type Head<P extends string> = P extends `${infer First}.${string}` ? First : P;
+/** The fields whose path starts with segment `K`. */
+type Under<F extends ExtensionValueField, K extends string> = F extends ExtensionValueField ? Head<F['path']> extends K ? F : never : never;
+/** The fields under `K`, their paths with `K.` taken off; never for the field at `K` itself. */
+type Rebased<F extends ExtensionValueField, K extends string> = F extends ExtensionValueField ? F['path'] extends `${K}.${infer Rest}` ? Omit<F, 'path'> & {
+    readonly path: Rest;
+} : never : never;
+/** A field's value: its JSON type, and an object of strings for one declaring string values. */
+type FieldValueOf<F extends ExtensionValueField> = F extends {
+    readonly values: 'string';
+} ? Readonly<Record<string, string>> : JsonOf<F['type']>;
+/** The value at `K`: the field there, or an object of the fields under it. */
+type ValueAt<F extends ExtensionValueField, K extends string> = [
+    Extract<F, {
+        readonly path: K;
+    }>
+] extends [never] ? ValuesOf$1<Rebased<F, K>> : FieldValueOf<Extract<F, {
+    readonly path: K;
+}>>;
+/**
+ * Value fields as an object: `payload.data.object.id` a `string` at `payload.data.object.id`. A
+ * segment is required when a field under it is.
+ */
+type ValuesOf$1<F extends ExtensionValueField> = Flatten<{
+    readonly [K in Head<F['path']> as true extends Under<F, K>['required'] ? K : never]: ValueAt<F, K>;
+} & {
+    readonly [K in Head<F['path']> as true extends Under<F, K>['required'] ? never : K]?: ValueAt<F, K>;
+}>;
+/** A Trigger's payload, as an object; one that declares nothing, `{}`. */
+type ValuesOfList<L extends readonly ExtensionValueField[]> = [L[number]] extends [never] ? Record<string, never> : ValuesOf$1<L[number]>;
+/** An action field's value, as TypeScript reads it (`@relyio/api-contract`'s `ACTION_FIELD_TYPES`). */
+type ActionValueOf<T extends ActionField['type']> = T extends 'text' | 'url' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : T extends 'headers' ? Readonly<Record<string, string>> : AutomationJson;
+/** An Action's input or output fields as an object: required ones required, the rest optional. */
+type ActionValuesOf<L extends readonly ActionField[]> = Flatten<{
+    readonly [F in L[number] as F extends {
+        readonly required: true;
+    } ? F['key'] : never]: ActionValueOf<F['type']>;
+} & {
+    readonly [F in L[number] as F extends {
+        readonly required: true;
+    } ? never : F['key']]?: ActionValueOf<F['type']>;
+}>;
+/** A Trigger's handle: call it for the Automation's `on`, with a `where` over its event if needed. */
+type ExtensionTriggerHandle<P> = (options?: {
+    readonly where?: (event: Ref<ExtensionTriggerEvent<P>>) => ConditionTree;
+}) => AutomationTriggerHandle<ExtensionTriggerEvent<P>>;
+/**
+ * The handle an Extension's declaration gives: each of its Actions and Triggers, by the name it gives
+ * them, typed by their fields.
+ */
+type HandleOf<X extends ExtensionSurface, S extends string = string> = {
+    readonly [A in keyof X['actions']]: X['actions'][A] extends {
+        readonly action: infer N extends string;
+        readonly step: {
+            readonly input: infer I extends readonly ActionField[];
+            readonly output: infer O extends readonly ActionField[];
+        };
+    } ? AutomationAction<ActionValuesOf<I>, ActionValuesOf<O>, S, N> : never;
+} & {
+    readonly [T in keyof X['triggers']]: X['triggers'][T] extends {
+        readonly payload: infer P extends readonly ExtensionValueField[];
+    } ? ExtensionTriggerHandle<ValuesOfList<P>> : never;
+};
+/**
+ * A contributed field kind's options (spec 4, REL-3894): its base reference's, without `to`, which
+ * the kind names, and never `localized` — a user is no translation.
+ */
+type ContributedFieldOptions<TTo extends string, TMulti extends boolean, TRequired extends boolean> = Omit<ReferenceConfig<TTo, TMulti>, 'to'> & {
+    readonly required?: TRequired;
+    readonly to?: never;
+} & KeyedFieldOptions<never>;
+/**
+ * A contributed field kind's builder — `clerk.userRef()`: a reference to the Extension's Managed
+ * Record type, typed exactly as `fields.reference` types a reference to it, which the Studio picks through
+ * the kind's picker. The schema, reads, writes and Policies treat it as that reference.
+ */
+type ContributedFieldKindBuilder<TTo extends string> = <TMulti extends boolean = false, TRequired extends boolean = false>(options?: ContributedFieldOptions<TTo, TMulti, TRequired>) => KeyedField<'reference', ReferenceConfig<TTo, TMulti> & {
+    required?: TRequired;
+}>;
+/** An Extension's contributed field kinds, by the name its declaration gives them. */
+type FieldKindsOf<X extends ExtensionSurface> = {
+    readonly [K in keyof X['fieldKinds']]: X['fieldKinds'][K] extends {
+        readonly base: {
+            readonly to: infer To extends string;
+        };
+    } ? ContributedFieldKindBuilder<To> : never;
+};
+/** An Extension's Managed Record types, by the name its declaration gives them (REL-3863). */
+type RecordTypesOf<X extends ExtensionSurface> = {
+    readonly [K in keyof X['recordTypes']]: X['recordTypes'][K];
+};
+/** Extension `S`'s handle. */
+type ExtensionHandle<S extends keyof Surfaces> = HandleOf<Surfaces[S], S & string> & FieldKindsOf<Surfaces[S]> & RecordTypesOf<Surfaces[S]>;
+/** Where the declaration rides on what `defineExtensions` returns. */
+declare const DECLARED = "declared";
+/**
+ * Where an {@link ExtensionsFile}'s type keeps the settings it was declared with, for
+ * {@link ClaimsOf} to read. Type-level only: no value carries it.
+ */
+declare const DECLARED_SETTINGS: unique symbol;
+/**
+ * What `relyio/extensions.ts` default-exports: the declaration the CLI reads into the Manifest, and
+ * a handle for each Extension it declares.
+ */
+type ExtensionsFile<C> = ExtensionsFileData & {
+    readonly [S in keyof C & keyof Surfaces]: ExtensionHandle<S>;
+} & {
+    readonly [DECLARED_SETTINGS]?: C;
+};
+/** The setting an identity Extension declares its Claims in (`@relyio/api-contract`'s `IDENTITY_CLAIMS_SETTING`). */
+type ClaimsSetting = 'claims';
+/** `S` without the whitespace `String.prototype.trim` takes off either end. */
+type Trimmed<S extends string> = S extends `${' ' | '\n' | '\t' | '\r'}${infer Rest}` ? Trimmed<Rest> : S extends `${infer Rest}${' ' | '\n' | '\t' | '\r'}` ? Trimmed<Rest> : S;
+/**
+ * The Claim names a `claims` setting declares, read as `claimNamesOf` reads it at deploy: split on
+ * commas, each trimmed, empty ones dropped. Text TypeScript does not know (`string`) may name any.
+ */
+type ClaimNames<S extends string> = string extends S ? string : S extends `${infer First},${infer Rest}` ? ClaimNames<First> | ClaimNames<Rest> : Trimmed<S> extends '' ? never : Trimmed<S>;
+/** Every Claim name the Extensions in `C` declare: an identity Extension's `claims` setting. */
+type DeclaredClaimNames<C> = {
+    readonly [S in keyof C]: C[S] extends {
+        readonly [K in ClaimsSetting]: infer T extends string;
+    } ? ClaimNames<T> : never;
+}[keyof C];
+/**
+ * The Claims a Project relies on, typed from its `relyio/extensions.ts`: `ClaimsOf<typeof
+ * extensions>` is an object with one optional key per Claim its identity Extension's `claims`
+ * setting names — `claims: 'plan, role'` is `{ plan?: unknown; role?: unknown }`. A Claim named and
+ * missing from a token is absent, and a setting is text, so each value is `unknown`: what a Claim may
+ * hold is for the Policy that tests it to say.
+ *
+ * Type a Policy's `claims` root with it, so a misspelt Claim is a compile error:
+ *
+ * @example
+ * import type { ClaimsOf } from '@relyio/sdk/extensions'
+ * import { conditionRoot } from '@relyio/sdk/schema'
+ * import extensions from './extensions'
+ *
+ * const claims = conditionRoot<ClaimsOf<typeof extensions>>('claims')
+ * claims.plan.eq('paid') // ✓
+ * claims.plna.eq('paid') // ✗ `plna` is no Claim the Project declares
+ */
+type ClaimsOf<F> = F extends {
+    readonly [DECLARED_SETTINGS]?: infer C;
+} ? {
+    readonly [N in DeclaredClaimNames<C>]?: unknown;
+} : never;
+/** `C`, refusing a key no Extension declares — at the top and in each Extension's settings. */
+type Exactly<C> = {
+    readonly [S in keyof C]: S extends keyof Surfaces ? C[S] & {
+        readonly [K in Exclude<keyof C[S], keyof ExtensionSettings<S>>]: never;
+    } : never;
+};
+/**
+ * Declare the Extensions the Project uses, with their settings, and take a typed handle for each.
+ * The file is `relyio/extensions.ts`; `relyio deploy` reads its default export into the Manifest.
+ */
+declare function defineExtensions<const C extends ExtensionsConfig>(config: C & Exactly<C>): ExtensionsFile<C>;
+/** What the CLI reads of `relyio/extensions.ts`' default export, whatever it declares. */
+interface ExtensionsFileData {
+    readonly _tag: 'extensions';
+    readonly [DECLARED]: ExtensionsDeclaration;
+}
+/** Whether `value` is what `defineExtensions` returns: how the CLI reads `relyio/extensions.ts`. */
+declare function isExtensionsFile(value: unknown): value is ExtensionsFileData;
+/** The declaration as the Manifest carries it. */
+declare function extensionsDeclarationOf(file: ExtensionsFileData): ExtensionsDeclaration;
+
 /**
  * `@relyio/sdk/functions` — a Function, declared (spec 2, REL-3819; ADR 0021).
  *
@@ -979,6 +1221,8 @@ interface FunctionDeclaration {
     readonly secrets: Readonly<Record<string, FunctionSecretDeclaration>>;
     /** The Actions it may send (REL-3856); absent when it declares none. */
     readonly actions?: readonly FunctionActionReach[];
+    /** Who besides a secret key may call its SDK Way in (spec 4, REL-3892); absent when undeclared. */
+    readonly endUsers?: FunctionEndUsers;
     readonly route?: FunctionRoute;
     readonly tool?: FunctionTool;
     readonly schedule?: FunctionSchedule;
@@ -1124,6 +1368,31 @@ type FunctionRecords<R extends string, W extends string> = {
  * the person's own Preview branch.
  */
 type FunctionWayIn = 'sdk' | 'route' | 'tool' | 'schedule' | 'automation' | 'editor';
+/**
+ * Whether a publishable key may call a Function from a browser (spec 4, REL-3892): `'required'` for
+ * a signed-in End user only — the call carries their token — or `'optional'` with or without one.
+ */
+type FunctionEndUsers = 'required' | 'optional';
+/**
+ * The Claims a run's End user carries: those the registered `relyio/extensions.ts` declares
+ * (`ClaimsOf`), once `Register` names it — `declare module '@relyio/sdk' { interface Register {
+ * extensions: typeof extensions } }` — else any name, each `unknown`.
+ */
+type FunctionEndUserClaims = Register extends {
+    extensions: infer F;
+} ? ClaimsOf<F> : {
+    readonly [claim: string]: unknown;
+};
+/**
+ * The End user a run's call carried a verified token for (spec 4, REL-3892): their subject — the
+ * `sub` an Owner field stores — and the Claims the Project declares, as the token carries them. A
+ * Record the run creates naming no owner is theirs; what the run may touch is still its reach, never
+ * their Policies.
+ */
+interface FunctionEndUser {
+    readonly subject: string;
+    readonly claims: FunctionEndUserClaims;
+}
 /** What a run knows of itself: its id survives every retry. */
 interface FunctionRunInfo {
     readonly id: string;
@@ -1146,6 +1415,11 @@ interface FunctionRunInfo {
      * Absent from a run an SDK call, a route or a tool started.
      */
     readonly event?: Readonly<Record<string, unknown>>;
+    /**
+     * The End user whose token the call carried, verified (spec 4, REL-3892) — with any key on the SDK
+     * Way in or a keyed route, and on a Public route that was sent one. Absent otherwise.
+     */
+    readonly endUser?: FunctionEndUser;
 }
 /** Published content, read through the read core: present when the reach declares `content: 'published'`. */
 interface FunctionContent {
@@ -1272,6 +1546,13 @@ interface FunctionConfig<I extends KeyedMembers, O extends KeyedMembers, R exten
      * type error, and refused at run time.
      */
     actions?: readonly A[];
+    /**
+     * Who besides a secret key may call it through `relyio.functions.<name>(input)` (spec 4,
+     * REL-3892): `'required'` lets a publishable key call it for a signed-in End user, whose token it
+     * carries; `'optional'` lets a publishable key call it with or without one. Left out, a secret key
+     * alone. Either way the run is bound by its reach, and `run.endUser` names who called.
+     */
+    endUsers?: FunctionEndUsers;
     route?: FunctionRoute;
     tool?: FunctionTool;
     schedule?: FunctionSchedule;
@@ -1306,4 +1587,4 @@ declare function defineFunction<const I extends KeyedMembers = Record<never, nev
 /** Whether `value` is what `defineFunction` returns: how the CLI reads a Function file's default export. */
 declare function isFunctionDefinition(value: unknown): value is FunctionDefinition;
 
-export { type FunctionActionRefused as A, type Accepts, type AgentStepConfig, type AnyEntryEvent, type AnyEntryTriggers, type ApproveCounts, type ApproveOutput, type ApproveStepConfig, type AskOutput, type AskStepConfig, type AutomationAction, type AutomationBecomesTest, type AutomationConfig, type AutomationDefinition, type AutomationDuration, type AutomationEntryAction, type AutomationFile, type AutomationInput, type AutomationItemHandle, type AutomationItemRef, type AutomationJson, type AutomationLookupState, type AutomationProposal, type AutomationProposeTarget, type AutomationRecordAction, type AutomationRef, type AutomationStep, type AutomationStepDraft, type AutomationTemplate, type AutomationTrigger, type AutomationTriggerHandle, type AutomationValue, type AutomationWhere, isActionRefused as B, type FunctionCapabilities as C, type FunctionResponse as D, respond as E, type EntryEvent, type EntryTriggers, type ExtensionTriggerEvent, type FunctionRuntime as F, type FunctionConfig as G, type FunctionDefinition as H, type FunctionInputOf as I, type FunctionOutputOf as J, defineFunction as K, isFunctionDefinition as L, type LookedUp, type LookedUpEntry, type LookedUpEntryItem, type LookedUpRecord, type LookupOptions, type ProposingAgentStepConfig, type ProposingOutput, type RecordEvent, type RecordTriggers, type Ref, type RunFailedEvent, type RunFailedWhere, type StepBuilder, type StepHandle, type StepInput, type StepWithOutput, type TriggerWhere, type UidRef, type FunctionContainerSize as a, and, anyEntry, automations, type FunctionDuration as b, type FunctionRouteMethod as c, type FunctionNetworkHost as d, defineAutomation, type FunctionActionReach as e, entries, extensionTrigger, type FunctionActionHandle as f, type FunctionSecretDeclaration as g, type FunctionRoute as h, type FunctionTool as i, isAutomationFile, type FunctionSchedule as j, type FunctionFieldDeclaration as k, type FunctionDeclaration as l, type FunctionRecordTypeName as m, type FunctionFile as n, not, type FunctionCounterMove as o, on, or, type FunctionRecordReader as p, type FunctionRecordWriter as q, type FunctionRecordBatch as r, records, resolveAutomation, type FunctionBatchResult as s, schedule, type FunctionBatchRefused as t, tpl, isBatchRefused as u, type FunctionRecords as v, type FunctionWayIn as w, type FunctionRunInfo as x, type FunctionContent as y, type FunctionActions as z };
+export { type FunctionOutputOf as $, type FunctionCounterMove as A, type Accepts, type AgentStepConfig, type AnyEntryEvent, type AnyEntryTriggers, type ApproveCounts, type ApproveOutput, type ApproveStepConfig, type AskOutput, type AskStepConfig, type AutomationAction, type AutomationBecomesTest, type AutomationConfig, type AutomationDefinition, type AutomationDuration, type AutomationEntryAction, type AutomationFile, type AutomationInput, type AutomationItemHandle, type AutomationItemRef, type AutomationJson, type AutomationLookupState, type AutomationProposal, type AutomationProposeTarget, type AutomationRecordAction, type AutomationRef, type AutomationStep, type AutomationStepDraft, type AutomationTemplate, type AutomationTrigger, type AutomationTriggerHandle, type AutomationValue, type AutomationWhere, type FunctionRecordReader as B, type ContributedFieldOptions as C, type FunctionRecordWriter as D, type ExtensionUse as E, type EntryEvent, type EntryTriggers, type ExtensionTriggerEvent, type FunctionRuntime as F, type FunctionRecordBatch as G, type HandleOf as H, type FunctionBatchResult as I, type FunctionBatchRefused as J, isBatchRefused as K, type FunctionRecords as L, type LookedUp, type LookedUpEntry, type LookedUpEntryItem, type LookedUpRecord, type LookupOptions, type FunctionWayIn as M, type FunctionEndUsers as N, type FunctionEndUserClaims as O, type FunctionEndUser as P, type ProposingAgentStepConfig, type ProposingOutput, type FunctionRunInfo as Q, type FunctionContent as R, type RecordEvent, type RecordTriggers, type Ref, type RunFailedEvent, type RunFailedWhere, type FunctionActions as S, type StepBuilder, type StepHandle, type StepInput, type StepWithOutput, type FunctionActionRefused as T, type TriggerWhere, isActionRefused as U, type UidRef, type FunctionCapabilities as V, type FunctionResponse as W, respond as X, type FunctionConfig as Y, type FunctionDefinition as Z, type FunctionInputOf as _, type ExtensionsDeclaration as a, defineFunction as a0, isFunctionDefinition as a1, and, anyEntry, automations, type ExtensionSettings as b, type ExtensionsConfig as c, type ExtensionTriggerHandle as d, defineAutomation, type ContributedFieldKindBuilder as e, entries, extensionTrigger, type ExtensionHandle as f, type ExtensionsFile as g, type ClaimsOf as h, defineExtensions as i, isAutomationFile, type ExtensionsFileData as j, isExtensionsFile as k, extensionsDeclarationOf as l, type FunctionContainerSize as m, type FunctionDuration as n, not, type FunctionRouteMethod as o, on, or, type FunctionNetworkHost as p, type FunctionActionReach as q, type FunctionActionHandle as r, records, resolveAutomation, type FunctionSecretDeclaration as s, schedule, type FunctionRoute as t, tpl, type FunctionTool as u, type FunctionSchedule as v, type FunctionFieldDeclaration as w, type FunctionDeclaration as x, type FunctionRecordTypeName as y, type FunctionFile as z };

package/dist/automations/index.js

@@ -1,5 +1,6 @@
-export { and, anyEntry, automations, defineAutomation, entries, extensionTrigger, isAutomationFile, not, on, or, records, resolveAutomation, schedule, tpl } from '../chunk-R6E4HE7R.js';
-export { fields } from '../chunk-W7JFHSFM.js';
+export { and, anyEntry, automations, defineAutomation, entries, extensionTrigger, isAutomationFile, not, on, or, records, resolveAutomation, schedule, tpl } from '../chunk-W2GRVXDG.js';
+export { fields } from '../chunk-PZCDJFMA.js';
+import '../chunk-T7LGREB3.js';
 import '../chunk-DI6KFDBO.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{chunk-ZHTJ7GXH.js → chunk-356SF5Y2.js}

@@ -1,7 +1,7 @@
 import { isBrowser } from './chunk-NJQK5STK.js';
 import { parseDevEnv, DEV_CONTEXT_DIR, DEV_CONTEXT_FILENAME, parseDevContextFile } from './chunk-W2A4OTCI.js';
 import { UNKNOWN_PREVIEW_RECHECK_MS, previewAtRequest } from './chunk-HDHBYYEY.js';
-import { VISITOR_CLOSE_CODES, HEADER_RETRY_AFTER, HEADER_IDEMPOTENCY_KEY, entityTag, HEADER_IF_MATCH, FRESH_PARAMETER, VISITOR_KEEPALIVE, parseVisitorFrame, VISITOR_FRAMES, VISITOR_POLL_INTERVAL_MS, VISITOR_CLOSE_RETRY, readVisitorPollAnswer, VISITOR_POLL_RETRY, VISITOR_LIVE_PATH, VISITOR_QUERY, previewDatasetSlug } from './chunk-EDE2H37D.js';
+import { HEADER_END_USER, VISITOR_CLOSE_CODES, HEADER_RETRY_AFTER, END_USER_TOKEN_REFUSAL_REASONS, HEADER_IDEMPOTENCY_KEY, entityTag, HEADER_IF_MATCH, FRESH_PARAMETER, VISITOR_KEEPALIVE, parseVisitorFrame, VISITOR_FRAMES, VISITOR_POLL_INTERVAL_MS, VISITOR_CLOSE_RETRY, readVisitorPollAnswer, VISITOR_POLL_RETRY, VISITOR_LIVE_PATH, VISITOR_QUERY, previewDatasetSlug } from './chunk-T7LGREB3.js';
 import { __name, __publicField } from './chunk-DI6KFDBO.js';
 
 /* RelyIO SDK - Built with ❤️ by the RelyIO Team */
@@ -169,13 +169,13 @@ var _ReadOnlyKeyError = class _ReadOnlyKeyError extends SDKError {
 __name(_ReadOnlyKeyError, "ReadOnlyKeyError");
 var ReadOnlyKeyError = _ReadOnlyKeyError;
 var _PublishableKeyRefusedError = class _PublishableKeyRefusedError extends SDKError {
-  constructor(message = "A publishable key cannot read or write Records or run Functions", context) {
+  constructor(message = "A publishable key writes a Record only for a signed-in End user", context) {
     super(message, 403, void 0, context);
     __publicField(this, "code", "PUBLISHABLE_KEY_REFUSED");
     __publicField(this, "retryable", false);
   }
   getUserMessage() {
-    return "A publishable key cannot reach Records or Functions. Call them from your server with a secret key.";
+    return "A publishable key writes a Record only with a signed-in End user's token, and runs only a Function declaring endUsers. Send the End user's token, declare endUsers on the Function, or call it from your server with a secret key.";
   }
 };
 __name(_PublishableKeyRefusedError, "PublishableKeyRefusedError");
@@ -392,6 +392,19 @@ var _InvalidApiKeyError = class _InvalidApiKeyError extends SDKError {
 };
 __name(_InvalidApiKeyError, "InvalidApiKeyError");
 var InvalidApiKeyError = _InvalidApiKeyError;
+var _EndUserTokenInvalidError = class _EndUserTokenInvalidError extends SDKError {
+  constructor(message, reason, context) {
+    super(message, 401, void 0, context);
+    this.reason = reason;
+    __publicField(this, "code", "END_USER_TOKEN_INVALID");
+    __publicField(this, "retryable", false);
+  }
+  getUserMessage() {
+    return "Your session is not valid. Please sign in again.";
+  }
+};
+__name(_EndUserTokenInvalidError, "EndUserTokenInvalidError");
+var EndUserTokenInvalidError = _EndUserTokenInvalidError;
 
 // src/errors/network-errors.ts
 var _NetworkError = class _NetworkError extends SDKError {
@@ -593,6 +606,9 @@ var _ErrorMapper = class _ErrorMapper {
       case "INVALID_API_KEY": {
         return new InvalidApiKeyError(message, void 0, context);
       }
+      case "END_USER_TOKEN_INVALID": {
+        return new EndUserTokenInvalidError(message, endUserTokenReasonOf(refusal), context);
+      }
       case "ACCESS_DENIED": {
         return new AuthorizationError(message, 403, void 0, context);
       }
@@ -800,6 +816,15 @@ function violationsOf(refusal) {
   }));
 }
 __name(violationsOf, "violationsOf");
+function endUserTokenReasonOf(refusal) {
+  const reason = detailString(refusal, "reason");
+  return isEndUserTokenReason(reason) ? reason : void 0;
+}
+__name(endUserTokenReasonOf, "endUserTokenReasonOf");
+function isEndUserTokenReason(value) {
+  return value !== void 0 && END_USER_TOKEN_REFUSAL_REASONS.includes(value);
+}
+__name(isEndUserTokenReason, "isEndUserTokenReason");
 
 // src/http/api-routes.ts
 function fillPath(template, params) {
@@ -1172,22 +1197,33 @@ var _HttpClient = class _HttpClient {
    * constructor accepts one so that a module-scope client can be evaluated by a
    * build that holds no key (REL-1120) — and so does one whose `setApiKey` was
    * given none.
+   *
+   * The End user's token is asked for once, after the key is known to be there and before the first
+   * attempt — of `getToken`, the nearest view's function, or the configuration's — so every retry
+   * of one call sends the token its first attempt sent. See `RelyIOConfig.getToken`.
    */
-  async request(config) {
+  async request(config, getToken) {
     if (this.view !== void 0) {
-      return this.view.client.request({
-        ...config,
-        headers: layerHeaders(this.view.headers, config.headers)
-      });
+      return this.view.client.request(
+        { ...config, headers: layerHeaders(this.view.headers, config.headers) },
+        getToken ?? this.view.getToken
+      );
     }
     if (config.timeout !== void 0) assertRequestTimeout(config.timeout);
     const mergedConfig = this.mergeRequestConfig(config);
-    if (presentKey(headerValue(mergedConfig.headers, API_KEY_HEADER)) === void 0) {
+    if (presentCredential(headerValue(mergedConfig.headers, API_KEY_HEADER)) === void 0) {
       throw new MissingApiKeyError(
         "`apiKey` is missing: this client holds no API key, so the request was not sent. Pass `apiKey` to createClient \u2014 the documented setup reads it from RELYIO_API_KEY.",
         { url: mergedConfig.url, method: mergedConfig.method, sent: false }
       );
     }
+    const tokenSource = getToken ?? this.connection.config.getToken;
+    if (tokenSource !== void 0) {
+      const token = presentCredential(await tokenSource());
+      mergedConfig.headers = layerHeaders(mergedConfig.headers ?? {}, {
+        [END_USER_HEADER]: token ?? null
+      });
+    }
     this.log("debug", "Making request", {
       method: mergedConfig.method,
       url: mergedConfig.url
@@ -1231,7 +1267,7 @@ var _HttpClient = class _HttpClient {
         });
         if (preview !== void 0 && answersUnknownDataset(sdkError, preview)) {
           rememberUnknownPreview(preview);
-          return this.request(config);
+          return this.request(config, getToken);
         }
         this.log("error", "Request failed after all retries", {
           error: sdkError.toJSON(),
@@ -1452,10 +1488,17 @@ var _ControlledHttpClient = class _ControlledHttpClient extends HttpClient {
    * retries and `fetch` are this client's as they are when each request is sent, so a later
    * `configure()` or `setApiKey()` on this client reaches the view, and one on the view reaches
    * this client. `client.with({ dataset })` is one (REL-2417).
+   *
+   * `options.getToken` is the End user's token function the view asks in place of this client's,
+   * and of any view it is made from: `client.with({ getToken })` (REL-3882).
    */
-  withHeaders(headers) {
+  withHeaders(headers, options = {}) {
     const view = new _ControlledHttpClient(this.connection.config);
-    view.view = { client: this, headers: { ...headers } };
+    view.view = {
+      client: this,
+      headers: { ...headers },
+      ...options.getToken === void 0 ? {} : { getToken: options.getToken }
+    };
     return view;
   }
   /**
@@ -1477,7 +1520,7 @@ var _ControlledHttpClient = class _ControlledHttpClient extends HttpClient {
    * Replace the key every later request sends as `X-API-Key`, and the `apiKey` the configuration
    * reports.
    *
-   * The key is read the way construction reads it (`presentKey`): an absent, empty or blank key is
+   * The key is read the way construction reads it (`presentCredential`): an absent, empty or blank key is
    * no key, so the header is dropped and the next request is refused with `MissingApiKeyError`
    * before anything is sent. A key header of any other spelling — one given in `headers` — goes
    * too, from the headers sent and from the headers the configuration reports, so the old key is
@@ -1498,7 +1541,7 @@ var _ControlledHttpClient = class _ControlledHttpClient extends HttpClient {
     this.connection = {
       ...this.connection,
       defaultHeaders: layerHeaders(this.connection.defaultHeaders, {
-        [API_KEY_HEADER]: presentKey(apiKey) ?? null
+        [API_KEY_HEADER]: presentCredential(apiKey) ?? null
       })
     };
   }
@@ -1507,6 +1550,7 @@ __name(_ControlledHttpClient, "ControlledHttpClient");
 var ControlledHttpClient = _ControlledHttpClient;
 var API_KEY_HEADER = "X-API-Key";
 var DATASET_HEADER = "X-RelyIO-Dataset";
+var END_USER_HEADER = HEADER_END_USER.name;
 function derivedPreviewIn(headers) {
   const dataset = headerValue(headers, DATASET_HEADER);
   return dataset !== void 0 && isDerivedPreview(dataset) ? dataset : void 0;
@@ -1525,7 +1569,7 @@ function connectionFor(config) {
   const defaultHeaders = layerHeaders(
     layerHeaders({ "Content-Type": "application/json" }, config.headers),
     {
-      [API_KEY_HEADER]: presentKey(config.apiKey),
+      [API_KEY_HEADER]: presentCredential(config.apiKey),
       [DATASET_HEADER]: config.dataset,
       // Only outside a browser, which controls this header. "A browser" is the core's one
       // definition, `isBrowser()` — every environment question in this file asks it.
@@ -1557,10 +1601,10 @@ function layerHeaders(base, over) {
   return layered;
 }
 __name(layerHeaders, "layerHeaders");
-function presentKey(value) {
+function presentCredential(value) {
   return typeof value === "string" && value.trim() !== "" ? value : void 0;
 }
-__name(presentKey, "presentKey");
+__name(presentCredential, "presentCredential");
 function credentialsModeFor(includeCredentials) {
   return includeCredentials ? "include" : "same-origin";
 }
@@ -2876,7 +2920,8 @@ var _RecordsClient = class _RecordsClient {
    * Store a Record, live the moment it lands. Values that break the Record type's fields are
    * refused with `ValidationError` naming each field, and nothing is stored. Values a unique set of
    * the type claims, held by another Record, are refused with `ResourceConflictError` — its
-   * `blockage` is `{ kind: 'value-taken', facts: { fields, recordId } }` (REL-3782).
+   * `blockage` is `{ kind: 'value-taken', facts: { fields, recordId } }` (REL-3782) — with no
+   * `recordId` for an End user's write, whose read Policy may hide the holder (REL-3863).
    */
   async create(fields, options = {}) {
     return this.httpClient.fetchPayload(
@@ -4117,6 +4162,9 @@ function validateConfig(config) {
   if (config.webSocket != null && typeof config.webSocket !== "function") {
     throw new Error("webSocket must be a WebSocket class");
   }
+  if (config.getToken != null && typeof config.getToken !== "function") {
+    throw new Error("getToken must be a function that answers the End user\u2019s token, or null");
+  }
   if (config.timeout != null) assertRequestTimeout(config.timeout);
   if (config.retryAttempts != null && !(Number.isInteger(config.retryAttempts) && config.retryAttempts >= 1)) {
     throw new Error(
@@ -4245,7 +4293,10 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
      * `createClient()` made, which reads its own.
      */
     __publicField(this, "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.
+     */
     __publicField(this, "defaults", {});
     /** The live edge's poll client id: chosen once, when first needed, and kept for this client's life. */
     __publicField(this, "_liveClientId");
@@ -4256,7 +4307,9 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
      * 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
@@ -4740,6 +4793,9 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
    * 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) {
@@ -4753,14 +4809,16 @@ var _TypedRelyIOClient = class _TypedRelyIOClient {
   }
   /** Make this client one `with()` made from `parent`: see {@link with}. */
   follow(parent, defaults) {
-    const { locale, dataset } = defaults;
+    const { locale, dataset, getToken } = defaults;
     this.parent = parent;
     this.defaults = {
       ...locale === void 0 ? {} : { locale },
-      ...dataset === void 0 ? {} : { dataset }
+      ...dataset === void 0 ? {} : { dataset },
+      ...getToken === void 0 ? {} : { getToken }
     };
     this.httpClient = parent.httpClient.withHeaders(
-      dataset === void 0 ? {} : { [DATASET_HEADER]: dataset }
+      dataset === void 0 ? {} : { [DATASET_HEADER]: dataset },
+      getToken === void 0 ? {} : { getToken }
     );
   }
   /**
@@ -4811,6 +4869,6 @@ function randomClientId() {
 }
 __name(randomClientId, "randomClientId");
 
-export { AssetClient, AssetFileBuilder, AssetUploadBuilder, AuthorizationError, BaseValidationError, ChangesExpiredError, ConnectionError, ContentClient, DefaultRetryPolicy, ErrorMapper, FileUploadError, FileValidationError, FunctionContainersBusyError, FunctionRunFailedError, FunctionRunTimedOutError, HttpClient, InvalidApiKeyError, InvalidPayloadError, LIVE_KEEPALIVE_INTERVAL_MS, LIVE_SOCKET_OPEN_TIMEOUT_MS, LiveEdgeError, MethodNotAllowedError, MissingApiKeyError, NetworkError, PREVIEW_KEY_PREFIX, PUBLISHABLE_KEY_PREFIX, PayloadTooLargeError, PlanFeatureUnavailableError, PublishableKeyRefusedError, RateLimitError, ReadOnlyKeyError, RecordsClient, ResourceConflictError, ResourceExpiredError, ResourceNotFoundError, SDKError, ServerError, ServiceIndeterminateError, SettingsClient, SingletonClient, TimeoutError, TransactionRolledBackError, TypedRelyIOClient, UnknownContractError, UsageQuotaExceededError, ValidationError, createClient, isAborted, isAssetEntry, isMissingEntry, isPreviewKey, isPublishableKey, isReplaySafe, isResourceNotFound, matchRoute, refusedOperationOf, retryPolicyFor, serviceInstructedDelayMs, sleep, validateFile, versionCheckOf };
-//# sourceMappingURL=chunk-ZHTJ7GXH.js.map
-//# sourceMappingURL=chunk-ZHTJ7GXH.js.map
+export { AssetClient, AssetFileBuilder, AssetUploadBuilder, AuthorizationError, BaseValidationError, ChangesExpiredError, ConnectionError, ContentClient, DefaultRetryPolicy, EndUserTokenInvalidError, ErrorMapper, FileUploadError, FileValidationError, FunctionContainersBusyError, FunctionRunFailedError, FunctionRunTimedOutError, HttpClient, InvalidApiKeyError, InvalidPayloadError, LIVE_KEEPALIVE_INTERVAL_MS, LIVE_SOCKET_OPEN_TIMEOUT_MS, LiveEdgeError, MethodNotAllowedError, MissingApiKeyError, NetworkError, PREVIEW_KEY_PREFIX, PUBLISHABLE_KEY_PREFIX, PayloadTooLargeError, PlanFeatureUnavailableError, PublishableKeyRefusedError, RateLimitError, ReadOnlyKeyError, RecordsClient, ResourceConflictError, ResourceExpiredError, ResourceNotFoundError, SDKError, ServerError, ServiceIndeterminateError, SettingsClient, SingletonClient, TimeoutError, TransactionRolledBackError, TypedRelyIOClient, UnknownContractError, UsageQuotaExceededError, ValidationError, createClient, isAborted, isAssetEntry, isMissingEntry, isPreviewKey, isPublishableKey, isReplaySafe, isResourceNotFound, matchRoute, refusedOperationOf, retryPolicyFor, serviceInstructedDelayMs, sleep, validateFile, versionCheckOf };
+//# sourceMappingURL=chunk-356SF5Y2.js.map
+//# sourceMappingURL=chunk-356SF5Y2.js.map