@relaya-chat/react-native 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JAB Ventures, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @relaya-chat/react-native
+
+> ⚠️ **No developer attention has been paid to this package yet.**
+>
+> This portion of the repository is planned but has not been implemented, tested, or validated in any way. There are **no assurances that anything here will work**. Do not attempt to use this package in a production or development context until this notice is removed.
+
+Work on this package is coming soon.

package/dist/hooks/useRelayaAuth.d.ts

@@ -0,0 +1,57 @@
+/**
+ * useRelayaAuth — AsyncStorage-based authentication for React Native / Expo.
+ *
+ * Manages the full OTP authentication lifecycle:
+ * - On mount: read token from AsyncStorage → GET /api/chat/:slug/me → set state
+ * - requestCode(email) → POST /auth/request-code → returns pendingId
+ * - verifyCode(pendingId, code) → POST /auth/verify-code → store JWT → authenticated
+ * - logout() → POST /auth/logout → delete AsyncStorage entry → anonymous
+ * - refresh() → POST /auth/refresh → replace stored token (call on app foreground)
+ *
+ * Uses Bearer token auth (not cookies). The host app installs
+ * @react-native-async-storage/async-storage as a peer dependency.
+ */
+import type { Permission, Role } from '@relaya-chat/core';
+export type AuthStatus = 'loading' | 'anonymous' | 'otp-sent' | 'authenticated';
+export interface RelayaAuthUser {
+    id: string;
+    displayName: string;
+    avatarUrl: string | null;
+    permissions: Permission[];
+    roles: Role[];
+}
+export interface RelayaAuthStation {
+    id: string;
+    name: string;
+    slug: string;
+}
+export interface RelayaAuthState {
+    status: AuthStatus;
+    user: RelayaAuthUser | null;
+    station: RelayaAuthStation | null;
+    error: string | null;
+}
+export interface RelayaAuthOptions {
+    /** Relaya SaaS endpoint — always 'https://api.relaya.chat' */
+    serverUrl: string;
+    /** Your space slug, assigned by Relaya — e.g. 'balearic-fm' */
+    stationSlug: string;
+    /** AsyncStorage key for the JWT (default: 'relaya_token') */
+    tokenStorageKey?: string;
+}
+export interface RelayaAuthActions {
+    /** Send a 6-digit OTP to the given email. Returns pendingId for verifyCode(). */
+    requestCode: (email: string) => Promise<{
+        pendingId: string;
+    }>;
+    /** Verify the OTP code. On success, stores JWT and transitions to 'authenticated'. */
+    verifyCode: (pendingId: string, code: string) => Promise<void>;
+    /** Log out: call server endpoint, delete stored token, transition to 'anonymous'. */
+    logout: () => Promise<void>;
+    /** Refresh the stored JWT. Call when app returns to foreground. */
+    refresh: () => Promise<void>;
+    /** Returns the current JWT synchronously (from ref). Used by ApiClient and ChatConnection. */
+    getToken: () => string | null;
+}
+export declare function useRelayaAuth(options: RelayaAuthOptions): RelayaAuthState & RelayaAuthActions;
+//# sourceMappingURL=useRelayaAuth.d.ts.map

package/dist/hooks/useRelayaAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRelayaAuth.d.ts","sourceRoot":"","sources":["../../src/hooks/useRelayaAuth.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAOH,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAI1D,MAAM,MAAM,UAAU,GAClB,SAAS,GACT,WAAW,GACX,UAAU,GACV,eAAe,CAAC;AAEpB,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5B,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAClC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/D,sFAAsF;IACtF,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,qFAAqF;IACrF,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,mEAAmE;IACnE,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,8FAA8F;IAC9F,QAAQ,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CAC/B;AAID,wBAAgB,aAAa,CAC3B,OAAO,EAAE,iBAAiB,GACzB,eAAe,GAAG,iBAAiB,CAuMrC"}

package/dist/hooks/useRelayaAuth.js

