@experiaapp/webchat-react-native 2.0.1

package/lib/core/logger.js

@@ -0,0 +1,53 @@
+"use strict";
+// src/core/logger.ts
+//
+// Logging policy (C18 / audit #28): the framework-agnostic core must NEVER leak
+// PII to release logs. React Native has no Terser/console-stripping by default,
+// so the logger is gated on `__DEV__` and no-ops entirely in release builds.
+//
+// HARD RULE: never pass a session_id or message content/text to this logger.
+// Callers log structural facts only ("session_request retry 2/3", a typed error
+// code, a status transition) — not the values that carry user data.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+exports.createLogger = createLogger;
+/**
+ * Resolve the ambient `__DEV__` flag without importing react-native (core stays
+ * framework-agnostic and unit-tests run under node where `__DEV__` is undefined).
+ * Treated as production (silent) unless explicitly `true`.
+ */
+function isDev() {
+    // `__DEV__` is injected by the RN/Metro bundler onto the global scope. We read
+    // it off `globalThis` (never as a bare identifier) so this module is safe to
+    // load anywhere — node tests, web, release bundles — without a declared global.
+    const flag = globalThis.__DEV__;
+    return flag === true;
+}
+const PREFIX = "[webchat]";
+/**
+ * Build a logger. In release (`__DEV__` !== true) every method is a no-op so no
+ * core diagnostics reach production logs. In dev they forward to the matching
+ * `console` method behind a stable prefix.
+ *
+ * @param sink injectable console-like sink (tests assert calls without spying on
+ *             the global console).
+ */
+function createLogger(sink = console) {
+    const dev = isDev();
+    const out = (method, args) => {
+        var _a;
+        if (!dev)
+            return;
+        const fn = (_a = sink[method]) !== null && _a !== void 0 ? _a : sink.log;
+        if (typeof fn === "function")
+            fn(PREFIX, ...args);
+    };
+    return {
+        debug: (...a) => out("debug", a),
+        info: (...a) => out("info", a),
+        warn: (...a) => out("warn", a),
+        error: (...a) => out("error", a),
+    };
+}
+/** Process-wide default logger (dev-gated). */
+exports.logger = createLogger();

package/lib/core/media.d.ts

@@ -0,0 +1,52 @@
+import type { Message } from "./types";
+/** A file selected for upload, sized in raw (pre-base64) bytes. */
+export interface MediaFile {
+    name: string;
+    mimeType: string;
+    /** raw byte size (NOT base64-inflated) */
+    size: number;
+    uri?: string;
+    base64?: string;
+}
+export interface MediaLimits {
+    /** images (and HEIC photos) cap, raw bytes */
+    imageBytes: number;
+    /** video cap, raw bytes (socket-frame limit) */
+    videoBytes: number;
+    /** documents/PDF cap, raw bytes */
+    documentBytes: number;
+    /** max files per send */
+    maxFiles: number;
+}
+/**
+ * RESOLVED caps (B4/B5): images ≤ 10MB, documents/PDF ≤ 10MB, video ≤ 16MB,
+ * max 10 files per send. Caps are on RAW bytes; base64 inflates ~33% on the wire
+ * (a 16MB file ≈ 21MB encoded) but the socket frame tolerates the resolved 16MB cap.
+ */
+export declare const DEFAULT_LIMITS: MediaLimits;
+export type RejectReason = "too-large" | "too-many" | "unsupported-type";
+export interface RejectedFile {
+    file: MediaFile;
+    reason: RejectReason;
+}
+export interface ValidationResult {
+    accepted: MediaFile[];
+    rejected: RejectedFile[];
+}
+/**
+ * The accepted mime allow-list, mirroring the web widget. HEIC is present because the
+ * resolved policy accepts HEIC photos (the picker converts them to JPEG before encoding).
+ */
+export declare function acceptedMimeTypes(): string[];
+/**
+ * Enforce count, type, and per-kind size caps on a selection BEFORE encoding.
+ * Count is checked first (extras beyond maxFiles are `too-many`), then each kept file is
+ * checked for an allow-listed mime and against its per-kind raw-byte cap.
+ */
+export declare function validateSelection(files: MediaFile[], limits?: MediaLimits): ValidationResult;
+/**
+ * Once the server echoes a hosted `mediaUrl` (UPDATE_MSG), drop the heavy base64 payload
+ * so it is never persisted. Keeps `mediaUrl` and all non-base64 metadata. Pure: returns a
+ * new message and does not mutate the input.
+ */
+export declare function stripBase64OnAck(message: Message): Message;

