@fastrelay/js-sdk 0.1.0

package/dist/client.js

@@ -0,0 +1,515 @@
+import { FastrelayApiError } from "./error.js";
+import { FastrelayFeed } from "./feed.js";
+import { FastrelayRealtime, } from "./realtime.js";
+import { buildFeedActivityQuery, parseJsonSafely, resolveFeedTarget, splitFeedId, toAbsoluteUrl, } from "./utils.js";
+const enc = encodeURIComponent;
+export class FastrelayClient {
+    apiKey;
+    baseUrl;
+    token;
+    user;
+    realtime;
+    fetchImpl;
+    socketFactory;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = options.baseUrl ?? 'http://localhost:8080';
+        this.token = options.token;
+        this.user = options.user ? { ...options.user } : undefined;
+        this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.socketFactory = options.socketFactory;
+    }
+    feed(group, id) {
+        return new FastrelayFeed(this, group, id);
+    }
+    async connectUser(user, token, options = {}) {
+        const userId = user.id;
+        if (userId === null || userId === undefined || String(userId) === '') {
+            throw new TypeError('connectUser requires a user object with an id.');
+        }
+        if (token.trim() === '') {
+            throw new TypeError('connectUser requires a JWT token string.');
+        }
+        // Drop the previous user's socket before any await so a failed upsert
+        // can never leave the old session receiving events under the new token.
+        if (this.realtime) {
+            this.realtime.dispose();
+            this.realtime = undefined;
+        }
+        const previousUser = this.user;
+        const previousToken = this.token;
+        this.user = { ...user };
+        this.token = token;
+        if (options.upsertUser) {
+            try {
+                await this.request('POST', '/v1/users', {
+                    body: {
+                        id: userId,
+                        displayName: user.displayName ?? user.name,
+                        profileData: user.profileData ?? user.data,
+                        ...(user.role !== null && user.role !== undefined
+                            ? { role: user.role }
+                            : {}),
+                    },
+                });
+            }
+            catch (error) {
+                this.user = previousUser;
+                this.token = previousToken;
+                throw error;
+            }
+        }
+        if (options.realtime) {
+            this.realtime = new FastrelayRealtime({
+                client: this,
+                token,
+                tokenProvider: options.tokenProvider,
+                socketFactory: this.socketFactory,
+            });
+            this.realtime.connect();
+        }
+        return this;
+    }
+    disconnectUser() {
+        this.realtime?.dispose();
+        this.realtime = undefined;
+        this.user = undefined;
+        this.token = undefined;
+        return this;
+    }
+    setToken(token) {
+        this.token = token;
+        this.realtime?.updateToken(token);
+        return this;
+    }
+    setBaseUrl(baseUrl) {
+        this.baseUrl = baseUrl;
+        this.realtime?.onBaseUrlChanged();
+        return this;
+    }
+    close() {
+        this.realtime?.dispose();
+        this.realtime = undefined;
+    }
+    // ---- capabilities & users ------------------------------------------------
+    getCapabilities(query = {}, options) {
+        return this.request('GET', '/v1/me/capabilities', {
+            query: { feed: query.feed },
+            options,
+        });
+    }
+    getUser(id, options) {
+        return this.request('GET', `/v1/users/${enc(id)}`, { options });
+    }
+    updateUser(id, request, options) {
+        return this.request('PATCH', `/v1/users/${enc(id)}`, {
+            body: request,
+            options,
+        });
+    }
+    // ---- feeds ---------------------------------------------------------------
+    getOrCreateFeed(group, id, request = {}, options) {
+        return this.request('POST', `/v1/feeds/${enc(group)}/${enc(id)}`, {
+            body: request,
+            options,
+        });
+    }
+    getFeedActivities(group, id, query, options) {
+        return this.request('GET', `/v1/feeds/${enc(group)}/${enc(id)}/activities`, {
+            query: buildFeedActivityQuery(query),
+            options,
+        });
+    }
+    getNotificationFeedActivities(group, id, query, options) {
+        return this.getFeedActivities(group, id, query, options);
+    }
+    deleteFeed(group, id, options) {
+        return this.request('DELETE', `/v1/feeds/${enc(group)}/${enc(id)}`, {
+            options,
+        });
+    }
+    setFeedVisibility(group, id, level, options) {
+        return this.request('PUT', `/v1/feeds/${enc(group)}/${enc(id)}/visibility`, {
+            body: { level },
+            options,
+        });
+    }
+    updateFeedSettings(group, id, request, options) {
+        return this.request('PUT', `/v1/feeds/${enc(group)}/${enc(id)}/settings`, {
+            body: request,
+            options,
+        });
+    }
+    addFeedMember(group, id, request, options) {
+        return this.request('POST', `/v1/feeds/${enc(group)}/${enc(id)}/members`, {
+            body: request,
+            options,
+        });
+    }
+    removeFeedMember(group, id, userId, options) {
+        return this.request('DELETE', `/v1/feeds/${enc(group)}/${enc(id)}/members/${enc(userId)}`, { options });
+    }
+    listFeedMembers(group, id, query, options) {
+        return this.request('GET', `/v1/feeds/${enc(group)}/${enc(id)}/members`, {
+            query: { limit: query?.limit, cursor: query?.cursor },
+            options,
+        });
+    }
+    followFeed(group, id, request, options) {
+        return this.request('POST', `/v1/feeds/${enc(group)}/${enc(id)}/follows`, {
+            body: { ...request, target: resolveFeedTarget(request.target) },
+            options,
+        });
+    }
+    batchFollowFeed(group, id, request, options) {
+        return this.request('POST', `/v1/feeds/${enc(group)}/${enc(id)}/follows/batch`, {
+            body: {
+                ...(request.activityCopyLimit !== undefined
+                    ? { activityCopyLimit: request.activityCopyLimit }
+                    : {}),
+                targets: (request.targets ?? []).map(resolveFeedTarget),
+            },
+            options,
+        });
+    }
+    unfollowFeed(group, id, target, { keepHistory } = {}, options) {
+        const [targetGroup, targetId] = splitFeedId(resolveFeedTarget(target));
+        return this.request('DELETE', `/v1/feeds/${enc(group)}/${enc(id)}/follows/${enc(targetGroup)}:${enc(targetId)}`, { query: { keepHistory }, options });
+    }
+    listFollowers(group, id, query, options) {
+        return this.request('GET', `/v1/feeds/${enc(group)}/${enc(id)}/followers`, {
+            query: { limit: query?.limit, cursor: query?.cursor },
+            options,
+        });
+    }
+    listFollowing(group, id, query, options) {
+        return this.request('GET', `/v1/feeds/${enc(group)}/${enc(id)}/following`, {
+            query: { limit: query?.limit, cursor: query?.cursor },
+            options,
+        });
+    }
+    listFollowRequests(group, id, query, options) {
+        return this.request('GET', `/v1/feeds/${enc(group)}/${enc(id)}/follow-requests`, { query: { status: query?.status }, options });
+    }
+    approveFollowRequest(group, id, requestId, options) {
+        return this.request('POST', `/v1/feeds/${enc(group)}/${enc(id)}/follow-requests/${enc(requestId)}/approve`, { options });
+    }
+    rejectFollowRequest(group, id, requestId, options) {
+        return this.request('POST', `/v1/feeds/${enc(group)}/${enc(id)}/follow-requests/${enc(requestId)}/reject`, { options });
+    }
+    // ---- activities ------------------------------------------------------
+    addActivity(request, options) {
+        return this.request('POST', '/v1/activities', { body: request, options });
+    }
+    getActivity(id, options) {
+        return this.request('GET', `/v1/activities/${enc(id)}`, { options });
+    }
+    updateActivity(id, request, options) {
+        return this.request('PATCH', `/v1/activities/${enc(id)}`, {
+            body: request,
+            options,
+        });
+    }
+    deleteActivity(id, options) {
+        return this.request('DELETE', `/v1/activities/${enc(id)}`, { options });
+    }
+    batchGetActivities(requestOrIds, options) {
+        const body = Array.isArray(requestOrIds)
+            ? { ids: requestOrIds }
+            : requestOrIds;
+        return this.request('POST', '/v1/activities/batch', { body, options });
+    }
+    // ---- reactions -------------------------------------------------------
+    addReaction(activityId, type, options) {
+        return this.request('POST', `/v1/activities/${enc(activityId)}/reactions`, {
+            body: { type },
+            options,
+        });
+    }
+    removeReaction(activityId, reactionId, options) {
+        return this.request('DELETE', `/v1/activities/${enc(activityId)}/reactions/${enc(reactionId)}`, { options });
+    }
+    listReactions(activityId, query, options) {
+        return this.request('GET', `/v1/activities/${enc(activityId)}/reactions`, {
+            query: { type: query?.type, limit: query?.limit, cursor: query?.cursor },
+            options,
+        });
+    }
+    // ---- comments --------------------------------------------------------
+    addComment(activityId, request, options) {
+        return this.request('POST', `/v1/activities/${enc(activityId)}/comments`, {
+            body: {
+                text: request.text,
+                ...(request.parentId !== undefined ? { parentId: request.parentId } : {}),
+                ...(request.mentionedUsers !== undefined
+                    ? { mentionedUsers: request.mentionedUsers }
+                    : {}),
+            },
+            options,
+        });
+    }
+    updateComment(commentId, request, options) {
+        return this.request('PATCH', `/v1/comments/${enc(commentId)}`, {
+            body: { text: request.text },
+            options,
+        });
+    }
+    deleteComment(commentId, options) {
+        return this.request('DELETE', `/v1/comments/${enc(commentId)}`, { options });
+    }
+    listComments(activityId, query, options) {
+        return this.request('GET', `/v1/activities/${enc(activityId)}/comments`, {
+            query: { sort: query?.sort, limit: query?.limit, cursor: query?.cursor },
+            options,
+        });
+    }
+    listReplies(commentId, query, options) {
+        return this.request('GET', `/v1/comments/${enc(commentId)}/replies`, {
+            query: { limit: query?.limit, cursor: query?.cursor },
+            options,
+        });
+    }
+    addCommentReaction(commentId, type, options) {
+        return this.request('POST', `/v1/comments/${enc(commentId)}/reactions`, {
+            body: { type },
+            options,
+        });
+    }
+    removeCommentReaction(commentId, reactionId, options) {
+        return this.request('DELETE', `/v1/comments/${enc(commentId)}/reactions/${enc(reactionId)}`, { options });
+    }
+    // ---- bookmarks & pins --------------------------------------------------
+    addBookmark(activityId, options) {
+        return this.request('POST', `/v1/activities/${enc(activityId)}/bookmarks`, {
+            options,
+        });
+    }
+    removeBookmark(activityId, options) {
+        return this.request('DELETE', `/v1/activities/${enc(activityId)}/bookmarks`, { options });
+    }
+    listBookmarks(query, options) {
+        return this.request('GET', '/v1/me/bookmarks', {
+            query: { limit: query?.limit, cursor: query?.cursor },
+            options,
+        });
+    }
+    pinActivity(group, id, activityId, options) {
+        return this.request('POST', `/v1/feeds/${enc(group)}/${enc(id)}/activities/${enc(activityId)}/pin`, { options });
+    }
+    unpinActivity(group, id, activityId, options) {
+        return this.request('DELETE', `/v1/feeds/${enc(group)}/${enc(id)}/activities/${enc(activityId)}/pin`, { options });
+    }
+    // ---- polls -------------------------------------------------------------
+    createPoll(activityId, request, options) {
+        return this.request('POST', `/v1/activities/${enc(activityId)}/polls`, {
+            body: {
+                question: request.question,
+                options: request.options,
+                maxVotesPerUser: request.maxVotesPerUser ?? 1,
+                anonymous: request.anonymous ?? false,
+                ...(request.expiresAt !== undefined
+                    ? {
+                        expiresAt: request.expiresAt instanceof Date
+                            ? request.expiresAt.toISOString()
+                            : request.expiresAt,
+                    }
+                    : {}),
+            },
+            options,
+        });
+    }
+    getPollForActivity(activityId, options) {
+        return this.request('GET', `/v1/activities/${enc(activityId)}/polls`, {
+            options,
+        });
+    }
+    getPoll(pollId, options) {
+        return this.request('GET', `/v1/polls/${enc(pollId)}`, { options });
+    }
+    vote(pollId, optionId, options) {
+        return this.request('POST', `/v1/polls/${enc(pollId)}/votes`, {
+            body: { optionId },
+            options,
+        });
+    }
+    removeVote(pollId, options) {
+        return this.request('DELETE', `/v1/polls/${enc(pollId)}/votes`, { options });
+    }
+    // ---- files & videos ------------------------------------------------------
+    async uploadFile(data, filename, { type } = {}, options) {
+        const blob = data instanceof Blob ? data : new Blob([data]);
+        if (blob.size === 0) {
+            throw new TypeError('uploadFile requires non-empty data.');
+        }
+        if (filename.trim() === '') {
+            throw new TypeError('uploadFile requires a non-empty filename.');
+        }
+        const form = new FormData();
+        form.append('file', blob, filename);
+        if (type && type.trim() !== '') {
+            form.append('type', type.trim());
+        }
+        return this.request('POST', '/v1/files', { form, options });
+    }
+    deleteFile(fileId, options) {
+        return this.request('DELETE', `/v1/files/${enc(fileId)}`, { options });
+    }
+    createVideoUploadUrl(request, options) {
+        return this.request('POST', '/v1/videos/upload-url', {
+            body: request,
+            options,
+        });
+    }
+    getVideo(videoId, options) {
+        return this.request('GET', `/v1/videos/${enc(videoId)}`, { options });
+    }
+    deleteVideo(videoId, options) {
+        return this.request('DELETE', `/v1/videos/${enc(videoId)}`, { options });
+    }
+    // ---- feedback & moderation -------------------------------------------
+    submitFeedback(activityId, type, options) {
+        if (type !== 'show_more' && type !== 'show_less') {
+            throw new TypeError("Feedback type must be 'show_more' or 'show_less'.");
+        }
+        return this.request('POST', `/v1/activities/${enc(activityId)}/feedback`, {
+            body: { type },
+            options,
+        });
+    }
+    createFlag(targetType, targetId, request, options) {
+        return this.request('POST', '/v1/moderation/flags', {
+            body: {
+                targetType,
+                targetId,
+                reason: request.reason,
+                ...(request.description !== undefined
+                    ? { description: request.description }
+                    : {}),
+            },
+            options,
+        });
+    }
+    deleteFlag(flagId, options) {
+        return this.request('DELETE', `/v1/moderation/flags/${enc(flagId)}`, {
+            options,
+        });
+    }
+    createMute(userId, { type = 'personal', expiresAt } = {}, options) {
+        return this.request('POST', '/v1/moderation/mutes', {
+            body: {
+                userId,
+                type,
+                ...(expiresAt !== undefined
+                    ? {
+                        expiresAt: expiresAt instanceof Date ? expiresAt.toISOString() : expiresAt,
+                    }
+                    : {}),
+            },
+            options,
+        });
+    }
+    removeMute(userId, { type = 'personal' } = {}, options) {
+        return this.request('DELETE', `/v1/moderation/mutes/${enc(userId)}`, {
+            query: { type },
+            options,
+        });
+    }
+    listMutes(query = {}, options) {
+        return this.request('GET', '/v1/moderation/mutes', {
+            query: {
+                type: query.type ?? 'personal',
+                limit: query.limit,
+                cursor: query.cursor,
+            },
+            options,
+        });
+    }
+    getMutedUsers(query = {}, options) {
+        return this.listMutes(query, options);
+    }
+    // ---- transport -----------------------------------------------------------
+    async request(method, path, { query, body, form, options = {}, } = {}) {
+        const authorization = this.buildAuthorization(options.auth ?? 'auto');
+        const url = toAbsoluteUrl(this.baseUrl, path, query);
+        const headers = { accept: 'application/json' };
+        if (authorization)
+            headers.authorization = authorization;
+        if (options.idempotencyKey) {
+            headers['idempotency-key'] = options.idempotencyKey;
+        }
+        Object.assign(headers, options.headers);
+        let requestBody;
+        if (form) {
+            requestBody = form; // fetch sets the multipart content-type + boundary
+        }
+        else if (body !== undefined) {
+            headers['content-type'] = 'application/json';
+            requestBody = JSON.stringify(body);
+        }
+        const response = await this.fetchImpl(url, {
+            method,
+            headers,
+            body: requestBody,
+        });
+        const text = await response.text();
+        const parsed = parseJsonSafely(text);
+        if (response.status < 200 || response.status >= 300) {
+            const parsedMap = parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+                ? parsed
+                : undefined;
+            const errorPayload = parsedMap?.error;
+            const errorMap = errorPayload && typeof errorPayload === 'object'
+                ? errorPayload
+                : undefined;
+            throw new FastrelayApiError({
+                message: String(errorMap?.message ??
+                    parsedMap?.message ??
+                    `fastrelay API request failed (${response.status} ${response.statusText}).`.trim()),
+                status: response.status,
+                code: errorMap?.code !== undefined ? String(errorMap.code) : undefined,
+                details: errorMap?.details,
+                hint: errorMap?.hint !== undefined ? String(errorMap.hint) : undefined,
+                docUrl: errorMap?.docUrl !== undefined ? String(errorMap.docUrl) : undefined,
+                requestId: parsedMap?.requestId !== undefined
+                    ? String(parsedMap.requestId)
+                    : undefined,
+                path,
+                method,
+                rateLimit: readRateLimit(response.headers),
+            });
+        }
+        if (parsed === null || parsed === '')
+            return null;
+        return parsed;
+    }
+    buildAuthorization(auth) {
+        switch (auth) {
+            case 'none':
+                return undefined;
+            case 'server':
+                throw new Error('Server auth is not supported: this SDK is client-only. ' +
+                    'Call server endpoints from your backend.');
+            case 'user':
+                if (!this.token) {
+                    throw new Error('This request requires a user token. Call connectUser() or setToken().');
+                }
+                return `Bearer ${this.token}`;
+            case 'auto':
+                return this.token ? `Bearer ${this.token}` : undefined;
+        }
+    }
+}
+function readRateLimit(headers) {
+    const limit = headers.get('x-ratelimit-limit');
+    const remaining = headers.get('x-ratelimit-remaining');
+    const reset = headers.get('x-ratelimit-reset');
+    if (limit === null && remaining === null && reset === null)
+        return undefined;
+    const parse = (value) => {
+        if (value === null)
+            return undefined;
+        const parsed = Number.parseInt(value, 10);
+        return Number.isNaN(parsed) ? undefined : parsed;
+    };
+    return { limit: parse(limit), remaining: parse(remaining), reset: parse(reset) };
+}