@@ -0,0 +1,193 @@
+"use strict";
+// Copyright (c) 2026 JAB Ventures, Inc. MIT License.
+// See LICENSE file at https://github.com/relaya-chat/sdk
+/**
+ * useRelayaAuth — AsyncStorage-based authentication for React Native / Expo.
+ *
+ * Manages the full OTP authentication lifecycle:
+ * - On mount: read token from AsyncStorage → GET /api/chat/:slug/me → set state
+ * - requestCode(email) → POST /auth/request-code → returns pendingId
+ * - verifyCode(pendingId, code) → POST /auth/verify-code → store JWT → authenticated
+ * - logout() → POST /auth/logout → delete AsyncStorage entry → anonymous
+ * - refresh() → POST /auth/refresh → replace stored token (call on app foreground)
+ *
+ * Uses Bearer token auth (not cookies). The host app installs
+ * @react-native-async-storage/async-storage as a peer dependency.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useRelayaAuth = useRelayaAuth;
+const react_1 = require("react");
+const react_native_1 = require("react-native");
+const async_storage_1 = __importDefault(require("@react-native-async-storage/async-storage"));
+const core_1 = require("@relaya-chat/core");
+// ── Hook ──────────────────────────────────────────────────────────────────────
+function useRelayaAuth(options) {
+    const { serverUrl, stationSlug, tokenStorageKey = 'relaya_token' } = options;
+    const [state, setState] = (0, react_1.useState)({
+        status: 'loading',
+        user: null,
+        station: null,
+        error: null,
+    });
+    // Token ref — always holds the latest JWT without triggering re-renders.
+    // getToken() reads from here so callers always get the freshest value.
+    const tokenRef = (0, react_1.useRef)(null);
+    const getToken = (0, react_1.useCallback)(() => tokenRef.current, []);
+    // Shared ApiClient — uses getToken callback so it always sends the latest JWT.
+    const api = (0, react_1.useRef)(new core_1.ApiClient(serverUrl, getToken)).current;
+    // Guard against React StrictMode double-invocation
+    const initStartedRef = (0, react_1.useRef)(false);
+    // ── Helpers ────────────────────────────────────────────────────────────────
+    const storeToken = (0, react_1.useCallback)(async (token) => {
+        tokenRef.current = token;
+        await async_storage_1.default.setItem(tokenStorageKey, token);
+    }, [tokenStorageKey]);
+    const clearToken = (0, react_1.useCallback)(async () => {
+        tokenRef.current = null;
+        await async_storage_1.default.removeItem(tokenStorageKey);
+    }, [tokenStorageKey]);
+    // ── Initial auth check ─────────────────────────────────────────────────────
+    (0, react_1.useEffect)(() => {
+        if (initStartedRef.current)
+            return;
+        initStartedRef.current = true;
+        async function initialize() {
+            // 1. Read stored token from AsyncStorage
+            const storedToken = await async_storage_1.default.getItem(tokenStorageKey);
+            if (!storedToken) {
+                setState((s) => ({ ...s, status: 'anonymous' }));
+                return;
+            }
+            // 2. Validate token by calling GET /me
+            tokenRef.current = storedToken;
+            try {
+                const meData = await api.getMe(stationSlug);
+                const stationData = await api.getStation(stationSlug);
+                setState({
+                    status: 'authenticated',
+                    user: {
+                        id: meData.userId,
+                        displayName: meData.displayName,
+                        avatarUrl: null,
+                        permissions: meData.permissions,
+                        roles: meData.roles,
+                    },
+                    station: {
+                        id: stationData.id,
+                        name: stationData.name,
+                        slug: stationData.slug,
+                    },
+                    error: null,
+                });
+            }
+            catch {
+                // Token invalid or expired — clear it and go anonymous
+                tokenRef.current = null;
+                await async_storage_1.default.removeItem(tokenStorageKey);
+                setState({ status: 'anonymous', user: null, station: null, error: null });
+            }
+        }
+        initialize().catch(() => {
+            setState({ status: 'anonymous', user: null, station: null, error: null });
+        });
+    }, []); // eslint-disable-line react-hooks/exhaustive-deps
+    // ── App foreground token refresh ───────────────────────────────────────────
+    const refresh = (0, react_1.useCallback)(async () => {
+        const currentToken = tokenRef.current;
+        if (!currentToken)
+            return;
+        try {
+            const data = await api.refresh(currentToken);
+            await storeToken(data.accessToken);
+        }
+        catch {
+            // Refresh failed — token may be expired; transition to anonymous
+            await clearToken();
+            setState({ status: 'anonymous', user: null, station: null, error: null });
+        }
+    }, [api, storeToken, clearToken]);
+    (0, react_1.useEffect)(() => {
+        const subscription = react_native_1.AppState.addEventListener('change', (nextState) => {
+            if (nextState === 'active' && tokenRef.current) {
+                refresh().catch(() => {
+                    // Handled inside refresh()
+                });
+            }
+        });
+        return () => {
+            subscription.remove();
+        };
+    }, [refresh]);
+    // ── requestCode ────────────────────────────────────────────────────────────
+    const requestCode = (0, react_1.useCallback)(async (email) => {
+        setState((s) => ({ ...s, error: null }));
+        try {
+            const data = await api.requestCode(email, stationSlug);
+            setState((s) => ({ ...s, status: 'otp-sent' }));
+            return { pendingId: data.pendingId };
+        }
+        catch (err) {
+            const message = err?.message ??
+                'Failed to send verification code. Please try again.';
+            setState((s) => ({ ...s, error: message }));
+            throw err;
+        }
+    }, [api, stationSlug]);
+    // ── verifyCode ─────────────────────────────────────────────────────────────
+    const verifyCode = (0, react_1.useCallback)(async (pendingId, code) => {
+        setState((s) => ({ ...s, error: null }));
+        try {
+            const data = await api.verifyCode(pendingId, code, stationSlug);
+            await storeToken(data.accessToken);
+            setState({
+                status: 'authenticated',
+                user: {
+                    id: data.user.id,
+                    displayName: data.user.displayName,
+                    avatarUrl: data.user.avatarUrl,
+                    permissions: data.user.permissions,
+                    roles: data.user.roles,
+                },
+                station: {
+                    id: data.station.id,
+                    name: data.station.name,
+                    slug: data.station.slug,
+                },
+                error: null,
+            });
+        }
+        catch (err) {
+            const message = err?.message ??
+                'Invalid or expired code. Please try again.';
+            setState((s) => ({ ...s, error: message }));
+            throw err;
+        }
+    }, [api, stationSlug, storeToken]);
+    // ── logout ─────────────────────────────────────────────────────────────────
+    const logout = (0, react_1.useCallback)(async () => {
+        try {
+            await fetch(`${serverUrl}/auth/logout`, {
+                method: 'POST',
+                headers: tokenRef.current
+                    ? { Authorization: `Bearer ${tokenRef.current}` }
+                    : {},
+            });
+        }
+        catch {
+            // Ignore server errors — proceed with local logout regardless
+        }
+        await clearToken();
+        setState({ status: 'anonymous', user: null, station: null, error: null });
+    }, [serverUrl, clearToken]);
+    return {
+        ...state,
+        requestCode,
+        verifyCode,
+        logout,
+        refresh,
+        getToken,
+    };
+}

package/dist/hooks/useRelayaChat.d.ts

@@ -0,0 +1,69 @@
+/**
+ * useRelayaChat — WebSocket + REST chat state for React Native / Expo.
+ *
+ * Mirrors the web useRelayaChat hook but:
+ * - Accepts a getToken callback instead of using cookies
+ * - Builds the WS URL from serverUrl + stationSlug props (no config.ts)
+ * - Has no NotificationMuteContext dependency (host app manages audio)
+ * - Has no sticker system (mobile UI handles stickers independently)
+ *
+ * Responsibilities:
+ * - Open and manage a ChatConnection WebSocket instance
+ * - Load initial messages via REST on connect (auth:success)
+ * - Catch up missed messages via REST on reconnect (cursor-based)
+ * - Load older messages on demand (scroll-up / load more)
+ * - Handle optimistic message sending with clientId reconciliation
+ * - Expose online users list from presence:update messages
+ * - Dispatch moderator REST actions (delete, ban)
+ * - Dispatch report REST action
+ */
+import type { Message, UserInfo, OptimisticMessage } from '@relaya-chat/core';
+import type { ConnectionStatus } from '@relaya-chat/core';
+import type { RelayaAuthState, RelayaAuthActions } from './useRelayaAuth';
+export interface OnlineUser {
+    id: string;
+    displayName: string;
+    avatarUrl: string | null;
+}
+export interface RelayaChatOptions {
+    /** Relaya SaaS endpoint — always 'https://api.relaya.chat' */
+    serverUrl: string;
+    /** Your space slug — e.g. 'balearic-fm' */
+    stationSlug: string;
+    /** Auth state from useRelayaAuth */
+    authState: RelayaAuthState;
+    /** Token getter from useRelayaAuth — called on every WS connect and API request */
+    getToken: RelayaAuthActions['getToken'];
+}
+export interface RelayaChatState {
+    messages: Message[];
+    optimistic: OptimisticMessage[];
+    users: OnlineUser[];
+    userCount: number;
+    totalCount: number;
+    connectionStatus: ConnectionStatus;
+    loadingInitial: boolean;
+    loadingOlder: boolean;
+    hasOlderMessages: boolean;
+    error: string | null;
+}
+export interface ReplyData {
+    messageId: string;
+    authorName: string;
+    excerpt: string;
+}
+export interface RelayaChatActions {
+    sendMessage: (content: string, replyTo?: ReplyData) => void;
+    loadOlderMessages: () => Promise<void>;
+    editMessage: (messageId: string, newContent: string) => Promise<void>;
+    deleteMessage: (messageId: string) => Promise<void>;
+    banUser: (userId: string, params?: {
+        reason?: string;
+        expiresAt?: string;
+    }) => Promise<void>;
+    reportMessage: (messageId: string, reason: string, details?: string) => Promise<void>;
+    getUserInfo: (userId: string) => UserInfo | undefined;
+    getAvatarForMessage: (userId: string, messageTime: Date) => string | null;
+}
+export declare function useRelayaChat(options: RelayaChatOptions): RelayaChatState & RelayaChatActions;
+//# sourceMappingURL=useRelayaChat.d.ts.map

