@relaya-chat/core 1.0.0

package/dist/chatConnection.js

@@ -0,0 +1,182 @@
+// Copyright (c) 2026 JAB Ventures, Inc. MIT License.
+// See LICENSE file at https://github.com/relaya-chat/sdk
+/**
+ * WebSocket connection manager for the Relaya chat system.
+ *
+ * Handles:
+ * - Connection lifecycle (connect, disconnect, reconnect)
+ * - Exponential backoff for reconnection attempts
+ * - Application-level heartbeat pong responses
+ * - Status change callbacks for UI indicators
+ *
+ * Designed for use in both browser (native WebSocket) and React Native
+ * (via the same global WebSocket API surface in React Native).
+ */
+import { calculateBackoff } from './messageUtils.js';
+/**
+ * Manages a single WebSocket connection to the Relaya chat server.
+ *
+ * Usage:
+ *   const conn = new ChatConnection(
+ *     () => `ws://localhost:9000/ws?token=${token}&station=balearic-fm`,
+ *     (msg) => dispatch(msg),
+ *     (status) => setConnectionStatus(status)
+ *   );
+ *   conn.connect();
+ *   conn.send({ type: 'message:send', content: 'hello', clientId: '...' });
+ *   conn.close(); // on component unmount
+ */
+export class ChatConnection {
+    buildWsUrl;
+    onMessage;
+    onStatusChange;
+    ws = null;
+    status = 'disconnected';
+    reconnectAttempt = 0;
+    reconnectTimer = null;
+    /** Set to true when `close()` is called; prevents any further reconnect. */
+    closed = false;
+    backoffBaseMs;
+    backoffMaxMs;
+    onAuthRevoked;
+    /**
+     * @param buildWsUrl      - Called each time a new WebSocket is opened; allows
+     *                          the caller to inject a fresh JWT on reconnect.
+     * @param onMessage       - Receives every parsed WsServerMessage except `ping`
+     *                          (pings are handled internally with an auto-pong) and
+     *                          `force_logout` (handled internally by stopping the
+     *                          connection and invoking `options.onAuthRevoked`).
+     * @param onStatusChange  - Called whenever the connection status changes.
+     * @param options         - Backoff tuning and auth-revocation callback (optional).
+     */
+    constructor(buildWsUrl, onMessage, onStatusChange, options = {}) {
+        this.buildWsUrl = buildWsUrl;
+        this.onMessage = onMessage;
+        this.onStatusChange = onStatusChange;
+        this.backoffBaseMs = options.backoffBaseMs ?? 1000;
+        this.backoffMaxMs = options.backoffMaxMs ?? 30_000;
+        this.onAuthRevoked = options.onAuthRevoked;
+    }
+    getStatus() {
+        return this.status;
+    }
+    /** Open the WebSocket connection (or start the reconnect cycle). */
+    connect() {
+        if (this.closed)
+            return;
+        this.setStatus('connecting');
+        this.openSocket();
+    }
+    /** Send a message to the server. Silently dropped if not connected. */
+    send(msg) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(msg));
+        }
+    }
+    /**
+     * Permanently close the connection and stop any pending reconnect.
+     * After calling this, the instance should be discarded.
+     */
+    close() {
+        this.closed = true;
+        this.clearReconnectTimer();
+        if (this.ws) {
+            this.ws.onclose = null; // prevent scheduleReconnect from firing
+            this.ws.close();
+            this.ws = null;
+        }
+        this.setStatus('disconnected');
+    }
+    // ── Private ───────────────────────────────────────────────────────────────
+    openSocket() {
+        if (this.closed)
+            return;
+        const url = this.buildWsUrl();
+        const ws = new WebSocket(url);
+        this.ws = ws;
+        ws.onopen = () => {
+            if (this.closed) {
+                ws.close();
+                return;
+            }
+            this.reconnectAttempt = 0;
+            this.setStatus('connected');
+        };
+        ws.onmessage = (event) => {
+            let msg;
+            try {
+                msg = JSON.parse(event.data);
+            }
+            catch {
+                return; // ignore malformed frames
+            }
+            // Reply to server heartbeat pings automatically
+            if (msg.type === 'ping') {
+                this.send({ type: 'pong' });
+                return;
+            }
+            // Server-initiated logout (e.g. demo space reset removes the user).
+            // Stop reconnecting and notify the caller to clear auth state.
+            if (msg.type === 'force_logout') {
+                this.handleAuthRevoked();
+                return;
+            }
+            this.onMessage(msg);
+        };
+        ws.onclose = (event) => {
+            if (this.closed)
+                return;
+            // Close code 4001 means the server explicitly revoked this session
+            // (e.g. a WS upgrade was rejected after the user was removed).
+            // Stop reconnecting and notify the caller to clear auth state.
+            if (event.code === 4001) {
+                this.handleAuthRevoked();
+                return;
+            }
+            this.scheduleReconnect();
+        };
+        ws.onerror = () => {
+            // onerror is always followed by onclose — no additional action needed here.
+            // The reconnect is scheduled in onclose.
+        };
+    }
+    scheduleReconnect() {
+        if (this.closed)
+            return;
+        this.setStatus('reconnecting');
+        const delay = calculateBackoff(this.reconnectAttempt, this.backoffBaseMs, this.backoffMaxMs);
+        this.reconnectAttempt++;
+        this.reconnectTimer = setTimeout(() => {
+            if (!this.closed)
+                this.openSocket();
+        }, delay);
+    }
+    clearReconnectTimer() {
+        if (this.reconnectTimer !== null) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    setStatus(status) {
+        if (this.status !== status) {
+            this.status = status;
+            this.onStatusChange(status);
+        }
+    }
+    /**
+     * Permanently stop this connection (no reconnect) and invoke the
+     * onAuthRevoked callback so the caller can clear auth state.
+     * Called when the server sends a force_logout message or closes with code 4001.
+     */
+    handleAuthRevoked() {
+        this.closed = true;
+        this.clearReconnectTimer();
+        if (this.ws) {
+            this.ws.onclose = null; // suppress the onclose that will fire after ws.close()
+            this.ws.close();
+            this.ws = null;
+        }
+        this.setStatus('disconnected');
+        this.onAuthRevoked?.();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared package exports
+ */
+export * from './types.js';
+export * from './messageUtils.js';
+export * from './apiClient.js';
+export * from './chatConnection.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+// Copyright (c) 2026 JAB Ventures, Inc. MIT License.
+// See LICENSE file at https://github.com/relaya-chat/sdk
+/**
+ * Shared package exports
+ */
+export * from './types.js';
+export * from './messageUtils.js';
+export * from './apiClient.js';
+export * from './chatConnection.js';

package/dist/messageUtils.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Pure utility functions for the Relaya chat system.
+ * No I/O, no side effects — safe to import in any environment.
+ */
+/**
+ * Generate a unique client-side message ID for optimistic rendering.
+ * Format: timestamp (base-36) + random suffix, both URL-safe.
+ */
+export declare function generateClientId(): string;
+/**
+ * Calculate exponential backoff delay for reconnection attempts.
+ *
+ * @param attempt - Zero-indexed reconnect attempt number
+ * @param baseMs  - Base delay in milliseconds (default 1000)
+ * @param maxMs   - Maximum delay cap in milliseconds (default 30000)
+ * @returns Delay in milliseconds
+ *
+ * Examples (baseMs=1000, maxMs=30000):
+ *   attempt 0 → 1000ms
+ *   attempt 1 → 2000ms
+ *   attempt 2 → 4000ms
+ *   attempt 3 → 8000ms
+ *   attempt 4 → 16000ms
+ *   attempt 5+ → 30000ms (capped)
+ */
+export declare function calculateBackoff(attempt: number, baseMs?: number, maxMs?: number): number;
+/**
+ * Build URLSearchParams for message cursor pagination.
+ * `before` and `after` are mutually exclusive; the server enforces this.
+ */
+export declare function buildCursorParams(params: {
+    before?: string;
+    after?: string;
+    limit?: number;
+}): URLSearchParams;
+/**
+ * A client-side pending message created before server confirmation.
+ * Rendered in the UI immediately; replaced by the server's authoritative
+ * copy once a matching `message:broadcast` arrives.
+ */
+export interface OptimisticMessage {
+    clientId: string;
+    content: string;
+    authorId: string;
+    authorDisplayName: string;
+    authorAvatarUrl: string | null;
+    createdAt: Date;
+    status: 'sending' | 'sent' | 'failed';
+}
+/**
+ * Remove the optimistic message that has been reconciled by a server broadcast.
+ * When the server echoes back a `message:broadcast` with a matching `clientId`,
+ * the optimistic copy is no longer needed — the server message is used instead.
+ *
+ * @param optimistic     - Current list of optimistic messages
+ * @param serverClientId - The clientId echoed back by the server, if any
+ * @returns Updated optimistic list with the reconciled message removed
+ */
+export declare function removeReconciledOptimistic(optimistic: OptimisticMessage[], serverClientId: string | undefined): OptimisticMessage[];
+/**
+ * Mark an optimistic message as failed.
+ * Called when a WS `error` response arrives that can be tied back to a clientId,
+ * or when the connection drops before the server echoes the message back.
+ */
+export declare function markOptimisticFailed(optimistic: OptimisticMessage[], clientId: string): OptimisticMessage[];
+/**
+ * Remove duplicate messages from a list, keeping the first occurrence.
+ * Used when merging REST catch-up results with already-received WS messages
+ * after a reconnect.
+ */
+export declare function deduplicateMessages<T extends {
+    id: string;
+}>(messages: T[]): T[];
+export interface ImageSegment {
+    text: string;
+    isImage: boolean;
+    url?: string;
+}
+export interface StickerShortcodeEntry {
+    shortcode: string | null;
+    url: string;
+}
+/**
+ * Host/path allowlist for inline image rendering in chat messages.
+ *
+ * Notes:
+ * - The station sticker path is allowlisted by pathname prefix so both
+ *   relative and absolute URLs can be rendered.
+ * - External hosts are intentionally constrained to known GIF/image providers.
+ */
+export declare const IMAGE_URL_ALLOWLIST: {
+    readonly pathPrefixes: readonly ["/files/stations/"];
+    readonly hosts: readonly ["tenor.com", "media.tenor.com", "giphy.com", "media.giphy.com", "i.giphy.com", "editablegifs.com", "imgur.com", "i.imgur.com"];
+};
+export declare function normalizeStickerShortcode(shortcode: string): string;
+export declare function buildStickerShortcodeMap(stickers: StickerShortcodeEntry[]): Record<string, string>;
+export declare function expandStickerShortcodes(content: string, stickers: StickerShortcodeEntry[]): string;
+export declare function hasStickerShortcodeToken(content: string): boolean;
+/**
+ * Segment message content into plain-text and allowlisted image URL spans.
+ */
+export declare function detectImageUrls(content: string): ImageSegment[];
+/**
+ * True when content is a single image URL plus optional surrounding whitespace.
+ */
+export declare function isSingleImageMessage(content: string): boolean;

package/dist/messageUtils.js

@@ -0,0 +1,221 @@
+// Copyright (c) 2026 JAB Ventures, Inc. MIT License.
+// See LICENSE file at https://github.com/relaya-chat/sdk
+/**
+ * Pure utility functions for the Relaya chat system.
+ * No I/O, no side effects — safe to import in any environment.
+ */
+// ==================== CLIENT ID ====================
+/**
+ * Generate a unique client-side message ID for optimistic rendering.
+ * Format: timestamp (base-36) + random suffix, both URL-safe.
+ */
+export function generateClientId() {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 9)}`;
+}
+// ==================== RECONNECT BACKOFF ====================
+/**
+ * Calculate exponential backoff delay for reconnection attempts.
+ *
+ * @param attempt - Zero-indexed reconnect attempt number
+ * @param baseMs  - Base delay in milliseconds (default 1000)
+ * @param maxMs   - Maximum delay cap in milliseconds (default 30000)
+ * @returns Delay in milliseconds
+ *
+ * Examples (baseMs=1000, maxMs=30000):
+ *   attempt 0 → 1000ms
+ *   attempt 1 → 2000ms
+ *   attempt 2 → 4000ms
+ *   attempt 3 → 8000ms
+ *   attempt 4 → 16000ms
+ *   attempt 5+ → 30000ms (capped)
+ */
+export function calculateBackoff(attempt, baseMs = 1000, maxMs = 30_000) {
+    const delay = baseMs * Math.pow(2, attempt);
+    return Math.min(delay, maxMs);
+}
+// ==================== CURSOR HELPERS ====================
+/**
+ * Build URLSearchParams for message cursor pagination.
+ * `before` and `after` are mutually exclusive; the server enforces this.
+ */
+export function buildCursorParams(params) {
+    const sp = new URLSearchParams();
+    if (params.before)
+        sp.set('before', params.before);
+    if (params.after)
+        sp.set('after', params.after);
+    if (params.limit !== undefined)
+        sp.set('limit', String(params.limit));
+    return sp;
+}
+/**
+ * Remove the optimistic message that has been reconciled by a server broadcast.
+ * When the server echoes back a `message:broadcast` with a matching `clientId`,
+ * the optimistic copy is no longer needed — the server message is used instead.
+ *
+ * @param optimistic     - Current list of optimistic messages
+ * @param serverClientId - The clientId echoed back by the server, if any
+ * @returns Updated optimistic list with the reconciled message removed
+ */
+export function removeReconciledOptimistic(optimistic, serverClientId) {
+    if (!serverClientId)
+        return optimistic;
+    return optimistic.filter((m) => m.clientId !== serverClientId);
+}
+/**
+ * Mark an optimistic message as failed.
+ * Called when a WS `error` response arrives that can be tied back to a clientId,
+ * or when the connection drops before the server echoes the message back.
+ */
+export function markOptimisticFailed(optimistic, clientId) {
+    return optimistic.map((m) => m.clientId === clientId ? { ...m, status: 'failed' } : m);
+}
+// ==================== DEDUPLICATION ====================
+/**
+ * Remove duplicate messages from a list, keeping the first occurrence.
+ * Used when merging REST catch-up results with already-received WS messages
+ * after a reconnect.
+ */
+export function deduplicateMessages(messages) {
+    const seen = new Set();
+    return messages.filter((m) => {
+        if (seen.has(m.id))
+            return false;
+        seen.add(m.id);
+        return true;
+    });
+}
+const ALLOWED_IMAGE_EXTENSIONS = new Set(['.gif', '.png', '.jpg', '.jpeg', '.webp']);
+/**
+ * Host/path allowlist for inline image rendering in chat messages.
+ *
+ * Notes:
+ * - The station sticker path is allowlisted by pathname prefix so both
+ *   relative and absolute URLs can be rendered.
+ * - External hosts are intentionally constrained to known GIF/image providers.
+ */
+export const IMAGE_URL_ALLOWLIST = {
+    pathPrefixes: ['/files/stations/'],
+    hosts: [
+        'tenor.com',
+        'media.tenor.com',
+        'giphy.com',
+        'media.giphy.com',
+        'i.giphy.com',
+        'editablegifs.com',
+        'imgur.com',
+        'i.imgur.com',
+    ],
+};
+const URL_TOKEN_REGEX = /(https?:\/\/[^\s]+|\/files\/stations\/[^\s]+)/gi;
+const SHORTCODE_TOKEN_REGEX = /:([a-z0-9_-]{1,64}):/gi;
+export function normalizeStickerShortcode(shortcode) {
+    return shortcode.trim().toLowerCase();
+}
+export function buildStickerShortcodeMap(stickers) {
+    return stickers.reduce((acc, sticker) => {
+        if (!sticker.shortcode)
+            return acc;
+        acc[normalizeStickerShortcode(sticker.shortcode)] = sticker.url;
+        return acc;
+    }, {});
+}
+export function expandStickerShortcodes(content, stickers) {
+    const shortcodeMap = buildStickerShortcodeMap(stickers);
+    return content.replace(SHORTCODE_TOKEN_REGEX, (fullMatch, rawShortcode) => {
+        const resolved = shortcodeMap[normalizeStickerShortcode(rawShortcode)];
+        return resolved ?? fullMatch;
+    });
+}
+export function hasStickerShortcodeToken(content) {
+    SHORTCODE_TOKEN_REGEX.lastIndex = 0;
+    return SHORTCODE_TOKEN_REGEX.test(content);
+}
+function hasAllowedImageExtension(pathname) {
+    const lowerPath = pathname.toLowerCase();
+    for (const ext of ALLOWED_IMAGE_EXTENSIONS) {
+        if (lowerPath.endsWith(ext))
+            return true;
+    }
+    return false;
+}
+function hostIsAllowlisted(hostname) {
+    const host = hostname.toLowerCase();
+    return IMAGE_URL_ALLOWLIST.hosts.some((allowed) => host === allowed || host.endsWith(`.${allowed}`));
+}
+function splitTrailingPunctuation(token) {
+    const match = token.match(/[\],.!?:;]+$/);
+    if (!match)
+        return { core: token, trailing: '' };
+    const trailing = match[0];
+    return { core: token.slice(0, -trailing.length), trailing };
+}
+function pushTextSegment(segments, text) {
+    if (!text)
+        return;
+    const last = segments[segments.length - 1];
+    if (last && !last.isImage) {
+        last.text += text;
+        return;
+    }
+    segments.push({ text, isImage: false });
+}
+function isAllowlistedImageUrl(url) {
+    try {
+        // Relative station sticker path
+        if (url.startsWith('/')) {
+            return IMAGE_URL_ALLOWLIST.pathPrefixes.some((prefix) => url.startsWith(prefix))
+                && hasAllowedImageExtension(url.split('?')[0] ?? url);
+        }
+        const parsed = new URL(url);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+            return false;
+        const pathname = parsed.pathname;
+        const isStickerPath = IMAGE_URL_ALLOWLIST.pathPrefixes.some((prefix) => pathname.startsWith(prefix));
+        const isExternalHost = hostIsAllowlisted(parsed.hostname);
+        if (!isStickerPath && !isExternalHost)
+            return false;
+        return hasAllowedImageExtension(pathname);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Segment message content into plain-text and allowlisted image URL spans.
+ */
+export function detectImageUrls(content) {
+    const segments = [];
+    let cursor = 0;
+    for (const match of content.matchAll(URL_TOKEN_REGEX)) {
+        const raw = match[0];
+        const start = match.index ?? 0;
+        const end = start + raw.length;
+        if (start > cursor) {
+            pushTextSegment(segments, content.slice(cursor, start));
+        }
+        const { core, trailing } = splitTrailingPunctuation(raw);
+        if (isAllowlistedImageUrl(core)) {
+            segments.push({ text: core, isImage: true, url: core });
+            pushTextSegment(segments, trailing);
+        }
+        else {
+            pushTextSegment(segments, raw);
+        }
+        cursor = end;
+    }
+    if (cursor < content.length) {
+        pushTextSegment(segments, content.slice(cursor));
+    }
+    return segments;
+}
+/**
+ * True when content is a single image URL plus optional surrounding whitespace.
+ */
+export function isSingleImageMessage(content) {
+    const segments = detectImageUrls(content);
+    const imageCount = segments.filter((s) => s.isImage).length;
+    if (imageCount !== 1)
+        return false;
+    return segments.every((segment) => segment.isImage || segment.text.trim() === '');
+}