package/lib/core/media.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LIMITS = void 0;
+exports.acceptedMimeTypes = acceptedMimeTypes;
+exports.validateSelection = validateSelection;
+exports.stripBase64OnAck = stripBase64OnAck;
+const MB = 1024 * 1024;
+/**
+ * RESOLVED caps (B4/B5): images ≤ 10MB, documents/PDF ≤ 10MB, video ≤ 16MB,
+ * max 10 files per send. Caps are on RAW bytes; base64 inflates ~33% on the wire
+ * (a 16MB file ≈ 21MB encoded) but the socket frame tolerates the resolved 16MB cap.
+ */
+exports.DEFAULT_LIMITS = {
+    imageBytes: 10 * MB,
+    videoBytes: 16 * MB,
+    documentBytes: 10 * MB,
+    maxFiles: 10,
+};
+/** Web allow-list (png/jpg/jpeg, mp4/m4v, pdf). HEIC included per resolved handling. */
+const ALLOW_LIST = [
+    "image/png",
+    "image/jpeg",
+    "image/heic", // NOTE: converted to / accepted as JPEG per resolved HEIC policy
+    "video/mp4",
+    "video/x-m4v",
+    // iOS picks .mov clips and expo-image-picker reports them as "video/quicktime".
+    // Without this, every iOS video send was rejected as "unsupported-type" -> a
+    // WebChatError("send") before it ever encoded. ⚠️ Backend acceptance of
+    // video/quicktime MUST BE CONFIRMED (the web widget only accepted mp4/m4v); if the
+    // server rejects .mov, transcode to mp4 before send. kindOf() classifies any
+    // "video/*" as the video kind, so the 16MB video cap still applies.
+    "video/quicktime",
+    "application/pdf",
+    "audio/ogg", // recorded voice notes (canonical "audio/ogg;codecs=opus"; suffix tolerated)
+    // B6 codec flag: the default expo-audio recorder (the Phase 2 <AudioRecorder>
+    // component via useAudioRecorder) emits MPEG-4/AAC (.m4a) on iOS AND Android —
+    // it cannot produce Ogg/Opus. These mimes are allow-listed so the honest m4a/aac
+    // voice note round-trips instead of being rejected as unsupported-type. ⚠️
+    // Backend/infra acceptance of m4a/aac voice notes MUST BE CONFIRMED (the web
+    // widget only ever sent audio/ogg;codecs=opus); otherwise substitute an
+    // Opus-capable recorder behind the same AudioAdapter.
+    "audio/mp4",
+    "audio/aac",
+    "audio/m4a",
+];
+/**
+ * The accepted mime allow-list, mirroring the web widget. HEIC is present because the
+ * resolved policy accepts HEIC photos (the picker converts them to JPEG before encoding).
+ */
+function acceptedMimeTypes() {
+    return [...ALLOW_LIST];
+}
+function kindOf(mimeType) {
+    if (mimeType.startsWith("video/"))
+        return "video";
+    if (mimeType.startsWith("image/"))
+        return "image";
+    return "document";
+}
+function capFor(kind, limits) {
+    if (kind === "video")
+        return limits.videoBytes;
+    if (kind === "image")
+        return limits.imageBytes;
+    return limits.documentBytes;
+}
+/**
+ * Enforce count, type, and per-kind size caps on a selection BEFORE encoding.
+ * Count is checked first (extras beyond maxFiles are `too-many`), then each kept file is
+ * checked for an allow-listed mime and against its per-kind raw-byte cap.
+ */
+function validateSelection(files, limits = exports.DEFAULT_LIMITS) {
+    const accepted = [];
+    const rejected = [];
+    files.forEach((file, i) => {
+        if (i >= limits.maxFiles) {
+            rejected.push({ file, reason: "too-many" });
+            return;
+        }
+        // Tolerate a `;codecs=…` suffix (e.g. "audio/ogg;codecs=opus") by comparing
+        // membership on the bare mime type only.
+        const baseMime = file.mimeType.split(";")[0].trim();
+        if (!ALLOW_LIST.includes(baseMime)) {
+            rejected.push({ file, reason: "unsupported-type" });
+            return;
+        }
+        if (file.size > capFor(kindOf(file.mimeType), limits)) {
+            rejected.push({ file, reason: "too-large" });
+            return;
+        }
+        accepted.push(file);
+    });
+    return { accepted, rejected };
+}
+/**
+ * Once the server echoes a hosted `mediaUrl` (UPDATE_MSG), drop the heavy base64 payload
+ * so it is never persisted. Keeps `mediaUrl` and all non-base64 metadata. Pure: returns a
+ * new message and does not mutate the input.
+ */
+function stripBase64OnAck(message) {
+    const next = { ...message };
+    if (next.media)
+        delete next.media;
+    if (Array.isArray(next.files)) {
+        next.files = next.files.map((f) => {
+            if (f && typeof f === "object") {
+                const { base64, ...rest } = f;
+                void base64;
+                return rest;
+            }
+            return f;
+        });
+    }
+    return next;
+}

