@iveri/contracts 0.7.0 → 0.9.0

package/dist/esm/api/unibox/conversation-status.enum.js

@@ -0,0 +1,40 @@
+/**
+ * Where one conversation is in an agent's working day.
+ *
+ * These are **workflow** states, not delivery states — nothing here says whether a message
+ * reached anyone. `MessageStatus` answers that, and conflating the two is how an inbox ends up
+ * showing a conversation as "failed".
+ *
+ * There is deliberately no `ARCHIVED`. Closing is already the "I am done with this" state, and a
+ * second one just moves the question of which list a conversation belongs in from the filter to
+ * the operator.
+ */
+export var ConversationStatus;
+(function (ConversationStatus) {
+    /** Needs a human. The default for anything with an unanswered inbound message. */
+    ConversationStatus["OPEN"] = "open";
+    /**
+     * Answered, waiting on the contact.
+     *
+     * Distinct from `OPEN` because an inbox sorted only by "has unread" hides the conversations
+     * an agent is actually running. A new inbound message moves this back to `OPEN`.
+     */
+    ConversationStatus["PENDING"] = "pending";
+    /**
+     * Deliberately out of sight until `snoozedUntil`.
+     *
+     * The only status carrying a time. It exists because "I will deal with this on Monday" is
+     * otherwise expressed by closing something that is not finished, and a closed conversation is
+     * one nobody looks at again.
+     */
+    ConversationStatus["SNOOZED"] = "snoozed";
+    /**
+     * Finished. Reopened automatically by a new inbound message.
+     *
+     * That automatic reopen is the important half: a contact replying to a closed conversation is
+     * continuing it, and starting a second thread would split one person's history across two
+     * rows for no reason a customer would recognise.
+     */
+    ConversationStatus["CLOSED"] = "closed";
+})(ConversationStatus || (ConversationStatus = {}));
+//# sourceMappingURL=conversation-status.enum.js.map

package/dist/esm/api/unibox/conversation-status.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-status.enum.js","sourceRoot":"","sources":["../../../../src/api/unibox/conversation-status.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,CAAN,IAAY,kBA6BX;AA7BD,WAAY,kBAAkB;IAC1B,kFAAkF;IAClF,mCAAa,CAAA;IAEb;;;;;OAKG;IACH,yCAAmB,CAAA;IAEnB;;;;;;OAMG;IACH,yCAAmB,CAAA;IAEnB;;;;;;OAMG;IACH,uCAAiB,CAAA;AACrB,CAAC,EA7BW,kBAAkB,KAAlB,kBAAkB,QA6B7B"}

package/dist/esm/api/unibox/conversation.type.d.ts

