@mantine-vue/whatsapp-inbox 3.2.0

package/lib/types.d.ts

@@ -0,0 +1,777 @@
+/**
+ * Backend neutral domain model of the WhatsApp inbox.
+ *
+ * These types are independent of Meta Cloud API response shapes. Applications map backend data
+ * to this model.
+ *
+ * Timestamps are plain values so that any serialization survives the trip: ISO 8601 strings are
+ * recommended, but anything `new Date(value)` understands is accepted.
+ */
+/** Point in time accepted by every component. Rendered through the inbox formatters. */
+export type WhatsAppTimestamp = string | number | Date;
+/** Who sent the message. */
+export type WhatsAppMessageDirection = 'inbound' | 'outbound';
+/**
+ * Delivery state of a message, as reported by the backend.
+ *
+ * Inbound messages usually leave this unset. The extension never advances the state on its own.
+ */
+export type WhatsAppDeliveryStatus = 'pending' | 'sent' | 'delivered' | 'read' | 'failed';
+/** Kind of media carried by an attachment. */
+export type WhatsAppMediaType = 'image' | 'video' | 'audio' | 'document' | 'sticker';
+/**
+ * Discriminator of the message union.
+ *
+ * `unsupported` is the escape hatch for anything the backend received but could not normalize;
+ * rendering it keeps the history complete instead of leaving a hole in it.
+ */
+export type WhatsAppMessageType = 'text' | 'image' | 'video' | 'audio' | 'document' | 'sticker' | 'location' | 'contacts' | 'template' | 'interactive' | 'system' | 'unsupported';
+/** One labelled value shown in the contact panel, for example a CRM field. */
+export interface WhatsAppContactField {
+    /** Stable key, used as the list key. */
+    key: string;
+    /** Field name shown to the user. */
+    label: string;
+    /** Field value. Rendered as text unless `href` is set. */
+    value: string;
+    /** If set, the value is rendered as a link. */
+    href?: string;
+}
+/** Person on the other end of a conversation. */
+export interface WhatsAppContact {
+    /** Stable identifier in the consumer's system. */
+    id: string;
+    /** Display name. Falls back to `phoneNumber`. */
+    name?: string;
+    /** WhatsApp phone number, in whatever format the backend stores it. */
+    phoneNumber?: string;
+    /** Profile image. */
+    avatarUrl?: string;
+    /** WhatsApp "about" text. */
+    about?: string;
+    /** Email address, shown in the contact panel. */
+    email?: string;
+    /** Free-form labels shown as badges. */
+    tags?: string[];
+    /** Extra fields shown in the contact panel. */
+    fields?: WhatsAppContactField[];
+    /** Anything the consumer needs to carry along. Never read by the components. */
+    meta?: Record<string, unknown>;
+}
+/** Agent or team a conversation is assigned to. */
+export interface WhatsAppAssignee {
+    id: string;
+    name: string;
+    avatarUrl?: string;
+}
+/** A media file that is already hosted somewhere the browser can reach. */
+export interface WhatsAppAttachment {
+    /** Identifier assigned by the consumer's storage or by the WhatsApp provider. */
+    id?: string;
+    /** Determines which renderer is used. */
+    mediaType: WhatsAppMediaType;
+    /** Location the file is served from. Required to preview or download it. */
+    url?: string;
+    /** Poster for videos, thumbnail for images and documents. */
+    thumbnailUrl?: string;
+    /** Original file name, shown for documents. */
+    fileName?: string;
+    /** MIME type, used for the document icon and for validation. */
+    mimeType?: string;
+    /** Size in bytes. */
+    size?: number;
+    /** Duration in seconds, for audio and video. */
+    durationSeconds?: number;
+    /** Intrinsic width in pixels, used to reserve space before the media loads. */
+    width?: number;
+    /** Intrinsic height in pixels, used to reserve space before the media loads. */
+    height?: number;
+    /** Anything the consumer needs to carry along. */
+    meta?: Record<string, unknown>;
+}
+/** Lifecycle of a file picked in the composer. Owned entirely by the consumer. */
+export type WhatsAppUploadStatus = 'pending' | 'uploading' | 'uploaded' | 'failed' | 'canceled';
+/**
+ * One file in the composer, with the upload state the consumer reports back.
+ *
+ * The extension never uploads anything: it emits `attachmentsAdd` with the picked files and
+ * renders whatever `uploads` the consumer passes back in.
+ */
+export interface WhatsAppUpload {
+    /** Identifier generated by the consumer when it accepts the file. */
+    id: string;
+    /** File name shown in the preview. */
+    fileName: string;
+    /** Determines the preview renderer. */
+    mediaType: WhatsAppMediaType;
+    /** Current state of the upload. */
+    status: WhatsAppUploadStatus;
+    /** Progress in percent, `0` to `100`. Rendered as an indeterminate bar when unset. */
+    progress?: number;
+    /** MIME type of the picked file. */
+    mimeType?: string;
+    /** Size in bytes. */
+    size?: number;
+    /** Local or remote preview, typically an object URL. */
+    previewUrl?: string;
+    /** Set once the upload finished. This is what ends up in the outgoing payload. */
+    attachment?: WhatsAppAttachment;
+    /** Human readable failure reason, shown on the preview when `status` is `failed`. */
+    error?: string;
+    /** Anything the consumer needs to carry along. */
+    meta?: Record<string, unknown>;
+}
+/** File constraints enforced by the composer before a file reaches the consumer. */
+export interface WhatsAppMediaConstraints {
+    /** Largest accepted file size in bytes. */
+    maxFileSize?: number;
+    /** Accepted MIME types or extensions, in the format of the `accept` attribute. */
+    accept?: string[];
+    /** Largest number of files that may be attached to a single message. */
+    maxFiles?: number;
+}
+/** Template category. Open ended: providers keep adding new ones. */
+export type WhatsAppTemplateCategory = 'marketing' | 'utility' | 'authentication' | (string & {});
+/** Approval state of a template. Only approved templates can normally be sent. */
+export type WhatsAppTemplateStatus = 'approved' | 'pending' | 'rejected' | 'paused' | 'disabled' | (string & {});
+/** Kind of value a template placeholder expects. */
+export type WhatsAppTemplateParameterType = 'text' | 'currency' | 'date_time' | 'image' | 'video' | 'document' | 'location';
+/** One placeholder inside a template component. */
+export interface WhatsAppTemplateParameter {
+    /**
+     * Placeholder key. Positional templates use `1`, `2` and so on; named templates use the
+     * variable name. Entered values are stored under this key.
+     */
+    key: string;
+    /** Field label. Falls back to the key. */
+    label?: string;
+    /**
+     * Value type the placeholder expects.
+     * @default 'text'
+     */
+    type?: WhatsAppTemplateParameterType;
+    /**
+     * Whether a value must be provided before the template can be submitted.
+     * @default true
+     */
+    required?: boolean;
+    /** Example value from the approved template, shown as a hint. */
+    example?: string;
+    /** Longer explanation shown under the field. */
+    description?: string;
+    /** Input placeholder. Falls back to `example`. */
+    placeholder?: string;
+    /** Largest accepted length, enforced by the parameter form. */
+    maxLength?: number;
+}
+/** Header of a template. `format` decides whether it carries text or media. */
+export interface WhatsAppTemplateHeaderComponent {
+    type: 'header';
+    /**
+     * What the header renders.
+     * @default 'text'
+     */
+    format?: 'text' | 'image' | 'video' | 'document' | 'location';
+    /** Header text with placeholders, for text headers. */
+    text?: string;
+    /** Placeholders inside the header. */
+    parameters?: WhatsAppTemplateParameter[];
+    /** Media used in the approved example, previewed before the user picks their own. */
+    example?: WhatsAppAttachment;
+}
+/** Body of a template. Every template has exactly one. */
+export interface WhatsAppTemplateBodyComponent {
+    type: 'body';
+    /** Body text with placeholders. */
+    text: string;
+    /** Placeholders inside the body. */
+    parameters?: WhatsAppTemplateParameter[];
+}
+/** Static footer of a template. Never carries placeholders. */
+export interface WhatsAppTemplateFooterComponent {
+    type: 'footer';
+    text: string;
+}
+/** A button attached to a template. */
+export type WhatsAppTemplateButton = {
+    type: 'quick_reply';
+    text: string;
+    /** Payload sent back when the recipient taps the button. */
+    payload?: string;
+} | {
+    type: 'url';
+    text: string;
+    /** Target URL, which may end in a placeholder. */
+    url: string;
+    /** Placeholders inside the URL. */
+    parameters?: WhatsAppTemplateParameter[];
+} | {
+    type: 'phone_number';
+    text: string;
+    phoneNumber: string;
+} | {
+    type: 'copy_code';
+    text: string;
+    parameters?: WhatsAppTemplateParameter[];
+};
+/** Buttons section of a template. */
+export interface WhatsAppTemplateButtonsComponent {
+    type: 'buttons';
+    buttons: WhatsAppTemplateButton[];
+}
+/** One section of a template, discriminated by `type`. */
+export type WhatsAppTemplateComponent = WhatsAppTemplateHeaderComponent | WhatsAppTemplateBodyComponent | WhatsAppTemplateFooterComponent | WhatsAppTemplateButtonsComponent;
+/** An approved WhatsApp message template, normalized by the backend. */
+export interface WhatsAppTemplate {
+    /** Stable identifier. */
+    id: string;
+    /** Template name as registered with the provider. */
+    name: string;
+    /** Language code, for example `en_US`. */
+    language: string;
+    /** Human readable language name. Falls back to `language`. */
+    languageLabel?: string;
+    /** Category badge shown in the selector. */
+    category?: WhatsAppTemplateCategory;
+    /** Approval state. Templates that are not approved are shown as unavailable. */
+    status?: WhatsAppTemplateStatus;
+    /** Sections of the template. */
+    components: WhatsAppTemplateComponent[];
+    /** Free-form description shown in the selector. */
+    description?: string;
+    /** Anything the consumer needs to carry along. */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Values entered for a template's placeholders.
+ *
+ * Records are keyed by `WhatsAppTemplateParameter.key`; `buttons` is keyed by the button index
+ * as a string, so the whole object stays JSON serializable.
+ */
+export interface WhatsAppTemplateValues {
+    header?: Record<string, string>;
+    body?: Record<string, string>;
+    buttons?: Record<string, Record<string, string>>;
+    /** Media chosen for a media header. */
+    headerMedia?: WhatsAppAttachment | null;
+}
+/** A template as it appears in the history, with its placeholders already resolved. */
+export interface WhatsAppTemplateInstance {
+    /** Template name as sent. */
+    name: string;
+    /** Language the template was sent in. */
+    language?: string;
+    /** Identifier of the template, when the backend keeps one. */
+    templateId?: string;
+    /** Values the placeholders were filled with. */
+    values?: WhatsAppTemplateValues;
+    /** Full definition, used to render an exact preview of what was sent. */
+    template?: WhatsAppTemplate;
+    /** Pre-rendered body text, used when the definition is no longer available. */
+    text?: string;
+}
+/** Interactive message flavours. Not every provider supports all of them. */
+export type WhatsAppInteractiveType = 'button' | 'cta_url' | 'list';
+/** Header of an interactive message. */
+export interface WhatsAppInteractiveHeader {
+    type: 'text' | 'image' | 'video' | 'document';
+    text?: string;
+    attachment?: WhatsAppAttachment;
+}
+/** One reply button of an interactive message. */
+export interface WhatsAppInteractiveReplyButton {
+    id: string;
+    title: string;
+}
+/** One row of a list message. */
+export interface WhatsAppInteractiveListRow {
+    id: string;
+    title: string;
+    description?: string;
+}
+/** One section of a list message. */
+export interface WhatsAppInteractiveListSection {
+    title?: string;
+    rows: WhatsAppInteractiveListRow[];
+}
+/** Reply-button message: up to three tappable buttons under the body. */
+export interface WhatsAppInteractiveButtonContent {
+    type: 'button';
+    header?: WhatsAppInteractiveHeader;
+    body: string;
+    footer?: string;
+    buttons: WhatsAppInteractiveReplyButton[];
+}
+/** Call-to-action message: a single button that opens a URL. */
+export interface WhatsAppInteractiveCtaUrlContent {
+    type: 'cta_url';
+    header?: WhatsAppInteractiveHeader;
+    body: string;
+    footer?: string;
+    action: {
+        displayText: string;
+        url: string;
+    };
+}
+/** List message: a control that opens a sectioned list of options. */
+export interface WhatsAppInteractiveListContent {
+    type: 'list';
+    header?: WhatsAppInteractiveHeader;
+    body: string;
+    footer?: string;
+    /** Label of the control that opens the list. */
+    button: string;
+    sections: WhatsAppInteractiveListSection[];
+}
+/** Payload of an interactive message, discriminated by `type`. */
+export type WhatsAppInteractiveContent = WhatsAppInteractiveButtonContent | WhatsAppInteractiveCtaUrlContent | WhatsAppInteractiveListContent;
+/** Who produced an outbound message, shown above the bubble in shared inboxes. */
+export interface WhatsAppMessageAuthor {
+    id?: string;
+    name: string;
+    avatarUrl?: string;
+}
+/** Failure details for a message whose status is `failed`. */
+export interface WhatsAppMessageError {
+    /** Provider or backend error code, shown next to the message. */
+    code?: string;
+    /** Human readable failure reason. */
+    message?: string;
+    /**
+     * Whether the consumer can resend the message. Controls the retry action.
+     * @default true
+     */
+    retryable?: boolean;
+}
+/** Reference to the message another message replies to. */
+export interface WhatsAppMessageReference {
+    id: string;
+    /** Preview text of the quoted message. */
+    text?: string;
+    /** Direction of the quoted message, used to colour the quote. */
+    direction?: WhatsAppMessageDirection;
+    /** Author name of the quoted message. */
+    author?: string;
+}
+/** An emoji reaction on a message. */
+export interface WhatsAppReaction {
+    emoji: string;
+    count?: number;
+    /** Whether the current user reacted. */
+    reacted?: boolean;
+}
+/** Members every message shares, whatever its `type`. */
+export interface WhatsAppMessageBase {
+    /** Stable identifier. Used as the list key, so it must not change between renders. */
+    id: string;
+    /** Conversation the message belongs to. Optional when the list is already scoped. */
+    conversationId?: string;
+    /** Whether the message was received or sent. */
+    direction: WhatsAppMessageDirection;
+    /** Delivery state. Rendered as an icon with a screen-reader label. */
+    status?: WhatsAppDeliveryStatus;
+    /** When the message was created. */
+    timestamp: WhatsAppTimestamp;
+    /** Agent who sent the message, for shared inboxes. */
+    author?: WhatsAppMessageAuthor;
+    /** Message this one replies to. */
+    replyTo?: WhatsAppMessageReference;
+    /** Failure details, meaningful when `status` is `failed`. */
+    error?: WhatsAppMessageError;
+    /** Reactions on the message. */
+    reactions?: WhatsAppReaction[];
+    /** Whether the message was forwarded. */
+    forwarded?: boolean;
+    /** Anything the consumer needs to carry along. Never read by the components. */
+    meta?: Record<string, unknown>;
+}
+/** Plain or multiline text message. */
+export interface WhatsAppTextMessage extends WhatsAppMessageBase {
+    type: 'text';
+    text: string;
+}
+/** Shared shape of the media message types. */
+export interface WhatsAppMediaMessageBase<Type extends WhatsAppMessageType> extends WhatsAppMessageBase {
+    type: Type;
+    attachment: WhatsAppAttachment;
+    /** Text shown under the media. */
+    caption?: string;
+}
+export type WhatsAppImageMessage = WhatsAppMediaMessageBase<'image'>;
+export type WhatsAppVideoMessage = WhatsAppMediaMessageBase<'video'>;
+export type WhatsAppAudioMessage = WhatsAppMediaMessageBase<'audio'>;
+export type WhatsAppDocumentMessage = WhatsAppMediaMessageBase<'document'>;
+export type WhatsAppStickerMessage = WhatsAppMediaMessageBase<'sticker'>;
+/** Any message that carries a single attachment. */
+export type WhatsAppMediaMessage = WhatsAppImageMessage | WhatsAppVideoMessage | WhatsAppAudioMessage | WhatsAppDocumentMessage | WhatsAppStickerMessage;
+/** A template message that was sent to the contact. */
+export interface WhatsAppTemplateMessage extends WhatsAppMessageBase {
+    type: 'template';
+    template: WhatsAppTemplateInstance;
+}
+/** An interactive message, in either direction. */
+export interface WhatsAppInteractiveMessage extends WhatsAppMessageBase {
+    type: 'interactive';
+    interactive: WhatsAppInteractiveContent;
+    /** Option the recipient picked, for an inbound reply to an interactive message. */
+    reply?: {
+        id: string;
+        title?: string;
+    };
+}
+/** A shared location. */
+export interface WhatsAppLocationMessage extends WhatsAppMessageBase {
+    type: 'location';
+    location: {
+        latitude: number;
+        longitude: number;
+        name?: string;
+        address?: string;
+        /** Map link opened by the message. */
+        url?: string;
+    };
+}
+/** One shared contact card. */
+export interface WhatsAppContactCard {
+    name: string;
+    phoneNumbers?: string[];
+    emails?: string[];
+    organization?: string;
+}
+/** One or more shared contact cards. */
+export interface WhatsAppContactsMessage extends WhatsAppMessageBase {
+    type: 'contacts';
+    contacts: WhatsAppContactCard[];
+}
+/**
+ * A conversation event rather than a message: assignment changes, window notices, notes.
+ * Rendered centred, without a bubble.
+ */
+export interface WhatsAppSystemMessage extends WhatsAppMessageBase {
+    type: 'system';
+    text: string;
+}
+/** A message the backend could not normalize. Keeps the history complete. */
+export interface WhatsAppUnsupportedMessage extends WhatsAppMessageBase {
+    type: 'unsupported';
+    /** Explanation shown in place of the content. */
+    text?: string;
+}
+/**
+ * Any message in a conversation.
+ *
+ * A discriminated union on `type`: narrowing a message gives access to exactly the payload that
+ * type carries, and adding a member here is a compile error in every renderer that must handle
+ * it.
+ */
+export type WhatsAppMessageData = WhatsAppTextMessage | WhatsAppImageMessage | WhatsAppVideoMessage | WhatsAppAudioMessage | WhatsAppDocumentMessage | WhatsAppStickerMessage | WhatsAppTemplateMessage | WhatsAppInteractiveMessage | WhatsAppLocationMessage | WhatsAppContactsMessage | WhatsAppSystemMessage | WhatsAppUnsupportedMessage;
+/**
+ * State of the WhatsApp customer service window, as reported by the backend.
+ *
+ * The extension never computes this. WhatsApp's 24-hour rule depends on the provider's own clock
+ * and on message events the frontend does not see, so the backend stays authoritative and the
+ * components render whatever it says.
+ */
+export interface WhatsAppMessagingWindow {
+    /**
+     * Whether free-form messages are currently accepted. `unknown` leaves the composer in its
+     * normal state rather than blocking the user on information the backend did not send.
+     * @default 'unknown'
+     */
+    state: 'open' | 'closed' | 'unknown';
+    /** Machine readable reason, for consumers that map their own copy onto it. */
+    reasonCode?: string;
+    /** Backend-provided explanation shown to the user when the window is closed. */
+    reason?: string;
+    /** When an open window expires. Shown as a hint in the composer. */
+    expiresAt?: WhatsAppTimestamp;
+}
+/**
+ * What the consumer allows in a given conversation.
+ *
+ * Every composer action is driven by these flags. Nothing about WhatsApp's own rules is
+ * hard-coded: a provider that does not support list messages simply leaves `interactiveTypes`
+ * without `list`, and the editor stops offering it.
+ */
+export interface WhatsAppConversationCapabilities {
+    /**
+     * Whether free-form text may be sent. Treated as `false` while the messaging window is
+     * closed.
+     * @default true
+     */
+    canSendFreeForm?: boolean;
+    /**
+     * Whether approved templates may be sent. Stays available while the window is closed.
+     * @default false
+     */
+    canSendTemplates?: boolean;
+    /**
+     * Whether media may be attached.
+     * @default false
+     */
+    canSendMedia?: boolean;
+    /**
+     * Whether interactive messages may be composed.
+     * @default false
+     */
+    canSendInteractive?: boolean;
+    /**
+     * Whether the built-in emoji picker may be shown. The `emojiPicker` slot can replace it.
+     * @default false
+     */
+    canUseEmoji?: boolean;
+    /**
+     * Whether a message may be sent as a reply to another one.
+     * @default false
+     */
+    canReplyToMessage?: boolean;
+    /**
+     * Whether failed messages offer a retry action.
+     * @default true
+     */
+    canRetryFailed?: boolean;
+    /** Media types that may be attached. Defaults to all of them when `canSendMedia` is set. */
+    allowedMediaTypes?: WhatsAppMediaType[];
+    /** Interactive message types the provider supports. */
+    interactiveTypes?: WhatsAppInteractiveType[];
+    /** Largest accepted length of a free-form message. */
+    maxTextLength?: number;
+    /** Per media type file constraints, enforced before a file reaches the consumer. */
+    mediaConstraints?: Partial<Record<WhatsAppMediaType, WhatsAppMediaConstraints>>;
+    /** Messaging window state. Drives the closed-window notice. */
+    messagingWindow?: WhatsAppMessagingWindow;
+    /**
+     * Explanation shown when the composer is disabled for a reason other than the messaging
+     * window, for example a conversation the current agent may not write to.
+     */
+    disabledReason?: string;
+}
+/**
+ * `WhatsAppConversationCapabilities` with every optional flag filled in.
+ *
+ * Produced by `resolveCapabilities` for use by the composer and related components.
+ */
+export interface WhatsAppResolvedCapabilities {
+    canSendFreeForm: boolean;
+    canSendTemplates: boolean;
+    canSendMedia: boolean;
+    canSendInteractive: boolean;
+    canUseEmoji: boolean;
+    canReplyToMessage: boolean;
+    canRetryFailed: boolean;
+    allowedMediaTypes: WhatsAppMediaType[];
+    interactiveTypes: WhatsAppInteractiveType[];
+    maxTextLength: number | undefined;
+    mediaConstraints: Partial<Record<WhatsAppMediaType, WhatsAppMediaConstraints>>;
+    messagingWindow: WhatsAppMessagingWindow;
+    disabledReason: string | undefined;
+    /** Whether the messaging window explicitly reports itself as closed. */
+    windowClosed: boolean;
+    /** Whether anything at all can be sent right now. */
+    canSendAnything: boolean;
+}
+/** Open ended conversation status. Consumers define their own workflow states. */
+export type WhatsAppConversationStatus = 'open' | 'pending' | 'resolved' | 'snoozed' | 'archived' | (string & {});
+/** Colored label attached to a conversation. */
+export interface WhatsAppConversationLabel {
+    id: string;
+    name: string;
+    /** Key of `theme.colors` or any valid CSS color. */
+    color?: string;
+}
+/** Last message of a conversation, as shown in the list. */
+export interface WhatsAppConversationPreview {
+    /** Identifier of the previewed message. */
+    id?: string;
+    /** Type of the previewed message, used to pick the icon shown before the text. */
+    type?: WhatsAppMessageType;
+    /** Direction of the previewed message. Outbound previews show a delivery state. */
+    direction?: WhatsAppMessageDirection;
+    /** Delivery state of the previewed message. */
+    status?: WhatsAppDeliveryStatus;
+    /** Preview text. Falls back to a label derived from `type`. */
+    text?: string;
+    /** When the previewed message was created. */
+    timestamp?: WhatsAppTimestamp;
+}
+/** A conversation as it appears in the conversation list. */
+export interface WhatsAppConversationSummary {
+    /** Stable identifier. Used as the list key and as the selection value. */
+    id: string;
+    /** Person the conversation is with. */
+    contact: WhatsAppContact;
+    /** Last message, shown under the contact name. */
+    lastMessage?: WhatsAppConversationPreview;
+    /** Number of unread inbound messages. Renders the unread badge when above zero. */
+    unreadCount?: number;
+    /** Time of the latest activity. Drives the default ordering. */
+    updatedAt?: WhatsAppTimestamp;
+    /** Workflow status, used by the status filter. */
+    status?: WhatsAppConversationStatus;
+    /** Agent the conversation is assigned to, used by the assignment filter. */
+    assignee?: WhatsAppAssignee;
+    /** Pinned conversations sort above the rest. */
+    pinned?: boolean;
+    /** Muted conversations render a muted icon. */
+    muted?: boolean;
+    /** Labels shown as badges on the list item. */
+    labels?: WhatsAppConversationLabel[];
+    /** Anything the consumer needs to carry along. */
+    meta?: Record<string, unknown>;
+}
+/** A conversation opened in the conversation view. */
+export interface WhatsAppConversationData extends WhatsAppConversationSummary {
+    /** What may be sent in this conversation. */
+    capabilities?: WhatsAppConversationCapabilities;
+}
+/**
+ * Conversation list filters.
+ *
+ * The extension never applies these itself: it emits `filtersChange` and renders whatever list
+ * the consumer supplies next.
+ */
+export interface WhatsAppInboxFilters {
+    /** Free-text search query. */
+    query?: string;
+    /** Restricts the list to conversations with unread messages. */
+    unreadOnly?: boolean;
+    /** Assignee to filter by. `null` means unassigned, `undefined` means no filter. */
+    assigneeId?: string | null;
+    /** Status to filter by. `null` or `undefined` means no filter. */
+    status?: WhatsAppConversationStatus | null;
+    /** Label ids to filter by. */
+    labels?: string[];
+}
+/** Which filter controls the conversation list renders. */
+export interface WhatsAppInboxFiltersConfig {
+    /**
+     * Whether the search field is rendered.
+     * @default true
+     */
+    search?: boolean;
+    /**
+     * Whether the unread-only toggle is rendered.
+     * @default true
+     */
+    unread?: boolean;
+    /**
+     * Assignee options. The control is hidden when this is omitted, so a backend without
+     * assignment never shows a filter it cannot answer.
+     */
+    assignees?: WhatsAppAssignee[];
+    /** Status options. The control is hidden when this is omitted. */
+    statuses?: WhatsAppFilterOption[];
+}
+/** One option of a select-style filter. */
+export interface WhatsAppFilterOption {
+    value: string;
+    label: string;
+}
+/** Cursor state of a paginated list. Advanced by the consumer. */
+export interface WhatsAppPaginationState {
+    /** Whether another page can be requested. Renders the load-more affordance. */
+    hasMore?: boolean;
+    /** Whether a page request is in flight. */
+    loadingMore?: boolean;
+    /** Opaque cursor echoed back in the `loadMore` payload. */
+    cursor?: string | null;
+    /** Total number of records, when the backend reports one. */
+    total?: number;
+}
+/** Async state of one data set, for consumers building their own adapters. */
+export interface WhatsAppAsyncState {
+    /** Whether the initial load is in flight. */
+    loading?: boolean;
+    /** Failure of the last load. Renders the error state with a retry action. */
+    error?: string | null;
+}
+/** Members every outgoing payload shares. */
+export interface WhatsAppOutgoingMessageBase {
+    /** Conversation the message belongs to. */
+    conversationId: string;
+    /**
+     * Identifier generated by the composer. Use it to reconcile the optimistic message with the
+     * one the backend echoes back.
+     */
+    clientId: string;
+    /** Identifier of the message being replied to. */
+    replyTo?: string;
+}
+/** A free-form text message. */
+export interface WhatsAppOutgoingTextMessage extends WhatsAppOutgoingMessageBase {
+    kind: 'text';
+    text: string;
+}
+/** One or more uploaded attachments, with an optional shared caption. */
+export interface WhatsAppOutgoingMediaMessage extends WhatsAppOutgoingMessageBase {
+    kind: 'media';
+    attachments: WhatsAppAttachment[];
+    caption?: string;
+}
+/** A template with its placeholders filled in. */
+export interface WhatsAppOutgoingTemplateMessage extends WhatsAppOutgoingMessageBase {
+    kind: 'template';
+    /** Identifier of the selected template, when it has one. */
+    templateId?: string;
+    /** Template name as registered with the provider. */
+    name: string;
+    /** Language the template is sent in. */
+    language: string;
+    /** Values entered for the placeholders. */
+    values: WhatsAppTemplateValues;
+    /** The full definition, so the consumer does not have to look it up again. */
+    template: WhatsAppTemplate;
+}
+/** An interactive message composed in the editor. */
+export interface WhatsAppOutgoingInteractiveMessage extends WhatsAppOutgoingMessageBase {
+    kind: 'interactive';
+    interactive: WhatsAppInteractiveContent;
+}
+/**
+ * Anything the composer can ask the consumer to send.
+ *
+ * A discriminated union on `kind`, so a `switch` in the consumer's send handler is exhaustive.
+ */
+export type WhatsAppOutgoingMessage = WhatsAppOutgoingTextMessage | WhatsAppOutgoingMediaMessage | WhatsAppOutgoingTemplateMessage | WhatsAppOutgoingInteractiveMessage;
+/** A file the composer refused before it reached the consumer. */
+export interface WhatsAppRejectedFile {
+    file: File;
+    code: 'file-too-large' | 'file-invalid-type' | 'too-many-files';
+    message: string;
+}
+/** Files the user picked, handed to the consumer to upload. */
+export interface WhatsAppAttachmentsAddPayload {
+    /** Conversation the files were picked in, when the composer knows it. */
+    conversationId?: string;
+    /** Files that passed the configured constraints. */
+    files: File[];
+    /** Files that were rejected, with the reason. */
+    rejected: WhatsAppRejectedFile[];
+}
+/**
+ * A conversation the user wants to start with a number that is not in the list yet.
+ *
+ * The extension does not create anything: it validates the input and hands you the number, and
+ * your application decides whether that means creating a conversation, looking up an existing
+ * one, or refusing because the contact has not opted in.
+ */
+export interface WhatsAppNewConversationPayload {
+    /** Phone number exactly as the user typed it. */
+    phoneNumber: string;
+    /** Digits only, with a leading `+` when one was entered. Convenient as a lookup key. */
+    normalizedPhoneNumber: string;
+    /** Optional display name the user supplied alongside the number. */
+    name?: string;
+}
+/**
+ * How the composer treats an unsent draft when the conversation changes.
+ *
+ * `preserve` keeps one draft per conversation and restores it on return; `reset` drops the draft
+ * of the conversation being left.
+ */
+export type WhatsAppDraftBehavior = 'preserve' | 'reset';
+/** Payload of the `loadMore` event of a paginated list. */
+export interface WhatsAppLoadMorePayload {
+    /** Cursor of the current page, echoed from `pagination.cursor`. */
+    cursor?: string | null;
+}