@foru-ms/sdk 1.1.1 → 1.2.0

package/dist/resources/Webhooks.d.ts

@@ -1,9 +1,21 @@
 import { ForumClient } from '../Client';
 import { Webhook, WebhookListResponse } from '../types';
+/**
+ * Resource for managing webhooks
+ */
 export declare class WebhooksResource {
     private client;
     constructor(client: ForumClient);
+    /**
+     * List all webhooks
+     * @returns Promise resolving to list of webhooks
+     */
     list(): Promise<WebhookListResponse>;
+    /**
+     * Create a new webhook
+     * @param payload - Webhook configuration
+     * @returns Promise resolving to created webhook
+     */
     create(payload: {
         name: string;
         url: string;
@@ -11,9 +23,20 @@ export declare class WebhooksResource {
     }): Promise<{
         webhook: Webhook;
     }>;
+    /**
+     * Get a webhook by ID
+     * @param id - Webhook ID
+     * @returns Promise resolving to webhook details
+     */
     retrieve(id: string): Promise<{
         webhook: Webhook;
     }>;
+    /**
+     * Update a webhook
+     * @param id - Webhook ID
+     * @param payload - Updated webhook data
+     * @returns Promise resolving to updated webhook
+     */
     update(id: string, payload: {
         name?: string;
         url?: string;
@@ -22,9 +45,20 @@ export declare class WebhooksResource {
     }): Promise<{
         webhook: Webhook;
     }>;
+    /**
+     * Delete a webhook
+     * @param id - Webhook ID
+     * @returns Promise resolving to deletion confirmation
+     */
     delete(id: string): Promise<{
         success: boolean;
     }>;
+    /**
+     * Get webhook delivery history
+     * @param id - Webhook ID
+     * @param params - Query parameters
+     * @returns Promise resolving to delivery history
+     */
     getDeliveries(id: string, params?: {
         cursor?: string;
     }): Promise<{
@@ -32,4 +66,39 @@ export declare class WebhooksResource {
         total: number;
         nextCursor?: string;
     }>;
+    /**
+     * Verify webhook signature for security
+     * @param payload - Request body (should be the original object, not stringified)
+     * @param signature - Signature from X-Webhook-Signature header
+     * @param timestamp - Timestamp from X-Webhook-Timestamp header (in milliseconds)
+     * @param secret - Webhook secret from creation
+     * @param maxAge - Maximum age of webhook in milliseconds (default: 5 minutes)
+     * @returns True if signature is valid and timestamp is recent
+     * @example
+     * ```typescript
+     * // In your webhook handler
+     * app.post('/webhook', (req, res) => {
+     *   const signature = req.headers['x-webhook-signature'];
+     *   const timestamp = req.headers['x-webhook-timestamp'];
+     *   const event = req.headers['x-webhook-event'];
+     *
+     *   // Verify signature and timestamp
+     *   const isValid = client.webhooks.verifySignature(
+     *     req.body,
+     *     signature,
+     *     timestamp,
+     *     'your_webhook_secret'
+     *   );
+     *
+     *   if (!isValid) {
+     *     return res.status(401).send('Invalid signature');
+     *   }
+     *
+     *   // Process webhook...
+     *   console.log('Event:', event);
+     *   res.sendStatus(200);
+     * });
+     * ```
+     */
+    verifySignature(payload: any, signature: string, timestamp: string, secret: string, maxAge?: number): boolean;
 }

package/dist/resources/Webhooks.js

@@ -1,37 +1,71 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebhooksResource = void 0;
+/**
+ * Resource for managing webhooks
+ */
 class WebhooksResource {
     constructor(client) {
         this.client = client;
     }
+    /**
+     * List all webhooks
+     * @returns Promise resolving to list of webhooks
+     */
     async list() {
         return this.client.request('/webhooks', {
             method: 'GET',
         });
     }
+    /**
+     * Create a new webhook
+     * @param payload - Webhook configuration
+     * @returns Promise resolving to created webhook
+     */
     async create(payload) {
         return this.client.request('/webhooks', {
             method: 'POST',
             body: JSON.stringify(payload),
         });
     }
+    /**
+     * Get a webhook by ID
+     * @param id - Webhook ID
+     * @returns Promise resolving to webhook details
+     */
     async retrieve(id) {
         return this.client.request(`/webhooks/${id}`, {
             method: 'GET',
         });
     }
+    /**
+     * Update a webhook
+     * @param id - Webhook ID
+     * @param payload - Updated webhook data
+     * @returns Promise resolving to updated webhook
+     */
     async update(id, payload) {
         return this.client.request(`/webhooks/${id}`, {
             method: 'PATCH',
             body: JSON.stringify(payload),
         });
     }
+    /**
+     * Delete a webhook
+     * @param id - Webhook ID
+     * @returns Promise resolving to deletion confirmation
+     */
     async delete(id) {
         return this.client.request(`/webhooks/${id}`, {
             method: 'DELETE',
         });
     }
+    /**
+     * Get webhook delivery history
+     * @param id - Webhook ID
+     * @param params - Query parameters
+     * @returns Promise resolving to delivery history
+     */
     async getDeliveries(id, params) {
         const searchParams = new URLSearchParams();
         if (params === null || params === void 0 ? void 0 : params.cursor)
@@ -40,5 +74,86 @@ class WebhooksResource {
             method: 'GET',
         });
     }
+    /**
+     * Verify webhook signature for security
+     * @param payload - Request body (should be the original object, not stringified)
+     * @param signature - Signature from X-Webhook-Signature header
+     * @param timestamp - Timestamp from X-Webhook-Timestamp header (in milliseconds)
+     * @param secret - Webhook secret from creation
+     * @param maxAge - Maximum age of webhook in milliseconds (default: 5 minutes)
+     * @returns True if signature is valid and timestamp is recent
+     * @example
+     * ```typescript
+     * // In your webhook handler
+     * app.post('/webhook', (req, res) => {
+     *   const signature = req.headers['x-webhook-signature'];
+     *   const timestamp = req.headers['x-webhook-timestamp'];
+     *   const event = req.headers['x-webhook-event'];
+     *
+     *   // Verify signature and timestamp
+     *   const isValid = client.webhooks.verifySignature(
+     *     req.body,
+     *     signature,
+     *     timestamp,
+     *     'your_webhook_secret'
+     *   );
+     *
+     *   if (!isValid) {
+     *     return res.status(401).send('Invalid signature');
+     *   }
+     *
+     *   // Process webhook...
+     *   console.log('Event:', event);
+     *   res.sendStatus(200);
+     * });
+     * ```
+     */
+    verifySignature(payload, signature, timestamp, secret, maxAge = 5 * 60 * 1000 // 5 minutes default
+    ) {
+        try {
+            // Verify timestamp (prevent replay attacks)
+            const webhookTimestamp = parseInt(timestamp, 10);
+            if (isNaN(webhookTimestamp)) {
+                console.error('Invalid webhook timestamp format');
+                return false;
+            }
+            const age = Date.now() - webhookTimestamp;
+            if (age > maxAge) {
+                console.error('Webhook timestamp too old:', age, 'ms');
+                return false;
+            }
+            // Use Node.js crypto if available
+            if (typeof require !== 'undefined') {
+                try {
+                    const crypto = require('crypto');
+                    // Create the signed data: timestamp.payload
+                    const data = `${timestamp}.${JSON.stringify(payload)}`;
+                    // Calculate expected signature
+                    const expectedSignature = crypto
+                        .createHmac('sha256', secret)
+                        .update(data)
+                        .digest('hex');
+                    // Use timing-safe comparison
+                    if (crypto.timingSafeEqual) {
+                        return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));
+                    }
+                    // Fallback to simple comparison (less secure)
+                    return signature === expectedSignature;
+                }
+                catch (error) {
+                    console.error('Error using Node.js crypto:', error);
+                    // Fall through to browser implementation
+                }
+            }
+            // For browser environments or when Node crypto is not available
+            console.warn('Webhook signature verification not fully supported in this environment');
+            console.warn('Please use Node.js for secure webhook verification');
+            return false;
+        }
+        catch (error) {
+            console.error('Error verifying webhook signature:', error);
+            return false;
+        }
+    }
 }
 exports.WebhooksResource = WebhooksResource;