@@ -0,0 +1,134 @@
+import type { CursorPage } from '../../type/cursor-page.type.js';
+import type { IsoDateTime } from '../../type/iso-date-time.type.js';
+import type { Nullable } from '../../type/nil.type.js';
+import type { UUID } from '../../type/uuid.type.js';
+import type { ChannelPlatform } from './channel-platform.enum.js';
+import type { ConversationStatus } from './conversation-status.enum.js';
+import type { Message } from './message.type.js';
+/**
+ * One thread between a tenant and a contact, on one channel.
+ *
+ * **One open conversation per `(channel, contact)`, never more.** A second one would split a
+ * person's history in half at the exact moment two agents are both replying, and the customer
+ * would see one conversation while the inbox showed two. A closed conversation reopens on the
+ * next inbound message rather than a new row being created, for the same reason.
+ *
+ * The denormalized fields below — `contactDisplayName`, `lastMessagePreview`, `unreadCount` — are
+ * here because an inbox list renders fifty of these at once and joining to messages for each one
+ * is the query that makes the product feel slow. They are maintained in the same transaction as
+ * the message that changes them, so they cannot drift.
+ */
+export interface Conversation {
+    id: UUID;
+    channelId: UUID;
+    /** Snapshotted so the list renders without a join. */
+    channelKey: string;
+    platform: ChannelPlatform;
+    contactId: UUID;
+    contactDisplayName: string;
+    status: ConversationStatus;
+    /** The agent responsible. Null means unassigned, which is a queue an inbox filters on. */
+    assigneeUserId: Nullable<UUID>;
+    /** The team it was routed to, if any. Independent of the assignee. */
+    teamId: Nullable<UUID>;
+    /**
+     * Messages the contact sent that no agent has opened.
+     *
+     * Per conversation, not per agent. A shared inbox is shared: two agents looking at the same
+     * queue should see the same numbers, and per-agent unread counts turn "has anyone dealt with
+     * this" into a question the UI cannot answer.
+     */
+    unreadCount: number;
+    /** First ~200 characters of the last message, for the list. Null on an empty conversation. */
+    lastMessagePreview: Nullable<string>;
+    /** Sorts the inbox. Null only for a conversation created before its first message. */
+    lastMessageAt: Nullable<IsoDateTime>;
+    /** When the contact last said something. Drives "waiting on us" without reading the messages. */
+    lastInboundAt: Nullable<IsoDateTime>;
+    /** Set only while `SNOOZED`. The conversation returns to `OPEN` at this time. */
+    snoozedUntil: Nullable<IsoDateTime>;
+    /**
+     * When a human took over from the AI, and who.
+     *
+     * §12 makes handover a launch requirement, and these two fields are what make it a fact rather
+     * than a convention: once set, `unibox-ai` must not answer in this conversation again. Nothing
+     * writes them from an AI side yet, and the guarantee is the same either way — the flag is what
+     * a future agent loop reads, and it exists before there is a loop to read it.
+     */
+    handedOverAt: Nullable<IsoDateTime>;
+    handedOverToUserId: Nullable<UUID>;
+    closedAt: Nullable<IsoDateTime>;
+    createdAt: IsoDateTime;
+    updatedAt: IsoDateTime;
+}
+/** One conversation with the head of its thread, for a detail view that opens in one request. */
+export interface ConversationWithMessages {
+    conversation: Conversation;
+    /** Newest first, same order as `MessagesPage`. */
+    messages: Message[];
+    /** Cursor for the next (older) page, or null when the thread is fully loaded. */
+    nextCursor: Nullable<string>;
+}
+/** `GET /api/v1/conversations`. Cursor-paged — this is the busiest list in the product. */
+export type ConversationsPage = CursorPage<Conversation>;
+/**
+ * Query for `GET /api/v1/conversations` — the inbox itself.
+ *
+ * Every filter is optional and they compose with AND. `assigneeUserId` accepting the literal
+ * `'unassigned'` is the one piece of overloading here, and it earns its place: "nobody has picked
+ * this up" is the single most-used view in a shared inbox, and expressing it as a separate boolean
+ * would make it silently combine with an assignee filter that contradicts it.
+ */
+export interface GetConversationsQuery {
+    limit?: number;
+    /** Opaque cursor from the previous page's `nextCursor`. Never parse it. */
+    after?: Nullable<string>;
+    status?: Nullable<ConversationStatus>;
+    /** A user id, or `'unassigned'`. */
+    assigneeUserId?: Nullable<string>;
+    teamId?: Nullable<UUID>;
+    channelId?: Nullable<UUID>;
+    platform?: Nullable<ChannelPlatform>;
+    /** Only conversations with at least one unread inbound message. */
+    hasUnread?: Nullable<boolean>;
+    /** Case-insensitive substring of the contact's display name. */
+    search?: Nullable<string>;
+}
+/**
+ * `PATCH /api/v1/conversations/:id/status`.
+ *
+ * Its own endpoint rather than a field on a general update, because a status change is an event
+ * with side effects — closing stamps `closedAt` and writes a system message, snoozing schedules a
+ * reopen — and folding it into a PATCH that also renames things makes those side effects a
+ * surprise.
+ */
+export interface UpdateConversationStatusBody {
+    status: ConversationStatus;
+    /** Required when `status` is `snoozed`, refused otherwise. Must be in the future. */
+    snoozedUntil?: Nullable<IsoDateTime>;
+}
+/**
+ * `PATCH /api/v1/conversations/:id/assignee`.
+ *
+ * `null` unassigns, which is a deliberate act and not the absence of one — hence a body with an
+ * explicitly nullable field rather than an optional one. Assigning to a user who is not an active
+ * member of the tenant is refused: identity is the authority on who exists, and an inbox that can
+ * assign work to a removed employee is an inbox with invisible work in it.
+ */
+export interface UpdateConversationAssigneeBody {
+    assigneeUserId: Nullable<UUID>;
+    /** Set the routing team at the same time. Omit to leave it alone; `null` clears it. */
+    teamId?: Nullable<UUID>;
+}
+/**
+ * `POST /api/v1/conversations/:id/handover` — a human takes over.
+ *
+ * Idempotent: taking over a conversation already handed over to you is a no-op rather than an
+ * error, because the button will be pressed twice and the second press must not read as a failure.
+ * Taking over one handed to *somebody else* reassigns it and says so in the thread.
+ */
+export interface HandoverConversationBody {
+    /** Defaults to the caller. Naming someone else is a handover *to* them. */
+    userId?: Nullable<UUID>;
+}
+//# sourceMappingURL=conversation.type.d.ts.map

