@foru-ms/sdk 1.3.3 → 2.0.3

package/dist/utils.d.ts

@@ -1,80 +0,0 @@
-/**
- * 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

@@ -1,138 +0,0 @@
-"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

@@ -1,38 +0,0 @@
-# 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

@@ -1,91 +0,0 @@
-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 { user, token } = await client.auth.register({
-            username: 'john_doe',
-            email: 'john@example.com',
-            password: 'securePassword123',
-            displayName: 'John Doe',
-        });
-        console.log('User registered:', user);
-        console.log('Auth token:', token);
-        // Note: Token is automatically set on the client
-
-        // 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);
-        // Note: Token is automatically set on the client
-
-        // 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: Get Account Security Information
-        console.log('\n=== Account Security Info ===');
-        const securityInfo = await client.auth.getSecurity();
-        console.log('User ID:', securityInfo.userId);
-        console.log('Username:', securityInfo.username);
-        console.log('Registration IP:', securityInfo.registrationIp);
-        console.log('Registration Date:', new Date(securityInfo.registrationDate).toLocaleDateString());
-        console.log('Last IP:', securityInfo.lastIp);
-        console.log('Last Seen:', new Date(securityInfo.lastSeenAt).toLocaleString());
-        console.log('Is Online:', securityInfo.isOnline);
-        console.log('Email Verified:', securityInfo.emailVerified);
-
-        // Example 6: Check Authentication Status
-        console.log('\n=== Authentication Status ===');
-        console.log('Is authenticated:', client.isAuthenticated());
-        console.log('Current token:', client.token);
-
-        // Example 7: 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

@@ -1,132 +0,0 @@
-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',
-        });
-    } 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

@@ -1,133 +0,0 @@
-// @ts-ignore
-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
-    const poll = await client.threads.getPoll(pollThread.id, userId);
-    console.log('Poll:', poll);
-
-    // Get poll results
-    const pollResults = await client.threads.getPollResults(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.',
-    });
-    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.',
-        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

@@ -1,80 +0,0 @@
-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',
-        });
-
-        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);