@iveri/contracts 0.6.0 → 0.8.0

package/dist/esm/api/unibox/channel-platform.enum.js

@@ -0,0 +1,33 @@
+/**
+ * The messaging network a channel is connected to.
+ *
+ * This is Unibox's vocabulary, not Conduit's. Conduit knows about *connectors* — a set of hosts
+ * and operations someone wrote down — and has no idea that any of them carry conversations.
+ * Unibox knows that a WhatsApp message and an Instagram message are the same kind of thing and
+ * belong in one inbox, which is the whole product.
+ *
+ * The members are the platforms Unibox can **normalize**, which is a stricter bar than the ones
+ * Conduit can talk to: normalizing means we can read a provider's webhook into a contact, a
+ * conversation and a message, and write a reply back. Adding one is a normalizer plus a
+ * connector manifest, and is a minor version here.
+ */
+export var ChannelPlatform;
+(function (ChannelPlatform) {
+    /** WhatsApp Cloud API. The first real platform, and the one `conduit-api` ships a manifest for. */
+    ChannelPlatform["WHATSAPP"] = "whatsapp";
+    /** Instagram Direct, via the Messenger Platform. */
+    ChannelPlatform["INSTAGRAM"] = "instagram";
+    /** Facebook Messenger. */
+    ChannelPlatform["MESSENGER"] = "messenger";
+    /**
+     * A loopback platform for local development and tests, matching Conduit's `local-echo`
+     * connector.
+     *
+     * It exists for the same reason that connector does: the entire pipeline — receive,
+     * normalize, thread, reply, dispatch — is provable without a Meta app, and a real Meta app
+     * would only prove we can talk to Meta. It is a first-class member rather than a test double
+     * so the normalizer registry has no branch that only exists under Jest.
+     */
+    ChannelPlatform["ECHO"] = "echo";
+})(ChannelPlatform || (ChannelPlatform = {}));
+//# sourceMappingURL=channel-platform.enum.js.map

package/dist/esm/api/unibox/channel-platform.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-platform.enum.js","sourceRoot":"","sources":["../../../../src/api/unibox/channel-platform.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAN,IAAY,eAoBX;AApBD,WAAY,eAAe;IACvB,mGAAmG;IACnG,wCAAqB,CAAA;IAErB,oDAAoD;IACpD,0CAAuB,CAAA;IAEvB,0BAA0B;IAC1B,0CAAuB,CAAA;IAEvB;;;;;;;;OAQG;IACH,gCAAa,CAAA;AACjB,CAAC,EApBW,eAAe,KAAf,eAAe,QAoB1B"}

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

