@superpanel-sdk/runtime 0.2.3 → 0.7.0

package/dist/core/context/exchanges.d.ts

@@ -0,0 +1,167 @@
+import { z } from 'zod';
+import { type CaseActivity } from '../case-orchestrator/types.js';
+/**
+ * One exchange, as company code names it (21 §11.4): each channel the way it is told apart — a call by
+ * its id, a text line by our number and theirs, an email by its thread.
+ */
+export declare const exchangeRef: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    channel: z.ZodLiteral<"call">;
+    callId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    channel: z.ZodLiteral<"sms">;
+    ours: z.ZodString;
+    theirs: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    channel: z.ZodLiteral<"email">;
+    emailThreadId: z.ZodString;
+}, z.core.$strip>], "channel">;
+export type ExchangeRef = z.infer<typeof exchangeRef>;
+/**
+ * The latest exchange between our number / mailbox and theirs, whatever its session's state: a call
+ * back or a reply to a message is recognised by it (14-sequence-instance §18.4).
+ */
+export declare const exchangeSummary: z.ZodObject<{
+    instanceId: z.ZodString;
+    sequence: z.ZodString;
+    at: z.ZodString;
+    sessionActive: z.ZodBoolean;
+    instanceActive: z.ZodBoolean;
+    contactId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ExchangeSummary = z.infer<typeof exchangeSummary>;
+export declare const exchangeLastInput: z.ZodObject<{
+    ours: z.ZodObject<{
+        kind: z.ZodEnum<{
+            email: "email";
+            phone: "phone";
+            sip: "sip";
+        }>;
+        value: z.ZodString;
+    }, z.core.$strip>;
+    theirs: z.ZodObject<{
+        kind: z.ZodEnum<{
+            email: "email";
+            phone: "phone";
+            sip: "sip";
+        }>;
+        value: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strict>;
+export type ExchangeLastParams = z.infer<typeof exchangeLastInput>;
+export declare const exchangeLastOutput: z.ZodObject<{
+    exchange: z.ZodNullable<z.ZodObject<{
+        instanceId: z.ZodString;
+        sequence: z.ZodString;
+        at: z.ZodString;
+        sessionActive: z.ZodBoolean;
+        instanceActive: z.ZodBoolean;
+        contactId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ExchangeLastResult = z.infer<typeof exchangeLastOutput>;
+export declare const exchangeEmailThreadInput: z.ZodObject<{
+    ours: z.ZodObject<{
+        kind: z.ZodEnum<{
+            email: "email";
+            phone: "phone";
+            sip: "sip";
+        }>;
+        value: z.ZodString;
+    }, z.core.$strip>;
+    threadId: z.ZodString;
+}, z.core.$strict>;
+export type ExchangeEmailThreadParams = z.infer<typeof exchangeEmailThreadInput>;
+/** The instance an email thread already belongs to. */
+export declare const exchangeEmailThreadOutput: z.ZodObject<{
+    thread: z.ZodNullable<z.ZodObject<{
+        instanceId: z.ZodString;
+        sequence: z.ZodString;
+        instanceActive: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ExchangeEmailThreadResult = z.infer<typeof exchangeEmailThreadOutput>;
+/**
+ * What one instance exchanged with the contacts its code names (38 §2.8): each one's history, contact
+ * hours and channel availability, the instance's together. The Orchestrator reads it to write its
+ * prompt; whom to name is its own to read from the business data.
+ */
+export declare const exchangeActivityInput: z.ZodObject<{
+    instanceId: z.ZodString;
+    contactIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type ExchangeActivityParams = z.infer<typeof exchangeActivityInput>;
+export declare const exchangeActivityOutput: z.ZodCustom<CaseActivity, CaseActivity>;
+/** Platform exchange lookups, reached from scripts as `ctx.api.exchanges` (§18.4). */
+export type ExchangesApi = {
+    /** The latest exchange between `ours` and `theirs`; null when they never exchanged anything. */
+    last(input: ExchangeLastParams): Promise<ExchangeLastResult>;
+    /** The instance an email thread belongs to; null when no message of it is on an instance. */
+    emailThread(input: ExchangeEmailThreadParams): Promise<ExchangeEmailThreadResult>;
+    /** An instance's exchanges with `contactIds`, in that order: the first one's time zone is the instance's. */
+    activity(input: ExchangeActivityParams): Promise<CaseActivity>;
+};
+/** Stand-in surface for fake contexts and local runs; never touches the database. */
+export declare const exchangesMockService: ExchangesApi;
+export declare const exchangesSurface: {
+    methods: {
+        last: {
+            input: z.ZodObject<{
+                ours: z.ZodObject<{
+                    kind: z.ZodEnum<{
+                        email: "email";
+                        phone: "phone";
+                        sip: "sip";
+                    }>;
+                    value: z.ZodString;
+                }, z.core.$strip>;
+                theirs: z.ZodObject<{
+                    kind: z.ZodEnum<{
+                        email: "email";
+                        phone: "phone";
+                        sip: "sip";
+                    }>;
+                    value: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strict>;
+            output: z.ZodObject<{
+                exchange: z.ZodNullable<z.ZodObject<{
+                    instanceId: z.ZodString;
+                    sequence: z.ZodString;
+                    at: z.ZodString;
+                    sessionActive: z.ZodBoolean;
+                    instanceActive: z.ZodBoolean;
+                    contactId: z.ZodNullable<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+        };
+        emailThread: {
+            input: z.ZodObject<{
+                ours: z.ZodObject<{
+                    kind: z.ZodEnum<{
+                        email: "email";
+                        phone: "phone";
+                        sip: "sip";
+                    }>;
+                    value: z.ZodString;
+                }, z.core.$strip>;
+                threadId: z.ZodString;
+            }, z.core.$strict>;
+            output: z.ZodObject<{
+                thread: z.ZodNullable<z.ZodObject<{
+                    instanceId: z.ZodString;
+                    sequence: z.ZodString;
+                    instanceActive: z.ZodBoolean;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+        };
+        activity: {
+            input: z.ZodObject<{
+                instanceId: z.ZodString;
+                contactIds: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>;
+            output: z.ZodCustom<CaseActivity, CaseActivity>;
+        };
+    };
+    mock: ExchangesApi;
+};
+//# sourceMappingURL=exchanges.d.ts.map

package/dist/core/context/exchanges.js

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+import { arrivalAddress } from '../party/schema.js';
+import { EMPTY_CASE_ACTIVITY } from '../case-orchestrator/types.js';
+/**
+ * One exchange, as company code names it (21 §11.4): each channel the way it is told apart — a call by
+ * its id, a text line by our number and theirs, an email by its thread.
+ */
+export const exchangeRef = z.discriminatedUnion('channel', [
+    z.object({ channel: z.literal('call'), callId: z.string() }),
+    z.object({ channel: z.literal('sms'), ours: z.string(), theirs: z.string() }),
+    z.object({ channel: z.literal('email'), emailThreadId: z.string() }),
+]);
+/**
+ * The latest exchange between our number / mailbox and theirs, whatever its session's state: a call
+ * back or a reply to a message is recognised by it (14-sequence-instance §18.4).
+ */
+export const exchangeSummary = z.object({
+    instanceId: z.string(),
+    /** The instance's sequence (its name). */
+    sequence: z.string(),
+    at: z.string(),
+    /** Its session is still open (an SMS conversation not yet ended, a call in progress). */
+    sessionActive: z.boolean(),
+    instanceActive: z.boolean(),
+    /** The contact it was with. */
+    contactId: z.string().nullable(),
+});
+export const exchangeLastInput = z.strictObject({
+    /** Our number, SIP address or mailbox (`conversation.to` of `resolve`). A SIP address has calls only. */
+    ours: arrivalAddress,
+    /**
+     * Theirs (`conversation.from`). Phone exchanges are calls and texts; email ones are emails; a SIP caller's
+     * URI finds their calls from it.
+     */
+    theirs: arrivalAddress,
+});
+export const exchangeLastOutput = z.object({ exchange: exchangeSummary.nullable() });
+export const exchangeEmailThreadInput = z.strictObject({
+    /**
+     * Our mailbox the email came to (`conversation.to` of `resolve`): a provider thread id is only one
+     * mailbox's. A number or SIP address has no threads.
+     */
+    ours: arrivalAddress,
+    /** The provider thread id (`conversation.threadId`). */
+    threadId: z.string().min(1),
+});
+/** The instance an email thread already belongs to. */
+export const exchangeEmailThreadOutput = z.object({
+    thread: z.object({ instanceId: z.string(), sequence: z.string(), instanceActive: z.boolean() }).nullable(),
+});
+/**
+ * What one instance exchanged with the contacts its code names (38 §2.8): each one's history, contact
+ * hours and channel availability, the instance's together. The Orchestrator reads it to write its
+ * prompt; whom to name is its own to read from the business data.
+ */
+export const exchangeActivityInput = z.object({
+    instanceId: z.string().min(1),
+    contactIds: z.array(z.string().min(1)),
+});
+export const exchangeActivityOutput = z.custom((value) => typeof value === 'object' && value !== null);
+/** Stand-in surface for fake contexts and local runs; never touches the database. */
+export const exchangesMockService = {
+    async last() {
+        return { exchange: null };
+    },
+    async emailThread() {
+        return { thread: null };
+    },
+    async activity() {
+        return EMPTY_CASE_ACTIVITY;
+    },
+};
+export const exchangesSurface = {
+    methods: {
+        last: { input: exchangeLastInput, output: exchangeLastOutput },
+        emailThread: { input: exchangeEmailThreadInput, output: exchangeEmailThreadOutput },
+        activity: { input: exchangeActivityInput, output: exchangeActivityOutput },
+    },
+    mock: exchangesMockService,
+};
+//# sourceMappingURL=exchanges.js.map

package/dist/core/context/instances.d.ts

@@ -0,0 +1,307 @@
+import { z } from 'zod';
+/** One run of a sequence about one business root (14-sequence-instance §4). */
+export declare const instanceSummary: z.ZodObject<{
+    id: z.ZodString;
+    sequenceId: z.ZodString;
+    sequence: z.ZodString;
+    subjectRecordId: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        closed: "closed";
+    }>;
+    closeReason: z.ZodNullable<z.ZodString>;
+    origin: z.ZodString;
+    variables: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    experiments: z.ZodRecord<z.ZodString, z.ZodString>;
+    createdAt: z.ZodString;
+    lastActivityAt: z.ZodString;
+    closedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type InstanceSummary = z.infer<typeof instanceSummary>;
+export declare const instanceStartInput: z.ZodObject<{
+    sequence: z.ZodString;
+    subjectRecordId: z.ZodString;
+    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    origin: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type InstanceStartParams = z.infer<typeof instanceStartInput>;
+/** A start: the instance, and whether it is new (false when one was already active on the root). */
+export declare const instanceStartOutput: z.ZodObject<{
+    instance: z.ZodObject<{
+        id: z.ZodString;
+        sequenceId: z.ZodString;
+        sequence: z.ZodString;
+        subjectRecordId: z.ZodString;
+        status: z.ZodEnum<{
+            active: "active";
+            closed: "closed";
+        }>;
+        closeReason: z.ZodNullable<z.ZodString>;
+        origin: z.ZodString;
+        variables: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        experiments: z.ZodRecord<z.ZodString, z.ZodString>;
+        createdAt: z.ZodString;
+        lastActivityAt: z.ZodString;
+        closedAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    created: z.ZodBoolean;
+}, z.core.$strip>;
+export type InstanceStartResult = z.infer<typeof instanceStartOutput>;
+export declare const instanceIdInput: z.ZodObject<{
+    instanceId: z.ZodString;
+}, z.core.$strict>;
+export type InstanceIdParams = z.infer<typeof instanceIdInput>;
+export declare const instanceCloseInput: z.ZodObject<{
+    instanceId: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strict>;
+export type InstanceCloseParams = z.infer<typeof instanceCloseInput>;
+/**
+ * A close: the instance as it is now, whether it was closed already (then nothing changed: its reason
+ * stays the first close's), and the pending scheduled actions this close cancelled.
+ */
+export declare const instanceCloseOutput: z.ZodObject<{
+    id: z.ZodString;
+    sequenceId: z.ZodString;
+    sequence: z.ZodString;
+    subjectRecordId: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        closed: "closed";
+    }>;
+    closeReason: z.ZodNullable<z.ZodString>;
+    origin: z.ZodString;
+    variables: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    experiments: z.ZodRecord<z.ZodString, z.ZodString>;
+    createdAt: z.ZodString;
+    lastActivityAt: z.ZodString;
+    closedAt: z.ZodNullable<z.ZodString>;
+    alreadyClosed: z.ZodBoolean;
+    cancelledScheduledActionIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type InstanceCloseResult = z.infer<typeof instanceCloseOutput>;
+export declare const instanceSetVariablesInput: z.ZodObject<{
+    instanceId: z.ZodString;
+    values: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>;
+export type InstanceSetVariablesParams = z.infer<typeof instanceSetVariablesInput>;
+export declare const instanceFindForContactInput: z.ZodObject<{
+    contactId: z.ZodString;
+    activeOnly: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type InstanceFindForContactParams = z.infer<typeof instanceFindForContactInput>;
+export declare const instanceNotifyInput: z.ZodObject<{
+    instanceId: z.ZodString;
+    reason: z.ZodString;
+    key: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type InstanceNotifyParams = z.infer<typeof instanceNotifyInput>;
+/**
+ * `recorded`: the Orchestrator runs with an `external` trigger; `duplicate`: this key was already
+ * recorded; `instance_closed` / `no_orchestrator`: nothing runs (the instance ended, or its sequence
+ * has no orchestrator.ts).
+ */
+export declare const instanceNotifyOutput: z.ZodObject<{
+    outcome: z.ZodEnum<{
+        duplicate: "duplicate";
+        instance_closed: "instance_closed";
+        no_orchestrator: "no_orchestrator";
+        recorded: "recorded";
+    }>;
+}, z.core.$strip>;
+export type InstanceNotifyResult = z.infer<typeof instanceNotifyOutput>;
+export declare const instanceListOutput: z.ZodObject<{
+    instances: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        sequenceId: z.ZodString;
+        sequence: z.ZodString;
+        subjectRecordId: z.ZodString;
+        status: z.ZodEnum<{
+            active: "active";
+            closed: "closed";
+        }>;
+        closeReason: z.ZodNullable<z.ZodString>;
+        origin: z.ZodString;
+        variables: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        experiments: z.ZodRecord<z.ZodString, z.ZodString>;
+        createdAt: z.ZodString;
+        lastActivityAt: z.ZodString;
+        closedAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type InstanceListResult = z.infer<typeof instanceListOutput>;
+/** Platform instance capability, reached from scripts as `ctx.api.instances`. */
+export type InstancesApi = {
+    /**
+     * Start an instance of a sequence on a business root row. When one is already active on that row
+     * (any sequence) it is returned with `created: false` instead: one active instance per root.
+     */
+    start(input: InstanceStartParams): Promise<InstanceStartResult>;
+    get(input: InstanceIdParams): Promise<InstanceSummary>;
+    /**
+     * End the instance: its pending scheduled actions are cancelled and no Run follows. Final. An
+     * instance already closed is returned as it is (`alreadyClosed`). Shown on the case's timeline.
+     */
+    close(input: InstanceCloseParams): Promise<InstanceCloseResult>;
+    /** Merge run variables by name (atomic per variable; checked against the sequence's declarations). */
+    setVariables(input: InstanceSetVariablesParams): Promise<InstanceSummary>;
+    /**
+     * The instances a contact takes part in: those whose business root is the contact, or a row that
+     * refers to the contact by a lookup and is under the root (by parent, up to 5 levels). Most recent
+     * activity first.
+     */
+    findForContact(input: InstanceFindForContactParams): Promise<InstanceListResult>;
+    /**
+     * Tell the instance about something outside the platform (25 §6.2): its Orchestrator runs with an
+     * `external` trigger (`{ reason }`), debounced with the others. Write the facts first (`ctx.api.db`):
+     * the Orchestrator reads the case as it is when it runs. From a webhook, a function or
+     * an event handler; the Orchestrator decides what it means (cancel the reminder, close the case).
+     */
+    notify(input: InstanceNotifyParams): Promise<InstanceNotifyResult>;
+};
+/** Stand-in surface for fake contexts and local runs; never touches the database. */
+export declare const instancesMockService: InstancesApi;
+export declare const instancesSurface: {
+    methods: {
+        start: {
+            input: z.ZodObject<{
+                sequence: z.ZodString;
+                subjectRecordId: z.ZodString;
+                variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                origin: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            output: z.ZodObject<{
+                instance: z.ZodObject<{
+                    id: z.ZodString;
+                    sequenceId: z.ZodString;
+                    sequence: z.ZodString;
+                    subjectRecordId: z.ZodString;
+                    status: z.ZodEnum<{
+                        active: "active";
+                        closed: "closed";
+                    }>;
+                    closeReason: z.ZodNullable<z.ZodString>;
+                    origin: z.ZodString;
+                    variables: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                    experiments: z.ZodRecord<z.ZodString, z.ZodString>;
+                    createdAt: z.ZodString;
+                    lastActivityAt: z.ZodString;
+                    closedAt: z.ZodNullable<z.ZodString>;
+                }, z.core.$strip>;
+                created: z.ZodBoolean;
+            }, z.core.$strip>;
+        };
+        get: {
+            input: z.ZodObject<{
+                instanceId: z.ZodString;
+            }, z.core.$strict>;
+            output: z.ZodObject<{
+                id: z.ZodString;
+                sequenceId: z.ZodString;
+                sequence: z.ZodString;
+                subjectRecordId: z.ZodString;
+                status: z.ZodEnum<{
+                    active: "active";
+                    closed: "closed";
+                }>;
+                closeReason: z.ZodNullable<z.ZodString>;
+                origin: z.ZodString;
+                variables: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                experiments: z.ZodRecord<z.ZodString, z.ZodString>;
+                createdAt: z.ZodString;
+                lastActivityAt: z.ZodString;
+                closedAt: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>;
+        };
+        close: {
+            input: z.ZodObject<{
+                instanceId: z.ZodString;
+                reason: z.ZodString;
+            }, z.core.$strict>;
+            output: z.ZodObject<{
+                id: z.ZodString;
+                sequenceId: z.ZodString;
+                sequence: z.ZodString;
+                subjectRecordId: z.ZodString;
+                status: z.ZodEnum<{
+                    active: "active";
+                    closed: "closed";
+                }>;
+                closeReason: z.ZodNullable<z.ZodString>;
+                origin: z.ZodString;
+                variables: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                experiments: z.ZodRecord<z.ZodString, z.ZodString>;
+                createdAt: z.ZodString;
+                lastActivityAt: z.ZodString;
+                closedAt: z.ZodNullable<z.ZodString>;
+                alreadyClosed: z.ZodBoolean;
+                cancelledScheduledActionIds: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>;
+        };
+        setVariables: {
+            input: z.ZodObject<{
+                instanceId: z.ZodString;
+                values: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            }, z.core.$strict>;
+            output: z.ZodObject<{
+                id: z.ZodString;
+                sequenceId: z.ZodString;
+                sequence: z.ZodString;
+                subjectRecordId: z.ZodString;
+                status: z.ZodEnum<{
+                    active: "active";
+                    closed: "closed";
+                }>;
+                closeReason: z.ZodNullable<z.ZodString>;
+                origin: z.ZodString;
+                variables: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                experiments: z.ZodRecord<z.ZodString, z.ZodString>;
+                createdAt: z.ZodString;
+                lastActivityAt: z.ZodString;
+                closedAt: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>;
+        };
+        findForContact: {
+            input: z.ZodObject<{
+                contactId: z.ZodString;
+                activeOnly: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>;
+            output: z.ZodObject<{
+                instances: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    sequenceId: z.ZodString;
+                    sequence: z.ZodString;
+                    subjectRecordId: z.ZodString;
+                    status: z.ZodEnum<{
+                        active: "active";
+                        closed: "closed";
+                    }>;
+                    closeReason: z.ZodNullable<z.ZodString>;
+                    origin: z.ZodString;
+                    variables: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                    experiments: z.ZodRecord<z.ZodString, z.ZodString>;
+                    createdAt: z.ZodString;
+                    lastActivityAt: z.ZodString;
+                    closedAt: z.ZodNullable<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+        };
+        notify: {
+            input: z.ZodObject<{
+                instanceId: z.ZodString;
+                reason: z.ZodString;
+                key: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            output: z.ZodObject<{
+                outcome: z.ZodEnum<{
+                    duplicate: "duplicate";
+                    instance_closed: "instance_closed";
+                    no_orchestrator: "no_orchestrator";
+                    recorded: "recorded";
+                }>;
+            }, z.core.$strip>;
+        };
+    };
+    mock: InstancesApi;
+};
+//# sourceMappingURL=instances.d.ts.map

package/dist/core/context/instances.js

@@ -0,0 +1,137 @@
+import { z } from 'zod';
+/** One run of a sequence about one business root (14-sequence-instance §4). */
+export const instanceSummary = z.object({
+    id: z.string(),
+    sequenceId: z.string(),
+    /** The sequence's name (its directory under `sequences/`). */
+    sequence: z.string(),
+    subjectRecordId: z.string(),
+    status: z.enum(['active', 'closed']),
+    closeReason: z.string().nullable(),
+    origin: z.string(),
+    /** Run variables' current values (`variables.ts`). */
+    variables: z.record(z.string(), z.unknown()),
+    /** The group each experiment assigned. */
+    experiments: z.record(z.string(), z.string()),
+    createdAt: z.string(),
+    lastActivityAt: z.string(),
+    closedAt: z.string().nullable(),
+});
+export const instanceStartInput = z
+    .strictObject({
+    /** Name of the sequence to run. */
+    sequence: z.string().min(1),
+    /**
+     * A row of the table the sequence declares as `subject`. A new one is made first with
+     * `ctx.api.db.<table>.create` (28 §6), then the instance starts on it.
+     */
+    subjectRecordId: z.string().min(1),
+    /** Initial run variables, checked against the sequence's `variables.ts`. */
+    variables: z.record(z.string(), z.unknown()).optional(),
+    /** How it started (default `script`). */
+    origin: z.string().min(1).max(64).optional(),
+});
+/** A start: the instance, and whether it is new (false when one was already active on the root). */
+export const instanceStartOutput = z.object({ instance: instanceSummary, created: z.boolean() });
+export const instanceIdInput = z.strictObject({ instanceId: z.string().min(1) });
+export const instanceCloseInput = z.strictObject({
+    instanceId: z.string().min(1),
+    /** completed | cancelled | a short text (at most 64 characters). */
+    reason: z.string().min(1).max(64),
+});
+/**
+ * A close: the instance as it is now, whether it was closed already (then nothing changed: its reason
+ * stays the first close's), and the pending scheduled actions this close cancelled.
+ */
+export const instanceCloseOutput = instanceSummary.extend({
+    alreadyClosed: z.boolean(),
+    cancelledScheduledActionIds: z.array(z.string()),
+});
+export const instanceSetVariablesInput = z.strictObject({
+    instanceId: z.string().min(1),
+    /** Variables to set, merged by name (null unsets one). */
+    values: z.record(z.string(), z.unknown()),
+});
+export const instanceFindForContactInput = z.strictObject({
+    contactId: z.string().min(1),
+    /** Only active instances. */
+    activeOnly: z.boolean().optional(),
+});
+export const instanceNotifyInput = z.strictObject({
+    instanceId: z.string().min(1),
+    /**
+     * What happened, a short stable label (`payment.posted`), for the Run's trigger and its log. The facts go in the records first: the Orchestrator reads them when it runs.
+     */
+    reason: z.string().trim().min(1).max(64),
+    /**
+     * The event's own id (the payment's id), so a webhook delivered twice wakes the Orchestrator once:
+     * one key is recorded once per instance. Left out, every call is a new event.
+     */
+    key: z.string().trim().min(1).max(200).optional(),
+});
+/**
+ * `recorded`: the Orchestrator runs with an `external` trigger; `duplicate`: this key was already
+ * recorded; `instance_closed` / `no_orchestrator`: nothing runs (the instance ended, or its sequence
+ * has no orchestrator.ts).
+ */
+export const instanceNotifyOutput = z.object({
+    outcome: z.enum(['recorded', 'duplicate', 'instance_closed', 'no_orchestrator']),
+});
+export const instanceListOutput = z.object({ instances: z.array(instanceSummary) });
+const mockInstance = {
+    id: 'instance',
+    sequenceId: 'sequence',
+    sequence: 'sequence',
+    subjectRecordId: 'subject',
+    status: 'active',
+    closeReason: null,
+    origin: 'script',
+    variables: {},
+    experiments: {},
+    createdAt: new Date(0).toISOString(),
+    lastActivityAt: new Date(0).toISOString(),
+    closedAt: null,
+};
+/** Stand-in surface for fake contexts and local runs; never touches the database. */
+export const instancesMockService = {
+    async start(input) {
+        return {
+            instance: { ...mockInstance, sequence: input.sequence, subjectRecordId: input.subjectRecordId },
+            created: true,
+        };
+    },
+    async get(input) {
+        return { ...mockInstance, id: input.instanceId };
+    },
+    async close(input) {
+        return {
+            ...mockInstance,
+            id: input.instanceId,
+            status: 'closed',
+            closeReason: input.reason,
+            alreadyClosed: false,
+            cancelledScheduledActionIds: [],
+        };
+    },
+    async setVariables(input) {
+        return { ...mockInstance, id: input.instanceId, variables: input.values };
+    },
+    async findForContact() {
+        return { instances: [] };
+    },
+    async notify() {
+        return { outcome: 'recorded' };
+    },
+};
+export const instancesSurface = {
+    methods: {
+        start: { input: instanceStartInput, output: instanceStartOutput },
+        get: { input: instanceIdInput, output: instanceSummary },
+        close: { input: instanceCloseInput, output: instanceCloseOutput },
+        setVariables: { input: instanceSetVariablesInput, output: instanceSummary },
+        findForContact: { input: instanceFindForContactInput, output: instanceListOutput },
+        notify: { input: instanceNotifyInput, output: instanceNotifyOutput },
+    },
+    mock: instancesMockService,
+};
+//# sourceMappingURL=instances.js.map