@fastrelay/js-sdk 0.1.0

package/dist/feed.js

@@ -0,0 +1,125 @@
+export class FastrelayFeed {
+    group;
+    feedId;
+    client;
+    constructor(client, group, id) {
+        this.client = client;
+        this.group = group.trim();
+        this.feedId = id.trim();
+        if (this.group === '' || this.feedId === '') {
+            throw new TypeError('feed(group, id) requires both group and id.');
+        }
+    }
+    get id() {
+        return `${this.group}:${this.feedId}`;
+    }
+    /** Subscribe to realtime events for this feed. Returns an unsubscribe fn. */
+    on(type, callback) {
+        const realtime = this.client.realtime;
+        if (!realtime) {
+            throw new Error('Realtime is not initialized. Call connectUser(..., {realtime: true}).');
+        }
+        const normalizedType = type.trim();
+        if (normalizedType === '') {
+            throw new TypeError('Event type must not be empty.');
+        }
+        return realtime.subscribeToFeed(this.id, callback, { type: normalizedType });
+    }
+    /** Subscribe to all realtime events for this feed. */
+    onAny(callback) {
+        const realtime = this.client.realtime;
+        if (!realtime) {
+            throw new Error('Realtime is not initialized. Call connectUser(..., {realtime: true}).');
+        }
+        return realtime.subscribeToFeed(this.id, callback);
+    }
+    getOrCreate(request = {}, options) {
+        return this.client.getOrCreateFeed(this.group, this.feedId, request, options);
+    }
+    getActivities(query, options) {
+        return this.client.getFeedActivities(this.group, this.feedId, query, options);
+    }
+    getNotificationActivities(query, options) {
+        return this.client.getNotificationFeedActivities(this.group, this.feedId, query, options);
+    }
+    getCapabilities(query, options) {
+        return this.client.getCapabilities({ feed: this.id, ...query }, options);
+    }
+    addActivity(activity, options) {
+        const feeds = Array.isArray(activity.feeds)
+            ? activity.feeds.map((entry) => String(entry))
+            : [];
+        if (!feeds.includes(this.id))
+            feeds.push(this.id);
+        return this.client.addActivity({ ...activity, feeds }, options);
+    }
+    delete(options) {
+        return this.client.deleteFeed(this.group, this.feedId, options);
+    }
+    setVisibility(level, options) {
+        return this.client.setFeedVisibility(this.group, this.feedId, level, options);
+    }
+    updateSettings(settings, options) {
+        return this.client.updateFeedSettings(this.group, this.feedId, settings, options);
+    }
+    addMember(userId, { role = 'member' } = {}, options) {
+        return this.client.addFeedMember(this.group, this.feedId, { userId, role }, options);
+    }
+    removeMember(userId, options) {
+        return this.client.removeFeedMember(this.group, this.feedId, userId, options);
+    }
+    listMembers(query, options) {
+        return this.client.listFeedMembers(this.group, this.feedId, query, options);
+    }
+    follow(target, { activityCopyLimit } = {}, options) {
+        return this.client.followFeed(this.group, this.feedId, {
+            target,
+            ...(activityCopyLimit !== undefined ? { activityCopyLimit } : {}),
+        }, options);
+    }
+    batchFollow(targets, { activityCopyLimit } = {}, options) {
+        return this.client.batchFollowFeed(this.group, this.feedId, {
+            targets,
+            ...(activityCopyLimit !== undefined ? { activityCopyLimit } : {}),
+        }, options);
+    }
+    unfollow(target, { keepHistory } = {}, options) {
+        return this.client.unfollowFeed(this.group, this.feedId, target, { keepHistory }, options);
+    }
+    listFollowers(query, options) {
+        return this.client.listFollowers(this.group, this.feedId, query, options);
+    }
+    listFollowing(query, options) {
+        return this.client.listFollowing(this.group, this.feedId, query, options);
+    }
+    listFollowRequests(query, options) {
+        return this.client.listFollowRequests(this.group, this.feedId, query, options);
+    }
+    approveFollowRequest(requestId, options) {
+        return this.client.approveFollowRequest(this.group, this.feedId, requestId, options);
+    }
+    rejectFollowRequest(requestId, options) {
+        return this.client.rejectFollowRequest(this.group, this.feedId, requestId, options);
+    }
+    addReaction(activityId, type, options) {
+        return this.client.addReaction(activityId, type, options);
+    }
+    removeReaction(activityId, reactionId, options) {
+        return this.client.removeReaction(activityId, reactionId, options);
+    }
+    addComment(activityId, request, options) {
+        return this.client.addComment(activityId, request, options);
+    }
+    addBookmark(activityId, options) {
+        return this.client.addBookmark(activityId, options);
+    }
+    removeBookmark(activityId, options) {
+        return this.client.removeBookmark(activityId, options);
+    }
+    pinActivity(activityId, options) {
+        return this.client.pinActivity(this.group, this.feedId, activityId, options);
+    }
+    unpinActivity(activityId, options) {
+        return this.client.unpinActivity(this.group, this.feedId, activityId, options);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { FastrelayClient, type ConnectUserOptions, type FastrelayAuthMode, type FastrelayClientOptions, type FastrelayRequestOptions, } from './client.ts';
+export { FastrelayApiError, type FastrelayRateLimit } from './error.ts';
+export { FastrelayFeed } from './feed.ts';
+export { FeedPollingService } from './polling.ts';
+export { FastrelayRealtime, type FastrelayRealtimeOptions, type FastrelayRealtimeSocket, type FastrelayRealtimeSocketFactory, type FastrelayTokenProvider, } from './realtime.ts';
+export * from './types.ts';
+export { buildFeedActivityQuery, resolveFeedTarget, splitFeedId, type FeedTarget, } from './utils.ts';
+export { FastrelayVideoUploadError, tusUploadBytes, uploadVideoBytes, type FastrelayVideoUploadProgress, type FastrelayVideoUploadResult, } from './video-upload.ts';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { FastrelayClient, } from "./client.js";
+export { FastrelayApiError } from "./error.js";
+export { FastrelayFeed } from "./feed.js";
+export { FeedPollingService } from "./polling.js";
+export { FastrelayRealtime, } from "./realtime.js";
+export * from "./types.js";
+export { buildFeedActivityQuery, resolveFeedTarget, splitFeedId, } from "./utils.js";
+export { FastrelayVideoUploadError, tusUploadBytes, uploadVideoBytes, } from "./video-upload.js";

package/dist/polling.d.ts

@@ -0,0 +1,30 @@
+import type { FastrelayClient } from './client.ts';
+import type { CursorPage, FastrelayActivity, NotificationPage } from './types.ts';
+interface PollerHandlers<T> {
+    limit?: number;
+    onPage: (page: T) => void;
+    onError?: (error: unknown) => void;
+}
+/**
+ * Polling fallback for environments without realtime. Each pollFeed /
+ * pollNotifications call starts an independent poller; call the returned
+ * function (or dispose()) to stop it.
+ */
+export declare class FeedPollingService {
+    private readonly client;
+    private readonly activeIntervalMs;
+    private readonly backgroundIntervalMs;
+    private readonly pollers;
+    private paused;
+    constructor(client: FastrelayClient, { activeIntervalMs, backgroundIntervalMs, }?: {
+        activeIntervalMs?: number;
+        backgroundIntervalMs?: number;
+    });
+    pollFeed(group: string, id: string, { limit, onPage, onError }: PollerHandlers<CursorPage<FastrelayActivity>>): () => void;
+    pollNotifications(group: string, id: string, { limit, onPage, onError, }: PollerHandlers<NotificationPage<FastrelayActivity>>): () => void;
+    pause(): void;
+    resume(): void;
+    dispose(): void;
+    private startPoller;
+}
+export {};

package/dist/polling.js

@@ -0,0 +1,82 @@
+/**
+ * Polling fallback for environments without realtime. Each pollFeed /
+ * pollNotifications call starts an independent poller; call the returned
+ * function (or dispose()) to stop it.
+ */
+export class FeedPollingService {
+    client;
+    activeIntervalMs;
+    backgroundIntervalMs;
+    pollers = new Set();
+    paused = false;
+    constructor(client, { activeIntervalMs = 15_000, backgroundIntervalMs = 60_000, } = {}) {
+        this.client = client;
+        this.activeIntervalMs = activeIntervalMs;
+        this.backgroundIntervalMs = backgroundIntervalMs;
+    }
+    pollFeed(group, id, { limit = 25, onPage, onError }) {
+        return this.startPoller(() => this.client.getFeedActivities(group, id, { limit }), onPage, onError);
+    }
+    pollNotifications(group, id, { limit = 25, onPage, onError, }) {
+        return this.startPoller(() => this.client.getNotificationFeedActivities(group, id, { limit }), onPage, onError);
+    }
+    pause() {
+        this.paused = true;
+        for (const poller of this.pollers) {
+            poller.setInterval(this.backgroundIntervalMs);
+        }
+    }
+    resume() {
+        this.paused = false;
+        for (const poller of this.pollers) {
+            poller.setInterval(this.activeIntervalMs);
+        }
+    }
+    dispose() {
+        for (const poller of this.pollers)
+            poller.stop();
+        this.pollers.clear();
+    }
+    startPoller(fetchPage, onPage, onError) {
+        let timer = null;
+        let stopped = false;
+        let inFlight = false;
+        const poll = async () => {
+            if (stopped || inFlight)
+                return;
+            inFlight = true;
+            try {
+                const page = await fetchPage();
+                if (!stopped)
+                    onPage(page);
+            }
+            catch (error) {
+                if (!stopped)
+                    onError?.(error);
+            }
+            finally {
+                inFlight = false;
+            }
+        };
+        const poller = {
+            setInterval: (ms) => {
+                if (timer !== null)
+                    clearInterval(timer);
+                timer = setInterval(() => void poll(), ms);
+            },
+            stop: () => {
+                stopped = true;
+                if (timer !== null)
+                    clearInterval(timer);
+                timer = null;
+            },
+        };
+        poller.setInterval(this.paused ? this.backgroundIntervalMs : this.activeIntervalMs);
+        void poll();
+        this.pollers.add(poller);
+        return () => {
+            poller.stop();
+            this.pollers.delete(poller);
+        };
+    }
+}

package/dist/realtime.d.ts

@@ -0,0 +1,101 @@
+import type { FastrelayClient } from './client.ts';
+import type { FastrelayConnectionState, FastrelayRealtimeError, FastrelayRealtimeEvent, FastrelayVideoStatusEvent } from './types.ts';
+export type FastrelayTokenProvider = () => Promise<string> | string;
+/** Minimal browser-WebSocket-shaped surface, injectable for tests / Node < 22. */
+export interface FastrelayRealtimeSocket {
+    send(data: string): void;
+    close(): void;
+    onopen: ((event?: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event: {
+        code?: number;
+        reason?: string;
+    }) => void) | null;
+    onerror: ((event?: unknown) => void) | null;
+}
+export type FastrelayRealtimeSocketFactory = (url: string) => FastrelayRealtimeSocket;
+export interface FastrelayRealtimeOptions {
+    client: FastrelayClient;
+    token: string;
+    tokenProvider?: FastrelayTokenProvider;
+    socketFactory?: FastrelayRealtimeSocketFactory;
+    subscribeDebounceMs?: number;
+    deadConnectionTimeoutMs?: number;
+    reconnectInitialDelayMs?: number;
+    reconnectMaxDelayMs?: number;
+}
+type Unsubscribe = () => void;
+export declare class FastrelayRealtime {
+    private readonly client;
+    private token;
+    private readonly tokenProvider?;
+    private readonly socketFactory;
+    private readonly subscribeDebounceMs;
+    private readonly deadConnectionTimeoutMs;
+    private readonly reconnectInitialDelayMs;
+    private readonly reconnectMaxDelayMs;
+    private readonly feedListeners;
+    private readonly acknowledgedFeeds;
+    private readonly pendingSubscribes;
+    private readonly pendingUnsubscribes;
+    private readonly recentEventIds;
+    private readonly eventListeners;
+    private readonly stateListeners;
+    private readonly errorListeners;
+    private readonly videoListeners;
+    private socket;
+    private subscribeBatchTimer;
+    private reconnectTimer;
+    private deadConnectionTimer;
+    private lastServerMessageAt;
+    private state;
+    private shouldBeConnected;
+    private disposed;
+    private awaitingTokenRefresh;
+    private hasConnectedAtLeastOnce;
+    private generation;
+    private reconnectAttempt;
+    constructor(options: FastrelayRealtimeOptions);
+    get connectionState(): FastrelayConnectionState;
+    onEvent(callback: (event: FastrelayRealtimeEvent) => void): Unsubscribe;
+    onStateChange(callback: (state: FastrelayConnectionState) => void): Unsubscribe;
+    onError(callback: (error: FastrelayRealtimeError) => void): Unsubscribe;
+    onVideoStatus(callback: (event: FastrelayVideoStatusEvent) => void): Unsubscribe;
+    /**
+     * Listen to events for one feed. Subscribes over the socket on the first
+     * listener and unsubscribes when the last one is removed.
+     */
+    subscribeToFeed(feedId: string, callback: (event: FastrelayRealtimeEvent) => void, { type }?: {
+        type?: string;
+    }): Unsubscribe;
+    updateToken(token: string): void;
+    onBaseUrlChanged(): void;
+    connect(): void;
+    disconnect({ clearSubscriptions }?: {
+        clearSubscriptions?: boolean | undefined;
+    }): void;
+    dispose(): void;
+    private openSocket;
+    private onConnected;
+    private onDisconnected;
+    private handleRawMessage;
+    private dispatchEvent;
+    private emitControlError;
+    private trackEventId;
+    private scheduleSubscribeBatch;
+    private flushSubscriptionBatch;
+    private send;
+    private setState;
+    private emitError;
+    private startDeadConnectionMonitor;
+    private stopDeadConnectionMonitor;
+    private scheduleReconnect;
+    private nextReconnectDelay;
+    private cancelReconnectTimer;
+    private cancelSubscribeBatch;
+    private closeSocketResources;
+    private refreshToken;
+}
+export {};