@webitel/ui-chats 26.8.3 → 26.8.5

package/src/v2/scripts/formatDate.ts

@@ -0,0 +1,74 @@
+import { getUserTimeZone } from '@webitel/api-services/utils';
+import { isSameDay, isSameYear } from 'date-fns';
+import { formatInTimeZone, toZonedTime } from 'date-fns-tz';
+
+/** App locale codes that are not BCP 47 tags `Intl` understands. */
+const INTL_LOCALE_ALIASES: Record<string, string> = {
+	kz: 'kk',
+	ua: 'uk',
+};
+
+const toIntlLocale = (locale: string) => {
+	const candidate = INTL_LOCALE_ALIASES[locale] ?? locale;
+	try {
+		return Intl.DateTimeFormat.supportedLocalesOf(candidate).length
+			? candidate
+			: 'en';
+	} catch {
+		return 'en';
+	}
+};
+
+/**
+ * Whether two instants fall on the same calendar day in `timeZone` — the
+ * operator's setting by default, the one the rest of the app formats with.
+ */
+export const isSameDayInZone = (
+	a: number,
+	b: number,
+	timeZone: string = getUserTimeZone(),
+): boolean => isSameDay(toZonedTime(a, timeZone), toZonedTime(b, timeZone));
+
+/** "Today" · "September 15" · "September 15, 2025" (AC_03.02.02). */
+export const formatDividerDate = (
+	timestamp: number,
+	{
+		locale,
+		todayLabel,
+		now = Date.now(),
+		timeZone = getUserTimeZone(),
+	}: {
+		locale: string;
+		todayLabel: string;
+		now?: number;
+		timeZone?: string;
+	},
+): string => {
+	if (isSameDayInZone(timestamp, now, timeZone)) return todayLabel;
+
+	const isThisYear = isSameYear(
+		toZonedTime(timestamp, timeZone),
+		toZonedTime(now, timeZone),
+	);
+
+	// Intl, not date-fns format: it has month names for every app locale
+	return new Intl.DateTimeFormat(toIntlLocale(locale), {
+		timeZone,
+		month: 'long',
+		day: 'numeric',
+		...(isThisYear
+			? {}
+			: {
+					year: 'numeric',
+				}),
+	}).format(timestamp);
+};
+
+/**
+ * 24h "HH:mm", as in DES-730, in the operator's time zone. Not the shared
+ * formatDate 'time' mode: its uk 'p' pattern drops the leading zero ("9:05").
+ */
+export const formatMessageTime = (
+	timestamp: number,
+	timeZone: string = getUserTimeZone(),
+): string => formatInTimeZone(timestamp, timeZone, 'HH:mm');

package/src/v2/scripts/getMessageStatus.ts

@@ -0,0 +1,59 @@
+import type { ChatMessageStatus, MessageModel, ThreadModel } from '../types';
+import { isContactCentreSide } from './isContactCentreSide';
+import { isSelfMessage } from './isSelfMessage';
+import { toSeq } from './toTimestamp';
+
+/**
+ * Sent / delivered / read for the operator's own messages, against the
+ * client's read horizon: the lowest horizon over every client member, so a
+ * message counts as read only once all clients have read it.
+ * `null` when no ticks should show.
+ */
+export const getMessageStatus = (
+	message: MessageModel,
+	thread: ThreadModel,
+	selfMemberId: string,
+): ChatMessageStatus | null => {
+	if (message.deleted || message.system) return null;
+	if (!isSelfMessage(message, thread, selfMemberId)) return null;
+
+	const seq = toSeq(message.seq);
+	if (seq === null) return 'sent';
+
+	const membersById = new Map(
+		(thread.members ?? []).flatMap((member) =>
+			member.id
+				? [
+						[
+							member.id,
+							member,
+						] as const,
+					]
+				: [],
+		),
+	);
+
+	const clientStates = (thread.readStates ?? []).filter((state) => {
+		const member =
+			state.member ??
+			(state.memberId ? membersById.get(state.memberId) : undefined);
+		return member !== undefined && !isContactCentreSide(member);
+	});
+
+	if (!clientStates.length) return 'sent';
+
+	const horizons = clientStates.map((state) => {
+		const read = toSeq(state.readUpToSeq) ?? 0;
+		// reading a message implies it was delivered, even if the delivered
+		// horizon lags behind
+		const delivered = Math.max(toSeq(state.deliveredUpToSeq) ?? 0, read);
+		return {
+			read,
+			delivered,
+		};
+	});
+
+	if (horizons.every((horizon) => seq <= horizon.read)) return 'read';
+	if (horizons.every((horizon) => seq <= horizon.delivered)) return 'delivered';
+	return 'sent';
+};

