@superpanel-sdk/runtime 0.2.3 → 0.5.0

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

@@ -0,0 +1,834 @@
+/**
+ * The page module (15 §10.2–§10.6): what a sequence's `context.page.ts` is written with. It runs
+ * inside the QuickJS sandbox, bundled into the page script, so it imports nothing at runtime and only
+ * uses `globalThis.__host` (the sandbox's async host call, services `page/sandbox.ts`).
+ *
+ * A page script reads with `db` and returns a free-form document: objects are blocks, arrays are
+ * lists, a slot is a cell, `field(slot, …)` a cell with page settings, other plain values read-only
+ * content, and actions (`createRow`, `deleteRow`, `defineAction`) buttons. The platform turns the
+ * document into a `RenderedPage` (`render.ts`).
+ */
+import type { Channel, Direction } from '../conversation/index.js';
+import type { TimelineEntry, TimelineWhere } from './timeline.js';
+export type SlotState = 'filled' | 'empty' | 'asked_unknown' | 'declined';
+export type SlotRef = {
+    table: string;
+    id: string;
+    field: string;
+};
+/** One field as read: plain data, never mutated. */
+export type Slot<V = unknown> = Readonly<{
+    value: V | null;
+    state: SlotState;
+    reason: string | null;
+    updatedAt: string | null;
+    ref: SlotRef;
+    /** The target row, on a lookup that was `include`d. */
+    row?: PageRow | null;
+}>;
+/** A row as `db` returns it: `id`, one slot per field. */
+export type PageRow = {
+    readonly id: string;
+} & {
+    readonly [field: string]: unknown;
+};
+export type FindArgs = {
+    where?: Record<string, unknown>;
+    include?: Record<string, unknown>;
+    select?: Record<string, boolean>;
+    orderBy?: Record<string, 'asc' | 'desc'> | Array<Record<string, 'asc' | 'desc'>>;
+    take?: number;
+    skip?: number;
+    cursor?: {
+        id: string;
+    };
+};
+/** One table's read methods (Prisma Client's read-only subset). */
+export type TableReader<Row = PageRow> = {
+    readonly $table: string;
+    findUnique(args: {
+        where: Record<string, unknown>;
+        include?: FindArgs['include'];
+        select?: FindArgs['select'];
+    }): Promise<Row | null>;
+    findFirst(args: FindArgs): Promise<Row | null>;
+    findMany(args: FindArgs): Promise<Row[]>;
+    count(args: {
+        where: Record<string, unknown>;
+    }): Promise<number>;
+};
+/**
+ * Prisma-shaped writes of an action's `run` (15 §10.6.1): create / update / upsert / delete. `upsert`
+ * finds the row by one `unique` field (18-record-search-index §4.5): updated when there is one, else
+ * created with that value.
+ */
+export type TableWriter = {
+    create(args: {
+        data: Record<string, unknown>;
+    }): Promise<{
+        id: string;
+    }>;
+    update(args: {
+        where: {
+            id: string;
+        };
+        data: Record<string, unknown>;
+    }): Promise<{
+        id: string;
+    }>;
+    upsert(args: {
+        where: Record<string, unknown>;
+        create: Record<string, unknown>;
+        update: Record<string, unknown>;
+    }): Promise<{
+        id: string;
+    }>;
+    delete(args: {
+        where: {
+            id: string;
+        };
+        reason?: string;
+    }): Promise<{
+        id: string;
+    }>;
+};
+/** `db` where only reading is allowed (a page render): each table's read methods. */
+export type ReadDb = {
+    readonly [table: string]: TableReader;
+};
+/** `db`, Prisma-shaped: each table's read and write methods on one object. */
+export type Db = {
+    readonly [table: string]: TableReader & TableWriter;
+};
+/**
+ * What the platform knows about this conversation (11-remove-sequence-schema §3.3): written once when
+ * its session opened, read-only, never a cell.
+ */
+export type PageConversation = {
+    /** The session id. */
+    id: string;
+    channel: Channel;
+    /** Who started this conversation; a resumed one keeps it. */
+    direction: Direction;
+    /** The contact was created while this conversation opened. */
+    isNewContact: boolean;
+    /** ISO timestamp the session opened. */
+    startedAt: string;
+};
+/**
+ * Counts over this instance, worked out when the page renders (11-remove-sequence-schema §3.3.1).
+ * The first call of the instance is `await history.sessionCount({ channel: 'call' }) === 1`.
+ */
+export type PageHistory = {
+    /** Conversations (sessions) of this instance, every contact, the current one included. */
+    sessionCount(where?: {
+        channel?: Channel;
+    }): Promise<number>;
+    /**
+     * Exchanges of this instance recorded so far (an unanswered dial included). The current
+     * conversation's own is recorded once its first step is decided, so the opening decision does not
+     * count it (a scheduled call's, written before dialing, it does); later turns do. "Is this the first
+     * call" is `sessionCount`'s question.
+     */
+    exchangeCount(where?: {
+        channel?: Channel;
+        direction?: Direction;
+    }): Promise<number>;
+    /**
+     * The case's timeline (20 §3): messages, calls, the AI's runs and actions, field changes, scheduled
+     * contacts, oldest first; the newest `limit` (50) unless `before` pages back. A text page can show the
+     * last call; a call page, the texts since.
+     */
+    timeline(where?: TimelineWhere): Promise<TimelineEntry[]>;
+};
+/** The channels a page function is written for (17b §9.1, 20 §5.1): one page function per channel. */
+export type PageChannel = 'call' | 'sms' | 'email';
+/**
+ * What the platform recorded (17b §9.8), read-only. `actions` by action key: every run of an action in
+ * this run on this case (one the page function returned, or a button the AI pressed), oldest first;
+ * `caseActions` the same for the whole case, every channel and run (21 §6.7).
+ */
+export type PageRuns = {
+    actions: Record<string, PageActionRun[]>;
+    caseActions: Record<string, PageActionRun[]>;
+};
+/** Where `tried()` and `lastActionRun()` look: this run on this case (the default), or the whole case. */
+export type ActionRunScope = 'run' | 'case';
+/** `started`: under way (a keypad or a transfer waiting for its result, a function running). */
+export type PageActionRun = {
+    result: 'ok' | 'failed' | 'started';
+    /** ISO time. */
+    at: string;
+    error?: string;
+    /** What a channel action brought back (the digits pressed), or what a function returned (25 §11, as text). */
+    value?: string;
+};
+/** Whether the action `key` ran at least once (whatever its result), in this run or (`'case'`) on the case. */
+export declare function tried(runs: PageRuns | null | undefined, key: string, scope?: ActionRunScope): boolean;
+/** The latest run of the action `key`, in this run or (`'case'`) on the case, if any. */
+export declare function lastActionRun(runs: PageRuns | null | undefined, key: string, scope?: ActionRunScope): PageActionRun | null;
+/** An agreed follow-up: the channel, when (ISO), and what it is about. */
+export type PageFollowUp = {
+    channel: string;
+    scheduledFor: string;
+    note: string | null;
+};
+/**
+ * The button that books what the customer just asked for or agreed to (25 §5): a call back, a text, an
+ * email, at the time they said. The platform books it at once as an agreed follow-up (09): the exchange
+ * and the time of their words are its own; the AI gives the channel, the time and their words.
+ */
+export type FollowUpAction = {
+    $action: 'followUp';
+    /** The run key (default `followUp`). */
+    key: string;
+    /** The channels the customer may be followed up on, of the ones this sequence has a page for. */
+    channels: Array<'call' | 'sms' | 'email'>;
+    label?: string;
+    description?: string;
+};
+/** `ctx.followUps`: the agreed follow-ups still to come, and `agree(...)`, the button that books one. */
+export type PageFollowUps = PageFollowUp[] & {
+    agree(options: {
+        channels: Array<'call' | 'sms' | 'email'>;
+        key?: string;
+        label?: string;
+        description?: string;
+    }): FollowUpAction;
+};
+/** The agreed follow-ups with the button that books one. */
+export declare function pageFollowUps(list: readonly PageFollowUp[]): PageFollowUps;
+/**
+ * One FAQ entry (24 §7): its id, what it covers (the catalog in the prompt shows these two), and the
+ * answer (the AI fetches it with `get_faq`).
+ */
+export type PageFaqEntry = {
+    id: string;
+    description: string;
+    content: string;
+};
+/** At most this many FAQ entries in a conversation (24 §7.2): the catalog is in every prompt. */
+export declare const MAX_FAQ_ENTRIES = 100;
+/** What the page decides once, when the conversation starts (24 §4): who the AI is, and its FAQ. */
+export type PageStart = {
+    persona: string;
+    faq: PageFaqEntry[];
+};
+/** The scheduled contact this conversation carries out (an outbound call or message, 09 §3.5). */
+export type PageScheduledAction = {
+    id: string;
+    /** What the contact agreed to, in the exchange where they agreed; null for a routine follow-up. */
+    agreedInExchangeId: string | null;
+    /** The contact's own words agreeing to it; null for a routine follow-up. */
+    customerQuote: string | null;
+    note: string | null;
+    /** ISO time it was scheduled for. */
+    scheduledFor: string;
+};
+export type PageBaseContext = {
+    /** Read-only: a render never writes. */
+    db: ReadDb;
+    /** What the platform recorded in this conversation; empty outside one. */
+    runs: PageRuns;
+    /** Why this conversation happened when the platform started it (17b §9.2); null for an inbound one. */
+    scheduledAction: PageScheduledAction | null;
+    /** The sequence's office hours now; null when it has none. */
+    officeHours: {
+        open: boolean;
+        timezone: string;
+        today: Array<{
+            start: string;
+            end: string;
+        }>;
+    } | null;
+    /**
+     * The contact's agreed follow-ups still to come (09): calls and messages they asked for or agreed to,
+     * soonest first. Empty without a Case Orchestrator (nothing books them). `ctx.followUps.agree({ channels })`
+     * is the button that books one when the customer asks for it (25 §5).
+     */
+    followUps: PageFollowUps;
+    /** The business root's id. */
+    subject: string;
+    /** The contact of the conversation; null outside one. */
+    caller: PageRow | null;
+    /** This conversation's session row (the session fields, cells); null outside one. */
+    session: PageRow | null;
+    /** This conversation's platform facts; null outside one. */
+    conversation: PageConversation | null;
+    /** Counts over this instance. */
+    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: PageMessages;
+    /** Times for people (25 §11): the sandbox has no `Intl`, so formatting goes through the platform. */
+    time: PageTime;
+};
+/**
+ * `ctx.time` (25 §11): the contact's time zone and today there, `format` for a time as people read it,
+ * and `day` for the calendar day of a time. `zone` is the contact's `timezone`, else worked out from
+ * their postal code, state or phone.
+ */
+export type PageTime = {
+    /** The contact's time zone (America/New_York without a contact). */
+    zone: string;
+    /** Today, `YYYY-MM-DD`, in `zone`. */
+    today: string;
+    /** `at` as people read it, in `timeZone` (default `zone`): "Tue, Nov 3, 3:00 PM EST". */
+    format(at: string, options?: {
+        timeZone?: string;
+        style?: 'datetime' | 'date' | 'time';
+    }): Promise<string>;
+    /** The calendar day (`YYYY-MM-DD`) at `at` in `timeZone` (default `zone`), to compare days or key a rule by date. */
+    day(at: string | number, timeZone?: string): Promise<string>;
+};
+/**
+ * A text the customer sent since the last run (20 §5.2): what this run is for. `earlier`: sent before,
+ * in a run that failed, and not answered yet (20 §5.4).
+ */
+export type PageSmsMessage = {
+    id: string;
+    body: string;
+    at: string;
+    earlier?: boolean;
+};
+/** An email the customer sent since the last run (20 §5.2), quoted history and signature taken out. */
+export type PageEmailMessage = {
+    id: string;
+    from: string;
+    to: string[];
+    cc: string[];
+    subject: string | null;
+    body: string;
+    at: string;
+    /** Listed only (20 §7): their contents are not read yet. */
+    attachments: Array<{
+        name: string;
+        contentType?: string;
+    }>;
+    /** Sent before, in a run that failed, and not answered yet (20 §5.4). */
+    earlier?: boolean;
+};
+/**
+ * This person's previous call on this case (21 §5.2): the facts a page decides by whether to pick up where it
+ * left off (a line dropped a minute ago) or open as usual (a call a week ago, or one handed to a person). A
+ * new call never carries the previous one's conversation or session fields.
+ */
+export type PagePreviousCall = {
+    /** ISO time it ended. */
+    endedAt: string;
+    direction: Direction;
+    /** How the call went: connected, no_answer, busy, failed, fallback, apology. */
+    outcome: string | null;
+    /** How its conversation ended, when the AI took it: `hangup` (the line closed: the caller hung up, or it dropped), `end` (the AI ended it), `transfer`, `error`. */
+    endedBy: string | null;
+    /** Its last lines, oldest first. */
+    lastLines: Array<{
+        speaker: 'party' | 'ai';
+        text: string;
+    }>;
+};
+/**
+ * Who answered an outbound call (25 §13), as the voice service tells it: a person, a voicemail greeting,
+ * a call-screening assistant, a phone menu; `said`: what it said. The page decides what to do: leave a
+ * message (`ctx.call.voicemail`), tell the screener who calls and why (`announce`), press keys (`keypad`),
+ * end. A page that returns nothing for it leaves the voice service to do what it does on its own (hang
+ * up on a machine).
+ */
+export type PageFarEnd = {
+    kind: 'human' | 'voicemail' | 'screening' | 'ivr';
+    said: string;
+};
+/** What only a call can do (20 §5.2): on `ctx.call`, so a text's page cannot even write it. */
+export type PageCallCaps = {
+    transferTo: typeof transferTo;
+    keypad: typeof keypad;
+    announce: typeof announce;
+    voicemail: typeof voicemail;
+    /** This person's previous call on this case; null when there is none. */
+    previous: PagePreviousCall | null;
+    /** Who answered, once the voice service knows (25 §13); null until then, and on an inbound call. */
+    farEnd: PageFarEnd | null;
+};
+/** What each channel adds to the page function's context (20 §5.2). */
+export type PageChannelCaps = {
+    call: {
+        call: PageCallCaps;
+    };
+    sms: {
+        sms: {
+            inbound: PageSmsMessage[];
+        };
+    };
+    email: {
+        email: {
+            inbound: PageEmailMessage[];
+            mailbox: string;
+        };
+    };
+};
+/** The context of one channel's page function. */
+export type PageContextOf<C extends PageChannel> = PageBaseContext & {
+    channel: C;
+} & PageChannelCaps[C];
+/** Any channel's context: what a helper shared by several page functions takes (switch on `channel`). */
+export type PageContext = {
+    [C in PageChannel]: PageContextOf<C>;
+}[PageChannel];
+export type ActionContext = {
+    db: Db;
+    subject: string;
+    caller: PageRow | null;
+    /**
+     * On a call, this party's session for this case (25 §9), as `ctx.session` on the page; null by text and
+     * email. `db.session.update({ where: { id: session.id }, data })` writes it in the action's transaction.
+     */
+    session: PageRow | null;
+    now: string;
+};
+/**
+ * Page settings of a cell `field(...)` opens: `readOnly` to show it with these settings without opening
+ * it, and `expand` to show the AI its definition (type, allowed values, how to fill it; 24 §2.2), not
+ * shown when left out. How to fill a field on this page is the page's `$extraction`, one per field for
+ * the whole page (26 §15.3); `extraction` here is refused. `hint` was renamed and is refused;
+ * `required` was removed (24 §2.3).
+ */
+export type FieldOptions = {
+    readOnly?: boolean;
+    expand?: boolean;
+    extraction?: MovedOption<'$extraction'>;
+    hint?: MovedOption<'$extraction'>;
+    required?: RemovedOption;
+};
+/** A removed option: any value is a type error. */
+export type RemovedOption = never;
+/** A removed option: any value is a type error whose message names the new one. */
+export type RenamedOption<New extends string> = `renamed: use ${New}`;
+/** An option that moved to the page: any value is a type error whose message names where it went. */
+export type MovedOption<Where extends string> = `moved: use the page's ${Where}`;
+export type FieldCell<S = Slot> = {
+    $field: true;
+    slot: S;
+    readOnly?: boolean;
+    expand?: boolean;
+};
+/** A row a ref field may point at, and what the AI sees of it (26 §16.2 #7). */
+export type RefOption = {
+    id: string;
+    label: string;
+};
+export type RefFieldOptions = {
+    /**
+     * The rows it may point at, with their labels: `[{ id, label }]`, or `choose(rows, label)`. Read-only:
+     * only to label the current value (put the current row in it). None: only the row's name is shown.
+     */
+    options?: readonly RefOption[] | ChooseParam;
+    readOnly?: boolean;
+};
+/** A ref field on the page (26 §16.2 #7): its candidates given by the page, each with its label. */
+export type RefFieldCell<S = Slot> = {
+    $refField: true;
+    slot: S;
+    options: RefOption[];
+    readOnly?: boolean;
+};
+/**
+ * A parameter taken from the schema (`schemaField('providers.name')`): the platform fills in its type,
+ * allowed values, label and `extraction` (the page's `extraction` replaces the schema's). `table.id`,
+ * or a lookup field, chooses a row on the page.
+ */
+export type SchemaFieldParam = {
+    $schemaField: string;
+    extraction?: string;
+};
+/** `schemaField()` options. `description` was renamed `extraction` and is refused. */
+export type SchemaFieldOptions = {
+    extraction?: string;
+    description?: RenamedOption<'extraction'>;
+};
+/** One parameter of an action: a schema field, or plain JSON Schema (function call `parameters`). */
+export type ActionParam = SchemaFieldParam | {
+    type: 'string' | 'number' | 'integer' | 'boolean';
+    description?: string;
+    enum?: Array<string | number>;
+} | {
+    type: 'array';
+    items: ActionParam;
+    description?: string;
+} | {
+    type: 'object';
+    properties: Record<string, ActionParam>;
+    required?: string[];
+    description?: string;
+};
+/** An action's `parameters`, as an LLM function call declares them. */
+export type ActionParameters = {
+    type: 'object';
+    properties: Record<string, ActionParam>;
+    required?: string[];
+};
+export type CreateRowAction = {
+    $action: 'createRow';
+    table: string;
+    label?: string;
+    description?: string;
+    fields: string[];
+    required: string[];
+    /** Preset values (the parent, `status: 'active'`): kept on the server, never shown to the AI. */
+    prefill: Record<string, unknown>;
+};
+export type DeleteRowAction = {
+    $action: 'deleteRow';
+    rowId: string;
+    label?: string;
+    description?: string;
+    reason?: string;
+};
+export type CustomAction = {
+    $action: 'custom';
+    name: string;
+    description: string;
+    parameters: ActionParameters;
+    /** Parameters filled where the page placed the action: kept on the server, never shown to the AI. */
+    prefill: Record<string, unknown>;
+};
+/**
+ * A company function (`functions/`, `defineCaseFunc`) as a button, or returned by the page function to
+ * run now (20 §6.2). It runs on the Worker, outside the page's transaction, and is waited for; on a call,
+ * `say` is said first and the customer cannot interrupt until it is done (20 §6.3).
+ */
+export type FunctionAction = {
+    $action: 'function';
+    name: string;
+    label?: string;
+    description?: string;
+    /** Said first, verbatim, on a call only (ignored elsewhere): the customer only listens meanwhile. */
+    say?: string;
+    /** What the AI fills: plain JSON Schema or schema fields, as a custom action's. */
+    parameters?: ActionParameters;
+    /** Parameters the page fills (a row's id) or offers rows for (`choose(...)`, 25 §10); kept on the server. */
+    prefill?: Record<string, unknown>;
+};
+/**
+ * The rows a row parameter may be chosen among (25 §10), with what the AI sees of each:
+ * `cancel({ appointment: choose(appointments, (a) => `${a.date.value} with ${a.provider.value}`) })`. The
+ * candidates are these rows, wherever else the page shows them (or not); none: the button is left off.
+ */
+export type ChooseParam = {
+    $choose: true;
+    table: string | null;
+    options: Array<{
+        id: string;
+        label: string;
+    }>;
+};
+export declare function choose<R extends PageRow>(rows: readonly R[], label: (row: R) => string): ChooseParam;
+export declare function isChoose(value: unknown): value is ChooseParam;
+/**
+ * A text or an email sent now (25 §8), on the platform's own way out: from this call's number (a text)
+ * or the contact's mailbox (an email), opt-outs checked, recorded on the case and this run. What the page
+ * leaves out the AI writes: `body`, and an email's `subject`.
+ */
+export type MessageAction = {
+    $action: 'message';
+    channel: 'sms' | 'email';
+    /** The run key: `lastActionRun(ctx.runs, key)` says whether it went. */
+    key: string;
+    /** The contact it goes to (a contact row the page read); absent: the contact of this conversation. */
+    to?: string;
+    /** The text, word for word; absent: the AI writes it. */
+    body?: string;
+    /** An email's subject; absent: the AI writes it. */
+    subject?: string;
+    /** On a call, said once it went (`'I just texted you the link.'`); ignored elsewhere. */
+    say?: string;
+    label?: string;
+    description?: string;
+};
+export type MessageOptions = {
+    to?: PageRow | string;
+    body?: string;
+    say?: string;
+    label?: string;
+    description?: string;
+};
+/** `ctx.messages` (25 §8): a text or an email to send now, as a button or returned to run at once. */
+export type PageMessages = {
+    text(key: string, options?: MessageOptions): MessageAction;
+    email(key: string, options?: MessageOptions & {
+        subject?: string;
+    }): MessageAction;
+};
+export declare const messages: PageMessages;
+export type PageAction = CreateRowAction | DeleteRowAction | CustomAction | ChannelAction | FunctionAction | MessageAction | FollowUpAction;
+/** Hand the call to a person. */
+export type TransferAction = {
+    $action: 'channel';
+    channel: 'transfer';
+    /** E.164 number to dial, or a SIP URI (`sip:desk@pbx.example.com`, headers after `?`). */
+    to: string;
+    /** A SIP `to` that asks for credentials: kept on the server, never on the page the AI reads. */
+    sipAuth?: {
+        username: string;
+        password: string;
+    };
+    /**
+     * The caller ID the person sees: the customer's number or ours (default: the voice service's own rule).
+     * A call that came in by SIP shows ours to a phone number whatever is asked (the carrier refuses it).
+     */
+    callerId?: 'customer' | 'service';
+    /**
+     * cold: connect and leave; warm: brief the person first with `briefing`, the customer on hold meanwhile;
+     * background: warm, but the AI keeps talking with the customer while the person is called, and the
+     * customer is put through once the person takes it. Nobody takes it: the conversation simply goes on.
+     */
+    mode: 'cold' | 'warm' | 'background';
+    briefing?: string;
+    /**
+     * Background only: what is said as the two are put through. `person`: to the person, once they take
+     * the call (`{{briefing}}` is the briefing; without it, the briefing). `customer`: to the customer, in
+     * their language (without it, a chime only).
+     */
+    bridge?: {
+        person?: string;
+        customer?: string;
+    };
+    label?: string;
+    description?: string;
+};
+/** Collect keypresses on a call: what was pressed is written to `write` (through `map` when given). */
+export type KeypadAction = {
+    $action: 'channel';
+    channel: 'keypad';
+    /** The run key: `tried(ctx.runs, key)` after the first try. */
+    key: string;
+    /** Said once, verbatim, before waiting for a key. */
+    say: string;
+    /** The keys that count. */
+    digits: string[];
+    timeoutMs: number;
+    /** Where the key goes: a slot read from db. */
+    write?: SlotRef;
+    /** Pressed key → value written (`{ '1': 'english', '2': 'spanish' }`); without it the key itself. */
+    map?: Record<string, string | number | boolean>;
+    label?: string;
+    description?: string;
+};
+/** Say a fixed text, verbatim and not interruptible (a compliance statement). */
+export type AnnounceAction = {
+    $action: 'channel';
+    channel: 'announce';
+    key: string;
+    text: string;
+};
+/** End the conversation (a call hangs up once the last line has played; an SMS conversation closes). */
+export type EndAction = {
+    $action: 'channel';
+    channel: 'end';
+    label?: string;
+    description?: string;
+};
+/**
+ * Leave a message on the voicemail (25 §13): after its beep, word for word (what a regulated business may
+ * leave is fixed), then hang up. The call's outcome is `voicemail`.
+ */
+export type VoicemailAction = {
+    $action: 'channel';
+    channel: 'voicemail';
+    text: string;
+    label?: string;
+    description?: string;
+};
+export type ChannelAction = TransferAction | KeypadAction | AnnounceAction | EndAction | VoicemailAction;
+export declare function transferTo(options: {
+    to: string;
+    sipAuth?: TransferAction['sipAuth'];
+    callerId?: TransferAction['callerId'];
+    mode?: TransferAction['mode'];
+    briefing?: string;
+    bridge?: TransferAction['bridge'];
+    label?: string;
+    description?: string;
+}): TransferAction;
+/** Whether a transfer's `to` is a SIP URI rather than a phone number. */
+export declare function isSipUri(to: string): boolean;
+export declare function keypad(key: string, options: {
+    say: string;
+    digits: string[];
+    timeoutMs?: number;
+    write?: Slot | SlotRef;
+    map?: Record<string, string | number | boolean>;
+    label?: string;
+    description?: string;
+}): KeypadAction;
+/** A company function as a button (20 §6.2): `runFunction('importOrders', { label, say, parameters })`. */
+export declare function runFunction(name: string, options?: {
+    label?: string;
+    description?: string;
+    say?: string;
+    parameters?: ActionParameters;
+    prefill?: Record<string, unknown>;
+}): FunctionAction;
+export declare function announce(key: string, text: string): AnnounceAction;
+export declare function voicemail(text: string, options?: {
+    label?: string;
+    description?: string;
+}): VoicemailAction;
+export declare function end(options?: {
+    label?: string;
+    description?: string;
+}): EndAction;
+/**
+ * An action the page function returns to run now, with its run key (default: the action's name, a
+ * channel action's key or kind) and whether the conversation waits for it (`wait: false`: run in the
+ * background, the conversation goes on; not for channel actions).
+ */
+export type PerformAction = {
+    $perform: true;
+    action: PageAction;
+    key?: string;
+    wait?: boolean;
+};
+export declare function perform(action: PageAction | {
+    toJSON(): PageAction;
+}, options?: {
+    key?: string;
+    wait?: boolean;
+}): PerformAction;
+/** Every channel a page may be written for, in order. */
+export declare const PAGE_CHANNELS: readonly PageChannel[];
+/** A page function: the page for one channel, or an action to run now (17b §9.1, §9.8). */
+export type PageFunction<D> = (ctx: PageContext) => D | Promise<D>;
+/**
+ * Who the employee is and how they talk on this conversation's channel (`ctx.channel`), and the FAQ the
+ * AI may look things up in (24 §4). Called once, when the conversation starts, with the page's context
+ * at that moment; what they return holds for the whole conversation (the head of every prompt).
+ */
+export type PagePersona = (ctx: PageContext) => string | Promise<string>;
+export type PageFaq = (ctx: PageContext) => PageFaqEntry[] | Promise<PageFaqEntry[]>;
+export type PageDefinition<D> = {
+    persona: PagePersona;
+    faq?: PageFaq;
+    call?: (ctx: PageContextOf<'call'>) => D | Promise<D>;
+    sms?: (ctx: PageContextOf<'sms'>) => D | Promise<D>;
+    email?: (ctx: PageContextOf<'email'>) => D | Promise<D>;
+};
+export type DefinedPage<D> = {
+    kind: 'page';
+    persona: PagePersona;
+    faq: PageFaq | null;
+    channels: Partial<Record<PageChannel, PageFunction<D>>>;
+};
+/**
+ * `context.page.ts` (17b §9.1, 24 §4): `definePage({ persona: (ctx) => '…', faq: (ctx) => [...], call:
+ * async (ctx) => page, sms: … })`. One page function per channel; what they share is the company code's
+ * own business.
+ */
+export declare function definePage<D>(definition: PageDefinition<D>): DefinedPage<D>;
+/**
+ * What `persona` and `faq` returned, checked (24 §4): a persona's text; at most `MAX_FAQ_ENTRIES` FAQ
+ * entries, each with an id of its own, a description and an answer. Throws what is wrong.
+ */
+export declare function checkPageStart(raw: unknown): PageStart;
+/**
+ * A cell the AI may write (19-page-writable-cells): a slot placed on a page as is is read-only;
+ * `field(slot)` opens it, unless `readOnly: true`. The row id and the parent never open; a lookup
+ * chooses among its table's rows on the page.
+ */
+/**
+ * A ref field (a lookup) on the page (26 §16.2 #7): the rows the AI may set it to, each with its label
+ * (`options: [{ id, label }]`, or `choose(rows, label)`); read-only, `options` only labels the current
+ * value. Its definition is always on the page. `field()` refuses a ref field.
+ */
+export declare function refField<S extends Slot>(slot: S, options?: RefFieldOptions): RefFieldCell<S>;
+export declare function field<S extends Slot>(slot: S, options?: FieldOptions): FieldCell<S>;
+/** A parameter taken from the schema: `schemaField('providers.name')`, `schemaField('injuries.id')` (a row). */
+export declare function schemaField(path: string, options?: SchemaFieldOptions): SchemaFieldParam;
+/**
+ * An action placed on a page: call it to prefill parameters (`addProvider({ injury: i.id })`), or place
+ * it as it is (nothing prefilled). It crosses out of the sandbox as its JSON (`toJSON`).
+ */
+export type Placeable<A extends PageAction, P> = ((prefill?: P) => A) & {
+    toJSON(): A;
+};
+/** Add a row (15 §10.6): `fields` are what the AI fills; call it to preset the rest (`({ status: 'active' })`). */
+export declare function createRow(table: TableReader | string, options: {
+    fields: readonly string[];
+    required?: readonly string[];
+    label?: string;
+    description?: string;
+}): Placeable<CreateRowAction, Record<string, unknown>>;
+/** Delete a row (cascading, 15 §10.6.1): a built-in action with the row prefilled and nothing to fill. */
+export declare function deleteRow(row: PageRow | string, options?: {
+    reason?: string;
+    label?: string;
+    description?: string;
+}): DeleteRowAction;
+type ActionRun<A> = (args: A, ctx: ActionContext) => unknown;
+export type DefinedAction<A> = Placeable<CustomAction, {
+    [K in keyof A]?: A[K] | ChooseParam;
+}> & {
+    readonly actionName: string;
+    readonly run: ActionRun<A>;
+};
+/**
+ * A custom action, declared like an LLM function call: `parameters` are everything `run` takes. Where
+ * the page places it, some parameters may be prefilled; the AI fills the rest.
+ */
+export declare function defineAction<A = Record<string, unknown>>(definition: {
+    name: string;
+    description: string;
+    parameters?: ActionParameters;
+    run: ActionRun<A>;
+}): DefinedAction<A>;
+export type PageEntryArg = {
+    /** `start`: `persona` and `faq` once, when the conversation starts (24 §4), with the same context. */
+    mode: 'render' | 'start';
+    /** The page function to run; outside a conversation, the first one the page defines. */
+    channel: PageChannel | null;
+    subject: string;
+    caller: PageRow | null;
+    session: PageRow | null;
+    conversation: PageConversation | null;
+    runs: PageRuns;
+    scheduledAction: PageScheduledAction | null;
+    officeHours: PageContext['officeHours'];
+    followUps: PageFollowUp[];
+    now: string;
+    /** The contact's time zone and today there (25 §11). */
+    time?: {
+        zone: string;
+        today: string;
+    };
+    /** What the customer sent since the last run (20 §5.2): a text run's texts, an email run's emails. */
+    sms?: {
+        inbound: PageSmsMessage[];
+    };
+    email?: {
+        inbound: PageEmailMessage[];
+        mailbox: string;
+    };
+    call?: {
+        previous: PagePreviousCall | null;
+        farEnd?: PageFarEnd | null;
+    };
+}
+/** The channels with a page function: read once, when the sequence is compiled. */
+ | {
+    mode: 'channels';
+} | {
+    mode: 'action';
+    name: string;
+    /** The prefilled parameters and the AI's, merged. */
+    args: Record<string, unknown>;
+    subject: string;
+    caller: PageRow | null;
+    session: PageRow | null;
+    now: string;
+};
+/** No runs yet. */
+export declare function emptyRuns(): PageRuns;
+/** What the compiled page script evaluates to: renders the page, or runs one of its actions. */
+export declare function pageEntry(mod: Record<string, unknown>): (arg: PageEntryArg) => unknown;
+export {};
+//# sourceMappingURL=define.d.ts.map