@foru-ms/sdk 1.1.1 → 1.2.0

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);

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.1",
+    "version": "1.2.0",
     "description": "JavaScript SDK for Foru.ms",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",