@fastrelay/js-sdk 0.1.0

package/dist/realtime.js

@@ -0,0 +1,521 @@
+import { parseJsonSafely, toAbsoluteUrl } from "./utils.js";
+const MAX_RECENT_EVENT_IDS = 1000;
+export class FastrelayRealtime {
+    client;
+    token;
+    tokenProvider;
+    socketFactory;
+    subscribeDebounceMs;
+    deadConnectionTimeoutMs;
+    reconnectInitialDelayMs;
+    reconnectMaxDelayMs;
+    feedListeners = new Map();
+    acknowledgedFeeds = new Set();
+    pendingSubscribes = new Set();
+    pendingUnsubscribes = new Set();
+    recentEventIds = new Set();
+    eventListeners = new Set();
+    stateListeners = new Set();
+    errorListeners = new Set();
+    videoListeners = new Set();
+    socket = null;
+    subscribeBatchTimer = null;
+    reconnectTimer = null;
+    deadConnectionTimer = null;
+    lastServerMessageAt = null;
+    state = 'disconnected';
+    shouldBeConnected = false;
+    disposed = false;
+    awaitingTokenRefresh = false;
+    hasConnectedAtLeastOnce = false;
+    generation = 0;
+    reconnectAttempt = 0;
+    constructor(options) {
+        this.client = options.client;
+        this.token = options.token;
+        this.tokenProvider = options.tokenProvider;
+        this.socketFactory =
+            options.socketFactory ??
+                ((url) => new WebSocket(url));
+        this.subscribeDebounceMs = options.subscribeDebounceMs ?? 50;
+        this.deadConnectionTimeoutMs = options.deadConnectionTimeoutMs ?? 90_000;
+        this.reconnectInitialDelayMs = options.reconnectInitialDelayMs ?? 1_000;
+        this.reconnectMaxDelayMs = options.reconnectMaxDelayMs ?? 30_000;
+    }
+    get connectionState() {
+        return this.state;
+    }
+    onEvent(callback) {
+        this.eventListeners.add(callback);
+        return () => this.eventListeners.delete(callback);
+    }
+    onStateChange(callback) {
+        this.stateListeners.add(callback);
+        return () => this.stateListeners.delete(callback);
+    }
+    onError(callback) {
+        this.errorListeners.add(callback);
+        return () => this.errorListeners.delete(callback);
+    }
+    onVideoStatus(callback) {
+        this.videoListeners.add(callback);
+        return () => this.videoListeners.delete(callback);
+    }
+    /**
+     * Listen to events for one feed. Subscribes over the socket on the first
+     * listener and unsubscribes when the last one is removed.
+     */
+    subscribeToFeed(feedId, callback, { type } = {}) {
+        if (this.disposed) {
+            throw new Error('FastrelayRealtime is disposed.');
+        }
+        const normalizedFeedId = feedId.trim();
+        if (normalizedFeedId === '') {
+            throw new TypeError('feedId must not be empty.');
+        }
+        let listeners = this.feedListeners.get(normalizedFeedId);
+        if (!listeners) {
+            listeners = new Set();
+            this.feedListeners.set(normalizedFeedId, listeners);
+            this.pendingUnsubscribes.delete(normalizedFeedId);
+            this.pendingSubscribes.add(normalizedFeedId);
+            this.scheduleSubscribeBatch();
+        }
+        const listener = { type: type?.trim() || undefined, callback };
+        listeners.add(listener);
+        return () => {
+            const current = this.feedListeners.get(normalizedFeedId);
+            if (!current)
+                return;
+            current.delete(listener);
+            if (current.size === 0) {
+                this.feedListeners.delete(normalizedFeedId);
+                this.acknowledgedFeeds.delete(normalizedFeedId);
+                this.pendingSubscribes.delete(normalizedFeedId);
+                this.pendingUnsubscribes.add(normalizedFeedId);
+                this.scheduleSubscribeBatch();
+            }
+        };
+    }
+    updateToken(token) {
+        this.token = token;
+    }
+    onBaseUrlChanged() {
+        if (!this.shouldBeConnected || this.disposed)
+            return;
+        this.scheduleReconnect({ immediate: true });
+    }
+    connect() {
+        if (this.disposed)
+            return;
+        this.shouldBeConnected = true;
+        this.cancelReconnectTimer();
+        void this.openSocket(this.hasConnectedAtLeastOnce);
+    }
+    disconnect({ clearSubscriptions = false } = {}) {
+        if (this.disposed)
+            return;
+        this.shouldBeConnected = false;
+        this.awaitingTokenRefresh = false;
+        this.cancelReconnectTimer();
+        this.cancelSubscribeBatch();
+        this.pendingSubscribes.clear();
+        this.pendingUnsubscribes.clear();
+        this.closeSocketResources();
+        this.acknowledgedFeeds.clear();
+        if (clearSubscriptions) {
+            this.feedListeners.clear();
+        }
+        this.setState('disconnected');
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.shouldBeConnected = false;
+        this.cancelReconnectTimer();
+        this.cancelSubscribeBatch();
+        this.stopDeadConnectionMonitor();
+        this.closeSocketResources();
+        this.feedListeners.clear();
+        this.eventListeners.clear();
+        this.stateListeners.clear();
+        this.errorListeners.clear();
+        this.videoListeners.clear();
+    }
+    // ---- internals ---------------------------------------------------------
+    async openSocket(isReconnect) {
+        if (this.disposed || !this.shouldBeConnected)
+            return;
+        if (this.awaitingTokenRefresh) {
+            const refreshed = await this.refreshToken();
+            if (this.disposed || !this.shouldBeConnected)
+                return;
+            if (!refreshed) {
+                this.scheduleReconnect();
+                return;
+            }
+            this.awaitingTokenRefresh = false;
+        }
+        const token = this.token.trim();
+        if (token === '') {
+            this.emitError({
+                code: 'MISSING_TOKEN',
+                message: 'Realtime connection requires a non-empty token.',
+                retryable: false,
+            });
+            this.setState('disconnected');
+            return;
+        }
+        this.closeSocketResources();
+        const generation = ++this.generation;
+        this.setState(isReconnect ? 'reconnecting' : 'connecting');
+        const httpUrl = toAbsoluteUrl(this.client.baseUrl, '/v1/realtime', { token });
+        const wsUrl = httpUrl.replace(/^https:/, 'wss:').replace(/^http:/, 'ws:');
+        let socket;
+        try {
+            socket = this.socketFactory(wsUrl);
+        }
+        catch (error) {
+            this.emitError({
+                code: 'CONNECTION_DROPPED',
+                message: 'Failed to open realtime socket.',
+                retryable: true,
+                cause: error,
+            });
+            this.scheduleReconnect();
+            return;
+        }
+        this.socket = socket;
+        this.lastServerMessageAt = Date.now();
+        this.startDeadConnectionMonitor();
+        socket.onopen = () => this.onConnected(generation, isReconnect);
+        socket.onmessage = (event) => {
+            if (typeof event.data === 'string') {
+                this.handleRawMessage(event.data, generation);
+            }
+        };
+        socket.onclose = (event) => this.onDisconnected(generation, event.code ?? null, event.reason ?? null);
+        socket.onerror = () => {
+            // The paired close event carries the actionable detail; nothing to do here.
+        };
+    }
+    onConnected(generation, _wasReconnect) {
+        if (this.disposed || generation !== this.generation)
+            return;
+        this.reconnectAttempt = 0;
+        this.cancelReconnectTimer();
+        this.setState('connected');
+        this.hasConnectedAtLeastOnce = true;
+        for (const feed of this.feedListeners.keys()) {
+            if (!this.acknowledgedFeeds.has(feed)) {
+                this.pendingSubscribes.add(feed);
+            }
+        }
+        this.flushSubscriptionBatch();
+    }
+    onDisconnected(generation, closeCode, reason) {
+        if (this.disposed || generation !== this.generation)
+            return;
+        this.stopDeadConnectionMonitor();
+        this.acknowledgedFeeds.clear();
+        this.setState('disconnected');
+        if (!this.shouldBeConnected)
+            return;
+        if (closeCode === 4029 || closeCode === 4002) {
+            this.shouldBeConnected = false;
+            this.emitError({
+                code: closeCode === 4029 ? 'CONNECTION_LIMIT_EXCEEDED' : 'INVALID_TOKEN',
+                message: closeCode === 4029
+                    ? 'Realtime connection limit exceeded for this user or app.'
+                    : 'Realtime token is invalid.',
+                retryable: false,
+                closeCode,
+                details: reason,
+            });
+            return;
+        }
+        if (closeCode === 4003) {
+            if (!this.tokenProvider) {
+                this.shouldBeConnected = false;
+                this.emitError({
+                    code: 'TOKEN_EXPIRED',
+                    message: 'Realtime token expired and no tokenProvider was configured.',
+                    retryable: false,
+                    closeCode,
+                    details: reason,
+                });
+                return;
+            }
+            this.awaitingTokenRefresh = true;
+            this.scheduleReconnect({ immediate: true });
+            return;
+        }
+        this.emitError({
+            code: 'CONNECTION_DROPPED',
+            message: 'Realtime connection dropped.',
+            retryable: true,
+            closeCode,
+            details: reason,
+        });
+        this.scheduleReconnect();
+    }
+    handleRawMessage(rawMessage, generation) {
+        if (this.disposed || generation !== this.generation)
+            return;
+        this.lastServerMessageAt = Date.now();
+        const decoded = parseJsonSafely(rawMessage);
+        if (!decoded || typeof decoded !== 'object' || Array.isArray(decoded)) {
+            return;
+        }
+        const payload = decoded;
+        const type = String(payload.type ?? '');
+        switch (type) {
+            case 'connection.established':
+            case 'heartbeat':
+            case 'server.going_away':
+                return;
+            case 'subscribe.success':
+                for (const feed of toStringArray(payload.feeds)) {
+                    this.acknowledgedFeeds.add(feed);
+                }
+                return;
+            case 'unsubscribe.success':
+                for (const feed of toStringArray(payload.feeds)) {
+                    this.acknowledgedFeeds.delete(feed);
+                }
+                return;
+            case 'subscribe.error':
+            case 'error':
+                this.emitControlError(type, payload);
+                return;
+            case 'video.ready':
+            case 'video.failed': {
+                const videoId = String(payload.videoId ?? '');
+                if (videoId === '')
+                    return;
+                const event = payload;
+                for (const listener of [...this.videoListeners])
+                    listener(event);
+                return;
+            }
+        }
+        const event = {
+            type,
+            feedId: String(payload.feedId ?? ''),
+            eventId: String(payload.eventId ?? ''),
+            seq: typeof payload.seq === 'number' ? payload.seq : null,
+            createdAt: payload.createdAt !== undefined ? String(payload.createdAt) : undefined,
+            data: payload.data && typeof payload.data === 'object'
+                ? payload.data
+                : {},
+        };
+        if (event.type === '' || event.feedId === '')
+            return;
+        if (event.eventId !== '' && !this.trackEventId(event.eventId))
+            return;
+        this.dispatchEvent(event);
+    }
+    dispatchEvent(event) {
+        for (const listener of [...this.eventListeners])
+            listener(event);
+        const feedListeners = this.feedListeners.get(event.feedId);
+        if (!feedListeners)
+            return;
+        for (const listener of [...feedListeners]) {
+            if (!listener.type || listener.type === event.type) {
+                listener.callback(event);
+            }
+        }
+    }
+    emitControlError(type, payload) {
+        const errorMap = payload.error && typeof payload.error === 'object'
+            ? payload.error
+            : {};
+        const code = String(errorMap.code ??
+            (type === 'subscribe.error' ? 'SUBSCRIBE_ERROR' : 'REALTIME_ERROR'));
+        this.emitError({
+            code,
+            message: String(errorMap.message ??
+                (type === 'subscribe.error'
+                    ? 'Feed subscription failed.'
+                    : 'Realtime error received from server.')),
+            retryable: code !== 'CONNECTION_LIMIT_EXCEEDED' && code !== 'INVALID_TOKEN',
+            details: errorMap.details,
+            hint: errorMap.hint !== undefined ? String(errorMap.hint) : undefined,
+        });
+    }
+    trackEventId(eventId) {
+        if (this.recentEventIds.has(eventId))
+            return false;
+        this.recentEventIds.add(eventId);
+        if (this.recentEventIds.size > MAX_RECENT_EVENT_IDS) {
+            const oldest = this.recentEventIds.values().next().value;
+            if (oldest !== undefined)
+                this.recentEventIds.delete(oldest);
+        }
+        return true;
+    }
+    scheduleSubscribeBatch() {
+        if (this.disposed || this.subscribeBatchTimer !== null)
+            return;
+        this.subscribeBatchTimer = setTimeout(() => {
+            this.subscribeBatchTimer = null;
+            this.flushSubscriptionBatch();
+        }, this.subscribeDebounceMs);
+    }
+    flushSubscriptionBatch() {
+        if (this.disposed || this.state !== 'connected')
+            return;
+        if (this.pendingSubscribes.size > 0) {
+            const feeds = [...this.pendingSubscribes].sort();
+            this.pendingSubscribes.clear();
+            this.send({ type: 'subscribe', feeds });
+        }
+        if (this.pendingUnsubscribes.size > 0) {
+            const feeds = [...this.pendingUnsubscribes].sort();
+            this.pendingUnsubscribes.clear();
+            this.send({ type: 'unsubscribe', feeds });
+        }
+    }
+    send(payload) {
+        if (!this.socket || this.disposed)
+            return;
+        try {
+            this.socket.send(JSON.stringify(payload));
+        }
+        catch (error) {
+            this.emitError({
+                code: 'SEND_FAILED',
+                message: 'Failed to send realtime message.',
+                retryable: true,
+                cause: error,
+                details: payload,
+            });
+        }
+    }
+    setState(state) {
+        if (this.state === state)
+            return;
+        this.state = state;
+        for (const listener of [...this.stateListeners])
+            listener(state);
+    }
+    emitError(error) {
+        if (this.disposed)
+            return;
+        for (const listener of [...this.errorListeners])
+            listener(error);
+    }
+    startDeadConnectionMonitor() {
+        this.stopDeadConnectionMonitor();
+        const frequency = Math.max(1000, Math.round(this.deadConnectionTimeoutMs / 3));
+        this.deadConnectionTimer = setInterval(() => {
+            if (this.disposed || !this.shouldBeConnected)
+                return;
+            if (this.lastServerMessageAt === null)
+                return;
+            if (Date.now() - this.lastServerMessageAt < this.deadConnectionTimeoutMs) {
+                return;
+            }
+            this.emitError({
+                code: 'DEAD_CONNECTION_TIMEOUT',
+                message: 'No realtime heartbeat/messages received within the dead connection timeout.',
+                retryable: true,
+            });
+            this.scheduleReconnect({ immediate: true });
+        }, frequency);
+    }
+    stopDeadConnectionMonitor() {
+        if (this.deadConnectionTimer !== null) {
+            clearInterval(this.deadConnectionTimer);
+            this.deadConnectionTimer = null;
+        }
+    }
+    scheduleReconnect({ immediate = false } = {}) {
+        if (this.disposed || !this.shouldBeConnected)
+            return;
+        if (this.reconnectTimer !== null)
+            return;
+        const delay = immediate ? 0 : this.nextReconnectDelay();
+        this.setState('reconnecting');
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            void this.openSocket(true);
+        }, delay);
+    }
+    nextReconnectDelay() {
+        const exponent = Math.min(this.reconnectAttempt, 10);
+        const rawDelay = this.reconnectInitialDelayMs * 2 ** exponent;
+        const cappedDelay = Math.min(rawDelay, this.reconnectMaxDelayMs);
+        const jitter = 0.8 + Math.random() * 0.4;
+        this.reconnectAttempt += 1;
+        return Math.max(1, Math.round(cappedDelay * jitter));
+    }
+    cancelReconnectTimer() {
+        if (this.reconnectTimer !== null) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    cancelSubscribeBatch() {
+        if (this.subscribeBatchTimer !== null) {
+            clearTimeout(this.subscribeBatchTimer);
+            this.subscribeBatchTimer = null;
+        }
+    }
+    closeSocketResources() {
+        this.stopDeadConnectionMonitor();
+        if (this.socket) {
+            this.socket.onopen = null;
+            this.socket.onmessage = null;
+            this.socket.onclose = null;
+            this.socket.onerror = null;
+            try {
+                this.socket.close();
+            }
+            catch {
+                // Already closed.
+            }
+            this.socket = null;
+        }
+    }
+    async refreshToken() {
+        if (!this.tokenProvider) {
+            this.emitError({
+                code: 'TOKEN_PROVIDER_MISSING',
+                message: 'Realtime token refresh requested but tokenProvider is null.',
+                retryable: false,
+            });
+            return false;
+        }
+        const generation = this.generation;
+        try {
+            const token = await this.tokenProvider();
+            // A dispose or newer connection attempt during the await means this
+            // token belongs to a dead session; never write it into the client.
+            if (this.disposed || generation !== this.generation)
+                return false;
+            if (token.trim() === '') {
+                throw new Error('tokenProvider returned an empty token.');
+            }
+            this.token = token;
+            this.client.setToken(token);
+            return true;
+        }
+        catch (error) {
+            this.emitError({
+                code: 'TOKEN_REFRESH_FAILED',
+                message: 'Failed to refresh realtime token.',
+                retryable: true,
+                cause: error,
+            });
+            return false;
+        }
+    }
+}
+function toStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((entry) => String(entry ?? '')).filter((entry) => entry !== '');
+}

