@superpanel-sdk/runtime 0.2.3 → 0.7.0

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

@@ -0,0 +1,448 @@
+/**
+ * Pages written with functions (76): what `context.page.ts` is written with. Every node and every action
+ * is a platform function returning its own type: `page()`, `block()`, `list()`, `field()`, `text()`,
+ * `data()`, `button()`, `doNow()`, `toolbox()`; actions `run()`, `createRow()`, `warmTransfer()`, …
+ * A node carries a mark no JSON can carry (31 §8), so data from outside never becomes a field or a
+ * button. The page module turns the tree into the envelope (`toFnPageResult`), the one thing the
+ * platform reads (`render.ts`): what the AI reads of the page does not change (76 §2.20).
+ *
+ * The types here are the generic ones; `typed.ts` binds `page`'s extraction, `field`'s slot, `createRow`,
+ * `deleteRow` and `run` to one sequence's tables, functions (`fn`) and page actions (`act`) (`__gen/index.ts`).
+ *
+ * Runs in the page's QuickJS sandbox like the rest of the page module: no imports at runtime but the
+ * page module's own.
+ */
+import { type ChooseParam, type FieldCell, type RefFieldCell, type PageAction, type PageRow, type RefOption, type Slot, type SlotRef } from './define.js';
+import type { Envelope } from './envelope.js';
+import type { Spoken } from '../conversation/index.js';
+/** The mark of a node: `Symbol.for`, the same in every copy of the page module a bundle may hold. */
+export declare const NODE: unique symbol;
+/** The mark of an action (what a button or `doNow` does). */
+export declare const ACTION: unique symbol;
+/** The mark of a handle `run()` takes: a company function (`fn.x`) or a page action (`act.x`). */
+export declare const HANDLE: unique symbol;
+/** The mark of a platform tool (`pressKeypad()`, `convertTime()`). */
+export declare const TOOL: unique symbol;
+declare const KEYED: unique symbol;
+declare const READY: unique symbol;
+declare const NOT_BUTTON: unique symbol;
+declare const ARGS: unique symbol;
+/** What `doNow()` asks of an action's run key (76 §2.14). */
+export type RunKeyGiven = 'runKey given';
+export type RunKeyMissing = 'no runKey';
+/** Whether `K`, the type of an action's `runKey`, is given. */
+export type KeyedOf<K> = [K] extends [string] ? RunKeyGiven : RunKeyMissing;
+/** What `doNow()` asks of a `run()`'s parameters (76 §2.15). */
+export type AllPrefilled = 'every required parameter prefilled';
+export type LeftForAi = 'some left for the AI';
+export interface PageNode {
+    readonly [NODE]: 'page';
+}
+export interface BlockNode {
+    readonly [NODE]: 'block';
+}
+export interface ListNode {
+    readonly [NODE]: 'list';
+}
+export interface FieldNode {
+    readonly [NODE]: 'field';
+}
+export interface TextNode {
+    readonly [NODE]: 'text';
+}
+export interface DataNode {
+    readonly [NODE]: 'data';
+}
+export interface ButtonNode {
+    readonly [NODE]: 'button';
+}
+export interface ToolboxNode {
+    readonly [NODE]: 'toolbox';
+}
+export interface DoNode {
+    readonly [NODE]: 'do';
+}
+/** Left out of a block or a list: `verify: verified ? undefined : button(…)`, `x && field(…)`. */
+export type Skip = undefined | null | false;
+/**
+ * What a block holds: nodes only. A text is `text(…)`, data `data(…)`; a value that may be empty is
+ * `x ? text(x) : undefined` (`x && text(x)` may be `''` or `0`, not a node).
+ */
+export type PageItem = BlockNode | ListNode | FieldNode | TextNode | DataNode | ButtonNode | ToolboxNode;
+/** A block's or a page's content: its items by name. A button's or a toolbox's name is the code's only (76 §2.3). */
+export type PageContent = {
+    readonly [name: string]: PageItem | Skip;
+};
+/** What a list holds: one kind of node (76 §2.10). */
+export type ListItem = BlockNode | FieldNode | TextNode | ButtonNode;
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+/** A list of one kind of node, or the sentence tsc says (76 §2.10). */
+export type OneKind<I> = [I] extends [UnionToIntersection<I>] ? unknown : {
+    'list items are all one kind: all block(), all field(), all text() or all button()': true;
+};
+/** Whether a page node or an action is anywhere in `T` (at most 8 levels; data of unknown shape is data). */
+export type HoldsNode<T, Depth extends unknown[] = []> = Depth['length'] extends 8 ? false : T extends {
+    readonly [NODE]: string;
+} | {
+    readonly [ACTION]: string;
+} ? true : T extends readonly (infer E)[] ? HoldsNode<E, [...Depth, 0]> : T extends (...args: never[]) => unknown ? false : T extends object ? true extends {
+    [K in keyof T]-?: HoldsNode<T[K], [...Depth, 0]>;
+}[keyof T] ? true : false : false;
+/** Data with no node in it, or the sentence tsc says (76 §2.8). */
+export type NoNodes<T> = true extends HoldsNode<T> ? {
+    'data() holds data only: put page nodes in block()': true;
+} : unknown;
+/** The words of a block or a list (`<block title description>`). */
+export type BlockSettings = {
+    title?: string;
+    description?: string;
+};
+/** The page's settings (31 §9): `guide`, `extraction`, `voice`, `title`, `description`. */
+export type PageSettings<Extraction = Record<string, string>> = {
+    title?: string;
+    description?: string;
+    /** What to do now and how (24 §2.1). */
+    guide?: string;
+    /** How to fill a field on this page, by `table.field` (26 §15.3). */
+    extraction?: Extraction;
+    /** The voice to speak with from the next line (2026-11-03 voice rule). */
+    voice?: {
+        name: string;
+        [setting: string]: unknown;
+    };
+};
+/** Handles `run()` takes: a company function by name (`fn.x`), a page action of `actions.ts` (`act.x`). */
+export interface FunctionHandle<N extends string = string, A = unknown> {
+    readonly [HANDLE]: 'function';
+    readonly name: N;
+    readonly [ARGS]?: (args: A) => void;
+}
+export interface PageActionHandle<N extends string = string, A = unknown> {
+    readonly [HANDLE]: 'action';
+    readonly name: N;
+    readonly [ARGS]?: (args: A) => void;
+}
+export type RunHandle<A = unknown> = FunctionHandle<string, A> | PageActionHandle<string, A>;
+/** The `args` a handle's function takes. */
+export type HandleArgs<H> = H extends {
+    readonly [ARGS]?: (args: infer A) => void;
+} ? A : never;
+/** An action: what a button or `doNow()` does. `V` its verb; the marks say where it may go (76 §2.6, §2.14, §2.15). */
+export interface Action<V extends string = string, K = RunKeyGiven | RunKeyMissing, R = AllPrefilled | LeftForAi> {
+    readonly [ACTION]: V;
+    readonly [KEYED]: K;
+    readonly [READY]: R;
+}
+export interface RunAction<K = RunKeyGiven | RunKeyMissing, R = AllPrefilled | LeftForAi> extends Action<'run', K, R> {
+}
+export interface TransferVerbAction<K = RunKeyGiven | RunKeyMissing> extends Action<'transfer', K, AllPrefilled> {
+}
+export interface AnnounceVerbAction extends Action<'announce', RunKeyGiven, AllPrefilled> {
+    readonly [NOT_BUTTON]: 'announce() is only for doNow(): the AI never presses it';
+}
+/** A follow-up is a button only: the AI books it with the customer. Its run-key mark says so to `doNow()`. */
+export interface FollowUpVerbAction<V extends string = 'scheduleFollowUp' | 'cancelFollowUp'> extends Action<V, 'a button only: the AI books it with the customer', AllPrefilled> {
+}
+/** What a button may do: any action but `announce()`. */
+export type ButtonAction = {
+    readonly [ACTION]: string;
+    readonly [NOT_BUTTON]?: undefined;
+};
+/**
+ * What `doNow()` may do: an action with its run key (the name `tried(ctx.runs, …)` checks, 76 §2.14) and
+ * every required parameter prefilled (nobody fills the rest); not a follow-up.
+ */
+export type DoAction = {
+    readonly [ACTION]: string;
+    readonly [KEYED]: RunKeyGiven;
+    readonly [READY]: AllPrefilled;
+};
+/**
+ * A button's words (31 §5): `run` says what it is and when to press it; a transfer who it goes to; the rest
+ * have the platform's. An action that may be one of several (`flag ? warmTransfer(…) : end()`) needs the
+ * words of the strictest it may be: whichever it turns out to be, its words are there.
+ */
+export type ButtonWords<X> = [Extract<X, {
+    readonly [ACTION]: 'run';
+}>] extends [never] ? [Extract<X, {
+    readonly [ACTION]: 'transfer';
+}>] extends [never] ? {
+    title?: string;
+    does?: string;
+} : {
+    title: string;
+    does?: string;
+} : {
+    title: string; /** When to press it. */
+    does: string;
+};
+/** What the page fixed of an action's parameters (35 §2): an optional one may be `null`. */
+export type PrefillOf<A> = {
+    [K in keyof A]?: A[K] | (undefined extends A[K] ? null : never);
+};
+/** The required parameters of `A`. */
+export type RequiredKeys<A> = {
+    [K in keyof A]-?: undefined extends A[K] ? never : K;
+}[keyof A];
+/** Every required parameter prefilled, none of them null. */
+export type FullPrefill<A> = {
+    [K in RequiredKeys<A>]: A[K];
+} & PrefillOf<A>;
+/** A tool of the platform's (76 §2.18): placed in `toolbox()`. */
+export interface Tool<N extends string = string> {
+    readonly [TOOL]: N;
+}
+type Words = {
+    label?: string;
+    description?: string;
+};
+type Built = {
+    action: PageAction;
+    key?: string;
+};
+type RawAction = {
+    readonly [ACTION]: string;
+    /** The action as rendered, with the button's words. */
+    readonly build: (words: Words, mode: 'button' | 'do') => Built;
+    readonly runKey?: string;
+};
+type RawNode = {
+    readonly [NODE]: 'page';
+    settings: Record<string, unknown>;
+    content: unknown;
+} | {
+    readonly [NODE]: 'block';
+    settings: Record<string, unknown>;
+    content: unknown;
+} | {
+    readonly [NODE]: 'list';
+    settings: Record<string, unknown>;
+    items: unknown;
+} | {
+    readonly [NODE]: 'field';
+    make: () => FieldCell | RefFieldCell;
+} | {
+    readonly [NODE]: 'text';
+    text: string;
+} | {
+    readonly [NODE]: 'data';
+    value: unknown;
+} | {
+    readonly [NODE]: 'button';
+    action: RawAction;
+    words: Words;
+} | {
+    readonly [NODE]: 'toolbox';
+    tools: string[];
+} | {
+    readonly [NODE]: 'do';
+    action: RawAction;
+    wait?: boolean;
+};
+/** Whether `value` is a node a platform function made. */
+export declare function isNode(value: unknown): value is RawNode;
+/** The page (76 §2.7): settings, then content. What a page function returns, unless it returns `doNow()`. */
+export declare function page(settings: PageSettings, content: PageContent): PageNode;
+/** A block (76 §2.7): settings (`{}` for none), then its content by name. */
+export declare function block(settings: BlockSettings, content: PageContent): BlockNode;
+/** A list (76 §2.10): settings, then items, all one kind of node (`rows.map((r) => block({}, { … }))`). */
+export declare function list<I extends ListItem>(settings: BlockSettings, items: readonly (I | Skip)[] & OneKind<I>): ListNode;
+/** A field the AI may write, or read only (`readOnly`). A ref field is `refField()`. */
+export declare function field(slot: Slot, 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`). */
+export declare function refField(slot: Slot, options: {
+    options: readonly RefOption[] | ChooseParam;
+    readOnly?: false;
+} | {
+    readOnly: true;
+    label?: string;
+}): FieldNode;
+/** One text, read only. A value that may be empty: `x ? text(x) : undefined`. */
+export declare function text(value: string | number): TextNode;
+/** Data shown as it is, whatever keys it has (`$action` too): never a field or a button (31 §4). */
+export declare function data<T>(value: T & NoNodes<T>): DataNode;
+/** What the AI can press (31 §5): its words, and what it does (`action`). */
+export declare function button<X extends ButtonAction>(options: {
+    action: X;
+} & ButtonWords<X>): ButtonNode;
+/**
+ * What the page does now (31 §6), instead of a page: the AI neither sees nor presses it. The action has
+ * its run key, the name `tried(ctx.runs, …)` checks (76 §2.14); `wait: false` only for `run()`: an action
+ * that may be one of several (`flag ? run(…) : end()`) only when every one is a `run()`.
+ */
+export declare function doNow<X extends DoAction>(action: X, options?: [X] extends [{
+    readonly [ACTION]: 'run';
+}] ? {
+    wait?: boolean;
+} : {
+    wait?: never;
+}): DoNode;
+/** The platform's tools the AI may use on this page (76 §2.18): one toolbox a page, each tool once. */
+export declare function toolbox(tools: readonly Tool[]): ToolboxNode;
+/** Press keys on the other side's automated phone menu (76 §2.18): a call only. */
+export declare function pressKeypad(): Tool<'pressKeypad'>;
+/** Convert between a local time in a time zone and an instant, UTC (76 §2.18, §2.19). */
+export declare function convertTime(): Tool<'convertTime'>;
+export type RunOptions<A> = {
+    /** What the page fixed: the AI neither sees nor changes it. */
+    prefill?: PrefillOf<A>;
+    /** The rows the AI chooses a row parameter among (35 §2): `{ order: choose(orders, label) }`. */
+    options?: {
+        [K in keyof A]?: ChooseParam;
+    };
+    /** How to fill each parameter here (31 §7): the function says what it takes, the page how to fill it. */
+    args?: {
+        [K in keyof A]?: string;
+    };
+};
+/** What `run()` takes as its handle: a company function (`fn.x`) or a page action (`act.x`). */
+export type AnyRunHandle = {
+    readonly [HANDLE]: 'function' | 'action';
+    readonly name: string;
+};
+/**
+ * `say` of a `run()`: said while a company function runs, per language (66). A page action runs at once,
+ * next to the database: it takes none, and the type says so.
+ */
+export type SayOf<H> = [H] extends [{
+    readonly [HANDLE]: 'function';
+}] ? Spoken : 'say is for a company function (fn.x): a page action runs at once';
+/** The `args` `run()` checks: its handle's. */
+export type RunArgs<H> = HandleArgs<H>;
+type Same<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => (T extends Y ? 1 : 2) ? true : false;
+/** `true` when two of the args in `U` are not the same type. */
+type ArgsDiffer<U, All = U> = U extends unknown ? (All extends unknown ? (Same<U, All> extends true ? never : true) : never) : never;
+/**
+ * A handle that may be one of several (`fn[name]`, `flag ? act.a : act.b`) is one `run()` only when they
+ * all take the same args (76 §2.15): each checks the parameters it is given exactly, so prefill for one
+ * is wrong for another. Different args: one `run()` per branch.
+ */
+export type SameArgs<H> = [ArgsDiffer<HandleArgs<H>>] extends [never] ? unknown : {
+    readonly 'run() of one of several handles that take different args: write one run() per branch, flag ? run(a, …) : run(b, …)': never;
+};
+/**
+ * Run a company function (`fn.x`) or a page action (`act.x`, 76 §2.11). Two signatures: every
+ * required parameter prefilled (what `doNow()` takes), or some left for the AI.
+ */
+export declare function 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>;
+export declare function run<H extends AnyRunHandle, K extends string | undefined = undefined>(handle: H & SameArgs<H>, options?: RunOptions<RunArgs<H>> & {
+    say?: SayOf<H>;
+    runKey?: K;
+}): RunAction<KeyedOf<K>, LeftForAi>;
+/** Add a row (15 §10.6): `fields` are what the AI fills, `prefill` what the page fixed, `options` a ref field's rows. */
+export declare function createRow<K extends string | undefined = undefined>(table: string, options: {
+    fields: readonly string[];
+    required?: readonly string[];
+    prefill?: Record<string, unknown>;
+    options?: Record<string, ChooseParam>;
+    runKey?: K;
+}): Action<'createRow', KeyedOf<K>, AllPrefilled>;
+/** Delete a row and everything under it (15 §10.6.1). */
+export declare function deleteRow<K extends string | undefined = undefined>(row: PageRow | string, options?: {
+    reason?: string;
+    runKey?: K;
+}): Action<'deleteRow', KeyedOf<K>, AllPrefilled>;
+/** What every transfer takes (76 §2.9). */
+export type TransferOptions = {
+    /** E.164 number, or a SIP URI (`sip:desk@pbx.example.com`). */
+    to: string;
+    /** What the person hears about the call before it is put through, in their `language`. */
+    briefing?: string;
+    /** The language of the person taking the call (BCP-47; default `en`): the briefing is said in it, they are heard in it. */
+    language?: string;
+    /** A SIP `to` that asks for credentials: kept on the server. */
+    sipAuth?: {
+        username: string;
+        password: string;
+    };
+    /** The caller ID the person sees: the customer's number or ours. */
+    callerId?: 'customer' | 'service';
+};
+/**
+ * A transfer the person confirms (76 §2.9): `whisper` is what they hear, on a loop, when they pick up,
+ * before they confirm: who it is and what about. The platform adds how to confirm. Said in English for now.
+ */
+export type WarmTransferOptions = TransferOptions & {
+    whisper?: string;
+};
+export type BackgroundTransferOptions = WarmTransferOptions & {
+    /** What is said as the two are put through: to the person (`{{briefing}}`), to the customer per language. */
+    bridge?: {
+        person?: string;
+        customer?: Spoken;
+    };
+};
+/** Put the customer through; the person hears the briefing first and does not confirm (76 §2.9). */
+export declare function coldTransfer<K extends string | undefined = undefined>(options: TransferOptions & {
+    runKey?: K;
+}): TransferVerbAction<KeyedOf<K>>;
+/** The customer waits; the person confirms, hears the briefing, then is put through (76 §2.9). */
+export declare function warmTransfer<K extends string | undefined = undefined>(options: WarmTransferOptions & {
+    runKey?: K;
+}): TransferVerbAction<KeyedOf<K>>;
+/** The AI keeps talking with the customer while the person is called; put through once they take it (76 §2.9). */
+export declare function backgroundTransfer<K extends string | undefined = undefined>(options: BackgroundTransferOptions & {
+    runKey?: K;
+}): TransferVerbAction<KeyedOf<K>>;
+/** End the conversation (a call hangs up once the last line has played). */
+export declare function end<K extends string | undefined = undefined>(options?: {
+    runKey?: K;
+}): Action<'end', KeyedOf<K>, AllPrefilled>;
+/** Leave a message on the voicemail, word for word, then hang up (25 §13). */
+export declare function voicemail<K extends string | undefined = undefined>(options: {
+    text: Spoken;
+    runKey?: K;
+}): Action<'voicemail', KeyedOf<K>, AllPrefilled>;
+/** Ask the customer to press a key; what they press is written to `write` (through `map`). */
+export declare function keypad(options: {
+    runKey: string;
+    say: Spoken;
+    digits: string[];
+    timeoutMs?: number;
+    write?: Slot | SlotRef;
+    map?: Record<string, string | number | boolean>;
+}): Action<'keypad', RunKeyGiven, AllPrefilled>;
+/** Book the case's next step (40 §2.2), or move one already booked (51 §2). The AI gives when, in UTC (76 §2.19). */
+export declare function scheduleFollowUp(options: {
+    channels: Array<'call' | 'sms' | 'email'>;
+    /** What the page fixed: the channel, or whom (a contact's id). */
+    prefill?: {
+        channel?: 'call' | 'sms' | 'email';
+        contactId?: string;
+    };
+    /** The contacts the AI chooses among: `{ contactId: choose(contacts, label) }`. */
+    options?: {
+        contactId: ChooseParam;
+    };
+    runKey?: string;
+}): FollowUpVerbAction<'scheduleFollowUp'>;
+/** Cancel the case's next step (40 §2.2): the AI says why. */
+export declare function cancelFollowUp(options?: {
+    runKey?: string;
+}): FollowUpVerbAction<'cancelFollowUp'>;
+/** Say a fixed text, word for word (a compliance statement): `doNow()` only. `answers`: it answers what the customer said. */
+export declare function announce(options: {
+    runKey: string;
+    text: Spoken;
+    answers?: boolean;
+}): AnnounceVerbAction;
+/** `fn` of `__gen` (76 §2.15): a handle per company function, by name; the types say which names there are. */
+export declare function functionHandles(): Record<string, FunctionHandle>;
+/** `act` of `__gen` (76 §2.11): a handle per page action of `actions.ts`, by name; the types say which names there are. */
+export declare function actionHandles(): Record<string, PageActionHandle>;
+/** What a page function returned, as the platform reads it: `page()` or `doNow()`, as its envelope. */
+export declare function toFnPageResult(value: unknown): Envelope;
+export {};
+//# sourceMappingURL=fns.d.ts.map