@superpanel-sdk/runtime 0.2.3 → 0.7.0

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

@@ -0,0 +1,244 @@
+/** The wall-clock parts of an instant in `timezone`, from one formatter (plus its UTC offset when asked). */
+function localParts(at, timezone, withOffset = false) {
+    const parts = Object.fromEntries(new Intl.DateTimeFormat('en-US', {
+        timeZone: timezone,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        ...(withOffset ? { timeZoneName: 'longOffset' } : {}),
+    })
+        .formatToParts(at)
+        .map((part) => [part.type, part.value]));
+    return parts;
+}
+/** `YYYY-MM-DD` of an instant in `timezone`. */
+export function localDay(at, timezone) {
+    const parts = localParts(new Date(at), timezone);
+    return `${parts.year}-${parts.month}-${parts.day}`;
+}
+/** `YYYY-MM-DD HH:mm:ss` of an instant in `timezone`. */
+export function localDateTime(at, timezone) {
+    const parts = localParts(new Date(at), timezone);
+    return `${parts.year}-${parts.month}-${parts.day} ${parts.hour}:${parts.minute}:${parts.second}`;
+}
+/** ISO 8601 in `timezone` with its UTC offset, e.g. `2026-10-09T06:25:00-04:00`: a time that names its own zone. */
+export function zonedIso(at, timezone) {
+    const parts = localParts(new Date(at), timezone, true);
+    const name = parts.timeZoneName ?? 'GMT';
+    const offset = name === 'GMT' ? '+00:00' : name.replace('GMT', '');
+    return `${parts.year}-${parts.month}-${parts.day}T${parts.hour}:${parts.minute}:${parts.second}${offset}`;
+}
+/** `Current local time: 2026-10-08 10:05:00, Thursday, and October has 31 days`. */
+function renderLocalClock(now, timezone) {
+    const parts = localParts(now, timezone);
+    const weekday = new Intl.DateTimeFormat('en-US', { timeZone: timezone, weekday: 'long' }).format(now);
+    const month = new Intl.DateTimeFormat('en-US', { timeZone: timezone, month: 'long' }).format(now);
+    const daysInMonth = new Date(Date.UTC(Number(parts.year), Number(parts.month), 0)).getUTCDate();
+    return `Current local time: ${localDateTime(now, timezone)}, ${weekday}, and ${month} has ${daysInMonth} days`;
+}
+function todayCounts(today) {
+    return `calls ${today.calls} (answered ${today.answeredCalls}), sms out ${today.smsOut}, sms in ${today.smsIn}, emails out ${today.emailsOut}, emails in ${today.emailsIn}`;
+}
+/** One party: `Today is [day 3]` and today's counts. */
+function partyActivitySummary(party) {
+    return `Today is [day ${party.dayNumber}]\nToday so far: ${todayCounts(party.today)}`;
+}
+/** The whole case: the Case day and today's counts. */
+function caseActivitySummary(activity) {
+    const { all, timezone } = activity;
+    const since = all.firstAt ? `day 1 = ${localDay(all.firstAt, timezone)}, ${timezone}` : 'no interactions yet';
+    return `Case day: [day ${all.dayNumber}] (${since})\nCase today so far: ${todayCounts(all.today)}`;
+}
+const WEEKDAYS = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'];
+const WEEKDAY_NAMES = { mon: 'Mon', tue: 'Tue', wed: 'Wed', thu: 'Thu', fri: 'Fri', sat: 'Sat', sun: 'Sun' };
+/** `09:00-12:00, 14:00-17:00`, or `none`. */
+function hoursText(windows) {
+    return windows.length > 0 ? windows.map((window) => `${window.start}-${window.end}`).join(', ') : 'none';
+}
+/**
+ * The party's own contact hours (their `contact_schedule`), in their timezone: a line per weekday
+ * (`every day` when all are the same), then one per date that differs. None on file: one line saying
+ * so. The company's rules for when to reach them are its own (25 §3), not shown here.
+ */
+function partyContactHours(party) {
+    const { source, weekly, dateOverrides } = party.contactHours;
+    if (source === 'none')
+        return "Customer's own contact hours: none on file.";
+    const days = WEEKDAYS.map((day) => hoursText(weekly[day]));
+    const sameEveryDay = days.every((text) => text === days[0]);
+    return [
+        "Customer's own contact hours (from their contact schedule; reach them only inside these):",
+        ...(sameEveryDay ? [`- every day: ${days[0]}`] : WEEKDAYS.map((day, i) => `- ${WEEKDAY_NAMES[day]}: ${days[i]}`)),
+        ...dateOverrides.map((override) => `- ${override.date} only: ${hoursText(override.windows)}`),
+    ].join('\n');
+}
+const CHANNEL_ORDER = ['sms', 'email', 'call'];
+function unavailableReason(channel, availability) {
+    const reason = availability.unavailableChannels[channel];
+    if (reason === 'opted_out')
+        return ' (opted out)';
+    if (reason === 'unreachable')
+        return ' (the number cannot take texts)';
+    if (reason === 'no_address')
+        return channel === 'email' ? ' (no email address on file)' : ' (no phone number on file)';
+    return '';
+}
+/** `sms: true` per channel; an unavailable one says why. */
+function partyChannelAvailability(availability) {
+    return CHANNEL_ORDER.map((channel) => availability.channels[channel]
+        ? `${channel}: true`
+        : `${channel}: false${unavailableReason(channel, availability)}`).join('\n');
+}
+/** ` [13s]` for a call whose length is known. */
+function duration(event) {
+    return event.durationSec === null ? '' : ` [${event.durationSec}s]`;
+}
+function describeEvent(event) {
+    if (event.channel === 'call') {
+        const result = event.result === 'answered' ? 'answered' : event.result === 'failed' ? 'failed' : 'no answer';
+        return `call [${event.direction}] [${result}]${duration(event)}`;
+    }
+    if (event.direction === 'inbound')
+        return `${event.channel} [customer] [reply]`;
+    return `${event.channel} [agent] [${event.result === 'failed' ? 'failed' : 'follow-up'}]`;
+}
+/** Events grouped by day: `[day N] [YYYY-MM-DD]:`, then `[YYYY-MM-DD HH:mm:ss] <event> exchangeId …`. */
+function partyTimeline(party, options = {}) {
+    let events = party.recent;
+    if (options.sinceDays !== undefined) {
+        const firstDay = party.dayNumber - options.sinceDays + 1;
+        events = events.filter((event) => event.dayNumber >= firstDay);
+    }
+    if (options.limit !== undefined)
+        events = events.slice(-options.limit);
+    const hidden = party.total > events.length;
+    if (events.length === 0) {
+        return party.total === 0
+            ? 'No interactions found.'
+            : 'No interactions in this range. Earlier exchanges are not shown; use searchExchanges for them.';
+    }
+    const days = [];
+    let current = null;
+    let lines = [];
+    const flush = () => {
+        if (lines.length > 0)
+            days.push(lines.join('\n'));
+        lines = [];
+    };
+    for (const event of events) {
+        if (event.dayNumber !== current) {
+            flush();
+            current = event.dayNumber;
+            lines.push(`[day ${event.dayNumber}] [${localDay(event.occurredAt, party.timezone)}]:`);
+        }
+        const scheduled = event.scheduledActionId ? ` scheduledActionId ${event.scheduledActionId}` : '';
+        lines.push(`[${localDateTime(event.occurredAt, party.timezone)}] ${describeEvent(event)} exchangeId ${event.exchangeId}${scheduled}`);
+    }
+    flush();
+    const text = days.join('\n\n');
+    return hidden ? `${text}\n\nEarlier exchanges are not shown; use searchExchanges for them.` : text;
+}
+/** ` [agreed in <exchangeId> at <local time of the party's message>]` on an agreed follow-up. */
+function agreedMark(action, timezone) {
+    const agreement = action.input.agreement;
+    return agreement ? ` [agreed in ${agreement.exchangeId} at ${localDateTime(agreement.agreedAt, timezone)}]` : '';
+}
+/**
+ * `- <id>: <kind> at <local time> [agreed in …] (<note or reason>) {"timing":…}`; an agreed
+ * follow-up is marked, scheduled slot writes say why and carry their `writes`, a hand-over names its
+ * sequence, a wake-up its name. `(none)` when empty.
+ */
+function pendingActions(actions, timezone) {
+    if (actions.length === 0)
+        return '(none)';
+    return actions
+        .map((action) => {
+        const head = `- ${action.id}: ${action.kind} at ${localDateTime(action.scheduledFor, timezone)}`;
+        const why = action.reason ? ` (${action.reason})` : '';
+        if (action.kind === 'update_slots') {
+            const { timing, writes } = action.input;
+            return `${head}${why} ${JSON.stringify({ timing, writes })}`;
+        }
+        if (action.kind === 'next_sequence') {
+            const { timing, sequence, subjectRecordId } = action.input;
+            return `${head}${why} ${JSON.stringify({ timing, sequence, ...(subjectRecordId ? { subjectRecordId } : {}) })}`;
+        }
+        if (action.kind === 'wake') {
+            const { timing } = action.input;
+            const name = action.name;
+            return `${head} ${name}${why} ${JSON.stringify({ timing })}`;
+        }
+        const { timing } = action.input;
+        return `${head}${agreedMark(action, timezone)}${why} ${JSON.stringify({ timing })}`;
+    })
+        .join('\n');
+}
+/**
+ * Why the Run woke up when nothing happened in a conversation (25 §6): each `timer` (a wake-up the
+ * Orchestrator booked) and `external` trigger (company code's `instances.notify`), as
+ * `- timer <name> at <local time> (<note>)` / `- external <reason> at <local time>`.
+ * `(none)` when there are none.
+ */
+function wakeUps(triggers, timezone) {
+    const lines = triggers.flatMap((trigger) => {
+        const at = localDateTime(trigger.occurredAt, timezone);
+        if (trigger.type === 'timer')
+            return [`- timer ${trigger.name} at ${at}${trigger.note ? ` (${trigger.note})` : ''}`];
+        if (trigger.type === 'external')
+            return [`- external ${trigger.reason} at ${at}`];
+        if (trigger.type === 'inbound.paused')
+            return [`- inbound ${trigger.channel} ${trigger.exchangeId} at ${at}, not answered: the case was paused`];
+        if (trigger.type === 'scheduled_action.ended') {
+            return [`- scheduled ${trigger.kind} ${trigger.scheduledActionId} at ${at}: ${trigger.outcome === 'not_sent' ? `not sent (${trigger.reason ?? 'decided'})` : 'slots written'}`];
+        }
+        return [];
+    });
+    return lines.length > 0 ? lines.join('\n') : '(none)';
+}
+/**
+ * Finished agreed follow-ups: `- <id>: <kind> at <local time> [agreed in …], <status> at <local time> (<note>)`,
+ * the second time being when it finished. `(none)` when empty.
+ */
+function recentAgreedActions(actions, timezone) {
+    if (actions.length === 0)
+        return '(none)';
+    return actions
+        .map((action) => `- ${action.id}: ${action.kind} at ${localDateTime(action.scheduledFor, timezone)}${agreedMark(action, timezone)}, ${action.status} at ${localDateTime(action.finishedAt, timezone)}${action.reason ? ` (${action.reason})` : ''}`)
+        .join('\n');
+}
+/**
+ * One exchange's words (a `readExchange` result): a head line naming it, then
+ * `[YYYY-MM-DD HH:mm:ss] customer|rep: <text>` per entry, in `timezone`.
+ */
+function conversation(result, timezone, options = {}) {
+    const entries = options.limit !== undefined ? result.entries.slice(-options.limit) : result.entries;
+    const party = result.contactId ? ` with customer ${result.contactId}` : '';
+    const head = `${result.channel} [${result.direction}] exchangeId ${result.exchangeId}${party}:`;
+    if (entries.length === 0)
+        return `${head}\n(nothing was said)`;
+    const earlier = result.range.from > 0 || entries.length < result.entries.length ? 'Earlier entries are not shown.\n' : '';
+    const lines = entries.map((entry) => `[${localDateTime(entry.at, timezone)}] ${entry.speaker === 'party' ? 'customer' : 'rep'}: ${entry.text}`);
+    return `${head}\n${earlier}${lines.join('\n')}`;
+}
+/**
+ * Text for company code to show or log (docs/design/08-case-orchestrator.md §5.3), in the mars next-step
+ * format. Party functions take one contact's activity (`activity.byContact[contactId]`) and
+ * write its local wall-clock times.
+ */
+export const render = {
+    localClock: renderLocalClock,
+    activitySummary: partyActivitySummary,
+    caseActivitySummary,
+    contactHours: partyContactHours,
+    channelAvailability: partyChannelAvailability,
+    timeline: partyTimeline,
+    pendingActions,
+    recentAgreedActions,
+    wakeUps,
+    conversation,
+};
+//# sourceMappingURL=render.js.map