package/dist/error.d.ts

@@ -0,0 +1,28 @@
+export interface FastrelayRateLimit {
+    limit?: number;
+    remaining?: number;
+    reset?: number;
+}
+export declare class FastrelayApiError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly details?: unknown;
+    readonly hint?: string;
+    readonly docUrl?: string;
+    readonly requestId?: string;
+    readonly path?: string;
+    readonly method?: string;
+    readonly rateLimit?: FastrelayRateLimit;
+    constructor(args: {
+        message: string;
+        status: number;
+        code?: string;
+        details?: unknown;
+        hint?: string;
+        docUrl?: string;
+        requestId?: string;
+        path?: string;
+        method?: string;
+        rateLimit?: FastrelayRateLimit;
+    });
+}

package/dist/error.js

@@ -0,0 +1,24 @@
+export class FastrelayApiError extends Error {
+    status;
+    code;
+    details;
+    hint;
+    docUrl;
+    requestId;
+    path;
+    method;
+    rateLimit;
+    constructor(args) {
+        super(args.message);
+        this.name = 'FastrelayApiError';
+        this.status = args.status;
+        this.code = args.code;
+        this.details = args.details;
+        this.hint = args.hint;
+        this.docUrl = args.docUrl;
+        this.requestId = args.requestId;
+        this.path = args.path;
+        this.method = args.method;
+        this.rateLimit = args.rateLimit;
+    }
+}