package/lib/core/mediaType.d.ts

@@ -0,0 +1,21 @@
+export type MediaKind = "image" | "video" | "audio" | "document";
+/** A minimal, transport-agnostic descriptor of an inbound file. */
+export interface MediaTypeInput {
+    /** display name including extension, e.g. "photo.jpg" */
+    name?: string;
+    /** MIME type from a File/blob/picker asset, e.g. "image/jpeg" */
+    type?: string;
+    /** MIME type from the SDK Asset/MediaEntry shape */
+    mimeType?: string;
+    /** server-hosted URL once the message is acked */
+    mediaUrl?: string;
+    /** local file URI (file://… or content://…) */
+    uri?: string;
+}
+/**
+ * Classify an inbound file into the kind the renderer should use, mirroring the
+ * web widget's FileDisplay. MIME (`type`/`mimeType`) wins when it names a kind;
+ * otherwise the extension of `name` || `mediaUrl` || `uri` decides; unknown
+ * inputs fall back to "document".
+ */
+export declare function detectMediaKind(file: MediaTypeInput): MediaKind;

package/lib/core/mediaType.js

@@ -0,0 +1,66 @@
+"use strict";
+// src/core/mediaType.ts
+//
+// PURE received-message media routing. Mirrors the web widget's FileDisplay
+// (src/components/chatComponents/Body/FileDisplay.tsx): decide whether an
+// inbound file should render as an image, video, audio player, or a generic
+// document tile. No I/O, no React — just a deterministic classifier so the
+// data layer and (Phase 2) the UI agree on a single source of truth.
+//
+// Routing precedence, matching FileDisplay.getFileType():
+//   1. MIME wins. If `type`/`mimeType` contains "image" | "video" | "audio",
+//      that kind is returned immediately (mime-wins resolves the ambiguous
+//      `ogg` case — an audio/ogg mime classifies as audio even though the
+//      `.ogg` extension is listed under video first).
+//   2. Otherwise fall back to the file extension taken from
+//      `name` || `mediaUrl` || `uri` (first non-empty), lower-cased,
+//      query-stripped. Extension order mirrors FileDisplay: image, then video,
+//      then audio — so `ogg` (in BOTH the video and audio lists, like the web
+//      reference) resolves to video on extension alone.
+//   3. Anything unrecognized -> "document".
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectMediaKind = detectMediaKind;
+// Extension tables mirror FileDisplay.getFileTypeFromUrl(). `ogg` deliberately
+// appears in BOTH video and audio (web parity); video is checked first below.
+const IMAGE_EXTS = ["jpg", "jpeg", "png", "gif", "bmp", "webp", "svg"];
+const VIDEO_EXTS = ["mp4", "webm", "mov", "avi", "mkv", "ogg"];
+const AUDIO_EXTS = ["mp3", "wav", "ogg", "aac", "m4a", "flac"];
+/** Lower-cased, query-stripped extension tail of a URL/name, "" when none. */
+function extOf(s) {
+    const clean = s.split("?")[0];
+    const dot = clean.lastIndexOf(".");
+    return dot >= 0 ? clean.slice(dot + 1).toLowerCase() : "";
+}
+/**
+ * Classify an inbound file into the kind the renderer should use, mirroring the
+ * web widget's FileDisplay. MIME (`type`/`mimeType`) wins when it names a kind;
+ * otherwise the extension of `name` || `mediaUrl` || `uri` decides; unknown
+ * inputs fall back to "document".
+ */
+function detectMediaKind(file) {
+    var _a, _b;
+    // 1. MIME wins (resolves the ambiguous ogg case in audio's favor when the
+    //    mime explicitly says audio).
+    const mime = (_b = (_a = file.type) !== null && _a !== void 0 ? _a : file.mimeType) !== null && _b !== void 0 ? _b : "";
+    if (mime) {
+        if (mime.includes("image"))
+            return "image";
+        if (mime.includes("video"))
+            return "video";
+        if (mime.includes("audio"))
+            return "audio";
+    }
+    // 2. Extension fallback on the first non-empty source.
+    const source = file.name || file.mediaUrl || file.uri || "";
+    const ext = extOf(source);
+    if (ext) {
+        if (IMAGE_EXTS.includes(ext))
+            return "image";
+        if (VIDEO_EXTS.includes(ext))
+            return "video"; // video checked before audio (web parity)
+        if (AUDIO_EXTS.includes(ext))
+            return "audio";
+    }
+    // 3. Unknown -> document.
+    return "document";
+}