@@ -0,0 +1,110 @@
+import type { IsoDateTime } from '../../type/iso-date-time.type.js';
+import type { Nullable } from '../../type/nil.type.js';
+import type { Paginated } from '../../type/paginated.type.js';
+import type { UUID } from '../../type/uuid.type.js';
+import type { ChannelPlatform } from './channel-platform.enum.js';
+/**
+ * One messaging account a tenant has connected — a WhatsApp number, an Instagram business
+ * account, a Facebook page.
+ *
+ * A channel is the seam between Unibox and Conduit, and it points at Conduit twice, in opposite
+ * directions:
+ *
+ * - **Inbound**, Conduit forwards a provider's raw webhook to Unibox and presents this channel's
+ *   ingest secret. Conduit does not parse it — it cannot, because §11 forbids it knowing what a
+ *   chat is — so normalizing the bytes into a message is Unibox's job.
+ * - **Outbound**, a reply is submitted to Conduit naming `connectionKey` and `sendOperation`.
+ *   Unibox never calls the Graph API itself (§12).
+ *
+ * Neither reference is a foreign key, because they name rows in another service's database. A
+ * `connectionKey` that no longer resolves is a misconfiguration Unibox reports; it is not
+ * something Unibox can prevent, and pretending otherwise would mean Unibox reading Conduit's
+ * tables, which is exactly what §2 forbids.
+ */
+export interface Channel {
+    id: UUID;
+    /** Tenant-scoped, stable, and how a normalizer is chosen for inbound traffic. */
+    key: string;
+    name: string;
+    platform: ChannelPlatform;
+    /**
+     * The account's own identifier at the provider — a WhatsApp phone-number id, an Instagram
+     * account id.
+     *
+     * Stored because a provider's webhook names the *recipient* account, and a tenant may have
+     * several channels on one platform. Without it there is no way to tell which of two WhatsApp
+     * numbers a message arrived at, and both would look equally plausible.
+     */
+    externalAccountId: string;
+    /** Conduit connection a reply is dispatched through. Loose reference into another service. */
+    connectionKey: string;
+    /** Which of that connector's operations sends a message. */
+    sendOperation: string;
+    /**
+     * Whether this channel accepts inbound traffic and sends replies.
+     *
+     * Turning it off stops new conversations and refuses sends. It does **not** delete anything
+     * already received: a channel a customer disconnected still has a history someone needs to
+     * read.
+     */
+    isActive: boolean;
+    /**
+     * Whether an ingest secret is currently set.
+     *
+     * A boolean, never the value. The secret is what authenticates Conduit to Unibox, so it is
+     * envelope-encrypted, returned by no endpoint, and shown to the operator exactly once — at
+     * the moment it is generated, when it also has to be pasted into Conduit's destination
+     * headers. Same control as an endpoint's signing secret in Conduit.
+     */
+    hasIngestSecret: boolean;
+    /** When a message was last received or sent here. Null until the first one. */
+    lastActivityAt: Nullable<IsoDateTime>;
+    createdAt: IsoDateTime;
+    updatedAt: IsoDateTime;
+}
+/** `GET /api/v1/channels`. Offset-paged: a tenant has a handful of channels, not a stream of them. */
+export type ChannelsPage = Paginated<Channel>;
+/** `POST /api/v1/channels`. */
+export interface CreateChannelBody {
+    /** Lowercase, `[a-z0-9-]`. Unique within the tenant and immutable once created. */
+    key: string;
+    name: string;
+    platform: ChannelPlatform;
+    externalAccountId: string;
+    connectionKey: string;
+    /** Defaults to the platform's conventional send operation when omitted. */
+    sendOperation?: Nullable<string>;
+}
+/**
+ * `PATCH /api/v1/channels/:id`.
+ *
+ * `key` and `platform` are absent on purpose. The key is what an ingest request resolves and what
+ * an operator wrote into Conduit's configuration; the platform decides which normalizer reads the
+ * history already stored against this channel. Changing either would silently reinterpret rows
+ * that are already there, so both are create-only — delete and recreate is the honest path.
+ */
+export interface UpdateChannelBody {
+    name?: string;
+    externalAccountId?: string;
+    connectionKey?: string;
+    sendOperation?: string;
+    isActive?: boolean;
+}
+/**
+ * `POST /api/v1/channels/:id/ingest-secret` — the **only** response that ever carries the secret.
+ *
+ * Rotating replaces the stored value immediately, so the previous secret stops working the moment
+ * this returns. That is deliberate and it is a brief outage by design: an ingest secret that
+ * overlapped with its replacement would mean a leaked one keeps working for as long as the
+ * overlap, which is the thing rotation exists to end.
+ */
+export interface ChannelIngestSecretResponse {
+    channelId: UUID;
+    /** Shown once. Not stored in retrievable form, and no endpoint returns it again. */
+    ingestSecret: string;
+    /** The URL to configure as the destination in Conduit, for convenience. */
+    ingestUrl: string;
+    /** The header Conduit must carry the secret in. */
+    ingestHeaderName: string;
+}
+//# sourceMappingURL=channel.type.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"channel.type.d.ts","sourceRoot":"","sources":["../../../../src/api/unibox/channel.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,OAAO;IACpB,EAAE,EAAE,IAAI,CAAC;IAET,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;IAEZ,IAAI,EAAE,MAAM,CAAC;IAEb,QAAQ,EAAE,eAAe,CAAC;IAE1B;;;;;;;OAOG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAE1B,8FAA8F;IAC9F,aAAa,EAAE,MAAM,CAAC;IAEtB,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAC;IAEtB;;;;;;OAMG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;;;;;;OAOG;IACH,eAAe,EAAE,OAAO,CAAC;IAEzB,+EAA+E;IAC/E,cAAc,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IAEtC,SAAS,EAAE,WAAW,CAAC;IACvB,SAAS,EAAE,WAAW,CAAC;CAC1B;AAED,sGAAsG;AACtG,MAAM,MAAM,YAAY,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;AAE9C,+BAA+B;AAC/B,MAAM,WAAW,iBAAiB;IAC9B,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;IAEZ,IAAI,EAAE,MAAM,CAAC;IAEb,QAAQ,EAAE,eAAe,CAAC;IAE1B,iBAAiB,EAAE,MAAM,CAAC;IAE1B,aAAa,EAAE,MAAM,CAAC;IAEtB,2EAA2E;IAC3E,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,2BAA2B;IACxC,SAAS,EAAE,IAAI,CAAC;IAEhB,oFAAoF;IACpF,YAAY,EAAE,MAAM,CAAC;IAErB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAElB,mDAAmD;IACnD,gBAAgB,EAAE,MAAM,CAAC;CAC5B"}

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

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

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

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

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

