@foru-ms/sdk 1.1.0 → 1.2.0

package/examples/webhooks.ts

@@ -0,0 +1,176 @@
+import { ForumClient } from '@foru-ms/sdk';
+import express from 'express';
+
+/**
+ * Example: Webhooks
+ * Demonstrates setting up, handling, and verifying webhooks
+ */
+
+async function setupWebhooks() {
+    const client = new ForumClient({
+        apiKey: process.env.FORU_API_KEY || 'your_api_key',
+    });
+
+    // Example 1: Create a Webhook
+    console.log('=== Creating a Webhook ===');
+    const webhook = await client.webhooks.create({
+        name: 'Thread Activity Monitor',
+        url: 'https://your-domain.com/webhooks/foru',
+        events: [
+            'thread.created',
+            'thread.updated',
+            'thread.deleted',
+            'post.created',
+        ],
+    });
+    console.log('Webhook created:', webhook.webhook.id);
+    console.log('Secret:', webhook.webhook.secret); // Save this securely!
+
+    // Example 2: List All Webhooks
+    console.log('\n=== Listing Webhooks ===');
+    const webhooks = await client.webhooks.list();
+    console.log('Total webhooks:', webhooks.webhooks.length);
+
+    // Example 3: Update a Webhook
+    console.log('\n=== Updating a Webhook ===');
+    await client.webhooks.update(webhook.webhook.id, {
+        active: true,
+        events: [
+            'thread.created',
+            'thread.updated',
+            'thread.deleted',
+            'post.created',
+            'post.updated', // Added new event
+        ],
+    });
+    console.log('Webhook updated');
+
+    // Example 4: Get Webhook Deliveries
+    console.log('\n=== Getting Webhook Deliveries ===');
+    const deliveries = await client.webhooks.getDeliveries(webhook.webhook.id);
+    console.log('Total deliveries:', deliveries.total);
+    console.log('Recent deliveries:', deliveries.deliveries.slice(0, 5));
+
+    return webhook.webhook.secret;
+}
+
+/**
+ * Example webhook handler using Express
+ */
+function setupWebhookHandler(secret: string) {
+    const app = express();
+    const client = new ForumClient({
+        apiKey: process.env.FORU_API_KEY || 'your_api_key',
+    });
+
+    // Important: Use raw body for signature verification
+    app.use(express.json({
+        verify: (req: any, res, buf) => {
+            req.rawBody = buf.toString();
+        }
+    }));
+
+    app.post('/webhooks/foru', (req: any, res) => {
+        // Example 5: Verify Webhook Signature with Timestamp
+        const signature = req.headers['x-webhook-signature'];
+        const timestamp = req.headers['x-webhook-timestamp'];
+        const event = req.headers['x-webhook-event'];
+
+        // Verify timestamp age (prevent replay attacks)
+        const age = Date.now() - parseInt(timestamp);
+        if (age > 5 * 60 * 1000) { // 5 minutes
+            console.error('Webhook timestamp too old');
+            return res.status(400).send('Webhook timestamp too old');
+        }
+
+        // Verify signature
+        const isValid = client.webhooks.verifySignature(
+            req.body,
+            signature,
+            timestamp,
+            secret
+        );
+
+        if (!isValid) {
+            console.error('Invalid webhook signature');
+            return res.status(401).send('Invalid signature');
+        }
+
+        // Process webhook payload
+        console.log('Received webhook event:', event);
+        const payload = req.body;
+
+        switch (event) {
+            case 'thread.created':
+                handleThreadCreated(payload);
+                break;
+            case 'thread.updated':
+                handleThreadUpdated(payload);
+                break;
+            case 'thread.deleted':
+                handleThreadDeleted(payload);
+                break;
+            case 'post.created':
+                handlePostCreated(payload);
+                break;
+            default:
+                console.log('Unhandled event type:', event);
+        }
+
+        // Always respond quickly to acknowledge receipt
+        res.status(200).send('OK');
+    });
+
+    const PORT = process.env.PORT || 3000;
+    app.listen(PORT, () => {
+        console.log(`\nWebhook handler listening on port ${PORT}`);
+        console.log(`Endpoint: http://localhost:${PORT}/webhooks/foru`);
+    });
+}
+
+// Event handler functions
+function handleThreadCreated(thread: any) {
+    console.log('New thread created:', thread.id);
+    console.log('Title:', thread.title);
+    console.log('Author:', thread.userId);
+
+    // Example: Send notification, update database, etc.
+}
+
+function handleThreadUpdated(thread: any) {
+    console.log('Thread updated:', thread.id);
+    console.log('Title:', thread.title);
+}
+
+function handleThreadDeleted(thread: any) {
+    console.log('Thread deleted:', thread.id);
+}
+
+function handlePostCreated(post: any) {
+    console.log('New post created:', post.id);
+    console.log('Thread:', post.threadId);
+    console.log('Author:', post.userId);
+
+    // Example: Check for spam, auto-moderate, etc.
+}
+
+// Main execution
+async function main() {
+    try {
+        // Setup webhooks
+        const secret = await setupWebhooks();
+
+        // Start webhook handler server
+        // setupWebhookHandler(secret);
+
+        console.log('\n=== Webhook Setup Complete ===');
+        console.log('Remember to save your webhook secret securely!');
+
+    } catch (error) {
+        console.error('Error setting up webhooks:', error);
+    }
+}
+
+// For demonstration, we'll just setup webhooks
+// Uncomment the line above to also start the webhook handler server
+main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@foru-ms/sdk",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "description": "JavaScript SDK for Foru.ms",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",

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',