package/lib/core/messagesReducer.d.ts

@@ -0,0 +1,36 @@
+import type { Message, MessageReaction } from "./types";
+export interface MessagesState {
+    messages: Message[];
+    lastReadAt: number;
+}
+export declare const initialState: MessagesState;
+export type MessagesAction = {
+    type: "RECEIVE";
+    message: Message;
+} | {
+    type: "SEND";
+    message: Message;
+} | {
+    type: "ACK";
+    key: string;
+} | {
+    type: "FAIL";
+    key: string;
+} | {
+    type: "UPDATE_MSG";
+    key: string;
+    patch: Partial<Message>;
+} | {
+    type: "HYDRATE";
+    messages: Message[];
+} | {
+    type: "MARK_READ";
+    at: number;
+} | {
+    type: "REACT";
+    messageKey: string;
+    reaction: MessageReaction | null;
+} | {
+    type: "CLEAR";
+};
+export declare function messagesReducer(state: MessagesState, action: MessagesAction): MessagesState;

package/lib/core/messagesReducer.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initialState = void 0;
+exports.messagesReducer = messagesReducer;
+const media_1 = require("./media");
+exports.initialState = { messages: [], lastReadAt: 0 };
+function messagesReducer(state, action) {
+    switch (action.type) {
+        case "RECEIVE":
+            return { ...state, messages: [...state.messages, action.message] };
+        case "SEND":
+            return { ...state, messages: [...state.messages, { ...action.message, status: "pending" }] };
+        case "ACK":
+            return { ...state, messages: state.messages.map((m) => m.key === action.key ? { ...m, status: "sent" } : m) };
+        case "FAIL":
+            return { ...state, messages: state.messages.map((m) => m.key === action.key ? { ...m, status: "failed" } : m) };
+        case "UPDATE_MSG":
+            // Reconcile by messageKey: apply the patch (e.g. server mediaUrl), default to 'sent',
+            // and strip base64 so the hosted URL is all that persists.
+            return {
+                ...state,
+                messages: state.messages.map((m) => m.key === action.key
+                    ? (0, media_1.stripBase64OnAck)({ ...m, status: "sent", ...action.patch })
+                    : m),
+            };
+        case "REACT":
+            // Match by the SERVER messageKey (distinct from the client `key`); set the
+            // reaction (or null to clear). No-op when no message carries that messageKey.
+            return {
+                ...state,
+                messages: state.messages.map((m) => m.messageKey === action.messageKey
+                    ? { ...m, userReaction: action.reaction }
+                    : m),
+            };
+        case "HYDRATE": {
+            // Legacy sessions persisted BEFORE received-message keys were made unique can
+            // hold duplicate client `key`s (same-millisecond bot bursts saved as `b{now}`).
+            // Re-key collisions on load so React keys — and key-based reconciliation
+            // lookups (ACK/UPDATE_MSG) — stay unique. Mirrors RECEIVE's unique-key fix.
+            const seen = new Set();
+            const deduped = action.messages.map((m, i) => {
+                var _a;
+                if (m.key && !seen.has(m.key)) {
+                    seen.add(m.key);
+                    return m;
+                }
+                return { ...m, key: `${(_a = m.key) !== null && _a !== void 0 ? _a : "m"}-${i}` };
+            });
+            return { ...state, messages: deduped };
+        }
+        case "MARK_READ":
+            return { ...state, lastReadAt: action.at };
+        case "CLEAR":
+            return { messages: [], lastReadAt: 0 };
+        default:
+            return state;
+    }
+}

package/lib/core/persistence.d.ts

