@superpanel-sdk/runtime 0.2.3 → 0.5.0

package/dist/core/page/define.js

@@ -0,0 +1,477 @@
+/**
+ * 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`).
+ */
+function runsOf(runs, key, scope) {
+    return (scope === 'case' ? runs?.caseActions : runs?.actions)?.[key];
+}
+/** Whether the action `key` ran at least once (whatever its result), in this run or (`'case'`) on the case. */
+export function tried(runs, key, scope = 'run') {
+    return (runsOf(runs, key, scope)?.length ?? 0) > 0;
+}
+/** The latest run of the action `key`, in this run or (`'case'`) on the case, if any. */
+export function lastActionRun(runs, key, scope = 'run') {
+    return runsOf(runs, key, scope)?.at(-1) ?? null;
+}
+function agree(options) {
+    const channels = [...new Set(options?.channels ?? [])];
+    if (!channels.length || channels.some((c) => c !== 'call' && c !== 'sms' && c !== 'email')) {
+        throw new Error("followUps.agree({ channels }): name at least one of 'call', 'sms', 'email'");
+    }
+    const action = { $action: 'followUp', key: options.key ?? 'followUp', channels };
+    if (options.label !== undefined)
+        action.label = options.label;
+    if (options.description !== undefined)
+        action.description = options.description;
+    return action;
+}
+/** The agreed follow-ups with the button that books one. */
+export function pageFollowUps(list) {
+    return Object.assign([...list], { agree });
+}
+/** At most this many FAQ entries in a conversation (24 §7.2): the catalog is in every prompt. */
+export const MAX_FAQ_ENTRIES = 100;
+export function choose(rows, label) {
+    if (!Array.isArray(rows))
+        throw new Error('choose(rows, label): rows must be a list of rows read from db');
+    let table = null;
+    const options = rows.map((row) => {
+        if (!isRow(row))
+            throw new Error('choose(rows, label): each row must be a row read from db');
+        const ref = Object.values(row).find(isSlot)?.ref;
+        if (ref) {
+            if (table !== null && table !== ref.table)
+                throw new Error(`choose(): rows of ${table} and ${ref.table} together`);
+            table = ref.table;
+        }
+        return { id: row.id, label: String(label(row)) };
+    });
+    return { $choose: true, table, options };
+}
+export function isChoose(value) {
+    return typeof value === 'object' && value !== null && value.$choose === true && Array.isArray(value.options);
+}
+function message(channel, key, options) {
+    if (!key || typeof key !== 'string')
+        throw new Error(`messages.${channel === 'sms' ? 'text' : 'email'}(): name it with a key`);
+    const action = { $action: 'message', channel, key };
+    if (options.to !== undefined) {
+        const to = typeof options.to === 'string' ? options.to : isRow(options.to) ? options.to.id : null;
+        if (!to)
+            throw new Error(`messages: ${key}: \`to\` must be a contact row read from db, or its id`);
+        action.to = to;
+    }
+    for (const name of ['body', 'subject', 'say', 'label', 'description']) {
+        const value = options[name];
+        if (value !== undefined)
+            action[name] = value;
+    }
+    return action;
+}
+export const messages = {
+    text: (key, options = {}) => message('sms', key, options),
+    email: (key, options = {}) => message('email', key, options),
+};
+export function transferTo(options) {
+    const mode = options.mode ?? 'cold';
+    if (options.bridge !== undefined && mode !== 'background')
+        throw new Error(`transferTo: bridge is for a background transfer (mode '${mode}')`);
+    const action = { $action: 'channel', channel: 'transfer', to: options.to, mode };
+    if (options.sipAuth !== undefined && !isSipUri(options.to))
+        throw new Error(`transferTo: sipAuth is for a SIP URI, not ${options.to}`);
+    if (options.sipAuth !== undefined)
+        action.sipAuth = { ...options.sipAuth };
+    if (options.callerId !== undefined)
+        action.callerId = options.callerId;
+    if (options.briefing !== undefined)
+        action.briefing = options.briefing;
+    if (options.bridge !== undefined)
+        action.bridge = { ...options.bridge };
+    if (options.label !== undefined)
+        action.label = options.label;
+    if (options.description !== undefined)
+        action.description = options.description;
+    return action;
+}
+/** Whether a transfer's `to` is a SIP URI rather than a phone number. */
+export function isSipUri(to) {
+    return /^sips?:/i.test(to.trim());
+}
+export function keypad(key, options) {
+    if (!options.digits.length)
+        throw new Error(`keypad('${key}'): digits must name at least one key`);
+    const action = { $action: 'channel', channel: 'keypad', key, say: options.say, digits: [...options.digits], timeoutMs: options.timeoutMs ?? 8000 };
+    if (options.write !== undefined)
+        action.write = isSlot(options.write) ? { ...options.write.ref } : { ...options.write };
+    if (options.map !== undefined)
+        action.map = { ...options.map };
+    if (options.label !== undefined)
+        action.label = options.label;
+    if (options.description !== undefined)
+        action.description = options.description;
+    return action;
+}
+/** A company function as a button (20 §6.2): `runFunction('importOrders', { label, say, parameters })`. */
+export function runFunction(name, options = {}) {
+    if (!name || typeof name !== 'string')
+        throw new Error('runFunction(): name the function (one of functions/)');
+    const action = { $action: 'function', name };
+    if (options.label !== undefined)
+        action.label = options.label;
+    if (options.description !== undefined)
+        action.description = options.description;
+    if (options.say !== undefined)
+        action.say = options.say;
+    if (options.parameters !== undefined)
+        action.parameters = options.parameters;
+    if (options.prefill !== undefined) {
+        for (const key of Object.keys(options.prefill)) {
+            if (!(key in (options.parameters?.properties ?? {})))
+                throw new Error(`runFunction('${name}'): ${key} is not one of its parameters`);
+        }
+        action.prefill = toPrefill(options.prefill);
+    }
+    return action;
+}
+export function announce(key, text) {
+    return { $action: 'channel', channel: 'announce', key, text };
+}
+export function voicemail(text, options = {}) {
+    if (typeof text !== 'string' || !text.trim())
+        throw new Error('voicemail(text): the message to leave');
+    const action = { $action: 'channel', channel: 'voicemail', text };
+    if (options.label !== undefined)
+        action.label = options.label;
+    if (options.description !== undefined)
+        action.description = options.description;
+    return action;
+}
+export function end(options = {}) {
+    const action = { $action: 'channel', channel: 'end' };
+    if (options.label !== undefined)
+        action.label = options.label;
+    if (options.description !== undefined)
+        action.description = options.description;
+    return action;
+}
+export function perform(action, options = {}) {
+    const plain = typeof action.toJSON === 'function' && !('$action' in action) ? action.toJSON() : action;
+    if (plain.$action === 'channel' && options.wait === false)
+        throw new Error('perform(): a channel action cannot run in the background');
+    const out = { $perform: true, action: plain };
+    if (options.key !== undefined)
+        out.key = options.key;
+    if (options.wait !== undefined)
+        out.wait = options.wait;
+    return out;
+}
+// ---------------------------------------------------------------------------------------------
+function isSlot(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'ref' in value &&
+        'state' in value &&
+        typeof value.ref === 'object' &&
+        value.ref !== null);
+}
+function isRow(value) {
+    return typeof value === 'object' && value !== null && typeof value.id === 'string';
+}
+/** Every channel a page may be written for, in order. */
+export const PAGE_CHANNELS = ['call', 'sms', 'email'];
+/**
+ * `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 function definePage(definition) {
+    if (!definition || typeof definition !== 'object' || typeof definition === 'function') {
+        throw new Error('definePage({ persona, faq, call, sms, email }): one page function per channel');
+    }
+    const channels = {};
+    for (const channel of PAGE_CHANNELS) {
+        const fn = definition[channel];
+        if (fn === undefined)
+            continue;
+        if (typeof fn !== 'function')
+            throw new Error(`definePage(): ${channel} must be a page function`);
+        channels[channel] = fn;
+    }
+    if (Object.keys(channels).length === 0)
+        throw new Error('definePage(): no page function (call, sms, email)');
+    if (typeof definition.persona !== 'function') {
+        throw new Error('definePage(): persona must be a function, called once when the conversation starts: persona: (ctx) => \'You are …\' (24 §4)');
+    }
+    if (definition.faq !== undefined && typeof definition.faq !== 'function') {
+        throw new Error('definePage(): faq must be a function, called once when the conversation starts: faq: (ctx) => [{ id, description, content }] (24 §4)');
+    }
+    return { kind: 'page', persona: definition.persona, faq: definition.faq ?? null, channels };
+}
+/**
+ * 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 function checkPageStart(raw) {
+    const value = raw;
+    if (typeof value?.persona !== 'string' || !value.persona.trim())
+        throw new Error('persona(ctx) must return the persona\'s text');
+    const faq = value.faq ?? [];
+    if (!Array.isArray(faq))
+        throw new Error('faq(ctx) must return a list of { id, description, content }');
+    if (faq.length > MAX_FAQ_ENTRIES)
+        throw new Error(`faq(ctx) returned ${faq.length} entries; at most ${MAX_FAQ_ENTRIES} (24 §7.2)`);
+    const seen = new Set();
+    const entries = faq.map((entry, i) => {
+        const e = entry;
+        for (const key of ['id', 'description', 'content']) {
+            if (typeof e?.[key] !== 'string' || !e[key].trim())
+                throw new Error(`faq(ctx)[${i}]: ${key} must be text`);
+        }
+        if (seen.has(e.id))
+            throw new Error(`faq(ctx): the id ${e.id} is used twice`);
+        seen.add(e.id);
+        return { id: e.id, description: e.description, content: e.content };
+    });
+    return { persona: value.persona, faq: entries };
+}
+/**
+ * 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 function refField(slot, options = {}) {
+    if (!isSlot(slot))
+        throw new Error('refField(): the first argument must be a slot read from db');
+    const given = options.options ?? [];
+    const list = isChoose(given) ? given.options : given;
+    if (!Array.isArray(list))
+        throw new Error('refField(): options must be a list of { id, label } or choose(rows, label)');
+    const cell = {
+        $refField: true,
+        slot,
+        options: list.map((option) => {
+            if (!option || typeof option.id !== 'string')
+                throw new Error('refField(): each option is { id, label }, id a row id');
+            return { id: option.id, label: String(option.label) };
+        }),
+    };
+    if (options.readOnly !== undefined)
+        cell.readOnly = options.readOnly;
+    return cell;
+}
+export function field(slot, options = {}) {
+    if (!isSlot(slot))
+        throw new Error('field(): the first argument must be a slot read from db');
+    if (options.hint !== undefined || options.extraction !== undefined) {
+        throw new Error("field(): how to fill a field is the page's: write it in $extraction on the page's root, by table.field (26 §15.3)");
+    }
+    const cell = { $field: true, slot };
+    if (options.readOnly !== undefined)
+        cell.readOnly = options.readOnly;
+    if (options.required !== undefined)
+        throw new Error('field(): `required` was removed (24 §2.3): say what is still needed in $guide');
+    if (options.expand !== undefined)
+        cell.expand = options.expand;
+    return cell;
+}
+/** A parameter taken from the schema: `schemaField('providers.name')`, `schemaField('injuries.id')` (a row). */
+export function schemaField(path, options = {}) {
+    if (options.description !== undefined)
+        throw new Error(`schemaField('${path}'): \`description\` was renamed \`extraction\``);
+    const param = { $schemaField: path };
+    if (options.extraction !== undefined)
+        param.extraction = options.extraction;
+    return param;
+}
+function placeable(make) {
+    const place = ((prefill) => make(toPrefill((prefill ?? {}))));
+    place.toJSON = () => make({});
+    return place;
+}
+const CREATE_ROW_OPTIONS = new Set(['fields', 'required', 'label', 'description']);
+/** Add a row (15 §10.6): `fields` are what the AI fills; call it to preset the rest (`({ status: 'active' })`). */
+export function createRow(table, options) {
+    const tableName = typeof table === 'string' ? table : table.$table;
+    // An option it does not know (a `prefill` here, say) would otherwise be dropped: preset values are
+    // given by calling it, `createRow(…)({ parent: row.id })` (26 §16.2 #5d).
+    const unknown = Object.keys(options).filter((key) => !CREATE_ROW_OPTIONS.has(key));
+    if (unknown.length) {
+        throw new Error(`createRow('${tableName}'): unknown option ${unknown.join(', ')} (it takes ${[...CREATE_ROW_OPTIONS].join(', ')}); preset values by calling it: createRow('${tableName}', { … })({ field: value })`);
+    }
+    return placeable((prefill) => {
+        const action = {
+            $action: 'createRow',
+            table: tableName,
+            fields: [...options.fields],
+            required: [...(options.required ?? [])],
+            prefill,
+        };
+        if (options.label !== undefined)
+            action.label = options.label;
+        if (options.description !== undefined)
+            action.description = options.description;
+        return action;
+    });
+}
+/** Delete a row (cascading, 15 §10.6.1): a built-in action with the row prefilled and nothing to fill. */
+export function deleteRow(row, options = {}) {
+    const rowId = typeof row === 'string' ? row : isRow(row) ? row.id : null;
+    if (!rowId)
+        throw new Error('deleteRow(): the first argument must be a row read from db, or its id');
+    const action = { $action: 'deleteRow', rowId };
+    if (options.reason !== undefined)
+        action.reason = options.reason;
+    if (options.label !== undefined)
+        action.label = options.label;
+    if (options.description !== undefined)
+        action.description = options.description;
+    return action;
+}
+const ACTIONS = new Map();
+/**
+ * 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 function defineAction(definition) {
+    if (ACTIONS.has(definition.name))
+        throw new Error(`defineAction(): two actions are named ${definition.name}`);
+    ACTIONS.set(definition.name, { run: definition.run });
+    const parameters = definition.parameters ?? { type: 'object', properties: {} };
+    const place = placeable((prefill) => {
+        for (const key of Object.keys(prefill)) {
+            if (!(key in parameters.properties))
+                throw new Error(`${definition.name}: ${key} is not one of its parameters`);
+        }
+        return { $action: 'custom', name: definition.name, description: definition.description, parameters, prefill };
+    });
+    return Object.assign(place, { actionName: definition.name, run: definition.run });
+}
+/** Prefilled values as given (ids and plain JSON, as `parameters` types them), without the unset ones. */
+function toPrefill(prefill) {
+    const out = {};
+    for (const [key, value] of Object.entries(prefill)) {
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+function host() {
+    const call = globalThis.__host;
+    if (!call)
+        throw new Error('the page module runs inside the page sandbox only');
+    return call;
+}
+function dbProxy(mode) {
+    const call = host();
+    return new Proxy({}, {
+        get(_, table) {
+            if (typeof table !== 'string')
+                return undefined;
+            const read = (method) => (args) => call('records', [table, method, args ?? {}]);
+            const reads = {
+                $table: table,
+                findUnique: read('findUnique'),
+                findFirst: read('findFirst'),
+                findMany: read('findMany'),
+                count: read('count'),
+            };
+            if (mode === 'read')
+                return reads;
+            const write = (method) => (args) => call('write', [table, method, args ?? {}]);
+            return { ...reads, create: write('create'), update: write('update'), upsert: write('upsert'), delete: write('delete') };
+        },
+    });
+}
+/** `ctx.time` inside the sandbox: `format` and `day` are host calls (the sandbox has no `Intl`). */
+function timeOf(at) {
+    const call = host();
+    return {
+        zone: at.zone,
+        today: at.today,
+        format: (when, options = {}) => call('time', [when, { timeZone: options.timeZone ?? at.zone, ...(options.style ? { style: options.style } : {}) }]),
+        day: (when, timeZone) => call('day', [when, timeZone ?? at.zone]),
+    };
+}
+/** `history` inside the sandbox: each count is a `history` host call. */
+function historyProxy() {
+    const call = host();
+    return {
+        sessionCount: (where) => call('history', ['sessionCount', where ?? {}]),
+        exchangeCount: (where) => call('history', ['exchangeCount', where ?? {}]),
+        timeline: (where) => call('history', ['timeline', where ?? {}]),
+    };
+}
+/** No runs yet. */
+export function emptyRuns() {
+    return { actions: {}, caseActions: {} };
+}
+/** What the compiled page script evaluates to: renders the page, or runs one of its actions. */
+export function pageEntry(mod) {
+    const exported = (mod.default ?? mod.page);
+    return (arg) => {
+        if (arg.mode === 'channels') {
+            if (exported?.kind !== 'page')
+                throw new Error('context.page.ts must default-export definePage({ persona, faq, call, sms, email })');
+            return { channels: Object.keys(exported.channels ?? {}) };
+        }
+        if (arg.mode === 'render' || arg.mode === 'start') {
+            const channels = exported?.kind === 'page' ? (exported.channels ?? {}) : null;
+            if (!channels)
+                throw new Error('context.page.ts must default-export definePage({ persona, faq, call, sms, email })');
+            const channel = arg.channel ?? Object.keys(channels)[0] ?? null;
+            const main = channel ? channels[channel] : undefined;
+            if (!channel || typeof main !== 'function')
+                throw new Error(`context.page.ts has no page function for ${arg.channel ?? 'any channel'}`);
+            const caps = channel === 'call'
+                ? { call: { transferTo, keypad, announce, voicemail, previous: arg.call?.previous ?? null, farEnd: arg.call?.farEnd ?? null } }
+                : channel === 'sms'
+                    ? { sms: { inbound: arg.sms?.inbound ?? [] } }
+                    : { email: { inbound: arg.email?.inbound ?? [], mailbox: arg.email?.mailbox ?? '' } };
+            const base = {
+                db: dbProxy('read'),
+                runs: arg.runs ?? emptyRuns(),
+                scheduledAction: arg.scheduledAction ?? null,
+                officeHours: arg.officeHours ?? null,
+                followUps: pageFollowUps(arg.followUps ?? []),
+                subject: arg.subject,
+                caller: arg.caller,
+                session: arg.session,
+                conversation: arg.conversation,
+                history: historyProxy(),
+                now: arg.now,
+                messages,
+                time: timeOf(arg.time ?? { zone: 'America/New_York', today: arg.now.slice(0, 10) }),
+            };
+            const ctx = { ...base, ...caps, channel };
+            if (arg.mode === 'start') {
+                const page = exported;
+                return Promise.all([page.persona(ctx), page.faq ? page.faq(ctx) : []]).then(([persona, faq]) => ({ persona, faq }));
+            }
+            return main(ctx);
+        }
+        if (arg.mode !== 'action')
+            throw new Error(`unknown page mode ${String(arg.mode)}`);
+        const action = ACTIONS.get(arg.name);
+        if (!action)
+            throw new Error(`no action named ${arg.name}`);
+        return action.run(arg.args, {
+            db: dbProxy('readWrite'),
+            subject: arg.subject,
+            caller: arg.caller,
+            session: arg.session ?? null,
+            now: arg.now,
+        });
+    };
+}
+//# sourceMappingURL=define.js.map

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

@@ -0,0 +1,58 @@
+import type { SlotState } from './define.js';
+import type { RenderedAction, RenderedCell, RenderedPage } from './render.js';
+import type { RowNames } from './render.js';
+/** `add` / `remove`: options added to or taken from a `multi_select`'s value, the rest kept (27 §3.3). */
+export type SlotOp = {
+    slot: string;
+    value?: unknown;
+    add?: unknown;
+    remove?: unknown;
+    state?: SlotState;
+    reason?: string;
+};
+export type ActionOp = {
+    action: string;
+    arguments?: Record<string, unknown>;
+};
+export type OpenOp = {
+    open: string;
+    why?: string;
+};
+export type PageOp = SlotOp | ActionOp | OpenOp;
+export type PageOpsAllowed = {
+    /** Slot ids the AI may change (the page's writable cells). */
+    slots: readonly string[];
+    /** Action ids the AI may press. */
+    actions: readonly string[];
+    /** Block paths the AI may open; empty: no `open`. */
+    open: readonly string[];
+};
+export type ResolvedSlotOp = {
+    kind: 'slot';
+    cell: RenderedCell;
+    value: unknown;
+    /** `empty`: cleared (the customer took it back). */
+    state: SlotState;
+    reason: string | null;
+};
+/** `args`: what the AI filled, rows as ids; the page's prefilled arguments are added when it runs. */
+export type ResolvedActionOp = {
+    kind: 'action';
+    action: RenderedAction;
+    args: Record<string, unknown>;
+};
+export type ResolvedOpenOp = {
+    kind: 'open';
+    path: string;
+    why: string;
+};
+export type ResolvedOp = ResolvedSlotOp | ResolvedActionOp | ResolvedOpenOp;
+export type DroppedOp = {
+    op: unknown;
+    why: string;
+};
+export declare function resolvePageOps(page: RenderedPage, names: RowNames, answer: unknown, allowed: PageOpsAllowed): {
+    ops: ResolvedOp[];
+    dropped: DroppedOp[];
+};
+//# sourceMappingURL=ops.d.ts.map