package/dist/esm/api/unibox/conversation.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.type.d.ts","sourceRoot":"","sources":["../../../../src/api/unibox/conversation.type.ts"],"names":[],"mappings":"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"}

package/dist/esm/api/unibox/conversation.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=conversation.type.js.map

package/dist/esm/api/unibox/conversation.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.type.js","sourceRoot":"","sources":["../../../../src/api/unibox/conversation.type.ts"],"names":[],"mappings":""}

package/dist/esm/api/unibox/index.d.ts

@@ -0,0 +1,13 @@
+export * from './canned-reply.type.js';
+export * from './channel-platform.enum.js';
+export * from './channel.type.js';
+export * from './contact.type.js';
+export * from './conversation-status.enum.js';
+export * from './conversation.type.js';
+export * from './message-author-type.enum.js';
+export * from './message-content-type.enum.js';
+export * from './message-direction.enum.js';
+export * from './message-status.enum.js';
+export * from './message.type.js';
+export * from './team.type.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/api/unibox/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/unibox/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC;AACvC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC"}

package/dist/esm/api/unibox/index.js

@@ -0,0 +1,13 @@
+export * from './canned-reply.type.js';
+export * from './channel-platform.enum.js';
+export * from './channel.type.js';
+export * from './contact.type.js';
+export * from './conversation-status.enum.js';
+export * from './conversation.type.js';
+export * from './message-author-type.enum.js';
+export * from './message-content-type.enum.js';
+export * from './message-direction.enum.js';
+export * from './message-status.enum.js';
+export * from './message.type.js';
+export * from './team.type.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/api/unibox/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/api/unibox/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC;AACvC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC"}

package/dist/esm/api/unibox/message-author-type.enum.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Who produced a message.
+ *
+ * `AI` is a member here even though `unibox-ai` is build-order step 9 and does not exist. That is
+ * not speculation — it is the field an agent taking over mid-conversation reads to know what the
+ * customer has already been told, and §12 makes human handoff a launch requirement rather than a
+ * v2 feature. Adding the member later would mean every message written before it was added is
+ * indistinguishable from a human's, retroactively and unfixably.
+ */
+export declare enum MessageAuthorType {
+    /** The person on the other end. `authorUserId` is null. */
+    CONTACT = "contact",
+    /** A human agent. `authorUserId` names them. */
+    AGENT = "agent",
+    /**
+     * The AI agent. Reserved for `unibox-ai`; nothing writes it yet.
+     *
+     * Distinct from `AGENT` because "did a person say this?" is the question a human asks before
+     * taking over, and because a customer who later asks whether they were talking to a bot
+     * deserves an answer the data can actually give.
+     */
+    AI = "ai",
+    /** Unibox itself — assignment changes, status changes. Always `INTERNAL`. */
+    SYSTEM = "system"
+}
+//# sourceMappingURL=message-author-type.enum.d.ts.map

package/dist/esm/api/unibox/message-author-type.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-author-type.enum.d.ts","sourceRoot":"","sources":["../../../../src/api/unibox/message-author-type.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,oBAAY,iBAAiB;IACzB,2DAA2D;IAC3D,OAAO,YAAY;IAEnB,gDAAgD;IAChD,KAAK,UAAU;IAEf;;;;;;OAMG;IACH,EAAE,OAAO;IAET,6EAA6E;IAC7E,MAAM,WAAW;CACpB"}

package/dist/esm/api/unibox/message-author-type.enum.js