@@ -0,0 +1,45 @@
+import type { Message } from "./types";
+export interface KeyValueStore {
+    getItem(k: string): Promise<string | null>;
+    setItem(k: string, v: string): Promise<void>;
+    removeItem(k: string): Promise<void>;
+}
+export declare class MemoryStore implements KeyValueStore {
+    private m;
+    getItem(k: string): Promise<string | null>;
+    setItem(k: string, v: string): Promise<void>;
+    removeItem(k: string): Promise<void>;
+}
+/**
+ * Config-driven storage backend selection (Tier C #33, web `config.storage`).
+ *
+ * Precedence: a HOST-INJECTED store ALWAYS wins (the host explicitly chose a
+ * backend) — we return it untouched. Only when the host injects nothing do we
+ * honor `config.storage`:
+ *   - "sessionStorage" | "memory" -> a fresh {@link MemoryStore} (EPHEMERAL —
+ *     history lives only for the process lifetime, mirroring the web's non-durable
+ *     sessionStorage/in-memory backends; nothing is written to AsyncStorage so a
+ *     relaunch starts clean).
+ *   - "localStorage" (default) / anything else -> the `persistent` store passed in
+ *     (AsyncStorage in production), keeping the 24h sliding-TTL persistence path.
+ *
+ * The TTL logic in {@link loadSession}/{@link saveSession} is unchanged — it runs
+ * against whichever store this returns, so the persistent path keeps the sliding
+ * window and the ephemeral path simply never has prior data to expire.
+ *
+ * @param injected   host-supplied store (or undefined when the host passed none).
+ * @param storage    `config.storage` value.
+ * @param persistent the durable store to use for the "localStorage" path.
+ */
+export declare function selectStore(injected: KeyValueStore | undefined | null, storage: string | undefined, persistent: KeyValueStore): KeyValueStore;
+export interface PersistedSession {
+    sessionId: string;
+    messages: Message[];
+    lastActivity: number;
+}
+export declare function saveSession(store: KeyValueStore, s: PersistedSession, channelId: string): Promise<void>;
+export declare function loadSession(store: KeyValueStore, channelId: string, opts: {
+    now: number;
+    ttlMs: number;
+}): Promise<PersistedSession | null>;
+export declare function clearSession(store: KeyValueStore, channelId: string): Promise<void>;

package/lib/core/persistence.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryStore = void 0;
+exports.selectStore = selectStore;
+exports.saveSession = saveSession;
+exports.loadSession = loadSession;
+exports.clearSession = clearSession;
+class MemoryStore {
+    constructor() {
+        this.m = new Map();
+    }
+    async getItem(k) { var _a; return (_a = this.m.get(k)) !== null && _a !== void 0 ? _a : null; }
+    async setItem(k, v) { this.m.set(k, v); }
+    async removeItem(k) { this.m.delete(k); }
+}
+exports.MemoryStore = MemoryStore;
+/**
+ * Config-driven storage backend selection (Tier C #33, web `config.storage`).
+ *
+ * Precedence: a HOST-INJECTED store ALWAYS wins (the host explicitly chose a
+ * backend) — we return it untouched. Only when the host injects nothing do we
+ * honor `config.storage`:
+ *   - "sessionStorage" | "memory" -> a fresh {@link MemoryStore} (EPHEMERAL —
+ *     history lives only for the process lifetime, mirroring the web's non-durable
+ *     sessionStorage/in-memory backends; nothing is written to AsyncStorage so a
+ *     relaunch starts clean).
+ *   - "localStorage" (default) / anything else -> the `persistent` store passed in
+ *     (AsyncStorage in production), keeping the 24h sliding-TTL persistence path.
+ *
+ * The TTL logic in {@link loadSession}/{@link saveSession} is unchanged — it runs
+ * against whichever store this returns, so the persistent path keeps the sliding
+ * window and the ephemeral path simply never has prior data to expire.
+ *
+ * @param injected   host-supplied store (or undefined when the host passed none).
+ * @param storage    `config.storage` value.
+ * @param persistent the durable store to use for the "localStorage" path.
+ */
+function selectStore(injected, storage, persistent) {
+    if (injected)
+        return injected; // host choice is authoritative
+    if (storage === "sessionStorage" || storage === "memory")
+        return new MemoryStore();
+    return persistent;
+}
+const key = (channelId) => `webchat:${channelId}`;
+async function saveSession(store, s, channelId) {
+    // never persist base64 media: callers strip it before saving
+    await store.setItem(key(channelId), JSON.stringify(s));
+}
+async function loadSession(store, channelId, opts) {
+    const raw = await store.getItem(key(channelId));
+    if (!raw)
+        return null;
+    const s = JSON.parse(raw);
+    if (opts.now - s.lastActivity > opts.ttlMs) {
+        await store.removeItem(key(channelId)); // active purge
+        return null;
+    }
+    return s;
+}
+async function clearSession(store, channelId) {
+    await store.removeItem(key(channelId));
+}