package/src/v2/scripts/isContactCentreSide.ts

@@ -0,0 +1,14 @@
+import type { ChatParticipant } from '../types';
+
+/**
+ * ⚠ Carried over from v1 (`chat-message.vue`, `member.type === 'webitel'`);
+ * not confirmed for the new IM backend. This is the one place to change it.
+ */
+export const INTERNAL_CONTACT_TYPE = 'webitel';
+
+/** Operators and bots speak for the contact centre; everyone else is the client. */
+export const isContactCentreSide = (
+	member: ChatParticipant | undefined,
+): boolean =>
+	member?.contact?.type === INTERNAL_CONTACT_TYPE ||
+	member?.contact?.isBot === true;

package/src/v2/scripts/isSelfMessage.ts

@@ -0,0 +1,29 @@
+import type { MessageModel, ThreadModel } from '../types';
+
+/**
+ * Whether the operator using the UI sent this message.
+ *
+ * Member ids are per membership: an operator who is removed and added again
+ * gets a new one, while `thread.members` (and so `selfMemberId`) may still
+ * hold the old. So an id match is not enough; the stable identity is the
+ * contact — same subject from the same issuer as the operator's own member.
+ */
+export const isSelfMessage = (
+	message: MessageModel,
+	thread: ThreadModel,
+	selfMemberId: string,
+): boolean => {
+	const sender = message.sender;
+	if (!sender?.id || !selfMemberId) return false;
+	if (sender.id === selfMemberId) return true;
+
+	const self = thread.members?.find((member) => member.id === selfMemberId);
+	const selfContact = self?.contact;
+	const senderContact = sender.contact;
+
+	return (
+		!!selfContact?.sub &&
+		selfContact.sub === senderContact?.sub &&
+		selfContact.iss === senderContact?.iss
+	);
+};

package/src/v2/scripts/resolveSystemNotice.ts