@@ -0,0 +1,27 @@
+/**
+ * Who produced a message.
+ *
+ * `AI` is a member here even though `unibox-ai` is build-order step 9 and does not exist. That is
+ * not speculation — it is the field an agent taking over mid-conversation reads to know what the
+ * customer has already been told, and §12 makes human handoff a launch requirement rather than a
+ * v2 feature. Adding the member later would mean every message written before it was added is
+ * indistinguishable from a human's, retroactively and unfixably.
+ */
+export var MessageAuthorType;
+(function (MessageAuthorType) {
+    /** The person on the other end. `authorUserId` is null. */
+    MessageAuthorType["CONTACT"] = "contact";
+    /** A human agent. `authorUserId` names them. */
+    MessageAuthorType["AGENT"] = "agent";
+    /**
+     * The AI agent. Reserved for `unibox-ai`; nothing writes it yet.
+     *
+     * Distinct from `AGENT` because "did a person say this?" is the question a human asks before
+     * taking over, and because a customer who later asks whether they were talking to a bot
+     * deserves an answer the data can actually give.
+     */
+    MessageAuthorType["AI"] = "ai";
+    /** Unibox itself — assignment changes, status changes. Always `INTERNAL`. */
+    MessageAuthorType["SYSTEM"] = "system";
+})(MessageAuthorType || (MessageAuthorType = {}));
+//# sourceMappingURL=message-author-type.enum.js.map

package/dist/esm/api/unibox/message-author-type.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-author-type.enum.js","sourceRoot":"","sources":["../../../../src/api/unibox/message-author-type.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAN,IAAY,iBAkBX;AAlBD,WAAY,iBAAiB;IACzB,2DAA2D;IAC3D,wCAAmB,CAAA;IAEnB,gDAAgD;IAChD,oCAAe,CAAA;IAEf;;;;;;OAMG;IACH,8BAAS,CAAA;IAET,6EAA6E;IAC7E,sCAAiB,CAAA;AACrB,CAAC,EAlBW,iBAAiB,KAAjB,iBAAiB,QAkB5B"}

package/dist/esm/api/unibox/message-content-type.enum.d.ts

@@ -0,0 +1,29 @@
+/**
+ * What kind of thing a message carries.
+ *
+ * A small closed set that every platform can be normalized into, rather than a union of what each
+ * one supports. A per-platform vocabulary would put "is this an Instagram story reply or a
+ * WhatsApp interactive button" in front of the inbox UI, and the inbox's whole promise is that it
+ * does not care.
+ */
+export declare enum MessageContentType {
+    TEXT = "text",
+    IMAGE = "image",
+    VIDEO = "video",
+    AUDIO = "audio",
+    /** A file — PDF, spreadsheet, anything not one of the media types above. */
+    DOCUMENT = "document",
+    LOCATION = "location",
+    /** A sticker or a bare emoji reaction, kept distinct so it can be rendered small. */
+    STICKER = "sticker",
+    /**
+     * Something arrived that this version cannot represent.
+     *
+     * **A first-class member, not an error.** A message we cannot render is still evidence that
+     * the contact said something, and dropping it leaves an agent replying to a gap. The raw
+     * provider payload is retained on the message so the same row can be re-read once a
+     * normalizer learns the type.
+     */
+    UNSUPPORTED = "unsupported"
+}
+//# sourceMappingURL=message-content-type.enum.d.ts.map

package/dist/esm/api/unibox/message-content-type.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-content-type.enum.d.ts","sourceRoot":"","sources":["../../../../src/api/unibox/message-content-type.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,oBAAY,kBAAkB;IAC1B,IAAI,SAAS;IACb,KAAK,UAAU;IACf,KAAK,UAAU;IACf,KAAK,UAAU;IACf,4EAA4E;IAC5E,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,qFAAqF;IACrF,OAAO,YAAY;IAEnB;;;;;;;OAOG;IACH,WAAW,gBAAgB;CAC9B"}

package/dist/esm/api/unibox/message-content-type.enum.js