package/dist/hooks/useRelayaChat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRelayaChat.d.ts","sourceRoot":"","sources":["../../src/hooks/useRelayaChat.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAWH,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EAGR,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAW1E,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,SAAS,EAAE,eAAe,CAAC;IAC3B,mFAAmF;IACnF,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,cAAc,EAAE,OAAO,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;IACtB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,KAAK,IAAI,CAAC;IAC5D,iBAAiB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7F,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtF,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,QAAQ,GAAG,SAAS,CAAC;IACtD,mBAAmB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,KAAK,MAAM,GAAG,IAAI,CAAC;CAC3E;AAID,wBAAgB,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,eAAe,GAAG,iBAAiB,CAua7F"}

package/dist/hooks/useRelayaChat.js

@@ -0,0 +1,365 @@
+"use strict";
+// Copyright (c) 2026 JAB Ventures, Inc. MIT License.
+// See LICENSE file at https://github.com/relaya-chat/sdk
+/**
+ * useRelayaChat — WebSocket + REST chat state for React Native / Expo.
+ *
+ * Mirrors the web useRelayaChat hook but:
+ * - Accepts a getToken callback instead of using cookies
+ * - Builds the WS URL from serverUrl + stationSlug props (no config.ts)
+ * - Has no NotificationMuteContext dependency (host app manages audio)
+ * - Has no sticker system (mobile UI handles stickers independently)
+ *
+ * Responsibilities:
+ * - Open and manage a ChatConnection WebSocket instance
+ * - Load initial messages via REST on connect (auth:success)
+ * - Catch up missed messages via REST on reconnect (cursor-based)
+ * - Load older messages on demand (scroll-up / load more)
+ * - Handle optimistic message sending with clientId reconciliation
+ * - Expose online users list from presence:update messages
+ * - Dispatch moderator REST actions (delete, ban)
+ * - Dispatch report REST action
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useRelayaChat = useRelayaChat;
+const react_1 = require("react");
+const core_1 = require("@relaya-chat/core");
+const buildRnWsUrl_1 = require("../utils/buildRnWsUrl");
+// ── Constants ─────────────────────────────────────────────────────────────────
+const PAGE_SIZE = 50;
+const MAX_MESSAGES = 150;
+const MAX_AVATAR_HISTORY = 20;
+// ── Hook ──────────────────────────────────────────────────────────────────────
+function useRelayaChat(options) {
+    const { serverUrl, stationSlug, authState, getToken } = options;
+    const [state, setState] = (0, react_1.useState)({
+        messages: [],
+        optimistic: [],
+        users: [],
+        userCount: 0,
+        totalCount: 0,
+        connectionStatus: 'disconnected',
+        loadingInitial: false,
+        loadingOlder: false,
+        hasOlderMessages: false,
+        error: null,
+    });
+    const connRef = (0, react_1.useRef)(null);
+    const oldestMessageIdRef = (0, react_1.useRef)(undefined);
+    const newestMessageIdRef = (0, react_1.useRef)(undefined);
+    const pendingClientIds = (0, react_1.useRef)(new Map());
+    // User directory for resolving message authors
+    const userDirectory = (0, react_1.useRef)(new Map());
+    // Avatar history for temporal tracking (session-only)
+    const avatarHistory = (0, react_1.useRef)(new Map());
+    const api = (0, react_1.useRef)(new core_1.ApiClient(serverUrl, getToken)).current;
+    // Stable refs for callbacks — prevents stale closures in long-lived WS handlers
+    const handleWsMessageRef = (0, react_1.useRef)(null);
+    const handleStatusChangeRef = (0, react_1.useRef)(null);
+    const userId = authState.user?.id ?? '';
+    // ── Temporal avatar resolution ─────────────────────────────────────────────
+    const getAvatarForMessage = (0, react_1.useCallback)((userId, messageTime) => {
+        const history = avatarHistory.current.get(userId) || [];
+        // Find most recent avatar that existed at messageTime
+        const historicalEntry = history
+            .filter((entry) => entry.changedAt <= messageTime)
+            .pop();
+        if (historicalEntry) {
+            return historicalEntry.url;
+        }
+        return userDirectory.current.get(userId)?.avatarUrl ?? null;
+    }, []);
+    // ── Load messages via REST ─────────────────────────────────────────────────
+    const loadMessages = (0, react_1.useCallback)(async (opts = {}) => {
+        if (!stationSlug)
+            return;
+        try {
+            const res = await api.getMessages(stationSlug, {
+                after: opts.after,
+                limit: PAGE_SIZE,
+            });
+            const msgs = res.messages ?? [];
+            setState((prev) => {
+                let merged;
+                if (opts.after) {
+                    merged = (0, core_1.deduplicateMessages)([...prev.messages, ...msgs]);
+                }
+                else {
+                    merged = msgs;
+                }
+                if (msgs.length > 0) {
+                    newestMessageIdRef.current = merged[merged.length - 1].id;
+                    if (!opts.after) {
+                        oldestMessageIdRef.current = merged[0].id;
+                    }
+                }
+                return {
+                    ...prev,
+                    messages: merged,
+                    hasOlderMessages: res.hasMore ?? false,
+                    loadingInitial: false,
+                };
+            });
+        }
+        catch (err) {
+            console.error('[useRelayaChat] loadMessages failed:', err);
+            setState((prev) => ({ ...prev, loadingInitial: false }));
+        }
+    }, [api, stationSlug]);
+    // ── WebSocket message handler ──────────────────────────────────────────────
+    const handleWsMessage = (0, react_1.useCallback)((msg) => {
+        switch (msg.type) {
+            case 'auth:success': {
+                // Populate user directory
+                userDirectory.current.clear();
+                avatarHistory.current.clear();
+                msg.users.forEach((user) => {
+                    userDirectory.current.set(user.id, {
+                        id: user.id,
+                        displayName: user.displayName,
+                        avatarUrl: user.avatarUrl,
+                    });
+                    if (user.avatarUrl !== null) {
+                        avatarHistory.current.set(user.id, [{ url: user.avatarUrl, changedAt: new Date(0) }]);
+                    }
+                });
+                // Fresh connect: load initial messages. Reconnect: catch-up already in flight.
+                if (!newestMessageIdRef.current) {
+                    setState((prev) => ({ ...prev, loadingInitial: true }));
+                    loadMessages();
+                }
+                break;
+            }
+            case 'message:broadcast': {
+                const { message, clientId } = msg;
+                setState((prev) => {
+                    const deduped = (0, core_1.deduplicateMessages)([...prev.messages, message]);
+                    const newMessages = deduped.length > MAX_MESSAGES
+                        ? deduped.slice(deduped.length - MAX_MESSAGES)
+                        : deduped;
+                    const newOptimistic = (0, core_1.removeReconciledOptimistic)(prev.optimistic, clientId);
+                    newestMessageIdRef.current = message.id;
+                    if (newMessages.length > 0) {
+                        oldestMessageIdRef.current = newMessages[0].id;
+                    }
+                    return { ...prev, messages: newMessages, optimistic: newOptimistic };
+                });
+                break;
+            }
+            case 'message:deleted': {
+                const { messageId } = msg;
+                setState((prev) => ({
+                    ...prev,
+                    messages: prev.messages.map((m) => m.id === messageId
+                        ? { ...m, is_deleted: true, content: null }
+                        : m),
+                }));
+                break;
+            }
+            case 'message:edited': {
+                const { message } = msg;
+                setState((prev) => ({
+                    ...prev,
+                    messages: prev.messages.map((m) => (m.id === message.id ? message : m)),
+                }));
+                break;
+            }
+            case 'presence:update': {
+                msg.users.forEach((user) => {
+                    userDirectory.current.set(user.id, {
+                        id: user.id,
+                        displayName: user.displayName,
+                        avatarUrl: user.avatarUrl,
+                    });
+                });
+                setState((prev) => ({
+                    ...prev,
+                    users: msg.users.map((u) => ({
+                        id: u.id,
+                        displayName: u.displayName,
+                        avatarUrl: u.avatarUrl,
+                    })),
+                    userCount: msg.userCount,
+                    totalCount: msg.totalCount,
+                }));
+                break;
+            }
+            case 'user:update': {
+                const { userId: updatedUserId, updates, timestamp } = msg;
+                const existing = userDirectory.current.get(updatedUserId);
+                userDirectory.current.set(updatedUserId, {
+                    id: updatedUserId,
+                    displayName: updates.displayName ?? existing?.displayName ?? 'Unknown User',
+                    avatarUrl: updates.avatarUrl !== undefined
+                        ? updates.avatarUrl
+                        : (existing?.avatarUrl ?? null),
+                });
+                if (updates.avatarUrl !== undefined) {
+                    const history = avatarHistory.current.get(updatedUserId) || [];
+                    history.push({ url: updates.avatarUrl, changedAt: new Date(timestamp) });
+                    const capped = history.length > MAX_AVATAR_HISTORY
+                        ? history.slice(history.length - MAX_AVATAR_HISTORY)
+                        : history;
+                    avatarHistory.current.set(updatedUserId, capped);
+                }
+                setState((prev) => ({
+                    ...prev,
+                    users: prev.users.map((u) => u.id === updatedUserId ? { ...u, ...updates } : u),
+                }));
+                break;
+            }
+            case 'error': {
+                setState((prev) => {
+                    const pending = prev.optimistic.filter((m) => m.status === 'sending');
+                    if (pending.length === 1) {
+                        return {
+                            ...prev,
+                            optimistic: (0, core_1.markOptimisticFailed)(prev.optimistic, pending[0].clientId),
+                            error: msg.message,
+                        };
+                    }
+                    return { ...prev, error: msg.message };
+                });
+                break;
+            }
+            // mention:notification and channel:notification — host app handles audio
+            case 'mention:notification':
+            case 'channel:notification':
+            case 'stickers:updated':
+            default:
+                break;
+        }
+    }, [loadMessages]);
+    // ── Status change handler ──────────────────────────────────────────────────
+    const handleStatusChange = (0, react_1.useCallback)((status) => {
+        setState((prev) => ({ ...prev, connectionStatus: status }));
+        if (status === 'connected' && newestMessageIdRef.current) {
+            // Reconnected — catch up any messages we missed
+            loadMessages({ after: newestMessageIdRef.current });
+        }
+    }, [loadMessages]);
+    // ── Keep refs updated with latest callbacks ────────────────────────────────
+    (0, react_1.useEffect)(() => {
+        handleWsMessageRef.current = handleWsMessage;
+        handleStatusChangeRef.current = handleStatusChange;
+    });
+    // ── Connect / disconnect when auth changes ─────────────────────────────────
+    (0, react_1.useEffect)(() => {
+        // Don't connect while auth is still being determined
+        if (!stationSlug || authState.status === 'loading')
+            return;
+        const conn = new core_1.ChatConnection(() => {
+            const token = authState.status === 'authenticated' ? (getToken() ?? undefined) : undefined;
+            return (0, buildRnWsUrl_1.buildRnWsUrl)(serverUrl, stationSlug, token);
+        }, (msg) => handleWsMessageRef.current?.(msg), (status) => handleStatusChangeRef.current?.(status));
+        connRef.current = conn;
+        conn.connect();
+        return () => {
+            conn.close();
+            connRef.current = null;
+        };
+    }, [authState.status, stationSlug, serverUrl, getToken]);
+    // ── Load older messages ────────────────────────────────────────────────────
+    const loadOlderMessages = (0, react_1.useCallback)(async () => {
+        if (!stationSlug || !oldestMessageIdRef.current || state.loadingOlder)
+            return;
+        setState((prev) => ({ ...prev, loadingOlder: true }));
+        try {
+            const res = await api.getMessages(stationSlug, {
+                before: oldestMessageIdRef.current,
+                limit: PAGE_SIZE,
+            });
+            const older = res.messages ?? [];
+            setState((prev) => {
+                const merged = (0, core_1.deduplicateMessages)([...older, ...prev.messages]);
+                if (older.length > 0) {
+                    oldestMessageIdRef.current = older[0].id;
+                }
+                return {
+                    ...prev,
+                    messages: merged,
+                    hasOlderMessages: res.hasMore ?? false,
+                    loadingOlder: false,
+                };
+            });
+        }
+        catch {
+            setState((prev) => ({ ...prev, loadingOlder: false }));
+        }
+    }, [api, stationSlug, state.loadingOlder]);
+    // ── Send message (optimistic) ──────────────────────────────────────────────
+    const sendMessage = (0, react_1.useCallback)((content, replyTo) => {
+        if (!connRef.current || !authState.user)
+            return;
+        const clientId = (0, core_1.generateClientId)();
+        const optimisticMsg = {
+            clientId,
+            content: content.trim(),
+            authorId: userId,
+            authorDisplayName: authState.user.displayName,
+            authorAvatarUrl: authState.user.avatarUrl,
+            createdAt: new Date(),
+            status: 'sending',
+        };
+        setState((prev) => ({ ...prev, optimistic: [...prev.optimistic, optimisticMsg] }));
+        pendingClientIds.current.set(clientId, content.trim());
+        connRef.current.send({
+            type: 'message:send',
+            content: content.trim(),
+            clientId,
+            replyToMessageId: replyTo?.messageId,
+            replyAuthorName: replyTo?.authorName,
+            replyExcerpt: replyTo?.excerpt,
+        });
+    }, [authState.user, userId]);
+    // ── Moderator REST actions ─────────────────────────────────────────────────
+    const deleteMessage = (0, react_1.useCallback)(async (messageId) => {
+        if (!stationSlug)
+            return;
+        await api.deleteMessage(stationSlug, messageId);
+        setState((prev) => ({
+            ...prev,
+            messages: prev.messages.map((m) => m.id === messageId
+                ? { ...m, is_deleted: true, content: null }
+                : m),
+        }));
+    }, [api, stationSlug]);
+    const banUser = (0, react_1.useCallback)(async (targetUserId, params) => {
+        if (!stationSlug)
+            return;
+        await api.createBan(stationSlug, targetUserId, params);
+    }, [api, stationSlug]);
+    const reportMessage = (0, react_1.useCallback)(async (messageId, reason, details) => {
+        if (!stationSlug)
+            return;
+        await api.createReport(stationSlug, messageId, reason, details);
+    }, [api, stationSlug]);
+    const editMessage = (0, react_1.useCallback)(async (messageId, newContent) => {
+        if (!stationSlug)
+            return;
+        try {
+            const edited = await api.editMessage(stationSlug, messageId, newContent);
+            setState((prev) => ({
+                ...prev,
+                messages: prev.messages.map((m) => m.id === messageId ? { ...m, ...edited } : m),
+            }));
+        }
+        catch (err) {
+            setState((prev) => ({ ...prev, error: 'Failed to edit message' }));
+            throw err;
+        }
+    }, [api, stationSlug]);
+    // ── Expose user directory lookup ───────────────────────────────────────────
+    const getUserInfo = (0, react_1.useCallback)((userId) => userDirectory.current.get(userId), []);
+    return {
+        ...state,
+        sendMessage,
+        loadOlderMessages,
+        editMessage,
+        deleteMessage,
+        banUser,
+        reportMessage,
+        getUserInfo,
+        getAvatarForMessage,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @relaya-chat/react-native — public API surface
+ *
+ * Headless hooks and utilities for building Relaya chat in React Native / Expo.
+ * No UI components are exported — host apps render their own native components
+ * using the state and actions provided by these hooks.
+ */
+export { useRelayaAuth } from './hooks/useRelayaAuth';
+export type { RelayaAuthOptions, RelayaAuthState, RelayaAuthActions, RelayaAuthUser, RelayaAuthStation, AuthStatus, } from './hooks/useRelayaAuth';
+export { useRelayaChat } from './hooks/useRelayaChat';
+export type { RelayaChatOptions, RelayaChatState, RelayaChatActions, OnlineUser, ReplyData, } from './hooks/useRelayaChat';
+export { getMessageMenuItems } from './utils/getMessageMenuItems';
+export type { MessageMenuItems, MessageMenuOpts, } from './utils/getMessageMenuItems';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,UAAU,GACX,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,UAAU,EACV,SAAS,GACV,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,YAAY,EACV,gBAAgB,EAChB,eAAe,GAChB,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+// Copyright (c) 2026 JAB Ventures, Inc. MIT License.
+// See LICENSE file at https://github.com/relaya-chat/sdk
+/**
+ * @relaya-chat/react-native — public API surface
+ *
+ * Headless hooks and utilities for building Relaya chat in React Native / Expo.
+ * No UI components are exported — host apps render their own native components
+ * using the state and actions provided by these hooks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMessageMenuItems = exports.useRelayaChat = exports.useRelayaAuth = void 0;
+// ── Auth hook ─────────────────────────────────────────────────────────────────
+var useRelayaAuth_1 = require("./hooks/useRelayaAuth");
+Object.defineProperty(exports, "useRelayaAuth", { enumerable: true, get: function () { return useRelayaAuth_1.useRelayaAuth; } });
+// ── Chat hook ─────────────────────────────────────────────────────────────────
+var useRelayaChat_1 = require("./hooks/useRelayaChat");
+Object.defineProperty(exports, "useRelayaChat", { enumerable: true, get: function () { return useRelayaChat_1.useRelayaChat; } });
+// ── Moderation utility ────────────────────────────────────────────────────────
+var getMessageMenuItems_1 = require("./utils/getMessageMenuItems");
+Object.defineProperty(exports, "getMessageMenuItems", { enumerable: true, get: function () { return getMessageMenuItems_1.getMessageMenuItems; } });

package/dist/utils/buildRnWsUrl.d.ts

@@ -0,0 +1,11 @@
+/**
+ * buildRnWsUrl — constructs the WebSocket URL for React Native chat connections.
+ *
+ * Converts an http(s) serverUrl to ws(s) and appends query parameters:
+ *   - token (Bearer JWT, URI-encoded) — omitted for anonymous connections
+ *   - station (space slug, URI-encoded)
+ *
+ * This is an internal utility; not part of the public @relaya-chat/react-native API.
+ */
+export declare function buildRnWsUrl(serverUrl: string, stationSlug: string, token?: string): string;
+//# sourceMappingURL=buildRnWsUrl.d.ts.map