@@ -0,0 +1,119 @@
+import type {
+	ChatNoticeTone,
+	ChatParticipant,
+	MessageModel,
+	ThreadModel,
+} from '../types';
+
+export interface SystemNoticeDefinition {
+	/** relative to the v2 locale namespace */
+	textKey: string;
+	tone: ChatNoticeTone;
+}
+
+/**
+ * ⚠ WS-22 (backend, "Need info"): only `member_added`, `member_removed` and
+ * `transferred` are documented. The started / accepted / closed type strings
+ * are assumed — confirm them there and change only this table.
+ */
+export const SYSTEM_NOTICES: Record<string, SystemNoticeDefinition> = {
+	thread_started: {
+		textKey: 'systemNotice.started',
+		tone: 'positive',
+	},
+	member_added: {
+		textKey: 'systemNotice.joined',
+		tone: 'neutral',
+	},
+	thread_accepted: {
+		textKey: 'systemNotice.accepted',
+		tone: 'neutral',
+	},
+	transferred: {
+		textKey: 'systemNotice.transferred',
+		tone: 'neutral',
+	},
+	member_removed: {
+		textKey: 'systemNotice.left',
+		tone: 'neutral',
+	},
+	thread_closed: {
+		textKey: 'systemNotice.ended',
+		tone: 'negative',
+	},
+};
+
+/** ⚠ WS-22: the metadata key carrying the acting member's id is unconfirmed. */
+const ACTOR_METADATA_KEYS = [
+	// chat-web-sdk's memberAdded / memberLeft socket payloads use these
+	'newMemberId',
+	'new_member_id',
+	'removedMemberId',
+	'removed_member_id',
+	'memberId',
+	'member_id',
+	'actorId',
+	'actor_id',
+] as const;
+
+export interface ResolvedSystemNotice {
+	/** null when `fallbackText` should be shown instead */
+	textKey: string | null;
+	/** the backend's own text, for types the table does not know */
+	fallbackText: string | null;
+	tone: ChatNoticeTone;
+	actor: ChatParticipant | undefined;
+}
+
+const findActor = (
+	message: MessageModel,
+	thread: ThreadModel,
+): ChatParticipant | undefined => {
+	const metadata = (message.system?.metadata ?? {}) as Record<string, unknown>;
+	const members = thread.members ?? [];
+
+	const actorId = ACTOR_METADATA_KEYS.map((key) => metadata[key]).find(
+		(value): value is string => typeof value === 'string' && value !== '',
+	);
+	const byActorId = actorId
+		? members.find((member) => member.id === actorId)
+		: undefined;
+	if (byActorId) return byActorId;
+
+	const senderId = message.sender?.id;
+	const bySender = senderId
+		? members.find((member) => member.id === senderId)
+		: undefined;
+	// a member who has left is no longer in thread.members — the sender's own
+	// enriched contact still carries the name
+	return bySender ?? message.sender;
+};
+
+export const resolveSystemNotice = (
+	message: MessageModel,
+	thread: ThreadModel,
+): ResolvedSystemNotice => {
+	const type = message.system?.type;
+	const definition = type ? SYSTEM_NOTICES[type] : undefined;
+	const actor = findActor(message, thread);
+
+	if (definition) {
+		return {
+			textKey: definition.textKey,
+			fallbackText: null,
+			tone: definition.tone,
+			actor,
+		};
+	}
+
+	return {
+		textKey: message.body ? null : 'systemNotice.unknown',
+		fallbackText: message.body || null,
+		tone: 'neutral',
+		actor,
+	};
+};
+
+/** Display name, or '' when the participant carries none. */
+export const participantName = (member: ChatParticipant | undefined): string =>
+	member?.contact?.name || member?.contact?.username || '';

package/src/v2/scripts/toHistoryItems.ts

@@ -0,0 +1,63 @@
+import { getUserTimeZone } from '@webitel/api-services/utils';
+import type { MessageModel } from '../types';
+
+import { isSameDayInZone } from './formatDate';
+import { toTimestamp } from './toTimestamp';
+
+export type ChatHistoryItem =
+	| {
+			kind: 'divider';
+			key: string;
+			/** timestamp of the first item of that day */
+			date: number;
+	  }
+	| {
+			kind: 'message' | 'system';
+			key: string;
+			message: MessageModel;
+	  };
+
+/**
+ * Messages (oldest → newest) as render rows, with a divider before the first
+ * item of each calendar day in `timeZone` (the operator's setting by default).
+ * Items without a usable `createdAt` never open a new day.
+ */
+export const toHistoryItems = (
+	messages: readonly MessageModel[],
+	{
+		timeZone = getUserTimeZone(),
+	}: {
+		timeZone?: string;
+	} = {},
+): ChatHistoryItem[] => {
+	const items: ChatHistoryItem[] = [];
+	// timestamp of the item that opened the current day
+	let currentDayStart: number | null = null;
+
+	for (const message of messages) {
+		const timestamp = toTimestamp(message.createdAt);
+
+		if (timestamp !== null) {
+			if (
+				currentDayStart === null ||
+				!isSameDayInZone(currentDayStart, timestamp, timeZone)
+			) {
+				items.push({
+					kind: 'divider',
+					// keyed by the day's first message: a day can recur out of order
+					key: `divider-${message.id}`,
+					date: timestamp,
+				});
+				currentDayStart = timestamp;
+			}
+		}
+
+		items.push({
+			kind: message.system ? 'system' : 'message',
+			key: message.id,
+			message,
+		});
+	}
+
+	return items;
+};

package/src/v2/scripts/toTimestamp.ts

@@ -0,0 +1,21 @@
+/** Backend timestamps are Unix ms as strings; `null` when absent or unusable. */
+export const toTimestamp = (
+	value: string | number | undefined | null,
+): number | null => {
+	if (value === undefined || value === null || value === '') return null;
+	const parsed = Number(value);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+};
+
+/**
+ * Per-thread message sequence numbers arrive as strings. Compare them as
+ * numbers: as strings, "10" sorts before "9".
+ */
+export const toSeq = (
+	value: string | number | null | undefined,
+): number | null => {
+	// typed string | undefined, but JSON can carry null, and Number(null) is 0
+	if (value === undefined || value === null || value === '') return null;
+	const parsed = Number(value);
+	return Number.isFinite(parsed) ? parsed : null;
+};

