@iveri/contracts 0.7.0 → 0.9.0

package/README.md

@@ -14,14 +14,16 @@ import { CursorPage, ErrorCode, Maybe, Paginated, UUID, UserPermission } from '@
 // One service's wire surface.
 import type { CaptureSummary, Endpoint } from '@iveri/contracts/conduit';
 import type { AuthSession, Principal } from '@iveri/contracts/identity';
+import type { Conversation, Message } from '@iveri/contracts/unibox';
 ```
 
-Three entry points, and no others — never `@iveri/contracts/dist/...`.
+Four entry points, and no others — never `@iveri/contracts/dist/...`.
 
 The per-service surfaces are **not** re-exported from the root, deliberately. Conduit owns a
-`Provider` and an `Endpoint`; Unibox will want both names for entirely different things. Keeping
-each service behind its own entry point means that collision never has to be resolved by
-renaming a type in a shipped API.
+`Provider`, a `Connection` and an `Endpoint`; Unibox owns a `Channel` and a `Contact` and would
+have wanted two of those names for entirely different things. Keeping each service behind its own
+entry point means that collision never has to be resolved by renaming a type in a shipped API —
+and it stopped being hypothetical the moment `unibox` was added.
 
 ## Zero runtime dependencies — the rule that defines this package
 
@@ -95,6 +97,22 @@ Plus the request bodies for each, and the seven enums they are built from — `S
 `SignatureAlgorithm`, `SignatureEncoding`, `SignatureHeaderScheme`, `HandshakeKind`,
 `MatchOperator`, `DeliveryStatus`.
 
+### `api/unibox/` → `@iveri/contracts/unibox`
+
+`unibox-api`'s surface: `Channel` and its `ChannelIngestSecretResponse`, `Contact` with its
+`ContactIdentity`, `Conversation`/`ConversationWithMessages`, `Message` with `MessageAttachment`,
+`Team`, `CannedReply`, plus the request bodies and six enums — `ChannelPlatform`,
+`ConversationStatus`, `MessageDirection`, `MessageAuthorType`, `MessageStatus`,
+`MessageContentType`.
+
+Two of those enums carry members nothing writes yet, and both are deliberate rather than
+speculative. `MessageAuthorType.AI` exists before `unibox-ai` does, because it is what an agent
+taking over reads to know what the customer was already told — adding it later would leave every
+message written before then indistinguishable from a human's, retroactively. `ChannelPlatform.ECHO`
+is a first-class member for the same reason Conduit's `local-echo` connector is: the whole pipeline
+is provable without a Meta app, and a test double would put a branch in the normalizer registry
+that only exists under Jest.
+
 ### Why the wire shapes moved here
 
 `conduit-admin-web` hand-transcribed all of it, carefully and with comments. It still drifted:
@@ -117,6 +135,8 @@ Conduit's outbox.
 - A new `ErrorCode` or `UserPermission` member is a **minor** version. Changing what an
   existing member means, or removing one, is **major** — clients branch on these, and a
   removed permission silently downgrades every live session whose token still carries it.
+- Version `0.9.0` adds the first Commerce permissions: `commerce:catalog:read` and
+  `commerce:catalog:manage`.
 - Widening a type is minor; narrowing it is major.
 - Under `api/`, the contract follows the service: add the field to the service's DTO and to the
   interface in the same release, and let `implements` prove they agree.

package/dist/cjs/api/unibox/canned-reply.type.d.ts