package/dist/core/case-orchestrator/time.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Picking a time for a contact in company code (25 §4): the platform runs an action at its `at`,
+ * exactly, so spreading contacts is the code's own choice. Part of the company API (`src/index.ts`),
+ * bundled into company code as is: no imports.
+ */
+/**
+ * A time in [`from`, `to`) (each a Date, ISO string or epoch ms), as an ISO string for `at`. With `seed` the same seed always gives the same
+ * time (a Run that is retried books the same moment); without one it is random.
+ */
+export declare function randomTimeBetween(from: Date | string | number, to: Date | string | number, seed?: string): string;
+//# sourceMappingURL=time.d.ts.map

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

@@ -0,0 +1,29 @@
+/**
+ * Picking a time for a contact in company code (25 §4): the platform runs an action at its `at`,
+ * exactly, so spreading contacts is the code's own choice. Part of the company API (`src/index.ts`),
+ * bundled into company code as is: no imports.
+ */
+/** A 32-bit FNV-1a hash of `text`, as a fraction in [0, 1). */
+function fraction(text) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i += 1) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash / 2 ** 32;
+}
+/**
+ * A time in [`from`, `to`) (each a Date, ISO string or epoch ms), as an ISO string for `at`. With `seed` the same seed always gives the same
+ * time (a Run that is retried books the same moment); without one it is random.
+ */
+export function randomTimeBetween(from, to, seed) {
+    const start = new Date(from).getTime();
+    const end = new Date(to).getTime();
+    if (!Number.isFinite(start) || !Number.isFinite(end))
+        throw new Error('randomTimeBetween: from and to must be times');
+    if (end <= start)
+        throw new Error('randomTimeBetween: to must be later than from');
+    const share = seed === undefined ? Math.random() : fraction(seed);
+    return new Date(start + Math.floor(share * (end - start))).toISOString();
+}
+//# sourceMappingURL=time.js.map