@mantine-vue/whatsapp-inbox 3.2.0

package/lib/utils/capabilities.d.ts

@@ -0,0 +1,14 @@
+import type { WhatsAppConversationCapabilities, WhatsAppMediaType, WhatsAppMessagingWindow, WhatsAppResolvedCapabilities } from '../types';
+/** Media types offered when `canSendMedia` is set but `allowedMediaTypes` is not. */
+export declare const DEFAULT_ALLOWED_MEDIA_TYPES: WhatsAppMediaType[];
+/** Window state assumed when the backend did not report one. */
+export declare const UNKNOWN_MESSAGING_WINDOW: WhatsAppMessagingWindow;
+/**
+ * Fills in every capability default once, so no component repeats them.
+ *
+ * The only rule the frontend applies is the one it can apply safely: a *closed* window, as
+ * reported by the backend, turns free-form messaging off. Whether the window is closed is never
+ * derived from timestamps here — `state: 'unknown'` deliberately leaves the composer usable
+ * rather than guessing at WhatsApp's 24-hour rule.
+ */
+export declare function resolveCapabilities(capabilities: WhatsAppConversationCapabilities | undefined): WhatsAppResolvedCapabilities;

package/lib/utils/format.d.ts

@@ -0,0 +1,27 @@
+import type { WhatsAppInboxLabels } from '../labels';
+import type { WhatsAppTimestamp } from '../types';
+/**
+ * Converts any accepted timestamp to a `Date`, or `null` when it cannot be parsed.
+ *
+ * Invalid values return `null` so callers do not render `Invalid Date` or `NaN`.
+ */
+export declare function toDate(value: WhatsAppTimestamp | undefined | null): Date | null;
+/** Whether two dates fall on the same calendar day in the local timezone. */
+export declare function isSameDay(a: Date, b: Date): boolean;
+/** Start of the calendar day, used as the grouping key of the message list. */
+export declare function startOfDay(date: Date): Date;
+/** Time of day, as shown under a message bubble. */
+export declare function formatMessageTime(value: WhatsAppTimestamp, locale?: string): string;
+/** Full date and time, used as the `title` and screen-reader text of a message timestamp. */
+export declare function formatFullTimestamp(value: WhatsAppTimestamp, locale?: string): string;
+/** Day divider label: `Today`, `Yesterday`, a weekday within the last week, or a full date. */
+export declare function formatDayLabel(value: WhatsAppTimestamp, locale?: string, labels?: Pick<WhatsAppInboxLabels, 'today' | 'yesterday'>, now?: Date): string;
+/**
+ * Timestamp of a conversation list item: the time for today, `Yesterday`, a weekday within the
+ * last week, and a short date beyond that. This is what keeps the column narrow.
+ */
+export declare function formatConversationTime(value: WhatsAppTimestamp | undefined, locale?: string, labels?: Pick<WhatsAppInboxLabels, 'today' | 'yesterday'>, now?: Date): string;
+/** Human readable file size. Used by the attachment previews and by the size validation copy. */
+export declare function formatFileSize(bytes: number | undefined): string;
+/** `m:ss` duration, as shown on audio and video attachments. */
+export declare function formatDuration(seconds: number | undefined): string;

package/lib/utils/index.d.ts

@@ -0,0 +1,9 @@
+export { formatConversationTime, formatDayLabel, formatDuration, formatFileSize, formatFullTimestamp, formatMessageTime, isSameDay, startOfDay, toDate, } from './format';
+export { DEFAULT_ALLOWED_MEDIA_TYPES, UNKNOWN_MESSAGING_WINDOW, resolveCapabilities, } from './capabilities';
+export { createClientId, getContactDisplayName, getConversationActivityTime, getConversationPreviewText, getMessagePreviewText, getMessageTypeLabel, groupMessagesByDay, sortConversationsByActivity, } from './messages';
+export type { WhatsAppMessageGroup } from './messages';
+export { createEmptyTemplateValues, extractPlaceholders, filterTemplates, getTemplateBody, getTemplateButtons, getTemplateFooter, getTemplateHeader, getTemplateParameters, isTemplateSendable, renderTemplateText, validateTemplateValues, } from './templates';
+export type { WhatsAppTemplateButtonParameters, WhatsAppTemplateErrors, WhatsAppTemplateParameters, WhatsAppTemplateValidation, } from './templates';
+export { MAX_PHONE_NUMBER_DIGITS, MIN_PHONE_NUMBER_DIGITS, isValidPhoneNumber, normalizePhoneNumber, } from './phone';
+export { DEFAULT_MEDIA_ACCEPT, getAcceptAttribute, getMediaTypeFromMime, matchesAccept, validateFiles, } from './media';
+export type { ValidateFilesInput, ValidateFilesResult } from './media';

