@foru-ms/sdk 1.1.1 → 1.2.0

package/README.md

@@ -1,8 +1,18 @@
 # @foru-ms/sdk
 
-The official JavaScript/TypeScript SDK for [Foru.ms](https://foru.ms). Build powerful community features directly into your application.
+The official JavaScript/ TypeScript SDK for [Foru.ms](https://foru.ms). Build powerful community features directly into your application.
 
-This SDK is fully typed and provides a comprehensive interface to the Foru.ms API.
+This SDK is fully typed and provides a comprehensive interface to the Foru.ms API with built-in error handling, automatic retries, and pagination helpers.
+
+## Features
+
+✨ **Fully Typed** - Complete TypeScript support with detailed type definitions  
+🔄 **Auto Retry** - Automatic retry logic for rate limits and server errors  
+📄 **Easy Pagination** - Built-in helpers for cursor-based pagination  
+🚨 **Rich Error Classes** - Specific error types for better error handling  
+🔐 **Webhook Verification** - Built-in signature verification for webhooks  
+📊 **Rate Limit Tracking** - Automatic tracking of API rate limits  
+📚 **Comprehensive Examples** - Detailed examples for common use cases
 
 ## Installation
 
@@ -14,20 +24,156 @@ yarn add @foru-ms/sdk
 pnpm add @foru-ms/sdk
 ```
 
-## Setup & Initialization
+## Quick Start
 
 ```typescript
 import { ForumClient } from '@foru-ms/sdk';
 
 const client = new ForumClient({
   apiKey: 'your_api_key',
-  // baseUrl: 'https://api.foru.ms/v1' // Optional
+  baseUrl: 'https://api.foru.ms/v1', // Optional
+  maxRetries: 3, // Optional, default: 3
+  enableRetry: true, // Optional, default: true
 });
 
 // Set an authentication token (JWT) for user-scoped requests
 client.setToken('user_jwt_token');
+
+// Create a thread
+const thread = await client.threads.create({
+  title: 'My First Thread',
+  body: 'Hello, Foru.ms!',
+  userId: 'user-123',
+});
+
+// List threads with auto-pagination
+for await (const thread of client.pagination.paginateAll(
+  (cursor) => client.threads.list({ cursor })
+)) {
+  console.log(thread.title);
+}
+```
+
+## Error Handling
+
+The SDK provides specific error classes for different scenarios:
+
+```typescript
+import {
+  ForumClient,
+  AuthenticationError,
+  NotFoundError,
+  RateLimitError,
+  ValidationError
+} from '@foru-ms/sdk';
+
+try {
+  await client.threads.retrieve('thread-id');
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    console.log('Thread not found');
+  } else if (error instanceof RateLimitError) {
+    console.log('Rate limited, retry after:', error.retryAfter);
+  } else if (error instanceof AuthenticationError) {
+    console.log('Authentication failed');
+  }
+}
 ```
 
+**Available Error Classes:**
+- `ForumAPIError` - Base class for all API errors
+- `AuthenticationError` - 401 errors
+- `AuthorizationError` - 403 errors
+- `NotFoundError` - 404 errors
+- `ValidationError` - 422 errors
+- `RateLimitError` - 429 errors
+- `ServerError` - 5xx errors
+- `NetworkError` - Network/connection errors
+
+## Pagination
+
+The SDK provides multiple ways to handle pagination:
+
+```typescript
+// Auto-pagination with async iterator
+for await (const thread of client.pagination.paginateAll(
+  (cursor) => client.threads.list({ cursor, filter: 'newest' })
+)) {
+  console.log(thread.title);
+}
+
+// Fetch all pages at once
+const allThreads = await client.pagination.fetchAllPages(
+  (cursor) => client.threads.list({ cursor }),
+  5 // max pages
+);
+
+// Manual pagination
+let cursor: string | undefined;
+do {
+  const response = await client.threads.list({ cursor });
+  // Process threads...
+  cursor = response.nextThreadCursor;
+} while (cursor);
+```
+
+## Webhooks
+
+Verify webhook signatures for security. All webhooks include:
+- `X-Webhook-Signature`: HMAC-SHA256 signature
+- `X-Webhook-Timestamp`: Unix timestamp (milliseconds)
+- `X-Webhook-Event`: Event type
+
+```typescript
+app.post('/webhooks/foru', (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 with timestamp (prevents replay attacks)
+  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.send('OK');
+});
+```
+
+## Rate Limiting
+
+Track rate limit information automatically:
+
+```typescript
+await client.threads.list();
+
+if (client.lastRateLimitInfo) {
+  console.log('Limit:', client.lastRateLimitInfo.limit);
+  console.log('Remaining:', client.lastRateLimitInfo.remaining);
+  console.log('Resets at:', new Date(client.lastRateLimitInfo.reset * 1000));
+}
+```
+
+## Examples
+
+Check the `/examples` directory for detailed examples:
+
+- [Authentication](./examples/authentication.ts) - Login, registration, token management
+- [Managing Threads](./examples/managing-threads.ts) - CRUD operations, polls, interactions
+- [Pagination](./examples/pagination.ts) - Different pagination strategies
+- [Error Handling](./examples/error-handling.ts) - Comprehensive error handling
+- [Webhooks](./examples/webhooks.ts) - Setup and verification
+
+
+
 ## API Reference
 
 ### Auth (`client.auth`)
@@ -48,10 +194,20 @@ client.setToken('user_jwt_token');
 *   `getPosts(id: string, params: { cursor?: string; filter?: 'newest' | 'oldest' })`: Get posts in a thread.
 *   `like(id: string, userId: string, extendedData?: any)`: Like a thread.
 *   `unlike(id: string, userId: string)`: Unlike a thread.
+*   `getLikes(id: string, params?: { cursor?: string })`: Get users who liked a thread.
 *   `dislike(id: string, userId: string, extendedData?: any)`: Dislike a thread.
 *   `undislike(id: string, userId: string)`: Remove dislike from a thread.
+*   `getDislikes(id: string, params?: { cursor?: string })`: Get users who disliked a thread.
 *   `subscribe(id: string, userId: string)`: Subscribe to a thread.
 *   `unsubscribe(id: string, userId: string)`: Unsubscribe from a thread.
+*   `getSubscribers(id: string, params?: { cursor?: string })`: Get users subscribed to a thread.
+*   `upvote(id: string, userId: string, extendedData?: any)`: Upvote a thread.
+*   `unupvote(id: string, userId: string)`: Remove upvote from a thread.
+*   `getUpvotes(id: string, params?: { cursor?: string })`: Get users who upvoted a thread.
+*   `downvote(id: string, userId: string, extendedData?: any)`: Downvote a thread.
+*   `undownvote(id: string, userId: string)`: Remove downvote from a thread.
+*   `getDownvotes(id: string, params?: { cursor?: string })`: Get users who downvoted a thread.
+*   `getPoll(id: string, userId?: string)`: Get poll results.
 *   `vote(id: string, userId: string, optionId: string)`: Vote in a thread poll.
 *   `voteUpdate(id: string, userId: string, optionId: string)`: Change vote.
 *   `unvote(id: string, userId: string)`: Remove vote.
@@ -66,12 +222,16 @@ client.setToken('user_jwt_token');
 *   `getChildren(id: string, params: { cursor?: string; filter?: 'newest' | 'oldest' })`: Get child posts (nested replies).
 *   `like(id: string, userId: string, extendedData?: any)`: Like a post.
 *   `unlike(id: string, userId: string)`: Unlike a post.
+*   `getLikes(id: string, params?: { cursor?: string })`: Get users who liked a post.
 *   `dislike(id: string, userId: string, extendedData?: any)`: Dislike a post.
 *   `undislike(id: string, userId: string)`: Remove dislike.
+*   `getDislikes(id: string, params?: { cursor?: string })`: Get users who disliked a post.
 *   `upvote(id: string, userId: string, extendedData?: any)`: Upvote a post.
 *   `unupvote(id: string, userId: string)`: Remove upvote.
+*   `getUpvotes(id: string, params?: { cursor?: string })`: Get users who upvoted a post.
 *   `downvote(id: string, userId: string, extendedData?: any)`: Downvote a post.
 *   `undownvote(id: string, userId: string)`: Remove downvote.
+*   `getDownvotes(id: string, params?: { cursor?: string })`: Get users who downvoted a post.
 
 ### Users (`client.users`)
 
@@ -80,6 +240,8 @@ client.setToken('user_jwt_token');
 *   `create(payload: { username: string; email: string; password: string; displayName?: string; emailVerified?: boolean; roles?: string[]; bio?: string; signature?: string; url?: string; extendedData?: Record<string, any> })`: Create a user (Admin).
 *   `update(id: string, payload: { username?: string; email?: string; password?: string; displayName?: string; emailVerified?: boolean; roles?: string[]; bio?: string; signature?: string; url?: string; extendedData?: Record<string, any> })`: Update a user.
 *   `delete(id: string)`: Delete a user.
+*   `getThreads(id: string, params?: { query?: string; cursor?: string; filter?: 'newest' | 'oldest' })`: Get all threads created by a user.
+*   `getPosts(id: string, params?: { query?: string; cursor?: string; filter?: 'newest' | 'oldest' })`: Get all posts created by a user.
 *   `getFollowers(id: string, params?: { query?: string; cursor?: string; filter?: 'newest' | 'oldest' })`: Get user's followers.
 *   `getFollowing(id: string, params?: { query?: string; cursor?: string; filter?: 'newest' | 'oldest' })`: Get who a user follows.
 *   `follow(id: string, followerId: string, extendedData?: any)`: Follow a user.
@@ -93,8 +255,10 @@ client.setToken('user_jwt_token');
 *   `retrieve(id: string, params?: { userId?: string })`: Get a tag.
 *   `update(id: string, payload: { name?: string; description?: string; color?: string; extendedData?: Record<string, any> })`: Update a tag.
 *   `delete(id: string)`: Delete a tag.
+*   `getThreads(id: string, params?: { query?: string; cursor?: string; filter?: 'newest' | 'oldest' })`: Get all threads with a specific tag.
 *   `subscribe(id: string, userId: string)`: Subscribe to a tag.
 *   `unsubscribe(id: string, userId: string)`: Unsubscribe from a tag.
+*   `getSubscribers(id: string, params?: { cursor?: string })`: Get users subscribed to a tag.
 *   `listSubscribed(params: { userId: string; query?: string; cursor?: string })`: List tags a user is subscribed to.
 
 
@@ -129,6 +293,7 @@ client.setToken('user_jwt_token');
 *   `list()`: Get all configured integrations.
 *   `create(payload: { type: 'SLACK' | 'DISCORD' | 'SALESFORCE' | 'HUBSPOT' | 'OKTA' | 'AUTH0'; name: string; config: any })`: Configure an integration (Slack, Discord, etc.).
 *   `retrieve(id: string)`: Get integration details.
+*   `update(id: string, payload: { name?: string; config?: any; active?: boolean })`: Update an integration.
 *   `delete(id: string)`: Remove an integration.
 
 ### Private Messages (`client.privateMessages`)
@@ -137,6 +302,7 @@ client.setToken('user_jwt_token');
 *   `create(payload: { title?: string; body: string; recipientId: string; senderId?: string; extendedData?: Record<string, any> })`: Send a direct message.
 *   `retrieve(id: string)`: Get a message thread.
 *   `reply(id: string, payload: { body: string; senderId: string; recipientId: string; extendedData?: Record<string, any> })`: Reply to a message.
+*   `update(id: string, payload: { read?: boolean; extendedData?: Record<string, any> })`: Update a message (e.g., mark as read).
 *   `delete(id: string)`: Delete a message.
 
 ### Reports (`client.reports`)
@@ -161,6 +327,8 @@ client.setToken('user_jwt_token');
 
 *   `list()`: List SSO providers.
 *   `create(payload: { provider: 'OKTA' | 'AUTH0' | 'SAML'; domain: string; config: any })`: Configure SSO.
+*   `retrieve(id: string)`: Get SSO provider details.
+*   `update(id: string, payload: { domain?: string; config?: any; active?: boolean })`: Update SSO configuration.
 *   `delete(id: string)`: Remove SSO provider.
 
 ## Types
@@ -230,22 +398,129 @@ import {
   
   // Utility Types
   PaginatedResponse,
-  InteractionType
+  InteractionType,
+  
+  // Error Classes
+  ForumAPIError,
+  AuthenticationError,
+  AuthorizationError,
+  NotFoundError,
+  ValidationError,
+  RateLimitError,
+  ServerError,
+  NetworkError,
+  
+  // Response Types
+  RateLimitInfo,
+  ResponseMetadata,
+  APIResponse,
+  InteractionListResponse,
+  PollResponse,
+  PollOption,
+  
+  // Utilities
+  PaginationHelper,
+  Validator,
+  RetryHelper
 } from '@foru-ms/sdk';
 ```
 
-## Error Handling
+## Advanced Usage
 
-All methods return a Promise. If the API returns a non-200 status, the Promise rejects with an Error object containing the server message.
+### Custom Client Options
 
 ```typescript
-try {
-  await client.threads.create({ ... });
-} catch (err: any) {
-  console.error("Error creating thread:", err.message);
+const client = new ForumClient({
+  apiKey: 'your_api_key',
+  baseUrl: 'https://api.foru.ms/v1',
+  maxRetries: 5,        // Increase retry attempts
+  enableRetry: true,    // Enable auto-retry (default: true)
+});
+
+// Access rate limit info after any request
+await client.threads.list();
+console.log('Rate limit:', client.lastRateLimitInfo);
+
+// Check authentication status
+if (client.isAuthenticated()) {
+  const user = await client.auth.me();
+}
+```
+
+### Async Iteration for Large Datasets
+
+```typescript
+// Automatically fetch all pages
+for await (const user of client.pagination.paginateAll(
+  (cursor) => client.users.list({ cursor })
+)) {
+  await processUser(user);
+  // Pagination happens automatically in the background
 }
 ```
 
+### Batch Operations
+
+```typescript
+// Fetch multiple items efficiently
+const threadIds = ['id1', 'id2', 'id3'];
+const threads = await Promise.all(
+  threadIds.map(id => client.threads.retrieve(id))
+);
+```
+
+## Best Practices
+
+1. **Error Handling**: Always use try-catch with specific error types
+2. **Rate Limits**: Monitor `client.lastRateLimitInfo` for API usage
+3. **Webhooks**: Always verify signatures to prevent unauthorized requests
+4. **Pagination**: Use async iterators for large result sets
+5. **Authentication**: Store tokens securely, never in client-side code
+
+## Troubleshooting
+
+### Rate Limit Errors
+
+If you encounter rate limit errors frequently, consider:
+- Implementing caching for frequently accessed data
+- Using pagination helpers to avoid fetching too much data
+- Batching operations where possible
+
+### Authentication Issues
+
+- Ensure your API key is valid and active
+- Check that tokens haven't expired
+- Use `client.isAuthenticated()` to verify authentication status
+
+### Webhook Verification Failures
+
+- Verify you're using the correct webhook secret
+- Check that timestamps aren't too old (default: 5 minutes)
+- Ensure you're passing the raw payload object, not a string
+
+## Contributing
+
+We welcome contributions! Please see our contributing guidelines for more information.
+
+## Support
+
+- 📧 Email: support@foru.ms
+- 📚 Documentation: https://docs.foru.ms
+- 🐛 Issues: https://github.com/foru-ms/sdk/issues
+
+## Changelog
+
+### v1.2.0
+- Added custom error classes for better error handling
+- Added automatic retry logic with exponential backoff
+- Added pagination helpers for easy iteration
+- Added webhook signature verification
+- Added 22 new endpoints
+- Enhanced documentation and examples
+
+### v1.x
+- Initial SDK release with core functionality
+
 ## License
 
 MIT

package/dist/Client.d.ts

@@ -12,10 +12,42 @@ import { PrivateMessagesResource } from './resources/PrivateMessages';
 import { ReportsResource } from './resources/Reports';
 import { RolesResource } from './resources/Roles';
 import { SSOResource } from './resources/SSO';
+import { PaginationHelper } from './utils';
+import { RateLimitInfo } from './response-types';
+export interface ClientOptions {
+    /** API key for authentication */
+    apiKey: string;
+    /** Base URL for the API (default: https://api.foru.ms/v1) */
+    baseUrl?: string;
+    /** Maximum number of retry attempts for failed requests (default: 3) */
+    maxRetries?: number;
+    /** Enable automatic retry for rate limits and server errors (default: true) */
+    enableRetry?: boolean;
+}
+/**
+ * Main client for interacting with the Foru.ms API
+ * @example
+ * ```typescript
+ * const client = new ForumClient({
+ *   apiKey: 'your_api_key',
+ *   baseUrl: 'https://api.foru.ms/v1'
+ * });
+ *
+ * // Set user token
+ * client.setToken('user_jwt_token');
+ *
+ * // Use resources
+ * const threads = await client.threads.list();
+ * ```
+ */
 export declare class ForumClient {
     apiKey: string;
     token: string | null;
     baseUrl: string;
+    maxRetries: number;
+    enableRetry: boolean;
+    /** Last known rate limit info */
+    lastRateLimitInfo?: RateLimitInfo;
     auth: AuthResource;
     threads: ThreadsResource;
     posts: PostsResource;
@@ -30,10 +62,37 @@ export declare class ForumClient {
     reports: ReportsResource;
     roles: RolesResource;
     sso: SSOResource;
-    constructor(options: {
-        apiKey: string;
-        baseUrl?: string;
-    });
+    /** Pagination helper for auto-paginating through results */
+    pagination: PaginationHelper;
+    constructor(options: ClientOptions);
+    /**
+     * Make an HTTP request to the API
+     * @param path - API endpoint path
+     * @param options - Fetch options
+     * @returns Promise resolving to the response data
+     * @throws {ForumAPIError} When the API returns an error
+     * @throws {NetworkError} When the network request fails
+     */
     request<T>(path: string, options?: RequestInit): Promise<T>;
+    /**
+     * Set the authentication token for user-scoped requests
+     * @param token - JWT token
+     */
     setToken(token: string): void;
+    /**
+     * Clear the authentication token
+     */
+    clearToken(): void;
+    /**
+     * Check if client is authenticated
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Extract and store rate limit information from response headers
+     */
+    private extractRateLimitInfo;
+    /**
+     * Handle error responses by throwing appropriate error types
+     */
+    private handleErrorResponse;
 }

package/dist/Client.js

@@ -15,13 +15,34 @@ const PrivateMessages_1 = require("./resources/PrivateMessages");
 const Reports_1 = require("./resources/Reports");
 const Roles_1 = require("./resources/Roles");
 const SSO_1 = require("./resources/SSO");
+const errors_1 = require("./errors");
+const utils_1 = require("./utils");
 // Polyfill fetch if needed (e.g. older Node versions)
 const fetch = globalThis.fetch || require('cross-fetch');
+/**
+ * Main client for interacting with the Foru.ms API
+ * @example
+ * ```typescript
+ * const client = new ForumClient({
+ *   apiKey: 'your_api_key',
+ *   baseUrl: 'https://api.foru.ms/v1'
+ * });
+ *
+ * // Set user token
+ * client.setToken('user_jwt_token');
+ *
+ * // Use resources
+ * const threads = await client.threads.list();
+ * ```
+ */
 class ForumClient {
     constructor(options) {
+        var _a, _b;
         this.token = null;
         this.apiKey = options.apiKey;
         this.baseUrl = options.baseUrl || 'https://api.foru.ms/v1';
+        this.maxRetries = (_a = options.maxRetries) !== null && _a !== void 0 ? _a : 3;
+        this.enableRetry = (_b = options.enableRetry) !== null && _b !== void 0 ? _b : true;
         this.auth = new Auth_1.AuthResource(this);
         this.threads = new Threads_1.ThreadsResource(this);
         this.posts = new Posts_1.PostsResource(this);
@@ -36,35 +57,116 @@ class ForumClient {
         this.reports = new Reports_1.ReportsResource(this);
         this.roles = new Roles_1.RolesResource(this);
         this.sso = new SSO_1.SSOResource(this);
+        this.pagination = new utils_1.PaginationHelper();
     }
+    /**
+     * Make an HTTP request to the API
+     * @param path - API endpoint path
+     * @param options - Fetch options
+     * @returns Promise resolving to the response data
+     * @throws {ForumAPIError} When the API returns an error
+     * @throws {NetworkError} When the network request fails
+     */
     async request(path, options = {}) {
-        const headers = {
-            'Content-Type': 'application/json',
-            'x-api-key': this.apiKey,
-            ...options.headers,
+        const makeRequest = async () => {
+            const headers = {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey,
+                ...options.headers,
+            };
+            if (this.token) {
+                headers['Authorization'] = `Bearer ${this.token}`;
+            }
+            let response;
+            try {
+                response = await fetch(`${this.baseUrl}${path}`, {
+                    ...options,
+                    headers,
+                });
+            }
+            catch (error) {
+                throw new errors_1.NetworkError('Network request failed', error);
+            }
+            // Extract rate limit info
+            this.extractRateLimitInfo(response);
+            const contentType = response.headers.get('content-type');
+            let data;
+            if (contentType && contentType.includes('application/json')) {
+                data = await response.json();
+            }
+            else {
+                data = await response.text();
+            }
+            if (!response.ok) {
+                this.handleErrorResponse(response.status, data);
+            }
+            return data;
         };
-        if (this.token) {
-            headers['Authorization'] = `Bearer ${this.token}`;
+        // Apply retry logic if enabled
+        if (this.enableRetry) {
+            return utils_1.RetryHelper.withRetry(makeRequest, this.maxRetries);
         }
-        const response = await fetch(`${this.baseUrl}${path}`, {
-            ...options,
-            headers,
-        });
-        const contentType = response.headers.get('content-type');
-        let data;
-        if (contentType && contentType.includes('application/json')) {
-            data = await response.json();
-        }
-        else {
-            data = await response.text();
-        }
-        if (!response.ok) {
-            throw new Error((data && data.message) || data.error || 'API Error');
-        }
-        return data;
+        return makeRequest();
     }
+    /**
+     * Set the authentication token for user-scoped requests
+     * @param token - JWT token
+     */
     setToken(token) {
         this.token = token;
     }
+    /**
+     * Clear the authentication token
+     */
+    clearToken() {
+        this.token = null;
+    }
+    /**
+     * Check if client is authenticated
+     */
+    isAuthenticated() {
+        return this.token !== null;
+    }
+    /**
+     * Extract and store rate limit information from response headers
+     */
+    extractRateLimitInfo(response) {
+        const limit = response.headers.get('x-ratelimit-limit');
+        const remaining = response.headers.get('x-ratelimit-remaining');
+        const reset = response.headers.get('x-ratelimit-reset');
+        if (limit && remaining && reset) {
+            this.lastRateLimitInfo = {
+                limit: parseInt(limit, 10),
+                remaining: parseInt(remaining, 10),
+                reset: parseInt(reset, 10),
+            };
+        }
+    }
+    /**
+     * Handle error responses by throwing appropriate error types
+     */
+    handleErrorResponse(status, data) {
+        const message = (data && data.message) || data.error || 'API Error';
+        switch (status) {
+            case 401:
+                throw new errors_1.AuthenticationError(message, data);
+            case 403:
+                throw new errors_1.AuthorizationError(message, data);
+            case 404:
+                throw new errors_1.NotFoundError(message, data);
+            case 422:
+                throw new errors_1.ValidationError(message, data);
+            case 429:
+                const retryAfter = data.retryAfter || 60;
+                throw new errors_1.RateLimitError(message, retryAfter, data);
+            case 500:
+            case 502:
+            case 503:
+            case 504:
+                throw new errors_1.ServerError(message, status, data);
+            default:
+                throw new errors_1.ForumAPIError(message, status, data);
+        }
+    }
 }
 exports.ForumClient = ForumClient;