package/dist/response-types.d.ts

@@ -0,0 +1,105 @@
+import { User } from './types';
+/**
+ * Rate limit information from API responses
+ */
+export interface RateLimitInfo {
+    /** Maximum number of requests allowed in the time window */
+    limit: number;
+    /** Number of requests remaining in the current window */
+    remaining: number;
+    /** Unix timestamp when the rate limit resets */
+    reset: number;
+}
+/**
+ * Metadata included with API responses
+ */
+export interface ResponseMetadata {
+    /** Rate limit information, if available */
+    rateLimit?: RateLimitInfo;
+    /** Request ID for debugging */
+    requestId?: string;
+}
+/**
+ * Generic API response wrapper
+ */
+export interface APIResponse<T> {
+    /** Response data */
+    data: T;
+    /** Response metadata */
+    meta?: ResponseMetadata;
+}
+/**
+ * Response for interaction lists (likes, upvotes, etc.)
+ */
+export interface InteractionListResponse {
+    /** List of users who performed the interaction */
+    users: User[];
+    /** Cursor for next page */
+    nextCursor?: string;
+    /** Total count of interactions */
+    count: number;
+}
+/**
+ * Response for poll data
+ */
+export interface PollResponse {
+    /** Poll ID */
+    id: string;
+    /** Poll title */
+    title: string;
+    /** Poll options */
+    options: PollOption[];
+    /** Total number of votes */
+    totalVotes: number;
+    /** Whether the poll allows multiple votes */
+    allowMultiple?: boolean;
+    /** Poll expiration date */
+    expiresAt?: string;
+    /** User's vote, if userId was provided */
+    userVote?: {
+        optionId: string;
+        votedAt: string;
+    };
+}
+/**
+ * Poll option data
+ */
+export interface PollOption {
+    /** Option ID */
+    id: string;
+    /** Option title */
+    title: string;
+    /** Option color */
+    color?: string;
+    /** Number of votes for this option */
+    votes: number;
+    /** Percentage of total votes */
+    percentage: number;
+    /** Extended data */
+    extendedData?: Record<string, any>;
+}
+/**
+ * Response for batch operations
+ */
+export interface BatchOperationResponse {
+    /** Number of items successfully processed */
+    success: number;
+    /** Number of items that failed */
+    failed: number;
+    /** Error details for failed items */
+    errors?: Array<{
+        id: string;
+        error: string;
+    }>;
+}
+/**
+ * Pagination cursor response
+ */
+export interface CursorPagination<T> {
+    /** Array of items */
+    items: T[];
+    /** Cursor for next page */
+    nextCursor?: string;
+    /** Whether there are more items */
+    hasMore: boolean;
+}

