@superpanel-sdk/runtime 0.2.3 → 0.5.0

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

@@ -0,0 +1,642 @@
+/**
+ * The page module's types bound to one sequence (15 §10.15): what `__gen/index.ts` exports as
+ * `definePage`, `field`, `schemaField`, `createRow`, `deleteRow` and `defineAction`. 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) gets the case
+ *    (`CaseInput`) and reads with `ctx.api.db`.
+ */
+import type { PageTime, ChooseParam, CreateRowAction, CustomAction, DeleteRowAction, FieldCell, FieldOptions, RefFieldCell, RefOption, MessageAction, MessageOptions, PageBaseContext, PageChannel, PageChannelCaps, PageConversation, PageFaq, PageFaqEntry, PageHistory, PagePersona, PageRuns, PageScheduledAction, Placeable, SchemaFieldOptions, 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;
+};
+/** 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;
+    contains?: string;
+    startsWith?: string;
+    endsWith?: string;
+    /** 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>;
+};
+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;
+    cursor?: {
+        id: Id<T & string>;
+    };
+};
+/** `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 contact's agreed follow-ups still to come (09). */
+    followUps: PageBaseContext['followUps'];
+    /** The business root's id. */
+    subject: Id<S>;
+    /** 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;
+    /** A text or an email to send now (25 §8): `ctx.messages.text('link', { body })`. */
+    messages: TypedPageMessages<D>;
+    /** The contact's time zone, today there, and `format` for a time as people read it (25 §11). */
+    time: PageTime;
+};
+type TypedMessageOptions<D> = Omit<MessageOptions, 'to'> & {
+    /** The contact it goes to (a contact row the page read); absent: the contact of this conversation. */
+    to?: RowIfTable<D, 'contact'> | Id<'contact'>;
+};
+/** `ctx.messages`, its `to` a contact of this company. */
+export type TypedPageMessages<D> = {
+    text(key: string, options?: TypedMessageOptions<D>): MessageAction;
+    email(key: string, options?: TypedMessageOptions<D> & {
+        subject?: string;
+    }): MessageAction;
+};
+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;
+};
+/** `table.field` (or `table.id`, a row) of this sequence: what `schemaField` takes. */
+export type SchemaFieldPath<D> = {
+    [T in TableOf<D>]: `${T}.id` | `${T}.${FieldOf<D, T>}`;
+}[TableOf<D>];
+export type TypedSchemaFieldParam<P extends string> = {
+    readonly $schemaField: P;
+    readonly extraction?: string;
+};
+/** One parameter: a schema field, or plain JSON Schema (an LLM function call's `parameters`). */
+export type TypedActionParam<D> = TypedSchemaFieldParam<SchemaFieldPath<D>> | {
+    readonly type: 'string';
+    readonly description?: string;
+    readonly enum?: readonly string[];
+} | {
+    readonly type: 'number' | 'integer';
+    readonly description?: string;
+    readonly enum?: readonly number[];
+} | {
+    readonly type: 'boolean';
+    readonly description?: string;
+} | {
+    readonly type: 'array';
+    readonly items: TypedActionParam<D>;
+    readonly description?: string;
+} | {
+    readonly type: 'object';
+    readonly properties: {
+        readonly [key: string]: TypedActionParam<D>;
+    };
+    readonly required?: readonly string[];
+    readonly description?: string;
+};
+export type TypedActionParameters<D> = {
+    readonly type: 'object';
+    readonly properties: {
+        readonly [key: string]: TypedActionParam<D>;
+    };
+    readonly required?: readonly string[];
+};
+/** What `run` gets for one parameter. */
+type ParamValue<D, P> = P extends {
+    $schemaField: `${infer T}.${infer F}`;
+} ? T extends keyof D ? F extends 'id' ? Id<T> : ValueOf<D, T, F> : never : P extends {
+    type: 'string';
+    enum: readonly (infer E)[];
+} ? E : P extends {
+    type: 'string';
+} ? string : P extends {
+    type: 'number' | 'integer';
+    enum: readonly (infer E)[];
+} ? E : P extends {
+    type: 'number' | 'integer';
+} ? number : P extends {
+    type: 'boolean';
+} ? boolean : P extends {
+    type: 'array';
+    items: infer I;
+} ? Array<ParamValue<D, I>> : P extends {
+    type: 'object';
+    properties: infer Props;
+} ? ArgsOf<D, {
+    properties: Props;
+    required: P extends {
+        required: infer R;
+    } ? R : [];
+}> : never;
+type RequiredOf<P> = P extends {
+    required: readonly (infer R)[];
+} ? R : never;
+/** What `run` gets: every parameter, required ones present, others optional. */
+export type ArgsOf<D, P> = P extends {
+    properties: infer Props;
+} ? Simplify<{
+    -readonly [K in Extract<keyof Props, RequiredOf<P>>]: ParamValue<D, Props[K]>;
+} & {
+    -readonly [K in Exclude<keyof Props, RequiredOf<P>>]?: ParamValue<D, Props[K]>;
+}> : Record<never, never>;
+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 a placed action is called with: a value, or for a row parameter its row's id or `choose(...)` (25 §10). */
+export type PrefillOf<A> = {
+    [K in keyof A]?: A[K] | (NonNullable<A[K]> extends {
+        readonly [ID_BRAND]: infer T extends string;
+    } ? TypedChoose<T> : never);
+};
+/**
+ * A custom action: called to prefill arguments (`markError({ injury: i.id })`, one button per row) or to
+ * offer the rows a row argument is chosen among (`cancel({ appointment: choose(rows, label) })`, 25 §10).
+ * Placing it as it is leaves a row argument to the rows the page happens to show: not recommended.
+ */
+export type TypedDefinedAction<A> = Placeable<CustomAction, PrefillOf<A>> & {
+    readonly actionName: string;
+};
+/** 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 = never, Sms = never, Email = 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>;
+        };
+    };
+    field<Sl extends TypedSlot<unknown, string, string>>(slot: Sl, options?: FieldOptions): FieldCell<Sl>;
+    /** A ref field (26 §16.2 #7): the rows it may point at, `{ id, label }` each, or `choose(rows, label)`. */
+    refField<Sl extends TypedSlot<unknown, string, string>>(slot: Sl, options?: {
+        options?: ReadonlyArray<RefOption & {
+            id: Sl['value'] & string;
+        }> | ChooseParam;
+        readOnly?: boolean;
+    }): RefFieldCell<Sl>;
+    schemaField<const P extends SchemaFieldPath<D>>(path: P, options?: SchemaFieldOptions): TypedSchemaFieldParam<P>;
+    createRow<T extends TableOf<D>, const F extends readonly Exclude<FieldOf<D, T>, ParentOf<D, T>>[]>(table: T | {
+        readonly $table: T;
+    }, options: {
+        fields: F;
+        required?: ReadonlyArray<F[number]>;
+        label?: string;
+        description?: string;
+    }): Placeable<CreateRowAction, Partial<CreateData<D, T>>>;
+    deleteRow(row: Id<TableOf<D>> | {
+        readonly id: Id<TableOf<D>>;
+    }, options?: {
+        reason?: string;
+        label?: string;
+        description?: string;
+    }): DeleteRowAction;
+    /** 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>;
+    defineAction<const P extends TypedActionParameters<D> = {
+        type: 'object';
+        properties: {};
+    }>(definition: {
+        name: string;
+        description: string;
+        parameters?: P;
+        run: (args: ArgsOf<D, P>, ctx: TypedActionContext<D, S>) => unknown;
+    }): TypedDefinedAction<ArgsOf<D, P>>;
+};
+/** What a page function may return instead of the page (17b §9.8): an action to run first. */
+type ReturnedAction = {
+    $action: string;
+} | {
+    $perform: true;
+} | ((...args: never[]) => unknown);
+/**
+ * The document a page script returns: `PageDocumentOf<typeof page>` of `context.page.ts`'s default
+ * export. An action the page function returns instead (a lookup, a keypad) is not part of it.
+ */
+export type PageDocumentOf<P> = P extends {
+    channels: infer C;
+} ? {
+    [K in keyof C]: C[K] extends ((...args: never[]) => infer R) | undefined ? Exclude<Awaited<R>, ReturnedAction> : never;
+}[keyof C] : never;
+export {};
+//# sourceMappingURL=typed.d.ts.map