@@ -0,0 +1,102 @@
+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';
+/**
+ * One way of reaching a contact on one platform.
+ *
+ * A person is not a phone number. The same human messages a business from WhatsApp on Monday and
+ * from Instagram on Thursday, and an inbox that treats those as two strangers is an inbox that
+ * loses the thread — so identities are a child collection rather than columns on the contact.
+ *
+ * That shape is what makes merging possible later without a migration. Merging is **not built**;
+ * the modelling for it is, which is the part that is expensive to retrofit.
+ */
+export interface ContactIdentity {
+    id: UUID;
+    platform: ChannelPlatform;
+    /**
+     * The provider's own identifier for this person — a WhatsApp `wa_id`, an Instagram-scoped
+     * user id.
+     *
+     * Unique per `(tenant, platform)`. **Scoped ids are not portable across platforms**: the same
+     * person has an entirely different id on Instagram and on Messenger, and treating one as the
+     * other merges two strangers. That is why the platform is part of the key rather than the id
+     * being assumed globally unique.
+     */
+    externalId: string;
+    /** The name the provider supplied, when it supplied one. Not authoritative and often absent. */
+    displayName: Nullable<string>;
+    createdAt: IsoDateTime;
+}
+/**
+ * A person the tenant talks to.
+ *
+ * Personal data, deliberately minimal: Unibox stores what it needs to thread a conversation and
+ * address someone by name. A CRM's worth of fields belongs in the vertical that needs them, and
+ * §17's GDPR line is materially cheaper to honour on a small table.
+ */
+export interface Contact {
+    id: UUID;
+    /**
+     * The name shown in the inbox.
+     *
+     * Editable by an agent, because a provider's display name is frequently a handle or absent,
+     * and correcting it is the first thing anyone does. Falls back to the first identity's
+     * `displayName`, then to its `externalId`.
+     */
+    displayName: string;
+    email: Nullable<string>;
+    /** E.164 where known. Not the same as a WhatsApp identity's `externalId`, which is scoped. */
+    phone: Nullable<string>;
+    /** Free-form agent notes. Not shown to the contact and never sent anywhere. */
+    notes: Nullable<string>;
+    /** Lowercased, deduplicated. For filtering the inbox, not for automation. */
+    tags: string[];
+    identities: ContactIdentity[];
+    /** When this contact last sent or received a message. Null until the first one. */
+    lastActivityAt: Nullable<IsoDateTime>;
+    createdAt: IsoDateTime;
+    updatedAt: IsoDateTime;
+}
+/** `GET /api/v1/contacts`. Cursor-paged: inbound traffic appends to it while it is being read. */
+export type ContactsPage = CursorPage<Contact>;
+/** Query for `GET /api/v1/contacts`. */
+export interface GetContactsQuery {
+    limit?: number;
+    /** Opaque cursor from the previous page's `nextCursor`. Never parse it. */
+    after?: Nullable<string>;
+    /** Case-insensitive substring of the display name, email or phone. */
+    search?: Nullable<string>;
+    tag?: Nullable<string>;
+}
+/**
+ * `POST /api/v1/contacts`.
+ *
+ * Creating a contact by hand is the uncommon path — almost every contact arrives because someone
+ * messaged in, and inbound creates them. This exists so an agent can prepare a record before a
+ * conversation starts, and so a vertical can seed one.
+ */
+export interface CreateContactBody {
+    displayName: string;
+    email?: Nullable<string>;
+    phone?: Nullable<string>;
+    notes?: Nullable<string>;
+    tags?: Nullable<string[]>;
+}
+/**
+ * `PATCH /api/v1/contacts/:id`.
+ *
+ * `identities` is absent: an identity is asserted by a provider, not chosen by an agent. Adding
+ * one by hand is how two strangers get merged into one record, and there is no undo for that.
+ */
+export interface UpdateContactBody {
+    displayName?: string;
+    email?: Nullable<string>;
+    phone?: Nullable<string>;
+    notes?: Nullable<string>;
+    /** Replaces the whole set. Omit to leave it alone; `[]` clears it. */
+    tags?: Nullable<string[]>;
+}
+//# sourceMappingURL=contact.type.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contact.type.d.ts","sourceRoot":"","sources":["../../../../src/api/unibox/contact.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,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC5B,EAAE,EAAE,IAAI,CAAC;IAET,QAAQ,EAAE,eAAe,CAAC;IAE1B;;;;;;;;OAQG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB,gGAAgG;IAChG,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE9B,SAAS,EAAE,WAAW,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACpB,EAAE,EAAE,IAAI,CAAC;IAET;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAExB,8FAA8F;IAC9F,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAExB,+EAA+E;IAC/E,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAExB,6EAA6E;IAC7E,IAAI,EAAE,MAAM,EAAE,CAAC;IAEf,UAAU,EAAE,eAAe,EAAE,CAAC;IAE9B,mFAAmF;IACnF,cAAc,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IAEtC,SAAS,EAAE,WAAW,CAAC;IACvB,SAAS,EAAE,WAAW,CAAC;CAC1B;AAED,kGAAkG;AAClG,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;AAE/C,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,2EAA2E;IAC3E,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEzB,sEAAsE;IACtE,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE1B,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzB,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzB,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzB,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzB,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzB,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEzB,sEAAsE;IACtE,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;CAC7B"}

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

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

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

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

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

@@ -0,0 +1,39 @@
+/**
+ * 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 declare enum ConversationStatus {
+    /** Needs a human. The default for anything with an unanswered inbound message. */
+    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`.
+     */
+    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.
+     */
+    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.
+     */
+    CLOSED = "closed"
+}
+//# sourceMappingURL=conversation-status.enum.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-status.enum.d.ts","sourceRoot":"","sources":["../../../../src/api/unibox/conversation-status.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,oBAAY,kBAAkB;IAC1B,kFAAkF;IAClF,IAAI,SAAS;IAEb;;;;;OAKG;IACH,OAAO,YAAY;IAEnB;;;;;;OAMG;IACH,OAAO,YAAY;IAEnB;;;;;;OAMG;IACH,MAAM,WAAW;CACpB"}

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"}