@foru-ms/sdk 1.3.3 → 2.0.3

package/examples/webhooks.ts

@@ -1,176 +0,0 @@
-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/src/Client.ts

@@ -1,233 +0,0 @@
-import { AuthResource } from './resources/Auth';
-import { ThreadsResource } from './resources/Threads';
-import { PostsResource } from './resources/Posts';
-import { UsersResource } from './resources/Users';
-import { TagsResource } from './resources/Tags';
-import { NotificationsResource } from './resources/Notifications';
-import { SearchResource } from './resources/Search';
-import { WebhooksResource } from './resources/Webhooks';
-import { StatsResource } from './resources/Stats';
-import { IntegrationsResource } from './resources/Integrations';
-import { PrivateMessagesResource } from './resources/PrivateMessages';
-import { ReportsResource } from './resources/Reports';
-import { RolesResource } from './resources/Roles';
-import { SSOResource } from './resources/SSO';
-import {
-    ForumAPIError,
-    AuthenticationError,
-    AuthorizationError,
-    NotFoundError,
-    ValidationError,
-    RateLimitError,
-    ServerError,
-    NetworkError
-} from './errors';
-import { PaginationHelper, RetryHelper } from './utils';
-import { RateLimitInfo } from './response-types';
-
-// Polyfill fetch if needed (e.g. older Node versions)
-const fetch = globalThis.fetch || require('cross-fetch');
-
-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 class ForumClient {
-    public apiKey: string;
-    public token: string | null = null;
-    public baseUrl: string;
-    public maxRetries: number;
-    public enableRetry: boolean;
-
-    /** Last known rate limit info */
-    public lastRateLimitInfo?: RateLimitInfo;
-
-    public auth: AuthResource;
-    public threads: ThreadsResource;
-    public posts: PostsResource;
-    public users: UsersResource;
-    public tags: TagsResource;
-    public notifications: NotificationsResource;
-    public search: SearchResource;
-    public webhooks: WebhooksResource;
-    public stats: StatsResource;
-    public integrations: IntegrationsResource;
-    public privateMessages: PrivateMessagesResource;
-    public reports: ReportsResource;
-    public roles: RolesResource;
-    public sso: SSOResource;
-
-    /** Pagination helper for auto-paginating through results */
-    public pagination: PaginationHelper;
-
-    constructor(options: ClientOptions) {
-        this.apiKey = options.apiKey;
-        this.baseUrl = options.baseUrl || 'https://api.foru.ms/v1';
-        this.maxRetries = options.maxRetries ?? 3;
-        this.enableRetry = options.enableRetry ?? true;
-
-        this.auth = new AuthResource(this);
-        this.threads = new ThreadsResource(this);
-        this.posts = new PostsResource(this);
-        this.users = new UsersResource(this);
-        this.tags = new TagsResource(this);
-        this.notifications = new NotificationsResource(this);
-        this.search = new SearchResource(this);
-        this.webhooks = new WebhooksResource(this);
-        this.stats = new StatsResource(this);
-        this.integrations = new IntegrationsResource(this);
-        this.privateMessages = new PrivateMessagesResource(this);
-        this.reports = new ReportsResource(this);
-        this.roles = new RolesResource(this);
-        this.sso = new SSOResource(this);
-
-        this.pagination = new 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
-     */
-    public async request<T>(path: string, options: RequestInit = {}): Promise<T> {
-        const makeRequest = async (): Promise<T> => {
-            const headers: Record<string, string> = {
-                'Content-Type': 'application/json',
-                'x-api-key': this.apiKey,
-                ...(options.headers as Record<string, string>),
-            };
-
-            if (this.token) {
-                headers['Authorization'] = `Bearer ${this.token}`;
-            }
-
-            let response: Response;
-
-            try {
-                response = await fetch(`${this.baseUrl}${path}`, {
-                    ...options,
-                    headers,
-                });
-            } catch (error: any) {
-                throw new 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 as T;
-        };
-
-        // Apply retry logic if enabled
-        if (this.enableRetry) {
-            return RetryHelper.withRetry(makeRequest, this.maxRetries);
-        }
-
-        return makeRequest();
-    }
-
-    /**
-     * Set the authentication token for user-scoped requests
-     * @param token - JWT token
-     */
-    public setToken(token: string): void {
-        this.token = token;
-    }
-
-    /**
-     * Clear the authentication token
-     */
-    public clearToken(): void {
-        this.token = null;
-    }
-
-    /**
-     * Check if client is authenticated
-     */
-    public isAuthenticated(): boolean {
-        return this.token !== null;
-    }
-
-    /**
-     * Extract and store rate limit information from response headers
-     */
-    private extractRateLimitInfo(response: Response): void {
-        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
-     */
-    private handleErrorResponse(status: number, data: any): never {
-        const message = (data && data.message) || data.error || 'API Error';
-
-        switch (status) {
-            case 401:
-                throw new AuthenticationError(message, data);
-            case 403:
-                throw new AuthorizationError(message, data);
-            case 404:
-                throw new NotFoundError(message, data);
-            case 422:
-                throw new ValidationError(message, data);
-            case 429:
-                const retryAfter = data.retryAfter || 60;
-                throw new RateLimitError(message, retryAfter, data);
-            case 500:
-            case 502:
-            case 503:
-            case 504:
-                throw new ServerError(message, status, data);
-            default:
-                throw new ForumAPIError(message, status, data);
-        }
-    }
-}

package/src/errors.ts

@@ -1,95 +0,0 @@
-/**
- * Base error class for all Foru.ms API errors
- */
-export class ForumAPIError extends Error {
-    constructor(
-        message: string,
-        public statusCode: number,
-        public response?: any
-    ) {
-        super(message);
-        this.name = 'ForumAPIError';
-        Object.setPrototypeOf(this, ForumAPIError.prototype);
-    }
-}
-
-/**
- * Error thrown when authentication fails or token is invalid
- */
-export class AuthenticationError extends ForumAPIError {
-    constructor(message: string = 'Authentication failed', response?: any) {
-        super(message, 401, response);
-        this.name = 'AuthenticationError';
-        Object.setPrototypeOf(this, AuthenticationError.prototype);
-    }
-}
-
-/**
- * Error thrown when user doesn't have permission for an action
- */
-export class AuthorizationError extends ForumAPIError {
-    constructor(message: string = 'Permission denied', response?: any) {
-        super(message, 403, response);
-        this.name = 'AuthorizationError';
-        Object.setPrototypeOf(this, AuthorizationError.prototype);
-    }
-}
-
-/**
- * Error thrown when a requested resource is not found
- */
-export class NotFoundError extends ForumAPIError {
-    constructor(message: string = 'Resource not found', response?: any) {
-        super(message, 404, response);
-        this.name = 'NotFoundError';
-        Object.setPrototypeOf(this, NotFoundError.prototype);
-    }
-}
-
-/**
- * Error thrown when request validation fails
- */
-export class ValidationError extends ForumAPIError {
-    constructor(message: string = 'Validation failed', response?: any) {
-        super(message, 422, response);
-        this.name = 'ValidationError';
-        Object.setPrototypeOf(this, ValidationError.prototype);
-    }
-}
-
-/**
- * Error thrown when rate limit is exceeded
- */
-export class RateLimitError extends ForumAPIError {
-    constructor(
-        message: string = 'Rate limit exceeded',
-        public retryAfter?: number,
-        response?: any
-    ) {
-        super(message, 429, response);
-        this.name = 'RateLimitError';
-        Object.setPrototypeOf(this, RateLimitError.prototype);
-    }
-}
-
-/**
- * Error thrown when server encounters an error
- */
-export class ServerError extends ForumAPIError {
-    constructor(message: string = 'Server error', statusCode: number = 500, response?: any) {
-        super(message, statusCode, response);
-        this.name = 'ServerError';
-        Object.setPrototypeOf(this, ServerError.prototype);
-    }
-}
-
-/**
- * Error thrown when network request fails
- */
-export class NetworkError extends Error {
-    constructor(message: string = 'Network request failed', public cause?: Error) {
-        super(message);
-        this.name = 'NetworkError';
-        Object.setPrototypeOf(this, NetworkError.prototype);
-    }
-}

package/src/index.ts

@@ -1,19 +0,0 @@
-export * from './Client';
-export * from './types';
-export * from './errors';
-export * from './response-types';
-export * from './utils';
-export * from './resources/Auth';
-export * from './resources/Threads';
-export * from './resources/Posts';
-export * from './resources/Users';
-export * from './resources/Tags';
-export * from './resources/Notifications';
-export * from './resources/Search';
-export * from './resources/Webhooks';
-export * from './resources/Stats';
-export * from './resources/Integrations';
-export * from './resources/PrivateMessages';
-export * from './resources/Reports';
-export * from './resources/Roles';
-export * from './resources/SSO';

package/src/resources/Auth.ts

@@ -1,84 +0,0 @@
-import { ForumClient } from '../Client';
-import { LoginResponse, RegisterResponse } from '../types';
-
-export class AuthResource {
-    private client: ForumClient;
-
-    constructor(client: ForumClient) {
-        this.client = client;
-    }
-
-    async login(payload: { login: string; password: string; }): Promise<LoginResponse> {
-        const response = await this.client.request<LoginResponse>('/auth/login', {
-            method: 'POST',
-            body: JSON.stringify(payload),
-        });
-
-        if (response.token) {
-            this.client.setToken(response.token);
-        }
-
-        return response;
-    }
-
-    async register(payload: import('../types').RegisterPayload): Promise<RegisterResponse> {
-        const response = await this.client.request<RegisterResponse>('/auth/register', {
-            method: 'POST',
-            body: JSON.stringify(payload),
-        });
-
-        if (response.token) {
-            this.client.setToken(response.token);
-        }
-
-        return response;
-    }
-
-    async me(): Promise<import('../types').User> {
-        return this.client.request<import('../types').User>('/auth/me', {
-            method: 'GET',
-        });
-    }
-
-    async forgotPassword(email: string): Promise<{ resetToken?: string; message?: string }> {
-        return this.client.request<{ resetToken?: string; message?: string }>('/auth/forgot-password', {
-            method: 'POST',
-            body: JSON.stringify({ email }),
-        });
-    }
-
-    async resetPassword(payload: {
-        password: string;
-        oldPassword?: string;
-        email?: string;
-        token?: string;
-    }): Promise<{ message: string }> {
-        const headers: Record<string, string> = {};
-        if (payload.token) {
-            headers['Authorization'] = `Bearer ${payload.token}`;
-        }
-
-        // Remove token from body
-        const { token, ...body } = payload;
-
-        return this.client.request<{ message: string }>('/auth/reset-password', {
-            method: 'POST',
-            headers,
-            body: JSON.stringify(body),
-        });
-    }
-
-    /**
-     * Get account security information for the authenticated user.
-     * This includes IP addresses, registration date, last seen timestamp, and verification status.
-     * Requires authentication token.
-     * 
-     * @returns Promise<SecurityInfo> Security information including IPs and account activity
-     * @throws {ApiError} If not authenticated or user not found
-     */
-    async getSecurity(): Promise<import('../types').SecurityInfo> {
-        return this.client.request<import('../types').SecurityInfo>('/auth/security', {
-            method: 'GET',
-        });
-    }
-}

package/src/resources/Integrations.ts

@@ -1,50 +0,0 @@
-import { ForumClient } from '../Client';
-import { Integration, IntegrationListResponse } from '../types';
-
-export class IntegrationsResource {
-    private client: ForumClient;
-
-    constructor(client: ForumClient) {
-        this.client = client;
-    }
-
-    async list(): Promise<IntegrationListResponse> {
-        return this.client.request<IntegrationListResponse>('/integrations', {
-            method: 'GET',
-        });
-    }
-
-    async create(payload: {
-        type: 'SLACK' | 'DISCORD' | 'SALESFORCE' | 'HUBSPOT' | 'OKTA' | 'AUTH0';
-        name: string;
-        config: any;
-    }): Promise<{ integration: Integration }> {
-        return this.client.request<{ integration: Integration }>('/integrations', {
-            method: 'POST',
-            body: JSON.stringify(payload),
-        });
-    }
-
-    async retrieve(id: string): Promise<{ integration: Integration }> {
-        return this.client.request<{ integration: Integration }>(`/integrations/${id}`, {
-            method: 'GET',
-        });
-    }
-
-    async update(id: string, payload: {
-        name?: string;
-        config?: any;
-        active?: boolean;
-    }): Promise<{ integration: Integration }> {
-        return this.client.request<{ integration: Integration }>(`/integrations/${id}`, {
-            method: 'PATCH',
-            body: JSON.stringify(payload),
-        });
-    }
-
-    async delete(id: string): Promise<{ success: boolean }> {
-        return this.client.request<{ success: boolean }>(`/integrations/${id}`, {
-            method: 'DELETE',
-        });
-    }
-}