package/dist/types.d.ts

@@ -0,0 +1,190 @@
+export interface FastrelayUser {
+    id: string;
+    displayName?: string | null;
+    profileData?: Record<string, unknown> | null;
+    role?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface FastrelayReaction {
+    id: string;
+    activityId: string;
+    userId: string;
+    user?: FastrelayUser | null;
+    type: string;
+    createdAt: string;
+}
+export interface FastrelayActivity {
+    id: string;
+    type: string;
+    text?: string | null;
+    userId: string;
+    user?: FastrelayUser | null;
+    feeds: string[];
+    visibility: string;
+    custom?: Record<string, unknown> | null;
+    popularity: number;
+    reactionCounts: Record<string, number>;
+    commentCount: number;
+    bookmarkCount: number;
+    expiresAt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+    ownReactions?: FastrelayReaction[] | null;
+}
+export interface FastrelayComment {
+    id: string;
+    activityId: string;
+    userId: string;
+    user?: FastrelayUser | null;
+    text: string;
+    parentId?: string | null;
+    mentionedUsers: string[];
+    reactionCounts: Record<string, number>;
+    score: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface FastrelayCommentReaction {
+    id: string;
+    commentId: string;
+    userId: string;
+    type: string;
+    createdAt: string;
+}
+export interface FastrelayBookmark {
+    id: string;
+    activityId: string;
+    userId: string;
+    createdAt: string;
+}
+export interface FastrelayFeedActivityPin {
+    appId: string;
+    feedId: string;
+    activityId: string;
+    pinnedAt: string;
+    pinnedBy: string;
+}
+export interface FastrelayFeedback {
+    id: string;
+    activityId: string;
+    userId: string;
+    type: 'show_more' | 'show_less';
+    createdAt: string;
+}
+export interface FastrelayFile {
+    id: string;
+    url: string;
+    type: string;
+    mimeType: string;
+    size: number;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+}
+export interface FastrelayModerationFlag {
+    id: string;
+    reporterId: string;
+    targetType: string;
+    targetId: string;
+    reason: string;
+    description?: string | null;
+    status: string;
+    resolvedBy?: string | null;
+    resolvedAt?: string | null;
+    createdAt: string;
+}
+export interface FastrelayPollOption {
+    id: string;
+    text: string;
+    voteCount: number;
+}
+export interface FastrelayPoll {
+    id: string;
+    question: string;
+    options: FastrelayPollOption[];
+    totalVotes: number;
+    userVote?: string | null;
+    expiresAt?: string | null;
+    isClosed: boolean;
+}
+export interface FastrelayUserMute {
+    id: string;
+    muterId?: string | null;
+    mutedUserId: string;
+    type: string;
+    mutedBy?: string | null;
+    expiresAt?: string | null;
+    createdAt: string;
+}
+export interface FastrelayVideo {
+    id: string;
+    mimeType: string;
+    sizeBytes: number;
+    status: 'uploading' | 'processing' | 'ready' | 'failed' | string;
+    provider: string;
+    createdAt: string;
+    hlsUrl?: string | null;
+    thumbnailUrl?: string | null;
+    durationSeconds?: number | null;
+    width?: number | null;
+    height?: number | null;
+    errorCode?: string | null;
+    errorMessage?: string | null;
+}
+export interface FastrelayVideoUploadUrl {
+    videoId: string;
+    uploadUrl: string;
+    protocol: string;
+}
+export interface FastrelayVideoStatusEvent {
+    type: 'video.ready' | 'video.failed';
+    videoId: string;
+    video?: FastrelayVideo | null;
+    errorCode?: string | null;
+    errorMessage?: string | null;
+}
+export interface CursorPage<T> {
+    data: T[];
+    nextCursor?: string | null;
+    hasMore: boolean;
+    pinned?: T[];
+}
+export interface NotificationGroup<T> {
+    groupKey: string;
+    activities: T[];
+    activityCount: number;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+}
+export interface NotificationPage<T> extends CursorPage<T> {
+    unseenCount?: number;
+    unreadCount?: number;
+    groups?: NotificationGroup<T>[];
+}
+export interface FastrelayRealtimeEvent {
+    type: string;
+    feedId: string;
+    eventId: string;
+    seq?: number | null;
+    createdAt?: string;
+    data: Record<string, unknown>;
+}
+export type FastrelayConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+export interface FastrelayRealtimeError {
+    code: string;
+    message: string;
+    retryable: boolean;
+    closeCode?: number | null;
+    details?: unknown;
+    hint?: string | null;
+    cause?: unknown;
+}
+export interface FeedActivityQuery {
+    limit?: number;
+    cursor?: string;
+    view?: string;
+    markSeen?: boolean | string;
+    markRead?: boolean | string | string[];
+    filter?: Record<string, unknown>;
+    [key: string]: unknown;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// Wire models. The fastrelay API speaks camelCase JSON, so responses are used
+// as-is; date fields are ISO-8601 strings.
+export {};