@superpanel-sdk/runtime 0.5.0 → 0.7.0

package/dist/testing.d.ts

@@ -0,0 +1,368 @@
+import { type SequenceBuild } from './builder/types.js';
+import { type LogLine, type LogsQuery } from './cli/logs/index.js';
+import type { ApiCall } from './cli/exec/trace.js';
+import { type TestCustomer, type TextCall } from './cli/calls/index.js';
+import { type TurnRead, type TurnsQuery, type TurnSummary } from './cli/turns/index.js';
+import type { CaseOrchestratorTools, ScheduledActionView } from './core/case-orchestrator/types.js';
+import { type PageChannel, type PageContext, type PageEntryArg, type PageNextStep, type PageScheduledAction, type PageStart } from './core/page/define.js';
+import { type MemoryRows } from './core/page/memory-reader.js';
+import type { RecordsCall } from './core/page/records-query.js';
+import { type RenderedPage } from './core/page/render.js';
+import { type ConsoleLevel, type HostResult } from './core/page/sandbox.js';
+import { type OfficeHours, type OfficeHoursSnapshot } from './core/office-hours/index.js';
+import type { SystemContext } from './core/context/types.js';
+import type { Db } from './core/page/define.js';
+import { makeCaseOrchestratorCtx as makePlatformCaseOrchestratorCtx } from './fn-context/make-ctx.js';
+import { type RunResult, type TurnInput } from './cli/turns/shadow.js';
+export { fakeTools, unfaked } from './fn-context/fake/index.js';
+/**
+ * What a test may set on the fake `ctx`. Each `api` surface takes only the methods the test fakes
+ * (`{ exchanges: { last: async () => ({ exchange: null }) } }`), the rest keep their stand-ins; `api.db`
+ * takes any object (`recordingDb`), so a test fakes only the tables it needs.
+ */
+export type TestCtxOverrides = {
+    today?: string;
+    timezone?: string;
+    now?: number;
+    meta?: Partial<SystemContext['meta']>;
+    config?: Partial<SystemContext['config']>;
+    api?: {
+        [K in keyof SystemContext['api']]?: K extends 'db' ? object : Partial<SystemContext['api'][K]>;
+    };
+};
+/**
+ * A fake `ctx`, typed as the caller asks: `makeCtx<Ctx>()` for a function, with `Ctx` from the
+ * sequence's `__gen`. Data slice defaults: `today` 1970-01-01, `timezone` UTC. Any `api` call the test
+ * did not fake rejects, naming the call.
+ */
+export declare function makeCtx<C = SystemContext>(overrides?: TestCtxOverrides): C;
+/** A fake Orchestrator `ctx`, typed as the caller asks; `tools` fakes `ctx.api.tools`, `db` fakes `ctx.api.db`. */
+export declare function makeCaseOrchestratorCtx<C = Awaited<ReturnType<typeof makePlatformCaseOrchestratorCtx>>>(overrides?: TestCtxOverrides & {
+    tools?: Partial<CaseOrchestratorTools>;
+    db?: object;
+}): Promise<C>;
+/** One call a function made on `db`. */
+export type DbCall = {
+    table: string;
+    method: string;
+    args: unknown;
+};
+/** Answers for `db` calls, by table then method; the return value is what the call resolves to. */
+export type DbHandlers = Record<string, Record<string, (args: any) => unknown>>;
+/**
+ * A `db` that records every call in `calls`, in order, and answers from `handlers`. A call with no
+ * handler rejects, naming it, so a test sees every read and write the function makes.
+ */
+export declare function recordingDb(handlers?: DbHandlers): {
+    db: Db;
+    calls: DbCall[];
+};
+/**
+ * A row as `ctx.api.db` hands it out, for a `recordingDb` handler to return: `id` as given, every other
+ * field a slot (`{ value, state, reason, updatedAt, ref }`), `filled` when it has a value, `empty` when
+ * null. A test that returns plain values instead (`{ crm_id: null }`) checks code against a shape the
+ * platform never gives: `if (row.crm_id)` is then false in the test and always true for real.
+ */
+export declare function row(table: string, values: {
+    id: string;
+} & Record<string, unknown>): any;
+/** One request `mockFetch` answered. */
+export type FetchCall = {
+    method: string;
+    url: string;
+    body: string | null;
+};
+/** A route: requests whose method (any, when left out) and URL (exact, or a pattern) match it. */
+export type FetchRoute = {
+    method?: string;
+    url: string | RegExp;
+    /** A `Response` is returned as is; any other value is sent as JSON with status 200. */
+    respond: (request: Request) => unknown;
+};
+/**
+ * Replaces the global `fetch` until `restore()`: each request goes to the first matching route; one
+ * that matches none rejects, so a test never reaches a real system (a CRM, a payment provider).
+ */
+export declare function mockFetch(routes: FetchRoute[]): {
+    calls: FetchCall[];
+    restore: () => void;
+};
+/** What the page function gets besides the data; each left out is what a conversation without it has. */
+export type RenderPageInput = {
+    /** The sequence: its directory under `sequences/`. */
+    sequence: string;
+    /** The repository's root; the working directory when left out (where `npm test` runs). */
+    repoRoot?: string;
+    /** The rows the page can read, by table: `{ contact: [{ id: 'c1', first_name: 'Ann' }] }`. A field left out or null is empty. */
+    data: MemoryRows;
+    /** The id of the row the sequence runs about (its `subject` table's). */
+    subject: string;
+    /** The conversation's contact (`ctx.caller`), one of `data.contact`; none outside a conversation. */
+    caller?: string | null;
+    /** The page function to run; the page's first one when left out. */
+    channel?: PageChannel | null;
+    /** The render's time (ISO 8601); 2026-01-01T15:00:00Z when left out. */
+    now?: string;
+    scheduledAction?: PageScheduledAction | null;
+    officeHours?: PageContext['officeHours'];
+    nextSteps?: PageNextStep[];
+    /** `ctx.env`: the environment's configuration the page reads (76 §2.19); none when left out. A turn's export does not carry it. */
+    env?: Record<string, unknown>;
+    sms?: {
+        inbound: NonNullable<Extract<PageEntryArg, {
+            mode: 'render' | 'start';
+        }>['sms']>['inbound'];
+    };
+    email?: NonNullable<Extract<PageEntryArg, {
+        mode: 'render' | 'start';
+    }>['email']>;
+    call?: NonNullable<Extract<PageEntryArg, {
+        mode: 'render' | 'start';
+    }>['call']>;
+    /**
+     * `ctx.history`: the counts and the timeline the page reads; 0 and none when left out. Or each call and
+     * its answer (`[{ method, where, result }]`, a turn's export): a call not among them fails the render.
+     */
+    history?: {
+        sessionCount?: number;
+        exchangeCount?: number;
+        timeline?: unknown[];
+    } | HistoryAnswer[];
+    /** `ctx.session`, as the page gets it (a call's session row); none when left out. */
+    session?: RenderArg['session'];
+    /** `ctx.runs`: what the conversation's actions did; none when left out. */
+    runs?: RenderArg['runs'];
+    /** `ctx.conversation`; none when left out. */
+    conversation?: RenderArg['conversation'];
+    /** The case's id (`ctx.instanceId`); `test-instance` when left out. */
+    instanceId?: string;
+};
+/** What a render or a start of the page function is given. */
+type RenderArg = Extract<PageEntryArg, {
+    mode: 'render' | 'start';
+}>;
+/** One `ctx.history` call a page made and its answer, as a turn's export keeps them. */
+export type HistoryAnswer = {
+    method: unknown;
+    where: unknown;
+    result: HostResult;
+};
+export type RenderedTestPage = {
+    /** The page as the platform builds it from what the page function returned: its blocks, fields, buttons. */
+    page: RenderedPage;
+    /** The page as the AI reads it. */
+    text: string;
+    /** Every `db` read the page made, in order. */
+    reads: RecordsCall[];
+    /** The page's `console` lines. */
+    console: Array<{
+        level: ConsoleLevel;
+        text: string;
+    }>;
+};
+/** A page script that failed: what the sandbox said, and where in the compiled page it threw. */
+export declare class PageTestError extends Error {
+    readonly scriptStack: string | null;
+    constructor(message: string, scriptStack: string | null);
+}
+/**
+ * Renders the sequence's page (`context.page.ts`) over `data`, as the platform renders it: the same
+ * compile, sandbox, `db` semantics and page building, with the rows read from `data` instead of the
+ * database. A read the platform refuses is refused here too.
+ */
+export declare function renderPage(input: RenderPageInput): Promise<RenderedTestPage>;
+/**
+ * A turn's export (`turns export <turnId>`, `exportTurn`) as `renderPage`'s input: the moment the turn
+ * began — its rows, its `ctx`, and each `ctx.history` answer — to render with this repository's code now.
+ */
+export declare function fromTurn(dir: string, options?: {
+    repoRoot?: string;
+}): RenderPageInput;
+/** What the page decides when the conversation starts (its `persona` and `faq`), over `data`. */
+export declare function startPage(input: RenderPageInput): Promise<PageStart>;
+/**
+ * The office hours (`office-hours.ts`) at `at` (ISO 8601 or epoch ms), as the platform reads them: open
+ * or not, and today's windows. Office hours the platform would refuse fail with what is wrong.
+ */
+export declare function officeHoursAt(officeHours: OfficeHours, at: string | number): OfficeHoursSnapshot;
+/**
+ * The sequence compiled as a release compiles it (`index.ts`, its variables, functions, events, office
+ * hours, Orchestrator and page), for a test that checks its configuration. A configuration the release
+ * would refuse rejects with the release's message. Compiled once per test run.
+ */
+export declare function compileForTest(input: {
+    sequence: string;
+    repoRoot?: string;
+}): Promise<SequenceBuild>;
+export type { ApiCall, LogLine, LogsQuery, OfficeHours, OfficeHoursSnapshot, SequenceBuild };
+export type { TurnRead, TurnRecord, TurnSnapshot, TurnsQuery, TurnSummary } from './cli/turns/index.js';
+export type { InboxItem, SentResult, TestCustomer, TextCall, TextCallEnd, TextCallEvent, TextCallStep } from './cli/calls/index.js';
+/** An open connection to an environment for an integration test (`connect`). */
+export type Connection<C = SystemContext> = {
+    /** The environment (never prod). */
+    environment: {
+        id: string;
+        name: string;
+    };
+    /** A real `ctx`: each `ctx.api` call reads and writes the environment's data, and is recorded in `calls`. */
+    ctx: C;
+    /**
+     * The last 200 `ctx.api` calls made through `ctx`, in order: `call`, `input`, `ok`, `output` or `error`,
+     * `ms`. Every call, however many, is in `callsFile` (one JSON per line).
+     */
+    calls: ApiCall[];
+    callsFile: string;
+    /**
+     * What the code wrote (`ctx.api.log`, the page's `console`, its functions' failures) in this environment,
+     * read from the platform's log store now: oldest first, since this connection opened unless `since` says
+     * otherwise, at most `limit` (200; 500 at most). Filter by `instance`, `run`, `contact`, `sequence`,
+     * `request`, `level` (`warn`: warn and error), `search`. Lines reach the store a few seconds after they
+     * are written.
+     */
+    logs(query?: Omit<LogsQuery, 'env'>): Promise<LogLine[]>;
+    /**
+     * A case's page as a conversation on it renders it now: this repository's page, the case's real data.
+     * `caller`: the conversation's contact; the case's subject when it is a contact and none is named.
+     * Returns `page` and `text` as the unit tests' `renderPage` does, so the same checks apply.
+     */
+    renderPage(input: {
+        instanceId: string;
+        channel: PageChannel;
+        caller?: string;
+    }): Promise<{
+        page: RenderedPage;
+        text: string;
+    }>;
+    /**
+     * The case's Orchestrator run now, as after an external event (`ctx.api.instances.notify`), with the
+     * inputs the platform builds for the case and this repository's code. Says how it ended and the
+     * follow-ups it scheduled and cancelled; they are real, and run when due.
+     */
+    runOrchestrator(input: {
+        instanceId: string;
+        reason?: string;
+    }): Promise<{
+        status: 'completed' | 'failed' | 'held' | 'idle' | 'no_orchestrator';
+        failureCode?: string;
+        scheduled: ScheduledActionView[];
+        cancelled: ScheduledActionView[];
+    }>;
+    /**
+     * One turn, always a shadow (68 §8): a text or email run, or a call's turn, as when the customer writes or
+     * says `say`, with this repository's page, the platform's model, and the case's data as it is now — or
+     * `from` a turn that ran (its id, or the directory it was exported to): its rows and conversation as they
+     * were then, its words heard again (`say` replaces them). It runs on a shadow of the environment's
+     * database: what it did comes back (`writes`, `actions`, `said`, `events`) and none of it is kept, sent,
+     * booked or woken. Company functions are not run: replayed from the turn's record (`from`), else
+     * `functions.results`, else answered as not run (`functions` says which). The model words things
+     * differently each time: check what it did, and with `repeat` how often (`rate(run => run.clicked('x'))`).
+     */
+    turn(input: TurnInput): Promise<RunResult>;
+    /**
+     * Runs `actions` on the case's page as the model's step would, with no model: `{ fill: '<field id>',
+     * value }`, `{ click: '<button id>', arguments }`, `{ note: '…' }`… (field and button ids as the page
+     * names them: `renderPage`'s `text`). Then the run ends without a reply. `stepResult` is what the
+     * platform told the model about each action.
+     */
+    act(input: TurnInput & {
+        actions: unknown[];
+    }): Promise<RunResult>;
+    /**
+     * The turns of a case, a run or a call in this environment, oldest first (68 §7.4): what the customer
+     * said, what the AI said, the buttons and functions it ran, the fields it wrote. Name one of them.
+     */
+    turns(query: TurnsQuery): Promise<TurnSummary[]>;
+    /** One turn, and what it began with (`snapshot`: null once it is no longer kept, after 30 days). */
+    readTurn(turnId: string): Promise<TurnRead>;
+    /** One turn written to `dir` (`.superpanel/turns/<turnId>/` when left out), as `turns export` writes it; the directory. */
+    exportTurn(turnId: string, dir?: string): Promise<string>;
+    /**
+     * Test lines and customers (68 §5.3): `line(name)` is the environment's simulated line of that name
+     * (`Main line` when left out), made when it has none, a number no provider carries; `phone()` a new test
+     * customer's number. A simulated line reaches test customers only, and a test customer only a simulated line.
+     */
+    sim: {
+        /**
+         * When a real line has that name, the simulated line stands in for it (`mirrors`): your `resolve` sees
+         * it by that name, and code's `from` that names the real line reaches a test customer through it.
+         */
+        line(name?: string): Promise<{
+            id: string;
+            number: string;
+            name: string;
+            mirrors: {
+                id: string;
+                number: string;
+            } | null;
+        }>;
+        /** The environment's simulated mailbox of that name (`Support` when left out), made when it has none: an address no provider has; standing in for a real one of that name, as `line` does. */
+        mailbox(name?: string): Promise<{
+            id: string;
+            address: string;
+            name: string;
+            mirrors: {
+                id: string;
+                address: string;
+            } | null;
+        }>;
+        phone(): string;
+        /**
+         * A test customer (68 §5.2), a new number and address unless given: they text and email the simulated
+         * lines and mailboxes, wait for what the environment sends them (`next('sms')`, `next('call')`), and
+         * answer or let ring its calls.
+         */
+        customer(input?: {
+            phone?: string;
+            email?: string;
+        }): TestCustomer;
+    };
+    /**
+     * A case's next scheduled step done now, as its job would when due (68 §6.4): for a step that waits for a
+     * day ("call on day 2"). Contact hours are the environment's to switch off (Environments page), not this.
+     */
+    runDue(input: {
+        instanceId: string;
+        scheduledActionId?: string;
+    }): Promise<{
+        action: {
+            id: string;
+            kind: string;
+            name: string | null;
+            reason: string | null;
+            scheduledFor: string;
+        } | null;
+        result: unknown;
+    }>;
+    /**
+     * A call in text (68 §4): a test customer (`from`, `sim.phone()`) calls a simulated line (`to`, its name or
+     * number, `Main line` when left out). This repository's code on the environment's real data, as a real
+     * call: the resolves, the opening, each turn, the wrap-up after the hang-up, `call.ended`, the Orchestrator.
+     * What the AI says comes back as text; a keypad, a transfer or a voicemail as an event to answer.
+     */
+    call: {
+        inbound(input: {
+            from: string;
+            to?: string;
+        }): Promise<TextCall>;
+    };
+    /** Stops serving this repository on the environment. Called by itself after the test file's tests. */
+    close(): Promise<void>;
+};
+export type { RunResult, ShadowRun, TurnInput } from './cli/turns/shadow.js';
+/**
+ * Connects a test file to an environment (`sandbox` when `env` is left out) as the CLI's login: this
+ * repository's code serves it (as `superpanel-sdk-runtime serve` does, its imports checked as a release
+ * checks them) until the file's tests are done, and `ctx` reads and writes the environment's real data.
+ * What a test writes is written.
+ */
+/**
+ * `debug`: when a test's debug package is written (68 §9, `.superpanel/tests/`): `failed` (the default),
+ * `always`, or `off`; `SUPERPANEL_TEST_DEBUG` overrides it.
+ */
+export declare function connect<C = SystemContext>(options?: {
+    env?: string;
+    repoRoot?: string;
+    url?: string;
+    debug?: 'failed' | 'always' | 'off';
+}): Promise<Connection<C>>;
+//# sourceMappingURL=testing.d.ts.map