@foru-ms/sdk 1.3.2 → 2.0.2

package/README.md

@@ -1,618 +1,268 @@
-# @foru-ms/sdk
-
-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 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
-
-```bash
-npm install @foru-ms/sdk
-# or
-yarn add @foru-ms/sdk
-# or
-pnpm add @foru-ms/sdk
-```
-
-## Quick Start
-
-```typescript
-import { ForumClient } from '@foru-ms/sdk';
-
-const client = new ForumClient({
-  apiKey: 'your_api_key',
-  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!',
-});
-
-// 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', limit: 25 })
-)) {
-  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 with custom page size
-let cursor: string | undefined;
-do {
-  const response = await client.threads.list({ 
-    cursor, 
-    limit: 50 // Request up to 50 items per page (max)
-  });
-  // Process threads...
-  cursor = response.nextThreadCursor;
-} while (cursor);
-```
-
-### Pagination Limit Parameter
-
-All paginated endpoints support an optional `limit` parameter to control page size:
-
-- **Min**: 1
-- **Max**: 50
-- **Default**: 15
-
-```typescript
-// Get 50 threads per page (maximum)
-const threads = await client.threads.list({ limit: 50 });
-
-// Get 10 users per page
-const users = await client.users.list({ limit: 10 });
-
-// Limit applies to all paginated endpoints
-const posts = await client.posts.list({ limit: 25 });
-const notifications = await client.notifications.list({ limit: 30 });
-```
-
-## 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`)
-
-*   `login(payload: { login: string; password: string })`: Login a user. Returns `{ token: string }`.
-*   `register(payload: RegisterPayload)`: Register a new user. Returns `{ user: User, token: string }`. Token is automatically set on the client.
-*   `me()`: Get specific details of the currently authenticated user.
-*   `forgotPassword(email: string)`: Initiate password reset flow.
-*   `resetPassword(payload: { password: string; oldPassword?: string; email?: string; token?: string })`: Reset password using token or old password.
-*   `getSecurity()`: Get account security information for the authenticated user. Returns IP addresses, registration date, last seen timestamp, and verification status. **Requires authentication token.**
-
-### Threads (`client.threads`)
-
-**Thread Management**
-*   `list(params?: { query?: string; tagId?: string; filter?: 'newest' | 'oldest'; type?: 'created' | 'liked' | 'disliked' | 'upvoted' | 'downvoted' | 'subscribed'; cursor?: string; userId?: string; limit?: number })`: List threads with filtering options. `limit` controls page size (1-50, default: 15).
-*   `create(payload: CreateThreadPayload)`: Create a new thread.
-*   `retrieve(id: string)`: Get a thread by ID.
-*   `update(id: string, payload: UpdateThreadPayload)`: Update a thread.
-*   `delete(id: string)`: Delete a thread.
-*   `getPosts(id: string, params?: { query?: string; cursor?: string; filter?: 'newest' | 'oldest'; limit?: number })`: Get posts in a thread.
-
-**Thread Interactions**
-*   `like(id: string, userId?: string, extendedData?: any)`: Like a thread.
-*   `unlike(id: string, userId?: string)`: Unlike a thread.
-*   `getLikes(id: string, params?: { cursor?: string; limit?: number })`: Get users who liked a thread with pagination.
-*   `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; limit?: number })`: Get users who disliked a thread with pagination.
-*   `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; limit?: number })`: Get users who upvoted a thread with pagination.
-*   `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; limit?: number })`: Get users who downvoted a thread with pagination.
-
-**Thread Subscriptions**
-*   `subscribe(id: string, userId?: string, extendedData?: any)`: Subscribe to a thread.
-*   `unsubscribe(id: string, userId?: string)`: Unsubscribe from a thread.
-*   `getSubscribers(id: string, params?: { cursor?: string; limit?: number })`: Get users subscribed to a thread with pagination.
-
-**Thread Polls**
-*   `createPoll(id: string, payload: { title?: string; expiresAt?: string; options: Array<{ title: string; color?: string; extendedData?: any }>, extendedData?: any })`: Create a poll for a thread.
-*   `getPoll(id: string)`: Get poll details and configuration.
-*   `updatePoll(id: string, payload: { title?: string; expiresAt?: string; closed?: boolean; options?: Array<{ id?: string; title?: string; color?: string; extendedData?: any }>; extendedData?: any })`: Update poll configuration.
-*   `deletePoll(id: string)`: Delete a poll from a thread.
-*   `getPollResults(id: string, userId?: string)`: Get poll results with vote counts.
-*   `vote(id: string, userId?: string, optionId: string)`: Cast a vote in a thread poll.
-*   `voteUpdate(id: string, userId?: string, optionId: string)`: Change an existing vote.
-*   `unvote(id: string, userId?: string)`: Remove your vote from a poll.
-
-### Posts (`client.posts`)
-
-**Post Management**
-*   `list(params?: { query?: string; filter?: 'newest' | 'oldest'; type?: 'created' | 'liked' | 'disliked' | 'upvoted' | 'downvoted'; cursor?: string; userId?: string; limit?: number })`: List posts with filtering options. `limit` controls page size (1-50, default: 15).
-*   `create(payload: CreatePostPayload)`: Create a new post/reply.
-*   `retrieve(id: string)`: Get a post by ID.
-*   `update(id: string, payload: UpdatePostPayload)`: Update a post.
-*   `delete(id: string, payload?: { userId?: string })`: Delete a post.
-*   `getChildren(id: string, params?: { query?: string; cursor?: string; filter?: 'newest' | 'oldest'; limit?: number })`: Get child posts (nested replies).
-
-**Post Interactions**
-*   `like(id: string, userId?: string, extendedData?: any)`: Like a post.
-*   `unlike(id: string, userId?: string)`: Unlike a post.
-*   `getLikes(id: string, params?: { cursor?: string; limit?: number })`: Get users who liked a post with pagination.
-*   `dislike(id: string, userId?: string, extendedData?: any)`: Dislike a post.
-*   `undislike(id: string, userId?: string)`: Remove dislike from a post.
-*   `getDislikes(id: string, params?: { cursor?: string; limit?: number })`: Get users who disliked a post with pagination.
-*   `upvote(id: string, userId?: string, extendedData?: any)`: Upvote a post.
-*   `unupvote(id: string, userId?: string)`: Remove upvote from a post.
-*   `getUpvotes(id: string, params?: { cursor?: string; limit?: number })`: Get users who upvoted a post with pagination.
-*   `downvote(id: string, userId?: string, extendedData?: any)`: Downvote a post.
-*   `undownvote(id: string, userId?: string)`: Remove downvote from a post.
-*   `getDownvotes(id: string, params?: { cursor?: string; limit?: number })`: Get users who downvoted a post with pagination.
-
-### Users (`client.users`)
-
-*   `list(params?: { query?: string; filter?: 'newest' | 'oldest'; cursor?: string; limit?: number })`: List users. `limit` controls page size (1-50, default: 15).
-*   `retrieve(userId: string)`: Get user by ID.
-*   `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'; limit?: number })`: Get all threads created by a user.
-*   `getPosts(id: string, params?: { query?: string; cursor?: string; filter?: 'newest' | 'oldest'; limit?: number })`: Get all posts created by a user.
-*   `getFollowers(id: string, params?: { query?: string; cursor?: string; filter?: 'newest' | 'oldest'; limit?: number })`: Get user's followers.
-*   `getFollowing(id: string, params?: { query?: string; cursor?: string; filter?: 'newest' | 'oldest'; limit?: number })`: Get who a user follows.
-*   `follow(id: string, followerId?: string, extendedData?: any)`: Follow a user.
-*   `unfollow(id: string, followerId?: string)`: Unfollow a user.
-
-
-### Tags (`client.tags`)
-
-*   `list(params?: { query?: string; cursor?: string; limit?: number })`: List all tags. `limit` controls page size (1-50, default: 15).
-*   `listSubscribed(params?: { userId?: string; query?: string; cursor?: string; limit?: number })`: List tags a user is subscribed to.
-*   `create(payload: { name: string; description?: string; color?: string; extendedData?: Record<string, any> })`: Create a tag.
-*   `retrieve(id: string, params?: { userId?: string })`: Get a tag with optional user context.
-*   `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'; limit?: number })`: 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; limit?: number })`: Get users subscribed to a tag with pagination.
-
-
-### Notifications (`client.notifications`)
-
-*   `list(params?: { userId?: string; status?: string; filter?: 'newest' | 'oldest'; cursor?: string; limit?: number })`: List notifications for a user. `limit` controls page size (1-50, default: 15).
-*   `create(payload: { threadId?: string; postId?: string; privateMessageId?: string; notifierId?: string; notifiedId: string; type: string; description?: string; extendedData?: Record<string, any> })`: Create a notification manually.
-*   `retrieve(id: string, userId?: string)`: Get a notification by ID.
-*   `update(id: string, payload: { userId?: string; status?: string })`: Update a notification's status.
-*   `delete(id: string, userId?: string)`: Delete a notification.
-*   `markAllAsRead(userId?: string, status?: string)`: Bulk update status for all of a user's notifications. Default status is `'read'`.
-
-### Search (`client.search`)
-
-*   `search(params: { query: string; type: 'threads' | 'posts' | 'users' | 'tags'; cursor?: string; limit?: number })`: Polymorphic search. `limit` controls page size (1-50, default: 15).
-
-### Webhooks (`client.webhooks`)
-
-*   `list()`: List all webhooks for your instance.
-*   `create(payload: { name: string; url: string; events: string[] })`: Create a new webhook subscription.
-*   `retrieve(id: string)`: Get a webhook by ID.
-*   `update(id: string, payload: { name?: string; url?: string; events?: string[]; active?: boolean })`: Update a webhook configuration.
-*   `delete(id: string)`: Delete a webhook.
-*   `getDeliveries(id: string, params?: { cursor?: string; limit?: number })`: Get webhook delivery history with pagination. Track successful and failed deliveries. `limit` controls page size (1-50, default: 15).
-*   `verifySignature(payload: any, signature: string, timestamp: string, secret: string, maxAge?: number)`: Verify webhook signature for security. Uses HMAC-SHA256. Default maxAge is 5 minutes to prevent replay attacks.
-
-### Stats (`client.stats`)
-
-*   `get(params?: { filter?: string; threadCursor?: string; postCursor?: string; ... })`: Get instance statistics.
-
-### Integrations (`client.integrations`)
-
-*   `list()`: Get all configured integrations for your instance.
-*   `create(payload: { type: 'SLACK' | 'DISCORD' | 'SALESFORCE' | 'HUBSPOT' | 'OKTA' | 'AUTH0'; name: string; config: any })`: Configure a new integration (Slack, Discord, CRM, or SSO).
-*   `retrieve(id: string)`: Get integration details by ID.
-*   `update(id: string, payload: { name?: string; type?: string; enabled?: boolean; config?: any })`: Update an integration configuration.
-*   `delete(id: string)`: Remove an integration.
-*   `test(integrationId: string)`: Send a test message to verify integration is working correctly.
-*   `oauthAuthorize(provider: 'hubspot' | 'salesforce')`: Initiate OAuth flow for a provider (redirects to provider).
-*   `oauthCallback(provider: string, code: string, state: string)`: Handle OAuth callback from provider.
-
-### Private Messages (`client.privateMessages`)
-
-*   `list(params?: { query?: string; userId?: string; filter?: 'newest' | 'oldest'; cursor?: string; limit?: number })`: List private messages. `limit` controls page size (1-50, default: 15).
-*   `create(payload: { title?: string; body: string; recipientId: string; senderId?: string; extendedData?: Record<string, any> })`: Send a new private message.
-*   `retrieve(id: string, userId?: string)`: Get a message by ID.
-*   `reply(id: string, payload: { body: string; senderId?: string; title?: string; extendedData?: Record<string, any> })`: Reply to a message thread.
-*   `update(id: string, payload: { status?: string; body?: string; extendedData?: Record<string, any> })`: Update a message (only sender can update).
-*   `delete(id: string)`: Delete a message (participants can delete).
-
-### Reports (`client.reports`)
-
-*   `list(params?: { reporterId?: string; reportedId?: string; status?: string; cursor?: string; filter?: 'newest' | 'oldest'; limit?: number })`: List reports with filtering options. `limit` controls page size (1-50, default: 15).
-*   `create(payload: { reporterId?: string; reportedId?: string; threadId?: string; postId?: string; privateMessageId?: string; type?: string; description?: string; extendedData?: Record<string, any> })`: Submit a new report.
-*   `retrieve(id: string)`: Get a report by ID.
-*   `update(id: string, payload: { threadId?: string; postId?: string; privateMessageId?: string; reportedId?: string; reporterId?: string; type?: string; description?: string; status?: string; extendedData?: Record<string, any> })`: Update report details (full update).
-*   `updateStatus(id: string, status?: string)`: Update status of a report (partial update).
-*   `batchUpdate(payload: { reportIds: string[]; status?: string })`: Bulk update status for multiple reports.
-*   `delete(id: string)`: Delete a report.
-
-### Roles (`client.roles`)
-
-*   `list(params?: { filter?: 'newest' | 'oldest'; cursor?: string; limit?: number })`: List user roles. `limit` controls page size (1-50, default: 15).
-*   `create(payload: { name: string; description?: string; color?: string; extendedData?: Record<string, any> })`: Create a new role.
-*   `retrieve(id: string)`: Get a role by ID.
-*   `update(id: string, payload: { name?: string; description?: string; color?: string; extendedData?: Record<string, any> })`: Update a role.
-*   `delete(id: string)`: Delete a role.
-
-### SSO (`client.sso`)
-
-*   `list()`: List all SSO providers configured for your instance.
-*   `create(payload: { provider: 'OKTA' | 'AUTH0' | 'SAML'; domain: string; config: any })`: Configure a new SSO provider.
-*   `retrieve(id: string)`: Get SSO provider details by ID.
-*   `update(id: string, payload: { name?: string; type?: 'SAML' | 'OIDC' | 'OAUTH2'; enabled?: boolean; config?: any })`: Update SSO configuration.
-*   `delete(id: string)`: Remove an SSO provider.
-
-## Types
-
-Import all available interfaces and types directly from the package:
-
-```typescript
-import { 
-  // Auth Types
-  RegisterPayload,
-  User,
-  LoginResponse,
-  RegisterResponse,
-  SecurityInfo,
-  
-  // Thread Types
-  Thread,
-  CreateThreadPayload,
-  UpdateThreadPayload,
-  ThreadListResponse,
-  ThreadFilter,
-  
-  // Post Types
-  Post,
-  CreatePostPayload,
-  UpdatePostPayload,
-  PostListResponse,
-  
-  // Tag Types
-  Tag,
-  TagListResponse,
-  
-  // User Types
-  UserListResponse,
-  
-  // Notification Types
-  Notification,
-  NotificationListResponse,
-  
-  // Search Types
-  SearchResponse,
-  
-  // Webhook Types
-  Webhook,
-  WebhookListResponse,
-  
-  // Stats Types
-  StatsResponse,
-  
-  // Integration Types
-  Integration,
-  IntegrationListResponse,
-  
-  // Private Message Types
-  PrivateMessage,
-  PrivateMessageListResponse,
-  
-  // Report Types
-  Report,
-  ReportListResponse,
-  
-  // Role Types
-  Role,
-  RoleListResponse,
-  
-  // SSO Types
-  SSOProvider,
-  SSOProviderListResponse,
-  
-  // Utility Types
-  PaginatedResponse,
-  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';
-```
-
-## Advanced Usage
-
-### Custom Client Options
-
-```typescript
-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
-
-- Support: https://foru.ms/support
-- Documentation: https://foru.ms/docs
-- Issues: https://github.com/foru-ms/sdk/issues
-
-## Changelog
-
-### v1.3.2
-- Fixed issue with optional parameters not being optional in typescript
-
-### v1.3.1
-- Updated Notifications, PrivateMessages, Reports to use `status` (string) instead of `read` (boolean)
-
-### v1.3.0
-- Added Auth resource, authentication example, and related types
-
-### v1.2.8
-- Added Poll resource for poll management
-
-### v1.2.7
-- Fixed issue with optional parameters not being optional in typescript
-
-### v1.2.6
-- Fixed issue with optional parameters not being optional in typescript
-
-### v1.2.5
-- Added optional `userId` parameter to methods that accept it
-
-### v1.2.4
-- Pagination Enhancement: Added configurable `limit` query parameter to all paginated endpoints
-  - Allows clients to control page size (min: 1, max: 50, default: 15)
-  - Applied to all list operations across Threads, Posts, Users, Tags, Notifications, Private Messages, Reports, Roles, Search, and Webhooks
-  - Updated documentation with usage examples and parameter specifications
-  - Improves API flexibility for different use cases (mobile, desktop, batch processing)
-
-### v1.2.3
-- README documentation update
-- Enhanced all API reference sections with:
-  - Better organization with categorized subsections (Management, Interactions, Subscriptions, Polls)
-  - Corrected optional vs required parameters throughout
-  - Added missing methods documentation (poll CRUD, webhook deliveries, integration OAuth, etc.)
-  - Improved clarity and consistency across all resource sections
-  - Added detailed descriptions for complex operations
-
-### v1.2.2
-- Added Auth resource with authentication methods
-- Introduced comprehensive SDK type definitions
-- Updated documentation
-
-### v1.2.1
-- README.md formatting and updates
-
-### 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 new endpoints
-- Enhanced documentation and examples
-
-### v1.1.0
-- Added new endpoints
-- Enhanced documentation and examples
-
-### v1.0.0
-- Initial SDK release with core functionality
-
-## License
-
-MIT
+# Foru.ms TypeScript Library
+
+![](https://foru.ms/images/cover.png)
+
+[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2Fforu-ms%2Fsdk)
+[![npm shield](https://img.shields.io/npm/v/@foru-ms/sdk)](https://www.npmjs.com/package/@foru-ms/sdk)
+
+The Foru.ms TypeScript library provides convenient access to the Foru.ms APIs from TypeScript.
+
+## Table of Contents
+
+- [Documentation](#documentation)
+- [Installation](#installation)
+- [Reference](#reference)
+- [Usage](#usage)
+- [Request and Response Types](#request-and-response-types)
+- [Exception Handling](#exception-handling)
+- [Advanced](#advanced)
+  - [Additional Headers](#additional-headers)
+  - [Additional Query String Parameters](#additional-query-string-parameters)
+  - [Retries](#retries)
+  - [Timeouts](#timeouts)
+  - [Aborting Requests](#aborting-requests)
+  - [Access Raw Response Data](#access-raw-response-data)
+  - [Logging](#logging)
+  - [Runtime Compatibility](#runtime-compatibility)
+
+## Documentation
+
+API reference documentation is available [here](https://foru.ms/docs/api-reference).
+
+## Installation
+
+```sh
+npm i -s @foru-ms/sdk
+```
+
+## Reference
+
+A full reference for this library is available [here](https://github.com/foru-ms/sdk/blob/HEAD/./reference.md).
+
+## Usage
+
+Instantiate and use the client with the following:
+
+```typescript
+import { ForumClient } from "@foru-ms/sdk";
+
+const client = new ForumClient({ apiKey: "YOUR_API_KEY" });
+await client.auth.register({
+    username: "username",
+    email: "email",
+    password: "password"
+});
+```
+
+## Request and Response Types
+
+The SDK exports all request and response types as TypeScript interfaces. Simply import them with the
+following namespace:
+
+```typescript
+import { Forum } from "@foru-ms/sdk";
+
+const request: Forum.PostAuthRegisterRequest = {
+    ...
+};
+```
+
+## Exception Handling
+
+When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error
+will be thrown.
+
+```typescript
+import { ForumError } from "@foru-ms/sdk";
+
+try {
+    await client.auth.register(...);
+} catch (err) {
+    if (err instanceof ForumError) {
+        console.log(err.statusCode);
+        console.log(err.message);
+        console.log(err.body);
+        console.log(err.rawResponse);
+    }
+}
+```
+
+## Advanced
+
+### Additional Headers
+
+If you would like to send additional headers as part of the request, use the `headers` request option.
+
+```typescript
+import { ForumClient } from "@foru-ms/sdk";
+
+const client = new ForumClient({
+    ...
+    headers: {
+        'X-Custom-Header': 'custom value'
+    }
+});
+
+const response = await client.auth.register(..., {
+    headers: {
+        'X-Custom-Header': 'custom value'
+    }
+});
+```
+
+### Additional Query String Parameters
+
+If you would like to send additional query string parameters as part of the request, use the `queryParams` request option.
+
+```typescript
+const response = await client.auth.register(..., {
+    queryParams: {
+        'customQueryParamKey': 'custom query param value'
+    }
+});
+```
+
+### Retries
+
+The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long
+as the request is deemed retryable and the number of retry attempts has not grown larger than the configured
+retry limit (default: 2).
+
+A request is deemed retryable when any of the following HTTP status codes is returned:
+
+- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)
+- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)
+- [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) (Internal Server Errors)
+
+Use the `maxRetries` request option to configure this behavior.
+
+```typescript
+const response = await client.auth.register(..., {
+    maxRetries: 0 // override maxRetries at the request level
+});
+```
+
+### Timeouts
+
+The SDK defaults to a 60 second timeout. Use the `timeoutInSeconds` option to configure this behavior.
+
+```typescript
+const response = await client.auth.register(..., {
+    timeoutInSeconds: 30 // override timeout to 30s
+});
+```
+
+### Aborting Requests
+
+The SDK allows users to abort requests at any point by passing in an abort signal.
+
+```typescript
+const controller = new AbortController();
+const response = await client.auth.register(..., {
+    abortSignal: controller.signal
+});
+controller.abort(); // aborts the request
+```
+
+### Access Raw Response Data
+
+The SDK provides access to raw response data, including headers, through the `.withRawResponse()` method.
+The `.withRawResponse()` method returns a promise that results to an object with a `data` and a `rawResponse` property.
+
+```typescript
+const { data, rawResponse } = await client.auth.register(...).withRawResponse();
+
+console.log(data);
+console.log(rawResponse.headers['X-My-Header']);
+```
+
+### Logging
+
+The SDK supports logging. You can configure the logger by passing in a `logging` object to the client options.
+
+```typescript
+import { ForumClient, logging } from "@foru-ms/sdk";
+
+const client = new ForumClient({
+    ...
+    logging: {
+        level: logging.LogLevel.Debug, // defaults to logging.LogLevel.Info
+        logger: new logging.ConsoleLogger(), // defaults to ConsoleLogger
+        silent: false, // defaults to true, set to false to enable logging
+    }
+});
+```
+The `logging` object can have the following properties:
+- `level`: The log level to use. Defaults to `logging.LogLevel.Info`.
+- `logger`: The logger to use. Defaults to a `logging.ConsoleLogger`.
+- `silent`: Whether to silence the logger. Defaults to `true`.
+
+The `level` property can be one of the following values:
+- `logging.LogLevel.Debug`
+- `logging.LogLevel.Info`
+- `logging.LogLevel.Warn`
+- `logging.LogLevel.Error`
+
+To provide a custom logger, you can pass in an object that implements the `logging.ILogger` interface.
+
+<details>
+<summary>Custom logger examples</summary>
+
+Here's an example using the popular `winston` logging library.
+```ts
+import winston from 'winston';
+
+const winstonLogger = winston.createLogger({...});
+
+const logger: logging.ILogger = {
+    debug: (msg, ...args) => winstonLogger.debug(msg, ...args),
+    info: (msg, ...args) => winstonLogger.info(msg, ...args),
+    warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
+    error: (msg, ...args) => winstonLogger.error(msg, ...args),
+};
+```
+
+Here's an example using the popular `pino` logging library.
+
+```ts
+import pino from 'pino';
+
+const pinoLogger = pino({...});
+
+const logger: logging.ILogger = {
+  debug: (msg, ...args) => pinoLogger.debug(args, msg),
+  info: (msg, ...args) => pinoLogger.info(args, msg),
+  warn: (msg, ...args) => pinoLogger.warn(args, msg),
+  error: (msg, ...args) => pinoLogger.error(args, msg),
+};
+```
+</details>
+
+
+### Runtime Compatibility
+
+
+The SDK works in the following runtimes:
+
+
+
+- Node.js 18+
+- Vercel
+- Cloudflare Workers
+- Deno v1.25+
+- Bun 1.0+
+- React Native
+
+### Customizing Fetch Client
+
+The SDK provides a way for you to customize the underlying HTTP client / Fetch function. If you're running in an
+unsupported environment, this provides a way for you to break glass and ensure the SDK works.
+
+```typescript
+import { ForumClient } from "@foru-ms/sdk";
+
+const client = new ForumClient({
+    ...
+    fetcher: // provide your implementation here
+});
+```