package/dist/feed.d.ts

@@ -0,0 +1,63 @@
+import type { FastrelayClient, FastrelayRequestOptions } from './client.ts';
+import type { CursorPage, FastrelayActivity, FastrelayBookmark, FastrelayComment, FastrelayFeedActivityPin, FastrelayReaction, FastrelayRealtimeEvent, FeedActivityQuery, NotificationPage } from './types.ts';
+import type { FeedTarget } from './utils.ts';
+export declare class FastrelayFeed {
+    readonly group: string;
+    readonly feedId: string;
+    private readonly client;
+    constructor(client: FastrelayClient, group: string, id: string);
+    get id(): string;
+    /** Subscribe to realtime events for this feed. Returns an unsubscribe fn. */
+    on(type: string, callback: (event: FastrelayRealtimeEvent) => void): () => void;
+    /** Subscribe to all realtime events for this feed. */
+    onAny(callback: (event: FastrelayRealtimeEvent) => void): () => void;
+    getOrCreate(request?: Record<string, unknown>, options?: FastrelayRequestOptions): Promise<any>;
+    getActivities(query?: FeedActivityQuery, options?: FastrelayRequestOptions): Promise<CursorPage<FastrelayActivity>>;
+    getNotificationActivities(query?: FeedActivityQuery, options?: FastrelayRequestOptions): Promise<NotificationPage<FastrelayActivity>>;
+    getCapabilities(query?: Record<string, unknown>, options?: FastrelayRequestOptions): Promise<any>;
+    addActivity(activity: Record<string, unknown>, options?: FastrelayRequestOptions): Promise<FastrelayActivity>;
+    delete(options?: FastrelayRequestOptions): Promise<any>;
+    setVisibility(level: string, options?: FastrelayRequestOptions): Promise<any>;
+    updateSettings(settings: Record<string, unknown>, options?: FastrelayRequestOptions): Promise<any>;
+    addMember(userId: string, { role }?: {
+        role?: string;
+    }, options?: FastrelayRequestOptions): Promise<any>;
+    removeMember(userId: string, options?: FastrelayRequestOptions): Promise<any>;
+    listMembers(query?: {
+        limit?: number;
+        cursor?: string;
+    }, options?: FastrelayRequestOptions): Promise<any>;
+    follow(target: FeedTarget, { activityCopyLimit }?: {
+        activityCopyLimit?: number;
+    }, options?: FastrelayRequestOptions): Promise<any>;
+    batchFollow(targets: FeedTarget[], { activityCopyLimit }?: {
+        activityCopyLimit?: number;
+    }, options?: FastrelayRequestOptions): Promise<any>;
+    unfollow(target: FeedTarget, { keepHistory }?: {
+        keepHistory?: boolean;
+    }, options?: FastrelayRequestOptions): Promise<any>;
+    listFollowers(query?: {
+        limit?: number;
+        cursor?: string;
+    }, options?: FastrelayRequestOptions): Promise<any>;
+    listFollowing(query?: {
+        limit?: number;
+        cursor?: string;
+    }, options?: FastrelayRequestOptions): Promise<any>;
+    listFollowRequests(query?: {
+        status?: string;
+    }, options?: FastrelayRequestOptions): Promise<any>;
+    approveFollowRequest(requestId: string, options?: FastrelayRequestOptions): Promise<any>;
+    rejectFollowRequest(requestId: string, options?: FastrelayRequestOptions): Promise<any>;
+    addReaction(activityId: string, type: string, options?: FastrelayRequestOptions): Promise<FastrelayReaction>;
+    removeReaction(activityId: string, reactionId: string, options?: FastrelayRequestOptions): Promise<void>;
+    addComment(activityId: string, request: {
+        text: string;
+        parentId?: string;
+        mentionedUsers?: string[];
+    }, options?: FastrelayRequestOptions): Promise<FastrelayComment>;
+    addBookmark(activityId: string, options?: FastrelayRequestOptions): Promise<FastrelayBookmark>;
+    removeBookmark(activityId: string, options?: FastrelayRequestOptions): Promise<void>;
+    pinActivity(activityId: string, options?: FastrelayRequestOptions): Promise<FastrelayFeedActivityPin>;
+    unpinActivity(activityId: string, options?: FastrelayRequestOptions): Promise<void>;
+}