@superpanel-sdk/runtime 0.2.3 → 0.7.0

package/dist/core/page/typed.d.ts

@@ -0,0 +1,648 @@
+/**
+ * The page module's types bound to one sequence (15 §10.15): what `__gen/index.ts` exports as
+ * `definePage`, `field`, `createRow` and `deleteRow`. Behaviour is
+ * `define.ts`'s; this file only types it.
+ *
+ * Everything starts from `PageTables`, generated per sequence into `__gen/slots.type.ts`: for each
+ * table, each field's value type, and for a ref field the table it points at (`ref`) and whether it
+ * is the parent (`parent`). From it:
+ *
+ *  - a row read with `db` has `id: Id<'table'>`, `createdAt` / `updatedAt` (ISO 8601, the platform's)
+ *    and one slot per field, its value typed by the schema; a lookup `include`d carries the target row
+ *    in `.row`, a way back (`relatedName`) its rows as a list under its name;
+ *  - `db.<table>`'s reads take only that table's fields and row times, a `where` starting at its top
+ *    level from `id`, a ref field (15 §10.15 point 4), a field or a row time (the field index,
+ *    18-record-search-index §4.6), `include` of lookups and ways back only, `some` / `every` / `none` on
+ *    a way back (13-data-model-v1 §23.4);
+ *  - an action's arguments come from its `parameters`; `db.<table>`'s writes take only that table's fields;
+ *  - the page is the conversation's: code (functions, event handlers, the Orchestrator) is called
+ *    `(ctx, args)` and reads with `ctx.api.db`.
+ */
+import type { Action, AllPrefilled, DoNode, FieldNode, FullPrefill, FunctionHandle, KeyedOf, LeftForAi, PageActionHandle, PageContent, PageNode, PageSettings, RequiredKeys, RunAction, AnyRunHandle, RunArgs, SameArgs, SayOf } from './fns.js';
+import type { PageTime, ChooseParam, RefOption, PageBaseContext, PageChannel, PageChannelCaps, PageConversation, PageFaq, PageFaqEntry, PageHistory, PagePersona, PageRuns, PageScheduledAction, SlotState } from './define.js';
+declare const ID_BRAND: unique symbol;
+/** A row id of table `T`: an `Id<'injuries'>` is not an `Id<'providers'>`, and no string is an id. */
+export type Id<T extends string = string> = string & {
+    readonly [ID_BRAND]: T;
+};
+declare const FORMAT_BRAND: unique symbol;
+/**
+ * A string in a format the AI is told (38 §2.4): any string is one, and the builder reads the mark to
+ * show the parameter as `date`, `phone`…; one format is not another.
+ */
+type Formatted<F extends string> = string & {
+    readonly [FORMAT_BRAND]?: F;
+};
+/** A calendar date, `YYYY-MM-DD`: the AI sees `date`. */
+export type IsoDate = Formatted<'date'>;
+/** An instant, ISO 8601 with an offset or Z: the AI sees `datetime`. */
+export type IsoDateTime = Formatted<'datetime'>;
+/** A time of day, `HH:mm`: the AI sees `time`. */
+export type TimeOfDay = Formatted<'time'>;
+/** A phone number: the AI sees `phone`. */
+export type Phone = Formatted<'phone'>;
+/** An email address: the AI sees `email`. */
+export type Email = Formatted<'email'>;
+/** One field, as `__gen/slots.type.ts` describes it. */
+export type PageFieldDesc = {
+    value: unknown;
+    ref?: string;
+    parent?: true;
+};
+/**
+ * A table's ways back (`$relations`, 13-data-model-v1 §23.4 items 3–4): for each `relatedName`, the
+ * table whose rows point at this one and the ref field they point with.
+ */
+export type PageRelationsDesc = {
+    [name: string]: {
+        table: string;
+        field: string;
+    };
+};
+/**
+ * A sequence's tables (`PageTables` in `__gen/slots.type.ts`): table → field → description, and its
+ * ways back under `$relations` (no field name starts with `$`).
+ */
+export type PageTablesDesc = {
+    [table: string]: {
+        [field: string]: PageFieldDesc | PageRelationsDesc;
+    };
+};
+type TableOf<D> = Extract<keyof D, string>;
+type FieldOf<D, T extends keyof D> = Exclude<Extract<keyof D[T], string>, '$relations'>;
+/** The ways back to a table, by name; none when it has no `$relations`. */
+type RelationsOf<D, T extends keyof D> = D[T] extends {
+    $relations: infer R;
+} ? R : {};
+type RelationOf<D, T extends keyof D> = Extract<keyof RelationsOf<D, T>, string>;
+/** The table whose rows a way back lists. */
+type RelationTable<D, T extends keyof D, K> = K extends keyof RelationsOf<D, T> ? RelationsOf<D, T>[K] extends {
+    table: infer R extends string;
+} ? R & keyof D : never : never;
+type Desc<D, T extends keyof D, F> = F extends keyof D[T] ? (D[T][F] extends PageFieldDesc ? D[T][F] : never) : never;
+/** The table a ref field points at; never for a plain field. */
+type RefTable<D, T extends keyof D, F> = Desc<D, T, F> extends {
+    ref: infer R extends string;
+} ? R : never;
+/** Lookup fields (refs that are not the parent): what `include` follows. */
+type LookupOf<D, T extends keyof D> = {
+    [F in FieldOf<D, T>]: Desc<D, T, F> extends {
+        ref: string;
+    } ? (Desc<D, T, F> extends {
+        parent: true;
+    } ? never : F) : never;
+}[FieldOf<D, T>];
+/** Ref fields, parent included: what anchors a `where`. */
+type RefFieldOf<D, T extends keyof D> = {
+    [F in FieldOf<D, T>]: Desc<D, T, F> extends {
+        ref: string;
+    } ? F : never;
+}[FieldOf<D, T>];
+/** Fields that are not refs: a condition on one starts a `where` through the field index. */
+type PlainFieldOf<D, T extends keyof D> = Exclude<FieldOf<D, T>, RefFieldOf<D, T>>;
+/** A row's times, the platform's (ISO 8601): when it was created, when it was last written. */
+type RowTime = 'createdAt' | 'updatedAt';
+type ParentOf<D, T extends keyof D> = {
+    [F in FieldOf<D, T>]: Desc<D, T, F> extends {
+        parent: true;
+    } ? F : never;
+}[FieldOf<D, T>];
+/** A field's value: a ref holds the id of a row of its table. */
+type ValueOf<D, T extends keyof D, F> = Desc<D, T, F> extends {
+    ref: infer R extends string;
+} ? Id<R> : Desc<D, T, F>['value'];
+type Simplify<X> = {
+    [K in keyof X]: X[K];
+} & {};
+/** One field as read (15 §10.4): plain data. Judge with `.value` / `.state`. */
+export type TypedSlot<V, T extends string, F extends string> = Readonly<{
+    value: V | null;
+    state: SlotState;
+    reason: string | null;
+    updatedAt: string | null;
+    ref: Readonly<{
+        table: T;
+        id: Id<T>;
+        field: F;
+    }>;
+}>;
+/**
+ * What `include` takes, at most 3 levels: lookup fields, `true` or a nested `{ include }`; ways back,
+ * `true` or the rows to list (`where`, `orderBy`, `skip`, `take`) and a nested `{ include }`.
+ */
+export type IncludeArg<D, T extends keyof D, Depth extends unknown[] = []> = Depth['length'] extends 3 ? never : {
+    [F in LookupOf<D, T>]?: boolean | {
+        include?: IncludeArg<D, RefTable<D, T, F> & keyof D, [...Depth, unknown]>;
+    };
+} & {
+    [K in RelationOf<D, T>]?: boolean | RelationInclude<D, RelationTable<D, T, K>, [...Depth, unknown]>;
+};
+/** The rows of a way back an `include` lists: filtered, ordered and paged like `findMany`. */
+type RelationInclude<D, R extends keyof D, Depth extends unknown[]> = {
+    where?: WhereFields<D, R, true>;
+    orderBy?: OrderByArg<D, R>;
+    skip?: number;
+    take?: number;
+    include?: IncludeArg<D, R, Depth>;
+};
+/** What `select` takes: the fields to keep (`id` always comes). */
+export type SelectArg<D, T extends keyof D> = {
+    [F in FieldOf<D, T>]?: boolean;
+};
+type IncludedRow<D, R extends keyof D, Spec> = [Spec] extends [{
+    include: infer I;
+}] ? RowOf<D, R, I> : RowOf<D, R, undefined>;
+/**
+ * The `.row` an `include` gives: there for sure on `true` or `{ include }`, not there on `false`, and
+ * maybe there on a `boolean` decided at run time (`include: { provider: flag }`).
+ */
+type IncludedSlot<D, T extends keyof D & string, F extends string, Spec> = [Spec] extends [false | undefined] ? unknown : [Spec] extends [true | {
+    include?: unknown;
+}] ? Readonly<{
+    row: IncludedRow<D, RefTable<D, T, F> & keyof D, Spec> | null;
+}> : Readonly<{
+    row?: IncludedRow<D, RefTable<D, T, F> & keyof D, Exclude<Spec, boolean | undefined>> | null;
+}>;
+/** What `include` says of `F`; with `undefined` in it when the whole `include` may be absent this time. */
+type IncludeSpec<Inc, F extends string> = F extends keyof NonNullable<Inc> ? NonNullable<Inc>[F] | (undefined extends Inc ? undefined : never) : undefined;
+type SlotFor<D, T extends keyof D & string, F extends string, Inc> = TypedSlot<ValueOf<D, T, F>, T, F> & IncludedSlot<D, T, F, IncludeSpec<Inc, F>>;
+/** Whether a `select` is given for sure (not `undefined`, nor maybe `undefined`). */
+type NoSelect<Sel> = [Sel] extends [undefined] ? true : unknown extends Sel ? true : false;
+/** Fields there for sure: every field without a `select`, else those selected with `true`. */
+type SureFields<D, T extends keyof D, Sel> = NoSelect<Sel> extends true ? FieldOf<D, T> : {
+    [F in keyof NonNullable<Sel>]-?: [NonNullable<Sel>[F]] extends [true] ? F : never;
+}[keyof NonNullable<Sel>] & FieldOf<D, T>;
+/**
+ * Fields that may be there: with a `select` that may be absent this time, every other field; with a
+ * field selected by a `boolean` decided at run time, that field.
+ */
+type MaybeFields<D, T extends keyof D, Sel> = NoSelect<Sel> extends true ? never : undefined extends Sel ? Exclude<FieldOf<D, T>, SureFields<D, T, Sel>> : Exclude<{
+    [F in keyof NonNullable<Sel>]-?: true extends NonNullable<Sel>[F] ? F : never;
+}[keyof NonNullable<Sel>] & FieldOf<D, T>, SureFields<D, T, Sel>>;
+/**
+ * The ways back an `include` lists: there for sure on `true` or `{ … }`, not there on `false`, maybe
+ * there on a `boolean` decided at run time.
+ */
+type RelationRows<D, T extends keyof D, Inc> = {
+    readonly [K in RelationOf<D, T> as [IncludeSpec<Inc, K>] extends [true | object] ? K : never]: ReadonlyArray<IncludedRow<D, RelationTable<D, T, K>, IncludeSpec<Inc, K>>>;
+} & {
+    readonly [K in RelationOf<D, T> as [IncludeSpec<Inc, K>] extends [false | undefined] ? never : [IncludeSpec<Inc, K>] extends [true | object] ? never : K]?: ReadonlyArray<IncludedRow<D, RelationTable<D, T, K>, Exclude<IncludeSpec<Inc, K>, boolean | undefined>>>;
+};
+/**
+ * The platform's part of a row: its id, and (a stored row, not the session) when it was created and
+ * last written, ISO 8601.
+ */
+type RowSystem<T> = Readonly<{
+    id: Id<T & string>;
+}> & (T extends 'session' ? unknown : Readonly<{
+    createdAt: string;
+    updatedAt: string;
+}>);
+/** A row as `db` returns it: `id`, its times, one slot per field, and the ways back it `include`s. */
+export type RowOf<D, T extends keyof D, Inc = undefined, Sel = undefined> = RowSystem<T> & {
+    readonly [F in SureFields<D, T, Sel>]: SlotFor<D, T & string, F, Inc>;
+} & {
+    readonly [F in MaybeFields<D, T, Sel>]?: SlotFor<D, T & string, F, Inc>;
+} & RelationRows<D, T, Inc>;
+type Ord = 'asc' | 'desc';
+type OrderByArg<D, T extends keyof D> = {
+    [F in FieldOf<D, T> | RowTime]?: Ord;
+} | ReadonlyArray<{
+    [F in FieldOf<D, T> | RowTime]?: Ord;
+}>;
+/** A `multi_select`'s filter (27 §3.2): Prisma's scalar-list filters, plus the slot's state. */
+type ListValueFilter<V extends readonly unknown[]> = V | null | {
+    equals?: V | null;
+    has?: V[number];
+    hasSome?: readonly V[number][];
+    hasEvery?: readonly V[number][];
+    isEmpty?: boolean;
+    state?: SlotState;
+};
+type ScalarFilter<V> = [V] extends [readonly unknown[]] ? ListValueFilter<V> : ScalarFilterOf<V>;
+type ScalarFilterOf<V> = V | null | {
+    equals?: V | null;
+    in?: readonly V[];
+    notIn?: readonly V[];
+    not?: V | null;
+    lt?: V;
+    lte?: V;
+    gt?: V;
+    gte?: V;
+    /** A text's beginning; there is no `contains` / `endsWith`: find by a beginning or an exact field (34 §10). */
+    startsWith?: string;
+    /** `insensitive`: text compared in any case (`equals`, `in`, `startsWith`, ranges). */
+    mode?: 'default' | 'insensitive';
+    /** By the slot's state (`asked_unknown`, `declined`, …): the one extension to Prisma's `where`. */
+    state?: SlotState;
+};
+type IdFilter<R extends string> = Id<R> | null | {
+    equals?: Id<R> | null;
+    in?: readonly Id<R>[];
+    notIn?: readonly Id<R>[];
+    not?: Id<R> | null;
+    state?: SlotState;
+};
+/** A row time (ISO 8601), compared as the instant it names. */
+type TimeFilter = string | {
+    equals?: string;
+    in?: readonly string[];
+    notIn?: readonly string[];
+    not?: string;
+    lt?: string;
+    lte?: string;
+    gt?: string;
+    gte?: string;
+};
+/** `is` / `isNot` on a ref: one level only (a nested `is` is refused; read those rows first, then `in`). */
+type RelationFilter<D, R extends keyof D> = {
+    is?: WhereFields<D, R, false> | null;
+    isNot?: WhereFields<D, R, false> | null;
+};
+/** `some` / `every` / `none` on a way back: one level only, like `is`. */
+type ListFilter<D, R extends keyof D> = {
+    some?: WhereFields<D, R, false>;
+    every?: WhereFields<D, R, false>;
+    none?: WhereFields<D, R, false>;
+};
+type WhereFields<D, T extends keyof D, Rel extends boolean> = {
+    id?: IdFilter<T & string>;
+} & {
+    [K in RowTime]?: TimeFilter;
+} & {
+    [F in FieldOf<D, T>]?: Desc<D, T, F> extends {
+        ref: infer R extends string;
+    } ? IdFilter<R> | (Rel extends true ? RelationFilter<D, R & keyof D> : never) : ScalarFilter<Desc<D, T, F>['value']>;
+} & (Rel extends true ? {
+    [K in RelationOf<D, T>]?: ListFilter<D, RelationTable<D, T, K>>;
+} : unknown) & {
+    AND?: WhereFields<D, T, Rel> | ReadonlyArray<WhereFields<D, T, Rel>>;
+    OR?: ReadonlyArray<WhereFields<D, T, Rel>>;
+    NOT?: WhereFields<D, T, Rel> | ReadonlyArray<WhereFields<D, T, Rel>>;
+};
+/** What anchors a read: an id, `{ equals: id }` or `{ in: ids }`. */
+type Anchor<R extends string> = Id<R> | {
+    equals: Id<R>;
+} | {
+    in: readonly Id<R>[];
+};
+/**
+ * A `where`: this table's fields and row times, starting at its top level from `id` or a ref field
+ * (the rows it pins), or from a condition on a field or a row time (the field index finds the rows;
+ * a long text cannot start one). A start inside `AND` works at run time but does not type-check: write
+ * it at the top level, it means the same.
+ */
+export type Where<D, T extends keyof D> = {
+    [K in 'id' | RefFieldOf<D, T>]: WhereFields<D, T, true> & {
+        [P in K]: Anchor<K extends 'id' ? T & string : RefTable<D, T, K>>;
+    };
+}['id' | RefFieldOf<D, T>] | {
+    [K in PlainFieldOf<D, T> | RowTime]: WhereFields<D, T, true> & {
+        [P in K]-?: NonNullable<WhereFields<D, T, true>[P & keyof WhereFields<D, T, true>]>;
+    };
+}[PlainFieldOf<D, T> | RowTime];
+/**
+ * `include` as written, with any key that is not a lookup (a parent, another table's field, a typo)
+ * turned into `never`, at every level: an inferred argument gets no excess-property check otherwise.
+ */
+type ExactInclude<D, T extends keyof D, I> = {
+    [K in keyof I]: K extends LookupOf<D, T> ? I[K] extends {
+        include: infer N;
+    } ? Omit<I[K], 'include'> & {
+        include: ExactInclude<D, RefTable<D, T, K> & keyof D, N>;
+    } : I[K] : K extends RelationOf<D, T> ? I[K] extends object ? ExactRelationInclude<D, RelationTable<D, T, K>, I[K]> : I[K] : never;
+};
+/**
+ * A way back's `{ where, orderBy, skip, take, include }` as written, any other key `never`; its
+ * `where` checked key by key at its top level (the listed table's fields, `id`, its ways back,
+ * `AND` / `OR` / `NOT`), its `include` like any `include`.
+ */
+type ExactRelationInclude<D, R extends keyof D, S> = {
+    [P in keyof S]: P extends 'include' ? ExactInclude<D, R, S[P]> : P extends 'where' ? {
+        [W in keyof S[P]]: W extends FieldOf<D, R> | RelationOf<D, R> | 'id' | RowTime | 'AND' | 'OR' | 'NOT' ? S[P][W] : never;
+    } : P extends 'orderBy' | 'skip' | 'take' ? S[P] : never;
+};
+/** `select` as written, with any key that is not a field of the table turned into `never`. */
+type ExactSelect<D, T extends keyof D, S> = {
+    [K in keyof S]: K extends FieldOf<D, T> ? S[K] : never;
+};
+/**
+ * `include` / `select`: left out, or written. Written, the key is required here so inference keeps an
+ * `undefined` in its value (`include: flag ? { … } : undefined`); an optional key would drop it.
+ */
+type IncludeKey<D, T extends keyof D, I> = {
+    include?: undefined;
+} | {
+    include: I & ExactInclude<D, T, I>;
+};
+type SelectKey<D, T extends keyof D, S> = {
+    select?: undefined;
+} | {
+    select: S & ExactSelect<D, T, S>;
+};
+/**
+ * `after`: a row of the table as read, whatever its `include` / `select` (normally the last of the page
+ * before); the rows strictly after it in the read's order come (define.ts `FindArgs.after`).
+ */
+type AfterRow<T> = Readonly<{
+    id: Id<T & string>;
+    createdAt?: string;
+    updatedAt?: string;
+}> & {
+    readonly [field: string]: unknown;
+};
+export type FindManyArgs<D, T extends keyof D, I = IncludeArg<D, T>, S = SelectArg<D, T>> = IncludeKey<D, T, I> & SelectKey<D, T, S> & {
+    where: Where<D, T>;
+    orderBy?: OrderByArg<D, T>;
+    take?: number;
+    skip?: number;
+    after?: AfterRow<T>;
+};
+/** `findUnique`: by `id`; null when there is no such row. */
+export type FindUniqueArgs<D, T extends keyof D, I = IncludeArg<D, T>, S = SelectArg<D, T>> = IncludeKey<D, T, I> & SelectKey<D, T, S> & {
+    where: {
+        id: Id<T & string>;
+    };
+};
+/**
+ * One table's read methods: Prisma Client's read-only subset. Only `include` / `select` are inferred
+ * (they shape the rows returned), and checked key by key (`ExactInclude`, `ExactSelect`); `where` is
+ * checked as written. A stray field anywhere is an error.
+ */
+export type TypedTableReader<D, T extends keyof D> = {
+    readonly $table: T;
+    findUnique<const I extends IncludeArg<D, T> | undefined = undefined, const S extends SelectArg<D, T> | undefined = undefined>(args: FindUniqueArgs<D, T, I, S>): Promise<RowOf<D, T, I, S> | null>;
+    findFirst<const I extends IncludeArg<D, T> | undefined = undefined, const S extends SelectArg<D, T> | undefined = undefined>(args: FindManyArgs<D, T, I, S>): Promise<RowOf<D, T, I, S> | null>;
+    findMany<const I extends IncludeArg<D, T> | undefined = undefined, const S extends SelectArg<D, T> | undefined = undefined>(args: FindManyArgs<D, T, I, S>): Promise<Array<RowOf<D, T, I, S>>>;
+    count(args: {
+        where: Where<D, T>;
+    }): Promise<number>;
+};
+/** `db` where only reading is allowed (a page render): this sequence's tables, read methods only. */
+export type TypedReadDb<D> = {
+    readonly [T in TableOf<D>]: TypedTableReader<D, T>;
+};
+type WriteValueOf<D, T extends keyof D, F> = ValueOf<D, T, F>;
+/** A new row: its parent required, any other field optional. */
+export type CreateData<D, T extends keyof D> = Simplify<{
+    [F in ParentOf<D, T>]: WriteValueOf<D, T, F>;
+} & {
+    [F in Exclude<FieldOf<D, T>, ParentOf<D, T>>]?: WriteValueOf<D, T, F> | null;
+}>;
+/** A change to a row: any field but the parent. */
+export type UpdateData<D, T extends keyof D> = {
+    [F in Exclude<FieldOf<D, T>, ParentOf<D, T>>]?: WriteValueOf<D, T, F> | null;
+};
+type TableWrites<D, T extends keyof D> = {
+    update(args: {
+        where: {
+            id: Id<T & string>;
+        };
+        data: UpdateData<D, T>;
+    }): Promise<{
+        id: Id<T & string>;
+    }>;
+    delete(args: {
+        where: {
+            id: Id<T & string>;
+        };
+        reason?: string;
+    }): Promise<{
+        id: Id<T & string>;
+    }>;
+} & (T extends 'session' ? unknown : {
+    create(args: {
+        data: CreateData<D, T>;
+    }): Promise<{
+        id: Id<T & string>;
+    }>;
+    /**
+     * The row whose `unique` field in `where` holds that value, updated; else a new row with it
+     * (18-record-search-index §4.5). `where` names exactly one `unique` field.
+     */
+    upsert(args: {
+        where: {
+            [F in Exclude<FieldOf<D, T>, ParentOf<D, T>>]?: WriteValueOf<D, T, F>;
+        };
+        create: CreateData<D, T>;
+        update: UpdateData<D, T>;
+    }): Promise<{
+        id: Id<T & string>;
+    }>;
+});
+/**
+ * `db`: this sequence's tables, Prisma-shaped, reads and writes on one object. Writes are V1
+ * `create` / `update` / `delete`. A contact may be created (with
+ * no lookup for one with the same phone or email, 15 §10.6.1); session rows are not created here.
+ */
+export type TypedDb<D> = {
+    readonly [T in TableOf<D>]: TypedTableReader<D, T> & TableWrites<D, T>;
+};
+type RowIfTable<D, T extends string> = T extends keyof D ? RowOf<D, T> : never;
+/**
+ * One channel's page function context (20 §5.2): `C` the channel, with what only it has (`ctx.call`,
+ * `ctx.sms`, `ctx.email`). Without `C`, any channel's: what a helper shared by several pages takes.
+ */
+export type TypedPageContext<D, S extends string, C extends PageChannel = PageChannel> = {
+    [K in C]: TypedPageBaseContext<D, S> & {
+        channel: K;
+    } & PageChannelCaps[K];
+}[C];
+type TypedPageBaseContext<D, S extends string> = {
+    /** Read-only: a render never writes. */
+    db: TypedReadDb<D>;
+    /** What the platform recorded (17b §7, 21 §6.7): `tried(ctx.runs, key)`, `tried(ctx.runs, key, 'case')`. */
+    runs: PageRuns;
+    /** Why this conversation happened when the platform started it; null for an inbound one. */
+    scheduledAction: PageScheduledAction | null;
+    /** The sequence's office hours now; null when it has none. */
+    officeHours: PageBaseContext['officeHours'];
+    /** The case's next step (40 §2.2): its pending contacts, soonest first; the platform shows it before the page. */
+    nextSteps: PageBaseContext['nextSteps'];
+    /** The business root's id. */
+    subject: Id<S>;
+    /** The instance this conversation is on: prefill it to a function that needs it (38 §2.2). */
+    instanceId: string;
+    /** The contact of the conversation; null outside one. */
+    caller: RowIfTable<D, 'contact'> | null;
+    /** This conversation's session row (the session fields, cells); null outside one. */
+    session: RowIfTable<D, 'session'> | null;
+    /** This conversation's platform facts (read-only, never a cell); null outside one. */
+    conversation: PageConversation | null;
+    /** Counts over this instance (`sessionCount`, `exchangeCount`). */
+    history: PageHistory;
+    /** ISO timestamp of this render. */
+    now: string;
+    /** The contact's time zone, today there, and `format` for a time as people read it (25 §11). */
+    time: PageTime;
+    /** The environment's configuration, read only (76 §2.19): `ctx.env.get('callback_number')`. */
+    env: PageBaseContext['env'];
+};
+export type TypedActionContext<D, S extends string> = {
+    db: TypedDb<D>;
+    subject: Id<S>;
+    caller: RowIfTable<D, 'contact'> | null;
+    /** On a call, this party's session for this case (25 §9); null by text and email. Written with `db.session.update`. */
+    session: RowIfTable<D, 'session'> | null;
+    now: string;
+};
+declare const CHOOSE_BRAND: unique symbol;
+/** `choose(rows, label)` over rows of `T` (25 §10): the rows a row parameter of `T` is chosen among. */
+export type TypedChoose<T extends string> = ChooseParam & {
+    readonly [CHOOSE_BRAND]?: T;
+};
+/**
+ * What the page fixed of an action's parameters (35 §2): values, a row parameter by its row's id; an
+ * optional one also `null`, none (the AI is not asked).
+ */
+export type PrefillOf<A> = {
+    [K in keyof A]?: A[K] | (undefined extends A[K] ? null : never);
+};
+/** The parameters of `A` that are rows. */
+type RowKeys<A> = {
+    [K in keyof A]-?: NonNullable<A[K]> extends {
+        readonly [ID_BRAND]: string;
+    } ? K : never;
+}[keyof A];
+/**
+ * The rows the AI chooses a row parameter among, each with its label (35 §2): `choose(rows, label)`.
+ * With no row parameter there is nothing to choose: `options` takes nothing (`{}` would take anything).
+ */
+export type OptionsOf<A> = [RowKeys<A>] extends [never] ? never : {
+    [K in RowKeys<A>]?: NonNullable<A[K]> extends {
+        readonly [ID_BRAND]: infer T extends string;
+    } ? TypedChoose<T> : never;
+};
+/** A page action's function (76 §2.11): `(ctx, args)`; what it is called with is the button's `prefill` and what the AI fills. */
+export type PageActionFn<A> = (ctx: never, args: A) => unknown;
+/** What a page function returns: `page(…)`, or `doNow(…)` to do something first (76). */
+export type PageResult = PageNode | DoNode;
+/** The page module of one sequence: `D` its tables (`PageTables`), `S` its business root table. */
+export type TypedPageModule<D, S extends string> = {
+    /** Each channel's page is its own (17b §9.1): what a call shows and what a text shows may differ. */
+    definePage<Call extends PageResult = never, Sms extends PageResult = never, Email extends PageResult = never>(definition: {
+        /** Called once when the conversation starts (24 §4): the persona for `ctx.channel`. */
+        persona: (ctx: TypedPageContext<D, S>) => string | Promise<string>;
+        /** Called once when the conversation starts (24 §4): the FAQ, at most 100 entries. */
+        faq?: (ctx: TypedPageContext<D, S>) => PageFaqEntry[] | Promise<PageFaqEntry[]>;
+        call?: (ctx: TypedPageContext<D, S, 'call'>) => Call | Promise<Call>;
+        sms?: (ctx: TypedPageContext<D, S, 'sms'>) => Sms | Promise<Sms>;
+        email?: (ctx: TypedPageContext<D, S, 'email'>) => Email | Promise<Email>;
+    }): {
+        kind: 'page';
+        persona: PagePersona;
+        faq: PageFaq | null;
+        channels: {
+            call?: (ctx: TypedPageContext<D, S, 'call'>) => Call | Promise<Call>;
+            sms?: (ctx: TypedPageContext<D, S, 'sms'>) => Sms | Promise<Sms>;
+            email?: (ctx: TypedPageContext<D, S, 'email'>) => Email | Promise<Email>;
+        };
+    };
+    /** The rows a row parameter is chosen among, each with what the AI sees of it (25 §10). */
+    choose<R extends {
+        readonly id: Id<TableOf<D>>;
+    }>(rows: readonly R[], label: (row: R) => string): TypedChoose<R['id'] extends {
+        readonly [ID_BRAND]: infer T extends string;
+    } ? T : never>;
+};
+type AnySlot = TypedSlot<unknown, string, string>;
+/** What a function takes: its `args`, the second parameter of `(ctx, args)` (38 §2.1). */
+export type FunctionParamsOf<Fn> = Fn extends (...args: infer A) => unknown ? A extends [unknown, infer P, ...unknown[]] ? P extends object ? P : Record<never, never> : Record<never, never> : Record<never, never>;
+/** `table.field` of this sequence: how the page says to fill it (`page({ extraction })`). */
+type FieldPathOf<D> = {
+    [T in TableOf<D>]: `${T}.${FieldOf<D, T>}`;
+}[TableOf<D>];
+/** `fn` of `__gen` (76 §2.15): a handle per company function, its `args` type the function's. */
+export type FunctionHandles<F> = {
+    readonly [N in keyof F & string]: FunctionHandle<N, FunctionParamsOf<F[N]>>;
+};
+/**
+ * `act` of `__gen` (76 §2.11): a handle per page action of `actions.ts`, its `args` type the action's. An
+ * action takes the page action's `ctx` (`ActionCtx`): one written for another (a company function's `Ctx`)
+ * has no handle, and `run()` says so.
+ */
+export type ActionHandles<A, D, S extends string> = {
+    readonly [N in keyof A & string]: A[N] extends (ctx: TypedActionContext<D, S>, ...rest: never[]) => unknown ? PageActionHandle<N, FunctionParamsOf<A[N]>> : `actions.${N} takes (ctx: ActionCtx, args): the page action's ctx`;
+};
+/** Add a row of `T` (15 §10.6): `fields` the AI fills, `prefill` what the page fixed, `options` a ref field's rows. */
+type CreateRowOptions<D, T extends TableOf<D>> = {
+    /** What the AI fills; a ref field is chosen in `options` instead (35 §2). */
+    fields: ReadonlyArray<Exclude<FieldOf<D, T>, ParentOf<D, T> | RowKeys<CreateData<D, T>>>>;
+    required?: ReadonlyArray<Exclude<FieldOf<D, T>, ParentOf<D, T>>>;
+    prefill?: Partial<CreateData<D, T>>;
+    /** The rows the AI chooses a ref field's row among (35 §2). */
+    options?: OptionsOf<Omit<CreateData<D, T>, ParentOf<D, T>>>;
+};
+/**
+ * The fields a prefill surely fills: there, and never null, undefined or a written-out '' (76 §2.14), as
+ * the write counts them; a `string` from code counts as filled (the render refuses it when it is ''). `{ body_part: null }`, `''` or a value that may be missing fills nothing: a required field prefilled so is still nobody's.
+ */
+type FilledKeys<P> = {
+    [X in keyof P]-?: undefined extends P[X] ? never : null extends P[X] ? never : string extends P[X] ? X : '' extends P[X] ? never : X;
+}[keyof P];
+/** The page's functions bound to one sequence (76 §2.17): what `__gen/index.ts` exports. */
+export type TypedPageFns<D, S extends string, F> = {
+    /** The page (76 §2.7): settings, then content by name. */
+    page(settings: PageSettings<{
+        readonly [K in FieldPathOf<D>]?: string;
+    }>, content: PageContent): PageNode;
+    /** A field the AI may write, or read only. A ref field is `refField()`. */
+    field(slot: AnySlot, options?: {
+        readOnly?: boolean;
+        expand?: boolean;
+    }): FieldNode;
+    /** A ref field: writable, the rows it may be set to (`options`); read-only, who its value is (`label`). */
+    refField(slot: AnySlot, options: {
+        options: ReadonlyArray<RefOption> | ChooseParam;
+        readOnly?: false;
+    } | {
+        readOnly: true;
+        label?: string;
+    }): FieldNode;
+    /** Add a row (15 §10.6). */
+    createRow<T extends TableOf<D>, const R extends ReadonlyArray<Exclude<FieldOf<D, T>, ParentOf<D, T>>> = [], P extends Partial<CreateData<D, T>> = {}, K extends string | undefined = undefined>(table: T, options: Omit<CreateRowOptions<D, T>, 'options' | 'required' | 'prefill'> & {
+        required?: R;
+        prefill?: P & {
+            readonly [X in Exclude<keyof P, keyof CreateData<D, T>>]: `${X & string} is not a field of ${T}`;
+        };
+        options?: undefined;
+        runKey?: K;
+    }): Action<'createRow', KeyedOf<K>, [Exclude<R[number], FilledKeys<P>>] extends [never] ? AllPrefilled : LeftForAi>;
+    /** With `options`, the AI chooses a ref field's row: a button's, never `doNow()`'s. */
+    createRow<T extends TableOf<D>, K extends string | undefined = undefined>(table: T, options: CreateRowOptions<D, T> & {
+        options: NonNullable<CreateRowOptions<D, T>['options']>;
+        runKey?: K;
+    }): Action<'createRow', KeyedOf<K>, LeftForAi>;
+    /**
+     * Run a company function (`fn.x`) or a page action (76 §2.15): every required parameter prefilled
+     * (what `doNow()` takes), or some left for the AI. `options` are rows of each row parameter's own table.
+     */
+    run<H extends AnyRunHandle, K extends string | undefined = undefined>(handle: H & SameArgs<H>, options: ([RequiredKeys<RunArgs<H>>] extends [never] ? {
+        prefill?: PrefillOf<RunArgs<H>>;
+    } : {
+        prefill: FullPrefill<RunArgs<H>>;
+    }) & {
+        options?: undefined;
+        args?: undefined;
+        say?: SayOf<H>;
+        runKey?: K;
+    }): RunAction<KeyedOf<K>, AllPrefilled>;
+    run<H extends AnyRunHandle, K extends string | undefined = undefined>(handle: H & SameArgs<H>, options?: {
+        prefill?: PrefillOf<RunArgs<H>>;
+        options?: OptionsOf<RunArgs<H>>;
+        args?: {
+            [P in keyof RunArgs<H>]?: string;
+        };
+        say?: SayOf<H>;
+        runKey?: K;
+    }): RunAction<KeyedOf<K>, LeftForAi>;
+    /** Delete a row and everything under it (15 §10.6.1). */
+    deleteRow<K extends string | undefined = undefined>(row: Id<TableOf<D>> | {
+        readonly id: Id<TableOf<D>>;
+    }, options?: {
+        reason?: string;
+        runKey?: K;
+    }): Action<'deleteRow', KeyedOf<K>, AllPrefilled>;
+};
+export {};
+//# sourceMappingURL=typed.d.ts.map

package/dist/core/page/typed.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=typed.js.map