@joinskips/brand 9.0.0-develop.147 → 9.0.0-develop.148

package/chat/helpers/cable.d.ts

@@ -0,0 +1,34 @@
+import { type ChatEvent } from './cableFrames.ts';
+export declare const STALE_MS = 10000;
+export declare const FIRST_RETRY_MS = 1000;
+export declare const MAX_RETRY_MS = 30000;
+export type CableState = 'connecting' | 'live' | 'down';
+export interface CableOptions {
+    careTeamName: string;
+    createSocket: (url: string) => Socket;
+    now: () => number;
+}
+export interface CableHandlers {
+    onEvent: (event: ChatEvent) => void;
+    onState: (state: CableState) => void;
+    onKeysRefused: () => void;
+}
+/** The socket address for a Skips App origin, such as https://app.joinskips.com. */
+export declare const cableUrl: (origin: string) => string;
+/** The wait before the nth reconnect, doubling up to MAX_RETRY_MS. */
+export declare const retryDelay: (attempt: number) => number;
+export interface SocketMessage {
+    data: unknown;
+}
+export interface Socket extends Pick<WebSocket, 'send' | 'close'> {
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: SocketMessage) => void) | null;
+    onclose: ((event: unknown) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+}
+/**
+ * Opens the feed for the member's keys, the Skips App's pubsub tokens, on sockets the app makes with createSocket.
+ * now is the app's clock, which the stale check reads.
+ * Returns a function that closes it for good.
+ */
+export declare function openCable(url: string, keys: string[], handlers: CableHandlers, { careTeamName, createSocket, now }: CableOptions): () => void;

package/chat/helpers/cable.js

@@ -0,0 +1,88 @@
+// A small ActionCable client for the Skips App's RoomChannel. It says when the feed is live or down, so a silent drop
+// never goes unnoticed: no frame for STALE_MS counts as down, and it reconnects with backoff. The Skips App pings
+// every 3 seconds.
+import { readFrame } from "./cableFrames.js";
+export const STALE_MS = 10_000;
+export const FIRST_RETRY_MS = 1_000;
+export const MAX_RETRY_MS = 30_000;
+/** The socket address for a Skips App origin, such as https://app.joinskips.com. */
+export const cableUrl = (origin) => `${origin.replace(/\/$/, '').replace(/^http/, 'ws')}/cable`;
+/** The wait before the nth reconnect, doubling up to MAX_RETRY_MS. */
+export const retryDelay = (attempt) => Math.min(MAX_RETRY_MS, FIRST_RETRY_MS * 2 ** attempt);
+/**
+ * Opens the feed for the member's keys, the Skips App's pubsub tokens, on sockets the app makes with createSocket.
+ * now is the app's clock, which the stale check reads.
+ * Returns a function that closes it for good.
+ */
+export function openCable(url, keys, handlers, { careTeamName, createSocket, now }) {
+    let socket = null;
+    let attempt = 0;
+    let lastFrameAt = now();
+    let closed = false;
+    let retry = null;
+    let state = null;
+    const setState = (next) => {
+        if (next !== state)
+            handlers.onState((state = next));
+    };
+    const drop = (reconnect) => {
+        if (socket) {
+            const old = socket;
+            socket = null;
+            old.onclose = old.onmessage = old.onerror = old.onopen = null;
+            old.close();
+        }
+        setState('down');
+        if (reconnect && !closed && !retry)
+            retry = setTimeout(connect, retryDelay(attempt++));
+    };
+    function connect() {
+        retry = null;
+        setState('connecting');
+        lastFrameAt = now();
+        const next = createSocket(url);
+        socket = next;
+        next.onmessage = ({ data }) => {
+            lastFrameAt = now();
+            const frame = readFrame(String(data), careTeamName);
+            if (frame.type === 'welcome') {
+                attempt = 0;
+                for (const key of keys) {
+                    next.send(JSON.stringify({
+                        command: 'subscribe',
+                        identifier: JSON.stringify({ channel: 'RoomChannel', pubsub_token: key }),
+                    }));
+                }
+            }
+            else if (frame.type === 'confirm_subscription')
+                setState('live');
+            else if (frame.type === 'event')
+                handlers.onEvent(frame.event);
+            else if (frame.type === 'reject_subscription' || (frame.type === 'disconnect' && !frame.reconnect)) {
+                drop(false);
+                handlers.onKeysRefused();
+            }
+            else if (frame.type === 'disconnect')
+                drop(true);
+        };
+        next.onclose = () => {
+            drop(true);
+        };
+        next.onerror = () => {
+            drop(true);
+        };
+    }
+    const watchdog = setInterval(() => {
+        if (socket && now() - lastFrameAt > STALE_MS)
+            drop(true);
+    }, STALE_MS / 2);
+    connect();
+    return () => {
+        closed = true;
+        clearInterval(watchdog);
+        if (retry)
+            clearTimeout(retry);
+        retry = null;
+        drop(false);
+    };
+}

