@bluecopa/core 0.1.7 → 0.1.8

package/README.md

@@ -20,9 +20,15 @@ The core package provides essential API utilities and functions for data managem
     - [Workbook Module](#workbook-module)
     - [Workflow Module](#workflow-module)
     - [Worksheet Module](#worksheet-module)
+  - [WebSocket Connection](#websocket-connection)
+    - [WebSocket Factory](#websocket-factory)
+    - [WebSocket Provider Interface](#websocket-provider-interface)
+    - [WebSocket Usage Example](#websocket-usage-example)
+    - [WebSocket Requirements](#websocket-requirements)
   - [Examples](#examples)
-    - [1. Get Input Tables](#1-get-input-tables)
-    - [2. Get Workbooks by Type](#2-get-workbooks-by-type)
+    - [1. Complete Setup with User Details and WebSocket](#1-complete-setup-with-user-details-and-websocket)
+    - [2. Get Input Tables](#2-get-input-tables)
+    - [3. Get Workbooks by Type](#3-get-workbooks-by-type)
   - [Development](#development)
   - [Related Packages](#related-packages)
 
@@ -42,7 +48,7 @@ npm install @bluecopa/core
 - Dependencies:
   - axios (1.12.0) - For HTTP requests
   - lodash (4.17.21) - For utility functions
-
+  - centrifuge (5.0.0) - For WebSocket connections
 
 ## Configuration
 
@@ -51,13 +57,38 @@ The package uses a singleton-based configuration system to manage API settings.
 Import and set the config:
 
 ```typescript
-import { copaSetConfig } from '@bluecopa/core';
+import { copaSetConfig, copaApi } from '@bluecopa/core';
 
 copaSetConfig({
   apiBaseUrl: 'https://develop.bluecopa.com', // Base URL for API endpoints
   accessToken: 'your-access-token',       // Authentication token
-  workspaceId: 'your-workspace-id'        // Current workspace identifier
+  workspaceId: 'your-workspace-id',       // Current workspace identifier
+  userId: 'your-user-id'                  // User identifier for WebSocket connections
+});
+```
+
+### Getting User Details and Setting User ID
+
+To automatically set the userId from the logged-in user:
+
+```typescript
+import { copaSetConfig, copaApi } from '@bluecopa/core';
+
+// First configure basic settings
+copaSetConfig({
+  apiBaseUrl: 'https://develop.bluecopa.com',
+  accessToken: 'your-access-token',
+  workspaceId: 'your-workspace-id'
 });
+
+// Get user details and set userId
+try {
+  const userDetails = await copaApi.user.getLoggedInUserDetails();
+  copaSetConfig({ userId: userDetails.id });
+  console.log('User ID set:', userDetails.id);
+} catch (error) {
+  console.error('Failed to get user details:', error);
+}
 ```
 
 - `copaSetConfig(partialConfig: Partial<Config>)`: Updates the configuration.
@@ -71,6 +102,7 @@ export interface Config {
   apiBaseUrl: string;
   accessToken: string;
   workspaceId: string;
+  userId: string;
 }
 ```
 
@@ -79,6 +111,7 @@ export interface Config {
 All API functions are asynchronous and use the shared `apiClient` for HTTP requests. They handle errors by throwing objects with `message` and `status`. Access via `copaApi.moduleName.functionName()`.
 
 ### Dataset Module
+
 - `copaApi.dataset.getData()`: Retrieves specific dataset data by ID or parameters
 - `copaApi.dataset.getDatasets()`: Fetches a list of datasets
 - `copaApi.dataset.getSampleData()`: Gets sample data for datasets
@@ -86,6 +119,7 @@ All API functions are asynchronous and use the shared `apiClient` for HTTP reque
 See: [`dataset/getData.ts`](src/api/dataset/getData.ts:1), [`dataset/getSampleData.ts`](src/api/dataset/getSampleData.ts:1), [`dataset/getDatasets.ts`](src/api/dataset/getDatasets.ts:1)
 
 ### Definition Module
+
 - `copaApi.definition.runDefinition()`: Executes a custom definition
 - `copaApi.definition.runPublishedDefinition()`: Runs a published definition
 - `copaApi.definition.runSampleDefinition()`: Executes a sample definition for testing
@@ -93,11 +127,13 @@ See: [`dataset/getData.ts`](src/api/dataset/getData.ts:1), [`dataset/getSampleDa
 See: [`definition/runPublishedDefinition.ts`](src/api/definition/runPublishedDefinition.ts:1), [`definition/runSampleDefinition.ts`](src/api/definition/runSampleDefinition.ts:1), [`definition/runDefinition.ts`](src/api/definition/runDefinition.ts:1)
 
 ### File Module
+
 - `copaApi.files.getFileUrlByFileId(fileId: string)`: Generates a URL for a file by its ID
 
 See: [`file/getFileUrlByFileId.ts`](src/api/file/getFileUrlByFileId.ts:1)
 
 ### InputTable Module
+
 - `copaApi.inputTable.getData()`: Retrieves data from an input table
 - `copaApi.inputTable.getInputTables()`: Fetches all input tables
 - `copaApi.inputTable.getTableById(id: string)`: Gets a specific input table by ID
@@ -105,22 +141,26 @@ See: [`file/getFileUrlByFileId.ts`](src/api/file/getFileUrlByFileId.ts:1)
 See: [`inputTable/getData.ts`](src/api/inputTable/getData.ts:1), [`inputTable/getInputTables.ts`](src/api/inputTable/getInputTables.ts:1), [`inputTable/getTableById.ts`](src/api/inputTable/getTableById.ts:1)
 
 ### Metric Module
+
 - `copaApi.metric.getData()`: Fetches metric data
 
 See: [`metric/getData.ts`](src/api/metric/getData.ts:1)
 
 ### User Module
+
 - `copaApi.user.getLoggedInUserDetails()`: Retrieves details of the currently logged-in user
 
 See: [`user/getLoggedInUserDetails.ts`](src/api/user/getLoggedInUserDetails.ts:1)
 
 ### Workbook Module
+
 - `copaApi.workbook.getPublishedWorkbookById(id: string)`: Fetches a published workbook by ID
 - `copaApi.workbook.getWorkbooksByType(type: string)`: Retrieves workbooks filtered by type
 
 See: [`workbook/getPublishedWorkbookById.ts`](src/api/workbook/getPublishedWorkbookById.ts:1), [`workbook/getWorkbooksByType.ts`](src/api/workbook/getWorkbooksByType.ts:1)
 
 ### Workflow Module
+
 - `copaApi.workflow.getWorkflowInstanceStatusById(id: string)`: Checks the status of a workflow instance
 - `copaApi.workflow.triggerHttpWorkflowById(id: string)`: Triggers an HTTP-based workflow
 - `copaApi.workflow.triggerWorkflowById(id: string)`: Triggers a workflow by ID
@@ -128,28 +168,137 @@ See: [`workbook/getPublishedWorkbookById.ts`](src/api/workbook/getPublishedWorkb
 See: [`workflow/triggerHttpWorkflowById.ts`](src/api/workflow/triggerHttpWorkflowById.ts:1), [`workflow/triggerWorkflowById.ts`](src/api/workflow/triggerWorkflowById.ts:1), [`workflow/getWorkflowInstanceStatusById.ts`](src/api/workflow/getWorkflowInstanceStatusById.ts:1)
 
 ### Worksheet Module
+
 - `copaApi.worksheet.getWorksheets()`: Fetches all worksheets
 - `copaApi.worksheet.getWorksheetsByType(type: string)`: Retrieves worksheets by type
 
 See: [`worksheet/getWorksheets.ts`](src/api/worksheet/getWorksheets.ts:1), [`worksheet/getWorksheetsByType.ts`](src/api/worksheet/getWorksheetsByType.ts:1)
 
+## WebSocket Connection
+
+The core package provides WebSocket utilities for real-time communication using Centrifugo.
+
+### WebSocket Factory
+
+Access WebSocket functionality through the utilities:
+
+```typescript
+import { copaUtils } from '@bluecopa/core';
+
+// Create a WebSocket connection
+const websocket = copaUtils.websocketUtils.WebsocketContextFactory.create('centrifugo', {
+  connectionUrl: 'wss://your-centrifugo-url'
+});
+```
+
+### WebSocket Provider Interface
+
+The `IWebsocketProvider` interface provides the following methods:
+
+- `connect()`: Establishes the WebSocket connection
+- `bind(channel: string, event: string, callback: (data: any) => void)`: Subscribe to private user-specific channels
+- `bindGlobal(event: string, callback: (data: any) => void)`: Subscribe to global channels
+- `unbindAll(channel: string)`: Unsubscribe from all events on a channel
+- `disconnect()`: Close the WebSocket connection
+
+### WebSocket Usage Example
+
+```typescript
+import { copaSetConfig, copaApi, copaUtils } from '@bluecopa/core';
+
+// Configure with userId for WebSocket connections
+copaSetConfig({
+  apiBaseUrl: 'https://develop.bluecopa.com',
+  accessToken: 'your-access-token',
+  workspaceId: 'your-workspace-id',
+  userId: 'your-user-id'
+});
+
+// Create WebSocket connection
+const websocket = copaUtils.websocketUtils.WebsocketContextFactory.create('centrifugo', {
+  connectionUrl: 'wss://centrifugo.your-domain.com/connection/websocket'
+});
+
+// Subscribe to user-specific events
+websocket.bind('notifications', 'new_message', (data) => {
+  console.log('New notification:', data);
+});
+
+// Subscribe to global events
+websocket.bindGlobal('system_updates', (data) => {
+  console.log('System update:', data);
+});
+
+// Clean up when done
+websocket.disconnect();
+```
+
+### WebSocket Requirements
+
+- **userId**: Required for private channel subscriptions (`bind` method)
+- **accessToken**: Required for authentication with Centrifugo
+- **connectionUrl**: WebSocket endpoint URL
+
+The WebSocket connection automatically uses the configured `accessToken` and `userId` from the config for authentication and channel binding.
+
 ## Examples
 
-### 1. Get Input Tables
+### 1. Complete Setup with User Details and WebSocket
+
+Complete example showing configuration, user details retrieval, and WebSocket setup.
+
+```typescript
+import { copaSetConfig, copaApi, copaUtils } from '@bluecopa/core';
+
+// Initial configuration
+copaSetConfig({
+  apiBaseUrl: 'https://develop.bluecopa.com',
+  accessToken: 'your-access-token',
+  workspaceId: 'your-workspace-id'
+});
+
+// Get user details and set userId
+try {
+  const userDetails = await copaApi.user.getLoggedInUserDetails();
+  copaSetConfig({ userId: userDetails.id });
+  console.log('User configured:', userDetails.name, userDetails.id);
+} catch (error: any) {
+  console.error('Failed to get user details:', error.message, error.status);
+}
+
+// Set up WebSocket connection
+const websocket = copaUtils.websocketUtils.WebsocketContextFactory.create('centrifugo', {
+  connectionUrl: 'wss://centrifugo.develop.bluecopa.com/connection/websocket'
+});
+
+// Subscribe to notifications
+websocket.bind('notifications', 'new_message', (data) => {
+  console.log('New notification received:', data);
+});
+```
+
+### 2. Get Input Tables
+
 Fetches all input tables from the API.
 
 ```typescript
 import { copaApi } from '@bluecopa/core';
 
 // Configure first
-copaSetConfig({ apiBaseUrl: 'https://api.example.com', accessToken: 'token', workspaceId: 'ws1' });
+copaSetConfig({ 
+  apiBaseUrl: 'https://api.example.com', 
+  accessToken: 'token', 
+  workspaceId: 'ws1',
+  userId: 'user123'
+});
 
 // Use API
 const { getInputTables } = copaApi.inputTable;
 const { getWorkbooksByType } = copaApi.workbook;
 ```
 
-### 2. Get Workbooks by Type
+### 3. Get Workbooks by Type
+
 Retrieves workbooks filtered by a specific type.
 
 ```typescript

package/dist/config.d.ts

@@ -2,6 +2,7 @@ export interface Config {
     apiBaseUrl: string;
     accessToken: string;
     workspaceId: string;
+    userId: string;
 }
 declare class ConfigSingleton {
     private static instance;