package/dist/utils/buildRnWsUrl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildRnWsUrl.d.ts","sourceRoot":"","sources":["../../src/utils/buildRnWsUrl.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,KAAK,CAAC,EAAE,MAAM,GACb,MAAM,CAKR"}

package/dist/utils/buildRnWsUrl.js

@@ -0,0 +1,20 @@
+"use strict";
+// Copyright (c) 2026 JAB Ventures, Inc. MIT License.
+// See LICENSE file at https://github.com/relaya-chat/sdk
+/**
+ * buildRnWsUrl — constructs the WebSocket URL for React Native chat connections.
+ *
+ * Converts an http(s) serverUrl to ws(s) and appends query parameters:
+ *   - token (Bearer JWT, URI-encoded) — omitted for anonymous connections
+ *   - station (space slug, URI-encoded)
+ *
+ * This is an internal utility; not part of the public @relaya-chat/react-native API.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRnWsUrl = buildRnWsUrl;
+function buildRnWsUrl(serverUrl, stationSlug, token) {
+    // Convert http(s):// → ws(s)://
+    const wsBase = serverUrl.replace(/^http/, 'ws');
+    const tokenParam = token ? `token=${encodeURIComponent(token)}&` : '';
+    return `${wsBase}/ws?${tokenParam}station=${encodeURIComponent(stationSlug)}`;
+}

package/dist/utils/getMessageMenuItems.d.ts

@@ -0,0 +1,29 @@
+/**
+ * getMessageMenuItems — pure moderation decision utility.
+ *
+ * Determines which context menu / action sheet items to show for a given
+ * message, based on ownership, permissions, and message state.
+ *
+ * This function is intentionally pure (no side effects, no platform deps)
+ * so it can be unit-tested without a React Native environment and shared
+ * across web and mobile surfaces to prevent moderation UX drift.
+ */
+import type { Message, Permission } from '@relaya-chat/core';
+export interface MessageMenuItems {
+    showReply: boolean;
+    showEdit: boolean;
+    showDelete: boolean;
+    showReport: boolean;
+    showBan: boolean;
+    /** Avatar options — only shown on the current user's own messages */
+    showAvatarOptions: boolean;
+}
+export interface MessageMenuOpts {
+    message: Message;
+    currentUserId: string | null;
+    currentUserPermissions: Permission[];
+    currentUserPriority: number;
+    messageAuthorPriority: number;
+}
+export declare function getMessageMenuItems(opts: MessageMenuOpts): MessageMenuItems;
+//# sourceMappingURL=getMessageMenuItems.d.ts.map

