@superpanel-sdk/runtime 0.2.3 → 0.7.0

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

@@ -0,0 +1,295 @@
+import type { CompiledSlotSchema, RuntimeFieldDef } from '../slot/types.js';
+import { type ActionParameters, type PageToolName } from './define.js';
+import type { ChannelAction, PageAction, PageChannel, SlotRef, SlotState } from './define.js';
+import { type Spoken } from '../conversation/index.js';
+/**
+ * `table:` and the last 12 hex digits of the row's uuid (33): what the row is called in logs, the
+ * timeline and the database too, so the same in every conversation and every process; nothing to keep.
+ * A name comes from the id alone, never from which row came first: two rows of a table alike in those
+ * digits (one page of n rows: about n² / 2⁴⁹) are both named by their whole id from then on, and the
+ * short name they share resolves to neither. So a name from an earlier conversation, or another
+ * process, means the row it meant or no row (the AI is told), never another row. A name resolves only
+ * to a row named here, and the AI's names are checked against the page's own (`one-of`, `enum`) first.
+ */
+export declare class RowNames {
+    /** The rows named here: id → table. */
+    private readonly tables;
+    /** A short name → the ids of its table ending in its digits. */
+    private readonly byShort;
+    name(table: string, id: string): string;
+    resolve(name: string): {
+        table: string;
+        id: string;
+    } | undefined;
+    nameOf(id: string): string | undefined;
+}
+export type ReadSlot = {
+    value: unknown;
+    state: SlotState;
+    reason: string | null;
+    updatedAt: string | null;
+};
+export type PageReads = {
+    /** A row this run read, with its true slots; undefined when it was not read. */
+    row(id: string): {
+        table: string;
+        slots: Record<string, ReadSlot>;
+    } | undefined;
+    /** The ids new rows of `table` would hang under, from the parent conditions of this run's reads. */
+    parentsOf(table: string): readonly string[];
+};
+/** A block. Only the root has `guide` (24 §2.1): what to do now and how, the page's words. */
+export type BlockNode = {
+    kind: 'block';
+    key: string;
+    path: string;
+    title?: string;
+    description?: string;
+    list: boolean;
+    children: PageNode[];
+    guide?: string;
+};
+export type PageNode = BlockNode
+/** `expand`: shown with its definition (24 §2.2). */
+ | {
+    kind: 'cell';
+    key: string;
+    path: string;
+    slotId: string;
+    readOnly: boolean;
+    expand?: boolean;
+} | {
+    kind: 'text';
+    key: string;
+    path: string;
+    value: string | number | boolean | null;
+} | {
+    kind: 'action';
+    key: string;
+    path: string;
+    actionId: string;
+};
+export type RenderedCell = {
+    slotId: string;
+    ref: SlotRef;
+    /** The row's page name, `table:<uuid tail>`. */
+    row: string;
+    /** A ref's value, by its row's name (33). */
+    valueRow?: string;
+    label: string;
+    description?: string;
+    /** The schema's; the page's `$extraction` for its `table.field` replaces it (`RenderedPage.extractions`). */
+    extraction?: string;
+    /** The field's type; `ref` for a lookup (26 §16.2 #7), as a row argument's. */
+    type: RuntimeFieldDef['dataType'] | 'ref';
+    /** A `select` / `multi_select` field's options; null on every other type. */
+    choices: string[] | null;
+    /** For a lookup (`refField`): the rows the page offers, by page name, in its order. */
+    options?: string[];
+    /** For a lookup: what the AI sees of each row the page offered, by page name (26 §16.2 #7). */
+    optionLabels?: Record<string, string>;
+    value: unknown;
+    state: SlotState;
+    reason: string | null;
+    updatedAt: string | null;
+    /** Writable in at least one place on the page (schema allows, page did not tighten everywhere). */
+    writable: boolean;
+    paths: string[];
+};
+/**
+ * A field type a `schemaField` argument keeps, named as the field's definition names it and checked as a
+ * fill of the field is (`string`, `number` and `boolean` are the plain ones below).
+ */
+export type FieldArgType = 'text' | 'phone' | 'email' | 'date' | 'datetime' | 'time' | 'select';
+/**
+ * One argument as the AI fills it. Never sent to a model as a schema: the page shows it as `<arg>` and
+ * the platform checks what the AI passed against it. A `schemaField` argument has its field's type
+ * (26 §15.8: the same names as a field's definition); a row choice is `ref`, its `enum` the rows' page
+ * names, and the platform hands `run` the row's id. The rest is plain JSON Schema, as the action wrote it.
+ */
+export type InputProperty = {
+    type: 'string';
+    description?: string;
+    enum?: Array<string | number>;
+} | {
+    type: 'number' | 'integer' | 'boolean';
+    description?: string;
+    enum?: Array<string | number>;
+} | {
+    type: FieldArgType;
+    description?: string;
+    enum?: string[];
+} | {
+    type: 'multi_select';
+    enum: string[];
+    description?: string;
+} | {
+    type: 'ref';
+    table: string;
+    enum: string[];
+    description?: string; /** What the AI sees of each row (`choose`), by page name. */
+    labels?: Record<string, string>;
+} | {
+    type: 'array';
+    items: InputProperty;
+    description?: string;
+} | {
+    type: 'object';
+    properties: Record<string, InputProperty>;
+    required?: string[];
+    description?: string;
+    /** May also be null. */
+    nullable?: true;
+    /** A field value with its own checks: the argument is validated as one (`contact_schedule`). */
+    'x-type'?: 'contact_schedule';
+};
+export type InputSchema = {
+    type: 'object';
+    properties: Record<string, InputProperty>;
+    required: string[];
+};
+export type RenderedAction = {
+    id: string;
+    kind: PageAction['$action'];
+    name: string;
+    description: string;
+    /** JSON Schema of the arguments the AI fills (prefilled ones left out); null: nothing to fill. */
+    input: InputSchema | null;
+    /** Server-only: what running it needs. Never shown to the AI. */
+    server: {
+        kind: 'createRow';
+        table: string;
+        parentId: string | null;
+        set: Record<string, unknown>;
+        fields: string[];
+        required: string[]; /** The run key, when the page named one. */
+        key?: string;
+    } | {
+        kind: 'deleteRow';
+        table: string;
+        rowId: string;
+        reason?: string; /** The run key, when the page named one. */
+        key?: string;
+    } | {
+        kind: 'custom';
+        name: string;
+        prefill: Record<string, unknown>; /** The run key, when the page named one. */
+        key?: string;
+    } | {
+        kind: 'channel';
+        spec: ChannelAction;
+    }
+    /**
+     * Book the case's next step (40 §2.2) on one of `channels`; `prefill`: what the page fixed (the
+     * channel, the contact's id), not asked of the AI.
+     */
+     | {
+        kind: 'followUp';
+        key: string;
+        channels: Array<'call' | 'sms' | 'email'>;
+        prefill: {
+            channel?: 'call' | 'sms' | 'email';
+            contactId?: string;
+        };
+    }
+    /** Cancel the case's next step (40 §2.2), with why. */
+     | {
+        kind: 'cancelFollowUp';
+        key: string;
+    }
+    /** A platform tool (76 §2.18): the platform runs it, the AI reads the result next turn. */
+     | {
+        kind: 'tool';
+        tool: PageToolName;
+    }
+    /** A company function (20 §6.2): run on the Worker by the platform, waited for, with the page's prefilled arguments. */
+     | {
+        kind: 'function';
+        name: string; /** Per language (66): the engine says the call's. */
+        say?: Spoken;
+        prefill?: Record<string, unknown>; /** The run key, when the page named one. */
+        key?: string;
+    };
+};
+/**
+ * The page function returned an action to run now instead of a page (17b §9.8): `action` is rendered
+ * as a button would be (its rows checked), `key` names its runs.
+ */
+export type AutoAction = {
+    action: RenderedAction;
+    key: string;
+    wait: boolean;
+};
+export type RenderedPage = {
+    root: BlockNode;
+    /** Set when the page function returned an action to run now: the page then has nothing else. */
+    auto?: AutoAction;
+    cells: Record<string, RenderedCell>;
+    actions: Record<string, RenderedAction>;
+    /**
+     * Set on a stand-in page when the page script failed (15 §10.9): the last good page marked stale and
+     * read-only, or an empty page. Nothing on it can be written, and it has no actions.
+     */
+    fallback?: {
+        reason: string;
+        stale: boolean;
+    };
+    /** Every row on the page, by page name; `parentId` is its parent. */
+    rows: Record<string, {
+        table: string;
+        id: string;
+        parentId: string | null;
+    }>;
+    /** The page's `$extraction` (26 §15.3): how to fill a field on this page, by `table.field`; replaces the schema's. */
+    extractions?: Record<string, string>;
+    /** The voice the page asks for (`page({ voice })`, 76). */
+    voice?: unknown;
+    warnings: string[];
+};
+export declare class PageDocumentError extends Error {
+    constructor(message: string);
+}
+export type RenderDocumentInput = {
+    document: unknown;
+    schema: CompiledSlotSchema;
+    reads: PageReads;
+    names: RowNames;
+    /** The conversation's channel: a button the channel cannot do (a transfer by text) is an error (20 §5.2). */
+    channel?: PageChannel;
+    /** The sequence's functions' parameters, from their `args` types (38 §2.4): a function button's. */
+    functions?: Readonly<Record<string, {
+        parameters?: ActionParameters;
+    }>>;
+    /** The page's actions' parameters, from their `args` types (38 §2.9): a page action button's. */
+    actions?: Readonly<Record<string, {
+        parameters?: ActionParameters;
+    }>>;
+};
+export declare function renderDocument(input: RenderDocumentInput): RenderedPage;
+/**
+ * The buttons' ids (46 §2.1), in page order: what each does (its run key's words: a function's name,
+ * `add:injury`, `remove`, `transfer`, …); where several on the page do the same, the rows that tell them
+ * apart, by page name (`voidInjury@injury:3f9a2c1d7e04`); where that still leaves two alike, `#2`, `#3`
+ * after the first. Unique on the page, and the same from one render to the next while the button does
+ * the same thing to the same rows.
+ */
+export declare function buttonIds(buttons: readonly RenderedAction[], rows: RenderedPage['rows']): string[];
+/**
+ * The button the AI means by `id` on this page (46 §2.1), or null. Its own id first; else an id it read
+ * on an earlier page, where alike buttons needed their rows (`bookSlot@slot_option:d12f648904ec`) and now
+ * one is left (`bookSlot`): the one button doing that to those rows. Never a guess among several.
+ */
+export declare function pressedButton(page: RenderedPage, id: string): string | null;
+/**
+ * The run key of a button on the page (17b §7): the action's own key, whoever runs it — the model
+ * pressing it, or the page function returning it — not its place on the page, which moves with rows.
+ */
+export declare function runKeyOf(action: RenderedAction): string;
+/** The run key of an action the page function returned, when it names none. */
+export declare function actionKey(action: PageAction): string;
+/**
+ * The page to show when the page script failed (15 §10.9): the last good page, every cell read-only
+ * and no actions, marked stale; without one, an empty page.
+ */
+export declare function fallbackPage(last: RenderedPage | null, reason: string): RenderedPage;
+//# sourceMappingURL=render.d.ts.map