@opencxh/domain 1.221.0 → 1.224.0

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

@@ -99,6 +99,23 @@ export declare function channelKindOf(type: string): ActivityChannelKind | undef
 export declare function isMessageShape(shape: ActivityShape | undefined): boolean;
 /** See {@link isMessageShape}. For the built-in types. */
 export declare function isMessageType(type: string): boolean;
+/**
+ * Does an answer of this kind fold into the list under the message it answers, instead of
+ * taking its own place in the timeline?
+ *
+ * Only notes. A mail carrying a `parentId` is still a message that was really sent, at a real
+ * moment, and burying it under the thing it answered would take it out of the chronology the
+ * rest of the conversation is read in — and out of view entirely while the thread is folded.
+ * An internal note has no such life of its own: it exists *about* that message.
+ *
+ * Keyed on the shape, so the rule has exactly one definition and an app-declared note kind
+ * behaves the same — see {@link ActivityTypeRegistry.nestsUnderParent}. `parentId` itself stays
+ * set on every reply regardless: it is a true fact about the row, and mail threading, the
+ * provider `In-Reply-To` and the reply notification all read it.
+ */
+export declare function isNoteShape(shape: ActivityShape | undefined): boolean;
+/** See {@link isNoteShape}. For the built-in types. */
+export declare function nestsUnderParent(type: string): boolean;
 /** Can a human reply to it? Not to notes — those go nowhere. */
 export declare function isReplyableType(type: string): boolean;
 /**

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

@@ -70,6 +70,8 @@ export declare class ActivityTypeRegistry {
      * {@link ResolvedActivityType}.
      */
     isMessage(type: string): boolean;
+    /** Folds into the list under the message it answers. See {@link isNoteShape}. */
+    nestsUnderParent(type: string): boolean;
     /** Can a person reply to this? Notes cannot — those go nowhere. */
     isReplyable(type: string): boolean;
     /** Readable content for a model: messages, notes and transcripts. */

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

@@ -1,6 +1,7 @@
 import { ActingIdentity } from '../../platform/identity';
 import { TranscriptSegment } from '../../platform/media';
 import { AIMessageInput, AIMessageOutput } from '../ai-message/types';
+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";
@@ -34,6 +35,14 @@ export interface BaseActivity {
         contactId?: string;
     };
     direction: "inbound" | "outbound" | "internal" | "none";
+    /**
+     * The activity this one answers, if any — the in-app thread, one level deep.
+     *
+     * Not `EmailPayload.threadId`: that is the provider's own conversation id and groups a whole
+     * mail thread. This points at one activity, and an internal note can hang off a customer's
+     * mail with it. A reply to a reply stores the *top* parent, so the feed never nests twice.
+     */
+    parentId?: string;
     externalIds?: string[];
     attachments?: Attachment[];
     /**
@@ -42,6 +51,14 @@ export interface BaseActivity {
      * indicator while true.
      */
     pending?: boolean;
+    /**
+     * The emoji on this message, as the list and get routes project them.
+     *
+     * Read-only and **never stored on the activity row**: reactions are their own rows, keyed
+     * by (resource, actor, emoji), so two people reacting at once cannot race on one column.
+     * The server joins them on in one bulk query per page; a writer that sets this is ignored.
+     */
+    reactions?: ReactionSummary[];
     /** Epoch ms — matches the DB model and Interaction.createdAt. */
     createdAt?: number;
     updatedAt?: number;

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

