@relaya-chat/core 1.0.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/dist/apiClient.d.ts

@@ -0,0 +1,246 @@
+/**
+ * REST API client for the Relaya chat system.
+ *
+ * Fetch-based, works in both browser and React Native environments.
+ * All methods throw an ApiError on non-2xx responses.
+ */
+import type { MessageWithAuthor, Ban, MessageReport, Station, Permission, Role, StickerListing } from './types.js';
+/**
+ * Wave 6: AT/RT auth overhaul.
+ * POST /auth/verify-code now returns { accessToken, refreshToken, user, station }.
+ * No cookie is set; tokens are managed entirely client-side.
+ */
+export interface AuthVerifyResponse {
+    accessToken: string;
+    refreshToken: string;
+    user: {
+        id: string;
+        displayName: string;
+        avatarUrl: string | null;
+        permissions: Permission[];
+        roles: Role[];
+    };
+    station: {
+        id: string;
+        name: string;
+        slug: string;
+    };
+}
+export interface AuthRefreshResponse {
+    accessToken: string;
+    refreshToken: string;
+}
+export interface MessagesResponse {
+    messages: MessageWithAuthor[];
+    hasMore: boolean;
+    /** ISO 8601 date string — messages older than this are filtered by the read layer.
+     *  Determined by the space's subscription tier (retentionDays in TIER_LIMITS).
+     *  The client uses this to display a "chat history before [date] is not available on this plan" notice. */
+    retentionCutoff?: string;
+}
+export interface ReportWithDetails {
+    reportId: string;
+    messageId: string;
+    messageContent: string | null;
+    messageIsDeleted: boolean;
+    messageAuthor: {
+        userId: string;
+        displayName: string;
+    };
+    reporter: {
+        userId: string;
+        displayName: string;
+    };
+    reason: string;
+    details: string | null;
+    status: 'pending' | 'reviewed' | 'dismissed';
+    createdAt: string;
+}
+export interface ModerationConfig {
+    rateLimitWindowMs: number;
+    rateLimitMaxMessages: number;
+    duplicateWindowMs: number;
+}
+export interface ModerationConfigResponse {
+    config: ModerationConfig;
+    note: string;
+}
+export interface PresenceConfig {
+    presenceGracePeriodMs: number;
+}
+export interface PresenceConfigResponse {
+    config: PresenceConfig;
+}
+export interface BanWithUser extends Ban {
+    bannedUser?: {
+        id: string;
+        displayName: string;
+    };
+}
+export interface MemberWithRoles {
+    id: string;
+    userId: string;
+    displayName: string;
+    email: string | null;
+    permissions: Permission[];
+    roles: Role[];
+    maxPriority: number;
+    joinedAt: string;
+}
+export interface ApiError {
+    status: number;
+    code: string;
+    message: string;
+}
+export interface ThemeByMode {
+    light: Record<string, string>;
+    dark: Record<string, string>;
+}
+export interface StationSoundsResponse {
+    mentionSoundUrl: string | null;
+    channelSoundUrl: string | null;
+}
+export interface AdminMember {
+    userId: string;
+    displayName: string;
+    email: string | null;
+    avatarUrl: string | null;
+    roles: string[];
+    joinedAt: string;
+    isOnline: boolean;
+}
+export interface GetMembersAdminResponse {
+    members: AdminMember[];
+    quota: {
+        used: number;
+        limit: number | null;
+    };
+}
+export declare class ApiClient {
+    private readonly baseUrl;
+    private readonly getToken;
+    /**
+     * @param baseUrl   - Base URL for all requests (e.g. '' for same-origin in browser,
+     *                    or 'http://localhost:9000' for direct connection)
+     * @param getToken  - Callback that returns the current JWT (or null if unauthenticated)
+     */
+    constructor(baseUrl: string, getToken: () => string | null);
+    private authHeaders;
+    private request;
+    private parseResponse;
+    login(email: string, stationSlug: string): Promise<{
+        message: string;
+        expiresIn: number;
+    }>;
+    /**
+     * Request a 6-digit OTP code to be sent to the provided email
+     * Returns pending_id for use in verifyCode()
+     */
+    requestCode(email: string, stationSlug: string): Promise<{
+        message: string;
+        pendingId: string;
+        expiresIn: number;
+    }>;
+    /**
+     * Verify OTP code and obtain session
+     */
+    verifyCode(pendingId: string, code: string, stationSlug: string): Promise<AuthVerifyResponse>;
+    verify(token: string, stationSlug: string): Promise<AuthVerifyResponse>;
+    /**
+     * Exchange a refresh token for a new access token + rotated refresh token.
+     * Wave 6: accepts refreshToken in body (no cookie).
+     */
+    refresh(refreshToken: string): Promise<AuthRefreshResponse>;
+    getStation(slug: string): Promise<Station>;
+    getMessages(stationSlug: string, params?: {
+        before?: string;
+        after?: string;
+        limit?: number;
+    }): Promise<MessagesResponse>;
+    deleteMessage(stationSlug: string, messageId: string): Promise<void>;
+    editMessage(stationSlug: string, messageId: string, content: string): Promise<MessageWithAuthor>;
+    createReport(stationSlug: string, messageId: string, reason: string, details?: string): Promise<MessageReport>;
+    getReports(stationSlug: string, params?: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        reports: ReportWithDetails[];
+        total: number;
+    }>;
+    updateReport(stationSlug: string, reportId: string, update: {
+        status: 'reviewed' | 'dismissed';
+    }): Promise<{
+        reportId: string;
+        status: string;
+        reviewedBy: string;
+        reviewedAt: string;
+    }>;
+    createBan(stationSlug: string, userId: string, params?: {
+        reason?: string;
+        expiresAt?: string;
+    }): Promise<BanWithUser>;
+    liftBan(stationSlug: string, banId: string): Promise<void>;
+    getBans(stationSlug: string, activeOnly?: boolean): Promise<{
+        bans: BanWithUser[];
+    }>;
+    getMembers(stationSlug: string): Promise<{
+        members: MemberWithRoles[];
+    }>;
+    /** Admin-only: returns member list with email addresses and moderator quota. */
+    getMembersAdmin(stationSlug: string): Promise<GetMembersAdminResponse>;
+    updateMemberRole(stationSlug: string, userId: string, roleId: string): Promise<MemberWithRoles>;
+    /** Assign or remove named roles for a member (admin-only). */
+    patchMemberRoles(stationSlug: string, userId: string, changes: {
+        add?: string[];
+        remove?: string[];
+    }): Promise<{
+        userId: string;
+        roles: string[];
+    }>;
+    getMe(stationSlug: string): Promise<{
+        userId: string;
+        displayName: string;
+        chatName: string | null;
+        permissions: Permission[];
+        roles: Role[];
+    }>;
+    updateChatName(stationSlug: string, chatName: string | null): Promise<{
+        chatName: string | null;
+        displayName: string;
+    }>;
+    getModerationConfig(stationSlug: string): Promise<ModerationConfigResponse>;
+    updateModerationConfig(stationSlug: string, updates: Partial<ModerationConfig>): Promise<ModerationConfigResponse>;
+    getPresenceConfig(stationSlug: string): Promise<PresenceConfigResponse>;
+    updatePresenceConfig(stationSlug: string, updates: Partial<PresenceConfig>): Promise<PresenceConfigResponse>;
+    getStickers(stationSlug: string): Promise<{
+        stickers: StickerListing[];
+        quota: {
+            used: number;
+            limit: number;
+        };
+    }>;
+    uploadSticker(stationSlug: string, file: Blob, filename: string): Promise<{
+        sticker: StickerListing;
+        quota: {
+            used: number;
+            limit: number;
+        };
+    }>;
+    updateStickerManifest(stationSlug: string, stickers: Array<{
+        filename: string;
+        shortcode: string | null;
+    }>): Promise<{
+        stickers: StickerListing[];
+    }>;
+    deleteSticker(stationSlug: string, filename: string): Promise<void>;
+    /** Returns the per-station audio notification URLs, or null values if none configured. */
+    getSounds(stationSlug: string): Promise<StationSoundsResponse>;
+    /** Returns the stored theme overrides for a space, or { light:{}, dark:{} } if none saved. */
+    getSpaceTheme(stationSlug: string): Promise<ThemeByMode>;
+    /**
+     * Saves theme overrides for a space (admin-only).
+     * Pass { light:{}, dark:{} } to clear all overrides.
+     */
+    saveSpaceTheme(stationSlug: string, theme: ThemeByMode): Promise<ThemeByMode>;
+}

