@foru-ms/sdk 1.1.1 → 1.2.0

package/src/Client.ts

@@ -12,14 +12,58 @@ import { PrivateMessagesResource } from './resources/PrivateMessages';
 import { ReportsResource } from './resources/Reports';
 import { RolesResource } from './resources/Roles';
 import { SSOResource } from './resources/SSO';
+import {
+    ForumAPIError,
+    AuthenticationError,
+    AuthorizationError,
+    NotFoundError,
+    ValidationError,
+    RateLimitError,
+    ServerError,
+    NetworkError
+} from './errors';
+import { PaginationHelper, RetryHelper } from './utils';
+import { RateLimitInfo } from './response-types';
 
 // Polyfill fetch if needed (e.g. older Node versions)
 const fetch = globalThis.fetch || require('cross-fetch');
 
+export interface ClientOptions {
+    /** API key for authentication */
+    apiKey: string;
+    /** Base URL for the API (default: https://api.foru.ms/v1) */
+    baseUrl?: string;
+    /** Maximum number of retry attempts for failed requests (default: 3) */
+    maxRetries?: number;
+    /** Enable automatic retry for rate limits and server errors (default: true) */
+    enableRetry?: boolean;
+}
+
+/**
+ * Main client for interacting with the Foru.ms API
+ * @example
+ * ```typescript
+ * const client = new ForumClient({
+ *   apiKey: 'your_api_key',
+ *   baseUrl: 'https://api.foru.ms/v1'
+ * });
+ * 
+ * // Set user token
+ * client.setToken('user_jwt_token');
+ * 
+ * // Use resources
+ * const threads = await client.threads.list();
+ * ```
+ */
 export class ForumClient {
     public apiKey: string;
     public token: string | null = null;
     public baseUrl: string;
+    public maxRetries: number;
+    public enableRetry: boolean;
+
+    /** Last known rate limit info */
+    public lastRateLimitInfo?: RateLimitInfo;
 
     public auth: AuthResource;
     public threads: ThreadsResource;
@@ -36,9 +80,14 @@ export class ForumClient {
     public roles: RolesResource;
     public sso: SSOResource;
 
-    constructor(options: { apiKey: string; baseUrl?: string }) {
+    /** Pagination helper for auto-paginating through results */
+    public pagination: PaginationHelper;
+
+    constructor(options: ClientOptions) {
         this.apiKey = options.apiKey;
         this.baseUrl = options.baseUrl || 'https://api.foru.ms/v1';
+        this.maxRetries = options.maxRetries ?? 3;
+        this.enableRetry = options.enableRetry ?? true;
 
         this.auth = new AuthResource(this);
         this.threads = new ThreadsResource(this);
@@ -54,40 +103,131 @@ export class ForumClient {
         this.reports = new ReportsResource(this);
         this.roles = new RolesResource(this);
         this.sso = new SSOResource(this);
+
+        this.pagination = new PaginationHelper();
     }
 
+    /**
+     * Make an HTTP request to the API
+     * @param path - API endpoint path
+     * @param options - Fetch options
+     * @returns Promise resolving to the response data
+     * @throws {ForumAPIError} When the API returns an error
+     * @throws {NetworkError} When the network request fails
+     */
     public async request<T>(path: string, options: RequestInit = {}): Promise<T> {
-        const headers: Record<string, string> = {
-            'Content-Type': 'application/json',
-            'x-api-key': this.apiKey,
-            ...(options.headers as Record<string, string>),
-        };
+        const makeRequest = async (): Promise<T> => {
+            const headers: Record<string, string> = {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey,
+                ...(options.headers as Record<string, string>),
+            };
 
-        if (this.token) {
-            headers['Authorization'] = `Bearer ${this.token}`;
-        }
+            if (this.token) {
+                headers['Authorization'] = `Bearer ${this.token}`;
+            }
 
-        const response = await fetch(`${this.baseUrl}${path}`, {
-            ...options,
-            headers,
-        });
-
-        const contentType = response.headers.get('content-type');
-        let data;
-        if (contentType && contentType.includes('application/json')) {
-            data = await response.json();
-        } else {
-            data = await response.text();
-        }
+            let response: Response;
+
+            try {
+                response = await fetch(`${this.baseUrl}${path}`, {
+                    ...options,
+                    headers,
+                });
+            } catch (error: any) {
+                throw new NetworkError('Network request failed', error);
+            }
+
+            // Extract rate limit info
+            this.extractRateLimitInfo(response);
+
+            const contentType = response.headers.get('content-type');
+            let data;
+            if (contentType && contentType.includes('application/json')) {
+                data = await response.json();
+            } else {
+                data = await response.text();
+            }
+
+            if (!response.ok) {
+                this.handleErrorResponse(response.status, data);
+            }
+
+            return data as T;
+        };
 
-        if (!response.ok) {
-            throw new Error((data && (data as any).message) || (data as any).error || 'API Error');
+        // Apply retry logic if enabled
+        if (this.enableRetry) {
+            return RetryHelper.withRetry(makeRequest, this.maxRetries);
         }
 
-        return data as T;
+        return makeRequest();
     }
 
-    public setToken(token: string) {
+    /**
+     * Set the authentication token for user-scoped requests
+     * @param token - JWT token
+     */
+    public setToken(token: string): void {
         this.token = token;
     }
+
+    /**
+     * Clear the authentication token
+     */
+    public clearToken(): void {
+        this.token = null;
+    }
+
+    /**
+     * Check if client is authenticated
+     */
+    public isAuthenticated(): boolean {
+        return this.token !== null;
+    }
+
+    /**
+     * Extract and store rate limit information from response headers
+     */
+    private extractRateLimitInfo(response: Response): void {
+        const limit = response.headers.get('x-ratelimit-limit');
+        const remaining = response.headers.get('x-ratelimit-remaining');
+        const reset = response.headers.get('x-ratelimit-reset');
+
+        if (limit && remaining && reset) {
+            this.lastRateLimitInfo = {
+                limit: parseInt(limit, 10),
+                remaining: parseInt(remaining, 10),
+                reset: parseInt(reset, 10),
+            };
+        }
+    }
+
+    /**
+     * Handle error responses by throwing appropriate error types
+     */
+    private handleErrorResponse(status: number, data: any): never {
+        const message = (data && data.message) || data.error || 'API Error';
+
+        switch (status) {
+            case 401:
+                throw new AuthenticationError(message, data);
+            case 403:
+                throw new AuthorizationError(message, data);
+            case 404:
+                throw new NotFoundError(message, data);
+            case 422:
+                throw new ValidationError(message, data);
+            case 429:
+                const retryAfter = data.retryAfter || 60;
+                throw new RateLimitError(message, retryAfter, data);
+            case 500:
+            case 502:
+            case 503:
+            case 504:
+                throw new ServerError(message, status, data);
+            default:
+                throw new ForumAPIError(message, status, data);
+        }
+    }
 }

package/src/errors.ts

@@ -0,0 +1,95 @@
+/**
+ * Base error class for all Foru.ms API errors
+ */
+export class ForumAPIError extends Error {
+    constructor(
+        message: string,
+        public statusCode: number,
+        public response?: any
+    ) {
+        super(message);
+        this.name = 'ForumAPIError';
+        Object.setPrototypeOf(this, ForumAPIError.prototype);
+    }
+}
+
+/**
+ * Error thrown when authentication fails or token is invalid
+ */
+export class AuthenticationError extends ForumAPIError {
+    constructor(message: string = 'Authentication failed', response?: any) {
+        super(message, 401, response);
+        this.name = 'AuthenticationError';
+        Object.setPrototypeOf(this, AuthenticationError.prototype);
+    }
+}
+
+/**
+ * Error thrown when user doesn't have permission for an action
+ */
+export class AuthorizationError extends ForumAPIError {
+    constructor(message: string = 'Permission denied', response?: any) {
+        super(message, 403, response);
+        this.name = 'AuthorizationError';
+        Object.setPrototypeOf(this, AuthorizationError.prototype);
+    }
+}
+
+/**
+ * Error thrown when a requested resource is not found
+ */
+export class NotFoundError extends ForumAPIError {
+    constructor(message: string = 'Resource not found', response?: any) {
+        super(message, 404, response);
+        this.name = 'NotFoundError';
+        Object.setPrototypeOf(this, NotFoundError.prototype);
+    }
+}
+
+/**
+ * Error thrown when request validation fails
+ */
+export class ValidationError extends ForumAPIError {
+    constructor(message: string = 'Validation failed', response?: any) {
+        super(message, 422, response);
+        this.name = 'ValidationError';
+        Object.setPrototypeOf(this, ValidationError.prototype);
+    }
+}
+
+/**
+ * Error thrown when rate limit is exceeded
+ */
+export class RateLimitError extends ForumAPIError {
+    constructor(
+        message: string = 'Rate limit exceeded',
+        public retryAfter?: number,
+        response?: any
+    ) {
+        super(message, 429, response);
+        this.name = 'RateLimitError';
+        Object.setPrototypeOf(this, RateLimitError.prototype);
+    }
+}
+
+/**
+ * Error thrown when server encounters an error
+ */
+export class ServerError extends ForumAPIError {
+    constructor(message: string = 'Server error', statusCode: number = 500, response?: any) {
+        super(message, statusCode, response);
+        this.name = 'ServerError';
+        Object.setPrototypeOf(this, ServerError.prototype);
+    }
+}
+
+/**
+ * Error thrown when network request fails
+ */
+export class NetworkError extends Error {
+    constructor(message: string = 'Network request failed', public cause?: Error) {
+        super(message);
+        this.name = 'NetworkError';
+        Object.setPrototypeOf(this, NetworkError.prototype);
+    }
+}

package/src/index.ts

@@ -1,5 +1,8 @@
 export * from './Client';
 export * from './types';
+export * from './errors';
+export * from './response-types';
+export * from './utils';
 export * from './resources/Auth';
 export * from './resources/Threads';
 export * from './resources/Posts';

package/src/resources/Integrations.ts

@@ -31,6 +31,17 @@ export class IntegrationsResource {
         });
     }
 
+    async update(id: string, payload: {
+        name?: string;
+        config?: any;
+        active?: boolean;
+    }): Promise<{ integration: Integration }> {
+        return this.client.request<{ integration: Integration }>(`/integrations/${id}`, {
+            method: 'PATCH',
+            body: JSON.stringify(payload),
+        });
+    }
+
     async delete(id: string): Promise<{ success: boolean }> {
         return this.client.request<{ success: boolean }>(`/integrations/${id}`, {
             method: 'DELETE',

package/src/resources/Posts.ts

@@ -84,6 +84,20 @@ export class PostsResource {
         });
     }
 
+    async getLikes(id: string, params?: {
+        cursor?: string;
+    }): Promise<any> {
+        const searchParams = new URLSearchParams();
+        if (params) {
+            Object.entries(params).forEach(([key, value]) => {
+                if (value !== undefined) {
+                    searchParams.append(key, value as string);
+                }
+            });
+        }
+        return this.client.request(`/post/${id}/likes?${searchParams.toString()}`, { method: 'GET' });
+    }
+
     async dislike(id: string, userId?: string, extendedData?: any): Promise<any> {
         return this.client.request(`/post/${id}/dislikes`, {
             method: 'POST',
@@ -97,6 +111,20 @@ export class PostsResource {
         });
     }
 
+    async getDislikes(id: string, params?: {
+        cursor?: string;
+    }): Promise<any> {
+        const searchParams = new URLSearchParams();
+        if (params) {
+            Object.entries(params).forEach(([key, value]) => {
+                if (value !== undefined) {
+                    searchParams.append(key, value as string);
+                }
+            });
+        }
+        return this.client.request(`/post/${id}/dislikes?${searchParams.toString()}`, { method: 'GET' });
+    }
+
     async upvote(id: string, userId?: string, extendedData?: any): Promise<any> {
         return this.client.request(`/post/${id}/upvotes`, {
             method: 'POST',
@@ -110,6 +138,20 @@ export class PostsResource {
         });
     }
 
+    async getUpvotes(id: string, params?: {
+        cursor?: string;
+    }): Promise<any> {
+        const searchParams = new URLSearchParams();
+        if (params) {
+            Object.entries(params).forEach(([key, value]) => {
+                if (value !== undefined) {
+                    searchParams.append(key, value as string);
+                }
+            });
+        }
+        return this.client.request(`/post/${id}/upvotes?${searchParams.toString()}`, { method: 'GET' });
+    }
+
     async downvote(id: string, userId?: string, extendedData?: any): Promise<any> {
         return this.client.request(`/post/${id}/downvotes`, {
             method: 'POST',
@@ -122,4 +164,18 @@ export class PostsResource {
             method: 'DELETE',
         });
     }
+
+    async getDownvotes(id: string, params?: {
+        cursor?: string;
+    }): Promise<any> {
+        const searchParams = new URLSearchParams();
+        if (params) {
+            Object.entries(params).forEach(([key, value]) => {
+                if (value !== undefined) {
+                    searchParams.append(key, value as string);
+                }
+            });
+        }
+        return this.client.request(`/post/${id}/downvotes?${searchParams.toString()}`, { method: 'GET' });
+    }
 }

package/src/resources/PrivateMessages.ts

@@ -59,6 +59,16 @@ export class PrivateMessagesResource {
         });
     }
 
+    async update(id: string, payload: {
+        read?: boolean;
+        extendedData?: Record<string, any>;
+    }): Promise<PrivateMessage> {
+        return this.client.request<PrivateMessage>(`/private-message/${id}`, {
+            method: 'PATCH',
+            body: JSON.stringify(payload),
+        });
+    }
+
     async delete(id: string): Promise<PrivateMessage & { deleted: boolean }> {
         return this.client.request<PrivateMessage & { deleted: boolean }>(`/private-message/${id}`, {
             method: 'DELETE',

package/src/resources/SSO.ts

@@ -25,6 +25,23 @@ export class SSOResource {
         });
     }
 
+    async retrieve(id: string): Promise<{ ssoProvider: SSOProvider }> {
+        return this.client.request<{ ssoProvider: SSOProvider }>(`/sso/${id}`, {
+            method: 'GET',
+        });
+    }
+
+    async update(id: string, payload: {
+        domain?: string;
+        config?: any;
+        active?: boolean;
+    }): Promise<{ ssoProvider: SSOProvider }> {
+        return this.client.request<{ ssoProvider: SSOProvider }>(`/sso/${id}`, {
+            method: 'PATCH',
+            body: JSON.stringify(payload),
+        });
+    }
+
     async delete(id: string): Promise<{ success: boolean }> {
         return this.client.request<{ success: boolean }>(`/sso/${id}`, {
             method: 'DELETE',

package/src/resources/Tags.ts

@@ -64,6 +64,24 @@ export class TagsResource {
         });
     }
 
+    async getThreads(id: string, params?: {
+        query?: string;
+        cursor?: string;
+        filter?: 'newest' | 'oldest';
+    }): Promise<import('../types').ThreadListResponse> {
+        const searchParams = new URLSearchParams();
+        if (params) {
+            Object.entries(params).forEach(([key, value]) => {
+                if (value !== undefined) {
+                    searchParams.append(key, value as string);
+                }
+            });
+        }
+        return this.client.request<import('../types').ThreadListResponse>(`/tag/${id}/threads?${searchParams.toString()}`, {
+            method: 'GET',
+        });
+    }
+
     async subscribe(id: string, userId: string): Promise<any> {
         return this.client.request(`/tag/${id}/subscribers`, {
             method: 'POST',
@@ -77,6 +95,20 @@ export class TagsResource {
         });
     }
 
+    async getSubscribers(id: string, params?: {
+        cursor?: string;
+    }): Promise<any> {
+        const searchParams = new URLSearchParams();
+        if (params) {
+            Object.entries(params).forEach(([key, value]) => {
+                if (value !== undefined) {
+                    searchParams.append(key, value as string);
+                }
+            });
+        }
+        return this.client.request(`/tag/${id}/subscribers?${searchParams.toString()}`, { method: 'GET' });
+    }
+
     async listSubscribed(params: {
         userId: string;
         query?: string;

package/src/resources/Threads.ts

@@ -85,6 +85,20 @@ export class ThreadsResource {
         });
     }
 
+    async getLikes(id: string, params?: {
+        cursor?: string;
+    }): Promise<any> {
+        const searchParams = new URLSearchParams();
+        if (params) {
+            Object.entries(params).forEach(([key, value]) => {
+                if (value !== undefined) {
+                    searchParams.append(key, value as string);
+                }
+            });
+        }
+        return this.client.request(`/thread/${id}/likes?${searchParams.toString()}`, { method: 'GET' });
+    }
+
     async dislike(id: string, userId?: string, extendedData?: any): Promise<any> {
         return this.client.request(`/thread/${id}/dislikes`, {
             method: 'POST',
@@ -98,6 +112,20 @@ export class ThreadsResource {
         });
     }
 
+    async getDislikes(id: string, params?: {
+        cursor?: string;
+    }): Promise<any> {
+        const searchParams = new URLSearchParams();
+        if (params) {
+            Object.entries(params).forEach(([key, value]) => {
+                if (value !== undefined) {
+                    searchParams.append(key, value as string);
+                }
+            });
+        }
+        return this.client.request(`/thread/${id}/dislikes?${searchParams.toString()}`, { method: 'GET' });
+    }
+
     async subscribe(id: string, userId: string, extendedData?: any): Promise<any> {
         return this.client.request(`/thread/${id}/subscribers`, {
             method: 'POST',
@@ -111,6 +139,87 @@ export class ThreadsResource {
         });
     }
 
+    async getSubscribers(id: string, params?: {
+        cursor?: string;
+    }): Promise<any> {
+        const searchParams = new URLSearchParams();
+        if (params) {
+            Object.entries(params).forEach(([key, value]) => {
+                if (value !== undefined) {
+                    searchParams.append(key, value as string);
+                }
+            });
+        }
+        return this.client.request(`/thread/${id}/subscribers?${searchParams.toString()}`, { method: 'GET' });
+    }
+
+    async upvote(id: string, userId?: string, extendedData?: any): Promise<any> {
+        return this.client.request(`/thread/${id}/upvotes`, {
+            method: 'POST',
+            body: JSON.stringify({ userId, extendedData }),
+        });
+    }
+
+    async unupvote(id: string, userId: string): Promise<any> {
+        return this.client.request(`/thread/${id}/upvotes?userId=${userId}`, {
+            method: 'DELETE',
+        });
+    }
+
+    async getUpvotes(id: string, params?: {
+        cursor?: string;
+    }): Promise<any> {
+        const searchParams = new URLSearchParams();
+        if (params) {
+            Object.entries(params).forEach(([key, value]) => {
+                if (value !== undefined) {
+                    searchParams.append(key, value as string);
+                }
+            });
+        }
+        return this.client.request(`/thread/${id}/upvotes?${searchParams.toString()}`, { method: 'GET' });
+    }
+
+    async downvote(id: string, userId?: string, extendedData?: any): Promise<any> {
+        return this.client.request(`/thread/${id}/downvotes`, {
+            method: 'POST',
+            body: JSON.stringify({ userId, extendedData }),
+        });
+    }
+
+    async undownvote(id: string, userId: string): Promise<any> {
+        return this.client.request(`/thread/${id}/downvotes?userId=${userId}`, {
+            method: 'DELETE',
+        });
+    }
+
+    async getDownvotes(id: string, params?: {
+        cursor?: string;
+    }): Promise<any> {
+        const searchParams = new URLSearchParams();
+        if (params) {
+            Object.entries(params).forEach(([key, value]) => {
+                if (value !== undefined) {
+                    searchParams.append(key, value as string);
+                }
+            });
+        }
+        return this.client.request(`/thread/${id}/downvotes?${searchParams.toString()}`, { method: 'GET' });
+    }
+
+    async getPoll(threadId: string, userId?: string): Promise<any> {
+        const searchParams = new URLSearchParams();
+        if (userId) {
+            searchParams.append('userId', userId);
+        }
+
+        const query = searchParams.toString();
+        return this.client.request(
+            `/thread/${threadId}/poll${query ? `?${query}` : ''}`,
+            { method: 'GET' }
+        );
+    }
+
     async vote(id: string, optionId: string, userId: string): Promise<any> {
         return this.client.request(`/thread/${id}/poll/votes`, {
             method: 'POST',