package/lib/utils/media.d.ts

@@ -0,0 +1,45 @@
+import type { WhatsAppInboxLabels } from '../labels';
+import type { WhatsAppMediaConstraints, WhatsAppMediaType, WhatsAppRejectedFile } from '../types';
+/**
+ * `accept` values offered per media type when the consumer does not configure its own.
+ *
+ * Deliberately broad: the authoritative list of what a provider accepts lives on the backend, and
+ * a consumer narrows this through `capabilities.mediaConstraints`.
+ */
+export declare const DEFAULT_MEDIA_ACCEPT: Record<WhatsAppMediaType, string[]>;
+/**
+ * Maps a MIME type onto the media type that decides which renderer is used.
+ *
+ * Never returns `sticker`: stickers are classified by the backend, a picked `.webp` file is an
+ * image. Anything unrecognized is a document, which is the renderer that degrades best.
+ */
+export declare function getMediaTypeFromMime(mimeType: string | undefined): WhatsAppMediaType;
+/** Value for the `accept` attribute of the composer file input. */
+export declare function getAcceptAttribute(allowedMediaTypes: WhatsAppMediaType[], constraints?: Partial<Record<WhatsAppMediaType, WhatsAppMediaConstraints>>): string;
+/** Whether a file matches any entry of an `accept` list. An empty list accepts everything. */
+export declare function matchesAccept(file: File, accept: string[] | undefined): boolean;
+/** Input of {@link validateFiles}. */
+export interface ValidateFilesInput {
+    /** Files the user picked. */
+    files: File[];
+    /** Media types the conversation accepts. */
+    allowedMediaTypes: WhatsAppMediaType[];
+    /** Per media type constraints from the conversation capabilities. */
+    constraints?: Partial<Record<WhatsAppMediaType, WhatsAppMediaConstraints>>;
+    /** Attachments already staged in the composer, counted against `maxFiles`. */
+    existingCount?: number;
+    /** Labels used to build the rejection messages. */
+    labels?: WhatsAppInboxLabels;
+}
+/** Files split into the ones the composer forwards and the ones it refused. */
+export interface ValidateFilesResult {
+    accepted: File[];
+    rejected: WhatsAppRejectedFile[];
+}
+/**
+ * Applies the configured file constraints before any file reaches the consumer.
+ *
+ * This is the only validation the extension performs on media, and every limit comes from
+ * `capabilities` rather than from a hard-coded provider table.
+ */
+export declare function validateFiles({ files, allowedMediaTypes, constraints, existingCount, labels, }: ValidateFilesInput): ValidateFilesResult;

package/lib/utils/messages.d.ts

