@opencxh/domain 1.224.0 → 1.226.0

package/dist/entities/activity/types.d.ts

@@ -5,7 +5,7 @@ import { ReactionSummary } from '../reaction/types';
 export type CallStatus = "new" | "connecting" | "ringing" | "connected" | "held" | "ended" | "failed";
 export type CallDirection = "inbound" | "outbound";
 export type CallType = "audio" | "video" | "data" | "screen-share";
-export type ActivityType = "VOICE_CALL_STARTED" | "VOICE_CALL_ANSWERED" | "VOICE_CALL_HOLD" | "VOICE_CALL_UNHOLD" | "VOICE_CALL_ENDED" | "VOICE_CALL_MISSED" | "VOICE_CALL_VOICEMAIL" | "VIDEO_CALL_STARTED" | "VIDEO_CALL_ANSWERED" | "VIDEO_CALL_HOLD" | "VIDEO_CALL_UNHOLD" | "VIDEO_CALL_ENDED" | "VIDEO_CALL_MISSED" | "EMAIL_RECEIVED" | "EMAIL_SENT" | "CHAT_MESSAGE_SENT" | "CHAT_MESSAGE_RECEIVED" | "CHAT_MEMBER_JOINED" | "CHAT_MEMBER_LEFT" | "CHAT_RENAMED" | "CHAT_CALL_STARTED" | "CHAT_CALL_ENDED" | "CHAT_EVENT" | "AI_MESSAGE_ADDED" | "AI_ACTION_PROPOSED" | "PLAYBOOK_STARTED" | "PLAYBOOK_COMPLETED" | "PLAYBOOK_ESCALATED" | "MEETING_SCHEDULED" | "MEETING_STARTED" | "MEETING_ENDED" | "MEETING_PARTICIPANT_JOINED" | "MEETING_PARTICIPANT_LEFT" | "COMMENT_ADDED" | "FILE_UPLOADED" | "INTERACTION_CREATED" | "INTERACTION_STATUS_CHANGED" | "INTERACTION_ASSIGNED" | "VOICE_CALL_FAILED" | "VIDEO_CALL_FAILED" | "TRANSCRIPT_ADDED" | "WORK_COMMENT_ADDED" | "WORK_ITEM_ASSIGNED" | "WORK_ITEM_STATUS_CHANGED";
+export type ActivityType = "VOICE_CALL_STARTED" | "VOICE_CALL_ANSWERED" | "VOICE_CALL_HOLD" | "VOICE_CALL_UNHOLD" | "VOICE_CALL_ENDED" | "VOICE_CALL_MISSED" | "VOICE_CALL_VOICEMAIL" | "VIDEO_CALL_STARTED" | "VIDEO_CALL_ANSWERED" | "VIDEO_CALL_HOLD" | "VIDEO_CALL_UNHOLD" | "VIDEO_CALL_ENDED" | "VIDEO_CALL_MISSED" | "EMAIL_RECEIVED" | "EMAIL_SENT" | "CHAT_MESSAGE_SENT" | "CHAT_MESSAGE_RECEIVED" | "CHAT_MEMBER_JOINED" | "CHAT_MEMBER_LEFT" | "CHAT_RENAMED" | "CHAT_CALL_STARTED" | "CHAT_CALL_ENDED" | "CHAT_EVENT" | "AI_MESSAGE_ADDED" | "AI_ACTION_PROPOSED" | "PLAYBOOK_STARTED" | "PLAYBOOK_COMPLETED" | "PLAYBOOK_ESCALATED" | "MEETING_SCHEDULED" | "MEETING_STARTED" | "MEETING_ENDED" | "MEETING_PARTICIPANT_JOINED" | "MEETING_PARTICIPANT_LEFT" | "COMMENT_ADDED" | "FILE_UPLOADED" | "INTERACTION_CREATED" | "INTERACTION_STATUS_CHANGED" | "INTERACTION_ASSIGNED" | "SLA_BREACHED" | "VOICE_CALL_FAILED" | "VIDEO_CALL_FAILED" | "TRANSCRIPT_ADDED" | "WORK_COMMENT_ADDED" | "WORK_ITEM_ASSIGNED" | "WORK_ITEM_STATUS_CHANGED";
 export interface Attachment {
     id: string;
     filename: string;
@@ -240,6 +240,23 @@ export type InteractionStatusChangedPayload = {
     fromStatus: InteractionStatus;
     toStatus: InteractionStatus;
 };
+/**
+ * A service target that ran out. Written by the app that owns the clocks, not by comms.
+ *
+ * It is a timeline row rather than a new trigger kind on purpose: the playbook engine already
+ * triggers on activities with a JSONLogic filter, so "escalate when the SLA breaches" needs no
+ * engine change at all — and the breach is visible to a human in the same move.
+ */
+export type SlaBreachedPayload = {
+    /** `first_response`, `close`, … — an `SlaMetric`, kept as a string so domain layers stay
+     *  independent of each other. */
+    metric: string;
+    profileId: string;
+    /** Which attempt of this target; `next_response` has more than one. */
+    attempt: number;
+    /** The deadline that passed. */
+    dueAt: number;
+};
 export type InteractionAssignedPayload = {
     userId: string;
     teamId?: string;
@@ -405,6 +422,9 @@ export type Activity = (BaseActivity & {
 }) | (BaseActivity & {
     type: "INTERACTION_ASSIGNED";
     payload: InteractionAssignedPayload;
+}) | (BaseActivity & {
+    type: "SLA_BREACHED";
+    payload: SlaBreachedPayload;
 });
 /**
  * An activity of **any type at all**, including a type an app declared.

package/dist/entities/mcp/types.d.ts

@@ -166,6 +166,20 @@ export interface McpConnectorDescribe {
     /** `mcp__<id>__`, same as {@link mcpToolPrefix} — passed along so the caller computes nothing. */
     toolPrefix: string;
 }
+/**
+ * One tool of one connector, as `GET /mcp-connector/:id/tools` reports it.
+ *
+ * Its own route next to the tool catalog because the catalog cannot answer this: it drops every
+ * `personal` tool, and every entry in the connector catalog is per-user OAuth — so an app asking
+ * `GET /tools/` about an MCP server reliably gets nothing back.
+ */
+export interface McpConnectorTool {
+    /** The **bare** tool name. Compose with {@link mcpToolPrefix} to invoke it. */
+    name: string;
+    description?: string;
+    /** JSON-Schema of the arguments, straight from the server — the right-hand side of a mapping. */
+    inputSchema?: unknown;
+}
 /** Body accepted by the create/update endpoints (write shape, distinct from the read view). */
 export interface McpServerInput {
     name?: string;

package/dist/entities/playbook/trigger-vars.d.ts

@@ -57,6 +57,15 @@ export declare const TRIGGER_VARS: readonly [{
 }, {
     readonly name: "companyId";
     readonly type: "string";
+}, {
+    readonly name: "priority";
+    readonly type: "string";
+}, {
+    readonly name: "inboxId";
+    readonly type: "string";
+}, {
+    readonly name: "topicId";
+    readonly type: "string";
 }, {
     readonly name: "assigneeUserId";
     readonly type: "string";

package/dist/entities/sla/hours.d.ts

@@ -0,0 +1,7 @@
+import { SlaCalendar } from './types';
+/** Working ms between two instants. 0 when `to <= from`. `null` calendar = around the clock. */
+export declare function workingMsBetween(from: number, to: number, cal: SlaCalendar | null): number;
+/** The instant `ms` of working time after `from`. `null` calendar = around the clock. */
+export declare function addWorkingMs(from: number, ms: number, cal: SlaCalendar | null): number;
+/** `"08:30"` -> 510. Returns `null` on anything that is not `HH:MM`. */
+export declare function parseClockMinutes(value: string): number | null;

package/dist/entities/sla/hours.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/sla/index.d.ts

@@ -0,0 +1,4 @@
+export * from './hours';
+export * from './machine';
+export * from './types';
+export * from './view';

package/dist/entities/sla/machine.d.ts

@@ -0,0 +1,47 @@
+import { SlaClock, SlaMetric, SlaProfile } from './types';
+/**
+ * The nine facts a source app reports about a resource. It reports *what happened*; every
+ * decision about which clock starts, stops or pauses lives here, so a second source app
+ * (work items, later) needs an adapter and nothing else.
+ */
+export type SlaEventKind = "apply" | "answered" | "inbound" | "outbound" | "resolved" | "closed" | "reopened" | "snoozed" | "unsnoozed" | "discarded";
+/**
+ * The facts a source app may report. `apply` is excluded on purpose: attaching a profile is a
+ * user-facing decision with its own route and its own authorization, not something an app
+ * announces about its resource.
+ */
+export type SlaFact = Exclude<SlaEventKind, "apply">;
+export type SlaClockPatch = Partial<Pick<SlaClock, "state" | "settledAt" | "dueAt" | "remainingMs" | "pauseBits">>;
+export type SlaOp = {
+    op: "start";
+    metric: SlaMetric;
+    attempt: number;
+    startedAt: number;
+    targetMs: number;
+    dueAt: number;
+} | {
+    op: "patch";
+    clockId: string;
+    patch: SlaClockPatch;
+};
+export interface SlaEventInput {
+    event: SlaEventKind;
+    /**
+     * When the fact happened. Clamped to `now`: a source clock that runs ahead must not create
+     * a deadline in the past.
+     */
+    at: number;
+    now: number;
+    /** Every clock on this resource, settled ones included — `attempt` is drawn from them. */
+    clocks: SlaClock[];
+    profile: SlaProfile;
+}
+/**
+ * Turn one reported fact into the store operations it implies.
+ *
+ * Pure: no ids are minted, nothing is written. The caller applies `start` as an upsert on the
+ * unique `(organizationId, scopeKey, metric, attempt)` index and `patch` as a conditional
+ * update with the clock's current state in the *filter* — which is what makes a replayed
+ * event match zero rows instead of needing a dedupe table.
+ */
+export declare function planSlaEvent({ event, at, now, clocks, profile }: SlaEventInput): SlaOp[];

package/dist/entities/sla/machine.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/sla/types.d.ts

@@ -0,0 +1,107 @@
+import { OrgTeamScope } from '../scope/types';
+/**
+ * The five service targets, in the vocabulary the market already uses.
+ *
+ * `speed_of_answer` only means something on a live channel (voice, video): it measures
+ * arrival -> picked up. On chat and mail it would be the same moment as
+ * `first_response`, so the profile form refuses that combination.
+ */
+export type SlaMetric = "speed_of_answer" | "first_response" | "next_response" | "resolution" | "close";
+export type SlaPauseReason = "snoozed" | "waiting_for_customer";
+/**
+ * `void` is not a third way of failing — it is "this clock stopped meaning anything".
+ * A conversation closed as spam 90 seconds into a 4h first-response target is neither a
+ * hit nor a miss, and counting it as either poisons the attainment number. Same for a
+ * profile swapped mid-flight and for the losing side of a merge.
+ */
+export type SlaClockState = "running" | "paused" | "hit" | "missed" | "void";
+/** Bit values for {@link SlaClock.pauseBits}. */
+export declare const PAUSE_SNOOZED = 1;
+export declare const PAUSE_WAITING_FOR_CUSTOMER = 2;
+export declare function pauseBitFor(reason: SlaPauseReason): number;
+/**
+ * Opening hours as the clock needs them: minutes from local midnight, plus the offset to
+ * get back to UTC.
+ *
+ * `utcOffsetMinutes` is **standard** time, minutes east of UTC — the house convention
+ * (`apps/time/server/src/time_entry/logic.ts`). Summer time is a rule, not a second field,
+ * because an offset stored once is wrong for seven months of the year.
+ */
+export interface SlaCalendar {
+    /** ISO weekdays that are open, 1 = Monday. Mirrors `ProfileOpeningHours.days`. */
+    days: number[];
+    /** "08:30" -> 510 */
+    fromMinutes: number;
+    toMinutes: number;
+    utcOffsetMinutes: number;
+    dst: "none" | "eu";
+}
+export interface SlaTarget {
+    metric: SlaMetric;
+    minutes: number;
+}
+/**
+ * A named set of service targets. Assigned to a resource explicitly — from a workflow rule
+ * (`tool:context__apply_sla`) or by hand — never matched automatically. That is why there is
+ * no `appliesTo` and no `order`: both only exist to drive a matcher nothing calls.
+ */
+export interface SlaProfile {
+    id: string;
+    organizationId: string;
+    ownerScope: OrgTeamScope;
+    name: string;
+    description?: string;
+    enabled: boolean;
+    targets: SlaTarget[];
+    /**
+     * Absent or empty = around the clock. Deliberately **not** a nullable field: `invoke`
+     * strips `null` out of a body before it ever reaches the server
+     * (`packages/app-sdk/src/modules/api.ts`), so "no calendar" has to be expressible as
+     * absence. Read it through {@link calendarOf}, never directly.
+     */
+    calendar?: SlaCalendar;
+    pauseOn: SlaPauseReason[];
+}
+/**
+ * The calendar to run against: `null` means around the clock. Takes a profile or a clock —
+ * both carry the field, and the clock's copy is the one a badge should trust.
+ */
+export declare function calendarOf(source: {
+    calendar?: SlaCalendar;
+}): SlaCalendar | null;
+/**
+ * One target, one attempt. `next_response` gets a fresh row per customer message, which is
+ * why `attempt` is part of the identity: `(organizationId, scopeKey, metric, attempt)` is
+ * unique in the store, and that uniqueness is the whole idempotency story.
+ *
+ * `dueAt` goes stale while paused, on purpose — the sweeper only ever queries
+ * `state: "running"`, and a paused clock shows time remaining, not a wall-clock moment.
+ */
+export interface SlaClock {
+    id: string;
+    organizationId: string;
+    /** `"<kind>:<id>"`, e.g. `"interaction:abc"`. Both halves of the resource, one column. */
+    scopeKey: string;
+    metric: SlaMetric;
+    attempt: number;
+    profileId: string;
+    ownerScope: OrgTeamScope;
+    targetMs: number;
+    /**
+     * The calendar this clock was started against, copied from the profile.
+     *
+     * Denormalised on purpose, twice over: a badge can do its arithmetic without fetching the
+     * profile — on any client, for any resource kind — and editing a profile does not silently
+     * move the deadline of something already running. Absent = around the clock.
+     */
+    calendar?: SlaCalendar;
+    startedAt: number;
+    dueAt: number;
+    /** Working ms left at the moment of pausing. Only meaningful while `state === "paused"`. */
+    remainingMs: number;
+    pauseBits: number;
+    state: SlaClockState;
+    settledAt?: number;
+}
+export declare const SLA_METRICS: SlaMetric[];
+export declare const SLA_PAUSE_REASONS: SlaPauseReason[];

package/dist/entities/sla/view.d.ts

@@ -0,0 +1,36 @@
+import { SlaClock } from './types';
+/**
+ * What a badge needs, derived from the clocks on one resource. Pure: the same answer on the
+ * server, in the browser and on mobile.
+ */
+export declare function isOpenClock(clock: SlaClock): boolean;
+/**
+ * Working ms left. Negative once the deadline has passed.
+ *
+ * A paused clock reads its stored remainder — `dueAt` is deliberately stale then. A running one
+ * measures against the calendar, so "2 hours left" at 16:00 on a Friday means two *working*
+ * hours, which lands on Monday and is the only number that matches the deadline.
+ */
+export declare function remainingMsOf(clock: SlaClock, now: number): number;
+/** Wall-clock moment the deadline falls on, calendar included. Useful for a tooltip. */
+export declare function dueAtOf(clock: SlaClock, now: number): number;
+/**
+ * The one clock a badge should show: the open one that runs out first.
+ *
+ * Running beats paused whatever the numbers say — a paused target is not what someone has to
+ * act on, and showing it above a running one would put the least urgent thing first. Among
+ * equals, the nearest deadline.
+ */
+export declare function nextSlaClock(clocks: SlaClock[], now: number): SlaClock | undefined;
+export type SlaBadgeTone = "breached" | "urgent" | "running" | "paused" | "met";
+/**
+ * How a clock should read. `urgent` at the last fifth of the target — a proportion, not a fixed
+ * number of minutes, because "five minutes left" means something very different on a 15-minute
+ * first response than on an eight-hour resolution.
+ */
+export declare function slaBadgeTone(clock: SlaClock, now: number): SlaBadgeTone;
+/**
+ * "2u 10m", "45m", "30s". Rounded down on purpose: a target with 59 seconds left should not
+ * read "1m" — being early about a breach is worse than being blunt about it.
+ */
+export declare function formatSlaDuration(ms: number): string;

package/dist/entities/sla/view.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/work/types.d.ts

@@ -114,6 +114,11 @@ export interface WorkProject {
     lastSequence?: number;
     archived?: boolean;
     order?: number;
+    /**
+     * Ids of this project in source systems (`asana:12345`), the dedupe axis of the ingest
+     * pipeline. Empty on a project created here.
+     */
+    externalIds?: string[];
     createdBy: string;
     createdAt?: number;
     updatedAt?: number;