@superpanel-sdk/runtime 0.5.0 → 0.7.0

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

@@ -1,4 +1,5 @@
 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.
@@ -33,6 +34,7 @@ export declare const exchangeLastInput: z.ZodObject<{
         kind: z.ZodEnum<{
             email: "email";
             phone: "phone";
+            sip: "sip";
         }>;
         value: z.ZodString;
     }, z.core.$strip>;
@@ -62,6 +64,7 @@ export declare const exchangeEmailThreadInput: z.ZodObject<{
         kind: z.ZodEnum<{
             email: "email";
             phone: "phone";
+            sip: "sip";
         }>;
         value: z.ZodString;
     }, z.core.$strip>;
@@ -77,12 +80,25 @@ export declare const exchangeEmailThreadOutput: z.ZodObject<{
     }, 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;
@@ -94,6 +110,7 @@ export declare const exchangesSurface: {
                     kind: z.ZodEnum<{
                         email: "email";
                         phone: "phone";
+                        sip: "sip";
                     }>;
                     value: z.ZodString;
                 }, z.core.$strip>;
@@ -123,6 +140,7 @@ export declare const exchangesSurface: {
                     kind: z.ZodEnum<{
                         email: "email";
                         phone: "phone";
+                        sip: "sip";
                     }>;
                     value: z.ZodString;
                 }, z.core.$strip>;
@@ -136,6 +154,13 @@ export declare const exchangesSurface: {
                 }, 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;
 };