@@ -0,0 +1,48 @@
+import type { WhatsAppInboxLabels } from '../labels';
+import type { WhatsAppConversationPreview, WhatsAppConversationSummary, WhatsAppMessageData, WhatsAppMessageType } from '../types';
+/** One calendar day of messages, as rendered between two day dividers. */
+export interface WhatsAppMessageGroup {
+    /** Stable key for the group, derived from the day. */
+    key: string;
+    /** Start of the day the group covers. `null` for messages without a usable timestamp. */
+    date: Date | null;
+    messages: WhatsAppMessageData[];
+}
+/**
+ * Splits a message list into calendar days, preserving the order it was given in.
+ *
+ * The list is not sorted: the consumer owns ordering, and re-sorting here would fight a backend
+ * that returns messages in its own sequence (for example threaded or cursor-paged results).
+ */
+export declare function groupMessagesByDay(messages: WhatsAppMessageData[]): WhatsAppMessageGroup[];
+/** Label used when a message type has no text of its own, for example a photo without caption. */
+export declare function getMessageTypeLabel(type: WhatsAppMessageType | undefined, labels?: WhatsAppInboxLabels): string;
+/**
+ * Single-line text for a message, used by conversation previews and by accessible names.
+ *
+ * Exhaustive over the message union, so adding a message type is a compile error here rather
+ * than an empty preview at runtime.
+ */
+export declare function getMessagePreviewText(message: WhatsAppMessageData, labels?: WhatsAppInboxLabels): string;
+/** Preview text of a conversation list item, falling back to a label derived from the type. */
+export declare function getConversationPreviewText(preview: WhatsAppConversationPreview | undefined, labels?: WhatsAppInboxLabels): string;
+/** Display name of a contact, falling back to the phone number and then to the id. */
+export declare function getContactDisplayName(conversation: WhatsAppConversationSummary): string;
+/** Time a conversation is ordered by: its last activity, then its last message. */
+export declare function getConversationActivityTime(conversation: WhatsAppConversationSummary): number;
+/**
+ * Copy of the list ordered by latest activity, pinned conversations first.
+ *
+ * Opt-in: `WhatsAppConversationList` renders the array it is given untouched unless `order` is
+ * set, because a server-side ordering (relevance, priority, custom queues) must not be silently
+ * overwritten by the UI.
+ */
+export declare function sortConversationsByActivity<T extends WhatsAppConversationSummary>(conversations: T[]): T[];
+/**
+ * Identifier attached to every outgoing payload so the consumer can reconcile its optimistic
+ * message with the one the backend echoes back.
+ *
+ * `crypto.randomUUID` when available, and a counter-plus-timestamp fallback for the environments
+ * that do not expose it (older Safari, non-secure contexts, some test runners).
+ */
+export declare function createClientId(): string;

package/lib/utils/phone.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Phone number handling for starting a conversation with a number that is not in the list yet.
+ *
+ * Deliberately permissive: the authoritative check is whichever provider the consumer uses, and
+ * a frontend that guessed at national formats would reject numbers the backend accepts. All this
+ * does is catch obvious typos before the payload is emitted.
+ */
+/** Digits only, keeping a leading `+`. Handy as a lookup key for an existing conversation. */
+export declare function normalizePhoneNumber(value: string): string;
+/**
+ * Shortest and longest number the default validation accepts.
+ *
+ * E.164 allows up to 15 digits; the lower bound is loose enough for short codes.
+ */
+export declare const MIN_PHONE_NUMBER_DIGITS = 6;
+export declare const MAX_PHONE_NUMBER_DIGITS = 15;
+/** Whether a number is plausible enough to send to the backend. */
+export declare function isValidPhoneNumber(value: string): boolean;

package/lib/utils/templates.d.ts