package/dist/response-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Pagination utilities for working with cursor-based pagination
+ */
+export declare class PaginationHelper {
+    /**
+     * Async generator to auto-paginate through all results
+     * @param fetchPage - Function to fetch a page of results
+     * @yields Individual items from each page
+     * @example
+     * ```typescript
+     * const helper = new PaginationHelper();
+     * for await (const thread of helper.paginateAll((cursor) =>
+     *   client.threads.list({ cursor })
+     * )) {
+     *   console.log(thread);
+     * }
+     * ```
+     */
+    paginateAll<T>(fetchPage: (cursor?: string) => Promise<{
+        threads?: T[];
+        posts?: T[];
+        users?: T[];
+        tags?: T[];
+        nextThreadCursor?: string;
+        nextPostCursor?: string;
+        nextUserCursor?: string;
+        nextTagCursor?: string;
+    }>): AsyncIterableIterator<T>;
+    /**
+     * Fetch all items from a paginated endpoint
+     * @param fetchPage - Function to fetch a page of results
+     * @param maxPages - Maximum number of pages to fetch (default: Infinity)
+     * @returns Array of all items
+     */
+    fetchAllPages<T>(fetchPage: (cursor?: string) => Promise<{
+        threads?: T[];
+        posts?: T[];
+        users?: T[];
+        tags?: T[];
+        nextThreadCursor?: string;
+        nextPostCursor?: string;
+        nextUserCursor?: string;
+        nextTagCursor?: string;
+    }>, maxPages?: number): Promise<T[]>;
+}
+/**
+ * Input validation utilities
+ */
+export declare class Validator {
+    /**
+     * Validate that a string is not empty
+     */
+    static isNonEmptyString(value: any, fieldName: string): void;
+    /**
+     * Validate email format
+     */
+    static isValidEmail(email: string): boolean;
+    /**
+     * Validate that a value is one of the allowed options
+     */
+    static isOneOf<T>(value: T, options: T[], fieldName: string): void;
+    /**
+     * Validate cursor format (if needed)
+     */
+    static isValidCursor(cursor: string): boolean;
+}
+/**
+ * Retry utilities for handling transient failures
+ */
+export declare class RetryHelper {
+    /**
+     * Execute a function with exponential backoff retry
+     * @param fn - Function to execute
+     * @param maxRetries - Maximum number of retry attempts
+     * @param initialDelay - Initial delay in milliseconds
+     * @returns Result of the function
+     */
+    static withRetry<T>(fn: () => Promise<T>, maxRetries?: number, initialDelay?: number): Promise<T>;
+    private static sleep;
+}