package/src/v2/types/index.ts

@@ -0,0 +1,74 @@
+import type { MessageModel, ThreadModel } from '@webitel/chat-web-sdk';
+
+export type { MessageModel, ThreadModel };
+
+export const ChatThreadMode = {
+	/** offered to the operator, not accepted yet: no composer, waiting line */
+	Awaiting: 'awaiting',
+	Active: 'active',
+	/** closed or otherwise not writable: no composer */
+	Readonly: 'readonly',
+} as const;
+
+export type ChatThreadMode =
+	(typeof ChatThreadMode)[keyof typeof ChatThreadMode];
+
+export const ChatComposerAction = {
+	Attach: 'attach',
+	Emoji: 'emoji',
+	Send: 'send',
+} as const;
+
+export type ChatComposerAction =
+	(typeof ChatComposerAction)[keyof typeof ChatComposerAction];
+
+export type ChatMessageStatus = 'sent' | 'delivered' | 'read';
+
+export type ChatNoticeTone = 'positive' | 'neutral' | 'negative';
+
+/** A thread member as it arrives on `message.sender` and `thread.members[]`. */
+export type ChatParticipant = NonNullable<MessageModel['sender']>;
+
+export type ChatImage = NonNullable<MessageModel['images']>[number];
+
+export type ChatDocument = NonNullable<MessageModel['documents']>[number];
+
+export type ResolveAvatarUrl = (member: ChatParticipant) => string | undefined;
+
+export type ChatSendHandler = (text: string) => Promise<unknown>;
+
+export type ChatAttachHandler = (files: File[]) => Promise<unknown>;
+
+export type ChatLoadMoreHandler = () => Promise<unknown>;
+
+export interface ChatComposerSlotProps {
+	/** inserts at the cursor (or appends) and updates the draft */
+	insertText: (text: string) => void;
+	focus: () => void;
+	disabled: boolean;
+}
+
+export interface ChatHistoryProps {
+	thread: ThreadModel;
+	/** oldest → newest; current and earlier sessions */
+	messages: MessageModel[];
+	/** thread-member id of the operator using the UI */
+	selfMemberId: string;
+	mode?: ChatThreadMode;
+	hasMore?: boolean;
+	onLoadMore?: ChatLoadMoreHandler;
+	resolveAvatarUrl?: ResolveAvatarUrl;
+}
+
+export interface ChatComposerProps {
+	onSend?: ChatSendHandler;
+	onAttach?: ChatAttachHandler;
+	actions?: ChatComposerAction[];
+	submitOnEnter?: boolean;
+	disabled?: boolean;
+}
+
+export interface ChatThreadProps extends ChatHistoryProps, ChatComposerProps {
+	/** controlled draft (v-model:draft); omit to let the composer own it */
+	draft?: string;
+}

package/src/v2/ui/__tests__/mountWithChats.ts

@@ -0,0 +1,38 @@
+import { mount } from '@vue/test-utils';
+import { createI18n } from 'vue-i18n';
+
+import { messages } from '../../../locale';
+
+export const chatsI18n = () =>
+	createI18n({
+		legacy: false,
+		locale: 'en',
+		fallbackLocale: 'en',
+		messages,
+	});
+
+export const mountWithChats: typeof mount = ((component, options = {}) =>
+	mount(component, {
+		...options,
+		global: {
+			...options.global,
+			plugins: [
+				...(options.global?.plugins ?? []),
+				chatsI18n(),
+			],
+		},
+	})) as typeof mount;
+
+export const deferred = <T = void>() => {
+	let resolve!: (value: T) => void;
+	let reject!: (reason?: unknown) => void;
+	const promise = new Promise<T>((res, rej) => {
+		resolve = res;
+		reject = rej;
+	});
+	return {
+		promise,
+		resolve,
+		reject,
+	};
+};