@@ -0,0 +1,65 @@
+import type { WhatsAppInboxLabels } from '../labels';
+import type { WhatsAppTemplate, WhatsAppTemplateBodyComponent, WhatsAppTemplateButton, WhatsAppTemplateButtonsComponent, WhatsAppTemplateFooterComponent, WhatsAppTemplateHeaderComponent, WhatsAppTemplateParameter, WhatsAppTemplateValues } from '../types';
+/** Placeholder keys used in a piece of template text, in order and without duplicates. */
+export declare function extractPlaceholders(text: string | undefined): string[];
+export declare function getTemplateHeader(template: WhatsAppTemplate | undefined): WhatsAppTemplateHeaderComponent | undefined;
+export declare function getTemplateBody(template: WhatsAppTemplate | undefined): WhatsAppTemplateBodyComponent | undefined;
+export declare function getTemplateFooter(template: WhatsAppTemplate | undefined): WhatsAppTemplateFooterComponent | undefined;
+export declare function getTemplateButtons(template: WhatsAppTemplate | undefined): WhatsAppTemplateButtonsComponent | undefined;
+/** Placeholders of one template button, together with the button and its index. */
+export interface WhatsAppTemplateButtonParameters {
+    index: number;
+    button: WhatsAppTemplateButton;
+    parameters: WhatsAppTemplateParameter[];
+}
+/** Everything the parameter form needs to know about a template. */
+export interface WhatsAppTemplateParameters {
+    header: WhatsAppTemplateParameter[];
+    body: WhatsAppTemplateParameter[];
+    buttons: WhatsAppTemplateButtonParameters[];
+    /** Header format, or `undefined` when the template has no header. */
+    headerFormat: WhatsAppTemplateHeaderComponent['format'] | undefined;
+    /** Whether the header expects a media file rather than text. */
+    requiresHeaderMedia: boolean;
+    /** Whether the template needs any input at all. */
+    hasParameters: boolean;
+}
+/** Collects every placeholder a template declares, grouped by the section it belongs to. */
+export declare function getTemplateParameters(template: WhatsAppTemplate | undefined): WhatsAppTemplateParameters;
+/** Empty value object matching a template's shape, used to seed the parameter form. */
+export declare function createEmptyTemplateValues(template: WhatsAppTemplate | undefined): WhatsAppTemplateValues;
+/** Field-level validation errors of a template parameter form. */
+export interface WhatsAppTemplateErrors {
+    header: Record<string, string>;
+    body: Record<string, string>;
+    buttons: Record<string, Record<string, string>>;
+    headerMedia?: string;
+}
+/** Result of validating a template parameter form. */
+export interface WhatsAppTemplateValidation {
+    valid: boolean;
+    errors: WhatsAppTemplateErrors;
+}
+/**
+ * Validates entered template values against the template's own declaration.
+ *
+ * Only the shape of the template drives this: nothing here knows which templates a particular
+ * provider accepts, which stays a backend decision surfaced through `WhatsAppTemplate.status`.
+ */
+export declare function validateTemplateValues(template: WhatsAppTemplate | undefined, values: WhatsAppTemplateValues, labels?: WhatsAppInboxLabels): WhatsAppTemplateValidation;
+/**
+ * Substitutes entered values into template text.
+ *
+ * Placeholders without a value keep their original form, so the preview shows the user exactly
+ * which variables are still empty.
+ */
+export declare function renderTemplateText(text: string | undefined, values: Record<string, string> | undefined): string;
+/** Whether a template may be sent, that is, whether the provider approved it. */
+export declare function isTemplateSendable(template: WhatsAppTemplate): boolean;
+/**
+ * Filters templates by a free-text query across name, description, category and body text.
+ *
+ * Client-side filtering of an already-supplied list, not a data-fetching concern: a consumer
+ * that searches server-side simply passes the filtered list and leaves the query empty.
+ */
+export declare function filterTemplates(templates: WhatsAppTemplate[], query: string): WhatsAppTemplate[];

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@mantine-vue/whatsapp-inbox",
+  "version": "3.2.0",
+  "description": "Backend-agnostic WhatsApp inbox components for Mantine Vue",
+  "license": "MIT",
+  "files": [
+    "cjs",
+    "esm",
+    "lib",
+    "styles.css",
+    "styles.layer.css",
+    "styles"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "main": "./cjs/index.cjs",
+  "module": "./esm/index.mjs",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/index.d.mts",
+        "default": "./esm/index.mjs"
+      },
+      "require": {
+        "types": "./lib/index.d.ts",
+        "default": "./cjs/index.cjs"
+      }
+    },
+    "./styles.css": "./styles.css",
+    "./styles.layer.css": "./styles.layer.css"
+  },
+  "devDependencies": {
+    "@mantine-vue/core": "workspace:*",
+    "@mantine-vue/hooks": "workspace:*",
+    "@vue/compiler-dom": "^3.5.0",
+    "@vue/test-utils": "^2.4.6",
+    "vue": "^3.5.0"
+  },
+  "peerDependencies": {
+    "@mantine-vue/core": "3.2.0",
+    "@mantine-vue/hooks": "3.2.0",
+    "vue": "^3.5.0"
+  }
+}