@bluecopa/core
Advanced tools
The core package provides essential API utilities and functions for data management, workbook handling, dataset operations, and definition execution in the Bluecopa platform.
The core package provides essential API utilities and functions for data management, workbook handling, dataset operations, and definition execution in the Bluecopa platform.
Current version: 0.1.4
npm install @bluecopa/core
The package uses a singleton-based configuration system to manage API settings. Configure it before making API calls.
Import and set the config:
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
userId: "your-user-id", // User identifier for WebSocket connections
});
To automatically set the userId from the logged-in user:
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.copaGetConfig(): Retrieves the current configuration.resetConfig(): Resets to default empty values.The Config interface:
export interface Config {
apiBaseUrl: string;
accessToken: string;
workspaceId: string;
userId: string;
solutionId?: string; // used by InputTableDB
websocketProvider?: IWebsocketProvider; // enables realtime sync
}
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().
copaApi.audit.createAuditLog(): Records an audit log entrycopaApi.audit.getAuditLogs(): Retrieves audit log entriesSee: audit/createAuditLog.ts, audit/getAuditLogs.ts
copaApi.chat.checkSubscriptionStatus(): Checks whether the user is subscribed to chat updatescopaApi.chat.createThread(): Creates a new chat threadcopaApi.chat.getCommentsByThreadId(): Lists comments in a threadcopaApi.chat.postComment(): Posts a comment to a threadcopaApi.chat.updateComment(): Updates an existing commentcopaApi.chat.deleteComment(): Deletes a commentcopaApi.chat.subscribeUser(): Subscribes a user to chat updatescopaApi.chat.unsubscribeUser(): Unsubscribes a user from chat updatesSee: chat/
copaApi.clientIp.getClientIp(): Returns the caller's client IPcopaApi.dataset.getData(): Retrieves specific dataset data by ID or parameterscopaApi.dataset.getDatasets(): Fetches a list of datasetscopaApi.dataset.getSampleData(): Gets sample data for datasetsSee: dataset/getData.ts, dataset/getSampleData.ts, dataset/getDatasets.ts
copaApi.definition.runDefinition(): Executes a custom definitioncopaApi.definition.runPublishedDefinition(): Runs a published definitioncopaApi.definition.runSampleDefinition(): Executes a sample definition for testingSee: definition/runPublishedDefinition.ts, definition/runSampleDefinition.ts, definition/runDefinition.ts
copaApi.emailEngine.getAllConversations(): Lists email conversations (paginated)copaApi.emailEngine.getConversation(): Fetches a single conversationcopaApi.emailEngine.createConversation(): Creates a new conversationcopaApi.emailEngine.replyToConversation(): Sends a reply on a conversationcopaApi.emailEngine.getMessageBySenderId(): Retrieves messages filtered by sender idSee: emailEngine/
copaApi.files.getFileUrlByFileId(fileId: string): Generates a URL for a file by its IDcopaApi.files.fileUpload({ data, contentType, method, uploadType }): Uploads data and returns a file id/pathcopaApi.files.fileDownload({ fileId }): Downloads a file by idcopaApi.files.getFileByFolderIdAndName({ folderId, name }): Fetches a filebox file by its parent folder and nameSee: file/getFileUrlByFileId.ts, file/fileUpload.ts, file/fileDownload.ts, file/getFileByFolderIdAndName.ts
copaApi.form.getFormById(): Fetches a form by idcopaApi.form.getFormSchema(): Retrieves a form's schemacopaApi.form.getFormData(): Retrieves submitted form datacopaApi.form.createOrUpdateForm(): Creates or updates a form definitionSee: form/
copaApi.inboxItems.getAllInboxItems(): Lists inbox itemscopaApi.inboxItems.createInboxItemPerUser(): Creates an inbox item for a specific usercopaApi.inboxItems.markItemAsRead(): Marks an inbox item as readcopaApi.inboxItems.markItemAsUnread(): Marks an inbox item as unreadSee: inboxItems/
copaApi.inputTable.getData(): Retrieves data from an input tablecopaApi.inputTable.getInputTables(): Fetches all input tablescopaApi.inputTable.getTableById(id: string): Gets a specific input table by IDcopaApi.inputTable.getRows(options): Reads rows from an input table view (filters, paging, sorting)copaApi.inputTable.insertRow(options): Inserts a new rowcopaApi.inputTable.updateRow(options): Updates an existing rowcopaApi.inputTable.deleteRow(options): Deletes a rowSee: inputTable/getData.ts, inputTable/getInputTables.ts, inputTable/getTableById.ts, inputTable/getRows.ts, inputTable/insertRow.ts, inputTable/updateRow.ts, inputTable/deleteRow.ts
copaApi.metric.getData(): Fetches metric dataSee: metric/getData.ts
copaApi.permissions.getPermissions(): Retrieves permissions for the current user / contextSee: permissions/getPermissions.ts
copaApi.process.markTaskDone(): Marks a process task as donecopaApi.process.reassignTask(): Reassigns a process task to a different usercopaApi.process.getTriggersBySheet(): Lists triggers associated with a sheetcopaApi.process.registerProcessTrigger(): Registers a new process triggercopaApi.process.deleteProcessTrigger(): Deletes a process triggerSee: process/
copaApi.recon.runRecon(): Triggers a recon workflow runcopaApi.recon.getAllReconWorkflows(): Lists all recon workflowsSee: recon/runRecon.ts, recon/getAllReconWorkflows.ts
copaApi.statement.getData(): Retrieves statement datacopaApi.statement.getViewsBySheetId(): Lists statement views for a sheetcopaApi.statement.getViewById(): Fetches a single statement viewcopaApi.statement.getRunsByViewId(): Lists runs for a given viewcopaApi.statement.createNewRun(): Creates a new statement runcopaApi.statement.getRunResultById(): Fetches the result of a given runSee: statement/
copaApi.task.getTaskDetails(): Fetches detailed information about a taskcopaApi.templatedPipeline.getAllTemplatedPipelines(): Lists all templated pipelinesSee: templatedPipeline/getAllTemplatedPipelines.ts
copaApi.templates.renderTemplate(): Renders a template with provided variablesSee: templates/render.ts
copaApi.tcn.getAuthUrl(): Returns the TCN OAuth authorization URLcopaApi.tcn.exchangeCode(): Exchanges an OAuth code for TCN tokenscopaApi.tcn.refreshToken(): Refreshes a TCN access tokencopaApi.tcn.getCurrentAgent(): Fetches the currently signed-in TCN agentcopaApi.tcn.getAgentSkills(): Lists skills available to the agentcopaApi.tcn.createSession(): Creates a new TCN agent sessioncopaApi.tcn.keepAlive(): Pings the TCN session to keep it alivecopaApi.tcn.agentGetStatus(): Returns the current agent statuscopaApi.tcn.agentSetReady(): Marks the agent as readycopaApi.tcn.agentPause(): Pauses the agentcopaApi.tcn.agentDisconnect(): Disconnects the agentcopaApi.tcn.agentGetConnectedParty(): Returns the currently connected party for the agentcopaApi.tcn.agentPutCallOnHold(): Puts the agent's current call on holdcopaApi.tcn.agentGetCallFromHold(): Resumes the agent's held callcopaApi.tcn.getHuntGroupAgentSettings(): Fetches hunt-group settings for the agentcopaApi.tcn.getCallData(): Retrieves data for an active callcopaApi.tcn.dialManualPrepare(): Prepares a manual dialcopaApi.tcn.manualDialStart(): Starts a prepared manual dialcopaApi.tcn.processManualDial(): Processes the result of a manual dialSee: tcn/
copaApi.user.getLoggedInUserDetails(): Retrieves details of the currently logged-in usercopaApi.user.getAllUsers(): Lists all users in the workspaceSee: user/getLoggedInUserDetails.ts, user/getAllUsers.ts
copaApi.workbook.getPublishedWorkbookById(id: string): Fetches a published workbook by IDcopaApi.workbook.getWorkbooksByType(type: string): Retrieves workbooks filtered by typecopaApi.workbook.getWorkbookDetails(): Retrieves workbook metadata/detailscopaApi.workbook.saveWorkbook(): Saves a workbook draftcopaApi.workbook.publishWorkbook(): Publishes a workbookSee: workbook/getPublishedWorkbookById.ts, workbook/getWorkbooksByType.ts, workbook/getWorkbookDetails.ts, workbook/saveWorkbook.ts, workbook/publishWorkbook.ts
copaApi.workflow.getWorkflowInstanceStatusById(id: string): Checks the status of a workflow instancecopaApi.workflow.triggerHttpWorkflowById(id: string): Triggers an HTTP-based workflowcopaApi.workflow.triggerWorkflowById(id: string): Triggers a workflow by IDcopaApi.workflow.getAllHttpTriggers(): Lists all HTTP triggersSee: workflow/triggerHttpWorkflowById.ts, workflow/triggerWorkflowById.ts, workflow/getWorkflowInstanceStatusById.ts, workflow/getAllHttpTriggers.ts
copaApi.worksheet.getWorksheets(): Fetches all worksheetscopaApi.worksheet.getWorksheetsByType(type: string): Retrieves worksheets by typeSee: worksheet/getWorksheets.ts, worksheet/getWorksheetsByType.ts
A Firebase-like client for querying and subscribing to Bluecopa Input Table V2 data. No init required — just import and use.
Full SDK Guide — comprehensive documentation with architecture details, error handling, framework integration (Svelte/React), and all available features.
import { copaSetConfig, copaInputTableDb } from "@bluecopa/core";
// Configure once at app startup
copaSetConfig({
apiBaseUrl: "https://develop.bluecopa.com",
accessToken: "your-token",
workspaceId: "ws-123",
solutionId: "sol-abc", // optional — falls back to SOLUTION_ID cookie
websocketProvider: ws, // optional — enables realtime sync
});
// Subscribe (reactive — fires on every change)
const unsub = copaInputTableDb.collection("invoices")
.where("status", "==", "pending")
.orderBy("updated_at", "desc")
.limit(50)
.subscribe((rows) => console.log(rows));
// Cleanup
unsub();
// One-time fetch
const rows = await copaInputTableDb.collection("invoices").get();
const inv = await copaInputTableDb.collection("invoices").doc(id).get();
// Write
const newId = await copaInputTableDb.collection("invoices").add({ vendor: "Acme", amount: 100 });
await copaInputTableDb.collection("invoices").doc(id).update({ status: "approved" });
await copaInputTableDb.collection("invoices").doc(id).delete();
// Listen to a single doc
const unsub = copaInputTableDb.collection("invoices").doc(id).onSnapshot((doc) => {
console.log(doc);
});
// Reactive count
const unsub = copaInputTableDb.collection("invoices").count((n) => console.log(n));
| Operator | Meaning |
|---|---|
== | equals |
!= | not equals |
< | less than |
<= | less than or eq |
> | greater than |
>= | gte |
in | in array |
not-in | not in array |
Compute server-side aggregates (sum, avg, count, min, max) without fetching all rows. Combines with where(), limit(), and skip() filters.
// Column aggregates
const result = await copaInputTableDb
.collection("invoices")
.where("status", "==", "active")
.aggregate({ amount: ["sum", "avg"], price: ["min", "max"] });
// => { amount: { sum: 1234.56, avg: 123.45 }, price: { min: 10, max: 999 } }
// Row count
const result = await copaInputTableDb
.collection("invoices")
.aggregate({ _count: true });
// => { _count: 42 }
// Column count (non-null values) + row count
const result = await copaInputTableDb
.collection("invoices")
.aggregate({ name: ["count"], _count: true });
// => { name: { count: 38 }, _count: 42 }
.aggregate() is a terminal method — it bypasses local RxDB and hits PostgREST directly. Errors throw InputTableError. An empty spec {} returns {} without calling the API.
Add a { groupBy: [...columns] } second argument to get per-group breakdowns. Returns an array instead of a single object.
// Sum per status group
const rows = await copaInputTableDb
.collection("invoices")
.aggregate({ amount: ["sum"] }, { groupBy: ["status"] });
// => [{ status: "active", amount: { sum: 1234 } }, { status: "draft", amount: { sum: 100 } }]
// Multi-column groupBy with filters and ordering
const rows = await copaInputTableDb
.collection("invoices")
.where("year", "==", 2024)
.orderBy("order_date", "asc")
.aggregate({ amount: ["sum", "avg"] }, { groupBy: ["order_date", "status"] });
// Count per group
const rows = await copaInputTableDb
.collection("invoices")
.aggregate({ _count: true }, { groupBy: ["status"] });
// => [{ status: "active", _count: 10 }, { status: "draft", _count: 4 }]
// Distinct values (no aggregate functions)
const rows = await copaInputTableDb
.collection("invoices")
.aggregate({}, { groupBy: ["status"] });
// => [{ status: "active" }, { status: "draft" }]
Notes:
orderBy() is forwarded to PostgREST when groupBy is present (ignored otherwise)limit()/skip() apply to the number of groups, not input rowsgroupBy — throws InputTableErrorgroupBy: [] behaves like no groupBy — returns a single objectSvelte 5
<script>
import { copaInputTableDb } from "@bluecopa/core";
let rows = $state([]);
$effect(() =>
copaInputTableDb.collection("invoices")
.where("status", "==", "pending")
.subscribe((r) => { rows = r; })
);
</script>
React
useEffect(() => {
return copaInputTableDb.collection("invoices")
.where("status", "==", "pending")
.subscribe(setRows);
}, []);
Vanilla JS
const unsub = copaInputTableDb.collection("invoices").subscribe(setRows);
// later:
unsub();
Enables realtime sync via push instead of polling:
import { copaSetConfig, copaInputTableDb, copaUtils } from "@bluecopa/core";
const ws = copaUtils.websocketUtils.WebsocketContextFactory.create("centrifugo", {
connectionUrl: "wss://...",
token: "jwt",
userId: "user-123",
});
// Option A: via config
copaSetConfig({ websocketProvider: ws });
// Option B: set directly
copaInputTableDb.setWebsocketProvider(ws);
If no provider is set, the SDK still works via HTTP pull replication and logs a console warning.
await copaInputTableDb.destroy(); // closes all collections + WebSocket
The core package provides WebSocket utilities for real-time communication using Centrifugo.
Access WebSocket functionality through the utilities:
import { copaUtils } from "@bluecopa/core";
// Create a WebSocket connection
const websocket = copaUtils.websocketUtils.WebsocketContextFactory.create(
"centrifugo",
{
connectionUrl: "wss://your-centrifugo-url",
},
);
The IWebsocketProvider interface provides the following methods:
connect(): Establishes the WebSocket connectionbind(channel: string, event: string, callback: (data: any) => void): Subscribe to private user-specific channelsbindGlobal(event: string, callback: (data: any) => void): Subscribe to global channelsunbindAll(channel: string): Unsubscribe from all events on a channeldisconnect(): Close the WebSocket connectionimport { 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();
bind method)The WebSocket connection automatically uses the configured accessToken and userId from the config for authentication and channel binding.
Complete example showing configuration, user details retrieval, and WebSocket setup.
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);
});
Fetches all input tables from the API.
import { copaApi } from "@bluecopa/core";
// Configure first
copaSetConfig({
apiBaseUrl: "https://api.example.com",
accessToken: "token",
workspaceId: "ws1",
userId: "user123",
});
// Use API
const { getInputTables } = copaApi.inputTable;
const { getWorkbooksByType } = copaApi.workbook;
Retrieves workbooks filtered by a specific type.
import { copaApi } from "@bluecopa/core";
import type { Worksheet } from "$models/gen/Api";
try {
const workbooks = await copaApi.workbook.getWorkbooksByType(
"dashboard" as Worksheet["type"],
);
console.log(workbooks); // Array of Worksheet
} catch (error: any) {
console.error(error.message, error.status);
}
npm run build (in the root or package-specific script)FAQs
The core package provides essential API utilities and functions for data management, workbook handling, dataset operations, and definition execution in the Bluecopa platform.
The npm package @bluecopa/core receives a total of 2,021 weekly downloads. As such, @bluecopa/core popularity was classified as popular.
We found that @bluecopa/core demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
npm confirmed a tooling bug incorrectly marked several one-character packages as security holders and said it was working on a rollback.
Research
/Security News
Newer packages in this compromise use native extensions and .pth loaders to execute JavaScript stealers in developer environments.
Research
Socket found 37 malicious PyPI wheels that abuse Python startup hooks to launch a Bun-powered credential stealer tied to Mini Shai-Hulud/Miasma.