@@ -0,0 +1,49 @@
+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';
+/**
+ * A saved reply an agent can insert into a message.
+ *
+ * **Inserted into the composer, never sent by itself.** A canned reply is text an agent chooses
+ * and can edit before sending — it is not an automation, and there is no endpoint that sends one
+ * directly. That line is what keeps this out of §14's no-scripting territory: the moment a saved
+ * reply can fire on a condition, we have built a rules engine in a chat product.
+ */
+export interface CannedReply {
+    id: UUID;
+    /** What an agent types to find it, e.g. `/hours`. Unique within the tenant. */
+    shortcut: string;
+    title: string;
+    /**
+     * The text, with `{{placeholders}}` substituted client-side at insert time.
+     *
+     * Substitution is the client's job on purpose. The server would have to resolve them at send
+     * time, which means an agent could send a message whose final text they never saw — and the
+     * one thing an agent must always be able to do is read what they are about to send.
+     */
+    body: string;
+    /** For grouping in the picker. Null is the ungrouped bucket. */
+    category: Nullable<string>;
+    createdByUserId: Nullable<UUID>;
+    createdAt: IsoDateTime;
+    updatedAt: IsoDateTime;
+}
+/** `GET /api/v1/canned-replies`. Offset-paged. */
+export type CannedRepliesPage = Paginated<CannedReply>;
+/** `POST /api/v1/canned-replies`. */
+export interface CreateCannedReplyBody {
+    /** Lowercase, `[a-z0-9-]`, no leading slash — the UI supplies that. */
+    shortcut: string;
+    title: string;
+    body: string;
+    category?: Nullable<string>;
+}
+/** `PATCH /api/v1/canned-replies/:id`. */
+export interface UpdateCannedReplyBody {
+    shortcut?: string;
+    title?: string;
+    body?: string;
+    category?: Nullable<string>;
+}
+//# sourceMappingURL=canned-reply.type.d.ts.map

package/dist/cjs/api/unibox/canned-reply.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canned-reply.type.d.ts","sourceRoot":"","sources":["../../../../src/api/unibox/canned-reply.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;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IACxB,EAAE,EAAE,IAAI,CAAC;IAET,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IAEjB,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb,gEAAgE;IAChE,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE3B,eAAe,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAEhC,SAAS,EAAE,WAAW,CAAC;IACvB,SAAS,EAAE,WAAW,CAAC;CAC1B;AAED,kDAAkD;AAClD,MAAM,MAAM,iBAAiB,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;AAEvD,qCAAqC;AACrC,MAAM,WAAW,qBAAqB;IAClC,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAC/B"}

package/dist/cjs/api/unibox/canned-reply.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=canned-reply.type.js.map

package/dist/cjs/api/unibox/canned-reply.type.js.map

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

package/dist/cjs/api/unibox/channel-platform.enum.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 declare enum ChannelPlatform {
+    /** WhatsApp Cloud API. The first real platform, and the one `conduit-api` ships a manifest for. */
+    WHATSAPP = "whatsapp",
+    /** Instagram Direct, via the Messenger Platform. */
+    INSTAGRAM = "instagram",
+    /** Facebook Messenger. */
+    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.
+     */
+    ECHO = "echo"
+}
+//# sourceMappingURL=channel-platform.enum.d.ts.map

package/dist/cjs/api/unibox/channel-platform.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-platform.enum.d.ts","sourceRoot":"","sources":["../../../../src/api/unibox/channel-platform.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,oBAAY,eAAe;IACvB,mGAAmG;IACnG,QAAQ,aAAa;IAErB,oDAAoD;IACpD,SAAS,cAAc;IAEvB,0BAA0B;IAC1B,SAAS,cAAc;IAEvB;;;;;;;;OAQG;IACH,IAAI,SAAS;CAChB"}

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

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChannelPlatform = void 0;
+/**
+ * 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.
+ */
+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 || (exports.ChannelPlatform = ChannelPlatform = {}));
+//# sourceMappingURL=channel-platform.enum.js.map

package/dist/cjs/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,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,+BAAf,eAAe,QAoB1B"}

package/dist/cjs/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/cjs/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/cjs/api/unibox/channel.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=channel.type.js.map

package/dist/cjs/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/cjs/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/cjs/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/cjs/api/unibox/contact.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=contact.type.js.map

package/dist/cjs/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/cjs/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/cjs/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/cjs/api/unibox/conversation-status.enum.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConversationStatus = void 0;
+/**
+ * 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.
+ */
+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 || (exports.ConversationStatus = ConversationStatus = {}));
+//# sourceMappingURL=conversation-status.enum.js.map

package/dist/cjs/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,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,kCAAlB,kBAAkB,QA6B7B"}