package/dist/apiClient.js

@@ -0,0 +1,241 @@
+// Copyright (c) 2026 JAB Ventures, Inc. MIT License.
+// See LICENSE file at https://github.com/relaya-chat/sdk
+/**
+ * REST API client for the Relaya chat system.
+ *
+ * Fetch-based, works in both browser and React Native environments.
+ * All methods throw an ApiError on non-2xx responses.
+ */
+// ==================== CLIENT ====================
+export class ApiClient {
+    baseUrl;
+    getToken;
+    /**
+     * @param baseUrl   - Base URL for all requests (e.g. '' for same-origin in browser,
+     *                    or 'http://localhost:9000' for direct connection)
+     * @param getToken  - Callback that returns the current JWT (or null if unauthenticated)
+     */
+    constructor(baseUrl, getToken) {
+        this.baseUrl = baseUrl;
+        this.getToken = getToken;
+    }
+    authHeaders() {
+        const token = this.getToken();
+        return token ? { Authorization: `Bearer ${token}` } : {};
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = { ...this.authHeaders() };
+        if (body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+        }
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (res.status === 204)
+            return undefined;
+        if (!res.ok) {
+            let errBody = {};
+            try {
+                errBody = (await res.json());
+            }
+            catch {
+                // ignore parse errors
+            }
+            const errObj = errBody?.error;
+            const err = {
+                status: res.status,
+                code: (typeof errObj === 'object' ? errObj?.code : undefined) ?? 'API_ERROR',
+                message: (typeof errObj === 'object' ? errObj?.message : errObj) ?? res.statusText,
+            };
+            throw err;
+        }
+        return res.json();
+    }
+    async parseResponse(res) {
+        if (res.status === 204)
+            return undefined;
+        if (!res.ok) {
+            let errBody = {};
+            try {
+                errBody = (await res.json());
+            }
+            catch {
+                // ignore parse errors
+            }
+            const errObj = errBody?.error;
+            const err = {
+                status: res.status,
+                code: (typeof errObj === 'object' ? errObj?.code : undefined) ?? 'API_ERROR',
+                message: (typeof errObj === 'object' ? errObj?.message : errObj) ?? res.statusText,
+            };
+            throw err;
+        }
+        return res.json();
+    }
+    // ── Auth ──────────────────────────────────────────────────────────────────
+    async login(email, stationSlug) {
+        return this.request('POST', '/auth/login', { email, stationSlug });
+    }
+    /**
+     * Request a 6-digit OTP code to be sent to the provided email
+     * Returns pending_id for use in verifyCode()
+     */
+    async requestCode(email, stationSlug) {
+        return this.request('POST', '/auth/request-code', { email, stationSlug });
+    }
+    /**
+     * Verify OTP code and obtain session
+     */
+    async verifyCode(pendingId, code, stationSlug) {
+        return this.request('POST', '/auth/verify-code', { pendingId, code, stationSlug });
+    }
+    async verify(token, stationSlug) {
+        return this.request('GET', `/auth/verify?token=${encodeURIComponent(token)}&station=${encodeURIComponent(stationSlug)}`);
+    }
+    /**
+     * Exchange a refresh token for a new access token + rotated refresh token.
+     * Wave 6: accepts refreshToken in body (no cookie).
+     */
+    async refresh(refreshToken) {
+        return this.request('POST', '/auth/refresh', { refreshToken });
+    }
+    // ── Station ───────────────────────────────────────────────────────────────
+    async getStation(slug) {
+        return this.request('GET', `/api/chat/stations/${encodeURIComponent(slug)}`);
+    }
+    // ── Messages ──────────────────────────────────────────────────────────────
+    async getMessages(stationSlug, params) {
+        const qs = new URLSearchParams();
+        if (params?.before)
+            qs.set('before', params.before);
+        if (params?.after)
+            qs.set('after', params.after);
+        if (params?.limit !== undefined)
+            qs.set('limit', String(params.limit));
+        const query = qs.toString() ? `?${qs.toString()}` : '';
+        return this.request('GET', `/api/chat/${stationSlug}/messages${query}`);
+    }
+    async deleteMessage(stationSlug, messageId) {
+        return this.request('DELETE', `/api/chat/${stationSlug}/messages/${messageId}`);
+    }
+    async editMessage(stationSlug, messageId, content) {
+        return this.request('PATCH', `/api/chat/${stationSlug}/messages/${messageId}`, { content });
+    }
+    // ── Reports ───────────────────────────────────────────────────────────────
+    async createReport(stationSlug, messageId, reason, details) {
+        return this.request('POST', `/api/chat/${stationSlug}/messages/${messageId}/report`, {
+            reason,
+            details,
+        });
+    }
+    async getReports(stationSlug, params) {
+        const qs = new URLSearchParams();
+        if (params?.status)
+            qs.set('status', params.status);
+        if (params?.limit !== undefined)
+            qs.set('limit', String(params.limit));
+        if (params?.offset !== undefined)
+            qs.set('offset', String(params.offset));
+        const query = qs.toString() ? `?${qs.toString()}` : '';
+        return this.request('GET', `/api/chat/${stationSlug}/reports${query}`);
+    }
+    async updateReport(stationSlug, reportId, update) {
+        return this.request('PATCH', `/api/chat/${stationSlug}/reports/${reportId}`, update);
+    }
+    // ── Bans ──────────────────────────────────────────────────────────────────
+    async createBan(stationSlug, userId, params) {
+        return this.request('POST', `/api/chat/${stationSlug}/bans`, { userId, ...params });
+    }
+    async liftBan(stationSlug, banId) {
+        return this.request('DELETE', `/api/chat/${stationSlug}/bans/${banId}`);
+    }
+    async getBans(stationSlug, activeOnly = true) {
+        const qs = activeOnly ? '?active=true' : '';
+        return this.request('GET', `/api/chat/${stationSlug}/bans${qs}`);
+    }
+    // ── Members ───────────────────────────────────────────────────────────────
+    async getMembers(stationSlug) {
+        return this.request('GET', `/api/chat/${stationSlug}/members`);
+    }
+    /** Admin-only: returns member list with email addresses and moderator quota. */
+    async getMembersAdmin(stationSlug) {
+        return this.request('GET', `/api/chat/${stationSlug}/members/admin`);
+    }
+    async updateMemberRole(stationSlug, userId, roleId) {
+        return this.request('PATCH', `/api/chat/${stationSlug}/members/${userId}/roles`, { roleId });
+    }
+    /** Assign or remove named roles for a member (admin-only). */
+    async patchMemberRoles(stationSlug, userId, changes) {
+        return this.request('PATCH', `/api/chat/${stationSlug}/members/${userId}/roles`, changes);
+    }
+    // ── Profile (Me) ──────────────────────────────────────────────────────────
+    async getMe(stationSlug) {
+        return this.request('GET', `/api/chat/${stationSlug}/me`);
+    }
+    async updateChatName(stationSlug, chatName) {
+        return this.request('PATCH', `/api/chat/${stationSlug}/me`, { chatName });
+    }
+    // ── Moderation Config ─────────────────────────────────────────────────────
+    async getModerationConfig(stationSlug) {
+        return this.request('GET', `/api/chat/${stationSlug}/moderation/config`);
+    }
+    async updateModerationConfig(stationSlug, updates) {
+        return this.request('PATCH', `/api/chat/${stationSlug}/moderation/config`, updates);
+    }
+    // ── Presence Config ───────────────────────────────────────────────────────
+    async getPresenceConfig(stationSlug) {
+        return this.request('GET', `/api/chat/${stationSlug}/presence/config`);
+    }
+    async updatePresenceConfig(stationSlug, updates) {
+        return this.request('PATCH', `/api/chat/${stationSlug}/presence/config`, updates);
+    }
+    // ── Stickers ──────────────────────────────────────────────────────────────
+    async getStickers(stationSlug) {
+        const result = await this.request('GET', `/api/chat/${stationSlug}/stickers`);
+        // Sticker URLs from the server are relative paths (/files/stations/…/stickers/…).
+        // When the chat widget is embedded cross-origin (e.g. www on port 3000, server on port 9000),
+        // the browser would resolve them against the wrong origin. Prepend baseUrl to make them absolute.
+        if (this.baseUrl) {
+            result.stickers = result.stickers.map((s) => s.url.startsWith('/') ? { ...s, url: `${this.baseUrl}${s.url}` } : s);
+        }
+        return result;
+    }
+    async uploadSticker(stationSlug, file, filename) {
+        const res = await fetch(`${this.baseUrl}/api/chat/${stationSlug}/stickers/upload`, {
+            method: 'POST',
+            headers: {
+                ...this.authHeaders(),
+                'Content-Type': file.type || 'application/octet-stream',
+                'X-Sticker-Filename': encodeURIComponent(filename),
+            },
+            body: file,
+        });
+        return this.parseResponse(res);
+    }
+    async updateStickerManifest(stationSlug, stickers) {
+        return this.request('PUT', `/api/chat/${stationSlug}/stickers/manifest`, { stickers });
+    }
+    async deleteSticker(stationSlug, filename) {
+        return this.request('DELETE', `/api/chat/${stationSlug}/stickers/${encodeURIComponent(filename)}`);
+    }
+    // ── Station Sounds ────────────────────────────────────────────────────────
+    /** Returns the per-station audio notification URLs, or null values if none configured. */
+    async getSounds(stationSlug) {
+        return this.request('GET', `/api/chat/${encodeURIComponent(stationSlug)}/sounds`);
+    }
+    // ── Space Theme ───────────────────────────────────────────────────────────
+    /** Returns the stored theme overrides for a space, or { light:{}, dark:{} } if none saved. */
+    async getSpaceTheme(stationSlug) {
+        return this.request('GET', `/api/chat/${stationSlug}/theme`);
+    }
+    /**
+     * Saves theme overrides for a space (admin-only).
+     * Pass { light:{}, dark:{} } to clear all overrides.
+     */
+    async saveSpaceTheme(stationSlug, theme) {
+        return this.request('PUT', `/api/chat/${stationSlug}/theme`, theme);
+    }
+}