package/lib/core/socketFactory.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Minimal socket surface the framework-agnostic client depends on.
+ *
+ * In the plan this interface lives in `./WebchatClient` (Task 4). Until that
+ * module lands it is declared here so the real factory is self-contained and
+ * unit-testable offline. The shape is identical to the plan's `MinimalSocket`.
+ */
+export interface MinimalSocket {
+    on(event: string, cb: Function): void;
+    off(event: string, cb?: Function): void;
+    emit(event: string, data?: unknown): void;
+    connect?(): void;
+    disconnect(): void;
+    connected?: boolean;
+}
+export declare function createSocket(connectionUrl: string, channelId: string, debug?: boolean): MinimalSocket;

package/lib/core/socketFactory.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSocket = createSocket;
+// src/core/socketFactory.ts
+const socket_io_client_1 = __importDefault(require("socket.io-client"));
+/**
+ * Compact a list of log args for the debug tracer: strings pass through; objects
+ * are JSON-stringified. Any string longer than 500 chars (e.g. base64 media) is
+ * truncated so Metro logs stay readable and copy-pasteable.
+ */
+function fmtArgs(args) {
+    const cap = (v) => (v.length > 500 ? `${v.slice(0, 200)}…(${v.length} chars)` : v);
+    return args
+        .map((a) => {
+        if (typeof a === "string")
+            return cap(a);
+        try {
+            return JSON.stringify(a, (_k, v) => (typeof v === "string" ? cap(v) : v));
+        }
+        catch {
+            return String(a);
+        }
+    })
+        .join(" ");
+}
+/**
+ * DEBUG ONLY (`config.debug`): trace every socket message to the console (Metro) —
+ * outbound emits, every inbound server event (via socket.io v2's `onevent` hook,
+ * so even events with no registered handler are seen), and connection lifecycle.
+ * Long strings (base64) are truncated. Never enable in production — full payloads
+ * (incl. session ids / content) reach the console. Fully guarded so a tracer
+ * failure never breaks the socket.
+ */
+function attachSocketTrace(s) {
+    try {
+        // Outbound: wrap emit (preserves chaining + any ack callback in args).
+        const realEmit = s.emit.bind(s);
+        s.emit = function (event, ...args) {
+            // eslint-disable-next-line no-console
+            console.log("[webchat ▶ emit]", event, fmtArgs(args));
+            return realEmit(event, ...args);
+        };
+        // Inbound: the v2 Socket dispatches server events through `onevent(packet)`;
+        // wrapping it catches EVERY inbound event + payload.
+        if (typeof s.onevent === "function") {
+            const realOnevent = s.onevent.bind(s);
+            s.onevent = function (packet) {
+                const data = (packet && packet.data) || [];
+                // eslint-disable-next-line no-console
+                console.log("[webchat ◀ recv]", data[0], fmtArgs(data.slice(1)));
+                return realOnevent(packet);
+            };
+        }
+        // Lifecycle (not routed through onevent).
+        ["connect", "disconnect", "connect_error", "error", "reconnect"].forEach((ev) => s.on(ev, (payload) => {
+            // eslint-disable-next-line no-console
+            console.log(`[webchat ◇ ${ev}]`, payload === undefined ? "" : fmtArgs([payload]));
+        }));
+        // eslint-disable-next-line no-console
+        console.log("[webchat] socket trace ENABLED (config.debug) — disable for production");
+    }
+    catch (e) {
+        // eslint-disable-next-line no-console
+        console.log("[webchat] socket trace attach failed", e);
+    }
+}
+function createSocket(connectionUrl, channelId, debug = false) {
+    const s = (0, socket_io_client_1.default)(`wss://${connectionUrl}`, {
+        path: `/${channelId}/ws`,
+        transports: ["websocket"],
+        reconnectionDelay: 5000,
+        reconnection: true,
+        autoConnect: false,
+    });
+    // Opt-in full socket tracing for on-device debugging (config.debug). No-op otherwise.
+    if (debug)
+        attachSocketTrace(s);
+    return s;
+}