package/dist/core/context/exchanges.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { arrivalAddress, partyAddress } from '../party/schema.js';
+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.
@@ -25,25 +26,38 @@ export const exchangeSummary = z.object({
     contactId: z.string().nullable(),
 });
 export const exchangeLastInput = z.strictObject({
-    /** Our number or mailbox (`ctx.params.to`). */
-    ours: partyAddress,
+    /** Our number, SIP address or mailbox (`conversation.to` of `resolve`). A SIP address has calls only. */
+    ours: arrivalAddress,
     /**
-     * Theirs (`ctx.params.from`). Phone exchanges are calls and texts; email ones are emails; a SIP caller's
+     * 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 (`ctx.params.to`): a provider thread id is only one mailbox's. */
-    ours: partyAddress,
-    /** The provider thread id (`ctx.params.threadId`). */
+    /**
+     * 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() {
@@ -52,11 +66,15 @@ export const exchangesMockService = {
     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,
 };

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

@@ -56,6 +56,30 @@ export declare const instanceCloseInput: z.ZodObject<{
     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>;
@@ -114,8 +138,11 @@ export type InstancesApi = {
      */
     start(input: InstanceStartParams): Promise<InstanceStartResult>;
     get(input: InstanceIdParams): Promise<InstanceSummary>;
-    /** End the instance: its pending scheduled actions are cancelled and no Run follows. Final. */
-    close(input: InstanceCloseParams): 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>;
     /**
@@ -207,6 +234,8 @@ export declare const instancesSurface: {
                 createdAt: z.ZodString;
                 lastActivityAt: z.ZodString;
                 closedAt: z.ZodNullable<z.ZodString>;
+                alreadyClosed: z.ZodBoolean;
+                cancelledScheduledActionIds: z.ZodArray<z.ZodString>;
             }, z.core.$strip>;
         };
         setVariables: {

package/dist/core/context/instances.js

@@ -39,6 +39,14 @@ export const instanceCloseInput = z.strictObject({
     /** 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). */
@@ -52,8 +60,7 @@ export const instanceFindForContactInput = z.strictObject({
 export const instanceNotifyInput = z.strictObject({
     instanceId: z.string().min(1),
     /**
-     * What happened, a short stable label (`payment.posted`), for the Run's trigger, its log and the
-     * Agent's prompt. The facts go in the records first: the Orchestrator reads them when it runs.
+     * 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),
     /**
@@ -97,7 +104,14 @@ export const instancesMockService = {
         return { ...mockInstance, id: input.instanceId };
     },
     async close(input) {
-        return { ...mockInstance, id: input.instanceId, status: 'closed', closeReason: input.reason };
+        return {
+            ...mockInstance,
+            id: input.instanceId,
+            status: 'closed',
+            closeReason: input.reason,
+            alreadyClosed: false,
+            cancelledScheduledActionIds: [],
+        };
     },
     async setVariables(input) {
         return { ...mockInstance, id: input.instanceId, variables: input.values };
@@ -113,7 +127,7 @@ export const instancesSurface = {
     methods: {
         start: { input: instanceStartInput, output: instanceStartOutput },
         get: { input: instanceIdInput, output: instanceSummary },
-        close: { input: instanceCloseInput, output: instanceSummary },
+        close: { input: instanceCloseInput, output: instanceCloseOutput },
         setVariables: { input: instanceSetVariablesInput, output: instanceSummary },
         findForContact: { input: instanceFindForContactInput, output: instanceListOutput },
         notify: { input: instanceNotifyInput, output: instanceNotifyOutput },

package/dist/core/context/platform-registry.d.ts

@@ -264,6 +264,20 @@ export declare const platformSurfaces: {
                     occurredAt: import("zod").ZodString;
                 }, import("zod/v4/core").$strip>>;
             };
+            send: {
+                input: import("zod").ZodObject<{
+                    to: import("zod").ZodUnion<readonly [import("zod").ZodString, import("zod").ZodObject<{
+                        address: import("zod").ZodString;
+                    }, import("zod/v4/core").$strict>]>;
+                    body: import("zod").ZodString;
+                    subject: import("zod").ZodOptional<import("zod").ZodString>;
+                    instanceId: import("zod").ZodOptional<import("zod").ZodString>;
+                    from: import("zod").ZodOptional<import("zod").ZodString>;
+                }, import("zod/v4/core").$strict>;
+                output: import("zod").ZodObject<{
+                    exchangeId: import("zod").ZodString;
+                }, import("zod/v4/core").$strip>;
+            };
         };
         mock: import("./email-message.js").EmailHistoryApi;
     };
@@ -275,6 +289,7 @@ export declare const platformSurfaces: {
                         kind: import("zod").ZodEnum<{
                             email: "email";
                             phone: "phone";
+                            sip: "sip";
                         }>;
                         value: import("zod").ZodString;
                     }, import("zod/v4/core").$strip>;
@@ -304,6 +319,7 @@ export declare const platformSurfaces: {
                         kind: import("zod").ZodEnum<{
                             email: "email";
                             phone: "phone";
+                            sip: "sip";
                         }>;
                         value: import("zod").ZodString;
                     }, import("zod/v4/core").$strip>;
@@ -317,6 +333,13 @@ export declare const platformSurfaces: {
                     }, import("zod/v4/core").$strip>>;
                 }, import("zod/v4/core").$strip>;
             };
+            activity: {
+                input: import("zod").ZodObject<{
+                    instanceId: import("zod").ZodString;
+                    contactIds: import("zod").ZodArray<import("zod").ZodString>;
+                }, import("zod/v4/core").$strip>;
+                output: import("zod").ZodCustom<import("../case-orchestrator/types.js").CaseActivity, import("../case-orchestrator/types.js").CaseActivity>;
+            };
         };
         mock: import("./exchanges.js").ExchangesApi;
     };
@@ -393,6 +416,8 @@ export declare const platformSurfaces: {
                     createdAt: import("zod").ZodString;
                     lastActivityAt: import("zod").ZodString;
                     closedAt: import("zod").ZodNullable<import("zod").ZodString>;
+                    alreadyClosed: import("zod").ZodBoolean;
+                    cancelledScheduledActionIds: import("zod").ZodArray<import("zod").ZodString>;
                 }, import("zod/v4/core").$strip>;
             };
             setVariables: {
@@ -560,6 +585,16 @@ export declare const platformSurfaces: {
                     occurredAt: import("zod").ZodString;
                 }, import("zod/v4/core").$strip>>;
             };
+            send: {
+                input: import("zod").ZodObject<{
+                    to: import("zod").ZodString;
+                    body: import("zod").ZodString;
+                    instanceId: import("zod").ZodOptional<import("zod").ZodString>;
+                }, import("zod/v4/core").$strip>;
+                output: import("zod").ZodObject<{
+                    exchangeId: import("zod").ZodString;
+                }, import("zod/v4/core").$strip>;
+            };
         };
         mock: import("./sms.js").SmsApi;
     };

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

@@ -79,10 +79,30 @@ export declare const smsGetOutput: z.ZodNullable<z.ZodObject<{
     errorCode: z.ZodNullable<z.ZodString>;
     occurredAt: z.ZodString;
 }, z.core.$strip>>;
+/**
+ * A text sent now (32), from any entry (64 §15): to a contact (its row id, not a number: the platform checks
+ * their opt-outs and finds their number), from the number of the call the run is on, else the one they are
+ * texted from. Stored with the run, then sent. The case it is about: `instanceId` when given (one of this
+ * environment's, else refused: `unknown_instance`), else the case the run is on; the case's Orchestrator
+ * hears `sms.sent`. With neither it is on no case: in the contact's history only (49), nobody told. Pause
+ * and contact hours are not checked: sending is company code's call.
+ */
+export declare const smsSendInput: z.ZodObject<{
+    to: z.ZodString;
+    body: z.ZodString;
+    instanceId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SmsSendParams = z.infer<typeof smsSendInput>;
+/** The exchange the text was recorded as (`sms.sent` on the case's timeline). */
+export declare const smsSendOutput: z.ZodObject<{
+    exchangeId: z.ZodString;
+}, z.core.$strip>;
+export type SmsSendResult = z.infer<typeof smsSendOutput>;
 /** Platform SMS capability, reached from scripts as `ctx.api.sms`. */
 export type SmsApi = {
     list(input: SmsListParams): Promise<SmsListResult>;
     get(id: string): Promise<SmsRecord | null>;
+    send(input: SmsSendParams): Promise<SmsSendResult>;
 };
 export declare const smsMockService: SmsApi;
 export declare const smsSurface: {
@@ -141,6 +161,16 @@ export declare const smsSurface: {
                 occurredAt: z.ZodString;
             }, z.core.$strip>>;
         };
+        send: {
+            input: z.ZodObject<{
+                to: z.ZodString;
+                body: z.ZodString;
+                instanceId: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            output: z.ZodObject<{
+                exchangeId: z.ZodString;
+            }, z.core.$strip>;
+        };
     };
     mock: SmsApi;
 };

package/dist/core/context/sms.js

@@ -39,6 +39,22 @@ export const smsListOutput = z.object({
 });
 export const smsGetInput = z.string().min(1);
 export const smsGetOutput = smsRecord.nullable();
+/**
+ * A text sent now (32), from any entry (64 §15): to a contact (its row id, not a number: the platform checks
+ * their opt-outs and finds their number), from the number of the call the run is on, else the one they are
+ * texted from. Stored with the run, then sent. The case it is about: `instanceId` when given (one of this
+ * environment's, else refused: `unknown_instance`), else the case the run is on; the case's Orchestrator
+ * hears `sms.sent`. With neither it is on no case: in the contact's history only (49), nobody told. Pause
+ * and contact hours are not checked: sending is company code's call.
+ */
+export const smsSendInput = z.object({
+    to: z.string().min(1),
+    body: z.string().min(1),
+    /** The case the text is about, any of this environment's; absent: the run's own case, if any. */
+    instanceId: z.string().min(1).optional(),
+});
+/** The exchange the text was recorded as (`sms.sent` on the case's timeline). */
+export const smsSendOutput = z.object({ exchangeId: z.string() });
 export const smsMockService = {
     async list(input) {
         return { sms: [], offset: input.offset, limit: input.limit };
@@ -46,11 +62,15 @@ export const smsMockService = {
     async get() {
         return null;
     },
+    async send() {
+        return { exchangeId: 'mock-sms' };
+    },
 };
 export const smsSurface = {
     methods: {
         list: { input: smsListInput, output: smsListOutput },
         get: { input: smsGetInput, output: smsGetOutput },
+        send: { input: smsSendInput, output: smsSendOutput },
     },
     mock: smsMockService,
 };

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

@@ -1,8 +1,10 @@
+import type { CaseOrchestratorTools } from '../case-orchestrator/types.js';
 import type { PlatformApis } from './platform-registry.js';
 import type { Db } from '../page/define.js';
 import type { EmailApi } from './email.js';
 import type { EnvApi } from './env.js';
 import type { IntegrationAccountFields } from './account-fields.js';
+import type { TimeParts } from '../page/time-format.js';
 export type { IntegrationAccountFields, IntegrationTarget } from './account-fields.js';
 /**
  * Lifecycle state of a slot field (`01-slot-design §2`):
@@ -19,7 +21,7 @@ export type Logger = {
     warn: (message: string, extra?: Record<string, unknown>) => void;
     error: (message: string, extra?: Record<string, unknown>) => void;
 };
-export type { EmailApi, EmailAttachment, EmailGetAttachmentInput, EmailGetAttachmentOutput, EmailGetMessageInput, EmailGetMessageOutput, EmailListMessagesInput, EmailListMessagesOutput, EmailProvider, EmailSendEmailInput, EmailSendEmailOutput, EmailService, } from './email.js';
+export type { EmailApi, EmailAttachment, EmailGetAttachmentInput, EmailGetAttachmentOutput, EmailGetMessageInput, EmailGetMessageOutput, EmailListMessagesInput, EmailListMessagesOutput, EmailProvider, EmailProviderService, EmailSendEmailInput, EmailSendEmailOutput, EmailService, } from './email.js';
 export type { EnvApi, EnvService } from './env.js';
 export type { ContactApi, ContactListParams, ContactListResult, ContactSummary } from './contact.js';
 /**
@@ -38,6 +40,11 @@ export type IntegrationSurfaceMeta = IntegrationAccountFields & {
     surfaceKey: IntegrationSurfaceKey;
     methods: string[];
 };
+/** What does not hold while an environment is tested (68 §6.2). */
+export type ContactHoursIgnore = Readonly<{
+    contactHours: boolean;
+    contactSchedule: boolean;
+}>;
 /** Context injected into custom and system functions. */
 export type SystemContext = {
     time: Readonly<{
@@ -47,6 +54,12 @@ export type SystemContext = {
         timezone: string;
         /** Current calendar date (`YYYY-MM-DD`) in `time.timezone`, i.e. the UTC date. */
         today: string;
+        /**
+         * What does not hold in this environment while it is tested (68 §6.2, set on the environment, never in
+         * prod): `contactHours`, the company's contact hours; `contactSchedule`, contacts' own schedules.
+         * `nextContactTime(hours, ctx.time, zone)` and `withinContactHours(…, ctx.time.ignore)` follow it.
+         */
+        ignore: ContactHoursIgnore;
         /**
          * `at` as people read it, in `timeZone` (25 §11): "Tue, Nov 3, 3:00 PM EST" (`style` `'date'` or
          * `'time'` for one part). A contact's zone is `contactTimezone(…)`.
@@ -57,6 +70,17 @@ export type SystemContext = {
         }): string;
         /** The calendar day (`YYYY-MM-DD`) at `at` in `timeZone` (25 §11), to compare days or key a rule by date. */
         day(at: string | number, timeZone: string): string;
+        /**
+         * The exact moment (ISO 8601, UTC) a clock in `timeZone` shows `date` (`YYYY-MM-DD`) at `time` (`HH:mm`)
+         * (74 §4.7): "the day before delivery at 17:00 her time" is `at(dayBefore, '17:00', zone)`. A time the
+         * clocks skip is the moment just after the gap; one they show twice, the first.
+         */
+        at(date: string, time: string, timeZone: string): string;
+        /**
+         * `at` on a clock in `timeZone` (74 §4.7): its date, `HH:mm`, hour, minute, ISO weekday (1 Monday … 7
+         * Sunday) and offset, to decide "is the office open now" without parsing `format`'s text.
+         */
+        parts(at: string | number, timeZone: string): TimeParts;
     }>;
     meta: Readonly<{
         companyId: string;
@@ -95,9 +119,13 @@ export type SystemContext = {
          * write entry, each call its own transaction. Any row of the company and environment.
          */
         db: Db;
+        /** The platform's tools (38 §2.7): schedule, reschedule, cancel, hand over, read exchanges, on an instance named in each call. */
+        tools: CaseOrchestratorTools;
     };
 };
 export type MakeCtxOverrides = {
+    /** `ctx.time.ignore`: what does not hold while the environment is tested (68 §6.2); nothing when left out. */
+    ignore?: ContactHoursIgnore;
     today?: string;
     timezone?: string;
     now?: number;

package/dist/core/conversation/index.d.ts

@@ -6,13 +6,67 @@ export type Direction = 'inbound' | 'outbound';
 export declare const CHANNELS: readonly ['call', 'sms', 'email'];
 export type Channel = (typeof CHANNELS)[number];
 /**
- * The languages the platform speaks: the values of the contact's `language` field. Each needs a voice
- * (the default voice profile's settings for it) and the platform's fixed lines in it.
+ * The languages a contact can have (`contact.language`, 48 §3) and texts and emails tag their replies with
+ * (48 §5.2): BCP-47 base tags. Texts and emails need no voice, so they are not limited to what calls can
+ * speak (75 §3); a contact who writes in Chinese keeps `zh`, and a call with them opens in English.
  */
-export declare const SPOKEN_LANGUAGES: readonly ['english', 'spanish'];
-/** A spoken language as the contact's `language` field holds it (`english`, `spanish`). */
+export declare const CONTACT_LANGUAGES: readonly ['en', 'fr', 'de', 'es', 'pt', 'zh', 'ja', 'hi', 'it', 'ko', 'nl', 'pl', 'ru', 'sv', 'tr', 'tl', 'bg', 'ro', 'ar', 'cs', 'el', 'fi', 'hr', 'ms', 'sk', 'da', 'ta', 'uk', 'hu', 'no', 'vi', 'bn', 'th', 'he', 'ka', 'id', 'te', 'gu', 'kn', 'ml', 'mr', 'pa'];
+/**
+ * The languages calls can speak (48 §4, narrowed by 75 §3): the platform language table's tags, the ones
+ * Deepgram Flux (`flux-general-multi`) turns on, all spoken by Cartesia. Each has a native default voice,
+ * the platform's fixed lines and STOP words (services' language table). A caller speaking another language
+ * is answered in the call's language, told once it cannot be spoken (48 §1 item 6).
+ */
+export declare const SPOKEN_LANGUAGES: readonly ['en', 'es', 'fr', 'de', 'hi', 'ru', 'pt', 'ja', 'it', 'nl'];
+/** A language as the platform stores it: a canonical BCP-47 tag (`en`, `es`, `pt-BR`). */
 export type SpokenLanguage = string;
+/** A language `contact.language` holds, texts and emails are written in: a canonical tag, one of `CONTACT_LANGUAGES`. */
+export type ContactLanguage = string;
+/** One of the table's tags, as a type: a key of `Spoken`. */
+export type SpokenTag = (typeof SPOKEN_LANGUAGES)[number];
+/**
+ * A fixed line the platform says word for word to the customer, in each language the page wrote (66 §2):
+ * `{ en: 'One moment.', es: 'Un momento.' }`. At least one language; `en` is not required.
+ */
+export type Spoken = {
+    [K in SpokenTag]: {
+        [L in K]: string;
+    } & Partial<Record<SpokenTag, string>>;
+}[SpokenTag];
+/**
+ * `value` checked as a `Spoken` (66 §2): an object, at least one language, every key a table tag, every
+ * text not empty. Copied, in the order written. No `Intl` (the page sandbox has none).
+ */
+export declare function checkSpoken(value: unknown, at: string): Spoken;
+/** The text a `Spoken` falls back to (66 §3): `en` when written, else the first language written. */
+export declare function fallbackSpoken(spoken: Spoken): {
+    text: string;
+    language: SpokenTag;
+};
+/**
+ * The line to say on a call in `language` (66 §3): the same tag, else the same base language
+ * (`pt-BR` → `pt`), else `en`, else the first written. `missing`: the language it fell back from, to tell
+ * the company.
+ */
+export declare function pickSpoken(spoken: Spoken, language: string | null | undefined): {
+    text: string;
+    missing: string | null;
+};
+/** `value` as a canonical BCP-47 tag (`pt-br` → `pt-BR`), or null when it is not one. */
+export declare function canonicalLanguage(value: unknown): string | null;
+/** Whether `value` is one of the table's tags as stored (a language calls can speak). */
 export declare function isSpokenLanguage(value: unknown): value is SpokenLanguage;
+/** Whether `value` is a language `contact.language` can hold, as stored (texts and emails: any of them). */
+export declare function isContactLanguage(value: unknown): value is ContactLanguage;
+/**
+ * The table's language a tag resolves to (48 §2): the same tag, else the first with its base language
+ * (`es-MX` → `es`), unless that entry is not the fallback for it (`zh-HK`). Null: calls cannot speak it.
+ */
+export declare function matchSpokenLanguage(value: unknown): SpokenLanguage | null;
+/** The contact language a tag resolves to, as {@link matchSpokenLanguage} (`zh-CN` → `zh`). Null: none. */
+export declare function matchContactLanguage(value: unknown): ContactLanguage | null;
+/** A language's name in English, for prompts (`zh` → `Chinese`); the tag itself when it has none. */
+export declare function languageName(tag: string): string;
 /**
  * The scheduled action that started an outbound conversation (a scheduled call or message), fixed for
  * the session. An agreed follow-up has `agreedInExchangeId`; `note` says why it happens