@fastrelay/js-sdk 0.1.0

package/README.md

@@ -0,0 +1,134 @@
+# fastrelay Feed JS SDK
+
+JavaScript/TypeScript SDK for [fastrelay](https://fastrelay.io) activity feeds — feeds, activities, reactions, comments, polls, video uploads, moderation, and realtime updates over WebSocket.
+
+- Feed-first API: `fastrelay.feed(group, id)`
+- Client-only by design: user (JWT) auth, no server secrets in the app
+- Zero runtime dependencies — native `fetch`, `FormData`, `WebSocket`
+- Realtime subscriptions with automatic reconnect + token refresh
+- Polling fallback for non-realtime environments
+- Direct-to-storage video uploads (tus / Cloudflare Stream)
+- Structured `FastrelayApiError` with rate-limit metadata
+
+## Requirements
+
+- Node.js >= 18 (>= 22 for native `WebSocket`, or pass `socketFactory`), or any modern browser.
+
+## Install
+
+```bash
+npm install @fastrelay/js-sdk
+```
+
+## Quick start
+
+```ts
+import { FastrelayClient } from '@fastrelay/js-sdk';
+
+const fastrelay = new FastrelayClient({
+  apiKey: 'your_api_key',
+  baseUrl: 'https://api.fastrelay.io',
+});
+
+await fastrelay.connectUser({ id: 'john' }, userJwt, {
+  upsertUser: true,
+  realtime: true,
+  tokenProvider: async () => fetchFreshJwtFromYourBackend(),
+});
+
+const timeline = fastrelay.feed('timeline', 'john');
+
+// Read
+const page = await timeline.getActivities({ limit: 25 });
+
+// Write
+await timeline.addActivity({ type: 'post', text: 'Hello world' });
+
+// Realtime — returns an unsubscribe function
+const off = timeline.on('activity.created', (event) => {
+  console.log('new activity', event.data);
+});
+```
+
+## Authentication
+
+The SDK is client-only: every request is sent with `Authorization: Bearer <user JWT>` once `connectUser()` or `setToken()` has been called. Per-request override via options: `{ auth: 'auto' | 'user' | 'none' }` (`'server'` throws — call server endpoints from your backend).
+
+```ts
+await fastrelay.getActivity('activity_id', { auth: 'user', idempotencyKey: 'key' });
+```
+
+## Activities, reactions, comments
+
+```ts
+const activity = await fastrelay.addActivity({ feeds: ['user:john'], type: 'post', text: 'hi' });
+await fastrelay.addReaction(activity.id, 'like');
+const comment = await fastrelay.addComment(activity.id, { text: 'Nice!' });
+await fastrelay.addCommentReaction(comment.id, 'like');
+const comments = await fastrelay.listComments(activity.id, { sort: 'top', limit: 10 });
+```
+
+Also available: bookmarks (`addBookmark`/`removeBookmark`/`listBookmarks`), pins (`feed.pinActivity`), polls (`createPoll`, `vote`), follows (`feed.follow`, `feed.listFollowers`), feed members, moderation (`createFlag`, `createMute`), feedback (`submitFeedback`), file upload (`uploadFile`).
+
+## Realtime
+
+```ts
+const realtime = fastrelay.realtime!;
+realtime.onStateChange((state) => console.log(state)); // connecting/connected/reconnecting/disconnected
+realtime.onError((error) => console.warn(error.code, error.message));
+realtime.onVideoStatus((event) => console.log(event.type, event.videoId));
+
+const off = realtime.subscribeToFeed('timeline:john', (event) => { ... });
+off(); // unsubscribes (frames are batched over the socket)
+```
+
+Reconnects use exponential backoff with jitter; close code `4003` triggers a token refresh via `tokenProvider`, `4002`/`4029` are fatal. Duplicate `eventId`s are dropped.
+
+## Polling fallback
+
+```ts
+import { FeedPollingService } from '@fastrelay/js-sdk';
+
+const polling = new FeedPollingService(fastrelay);
+const stop = polling.pollFeed('timeline', 'john', {
+  limit: 25,
+  onPage: (page) => render(page.data),
+});
+// polling.pause() / polling.resume() / polling.dispose()
+```
+
+## Video upload
+
+```ts
+import { uploadVideoBytes } from '@fastrelay/js-sdk';
+
+const result = await uploadVideoBytes(fastrelay, {
+  data: fileBytes, // Uint8Array | ArrayBuffer
+  filename: 'clip.mp4',
+  mimeType: 'video/mp4',
+  onProgress: ({ fraction }) => console.log(Math.round(fraction * 100), '%'),
+});
+// Wait for realtime `video.ready`, or poll fastrelay.getVideo(result.videoId)
+```
+
+## Error handling
+
+```ts
+import { FastrelayApiError } from '@fastrelay/js-sdk';
+
+try {
+  await fastrelay.getActivity('missing');
+} catch (error) {
+  if (error instanceof FastrelayApiError) {
+    console.log(error.status, error.code, error.message, error.rateLimit);
+  }
+}
+```
+
+## Development
+
+```bash
+npm install
+npm run build   # tsc -> dist/
+npm test        # node --test (Node 23+ runs TS directly)
+```

package/dist/client.d.ts

@@ -0,0 +1,159 @@
+import { FastrelayFeed } from './feed.ts';
+import { FastrelayRealtime, type FastrelayRealtimeSocketFactory, type FastrelayTokenProvider } from './realtime.ts';
+import type { CursorPage, FastrelayActivity, FastrelayBookmark, FastrelayComment, FastrelayCommentReaction, FastrelayFeedActivityPin, FastrelayFeedback, FastrelayFile, FastrelayModerationFlag, FastrelayPoll, FastrelayReaction, FastrelayUser, FastrelayUserMute, FastrelayVideo, FastrelayVideoUploadUrl, FeedActivityQuery, NotificationPage } from './types.ts';
+import { type FeedTarget, type QueryMap } from './utils.ts';
+export type FastrelayAuthMode = 'auto' | 'user' | 'server' | 'none';
+export interface FastrelayRequestOptions {
+    auth?: FastrelayAuthMode;
+    idempotencyKey?: string;
+    headers?: Record<string, string>;
+}
+export interface FastrelayClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    token?: string;
+    user?: Record<string, unknown>;
+    fetch?: typeof fetch;
+    socketFactory?: FastrelayRealtimeSocketFactory;
+}
+export interface ConnectUserOptions {
+    upsertUser?: boolean;
+    realtime?: boolean;
+    tokenProvider?: FastrelayTokenProvider;
+}
+type ListQuery = {
+    limit?: number;
+    cursor?: string;
+};
+export declare class FastrelayClient {
+    apiKey: string;
+    baseUrl: string;
+    token?: string;
+    user?: Record<string, unknown>;
+    realtime?: FastrelayRealtime;
+    private readonly fetchImpl;
+    private readonly socketFactory?;
+    constructor(options: FastrelayClientOptions);
+    feed(group: string, id: string): FastrelayFeed;
+    connectUser(user: Record<string, unknown>, token: string, options?: ConnectUserOptions): Promise<this>;
+    disconnectUser(): this;
+    setToken(token: string): this;
+    setBaseUrl(baseUrl: string): this;
+    close(): void;
+    getCapabilities(query?: {
+        feed?: string;
+    }, options?: FastrelayRequestOptions): Promise<any>;
+    getUser(id: string, options?: FastrelayRequestOptions): Promise<FastrelayUser>;
+    updateUser(id: string, request: Record<string, unknown>, options?: FastrelayRequestOptions): Promise<FastrelayUser>;
+    getOrCreateFeed(group: string, id: string, request?: Record<string, unknown>, options?: FastrelayRequestOptions): Promise<any>;
+    getFeedActivities(group: string, id: string, query?: FeedActivityQuery, options?: FastrelayRequestOptions): Promise<CursorPage<FastrelayActivity>>;
+    getNotificationFeedActivities(group: string, id: string, query?: FeedActivityQuery, options?: FastrelayRequestOptions): Promise<NotificationPage<FastrelayActivity>>;
+    deleteFeed(group: string, id: string, options?: FastrelayRequestOptions): Promise<any>;
+    setFeedVisibility(group: string, id: string, level: string, options?: FastrelayRequestOptions): Promise<any>;
+    updateFeedSettings(group: string, id: string, request: Record<string, unknown>, options?: FastrelayRequestOptions): Promise<any>;
+    addFeedMember(group: string, id: string, request: {
+        userId: string;
+        role?: string;
+    }, options?: FastrelayRequestOptions): Promise<any>;
+    removeFeedMember(group: string, id: string, userId: string, options?: FastrelayRequestOptions): Promise<any>;
+    listFeedMembers(group: string, id: string, query?: ListQuery, options?: FastrelayRequestOptions): Promise<any>;
+    followFeed(group: string, id: string, request: {
+        target: FeedTarget;
+        activityCopyLimit?: number;
+    }, options?: FastrelayRequestOptions): Promise<any>;
+    batchFollowFeed(group: string, id: string, request: {
+        targets: FeedTarget[];
+        activityCopyLimit?: number;
+    }, options?: FastrelayRequestOptions): Promise<any>;
+    unfollowFeed(group: string, id: string, target: FeedTarget, { keepHistory }?: {
+        keepHistory?: boolean;
+    }, options?: FastrelayRequestOptions): Promise<any>;
+    listFollowers(group: string, id: string, query?: ListQuery, options?: FastrelayRequestOptions): Promise<any>;
+    listFollowing(group: string, id: string, query?: ListQuery, options?: FastrelayRequestOptions): Promise<any>;
+    listFollowRequests(group: string, id: string, query?: {
+        status?: string;
+    }, options?: FastrelayRequestOptions): Promise<any>;
+    approveFollowRequest(group: string, id: string, requestId: string, options?: FastrelayRequestOptions): Promise<any>;
+    rejectFollowRequest(group: string, id: string, requestId: string, options?: FastrelayRequestOptions): Promise<any>;
+    addActivity(request: Record<string, unknown>, options?: FastrelayRequestOptions): Promise<FastrelayActivity>;
+    getActivity(id: string, options?: FastrelayRequestOptions): Promise<FastrelayActivity>;
+    updateActivity(id: string, request: Record<string, unknown>, options?: FastrelayRequestOptions): Promise<FastrelayActivity>;
+    deleteActivity(id: string, options?: FastrelayRequestOptions): Promise<any>;
+    batchGetActivities(requestOrIds: string[] | Record<string, unknown>, options?: FastrelayRequestOptions): Promise<any>;
+    addReaction(activityId: string, type: string, options?: FastrelayRequestOptions): Promise<FastrelayReaction>;
+    removeReaction(activityId: string, reactionId: string, options?: FastrelayRequestOptions): Promise<void>;
+    listReactions(activityId: string, query?: {
+        type?: string;
+    } & ListQuery, options?: FastrelayRequestOptions): Promise<CursorPage<FastrelayReaction>>;
+    addComment(activityId: string, request: {
+        text: string;
+        parentId?: string;
+        mentionedUsers?: string[];
+    }, options?: FastrelayRequestOptions): Promise<FastrelayComment>;
+    updateComment(commentId: string, request: {
+        text: string;
+    }, options?: FastrelayRequestOptions): Promise<FastrelayComment>;
+    deleteComment(commentId: string, options?: FastrelayRequestOptions): Promise<void>;
+    listComments(activityId: string, query?: {
+        sort?: string;
+    } & ListQuery, options?: FastrelayRequestOptions): Promise<CursorPage<FastrelayComment>>;
+    listReplies(commentId: string, query?: ListQuery, options?: FastrelayRequestOptions): Promise<CursorPage<FastrelayComment>>;
+    addCommentReaction(commentId: string, type: string, options?: FastrelayRequestOptions): Promise<FastrelayCommentReaction>;
+    removeCommentReaction(commentId: string, reactionId: string, options?: FastrelayRequestOptions): Promise<void>;
+    addBookmark(activityId: string, options?: FastrelayRequestOptions): Promise<FastrelayBookmark>;
+    removeBookmark(activityId: string, options?: FastrelayRequestOptions): Promise<void>;
+    listBookmarks(query?: ListQuery, options?: FastrelayRequestOptions): Promise<CursorPage<FastrelayBookmark>>;
+    pinActivity(group: string, id: string, activityId: string, options?: FastrelayRequestOptions): Promise<FastrelayFeedActivityPin>;
+    unpinActivity(group: string, id: string, activityId: string, options?: FastrelayRequestOptions): Promise<void>;
+    createPoll(activityId: string, request: {
+        question: string;
+        options: Array<{
+            text: string;
+        } & Record<string, string>>;
+        maxVotesPerUser?: number;
+        anonymous?: boolean;
+        expiresAt?: string | Date;
+    }, options?: FastrelayRequestOptions): Promise<FastrelayPoll>;
+    getPollForActivity(activityId: string, options?: FastrelayRequestOptions): Promise<FastrelayPoll>;
+    getPoll(pollId: string, options?: FastrelayRequestOptions): Promise<FastrelayPoll>;
+    vote(pollId: string, optionId: string, options?: FastrelayRequestOptions): Promise<FastrelayPoll>;
+    removeVote(pollId: string, options?: FastrelayRequestOptions): Promise<void>;
+    uploadFile(data: Blob | ArrayBuffer | Uint8Array, filename: string, { type }?: {
+        type?: string;
+    }, options?: FastrelayRequestOptions): Promise<FastrelayFile>;
+    deleteFile(fileId: string, options?: FastrelayRequestOptions): Promise<void>;
+    createVideoUploadUrl(request: {
+        filename: string;
+        sizeBytes: number;
+        mimeType: string;
+    }, options?: FastrelayRequestOptions): Promise<FastrelayVideoUploadUrl>;
+    getVideo(videoId: string, options?: FastrelayRequestOptions): Promise<FastrelayVideo>;
+    deleteVideo(videoId: string, options?: FastrelayRequestOptions): Promise<void>;
+    submitFeedback(activityId: string, type: 'show_more' | 'show_less', options?: FastrelayRequestOptions): Promise<FastrelayFeedback>;
+    createFlag(targetType: string, targetId: string, request: {
+        reason: string;
+        description?: string;
+    }, options?: FastrelayRequestOptions): Promise<FastrelayModerationFlag>;
+    deleteFlag(flagId: string, options?: FastrelayRequestOptions): Promise<void>;
+    createMute(userId: string, { type, expiresAt }?: {
+        type?: string;
+        expiresAt?: string | Date;
+    }, options?: FastrelayRequestOptions): Promise<FastrelayUserMute>;
+    removeMute(userId: string, { type }?: {
+        type?: string;
+    }, options?: FastrelayRequestOptions): Promise<void>;
+    listMutes(query?: {
+        type?: string;
+    } & ListQuery, options?: FastrelayRequestOptions): Promise<CursorPage<FastrelayUserMute>>;
+    getMutedUsers(query?: {
+        type?: string;
+    } & ListQuery, options?: FastrelayRequestOptions): Promise<CursorPage<FastrelayUserMute>>;
+    request(method: string, path: string, { query, body, form, options, }?: {
+        query?: QueryMap;
+        body?: unknown;
+        form?: FormData;
+        options?: FastrelayRequestOptions;
+    }): Promise<any>;
+    private buildAuthorization;
+}
+export {};