package/dist/chatConnection.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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 type { WsClientMessage, WsServerMessage } from './types.js';
+export type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+export interface ChatConnectionOptions {
+    /** Base delay for exponential backoff in ms (default: 1000) */
+    backoffBaseMs?: number;
+    /** Maximum backoff delay cap in ms (default: 30000) */
+    backoffMaxMs?: number;
+    /**
+     * Called when the server forces the client to log out — either via a
+     * `force_logout` WS message or a WS close with code 4001. The caller
+     * should clear auth state and stop reconnecting.
+     */
+    onAuthRevoked?: () => void;
+}
+/**
+ * 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 declare class ChatConnection {
+    private readonly buildWsUrl;
+    private readonly onMessage;
+    private readonly onStatusChange;
+    private ws;
+    private status;
+    private reconnectAttempt;
+    private reconnectTimer;
+    /** Set to true when `close()` is called; prevents any further reconnect. */
+    private closed;
+    private readonly backoffBaseMs;
+    private readonly backoffMaxMs;
+    private readonly 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: () => string, onMessage: (msg: WsServerMessage) => void, onStatusChange: (status: ConnectionStatus) => void, options?: ChatConnectionOptions);
+    getStatus(): ConnectionStatus;
+    /** Open the WebSocket connection (or start the reconnect cycle). */
+    connect(): void;
+    /** Send a message to the server. Silently dropped if not connected. */
+    send(msg: WsClientMessage): void;
+    /**
+     * Permanently close the connection and stop any pending reconnect.
+     * After calling this, the instance should be discarded.
+     */
+    close(): void;
+    private openSocket;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+    private setStatus;
+    /**
+     * 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.
+     */
+    private handleAuthRevoked;
+}