@@ -128,17 +128,55 @@ export interface Assignment {
  *    signal it wakes on — a loop that stops only at the turn ceiling.
  * 3. **The agent is mentioned**: wakes, whatever it is waiting on. A mention is the explicit answer
  *    to the question the engine cannot answer itself: *is this addressed to my agent?*
- * 4. **An internal note while it waits for a reply** (`waitingOn === "reply"`): wakes. If an agent
+ * 4. **An answer in the agent's own thread**: wakes, whatever it is waiting on. A note hanging
+ *    under the message the agent itself wrote is as addressed to it as its name would be — more
+ *    so, really: you had to aim at that message to write it. This is the case the mention rule
+ *    was standing in for before threads existed, and it deliberately widens the earlier choice
+ *    that a mention stays required while waiting on a task. Only for its *own* thread: a reply
+ *    under a colleague's note is two people talking, and still costs no turn.
+ * 5. **An internal note while it waits for a reply** (`waitingOn === "reply"`): wakes. If an agent
  *    explicitly asked for an answer, the next thing a colleague writes *is* that answer; forcing
  *    someone to @-mention their own agent on the question it just asked is a ritual, not a signal.
  *    The worry it replaces ("two colleagues conferring cost a turn each") stays covered by the
- *    edge: `waitingOn` has to be `"reply"`, and once it waits on a task or is still busy, a mention
- *    is again the only way in.
+ *    edge: `waitingOn` has to be `"reply"`, and once it waits on a task or is still busy, a
+ *    mention or its own thread is again the only way in.
  *
  * @param waitingOn What the assignment waits on. Omitted = rules 1-3 only, so a caller that does
  *                  not know never wakes too eagerly.
+ * @param parentAuthorId Who wrote the activity this one answers, when it answers one. Resolved by
+ *                  the caller: the activity carries only `parentId`, and this function stays pure.
  */
-export declare function wakesAssignment(activity: FeedActivity, agentId: string, waitingOn?: WaitingOn["on"]): boolean;
+export declare function wakesAssignment(activity: FeedActivity, agentId: string, waitingOn?: WaitingOn["on"], parentAuthorId?: string): boolean;
+/**
+ * Does this reaction wake an assignment?
+ *
+ * A reaction is the cheapest possible answer: the agent asks "shall I send this?" and you put
+ * a ✅ on it without typing a word. That is worth having, because the alternative — typing
+ * "ja" and @-mentioning your own agent — is the friction that makes people not answer at all.
+ *
+ * **Its own function, not a rule inside {@link wakesAssignment}.** A reaction is not a
+ * `FeedActivity` and never becomes one: activities are real rows on a timeline, and
+ * manufacturing a fake one to reuse a signature would put a lie in the feed's own vocabulary.
+ *
+ * **Three gates, all narrow.** It must be a reaction that was *put there* (taking one away
+ * answers nothing); it must sit on a message this agent itself wrote (that is what makes it
+ * addressed — a reaction on a colleague's note is between colleagues); and the reactor must
+ * not be the agent. `waitingOn` does not come into it: the same standing as a mention, because
+ * the aiming is just as explicit.
+ *
+ * Which emoji it is, deliberately does not matter here. There is no 👍-means-yes table: the
+ * turn is told which emoji and from whom, and reading that is what a model is for. A fixed
+ * set would be a configuration that differs per team and grows by commit.
+ */
+export declare function reactionWakesAssignment(input: {
+    /** The author of the activity that was reacted on. Only a `user` author can be an agent. */
+    targetAuthorId?: string;
+    /** Who reacted. */
+    reactorId?: string;
+    agentId: string;
+    /** `true` put it there, `false` took it away. */
+    on: boolean;
+}): boolean;
 /** The subject of an assignment as one reference, or `undefined`. */
 export declare function assignmentSubject(assignment: {
     subjectKind?: string;

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

@@ -0,0 +1 @@
+export * from './types';

package/dist/entities/reaction/summarize.test.d.ts

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

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

@@ -0,0 +1,98 @@
+/**
+ * Who reacted.
+ *
+ * Not a bare `userId`, and not `MutationAuthor`: a reaction can come from outside the
+ * organisation. A Teams chat is synced with the customer in it, and their 👍 has to land
+ * somewhere — as a `contact`, with the name the provider gave. Mirrors `BaseActivity.author`,
+ * which already carries that same four-way distinction.
+ *
+ * `id` is the user id, the app name, or the provider's id for a contact; absent for `system`.
+ */
+export interface ReactionActor {
+    type: "user" | "contact" | "app" | "system";
+    id?: string;
+    /** Shown on hover. Kept on the row because an external reactor has no record to look up. */
+    name?: string;
+}
+/**
+ * One emoji, put on one resource, by one actor.
+ *
+ * Addressed by (resourceType, resourceId) — the same `ResourceRef` shape read-state and the
+ * attribute store use — so an activity, a work comment, a file or a knowledge article all
+ * reuse this without the store learning what any of them are.
+ *
+ * A row per (resource, actor, emoji), never an array on the resource: two people reacting at
+ * the same moment would otherwise race on one column, and the unique index makes both the
+ * toggle and a re-sync from a provider idempotent.
+ */
+export interface Reaction {
+    id: string;
+    organizationId: string;
+    resourceType: string;
+    resourceId: string;
+    actor: ReactionActor;
+    /**
+     * The literal character, e.g. `"👍"` — never a shortcode and never a provider's name for it.
+     * One vocabulary means no mapping table in the core; the six legacy Teams names are
+     * translated at the edge, in the app that speaks to Graph.
+     */
+    emoji: string;
+    createdAt?: number;
+}
+/** One chip: an emoji, how many put it there, and who — for the hover. */
+export interface ReactionSummary {
+    emoji: string;
+    count: number;
+    actors: ReactionActor[];
+}
+/** `POST /reaction/:type/:id` body. `on` absent means "flip whatever it is now". */
+export interface ToggleReactionRequest {
+    emoji: string;
+    on?: boolean;
+    /**
+     * Who to record it for, instead of the caller.
+     *
+     * **Honoured for an app-to-app caller only**, and ignored outright for a user — otherwise
+     * anyone could put an emoji on a message in a colleague's name. It exists for provider
+     * sync: a reaction pulled out of Teams belongs to the person who left it there, not to the
+     * app that carried it across.
+     */
+    actor?: ReactionActor;
+}
+/** Reactions per resource id, as the list endpoints hand them to a feed. */
+export type ReactionsByResource = Record<string, ReactionSummary[]>;
+/** The one thing that just happened, as opposed to the state that resulted from it. */
+export interface ReactionChange {
+    emoji: string;
+    actor: ReactionActor;
+    /** `true` put it there, `false` took it away. */
+    on: boolean;
+}
+/**
+ * The `reactions:changed` event, as apps receive it (`communication:reactions:changed`).
+ *
+ * Carries **both** the resulting chip set and the delta, because the two consumers need
+ * different things. A feed re-renders from `reactions` — a client that only got deltas and
+ * missed one would keep a wrong count forever. A server-side listener needs `change`: "who
+ * just did what" cannot be derived from a state it never saw the previous version of.
+ *
+ * `organizationId` rides along because an event handler has no request: every other
+ * subscriber in this platform reads the tenant from the payload and gives up without it.
+ */
+export interface ReactionsChangedEvent {
+    organizationId: string;
+    resourceType: string;
+    resourceId: string;
+    reactions: ReactionSummary[];
+    change: ReactionChange;
+}
+/**
+ * Rows to chips.
+ *
+ * Most-used first so the chip that carries the most agreement sits nearest the message, with
+ * ties broken by which emoji appeared first — a stable order, so a chip does not jump when
+ * someone else reacts. Pure: this is the one piece of the feature worth a test.
+ */
+export declare function summarizeReactions(rows: Reaction[]): ReactionSummary[];
+/** Did this user put this emoji there? The chip's own state, asked without a second query. */
+export declare function hasReacted(summary: ReactionSummary, userId: string | undefined): boolean;

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

@@ -1,3 +1,4 @@
+import { ReactionSummary } from '../reaction/types';
 import { WorkStatusCategory } from './types';
 /**
  * The activity feed under a work item.
@@ -36,6 +37,8 @@ export interface WorkActivity {
      * "the customer answered" and would wake every waiting assignment on the item.
      */
     direction: "internal";
+    /** The activity this one answers — same one-level thread as comms' `BaseActivity.parentId`. */
+    parentId?: string;
     /** `html` is the composer's markup for a comment; `text` stays the plain reading of it. */
     payload: {
         text?: string;
@@ -46,6 +49,12 @@ export interface WorkActivity {
         toStatus?: string;
         toCategory?: WorkStatusCategory;
     };
+    /**
+     * The emoji on this comment, as the list route projects them. Read-only and never stored
+     * on the row — see `BaseActivity.reactions`, which this mirrors, and the generic store in
+     * the communication app that both read from.
+     */
+    reactions?: ReactionSummary[];
     createdAt?: number;
     updatedAt?: number;
 }

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

@@ -10,8 +10,17 @@ import { WorkItem, WorkProject } from './types';
 /** The scope kinds `apps/work` claims through `/provider/scope/describe`. */
 export declare const WORK_ITEM_SCOPE_KIND = "work_item";
 export declare const WORK_PROJECT_SCOPE_KIND = "work_project";
+/**
+ * A row in an item's feed, addressable on its own.
+ *
+ * Claimed so the generic stores can hang something off a single comment — reactions today,
+ * whatever is resource-agnostic tomorrow. It inherits its item's access exactly the way
+ * comms' `activity:` inherits its conversation's: a comment is not a second boundary.
+ */
+export declare const WORK_ACTIVITY_SCOPE_KIND = "work_activity";
 export declare function workItemScopeKey(itemId: string): string;
 export declare function workProjectScopeKey(projectId: string): string;
+export declare function workActivityScopeKey(activityId: string): string;
 /**
  * The human key: `SAL-142`, or `SAL-142-1` for a subitem.
  *