package/chat/helpers/cableFrames.d.ts

@@ -0,0 +1,40 @@
+import type { ChatMessage } from './message.ts';
+interface ChatMessageEvent {
+    kind: 'message';
+    conversationId: number;
+    message: ChatMessage;
+}
+interface TypingEvent {
+    kind: 'typing';
+    conversationId: number;
+    typing: boolean;
+    name: string;
+}
+interface ConversationEvent {
+    kind: 'conversation';
+    conversationId: number;
+}
+export type ChatEvent = ChatMessageEvent | TypingEvent | ConversationEvent;
+type ControlType = 'welcome' | 'ping' | 'confirm_subscription' | 'reject_subscription';
+interface ControlFrame {
+    type: ControlType;
+}
+interface DisconnectFrame {
+    type: 'disconnect';
+    reconnect: boolean;
+}
+interface EventFrame {
+    type: 'event';
+    event: ChatEvent;
+}
+interface IgnoredFrame {
+    type: 'ignored';
+}
+/** One ActionCable frame: a control frame the client handles, or a Skips App event. */
+export type CableFrame = ControlFrame | DisconnectFrame | EventFrame | IgnoredFrame;
+/**
+ * Reads one frame of text from the socket. A frame that is not JSON, or not one the app knows, is ignored.
+ * careTeamName is the app's name for a care team line with no named sender (toChatMessage).
+ */
+export declare function readFrame(text: string, careTeamName: string): CableFrame;
+export {};

package/chat/helpers/cableFrames.js

