@superpanel-sdk/runtime 0.2.3 → 0.7.0

package/dist/core/case-orchestrator/types.js

@@ -0,0 +1,42 @@
+/** Reserved export of `sequences/<id>/orchestrator.ts` and its name in the build's `functions`. */
+export const ORCHESTRATOR_FUNCTION = 'orchestrator';
+/** `ctx.meta.entry` / RunScope entry of a Case Orchestrator call. */
+export const ORCHESTRATOR_ENTRY = 'orchestrator';
+/** Platform tools a Run may open. Names, descriptions, schemas and executors belong to the platform. */
+export const CASE_ORCHESTRATOR_TOOL_NAMES = [
+    'readExchange',
+    'searchExchanges',
+    'scheduleCall',
+    'scheduleSms',
+    'scheduleEmail',
+    'scheduleUpdateSlots',
+    'rescheduleAction',
+    'cancelScheduledAction',
+    'scheduleNextSequence',
+    'scheduleWake',
+    'cancelWake',
+];
+export const ACTIVITY_RECENT_LIMIT = 50;
+/** How far back `recentAgreedActions` reaches. */
+export const RECENT_AGREED_ACTIONS_DAYS = 14;
+export const EMPTY_CASE_ACTIVITY = {
+    timezone: 'America/New_York',
+    all: {
+        firstAt: null,
+        total: 0,
+        dayNumber: 1,
+        today: { calls: 0, answeredCalls: 0, smsOut: 0, smsIn: 0, emailsOut: 0, emailsIn: 0 },
+        last: {
+            exchange: null,
+            inbound: null,
+            outbound: null,
+            call: null,
+            answeredCall: null,
+            sms: null,
+            email: null,
+        },
+        recent: [],
+    },
+    byContact: {},
+};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,291 @@
+import { z } from 'zod';
+import type { Id } from '../page/typed.js';
+export declare const CALL_PAGE_LIMIT_MAX = 100;
+export declare const callDirection: z.ZodEnum<{
+    inbound: "inbound";
+    outbound: "outbound";
+}>;
+export type CallDirection = z.infer<typeof callDirection>;
+/** One side of a call (21 §5.3): the AI, or a person on a line. */
+export declare const callParticipant: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        ai: "ai";
+        party: "party";
+    }>;
+    address: z.ZodNullable<z.ZodString>;
+    contactId: z.ZodNullable<z.ZodString>;
+    identifiedReason: z.ZodNullable<z.ZodString>;
+    isNewContact: z.ZodBoolean;
+    joinedAt: z.ZodString;
+    leftAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type CallParticipant = z.infer<typeof callParticipant>;
+/** Script-facing call projection (27 §5): who was on it; what was said is `transcript(id)`. */
+export declare const callRecord: z.ZodObject<{
+    id: z.ZodString;
+    sessionId: z.ZodNullable<z.ZodType<Id<"session">, unknown, z.core.$ZodTypeInternals<Id<"session">, unknown>>>;
+    instanceId: z.ZodNullable<z.ZodString>;
+    instanceIds: z.ZodArray<z.ZodString>;
+    contactIds: z.ZodArray<z.ZodString>;
+    participants: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            ai: "ai";
+            party: "party";
+        }>;
+        address: z.ZodNullable<z.ZodString>;
+        contactId: z.ZodNullable<z.ZodString>;
+        identifiedReason: z.ZodNullable<z.ZodString>;
+        isNewContact: z.ZodBoolean;
+        joinedAt: z.ZodString;
+        leftAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    externalId: z.ZodString;
+    direction: z.ZodEnum<{
+        inbound: "inbound";
+        outbound: "outbound";
+    }>;
+    from: z.ZodString;
+    to: z.ZodString;
+    status: z.ZodString;
+    outcome: z.ZodNullable<z.ZodString>;
+    startedAt: z.ZodString;
+    endedAt: z.ZodNullable<z.ZodString>;
+    durationSec: z.ZodNullable<z.ZodNumber>;
+    recordingUrl: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type CallRecord = z.infer<typeof callRecord>;
+export declare const callListInput: z.ZodObject<{
+    offset: z.ZodNumber;
+    limit: z.ZodNumber;
+    instanceId: z.ZodOptional<z.ZodString>;
+    contactId: z.ZodOptional<z.ZodString>;
+    direction: z.ZodOptional<z.ZodEnum<{
+        inbound: "inbound";
+        outbound: "outbound";
+    }>>;
+    status: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CallListParams = z.infer<typeof callListInput>;
+export declare const callListOutput: z.ZodObject<{
+    calls: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        sessionId: z.ZodNullable<z.ZodType<Id<"session">, unknown, z.core.$ZodTypeInternals<Id<"session">, unknown>>>;
+        instanceId: z.ZodNullable<z.ZodString>;
+        instanceIds: z.ZodArray<z.ZodString>;
+        contactIds: z.ZodArray<z.ZodString>;
+        participants: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodEnum<{
+                ai: "ai";
+                party: "party";
+            }>;
+            address: z.ZodNullable<z.ZodString>;
+            contactId: z.ZodNullable<z.ZodString>;
+            identifiedReason: z.ZodNullable<z.ZodString>;
+            isNewContact: z.ZodBoolean;
+            joinedAt: z.ZodString;
+            leftAt: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+        externalId: z.ZodString;
+        direction: z.ZodEnum<{
+            inbound: "inbound";
+            outbound: "outbound";
+        }>;
+        from: z.ZodString;
+        to: z.ZodString;
+        status: z.ZodString;
+        outcome: z.ZodNullable<z.ZodString>;
+        startedAt: z.ZodString;
+        endedAt: z.ZodNullable<z.ZodString>;
+        durationSec: z.ZodNullable<z.ZodNumber>;
+        recordingUrl: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    offset: z.ZodNumber;
+    limit: z.ZodNumber;
+}, z.core.$strip>;
+export type CallListResult = z.infer<typeof callListOutput>;
+export declare const callGetInput: z.ZodString;
+export declare const callGetOutput: z.ZodNullable<z.ZodObject<{
+    id: z.ZodString;
+    sessionId: z.ZodNullable<z.ZodType<Id<"session">, unknown, z.core.$ZodTypeInternals<Id<"session">, unknown>>>;
+    instanceId: z.ZodNullable<z.ZodString>;
+    instanceIds: z.ZodArray<z.ZodString>;
+    contactIds: z.ZodArray<z.ZodString>;
+    participants: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            ai: "ai";
+            party: "party";
+        }>;
+        address: z.ZodNullable<z.ZodString>;
+        contactId: z.ZodNullable<z.ZodString>;
+        identifiedReason: z.ZodNullable<z.ZodString>;
+        isNewContact: z.ZodBoolean;
+        joinedAt: z.ZodString;
+        leftAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    externalId: z.ZodString;
+    direction: z.ZodEnum<{
+        inbound: "inbound";
+        outbound: "outbound";
+    }>;
+    from: z.ZodString;
+    to: z.ZodString;
+    status: z.ZodString;
+    outcome: z.ZodNullable<z.ZodString>;
+    startedAt: z.ZodString;
+    endedAt: z.ZodNullable<z.ZodString>;
+    durationSec: z.ZodNullable<z.ZodNumber>;
+    recordingUrl: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>>;
+/** One spoken line of a call, oldest first (events such as a transfer or a hang-up left out). */
+export declare const callTranscriptLine: z.ZodObject<{
+    at: z.ZodString;
+    speaker: z.ZodEnum<{
+        ai: "ai";
+        party: "party";
+    }>;
+    participantId: z.ZodNullable<z.ZodString>;
+    contactId: z.ZodNullable<z.ZodString>;
+    instanceId: z.ZodNullable<z.ZodString>;
+    text: z.ZodString;
+    interrupted: z.ZodBoolean;
+}, z.core.$strip>;
+export type CallTranscriptLine = z.infer<typeof callTranscriptLine>;
+export declare const callTranscriptInput: z.ZodString;
+export declare const callTranscriptOutput: z.ZodNullable<z.ZodObject<{
+    callId: z.ZodString;
+    lines: z.ZodArray<z.ZodObject<{
+        at: z.ZodString;
+        speaker: z.ZodEnum<{
+            ai: "ai";
+            party: "party";
+        }>;
+        participantId: z.ZodNullable<z.ZodString>;
+        contactId: z.ZodNullable<z.ZodString>;
+        instanceId: z.ZodNullable<z.ZodString>;
+        text: z.ZodString;
+        interrupted: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+export type CallTranscript = NonNullable<z.infer<typeof callTranscriptOutput>>;
+/** Platform call-history capability, reached from scripts as `ctx.api.call`. */
+export type CallApi = {
+    list(input: CallListParams): Promise<CallListResult>;
+    get(id: string): Promise<CallRecord | null>;
+    /** What was said on any call of the company and environment (27 §5.3); null when there is no such call. */
+    transcript(id: string): Promise<CallTranscript | null>;
+};
+export declare const callMockService: CallApi;
+export declare const callSurface: {
+    methods: {
+        list: {
+            input: z.ZodObject<{
+                offset: z.ZodNumber;
+                limit: z.ZodNumber;
+                instanceId: z.ZodOptional<z.ZodString>;
+                contactId: z.ZodOptional<z.ZodString>;
+                direction: z.ZodOptional<z.ZodEnum<{
+                    inbound: "inbound";
+                    outbound: "outbound";
+                }>>;
+                status: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            output: z.ZodObject<{
+                calls: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    sessionId: z.ZodNullable<z.ZodType<Id<"session">, unknown, z.core.$ZodTypeInternals<Id<"session">, unknown>>>;
+                    instanceId: z.ZodNullable<z.ZodString>;
+                    instanceIds: z.ZodArray<z.ZodString>;
+                    contactIds: z.ZodArray<z.ZodString>;
+                    participants: z.ZodArray<z.ZodObject<{
+                        id: z.ZodString;
+                        kind: z.ZodEnum<{
+                            ai: "ai";
+                            party: "party";
+                        }>;
+                        address: z.ZodNullable<z.ZodString>;
+                        contactId: z.ZodNullable<z.ZodString>;
+                        identifiedReason: z.ZodNullable<z.ZodString>;
+                        isNewContact: z.ZodBoolean;
+                        joinedAt: z.ZodString;
+                        leftAt: z.ZodNullable<z.ZodString>;
+                    }, z.core.$strip>>;
+                    externalId: z.ZodString;
+                    direction: z.ZodEnum<{
+                        inbound: "inbound";
+                        outbound: "outbound";
+                    }>;
+                    from: z.ZodString;
+                    to: z.ZodString;
+                    status: z.ZodString;
+                    outcome: z.ZodNullable<z.ZodString>;
+                    startedAt: z.ZodString;
+                    endedAt: z.ZodNullable<z.ZodString>;
+                    durationSec: z.ZodNullable<z.ZodNumber>;
+                    recordingUrl: z.ZodNullable<z.ZodString>;
+                }, z.core.$strip>>;
+                offset: z.ZodNumber;
+                limit: z.ZodNumber;
+            }, z.core.$strip>;
+        };
+        get: {
+            input: z.ZodString;
+            output: z.ZodNullable<z.ZodObject<{
+                id: z.ZodString;
+                sessionId: z.ZodNullable<z.ZodType<Id<"session">, unknown, z.core.$ZodTypeInternals<Id<"session">, unknown>>>;
+                instanceId: z.ZodNullable<z.ZodString>;
+                instanceIds: z.ZodArray<z.ZodString>;
+                contactIds: z.ZodArray<z.ZodString>;
+                participants: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    kind: z.ZodEnum<{
+                        ai: "ai";
+                        party: "party";
+                    }>;
+                    address: z.ZodNullable<z.ZodString>;
+                    contactId: z.ZodNullable<z.ZodString>;
+                    identifiedReason: z.ZodNullable<z.ZodString>;
+                    isNewContact: z.ZodBoolean;
+                    joinedAt: z.ZodString;
+                    leftAt: z.ZodNullable<z.ZodString>;
+                }, z.core.$strip>>;
+                externalId: z.ZodString;
+                direction: z.ZodEnum<{
+                    inbound: "inbound";
+                    outbound: "outbound";
+                }>;
+                from: z.ZodString;
+                to: z.ZodString;
+                status: z.ZodString;
+                outcome: z.ZodNullable<z.ZodString>;
+                startedAt: z.ZodString;
+                endedAt: z.ZodNullable<z.ZodString>;
+                durationSec: z.ZodNullable<z.ZodNumber>;
+                recordingUrl: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>>;
+        };
+        transcript: {
+            input: z.ZodString;
+            output: z.ZodNullable<z.ZodObject<{
+                callId: z.ZodString;
+                lines: z.ZodArray<z.ZodObject<{
+                    at: z.ZodString;
+                    speaker: z.ZodEnum<{
+                        ai: "ai";
+                        party: "party";
+                    }>;
+                    participantId: z.ZodNullable<z.ZodString>;
+                    contactId: z.ZodNullable<z.ZodString>;
+                    instanceId: z.ZodNullable<z.ZodString>;
+                    text: z.ZodString;
+                    interrupted: z.ZodBoolean;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+        };
+    };
+    mock: CallApi;
+};
+//# sourceMappingURL=call.d.ts.map

package/dist/core/context/call.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+export const CALL_PAGE_LIMIT_MAX = 100;
+export const callDirection = z.enum(['inbound', 'outbound']);
+/** A session id the platform hands out: typed as one, so `db.session.findUnique({ where: { id } })` takes it. */
+const sessionId = z.string();
+/** One side of a call (21 §5.3): the AI, or a person on a line. */
+export const callParticipant = z.object({
+    id: z.string(),
+    kind: z.enum(['ai', 'party']),
+    /** Their number (E.164) or address; null for the AI. */
+    address: z.string().nullable(),
+    contactId: z.string().nullable(),
+    /** How the contact was found: `address_match` | `resolve` | `verified` | `reconnect`; null when not known. */
+    identifiedReason: z.string().nullable(),
+    /** The contact was created for this call. */
+    isNewContact: z.boolean(),
+    joinedAt: z.string(),
+    leftAt: z.string().nullable(),
+});
+/** Script-facing call projection (27 §5): who was on it; what was said is `transcript(id)`. */
+export const callRecord = z.object({
+    id: z.string(),
+    /** Null when the call never became a conversation (no answer). */
+    sessionId: sessionId.nullable(),
+    /** The call's first case; `instanceIds` all of them (a call can move to another case). */
+    instanceId: z.string().nullable(),
+    instanceIds: z.array(z.string()),
+    /** The contacts of the parties (`participants` of kind `party`). */
+    contactIds: z.array(z.string()),
+    participants: z.array(callParticipant),
+    externalId: z.string(),
+    direction: callDirection,
+    from: z.string(),
+    to: z.string(),
+    /** The provider's status of the main line (`in-progress`, `completed`, `no-answer` …). */
+    status: z.string(),
+    /** How the call ended (21 §5.2): connected | voicemail | no_answer | busy | failed | fallback | apology; null while it goes on. */
+    outcome: z.string().nullable(),
+    startedAt: z.string(),
+    endedAt: z.string().nullable(),
+    durationSec: z.number().int().min(0).nullable(),
+    recordingUrl: z.string().nullable(),
+});
+export const callListInput = z.object({
+    offset: z.number().int().min(0),
+    limit: z.number().int().min(1).max(CALL_PAGE_LIMIT_MAX),
+    instanceId: z.string().optional(),
+    contactId: z.string().optional(),
+    direction: callDirection.optional(),
+    status: z.string().optional(),
+});
+export const callListOutput = z.object({
+    calls: z.array(callRecord),
+    offset: z.number().int(),
+    limit: z.number().int(),
+});
+export const callGetInput = z.string().min(1);
+export const callGetOutput = callRecord.nullable();
+/** One spoken line of a call, oldest first (events such as a transfer or a hang-up left out). */
+export const callTranscriptLine = z.object({
+    /** When it started, ISO 8601. */
+    at: z.string(),
+    speaker: z.enum(['ai', 'party']),
+    /** Who said it (a {@link CallParticipant} id); null when unclear. */
+    participantId: z.string().nullable(),
+    contactId: z.string().nullable(),
+    /** The case the call was on when it was said. */
+    instanceId: z.string().nullable(),
+    text: z.string(),
+    /** The AI was cut off while saying it. */
+    interrupted: z.boolean(),
+});
+export const callTranscriptInput = z.string().min(1);
+export const callTranscriptOutput = z.object({ callId: z.string(), lines: z.array(callTranscriptLine) }).nullable();
+export const callMockService = {
+    async list(input) {
+        return { calls: [], offset: input.offset, limit: input.limit };
+    },
+    async get() {
+        return null;
+    },
+    async transcript() {
+        return null;
+    },
+};
+export const callSurface = {
+    methods: {
+        list: { input: callListInput, output: callListOutput },
+        get: { input: callGetInput, output: callGetOutput },
+        transcript: { input: callTranscriptInput, output: callTranscriptOutput },
+    },
+    mock: callMockService,
+};
+//# sourceMappingURL=call.js.map

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

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+/**
+ * The environment's numbers and mailboxes (22-sequence-as-business-unit §8), read-only. Code picks one
+ * of them when it assigns a contact its own (`assigned_phone_number` / `assigned_mailbox`), e.g. a
+ * number local to the contact's area code; `name` is what an explicit `from` takes.
+ */
+export declare const channelPhoneNumber: z.ZodObject<{
+    number: z.ZodString;
+    name: z.ZodNullable<z.ZodString>;
+    locality: z.ZodNullable<z.ZodString>;
+    region: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ChannelPhoneNumber = z.infer<typeof channelPhoneNumber>;
+export declare const channelMailbox: z.ZodObject<{
+    address: z.ZodString;
+    name: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ChannelMailbox = z.infer<typeof channelMailbox>;
+export declare const channelsListInput: z.ZodObject<{}, z.core.$strict>;
+export type ChannelsListParams = z.infer<typeof channelsListInput>;
+export declare const channelsListOutput: z.ZodObject<{
+    phoneNumbers: z.ZodArray<z.ZodObject<{
+        number: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+        locality: z.ZodNullable<z.ZodString>;
+        region: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    mailboxes: z.ZodArray<z.ZodObject<{
+        address: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ChannelsListResult = z.infer<typeof channelsListOutput>;
+/** The environment's active numbers and mailboxes, reached from scripts as `ctx.api.channels`. */
+export type ChannelsApi = {
+    list(input: ChannelsListParams): Promise<ChannelsListResult>;
+};
+/** Stand-in surface for fake contexts and local runs; never touches the database. */
+export declare const channelsMockService: ChannelsApi;
+export declare const channelsSurface: {
+    methods: {
+        list: {
+            input: z.ZodObject<{}, z.core.$strict>;
+            output: z.ZodObject<{
+                phoneNumbers: z.ZodArray<z.ZodObject<{
+                    number: z.ZodString;
+                    name: z.ZodNullable<z.ZodString>;
+                    locality: z.ZodNullable<z.ZodString>;
+                    region: z.ZodNullable<z.ZodString>;
+                }, z.core.$strip>>;
+                mailboxes: z.ZodArray<z.ZodObject<{
+                    address: z.ZodString;
+                    name: z.ZodNullable<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+        };
+    };
+    mock: ChannelsApi;
+};
+//# sourceMappingURL=channels.d.ts.map

package/dist/core/context/channels.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+/**
+ * The environment's numbers and mailboxes (22-sequence-as-business-unit §8), read-only. Code picks one
+ * of them when it assigns a contact its own (`assigned_phone_number` / `assigned_mailbox`), e.g. a
+ * number local to the contact's area code; `name` is what an explicit `from` takes.
+ */
+export const channelPhoneNumber = z.object({
+    /** E.164. */
+    number: z.string(),
+    name: z.string().nullable(),
+    locality: z.string().nullable(),
+    region: z.string().nullable(),
+});
+export const channelMailbox = z.object({
+    address: z.string(),
+    name: z.string().nullable(),
+});
+export const channelsListInput = z.strictObject({});
+export const channelsListOutput = z.object({
+    phoneNumbers: z.array(channelPhoneNumber),
+    mailboxes: z.array(channelMailbox),
+});
+/** Stand-in surface for fake contexts and local runs; never touches the database. */
+export const channelsMockService = {
+    async list() {
+        return { phoneNumbers: [], mailboxes: [] };
+    },
+};
+export const channelsSurface = {
+    methods: {
+        list: { input: channelsListInput, output: channelsListOutput },
+    },
+    mock: channelsMockService,
+};
+//# sourceMappingURL=channels.js.map

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

@@ -1,11 +1,16 @@
 import { z } from 'zod';
+import type { Id } from '../page/typed.js';
 export declare const CONTACT_PAGE_LIMIT_MAX = 100;
+/** A filled slot value as scripts read and write it. */
+export declare const slotFieldValue: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>, z.ZodNull]>;
+export type SlotFieldValue = z.infer<typeof slotFieldValue>;
 export declare const contactSummary: z.ZodObject<{
-    id: z.ZodString;
+    id: z.ZodCustom<Id<"contact">, Id<"contact">>;
     kind: z.ZodString;
-    externalIdentifier: z.ZodNullable<z.ZodString>;
     phone: z.ZodNullable<z.ZodString>;
+    email: z.ZodNullable<z.ZodString>;
     createdAt: z.ZodString;
+    fields: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>, z.ZodNull]>>;
 }, z.core.$strip>;
 export type ContactSummary = z.infer<typeof contactSummary>;
 export declare const contactListInput: z.ZodObject<{
@@ -17,19 +22,58 @@ export declare const contactListInput: z.ZodObject<{
 export type ContactListParams = z.infer<typeof contactListInput>;
 export declare const contactListOutput: z.ZodObject<{
     contacts: z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
+        id: z.ZodCustom<Id<"contact">, Id<"contact">>;
         kind: z.ZodString;
-        externalIdentifier: z.ZodNullable<z.ZodString>;
         phone: z.ZodNullable<z.ZodString>;
+        email: z.ZodNullable<z.ZodString>;
         createdAt: z.ZodString;
+        fields: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>, z.ZodNull]>>;
     }, z.core.$strip>>;
     offset: z.ZodNumber;
     limit: z.ZodNumber;
 }, z.core.$strip>;
 export type ContactListResult = z.infer<typeof contactListOutput>;
+/** Exactly one identity: an id, a phone or an email. */
+export declare const contactFindInput: z.ZodUnion<readonly [z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    phone: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    email: z.ZodString;
+}, z.core.$strict>]>;
+export type ContactFindParams = z.infer<typeof contactFindInput>;
+export declare const contactFindOutput: z.ZodObject<{
+    contacts: z.ZodArray<z.ZodObject<{
+        id: z.ZodCustom<Id<"contact">, Id<"contact">>;
+        kind: z.ZodString;
+        phone: z.ZodNullable<z.ZodString>;
+        email: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+        fields: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ContactFindResult = z.infer<typeof contactFindOutput>;
+export declare const contactCreateInput: z.ZodObject<{
+    fields: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+}, z.core.$strict>;
+export type ContactCreateParams = z.infer<typeof contactCreateInput>;
+export declare const contactIdInput: z.ZodObject<{
+    contactId: z.ZodString;
+}, z.core.$strict>;
+export type ContactIdParams = z.infer<typeof contactIdInput>;
 /** Platform contact capability, reached from scripts as `ctx.api.contact`. */
 export type ContactApi = {
     list(input: ContactListParams): Promise<ContactListResult>;
+    /** Contacts with this id, phone or email; several people can share a phone or an email. */
+    find(input: ContactFindParams): Promise<ContactFindResult>;
+    /** A new contact with these fields filled (`kind` defaults to `person`). */
+    create(input: ContactCreateParams): Promise<ContactSummary>;
+    /**
+     * "Remove" a contact (14-sequence-instance §5.5): clear its phone, email and every other identifier
+     * field, drop their lookup rows, cancel its pending scheduled actions. The record and its history
+     * stay. An opted-out contact's addresses go to the do-not-contact list first.
+     */
+    clearContactMethods(input: ContactIdParams): Promise<ContactSummary>;
 };
 /** Stand-in surface for fake contexts and local runs; never touches the database. */
 export declare const contactMockService: ContactApi;
@@ -44,16 +88,62 @@ export declare const contactSurface: {
             }, z.core.$strip>;
             output: z.ZodObject<{
                 contacts: z.ZodArray<z.ZodObject<{
-                    id: z.ZodString;
+                    id: z.ZodCustom<Id<"contact">, Id<"contact">>;
                     kind: z.ZodString;
-                    externalIdentifier: z.ZodNullable<z.ZodString>;
                     phone: z.ZodNullable<z.ZodString>;
+                    email: z.ZodNullable<z.ZodString>;
                     createdAt: z.ZodString;
+                    fields: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>, z.ZodNull]>>;
                 }, z.core.$strip>>;
                 offset: z.ZodNumber;
                 limit: z.ZodNumber;
             }, z.core.$strip>;
         };
+        find: {
+            input: z.ZodUnion<readonly [z.ZodObject<{
+                id: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                phone: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                email: z.ZodString;
+            }, z.core.$strict>]>;
+            output: z.ZodObject<{
+                contacts: z.ZodArray<z.ZodObject<{
+                    id: z.ZodCustom<Id<"contact">, Id<"contact">>;
+                    kind: z.ZodString;
+                    phone: z.ZodNullable<z.ZodString>;
+                    email: z.ZodNullable<z.ZodString>;
+                    createdAt: z.ZodString;
+                    fields: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+        };
+        create: {
+            input: z.ZodObject<{
+                fields: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+            }, z.core.$strict>;
+            output: z.ZodObject<{
+                id: z.ZodCustom<Id<"contact">, Id<"contact">>;
+                kind: z.ZodString;
+                phone: z.ZodNullable<z.ZodString>;
+                email: z.ZodNullable<z.ZodString>;
+                createdAt: z.ZodString;
+                fields: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+            }, z.core.$strip>;
+        };
+        clearContactMethods: {
+            input: z.ZodObject<{
+                contactId: z.ZodString;
+            }, z.core.$strict>;
+            output: z.ZodObject<{
+                id: z.ZodCustom<Id<"contact">, Id<"contact">>;
+                kind: z.ZodString;
+                phone: z.ZodNullable<z.ZodString>;
+                email: z.ZodNullable<z.ZodString>;
+                createdAt: z.ZodString;
+                fields: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>, z.ZodNull]>>;
+            }, z.core.$strip>;
+        };
     };
     mock: ContactApi;
 };