@@ -0,0 +1,30 @@
+/**
+ * What kind of thing a message carries.
+ *
+ * A small closed set that every platform can be normalized into, rather than a union of what each
+ * one supports. A per-platform vocabulary would put "is this an Instagram story reply or a
+ * WhatsApp interactive button" in front of the inbox UI, and the inbox's whole promise is that it
+ * does not care.
+ */
+export var MessageContentType;
+(function (MessageContentType) {
+    MessageContentType["TEXT"] = "text";
+    MessageContentType["IMAGE"] = "image";
+    MessageContentType["VIDEO"] = "video";
+    MessageContentType["AUDIO"] = "audio";
+    /** A file — PDF, spreadsheet, anything not one of the media types above. */
+    MessageContentType["DOCUMENT"] = "document";
+    MessageContentType["LOCATION"] = "location";
+    /** A sticker or a bare emoji reaction, kept distinct so it can be rendered small. */
+    MessageContentType["STICKER"] = "sticker";
+    /**
+     * Something arrived that this version cannot represent.
+     *
+     * **A first-class member, not an error.** A message we cannot render is still evidence that
+     * the contact said something, and dropping it leaves an agent replying to a gap. The raw
+     * provider payload is retained on the message so the same row can be re-read once a
+     * normalizer learns the type.
+     */
+    MessageContentType["UNSUPPORTED"] = "unsupported";
+})(MessageContentType || (MessageContentType = {}));
+//# sourceMappingURL=message-content-type.enum.js.map

package/dist/esm/api/unibox/message-content-type.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-content-type.enum.js","sourceRoot":"","sources":["../../../../src/api/unibox/message-content-type.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAN,IAAY,kBAoBX;AApBD,WAAY,kBAAkB;IAC1B,mCAAa,CAAA;IACb,qCAAe,CAAA;IACf,qCAAe,CAAA;IACf,qCAAe,CAAA;IACf,4EAA4E;IAC5E,2CAAqB,CAAA;IACrB,2CAAqB,CAAA;IACrB,qFAAqF;IACrF,yCAAmB,CAAA;IAEnB;;;;;;;OAOG;IACH,iDAA2B,CAAA;AAC/B,CAAC,EApBW,kBAAkB,KAAlB,kBAAkB,QAoB7B"}

package/dist/esm/api/unibox/message-direction.enum.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Which way a message travelled.
+ *
+ * Separate from {@link MessageAuthorType} on purpose, because they answer different questions and
+ * the mapping is not one-to-one. A `SYSTEM` note ("conversation assigned to Dana") is outbound in
+ * neither sense — it was never sent anywhere — so it is `INTERNAL`, and collapsing the two fields
+ * would make every internal note look like something a customer received.
+ */
+export declare enum MessageDirection {
+    /** From the contact to us, through a provider. */
+    INBOUND = "inbound",
+    /** From us to the contact, through Conduit. */
+    OUTBOUND = "outbound",
+    /**
+     * Never left Unibox. Assignment notes, status changes, private agent comments.
+     *
+     * Rendered in the thread because context is what makes a handover work, but structurally
+     * distinct: an internal message has no delivery status and no provider message id, and a bug
+     * that sent one would be a customer reading our internal notes.
+     */
+    INTERNAL = "internal"
+}
+//# sourceMappingURL=message-direction.enum.d.ts.map

package/dist/esm/api/unibox/message-direction.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-direction.enum.d.ts","sourceRoot":"","sources":["../../../../src/api/unibox/message-direction.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,oBAAY,gBAAgB;IACxB,kDAAkD;IAClD,OAAO,YAAY;IAEnB,+CAA+C;IAC/C,QAAQ,aAAa;IAErB;;;;;;OAMG;IACH,QAAQ,aAAa;CACxB"}

package/dist/esm/api/unibox/message-direction.enum.js

@@ -0,0 +1,24 @@
+/**
+ * Which way a message travelled.
+ *
+ * Separate from {@link MessageAuthorType} on purpose, because they answer different questions and
+ * the mapping is not one-to-one. A `SYSTEM` note ("conversation assigned to Dana") is outbound in
+ * neither sense — it was never sent anywhere — so it is `INTERNAL`, and collapsing the two fields
+ * would make every internal note look like something a customer received.
+ */
+export var MessageDirection;
+(function (MessageDirection) {
+    /** From the contact to us, through a provider. */
+    MessageDirection["INBOUND"] = "inbound";
+    /** From us to the contact, through Conduit. */
+    MessageDirection["OUTBOUND"] = "outbound";
+    /**
+     * Never left Unibox. Assignment notes, status changes, private agent comments.
+     *
+     * Rendered in the thread because context is what makes a handover work, but structurally
+     * distinct: an internal message has no delivery status and no provider message id, and a bug
+     * that sent one would be a customer reading our internal notes.
+     */
+    MessageDirection["INTERNAL"] = "internal";
+})(MessageDirection || (MessageDirection = {}));
+//# sourceMappingURL=message-direction.enum.js.map