package/dist/core/page/typed.js

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

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

@@ -0,0 +1,33 @@
+/**
+ * What the AI reads of a page (24 §3, 26 §15.5): one layer, the whole page, like a rep's screen. The
+ * page decides what is on it; the platform works out nothing from it. Everything is an element; every
+ * attribute value is JSON (strings "…" with \" and \n, numbers, true/false, null, lists); free text is
+ * always a `value` attribute; flush left.
+ *
+ *   <notes><note id about value/></notes>   the model's own reminders (17b §8), first, all of them
+ *   <guide value/>                          the page's `$guide`: what to do now and how
+ *   <page title description fallback>       the page:
+ *     <definitions>                         once for the page, a definition per `table.field` some field
+ *       <definition for label type …/>      on it shows expanded (`field(slot, { expand: true })`)
+ *     <block key title description>         a part of the page; inside a list, without `key`
+ *     <list key title description>          several things of one kind (an array on the page)
+ *     <field id key readonly more type value value-label one-of state reason/>   one value; `more`: its
+ *                                           definition is not shown (its type is); a ref's one-of: its rows
+ *     <text key value/>                     read-only text
+ *     <button id title does><arg …/></button>
+ */
+import type { BlockNode, RenderedPage } from './render.js';
+export type WorkspaceNote = {
+    id: string;
+    text: string;
+    about?: string;
+};
+export type WorkspaceTextOptions = {
+    notes?: readonly WorkspaceNote[];
+};
+export declare function workspaceText(page: RenderedPage, options?: WorkspaceTextOptions): string;
+/** The block at `path` (`''`: the root). */
+export declare function blockAt(page: RenderedPage, path: string): BlockNode | null;
+/** What `view` shows of one thing on the page (24 §3.2): a field with its definition, a button with its arguments. */
+export declare function viewText(page: RenderedPage, id: string): string | null;
+//# sourceMappingURL=workspace.d.ts.map