@superpanel-sdk/runtime 0.2.3 → 0.7.0

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

@@ -0,0 +1,177 @@
+import { z } from 'zod';
+export declare const SMS_PAGE_LIMIT_MAX = 100;
+export declare const smsDirection: z.ZodEnum<{
+    inbound: "inbound";
+    outbound: "outbound";
+}>;
+export type SmsDirection = z.infer<typeof smsDirection>;
+/**
+ * Script-facing SMS projection (21 §5.10). A text line is our number and theirs: `from` / `to` are the
+ * message's own. Provider metadata stays private.
+ */
+export declare const smsRecord: z.ZodObject<{
+    id: z.ZodString;
+    instanceId: z.ZodNullable<z.ZodString>;
+    contactId: z.ZodNullable<z.ZodString>;
+    runId: z.ZodNullable<z.ZodString>;
+    direction: z.ZodEnum<{
+        inbound: "inbound";
+        outbound: "outbound";
+    }>;
+    from: z.ZodString;
+    to: z.ZodString;
+    body: z.ZodNullable<z.ZodString>;
+    processing: z.ZodNullable<z.ZodString>;
+    delivery: z.ZodNullable<z.ZodString>;
+    errorCode: z.ZodNullable<z.ZodString>;
+    occurredAt: z.ZodString;
+}, z.core.$strip>;
+export type SmsRecord = z.infer<typeof smsRecord>;
+export declare const smsListInput: z.ZodObject<{
+    offset: z.ZodNumber;
+    limit: z.ZodNumber;
+    instanceId: z.ZodOptional<z.ZodString>;
+    contactId: z.ZodOptional<z.ZodString>;
+    counterpart: z.ZodOptional<z.ZodString>;
+    direction: z.ZodOptional<z.ZodEnum<{
+        inbound: "inbound";
+        outbound: "outbound";
+    }>>;
+}, z.core.$strip>;
+export type SmsListParams = z.infer<typeof smsListInput>;
+export declare const smsListOutput: z.ZodObject<{
+    sms: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        instanceId: z.ZodNullable<z.ZodString>;
+        contactId: z.ZodNullable<z.ZodString>;
+        runId: z.ZodNullable<z.ZodString>;
+        direction: z.ZodEnum<{
+            inbound: "inbound";
+            outbound: "outbound";
+        }>;
+        from: z.ZodString;
+        to: z.ZodString;
+        body: z.ZodNullable<z.ZodString>;
+        processing: z.ZodNullable<z.ZodString>;
+        delivery: z.ZodNullable<z.ZodString>;
+        errorCode: z.ZodNullable<z.ZodString>;
+        occurredAt: z.ZodString;
+    }, z.core.$strip>>;
+    offset: z.ZodNumber;
+    limit: z.ZodNumber;
+}, z.core.$strip>;
+export type SmsListResult = z.infer<typeof smsListOutput>;
+export declare const smsGetInput: z.ZodString;
+export declare const smsGetOutput: z.ZodNullable<z.ZodObject<{
+    id: z.ZodString;
+    instanceId: z.ZodNullable<z.ZodString>;
+    contactId: z.ZodNullable<z.ZodString>;
+    runId: z.ZodNullable<z.ZodString>;
+    direction: z.ZodEnum<{
+        inbound: "inbound";
+        outbound: "outbound";
+    }>;
+    from: z.ZodString;
+    to: z.ZodString;
+    body: z.ZodNullable<z.ZodString>;
+    processing: z.ZodNullable<z.ZodString>;
+    delivery: z.ZodNullable<z.ZodString>;
+    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: {
+    methods: {
+        list: {
+            input: z.ZodObject<{
+                offset: z.ZodNumber;
+                limit: z.ZodNumber;
+                instanceId: z.ZodOptional<z.ZodString>;
+                contactId: z.ZodOptional<z.ZodString>;
+                counterpart: z.ZodOptional<z.ZodString>;
+                direction: z.ZodOptional<z.ZodEnum<{
+                    inbound: "inbound";
+                    outbound: "outbound";
+                }>>;
+            }, z.core.$strip>;
+            output: z.ZodObject<{
+                sms: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    instanceId: z.ZodNullable<z.ZodString>;
+                    contactId: z.ZodNullable<z.ZodString>;
+                    runId: z.ZodNullable<z.ZodString>;
+                    direction: z.ZodEnum<{
+                        inbound: "inbound";
+                        outbound: "outbound";
+                    }>;
+                    from: z.ZodString;
+                    to: z.ZodString;
+                    body: z.ZodNullable<z.ZodString>;
+                    processing: z.ZodNullable<z.ZodString>;
+                    delivery: z.ZodNullable<z.ZodString>;
+                    errorCode: z.ZodNullable<z.ZodString>;
+                    occurredAt: 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;
+                instanceId: z.ZodNullable<z.ZodString>;
+                contactId: z.ZodNullable<z.ZodString>;
+                runId: z.ZodNullable<z.ZodString>;
+                direction: z.ZodEnum<{
+                    inbound: "inbound";
+                    outbound: "outbound";
+                }>;
+                from: z.ZodString;
+                to: z.ZodString;
+                body: z.ZodNullable<z.ZodString>;
+                processing: z.ZodNullable<z.ZodString>;
+                delivery: z.ZodNullable<z.ZodString>;
+                errorCode: z.ZodNullable<z.ZodString>;
+                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;
+};
+//# sourceMappingURL=sms.d.ts.map

package/dist/core/context/sms.js

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+export const SMS_PAGE_LIMIT_MAX = 100;
+export const smsDirection = z.enum(['inbound', 'outbound']);
+/**
+ * Script-facing SMS projection (21 §5.10). A text line is our number and theirs: `from` / `to` are the
+ * message's own. Provider metadata stays private.
+ */
+export const smsRecord = z.object({
+    id: z.string(),
+    instanceId: z.string().nullable(),
+    contactId: z.string().nullable(),
+    /** Inbound: the run that handled it; outbound: the run that sent it (null: the platform did). */
+    runId: z.string().nullable(),
+    direction: smsDirection,
+    from: z.string(),
+    to: z.string(),
+    body: z.string().nullable(),
+    /** Inbound: pending | claimed | processed | skipped | declined | failed. */
+    processing: z.string().nullable(),
+    /** Outbound: pending | submitting | the provider's status (queued, sent, delivered, undelivered, failed …). */
+    delivery: z.string().nullable(),
+    /** The provider's error code, as given. */
+    errorCode: z.string().nullable(),
+    occurredAt: z.string(),
+});
+export const smsListInput = z.object({
+    offset: z.number().int().min(0),
+    limit: z.number().int().min(1).max(SMS_PAGE_LIMIT_MAX),
+    instanceId: z.string().optional(),
+    contactId: z.string().optional(),
+    /** Their number: one text line with them (on any of our numbers). */
+    counterpart: z.string().optional(),
+    direction: smsDirection.optional(),
+});
+export const smsListOutput = z.object({
+    sms: z.array(smsRecord),
+    offset: z.number().int(),
+    limit: z.number().int(),
+});
+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 };
+    },
+    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,
+};
+//# sourceMappingURL=sms.js.map

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

@@ -1,100 +1,131 @@
-import type { FieldPath } from '../slot/path.js';
+import type { CaseOrchestratorTools } from '../case-orchestrator/types.js';
 import type { PlatformApis } from './platform-registry.js';
-import type { DocusignApi } from './docusign.js';
+import type { Db } from '../page/define.js';
+import type { EmailApi } from './email.js';
 import type { EnvApi } from './env.js';
-import type { FilevineApi } from './filevine.js';
-import type { HubspotApi } from './hubspot.js';
-import type { TwilioApi } from './twilio.js';
-import type { HttpApi } from './http.js';
 import type { IntegrationAccountFields } from './account-fields.js';
+import type { TimeParts } from '../page/time-format.js';
 export type { IntegrationAccountFields, IntegrationTarget } from './account-fields.js';
-export type FieldState = 'empty' | 'filled' | 'asked_unknown' | 'declined';
-/**
- * Fallback Slots. Sequence `__gen/slots.type.ts` provides the narrowed shape;
- * `view.ts` selectors import that type.
- */
-export type Slots = Record<string, unknown>;
-/**
- * Fallback CaseContext (no view / before narrowing).
- * With `view.ts`, use `CaseContextOf<typeof caseContextView>` from that module.
- */
-export type CaseContext = Record<string, unknown>;
-/** Flat writes for single-row tables, or the current-bound row of an entity table. */
-export type FieldWrites = Record<FieldPath, unknown>;
-/** Address one row of a multi-row table (`children`, `contact`, custom arrays). */
-export type RowWrite = {
-    table: string;
-    rowId: string;
-    values: Record<string, unknown>;
-};
-/** Mix flat field writes with explicit row writes in one return. */
-export type StructuredWrites = {
-    fields?: FieldWrites;
-    rows?: RowWrite[];
-};
 /**
- * Function / platform write payload.
- * Flat `{ '表.字段': 值 }` for single-row (or current-party) fields;
- * `{ table, rowId, values }` to write a specific multi-row.
+ * Lifecycle state of a slot field (`01-slot-design §2`):
+ * - `'empty'`: Not yet asked or set (`value` is `null`). Not `resolved`.
+ * - `'filled'`: Has an answer (`value` is non-null). Counts as `resolved`.
+ * - `'asked_unknown'`: Asked, and the contact does not know / cannot remember (`value` is `null` or a coarse value). Counts as `resolved`.
+ * - `'declined'`: Asked, and the contact refused to answer (`value` is `null`). Counts as `resolved`.
  */
-export type Writes = FieldWrites | RowWrite | StructuredWrites;
+export type FieldState = 'empty' | 'filled' | 'asked_unknown' | 'declined';
+/** Field states a write can set without a value; the platform stores `value: null`. */
+export type SlotWriteClearState = 'empty' | 'asked_unknown' | 'declined';
 export type Logger = {
     info: (message: string, extra?: Record<string, unknown>) => void;
     warn: (message: string, extra?: Record<string, unknown>) => void;
     error: (message: string, extra?: Record<string, unknown>) => void;
 };
-export type { DocusignApi, DocusignService } from './docusign.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 { FilevineApi, FilevineService } from './filevine.js';
-export type { HubspotApi, HubspotService } from './hubspot.js';
-export type { TwilioApi, TwilioCreateCallInput, TwilioCreateCallOutput, TwilioIncomingNumber, TwilioListIncomingNumbersOutput, TwilioSendSmsInput, TwilioSendSmsOutput, TwilioService, } from './twilio.js';
 export type { ContactApi, ContactListParams, ContactListResult, ContactSummary } from './contact.js';
-export type { HttpApi } from './http.js';
 /**
  * Integration API: surfaceKey → array of bound stubs.
  * Add a key here when the platform adds a script surface; the provider table must implement it.
  */
 export type IntegrationApi = {
-    hubspots?: HubspotApi[];
-    twilios?: TwilioApi[];
-    filevines?: FilevineApi[];
-    docusigns?: DocusignApi[];
     envs?: EnvApi[];
+    emails?: EmailApi[];
 };
 export type IntegrationSurfaceKey = keyof IntegrationApi;
 type SurfaceItem<K extends IntegrationSurfaceKey> = NonNullable<IntegrationApi[K]>[number];
 export type IntegrationStub = SurfaceItem<IntegrationSurfaceKey>;
-export declare const integrationSurfaceKeys: readonly ["hubspots", "twilios", "filevines", "docusigns", "envs"];
-export type BoundIntegrationMeta = IntegrationAccountFields & {
+export declare const integrationSurfaceKeys: readonly ["envs", "emails"];
+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<{
+        /** Current wall-clock timestamp in epoch milliseconds (use instead of `Date.now()`). */
         now: number;
+        /** IANA timezone of `today`; currently always `'UTC'` (not the contact's or office's timezone). */
         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(…)`.
+         */
+        format(at: string | number, options: {
+            timeZone: string;
+            style?: 'datetime' | 'date' | 'time';
+        }): 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;
         environmentId: string;
         sequenceId: string;
+        /**
+         * What the function runs under: `'voice'` / `'sms'` / `'email'` in a conversation,
+         * `'orchestrator'` in an Orchestrator Run, `'resolve'` when resolving a conversation.
+         */
         entry: string;
-        contactId: string;
-        caseId: string;
+        /**
+         * The instance the function runs on; null when none (`resolve`, a webhook, a handler without one).
+         * Who the conversation is with, and its session, are not here (28 §4): a page passes them as the
+         * function's params (`runFunction(name, { prefill: { contactId: ctx.caller.id, sessionId: ctx.session.id } })`).
+         */
+        instanceId: string | null;
+        /**
+         * A function pressed as a button (25 §11): this press's key, the same when the AI presses it again with
+         * the same arguments in the same run. Send it to another system as its idempotency key, so a second
+         * press does not do the work twice. Absent outside a button.
+         */
+        idempotencyKey?: string;
     }>;
     config: Readonly<{
+        /** Base URL of the frontend app. */
         frontendUrl: string;
+        /** Base URL of the backend RPC endpoint. */
         backendUrl: string;
     }>;
     api: PlatformApis & {
         integration: IntegrationApi;
         log: Logger;
-        http: HttpApi;
+        /**
+         * The company's records, Prisma-shaped (`db.<table>.findMany(…)`, `db.<table>.update(…)`): reads
+         * like a page script's (every `where` anchored), writes like a page action's, through the explicit
+         * 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/context/types.js

@@ -1,9 +1,3 @@
-export const integrationSurfaceKeys = [
-    'hubspots',
-    'twilios',
-    'filevines',
-    'docusigns',
-    'envs',
-];
+export const integrationSurfaceKeys = ['envs', 'emails'];
 true;
 //# sourceMappingURL=types.js.map

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

@@ -0,0 +1,85 @@
+/**
+ * What the platform knows of a conversation's channel, shared by the page, the engine and the pipeline.
+ */
+export type Direction = 'inbound' | 'outbound';
+/** The channels a conversation runs on. A conversation engine runs on calls and SMS (17b §9.0); email routes and stores only. */
+export declare const CHANNELS: readonly ['call', 'sms', 'email'];
+export type Channel = (typeof CHANNELS)[number];
+/**
+ * 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 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
+ * (docs/design/09-agreed-follow-up.md).
+ */
+export type ScheduledContactContext = {
+    scheduledActionId: string;
+    /** Set for an agreed follow-up: the exchange the party asked for or agreed to it in. */
+    agreedInExchangeId: string | null;
+    /** An agreed follow-up: the party's own words agreeing to it; null otherwise. */
+    customerQuote: string | null;
+    note: string | null;
+    /** When it was due, ISO 8601. */
+    scheduledFor: string;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/core/conversation/index.js

@@ -0,0 +1,133 @@
+/**
+ * What the platform knows of a conversation's channel, shared by the page, the engine and the pipeline.
+ */
+/** The channels a conversation runs on. A conversation engine runs on calls and SMS (17b §9.0); email routes and stores only. */
+export const CHANNELS = ['call', 'sms', 'email'];
+/**
+ * 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 const CONTACT_LANGUAGES = [
+    '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 const SPOKEN_LANGUAGES = ['en', 'es', 'fr', 'de', 'hi', 'ru', 'pt', 'ja', 'it', 'nl'];
+/**
+ * `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 function checkSpoken(value, at) {
+    if (typeof value === 'string')
+        throw new Error(`${at}: write it per language, { en: '…', es: '…' } (66 §2), not one string`);
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new Error(`${at}: write it per language, { en: '…', es: '…' } (66 §2)`);
+    const out = {};
+    for (const [key, text] of Object.entries(value)) {
+        if (!SPOKEN_LANGUAGES.includes(key))
+            throw new Error(`${at}: '${key}' is not a language of the platform's table (${SPOKEN_LANGUAGES.join(', ')})`);
+        if (typeof text !== 'string' || !text.trim())
+            throw new Error(`${at}: the ${key} text is empty`);
+        out[key] = text;
+    }
+    if (!Object.keys(out).length)
+        throw new Error(`${at}: write it in at least one language`);
+    return out;
+}
+/** The text a `Spoken` falls back to (66 §3): `en` when written, else the first language written. */
+export function fallbackSpoken(spoken) {
+    const texts = spoken;
+    if (texts.en)
+        return { text: texts.en, language: 'en' };
+    const [language, text] = Object.entries(texts).find(([, t]) => !!t);
+    return { text, language };
+}
+/**
+ * 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 function pickSpoken(spoken, language) {
+    const texts = spoken;
+    if (language) {
+        const exact = texts[language];
+        if (exact)
+            return { text: exact, missing: null };
+        const base = matchSpokenLanguage(language);
+        const near = base ? texts[base] : undefined;
+        if (near)
+            return { text: near, missing: null };
+    }
+    const fallback = fallbackSpoken(spoken);
+    return { text: fallback.text, missing: language && language !== fallback.language ? language : null };
+}
+/**
+ * Tags a table entry is not the fallback for (48 §2): the same base language, not understood by its
+ * speakers. Matched by language and region (`zh-HK` covers `zh-Hant-HK`); Cantonese (`yue`) is apart already.
+ */
+const NOT_FALLBACK_FOR = { zh: ['zh-HK', 'zh-MO'] };
+/** `value` as a canonical BCP-47 tag (`pt-br` → `pt-BR`), or null when it is not one. */
+export function canonicalLanguage(value) {
+    if (typeof value !== 'string' || !value.trim())
+        return null;
+    try {
+        return Intl.getCanonicalLocales(value.trim())[0] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether `value` is one of the table's tags as stored (a language calls can speak). */
+export function isSpokenLanguage(value) {
+    return typeof value === 'string' && SPOKEN_LANGUAGES.includes(value);
+}
+/** Whether `value` is a language `contact.language` can hold, as stored (texts and emails: any of them). */
+export function isContactLanguage(value) {
+    return typeof value === 'string' && CONTACT_LANGUAGES.includes(value);
+}
+/**
+ * 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 function matchSpokenLanguage(value) {
+    return matchIn(SPOKEN_LANGUAGES, value);
+}
+/** The contact language a tag resolves to, as {@link matchSpokenLanguage} (`zh-CN` → `zh`). Null: none. */
+export function matchContactLanguage(value) {
+    return matchIn(CONTACT_LANGUAGES, value);
+}
+function matchIn(tags, value) {
+    const tag = canonicalLanguage(value);
+    if (!tag)
+        return null;
+    if (tags.includes(tag))
+        return tag;
+    const locale = new Intl.Locale(tag);
+    const hit = tags.find((l) => new Intl.Locale(l).language === locale.language);
+    if (!hit)
+        return null;
+    const excluded = (NOT_FALLBACK_FOR[hit] ?? []).some((x) => {
+        const ex = new Intl.Locale(x);
+        return ex.language === locale.language && (!ex.region || ex.region === locale.region);
+    });
+    return excluded ? null : hit;
+}
+let displayNames = null;
+/** A language's name in English, for prompts (`zh` → `Chinese`); the tag itself when it has none. */
+export function languageName(tag) {
+    try {
+        displayNames ??= new Intl.DisplayNames(['en'], { type: 'language' });
+        return displayNames.of(tag) ?? tag;
+    }
+    catch {
+        return tag;
+    }
+}
+//# sourceMappingURL=index.js.map