package/dist/esm/api/unibox/message-direction.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-direction.enum.js","sourceRoot":"","sources":["../../../../src/api/unibox/message-direction.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAN,IAAY,gBAeX;AAfD,WAAY,gBAAgB;IACxB,kDAAkD;IAClD,uCAAmB,CAAA;IAEnB,+CAA+C;IAC/C,yCAAqB,CAAA;IAErB;;;;;;OAMG;IACH,yCAAqB,CAAA;AACzB,CAAC,EAfW,gBAAgB,KAAhB,gBAAgB,QAe3B"}

package/dist/esm/api/unibox/message-status.enum.d.ts

@@ -0,0 +1,40 @@
+/**
+ * How far an **outbound** message got.
+ *
+ * Inbound and internal messages are always {@link MessageStatus.RECEIVED} and
+ * {@link MessageStatus.NONE} respectively — the states below describe our side of a send, and a
+ * message that arrived has no send to describe.
+ *
+ * The three post-send states mirror what the messaging platforms report back through their status
+ * webhooks, and they arrive **through the inbound pipeline** (§11): a provider telling us a
+ * message was read is just another webhook. Nothing polls for them.
+ */
+export declare enum MessageStatus {
+    /** Not applicable — an internal note. */
+    NONE = "none",
+    /** Inbound. It is here; there was nothing to send. */
+    RECEIVED = "received",
+    /**
+     * Written down and handed to Conduit, which answered `202`.
+     *
+     * The important state to read correctly: it means Conduit has accepted responsibility, not
+     * that the provider has seen it. An inbox that renders this as a delivered tick is lying at
+     * exactly the moment a provider outage matters.
+     */
+    QUEUED = "queued",
+    /** The provider accepted it. */
+    SENT = "sent",
+    /** The provider says it reached the contact's device. */
+    DELIVERED = "delivered",
+    /** The contact opened it. Not every platform reports this. */
+    READ = "read",
+    /**
+     * It will not be sent. Terminal.
+     *
+     * Set when Conduit dead-letters the dispatch, or when the send is refused outright — an
+     * inactive channel, a closed messaging window. `failureReason` carries the why, because
+     * "failed" alone sends an agent to ask an engineer.
+     */
+    FAILED = "failed"
+}
+//# sourceMappingURL=message-status.enum.d.ts.map

package/dist/esm/api/unibox/message-status.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-status.enum.d.ts","sourceRoot":"","sources":["../../../../src/api/unibox/message-status.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,oBAAY,aAAa;IACrB,yCAAyC;IACzC,IAAI,SAAS;IAEb,sDAAsD;IACtD,QAAQ,aAAa;IAErB;;;;;;OAMG;IACH,MAAM,WAAW;IAEjB,gCAAgC;IAChC,IAAI,SAAS;IAEb,yDAAyD;IACzD,SAAS,cAAc;IAEvB,8DAA8D;IAC9D,IAAI,SAAS;IAEb;;;;;;OAMG;IACH,MAAM,WAAW;CACpB"}

package/dist/esm/api/unibox/message-status.enum.js

@@ -0,0 +1,41 @@
+/**
+ * How far an **outbound** message got.
+ *
+ * Inbound and internal messages are always {@link MessageStatus.RECEIVED} and
+ * {@link MessageStatus.NONE} respectively — the states below describe our side of a send, and a
+ * message that arrived has no send to describe.
+ *
+ * The three post-send states mirror what the messaging platforms report back through their status
+ * webhooks, and they arrive **through the inbound pipeline** (§11): a provider telling us a
+ * message was read is just another webhook. Nothing polls for them.
+ */
+export var MessageStatus;
+(function (MessageStatus) {
+    /** Not applicable — an internal note. */
+    MessageStatus["NONE"] = "none";
+    /** Inbound. It is here; there was nothing to send. */
+    MessageStatus["RECEIVED"] = "received";
+    /**
+     * Written down and handed to Conduit, which answered `202`.
+     *
+     * The important state to read correctly: it means Conduit has accepted responsibility, not
+     * that the provider has seen it. An inbox that renders this as a delivered tick is lying at
+     * exactly the moment a provider outage matters.
+     */
+    MessageStatus["QUEUED"] = "queued";
+    /** The provider accepted it. */
+    MessageStatus["SENT"] = "sent";
+    /** The provider says it reached the contact's device. */
+    MessageStatus["DELIVERED"] = "delivered";
+    /** The contact opened it. Not every platform reports this. */
+    MessageStatus["READ"] = "read";
+    /**
+     * It will not be sent. Terminal.
+     *
+     * Set when Conduit dead-letters the dispatch, or when the send is refused outright — an
+     * inactive channel, a closed messaging window. `failureReason` carries the why, because
+     * "failed" alone sends an agent to ask an engineer.
+     */
+    MessageStatus["FAILED"] = "failed";
+})(MessageStatus || (MessageStatus = {}));
+//# sourceMappingURL=message-status.enum.js.map