@@ -0,0 +1,70 @@
+// What the Skips App's live socket says, read into the few things an app acts on. Shapes come from the socket itself
+// (message_type and created_at as numbers, the member's own typing never sent back), and anything else is ignored.
+import { firstFilled, isNullableString, isObject, isRawMessage, optional, toChatMessage } from "./skipsMessage.js";
+const CONTROL_TYPES = ['welcome', 'ping', 'confirm_subscription', 'reject_subscription'];
+const IGNORED = { type: 'ignored' };
+function isTypingData(value) {
+    if (!isObject(value) || !isObject(value.user) || !isObject(value.conversation))
+        return false;
+    const { user } = value;
+    return (optional(value.is_private, (flag) => typeof flag === 'boolean') &&
+        optional(user.type, (type) => typeof type === 'string') &&
+        optional(user.available_name, isNullableString) &&
+        optional(user.name, isNullableString) &&
+        typeof value.conversation.id === 'number');
+}
+const fieldIn = (value, key) => (isObject(value) ? value[key] : undefined);
+function toEvent(message, careTeamName) {
+    const event = fieldIn(message, 'event');
+    const data = fieldIn(message, 'data');
+    switch (event) {
+        case 'message.created':
+        case 'message.updated': {
+            if (!isRawMessage(data))
+                return null;
+            const chatMessage = toChatMessage(data, careTeamName);
+            return chatMessage ? { kind: 'message', conversationId: data.conversation_id ?? 0, message: chatMessage } : null;
+        }
+        case 'conversation.typing_on':
+        case 'conversation.typing_off': {
+            // A private note's typing is the care team's own, and a contact's typing is the member's.
+            if (!isTypingData(data) || data.is_private || data.user.type === 'contact')
+                return null;
+            return {
+                kind: 'typing',
+                conversationId: data.conversation.id,
+                typing: event === 'conversation.typing_on',
+                name: firstFilled(data.user.available_name, data.user.name) ?? '',
+            };
+        }
+        // Only which conversation changed: its fields on the socket can be partial, so the app asks for them again.
+        case 'conversation.updated':
+        case 'conversation.status_changed': {
+            const id = fieldIn(data, 'id');
+            return typeof id === 'number' ? { kind: 'conversation', conversationId: id } : null;
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * Reads one frame of text from the socket. A frame that is not JSON, or not one the app knows, is ignored.
+ * careTeamName is the app's name for a care team line with no named sender (toChatMessage).
+ */
+export function readFrame(text, careTeamName) {
+    let frame;
+    try {
+        frame = JSON.parse(text);
+    }
+    catch {
+        return IGNORED;
+    }
+    const type = fieldIn(frame, 'type');
+    if (type === 'disconnect')
+        return { type: 'disconnect', reconnect: fieldIn(frame, 'reconnect') !== false };
+    const control = CONTROL_TYPES.find((each) => each === type);
+    if (control)
+        return { type: control };
+    const event = toEvent(fieldIn(frame, 'message'), careTeamName);
+    return event ? { type: 'event', event } : IGNORED;
+}

package/chat/helpers/index.d.ts

@@ -4,4 +4,7 @@ export { CLUSTER_GAP_MS, EMPTY_THREAD, groupThread, pendingId, withFailed, witho
 export { TYPING_CLEAR_MS, TYPING_IDLE_MS, createTypingSignal, createTypingWatch } from './typing.ts';
 export { DOT_CYCLE_MS, TYPING_IDLE, TYPING_TIMES, heldFrom, typingReducer, type TypingEvent, type TypingSignal, type TypingStarted, type TypingState, type TypingTimes, } from './skipTyping.ts';
 export { fitVisibleArea, type Fit, type VisualViewportBox } from './visibleArea.ts';
+export { FIRST_RETRY_MS, MAX_RETRY_MS, STALE_MS, cableUrl, openCable, retryDelay, type CableHandlers, type CableOptions, type CableState, type Socket, type SocketMessage, } from './cable.ts';
+export { readFrame, type CableFrame, type ChatEvent } from './cableFrames.ts';
+export { CHOICE_CONTENT_TYPE, choiceFrom, fileNameIn, firstFilled, fromContact, isRawMessage, toChatMessage, toMs, type RawMessage, type RawMessageFile, type RawSender, } from './skipsMessage.ts';
 export { EMAIL_MAX_LENGTH, NAME_MAX_LENGTH, RESEND_AFTER_MS, WELCOME_TYPING_TIMES, givenEmail, givenName, isEmail, isName, typesBefore, typingMs, type WelcomeStep, type WelcomeTypingTimes, } from './welcome.ts';

package/chat/helpers/index.js

@@ -4,4 +4,7 @@ export { CLUSTER_GAP_MS, EMPTY_THREAD, groupThread, pendingId, withFailed, witho
 export { TYPING_CLEAR_MS, TYPING_IDLE_MS, createTypingSignal, createTypingWatch } from "./typing.js";
 export { DOT_CYCLE_MS, TYPING_IDLE, TYPING_TIMES, heldFrom, typingReducer, } from "./skipTyping.js";
 export { fitVisibleArea } from "./visibleArea.js";
+export { FIRST_RETRY_MS, MAX_RETRY_MS, STALE_MS, cableUrl, openCable, retryDelay, } from "./cable.js";
+export { readFrame } from "./cableFrames.js";
+export { CHOICE_CONTENT_TYPE, choiceFrom, fileNameIn, firstFilled, fromContact, isRawMessage, toChatMessage, toMs, } from "./skipsMessage.js";
 export { EMAIL_MAX_LENGTH, NAME_MAX_LENGTH, RESEND_AFTER_MS, WELCOME_TYPING_TIMES, givenEmail, givenName, isEmail, isName, typesBefore, typingMs, } from "./welcome.js";

package/chat/helpers/skipsMessage.d.ts

@@ -0,0 +1,52 @@
+import type { ChatMessage, MessageChoice } from './message.ts';
+export interface RawSender {
+    id?: number;
+    type?: string;
+    name?: string | null;
+    available_name?: string | null;
+    thumbnail?: string | null;
+}
+export interface RawMessageFile {
+    file_type?: string;
+    data_url?: string;
+    thumb_url?: string | null;
+    file_name?: string | null;
+}
+/** A message as the Skips App's API and its socket give it. The socket spells message_type as a word. */
+export interface RawMessage {
+    id: number;
+    conversation_id?: number;
+    content: string | null;
+    message_type: number | string;
+    created_at: number | string;
+    private?: boolean;
+    sender?: RawSender | null;
+    attachments?: RawMessageFile[];
+    content_type?: unknown;
+    content_attributes?: unknown;
+}
+export type JsonObject = Record<string, unknown>;
+export declare const isObject: (value: unknown) => value is JsonObject;
+export declare const isNullableString: (value: unknown) => value is string | null;
+export declare const optional: (value: unknown, check: (value: unknown) => boolean) => boolean;
+/** Whether a value from the Skips App has a message's shape, every field it carries checked. */
+export declare function isRawMessage(value: unknown): value is RawMessage;
+/** The first value that holds text, an empty string counting as none, or undefined when none does. */
+export declare const firstFilled: (...values: (string | null | undefined)[]) => string | undefined;
+/** A file's name from its Skips App address, which ends with it. */
+export declare const fileNameIn: (url: string) => string;
+export declare const fromContact: (raw: RawMessage) => boolean;
+/** A Skips App time in milliseconds: the API gives seconds, the socket text. */
+export declare const toMs: (value: number | string) => number;
+export declare const CHOICE_CONTENT_TYPE = "input_select";
+/**
+ * A question's buttons, with the answer already given if it is one of them. A message of another type, or one whose
+ * buttons cannot all be read, offers none: a button with no words could not be pressed knowingly. Nor does one with
+ * two buttons of the same value, since the answer kept could not say which was pressed.
+ */
+export declare function choiceFrom(contentType: unknown, attributes: unknown): MessageChoice | null;
+/**
+ * The member's view of a message, or null when it is a private note or an activity the member does not see.
+ * careTeamName, the app's own words, names a care team line whose sender the Skips App leaves unnamed.
+ */
+export declare function toChatMessage(raw: RawMessage, careTeamName: string): ChatMessage | null;

package/chat/helpers/skipsMessage.js

@@ -0,0 +1,129 @@
+// A Skips App message as its API and its live socket give it, and the member's view of it. Neither ever shows the
+// member a private note or an internal activity line.
+export const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isNumber = (value) => typeof value === 'number';
+const isString = (value) => typeof value === 'string';
+const isBoolean = (value) => typeof value === 'boolean';
+const isNumberOrString = (value) => isNumber(value) || isString(value);
+export const isNullableString = (value) => value === null || isString(value);
+// A field left out passes, and a field that is there must have its type.
+export const optional = (value, check) => value === undefined || check(value);
+function isRawSender(value) {
+    return (isObject(value) &&
+        optional(value.id, isNumber) &&
+        optional(value.type, isString) &&
+        optional(value.name, isNullableString) &&
+        optional(value.available_name, isNullableString) &&
+        optional(value.thumbnail, isNullableString));
+}
+function isRawMessageFile(value) {
+    return (isObject(value) &&
+        optional(value.file_type, isString) &&
+        optional(value.data_url, isString) &&
+        optional(value.thumb_url, isNullableString) &&
+        optional(value.file_name, isNullableString));
+}
+/** Whether a value from the Skips App has a message's shape, every field it carries checked. */
+export function isRawMessage(value) {
+    return (isObject(value) &&
+        isNumber(value.id) &&
+        optional(value.conversation_id, isNumber) &&
+        isNullableString(value.content) &&
+        isNumberOrString(value.message_type) &&
+        isNumberOrString(value.created_at) &&
+        optional(value.private, isBoolean) &&
+        optional(value.sender, (sender) => sender === null || isRawSender(sender)) &&
+        optional(value.attachments, (files) => Array.isArray(files) && files.every(isRawMessageFile)));
+}
+/** The first value that holds text, an empty string counting as none, or undefined when none does. */
+export const firstFilled = (...values) => values.find((value) => Boolean(value));
+/** A file's name from its Skips App address, which ends with it. */
+export const fileNameIn = (url) => {
+    let path = url;
+    try {
+        path = new URL(url).pathname;
+    }
+    catch {
+        // Not a full address: its last part is still the best name there is.
+    }
+    const name = path.slice(path.lastIndexOf('/') + 1);
+    try {
+        return decodeURIComponent(name);
+    }
+    catch {
+        return name;
+    }
+};
+// message_type 0 is the contact's, 2 an activity. The socket sends the names instead of the numbers.
+export const fromContact = (raw) => raw.sender?.type === 'contact' || raw.message_type === 0 || raw.message_type === 'incoming';
+const isActivity = (raw) => raw.message_type === 2 || raw.message_type === 'activity';
+// Of the Skips App's activity lines, only a conversation closing or reopening is the member's business.
+const NOTICE = /conversation was (resolved|reopened)|(resolved|reopened) the conversation/i;
+/** A Skips App time in milliseconds: the API gives seconds, the socket text. */
+export const toMs = (value) => (typeof value === 'number' ? value * 1000 : Date.parse(value));
+// The Skips App's question answered with one of its buttons.
+export const CHOICE_CONTENT_TYPE = 'input_select';
+function isChoiceItem(value) {
+    return (isObject(value) &&
+        isString(value.title) &&
+        value.title.trim().length > 0 &&
+        isString(value.value) &&
+        value.value.length > 0);
+}
+/**
+ * A question's buttons, with the answer already given if it is one of them. A message of another type, or one whose
+ * buttons cannot all be read, offers none: a button with no words could not be pressed knowingly. Nor does one with
+ * two buttons of the same value, since the answer kept could not say which was pressed.
+ */
+export function choiceFrom(contentType, attributes) {
+    if (contentType !== CHOICE_CONTENT_TYPE || !isObject(attributes))
+        return null;
+    const { items, submitted_values: submitted } = attributes;
+    if (!Array.isArray(items) || items.length === 0 || !items.every(isChoiceItem))
+        return null;
+    if (new Set(items.map((item) => item.value)).size !== items.length)
+        return null;
+    const first = Array.isArray(submitted) ? submitted[0] : null;
+    const given = isObject(first) ? first.value : null;
+    const chosen = items.find((item) => item.value === given)?.value ?? null;
+    return { items, chosen };
+}
+/**
+ * The member's view of a message, or null when it is a private note or an activity the member does not see.
+ * careTeamName, the app's own words, names a care team line whose sender the Skips App leaves unnamed.
+ */
+export function toChatMessage(raw, careTeamName) {
+    if (raw.private)
+        return null;
+    const notice = isActivity(raw);
+    if (notice && !NOTICE.test(raw.content ?? ''))
+        return null;
+    const mine = !notice && fromContact(raw);
+    const choice = mine || notice ? null : choiceFrom(raw.content_type, raw.content_attributes);
+    return {
+        ...(choice === null ? {} : { choice }),
+        id: raw.id,
+        text: raw.content ?? '',
+        sentAt: toMs(raw.created_at),
+        mine,
+        notice,
+        author: mine || notice
+            ? null
+            : {
+                id: raw.sender?.id ?? null,
+                name: firstFilled(raw.sender?.available_name, raw.sender?.name) ?? careTeamName,
+                avatarUrl: firstFilled(raw.sender?.thumbnail) ?? null,
+                bot: raw.sender?.type === 'agent_bot',
+            },
+        attachments: (raw.attachments ?? []).flatMap((a) => a.data_url
+            ? [
+                {
+                    kind: a.file_type === 'image' ? 'image' : 'file',
+                    url: a.data_url,
+                    thumbUrl: a.thumb_url ?? null,
+                    name: firstFilled(a.file_name) ?? fileNameIn(a.data_url),
+                },
+            ]
+            : []),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joinskips/brand",
-  "version": "9.0.0-develop.147",
+  "version": "9.0.0-develop.148",
   "description": "Skips design tokens, Onest, logos, favicons, interface icons, member pictures and app icons.",
   "license": "UNLICENSED",
   "homepage": "https://brand.joinskips.com",