package/dist/utils/getMessageMenuItems.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getMessageMenuItems.d.ts","sourceRoot":"","sources":["../../src/utils/getMessageMenuItems.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,sBAAsB,EAAE,UAAU,EAAE,CAAC;IACrC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAKD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,eAAe,GAAG,gBAAgB,CA0C3E"}

package/dist/utils/getMessageMenuItems.js

@@ -0,0 +1,43 @@
+"use strict";
+// Copyright (c) 2026 JAB Ventures, Inc. MIT License.
+// See LICENSE file at https://github.com/relaya-chat/sdk
+/**
+ * getMessageMenuItems — pure moderation decision utility.
+ *
+ * Determines which context menu / action sheet items to show for a given
+ * message, based on ownership, permissions, and message state.
+ *
+ * This function is intentionally pure (no side effects, no platform deps)
+ * so it can be unit-tested without a React Native environment and shared
+ * across web and mobile surfaces to prevent moderation UX drift.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMessageMenuItems = getMessageMenuItems;
+const EDIT_WINDOW_MS = 15 * 60 * 1000; // 15 minutes
+const MAX_EDITS = 2;
+function getMessageMenuItems(opts) {
+    const { message, currentUserId, currentUserPermissions, currentUserPriority, messageAuthorPriority, } = opts;
+    const isOwn = !!currentUserId && message.user_id === currentUserId;
+    const isAnonymous = !currentUserId;
+    const isDeleted = message.is_deleted;
+    const hasPermission = (p) => currentUserPermissions.includes(p);
+    const withinEditWindow = !isDeleted &&
+        Date.now() - new Date(message.created_at).getTime() < EDIT_WINDOW_MS;
+    const editCountOk = (message.edit_count ?? 0) < MAX_EDITS;
+    // Ban is only available when the target has lower priority than the actor
+    const canBanTarget = messageAuthorPriority < currentUserPriority;
+    return {
+        showReply: !isAnonymous && !isDeleted,
+        showEdit: isOwn &&
+            withinEditWindow &&
+            editCountOk &&
+            hasPermission('chat.edit_own'),
+        showDelete: !isDeleted && (isOwn || hasPermission('chat.delete_any')),
+        showReport: !isOwn && !isAnonymous && !isDeleted,
+        showBan: !isOwn &&
+            !isAnonymous &&
+            hasPermission('chat.ban_user') &&
+            canBanTarget,
+        showAvatarOptions: isOwn,
+    };
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@relaya-chat/react-native",
+  "version": "1.1.0",
+  "private": false,
+  "description": "Real-time community chat hooks for React Native and Expo — OTP auth, WebSocket messaging, moderation. Connects to the Relaya™ SaaS at api.relaya.chat. Headless: bring your own UI.",
+  "keywords": [
+    "chat", "real-time", "realtime", "community-chat", "react-native",
+    "expo", "websocket", "moderation", "radio", "live", "ugc",
+    "hooks", "headless"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/relaya-chat/sdk.git",
+    "directory": "packages/react-native"
+  },
+  "homepage": "https://relaya.chat",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts"
+  },
+  "peerDependencies": {
+    "@react-native-async-storage/async-storage": ">=1.18.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.72.0"
+  },
+  "dependencies": {
+    "@relaya-chat/core": "^1.0.0"
+  },
+  "devDependencies": {
+    "@react-native-async-storage/async-storage": "^3.0.2",
+    "@types/react": "^18.3.0",
+    "@types/react-native": "^0.73.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.2"
+  }
+}