{"id":29136312,"url":"https://github.com/fastcomments/fastcomments-sdk-js","last_synced_at":"2026-01-08T19:14:36.826Z","repository":{"id":301454288,"uuid":"1009191811","full_name":"FastComments/fastcomments-sdk-js","owner":"FastComments","description":"The FastComments JS/TS SDK","archived":false,"fork":false,"pushed_at":"2025-06-27T00:33:00.000Z","size":107,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-27T00:44:40.367Z","etag":null,"topics":["api","commenting-system","nodejs","typescript"],"latest_commit_sha":null,"homepage":"https://docs.fastcomments.com/guide-api.html","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FastComments.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-26T18:14:46.000Z","updated_at":"2025-06-27T00:33:03.000Z","dependencies_parsed_at":"2025-06-27T00:44:44.291Z","dependency_job_id":"b6183109-cf66-48f9-91f1-6496b8572a99","html_url":"https://github.com/FastComments/fastcomments-sdk-js","commit_stats":null,"previous_names":["fastcomments/fastcomments-sdk-js"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/FastComments/fastcomments-sdk-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FastComments%2Ffastcomments-sdk-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FastComments%2Ffastcomments-sdk-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FastComments%2Ffastcomments-sdk-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FastComments%2Ffastcomments-sdk-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FastComments","download_url":"https://codeload.github.com/FastComments/fastcomments-sdk-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FastComments%2Ffastcomments-sdk-js/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262762465,"owners_count":23360330,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","commenting-system","nodejs","typescript"],"created_at":"2025-06-30T11:07:38.476Z","updated_at":"2026-01-08T19:14:36.821Z","avatar_url":"https://github.com/FastComments.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FastComments Node.js/TypeScript SDK\n\nOfficial Node.js and TypeScript SDK for the FastComments API. Build secure and scalable backend applications that interact with FastComments, or build reactive client applications.\n\n## Installation\n\n```bash\nnpm install fastcomments-sdk\n```\n\n## API Documentation\n\nFull API reference: [docs/api/README.md](docs/api/README.md)\n\n## Browser vs Server Compatibility\n\nThis SDK uses **dual entry points** to ensure optimal compatibility and prevent runtime errors:\n\n- **`fastcomments-sdk/browser`** - Browser-safe version with native `fetch`\n- **`fastcomments-sdk/server`** - Full Node.js version with SSO support\n- **`fastcomments-sdk`** (default) - Types only, safe to import anywhere\n\n## Usage\n\nThis SDK provides separate entry points for browser and server environments to ensure optimal compatibility and security:\n\n### Browser Usage (Client-Side)\n\nFor browser/frontend applications, use the browser-safe export that excludes Node.js dependencies:\n\n```typescript\n// Browser-safe import (no Node.js dependencies)\nimport { createFastCommentsBrowserSDK } from 'fastcomments-sdk/browser';\n\n// Create browser SDK instance\nconst sdk = createFastCommentsBrowserSDK({\n  basePath: 'https://fastcomments.com' // optional, defaults to https://fastcomments.com\n});\n\n// Use public APIs (no API key needed - safe for browsers)\nconst comments = await sdk.publicApi.getCommentsPublic({ \n  tenantId: 'your-tenant-id',\n  urlId: 'page-url-id'\n});\n```\n\n### Server Usage (Node.js)\n\nFor server/backend applications, use the full SDK with SSO and authentication features:\n\n```typescript\n// Server-side import (includes SSO and designed to work with NodeJS)\nimport { createFastCommentsSDK } from 'fastcomments-sdk/server';\n\n// Create server SDK instance\nconst sdk = createFastCommentsSDK({\n  apiKey: 'your-api-key', // Keep this secret on the server!\n  basePath: 'https://fastcomments.com' // optional, defaults to https://fastcomments.com\n});\n\n// Use secured APIs with your API key\nconst comments = await sdk.defaultApi.getComments({ \n  tenantId: 'your-tenant-id',\n  urlId: 'page-url-id'\n});\n```\n\n### Types Only Import\n\nIf you only need TypeScript types (no runtime code), use the default import:\n\n```typescript\n// Types only (no runtime dependencies - safe everywhere)\nimport type { \n  PublicComment, \n  CreateCommentParams, \n  GetCommentsPublic200Response \n} from 'fastcomments-sdk';\n```\n\n### Using Individual API Classes\n\n#### Browser Environment\n\n```typescript\nimport { PublicApi, Configuration } from 'fastcomments-sdk/browser';\n\nconst config = new Configuration({\n  basePath: 'https://fastcomments.com'\n});\n\nconst publicApi = new PublicApi(config);\n```\n\n#### Server Environment  \n\n```typescript\nimport { DefaultApi, PublicApi, Configuration } from 'fastcomments-sdk/server';\n\nconst config = new Configuration({\n  apiKey: 'your-api-key',\n  basePath: 'https://fastcomments.com'\n});\n\nconst defaultApi = new DefaultApi(config);\nconst publicApi = new PublicApi(config);\n```\n\n## Public vs Secured APIs\n\nThe SDK provides three main API classes:\n\n- **`DefaultApi`** - Secured endpoints that require your API key for authentication. Use these for server-side operations.\n- **`PublicApi`** - Public endpoints that can be accessed without an API key. These can be called directly from browsers/mobile devices/etc.\n- **`HiddenApi`** - Internal/admin endpoints for advanced use cases.\n\n### Example: Using Public API (browser-safe)\n\n```typescript\nimport { PublicApi } from 'fastcomments-sdk/browser';\n\nconst publicApi = new PublicApi();\n\n// Get comments for a page (no API key required)\nconst response = await publicApi.getCommentsPublic({\n  tenantId: 'your-tenant-id',\n  urlId: 'page-url-id'\n});\n```\n\n### Example: Using Default API (server-side only)\n\n```typescript\nimport { DefaultApi, Configuration } from 'fastcomments-sdk/server';\n\nconst config = new Configuration({\n  apiKey: 'your-api-key' // Keep this secret!\n});\nconst defaultApi = new DefaultApi(config);\n\n// Get comments with full admin access\nconst response = await defaultApi.getComments({\n  tenantId: 'your-tenant-id',\n  urlId: 'page-url-id'\n});\n```\n\n## SSO (Single Sign-On) Integration\n\nFastComments supports SSO to integrate with your existing user authentication system. **SSO functionality is only available in the server export** since it requires Node.js crypto features.\n\n### Simple SSO (Server-Side Only)\n\nSimple SSO should be generated server-side and sent to the client:\n\n```typescript\n// Server-side code (Node.js/backend)\nimport { FastCommentsSSO, PublicApi } from 'fastcomments-sdk/server';\n\n// Create simple SSO using the built-in helper  \nconst userData = {\n  username: 'john_doe',\n  email: 'john@example.com',\n  displayName: 'John Doe',\n  avatar: 'https://example.com/avatar.jpg'\n};\n\nconst sso = FastCommentsSSO.createSimple(userData, {\n  loginURL: '/login',\n  logoutURL: '/logout'\n});\n\nconst ssoToken = sso.createToken();\n\n// Send ssoToken to your client-side code\n// Client-side code can then use this token with the browser SDK\n```\n\n### Secure SSO (Server-Side, Recommended)\n\nSecure SSO should be implemented server-side and provides better security:\n\n```typescript\n// Server-side code (Node.js/backend)\nimport { FastCommentsSSO, PublicApi } from 'fastcomments-sdk/server';\n\n// Create secure SSO using the built-in helper\nconst userData = {\n  id: 'user-123',\n  email: 'john@example.com',\n  username: 'john_doe',\n  displayName: 'John Doe',\n  avatar: 'https://example.com/avatar.jpg',\n  isAdmin: false,\n  isModerator: false\n};\n\nconst sso = FastCommentsSSO.createSecure('your-api-key', userData, {\n  loginURL: '/login',\n  logoutURL: '/logout'\n});\n\nconst ssoConfig = sso.prepareToSend();\n\n// Use with API calls on the server\nconst publicApi = new PublicApi();\nconst response = await publicApi.getCommentsPublic({\n  tenantId: 'your-tenant-id',\n  urlId: 'page-url-id',\n  sso: JSON.stringify(ssoConfig)\n});\n\n// Or send ssoConfig to client for browser usage\n```\n\n### Using SSO from Browser (with Server-Generated Token)\n\n```typescript\n// Client-side code (browser)\nimport { PublicApi } from 'fastcomments-sdk/browser';\n\n// Get SSO token from your server endpoint\nconst ssoToken = await fetch('/api/sso-token').then(r =\u003e r.json());\n\nconst publicApi = new PublicApi();\nconst response = await publicApi.getCommentsPublic({\n  tenantId: 'your-tenant-id',\n  urlId: 'page-url-id',\n  sso: ssoToken // Use the server-generated SSO token\n});\n```\n\n### SSO with Comment Creation\n\n```typescript\n// Server-side: Create SSO and comment\nimport { FastCommentsSSO, PublicApi } from 'fastcomments-sdk/server';\n\nconst sso = FastCommentsSSO.createSecure('your-api-key', userData);\nconst ssoConfig = sso.prepareToSend();\n\nconst response = await publicApi.createCommentPublic({\n  tenantId: 'your-tenant-id',\n  urlId: 'page-url-id',\n  broadcastId: 'unique-broadcast-id',\n  commentData: {\n    comment: 'This is my comment',\n    date: Date.now(),\n    commenterName: 'John Doe',\n    url: 'https://example.com/page',\n    urlId: 'page-url-id'\n  },\n  sso: JSON.stringify(ssoConfig)\n});\n```\n\n## Common Use Cases\n\n### Getting Comments for a Page\n\n```typescript\nconst comments = await sdk.publicApi.getCommentsPublic({\n  tenantId: 'your-tenant-id',\n  urlId: 'article-123'\n});\n```\n\n### Creating a Comment\n\n```typescript\nconst newComment = await sdk.publicApi.createCommentPublic({\n  createCommentParams: {\n    tenantId: 'your-tenant-id',\n    urlId: 'article-123',\n    comment: 'Great article!',\n    commenterName: 'John Doe',\n    commenterEmail: 'john@example.com'\n  }\n});\n```\n\n### Voting on a Comment\n\n```typescript\nconst voteResponse = await sdk.publicApi.voteComment({\n  voteBodyParams: {\n    commentId: 'comment-id',\n    direction: 1 // 1 for upvote, -1 for downvote\n  }\n});\n```\n\n### User Management (Requires API Key)\n\n```typescript\n// Search for users (requires DefaultApi)\nconst users = await sdk.defaultApi.searchUsers({\n  tenantId: 'your-tenant-id',\n  urlId: 'page-id',\n  usernameStartsWith: 'john'\n});\n```\n\n## Live Events (Real-time Updates)\n\nSubscribe to live events to get real-time updates for comments, votes, and other activities.\n\n### Page-Level Events\n\nListen for live events on a specific page (comments, votes, etc.):\n\n```typescript\nimport { subscribeToChanges, LiveEvent, LiveEventType } from 'fastcomments-sdk/browser';\n\nconst config = {\n  tenantId: 'your-tenant-id',\n  urlId: 'page-url-id',\n};\n\n// Subscribe to live events for a page\nconst subscription = subscribeToChanges(\n  config,\n  'your-tenant-id', // tenantIdWS\n  'page-url-id',    // urlIdWS  \n  'user-session-id', // userIdWS (get this from getComments response)\n  (event: LiveEvent) =\u003e {\n    console.log('Live event received:', event);\n    \n    switch (event.type) {\n      case LiveEventType.new_comment:\n        console.log('New comment:', event.comment);\n        // Update your UI with the new comment\n        break;\n      case LiveEventType.new_vote:\n        console.log('New vote:', event.vote);\n        // Update vote counts in your UI\n        break;\n      case LiveEventType.updated_comment:\n        console.log('Comment updated:', event.comment);\n        break;\n      default:\n        console.log('Other event type:', event.type);\n    }\n    \n    return true; // Return true if event was handled\n  },\n  (isConnected: boolean) =\u003e {\n    console.log('Connection status:', isConnected ? 'Connected' : 'Disconnected');\n  }\n);\n\n// Close the subscription when done\nsubscription.close();\n```\n\n### Subscribe to User Events\n\nListen for user-specific events (notifications, mentions, etc.):\n\n```typescript\nimport { subscribeToUserFeed, LiveEvent, LiveEventType } from 'fastcomments-sdk/browser';\n\nconst userConfig = {\n  userIdWS: 'user-session-id', // Get this from getComments response\n};\n\n// Subscribe to user's personal feed\nconst userSubscription = subscribeToUserFeed(\n  userConfig,\n  (event: LiveEvent) =\u003e {\n    console.log('User event received:', event);\n    \n    switch (event.type) {\n      case LiveEventType.notification:\n        console.log('New notification:', event.notification);\n        // Show notification in your UI\n        break;\n      case LiveEventType.notification_update:\n        console.log('Notification updated:', event.notification);\n        break;\n      default:\n        console.log('Other user event:', event.type);\n    }\n    \n    return true;\n  },\n  (isConnected: boolean) =\u003e {\n    console.log('User feed connection:', isConnected ? 'Connected' : 'Disconnected');\n  }\n);\n\n// Close when done\nuserSubscription.close();\n```\n\n### Getting userIdWS\n\nThe `userIdWS` parameter is required for live events and can be obtained from API responses:\n\n```typescript\nconst response = await sdk.publicApi.getCommentsPublic({\n  tenantId: 'your-tenant-id',\n  urlId: 'page-id'\n});\n\n// Extract userIdWS from the response\nconst userIdWS = response.data?.userSessionInfo?.userIdWS;\n\nif (userIdWS) {\n  // Now you can subscribe to live events\n  const subscription = subscribeToChanges(config, tenantIdWS, urlIdWS, userIdWS, handleEvent);\n}\n```\n\n## Broadcast IDs\n\nYou'll see you're supposed to pass a `broadcastId` in some API calls. When you receive events, you'll get this ID back, so you know to ignore the event if you plan to optimistically apply changes on the client (which you'll probably want to do since it offers the best experience). Pass a UUID here. The ID should be unique enough to not occur twice in a browser session.\n\n```typescript\nimport { v4 as uuidv4 } from 'uuid';\n\nconst response = await sdk.publicApi.createCommentPublic({\n  createCommentParams: {\n    tenantId: 'your-tenant-id',\n    urlId: 'page-id',\n    comment: 'My comment',\n    broadcastId: uuidv4() // Unique ID for this operation\n  }\n});\n```\n\n## Error Handling\n\n```typescript\ntry {\n  const comments = await sdk.publicApi.getCommentsPublic({\n    tenantId: 'your-tenant-id',\n    urlId: 'page-id'\n  });\n} catch (error) {\n  if (error.response?.status === 404) {\n    console.log('Page not found');\n  } else {\n    console.error('API Error:', error.message);\n  }\n}\n```\n\n## TypeScript Support\n\nThe SDK is written in TypeScript and provides complete type definitions for all API methods and response models:\n\n```typescript\n// Import types from the default export (safe everywhere)\nimport type { \n  PublicComment, \n  CreateCommentParams, \n  GetCommentsPublic200Response \n} from 'fastcomments-sdk';\n\n// Use with browser SDK\nimport { createFastCommentsBrowserSDK } from 'fastcomments-sdk/browser';\n\nconst sdk = createFastCommentsBrowserSDK();\nconst response: GetCommentsPublic200Response = await sdk.publicApi.getCommentsPublic({\n  tenantId: 'your-tenant-id',\n  urlId: 'page-id'\n});\n\nconst comments: PublicComment[] = response.comments || [];\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastcomments%2Ffastcomments-sdk-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffastcomments%2Ffastcomments-sdk-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastcomments%2Ffastcomments-sdk-js/lists"}