package/dist/esm/api/unibox/message-status.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-status.enum.js","sourceRoot":"","sources":["../../../../src/api/unibox/message-status.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,CAAN,IAAY,aAiCX;AAjCD,WAAY,aAAa;IACrB,yCAAyC;IACzC,8BAAa,CAAA;IAEb,sDAAsD;IACtD,sCAAqB,CAAA;IAErB;;;;;;OAMG;IACH,kCAAiB,CAAA;IAEjB,gCAAgC;IAChC,8BAAa,CAAA;IAEb,yDAAyD;IACzD,wCAAuB,CAAA;IAEvB,8DAA8D;IAC9D,8BAAa,CAAA;IAEb;;;;;;OAMG;IACH,kCAAiB,CAAA;AACrB,CAAC,EAjCW,aAAa,KAAb,aAAa,QAiCxB"}

package/dist/esm/api/unibox/message.type.d.ts

@@ -0,0 +1,120 @@
+import type { CursorPage } from '../../type/cursor-page.type.js';
+import type { IsoDateTime } from '../../type/iso-date-time.type.js';
+import type { Nullable } from '../../type/nil.type.js';
+import type { UUID } from '../../type/uuid.type.js';
+import type { MessageAuthorType } from './message-author-type.enum.js';
+import type { MessageContentType } from './message-content-type.enum.js';
+import type { MessageDirection } from './message-direction.enum.js';
+import type { MessageStatus } from './message-status.enum.js';
+/** A file attached to a message. Media is referenced by provider URL until `iveri-files-api` exists. */
+export interface MessageAttachment {
+    contentType: MessageContentType;
+    /**
+     * Where the media lives.
+     *
+     * Today this is the provider's own URL, which for most platforms is short-lived and requires
+     * the channel's credentials to fetch — so it is not something a browser can render directly.
+     * Re-hosting is `iveri-files-api`'s job (build-order step 10 territory), and this field is
+     * what will point at it instead.
+     */
+    url: Nullable<string>;
+    /** The provider's media id, which is what a re-host job would need to fetch it. */
+    externalMediaId: Nullable<string>;
+    fileName: Nullable<string>;
+    mimeType: Nullable<string>;
+    sizeBytes: Nullable<number>;
+}
+/**
+ * One message in a conversation.
+ *
+ * Immutable once written, apart from `status` and its timestamps. An inbox is a record of what was
+ * said, and an editable one is not evidence of anything — which matters the first time a customer
+ * disputes what they were told.
+ */
+export interface Message {
+    id: UUID;
+    conversationId: UUID;
+    direction: MessageDirection;
+    authorType: MessageAuthorType;
+    /** The agent who wrote it. Null for anything not authored by a human. */
+    authorUserId: Nullable<UUID>;
+    contentType: MessageContentType;
+    /** The text, or a caption on a media message. Null when there was none. */
+    text: Nullable<string>;
+    attachments: MessageAttachment[];
+    status: MessageStatus;
+    /** Why a `FAILED` message failed, in words an agent can act on. Null otherwise. */
+    failureReason: Nullable<string>;
+    /**
+     * The provider's own message id.
+     *
+     * Inbound, this is the **idempotency key**: Conduit is at-least-once by design and a
+     * redelivered webhook must not produce a second message. Outbound, it arrives with the
+     * provider's acceptance and is what a later status webhook is matched against.
+     */
+    externalMessageId: Nullable<string>;
+    /**
+     * The Conduit dispatch this send was submitted as.
+     *
+     * Kept so a dead letter in Conduit's outbound DLQ can be traced back to the message an agent
+     * is looking at. Conduit puts `x-conduit-dispatch-id` on every send for the same reason from
+     * the other end.
+     */
+    dispatchId: Nullable<UUID>;
+    /**
+     * When the message was said, according to the provider — not when we stored it.
+     *
+     * These differ by however long a provider queued a webhook, which after an outage is hours.
+     * Ordering the thread by arrival would then shuffle a conversation into nonsense, so this is
+     * what the thread sorts on.
+     */
+    sentAt: IsoDateTime;
+    deliveredAt: Nullable<IsoDateTime>;
+    readAt: Nullable<IsoDateTime>;
+    createdAt: IsoDateTime;
+}
+/**
+ * `GET /api/v1/conversations/:id/messages`. Cursor-paged, **newest first**.
+ *
+ * Newest first because that is what a thread opens to, and because paging backwards through
+ * history is the direction a scroll actually goes. The client reverses a page to render it.
+ */
+export type MessagesPage = CursorPage<Message>;
+/** Query for `GET /api/v1/conversations/:id/messages`. */
+export interface GetMessagesQuery {
+    limit?: number;
+    /** Opaque cursor from the previous page's `nextCursor`. Never parse it. */
+    before?: Nullable<string>;
+}
+/**
+ * `POST /api/v1/conversations/:id/messages` — an agent replying.
+ *
+ * Note what is absent: no channel, no recipient, no provider fields. The conversation already
+ * knows which channel it is on and who the contact is, and letting a caller restate either would
+ * be a way to send a message to one person through another person's thread.
+ */
+export interface SendMessageBody {
+    /** The reply text. Required for `TEXT`; a caption otherwise. */
+    text?: Nullable<string>;
+    contentType?: Nullable<MessageContentType>;
+    attachments?: Nullable<MessageAttachment[]>;
+    /**
+     * The caller's idempotency key, scoped to the conversation.
+     *
+     * **Strongly recommended, and forwarded to Conduit as its dispatch key.** Without one, an
+     * agent double-clicking Send messages the customer twice — and unlike an inbound duplicate,
+     * which is evidence, an outbound duplicate is a mistake the customer sees.
+     */
+    idempotencyKey?: Nullable<string>;
+}
+/**
+ * `POST /api/v1/conversations/:id/notes` — a private note in the thread.
+ *
+ * A separate endpoint from sending rather than a flag on {@link SendMessageBody}, because the
+ * difference between "the customer reads this" and "only we read this" must not be one boolean
+ * away from being wrong. It also carries a different permission: writing a note is not sending.
+ */
+export interface AddNoteBody {
+    text: string;
+}
+//# sourceMappingURL=message.type.d.ts.map

