@foru-ms/sdk 1.1.1 → 1.2.1

package/src/resources/Users.ts

@@ -75,6 +75,42 @@ export class UsersResource {
         });
     }
 
+    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>(`/user/${id}/threads?${searchParams.toString()}`, {
+            method: 'GET',
+        });
+    }
+
+    async getPosts(id: string, params?: {
+        query?: string;
+        cursor?: string;
+        filter?: 'newest' | 'oldest';
+    }): Promise<import('../types').PostListResponse> {
+        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').PostListResponse>(`/user/${id}/posts?${searchParams.toString()}`, {
+            method: 'GET',
+        });
+    }
+
     async getFollowers(id: string, params?: {
         query?: string;
         cursor?: string;

package/src/resources/Webhooks.ts

@@ -1,6 +1,9 @@
 import { ForumClient } from '../Client';
 import { Webhook, WebhookListResponse } from '../types';
 
+/**
+ * Resource for managing webhooks
+ */
 export class WebhooksResource {
     private client: ForumClient;
 
@@ -8,12 +11,21 @@ export class WebhooksResource {
         this.client = client;
     }
 
+    /**
+     * List all webhooks
+     * @returns Promise resolving to list of webhooks
+     */
     async list(): Promise<WebhookListResponse> {
         return this.client.request<WebhookListResponse>('/webhooks', {
             method: 'GET',
         });
     }
 
+    /**
+     * Create a new webhook
+     * @param payload - Webhook configuration
+     * @returns Promise resolving to created webhook
+     */
     async create(payload: {
         name: string;
         url: string;
@@ -25,12 +37,23 @@ export class WebhooksResource {
         });
     }
 
+    /**
+     * Get a webhook by ID
+     * @param id - Webhook ID
+     * @returns Promise resolving to webhook details
+     */
     async retrieve(id: string): Promise<{ webhook: Webhook }> {
         return this.client.request<{ webhook: Webhook }>(`/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: string, payload: {
         name?: string;
         url?: string;
@@ -43,12 +66,23 @@ export class WebhooksResource {
         });
     }
 
+    /**
+     * Delete a webhook
+     * @param id - Webhook ID
+     * @returns Promise resolving to deletion confirmation
+     */
     async delete(id: string): Promise<{ success: boolean }> {
         return this.client.request<{ success: boolean }>(`/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: string, params?: { cursor?: string }): Promise<{ deliveries: any[]; total: number; nextCursor?: string }> {
         const searchParams = new URLSearchParams();
         if (params?.cursor) searchParams.append('cursor', params.cursor);
@@ -57,4 +91,101 @@ export 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: any,
+        signature: string,
+        timestamp: string,
+        secret: string,
+        maxAge: number = 5 * 60 * 1000 // 5 minutes default
+    ): boolean {
+        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;
+        }
+    }
 }

package/src/response-types.ts

@@ -0,0 +1,113 @@
+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/src/utils.ts

@@ -0,0 +1,182 @@
+import { CursorPagination } from './response-types';
+
+/**
+ * Pagination utilities for working with cursor-based pagination
+ */
+export 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<T>(
+        fetchPage: (cursor?: string) => Promise<{
+            threads?: T[];
+            posts?: T[];
+            users?: T[];
+            tags?: T[];
+            nextThreadCursor?: string;
+            nextPostCursor?: string;
+            nextUserCursor?: string;
+            nextTagCursor?: string;
+        }>
+    ): AsyncIterableIterator<T> {
+        let cursor: string | undefined;
+        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<T>(
+        fetchPage: (cursor?: string) => Promise<{
+            threads?: T[];
+            posts?: T[];
+            users?: T[];
+            tags?: T[];
+            nextThreadCursor?: string;
+            nextPostCursor?: string;
+            nextUserCursor?: string;
+            nextTagCursor?: string;
+        }>,
+        maxPages: number = Infinity
+    ): Promise<T[]> {
+        const allItems: T[] = [];
+        let cursor: string | undefined;
+        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;
+    }
+}
+
+/**
+ * Input validation utilities
+ */
+export class Validator {
+    /**
+     * Validate that a string is not empty
+     */
+    static isNonEmptyString(value: any, fieldName: string): void {
+        if (typeof value !== 'string' || value.trim().length === 0) {
+            throw new Error(`${fieldName} must be a non-empty string`);
+        }
+    }
+
+    /**
+     * Validate email format
+     */
+    static isValidEmail(email: string): boolean {
+        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        return emailRegex.test(email);
+    }
+
+    /**
+     * Validate that a value is one of the allowed options
+     */
+    static isOneOf<T>(value: T, options: T[], fieldName: string): void {
+        if (!options.includes(value)) {
+            throw new Error(`${fieldName} must be one of: ${options.join(', ')}`);
+        }
+    }
+
+    /**
+     * Validate cursor format (if needed)
+     */
+    static isValidCursor(cursor: string): boolean {
+        return typeof cursor === 'string' && cursor.length > 0;
+    }
+}
+
+/**
+ * Retry utilities for handling transient failures
+ */
+export 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<T>(
+        fn: () => Promise<T>,
+        maxRetries: number = 3,
+        initialDelay: number = 1000
+    ): Promise<T> {
+        let lastError: Error;
+
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return await fn();
+            } catch (error: any) {
+                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!;
+    }
+
+    private static sleep(ms: number): Promise<void> {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}