@foru-ms/sdk 1.1.0 → 1.2.0

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"
+```

package/examples/authentication.ts

@@ -0,0 +1,79 @@
+import { ForumClient, AuthenticationError } from '@foru-ms/sdk';
+
+/**
+ * Example: Authentication with Foru.ms SDK
+ * Demonstrates user registration, login, and token management
+ */
+
+async function main() {
+    // Initialize client with API key
+    const client = new ForumClient({
+        apiKey: process.env.FORU_API_KEY || 'your_api_key',
+    });
+
+    try {
+        // Example 1: User Registration
+        console.log('=== User Registration ===');
+        const newUser = await client.auth.register({
+            username: 'john_doe',
+            email: 'john@example.com',
+            password: 'securePassword123',
+            displayName: 'John Doe',
+        });
+        console.log('User registered:', newUser);
+
+        // Example 2: User Login
+        console.log('\n=== User Login ===');
+        const loginResponse = await client.auth.login({
+            login: 'john@example.com', // Can be username or email
+            password: 'securePassword123',
+        });
+        console.log('Login successful, token:', loginResponse.token);
+
+        // Store the token for authenticated requests
+        client.setToken(loginResponse.token);
+
+        // Example 3: Get Current User
+        console.log('\n=== Get Current User ===');
+        const currentUser = await client.auth.me();
+        console.log('Current user:', currentUser);
+
+        // Example 4: Password Reset Flow
+        console.log('\n=== Password Reset ===');
+
+        // Step 1: Request password reset
+        await client.auth.forgotPassword('john@example.com');
+        console.log('Password reset email sent');
+
+        // Step 2: Reset password with token (received via email)
+        // Note: In a real app, this would be done after user clicks the email link
+        const resetToken = 'token_from_email';
+        await client.auth.resetPassword({
+            password: 'newSecurePassword123',
+            token: resetToken,
+        });
+        console.log('Password reset successful');
+
+        // Example 5: Check Authentication Status
+        console.log('\n=== Authentication Status ===');
+        console.log('Is authenticated:', client.isAuthenticated());
+        console.log('Current token:', client.token);
+
+        // Example 6: Logout (clear token)
+        console.log('\n=== Logout ===');
+        client.clearToken();
+        console.log('Token cleared');
+        console.log('Is authenticated:', client.isAuthenticated());
+
+    } catch (error) {
+        if (error instanceof AuthenticationError) {
+            console.error('Authentication failed:', error.message);
+            console.error('Status code:', error.statusCode);
+        } else {
+            console.error('An error occurred:', error);
+        }
+    }
+}
+
+// Run the example
+main().catch(console.error);

package/examples/error-handling.ts

@@ -0,0 +1,133 @@
+import {
+    ForumClient,
+    ForumAPIError,
+    AuthenticationError,
+    AuthorizationError,
+    NotFoundError,
+    ValidationError,
+    RateLimitError,
+    ServerError,
+    NetworkError
+} from '@foru-ms/sdk';
+
+/**
+ * Example: Error Handling
+ * Demonstrates proper error handling with custom error classes
+ */
+
+async function main() {
+    const client = new ForumClient({
+        apiKey: process.env.FORU_API_KEY || 'your_api_key',
+        maxRetries: 3,
+        enableRetry: true,
+    });
+
+    // Example 1: Catch specific error types
+    console.log('=== Handling Specific Errors ===');
+    try {
+        await client.auth.login({
+            login: 'nonexistent@example.com',
+            password: 'wrong_password',
+        });
+    } catch (error) {
+        if (error instanceof AuthenticationError) {
+            console.log('Authentication failed');
+            console.log('Message:', error.message);
+            console.log('Status:', error.statusCode);
+        } else if (error instanceof NetworkError) {
+            console.log('Network error occurred');
+            console.log('Cause:', error.cause);
+        } else {
+            console.log('Unexpected error:', error);
+        }
+    }
+
+    // Example 2: Handle not found errors
+    console.log('\n=== Handling Not Found ===');
+    try {
+        await client.threads.retrieve('non-existent-id');
+    } catch (error) {
+        if (error instanceof NotFoundError) {
+            console.log('Thread not found');
+            console.log('Status:', error.statusCode); // 404
+        }
+    }
+
+    // Example 3: Handle validation errors
+    console.log('\n=== Handling Validation Errors ===');
+    try {
+        await client.threads.create({
+            title: '', // Invalid: empty title
+            body: 'Test',
+            userId: 'user-123',
+        });
+    } catch (error) {
+        if (error instanceof ValidationError) {
+            console.log('Validation failed');
+            console.log('Details:', error.response);
+        }
+    }
+
+    // Example 4: Handle rate limits
+    console.log('\n=== Handling Rate Limits ===');
+    try {
+        // Make many requests quickly
+        for (let i = 0; i < 100; i++) {
+            await client.threads.list();
+        }
+    } catch (error) {
+        if (error instanceof RateLimitError) {
+            console.log('Rate limit exceeded');
+            console.log('Retry after:', error.retryAfter, 'seconds');
+            console.log('Wait until:', new Date(Date.now() + error.retryAfter! * 1000));
+        }
+    }
+
+    // Example 5: Handle server errors with retry
+    console.log('\n=== Handling Server Errors ===');
+    const clientWithoutRetry = new ForumClient({
+        apiKey: process.env.FORU_API_KEY || 'your_api_key',
+        enableRetry: false, // Disable auto-retry
+    });
+
+    try {
+        // This might fail with 500 error
+        await clientWithoutRetry.threads.list();
+    } catch (error) {
+        if (error instanceof ServerError) {
+            console.log('Server error occurred');
+            console.log('Status:', error.statusCode);
+            console.log('You might want to retry manually');
+        }
+    }
+
+    // Example 6: Generic error handling
+    console.log('\n=== Generic Error Handling ===');
+    try {
+        await client.threads.delete('thread-123');
+    } catch (error) {
+        if (error instanceof ForumAPIError) {
+            // All API errors inherit from ForumAPIError
+            console.log('API Error:', error.message);
+            console.log('Status Code:', error.statusCode);
+            console.log('Response:', error.response);
+        } else {
+            // Non-API errors (network, etc.)
+            console.log('Unexpected error:', error);
+        }
+    }
+
+    // Example 7: Authorization errors
+    console.log('\n=== Handling Authorization Errors ===');
+    try {
+        // Try to access admin-only endpoint
+        await client.users.delete('some-user-id');
+    } catch (error) {
+        if (error instanceof AuthorizationError) {
+            console.log('Permission denied');
+            console.log('Status:', error.statusCode); // 403
+        }
+    }
+}
+
+main().catch(console.error);

package/examples/managing-threads.ts

@@ -0,0 +1,130 @@
+import { ForumClient } from '@foru-ms/sdk';
+
+/**
+ * Example: Managing Threads
+ * Demonstrates thread creation, updates, and interactions
+ */
+
+async function main() {
+    const client = new ForumClient({
+        apiKey: process.env.FORU_API_KEY || 'your_api_key',
+    });
+
+    // Set user token for authenticated actions
+    client.setToken(process.env.FORU_USER_TOKEN || 'user_token');
+
+    const userId = 'user-123';
+
+    // Example 1: Create a Thread
+    console.log('=== Creating a Thread ===');
+    const newThread = await client.threads.create({
+        title: 'How to use the SDK?',
+        body: 'I need help getting started with the Foru.ms SDK.',
+        userId,
+        tags: ['help', 'sdk'],
+    });
+    console.log('Thread created:', newThread.id);
+
+    // Example 2: Create a Thread with Poll
+    console.log('\n=== Creating a Thread with Poll ===');
+    const pollThread = await client.threads.create({
+        title: 'What\'s your favorite feature?',
+        body: 'Vote for your favorite SDK feature!',
+        userId,
+        poll: {
+            title: 'Favorite Feature',
+            options: [
+                { title: 'Type Safety', color: '#3B82F6' },
+                { title: 'Auto Pagination', color: '#10B981' },
+                { title: 'Error Handling', color: '#F59E0B' },
+            ],
+        },
+    });
+    console.log('Poll thread created:', pollThread.id);
+
+    // Example 3: Update a Thread
+    console.log('\n=== Updating a Thread ===');
+    const updatedThread = await client.threads.update(newThread.id, {
+        title: 'How to use the SDK? [SOLVED]',
+        locked: false,
+        pinned: true,
+    });
+    console.log('Thread updated');
+
+    // Example 4: Like a Thread
+    console.log('\n=== Liking a Thread ===');
+    await client.threads.like(newThread.id, userId);
+    console.log('Thread liked');
+
+    // Get likes
+    const likes = await client.threads.getLikes(newThread.id);
+    console.log('Total likes:', likes.count);
+
+    // Example 5: Subscribe to a Thread
+    console.log('\n=== Subscribing to Thread ===');
+    await client.threads.subscribe(newThread.id, userId);
+    console.log('Subscribed to thread');
+
+    // Example 6: Vote in a Poll
+    console.log('\n=== Voting in Poll ===');
+    await client.threads.vote(pollThread.id, 'option-id-1', userId);
+    console.log('Vote cast');
+
+    // Get poll results
+    const pollResults = await client.threads.getPoll(pollThread.id, userId);
+    console.log('Poll results:', pollResults);
+
+    // Example 7: Add Posts to Thread
+    console.log('\n=== Adding Posts ===');
+    const post = await client.posts.create({
+        threadId: newThread.id,
+        body: 'Thanks for posting! Check out our documentation.',
+        userId: 'moderator-123',
+    });
+    console.log('Post created:', post.id);
+
+    // Reply to the post
+    const reply = await client.posts.create({
+        threadId: newThread.id,
+        body: 'Thank you! That helps a lot.',
+        userId,
+        parentId: post.id, // This makes it a reply
+    });
+    console.log('Reply created:', reply.id);
+
+    // Example 8: Get Thread Posts
+    console.log('\n=== Getting Thread Posts ===');
+    const threadPosts = await client.threads.getPosts(newThread.id, {
+        filter: 'newest',
+    });
+    console.log('Total posts:', threadPosts.count);
+
+    // Example 9: Upvote/Downvote Threads
+    console.log('\n=== Voting on Threads ===');
+    await client.threads.upvote(newThread.id, userId);
+    console.log('Thread upvoted');
+
+    const upvotes = await client.threads.getUpvotes(newThread.id);
+    console.log('Total upvotes:', upvotes.count);
+
+    // Example 10: List Threads with Filters
+    console.log('\n=== Listing Threads ===');
+    const threads = await client.threads.list({
+        filter: 'newest',
+        tagId: 'help',
+        query: 'SDK',
+    });
+    console.log('Found threads:', threads.threads.length);
+
+    // Example 11: Get Subscribers
+    console.log('\n=== Getting Subscribers ===');
+    const subscribers = await client.threads.getSubscribers(newThread.id);
+    console.log('Total subscribers:', subscribers.count);
+
+    // Example 12: Delete a Thread
+    console.log('\n=== Deleting a Thread ===');
+    const deleted = await client.threads.delete(newThread.id, { userId });
+    console.log('Thread deleted:', deleted.deleted);
+}
+
+main().catch(console.error);

package/examples/pagination.ts

@@ -0,0 +1,81 @@
+import { ForumClient } from '@foru-ms/sdk';
+
+/**
+ * Example: Working with Pagination
+ * Demonstrates different ways to paginate through results
+ */
+
+async function main() {
+    const client = new ForumClient({
+        apiKey: process.env.FORU_API_KEY || 'your_api_key',
+    });
+
+    // Example 1: Manual Pagination
+    console.log('=== Manual Pagination ===');
+    let cursor: string | undefined;
+    let pageCount = 0;
+    const maxPages = 3;
+
+    do {
+        const response = await client.threads.list({ cursor, filter: 'newest' });
+        console.log(`Page ${++pageCount}:`, response.threads.length, 'threads');
+
+        // Process threads
+        response.threads.forEach(thread => {
+            console.log(`  - ${thread.title}`);
+        });
+
+        cursor = response.nextThreadCursor;
+    } while (cursor && pageCount < maxPages);
+
+    // Example 2: Auto-pagination with async iterator
+    console.log('\n=== Auto-Pagination (Async Iterator) ===');
+    let count = 0;
+    const maxItems = 10;
+
+    for await (const thread of client.pagination.paginateAll(
+        (cursor) => client.threads.list({ cursor, filter: 'newest' })
+    )) {
+        console.log(`Thread ${++count}:`, thread.title);
+
+        if (count >= maxItems) break; // Limit for demo
+    }
+
+    // Example 3: Fetch all pages at once
+    console.log('\n=== Fetch All Pages ===');
+    const allThreads = await client.pagination.fetchAllPages(
+        (cursor) => client.threads.list({ cursor }),
+        3 // Max 3 pages
+    );
+    console.log('Total threads fetched:', allThreads.length);
+
+    // Example 4: Paginate with filters
+    console.log('\n=== Pagination with Filters ===');
+    cursor = undefined;
+    pageCount = 0;
+
+    do {
+        const response = await client.posts.list({
+            cursor,
+            filter: 'newest',
+            type: 'created', // Only posts created by user
+            userId: 'user-123',
+        });
+
+        console.log(`Page ${++pageCount}:`, response.posts.length, 'posts');
+        cursor = response.nextPostCursor;
+    } while (cursor && pageCount < 2);
+
+    // Example 5: Check rate limits during pagination
+    console.log('\n=== Rate Limit Monitoring ===');
+    await client.threads.list();
+
+    if (client.lastRateLimitInfo) {
+        console.log('Rate Limit Info:');
+        console.log('  Limit:', client.lastRateLimitInfo.limit);
+        console.log('  Remaining:', client.lastRateLimitInfo.remaining);
+        console.log('  Resets at:', new Date(client.lastRateLimitInfo.reset * 1000));
+    }
+}
+
+main().catch(console.error);