package/dist/esm/api/unibox/message.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.type.d.ts","sourceRoot":"","sources":["../../../../src/api/unibox/message.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,wGAAwG;AACxG,MAAM,WAAW,iBAAiB;IAC9B,WAAW,EAAE,kBAAkB,CAAC;IAEhC;;;;;;;OAOG;IACH,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEtB,mFAAmF;IACnF,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAElC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3B,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3B,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACpB,EAAE,EAAE,IAAI,CAAC;IAET,cAAc,EAAE,IAAI,CAAC;IAErB,SAAS,EAAE,gBAAgB,CAAC;IAE5B,UAAU,EAAE,iBAAiB,CAAC;IAE9B,yEAAyE;IACzE,YAAY,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAE7B,WAAW,EAAE,kBAAkB,CAAC;IAEhC,2EAA2E;IAC3E,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEvB,WAAW,EAAE,iBAAiB,EAAE,CAAC;IAEjC,MAAM,EAAE,aAAa,CAAC;IAEtB,mFAAmF;IACnF,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEhC;;;;;;OAMG;IACH,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEpC;;;;;;OAMG;IACH,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAE3B;;;;;;OAMG;IACH,MAAM,EAAE,WAAW,CAAC;IAEpB,WAAW,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IACnC,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IAE9B,SAAS,EAAE,WAAW,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;AAE/C,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,2EAA2E;IAC3E,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC5B,gEAAgE;IAChE,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAExB,WAAW,CAAC,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC;IAE3C,WAAW,CAAC,EAAE,QAAQ,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAE5C;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACrC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAC;CAChB"}