package/dist/utils.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetryHelper = exports.Validator = exports.PaginationHelper = void 0;
+/**
+ * Pagination utilities for working with cursor-based pagination
+ */
+class PaginationHelper {
+    /**
+     * Async generator to auto-paginate through all results
+     * @param fetchPage - Function to fetch a page of results
+     * @yields Individual items from each page
+     * @example
+     * ```typescript
+     * const helper = new PaginationHelper();
+     * for await (const thread of helper.paginateAll((cursor) =>
+     *   client.threads.list({ cursor })
+     * )) {
+     *   console.log(thread);
+     * }
+     * ```
+     */
+    async *paginateAll(fetchPage) {
+        let cursor;
+        let hasMore = true;
+        while (hasMore) {
+            const response = await fetchPage(cursor);
+            // Determine which array and cursor to use
+            const items = response.threads || response.posts || response.users || response.tags || [];
+            const nextCursor = response.nextThreadCursor || response.nextPostCursor ||
+                response.nextUserCursor || response.nextTagCursor;
+            for (const item of items) {
+                yield item;
+            }
+            cursor = nextCursor;
+            hasMore = !!nextCursor;
+        }
+    }
+    /**
+     * Fetch all items from a paginated endpoint
+     * @param fetchPage - Function to fetch a page of results
+     * @param maxPages - Maximum number of pages to fetch (default: Infinity)
+     * @returns Array of all items
+     */
+    async fetchAllPages(fetchPage, maxPages = Infinity) {
+        const allItems = [];
+        let cursor;
+        let pageCount = 0;
+        while (pageCount < maxPages) {
+            const response = await fetchPage(cursor);
+            const items = response.threads || response.posts || response.users || response.tags || [];
+            const nextCursor = response.nextThreadCursor || response.nextPostCursor ||
+                response.nextUserCursor || response.nextTagCursor;
+            allItems.push(...items);
+            cursor = nextCursor;
+            pageCount++;
+            if (!nextCursor)
+                break;
+        }
+        return allItems;
+    }
+}
+exports.PaginationHelper = PaginationHelper;
+/**
+ * Input validation utilities
+ */
+class Validator {
+    /**
+     * Validate that a string is not empty
+     */
+    static isNonEmptyString(value, fieldName) {
+        if (typeof value !== 'string' || value.trim().length === 0) {
+            throw new Error(`${fieldName} must be a non-empty string`);
+        }
+    }
+    /**
+     * Validate email format
+     */
+    static isValidEmail(email) {
+        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        return emailRegex.test(email);
+    }
+    /**
+     * Validate that a value is one of the allowed options
+     */
+    static isOneOf(value, options, fieldName) {
+        if (!options.includes(value)) {
+            throw new Error(`${fieldName} must be one of: ${options.join(', ')}`);
+        }
+    }
+    /**
+     * Validate cursor format (if needed)
+     */
+    static isValidCursor(cursor) {
+        return typeof cursor === 'string' && cursor.length > 0;
+    }
+}
+exports.Validator = Validator;
+/**
+ * Retry utilities for handling transient failures
+ */
+class RetryHelper {
+    /**
+     * Execute a function with exponential backoff retry
+     * @param fn - Function to execute
+     * @param maxRetries - Maximum number of retry attempts
+     * @param initialDelay - Initial delay in milliseconds
+     * @returns Result of the function
+     */
+    static async withRetry(fn, maxRetries = 3, initialDelay = 1000) {
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                lastError = error;
+                // Don't retry on client errors (4xx) except 429
+                if (error.statusCode >= 400 && error.statusCode < 500 && error.statusCode !== 429) {
+                    throw error;
+                }
+                // Don't retry on last attempt
+                if (attempt === maxRetries) {
+                    break;
+                }
+                // Calculate delay with exponential backoff
+                const delay = error.retryAfter
+                    ? error.retryAfter * 1000
+                    : initialDelay * Math.pow(2, attempt);
+                await this.sleep(delay);
+            }
+        }
+        throw lastError;
+    }
+    static sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+exports.RetryHelper = RetryHelper;

package/examples/README.md

@@ -0,0 +1,38 @@
+# SDK Examples
+
+This directory contains example code demonstrating common use cases for the Foru.ms SDK.
+
+## Examples
+
+- [Authentication](./authentication.ts) - Login, registration, and token management
+- [Managing Threads](./managing-threads.ts) - Create, update, and interact with threads
+- [Pagination](./pagination.ts) - Working with cursor-based pagination
+- [Webhooks](./webhooks.ts) - Setting up and verifying webhooks
+- [Error Handling](./error-handling.ts) - Properly handling SDK errors
+
+## Running Examples
+
+```bash
+# Install dependencies
+npm install @foru-ms/sdk
+
+# Run an example with ts-node
+npx ts-node examples/authentication.ts
+
+# Or compile and run
+tsc examples/authentication.ts && node examples/authentication.js
+```
+
+## Configuration
+
+Most examples require an API key. Set it as an environment variable:
+
+```bash
+export FORU_API_KEY="your_api_key_here"
+```
+
+For user-authenticated examples, you'll also need a user token:
+
+```bash
+export FORU_USER_TOKEN="user_jwt_token"
+```