@bluecopa/core

中文文档

0.1.127发布于 2026/10/13MITTypeScriptES Module近 30 天下载 9873

核心包是Bluecopa的TypeScript API SDK. 它提供了一个配置的 Axios 客户端,一个命名的空格 API 表面(copaApi.*)覆盖了每个平台域,一个被整理的api/hub客户端,一个类似 Firebase 的反应式输入表 DB, Centrifugo/Pusher WebSocket

文档目录63 节

目录
安装
所需资源
配置
配置接口
从登录的用户设置用户 ID
API 参考
用户
团队
工作流程
文档( copaApi.files (中文(简体) )
定义
计量
聊天
数据集
输入表
工作手册
工作表
语句
任务
侦察
侦察V2
表单
审计
模板管道
进程
进程
收件箱项目
收件箱V2
权限
自定义Authz
客户端IP
电子邮件引擎
管理
数据框
吨数
模板
管道
正在工作纸张
解决方案
版本
外部附录
中心模块 /blui-api (中文(简体) )
顶级出口
输入表DB — 反应数据库客户端
快速启动
拥挤
查询运算符
总计查询
分组汇总
框架整合
WebSocket 提供者( 可选)
清理
WebSocket 连接
网索厂
WebSocket 提供者接口
WebSocket 用法示例
WebSocket 要求
实例
配置, 然后获取输入表
按类型获得工作簿
发展
相关软件包

@ 蓝色copa/ 核心

核心包是Bluecopa的TypeScript API SDK. 它提供了一个配置的 Axios 客户端,一个命名空格 API 表面(copaApi.*覆盖每个平台域,a api/ hub 客户端,类似 Firebase 的反应式输入表 DB, Centrifugo/ Pusher WebSocket 公用设备, 和共享的 Tailwind 配置 .

安装

npm install @bluecopa/core
# or
pnpm add @bluecopa/core

请检查access-date=中的日期值 (帮助) Npm 徽章上方为当前已发布的版本.

所需资源

节点.js ^20.19.0 || >=22.12.0
运行时间依赖性 :
- axios (1.16.0)——HTTP请求
- centrifuge (5.2.2)-离心式WebSocket连接
- pusher-js (^8.3.0) — Pusher WebSocket 连接
- rxdb (^16.21.1)+ (中文(简体) ) rxjs (^ 7.5.4) - 反应式输入表 DB
- lodash (4.18.1)——公用事业职能

配置

该包采用单通配置. 在API通话前设定一次.

import { copaSetConfig, copaGetConfig, copaApi } from '@bluecopa/core';

copaSetConfig({
    apiBaseUrl: 'https://develop.bluecopa.com/api/v1', // data-plane base URL
    accessToken: 'your-access-token', // auth token
    workspaceId: 'your-workspace-id', // active workspace
    userId: 'your-user-id' // used by WebSocket private channels
});

copaSetConfig(partialConfig: Partial<Config>) ——合并为当前配置.
copaGetConfig() ——返回当前配置的副本.

配置接口

export interface Config {
    apiBaseUrl: string;
    hubBaseUrl?: string; // curated /blui-api base; derived from apiBaseUrl when unset
    accessToken: string;
    workspaceId: string;
    userId: string;
    solutionId?: string; // solution-scoped requests + InputTableDB
    solutionBranch?: string; // solution branch name
    solutionBranchType?: string; // 'LOCAL' | 'REMOTE'
    deployedSolution?: boolean; // forwards x-bluecopa-deployed-solution: true
    websocketProvider?: IWebsocketProvider; // enables realtime sync
}

SDK 转发工作空间和溶液背景( 分支、分支类型、部署) )作为请求头自动。设置解析字段(或 solutionId cookie),来做调用 - 了解解决方案.

从登录的用户设置用户 ID

copaSetConfig({
    apiBaseUrl: 'https://develop.bluecopa.com/api/v1',
    accessToken: 'your-access-token',
    workspaceId: 'your-workspace-id'
});

const userDetails = await copaApi.user.getLoggedInUserDetails();
copaSetConfig({ userId: userDetails.id });

API 参考

所有 API 函数都是同步的, 使用共享 apiClient,并实现正常化扔出对象时出错 { message, status }。作为 copaApi.<module>.<function>()标记模块 (呼声) 目标 /blui-api 地面通过 hubClient 而不是数据平面 apiClient。。。 .

用户

copaApi.user.getLoggedInUserDetails(): 获取认证的用户配置文件 .
copaApi.user.getAllUsers(): 列出工作空间中的所有用户.

团队

copaApi.team.getAllTeams():列出工作空间中的所有团队.

工作流程

copaApi.workflow.triggerHttpWorkflowById(): 由 id 触发 HTTP 工作流程 .
copaApi.workflow.triggerWorkflowById(): 由 id 触发一个工作流程.
copaApi.workflow.getWorkflowInstanceStatusById():获得工作流程实例状态.
copaApi.workflow.getAllHttpTriggers():列出所有HTTP工作流程触发器.

文档(`copaApi.files`(中文(简体) )

copaApi.files.getFileUrlByFileId(): 为文件 ID 返回 a(已签名) URL.
copaApi.files.fileUpload(): 上传一个文件并返回其元数据.
copaApi.files.fileDownload():下载文件的内容.
copaApi.files.getFileByFolderIdAndName():通过文件夹 id + name 查找文件箱文件.
copaApi.files.getFileById(): 由 id 获取文件的元数据 .

定义

copaApi.definition.runDefinition(): 运行定义草案.
copaApi.definition.runPublishedDefinition():运行已发布的定义.
copaApi.definition.runSampleDefinition():对照样本数据运行定义.
copaApi.definition.getDescription():检索定义的描述/元数据.

计量

copaApi.metric.getData(): 获取计算出的计量数据.

聊天

copaApi.chat.createThread():创建注释线程.
copaApi.chat.getCommentsByThreadId(): 在线索中列出注释.
copaApi.chat.postComment(): 将注释张贴到一条线上.
copaApi.chat.updateComment(): 编辑注释.
copaApi.chat.deleteComment(): 删除注释.
copaApi.chat.subscribeUser(): 用户订阅到线索.
copaApi.chat.unsubscribeUser(): 取消从线程订阅用户.
copaApi.chat.checkSubscriptionStatus():检查用户订阅线索.

数据集

copaApi.dataset.getData(): 获取数据集行数据.
copaApi.dataset.getSampleData():获取数据集行样本.
copaApi.dataset.getAllDatasets():列出所有数据集.
copaApi.dataset.getVirtualDatasets(): 列出虚拟数据集.
copaApi.dataset.getDatasetExceptions():为数据集获取例外行.
copaApi.dataset.getDatasetDuplicates():为数据集获取重复行.

输入表

copaApi.inputTable.getData():获取输入表数据.
copaApi.inputTable.getTableById(): 以 id 获取输入表定义.
copaApi.inputTable.getInputTables(): 列出所有输入表格.
copaApi.inputTable.getRows():读取行(过滤,呼出,排序).
copaApi.inputTable.insertRow():插入一行.
copaApi.inputTable.updateRow(): 更新一行.
copaApi.inputTable.deleteRow(): 删除一行.

工作手册

copaApi.workbook.getWorkbooksByType(): 列出特定类型的工作手册.
copaApi.workbook.getPublishedWorkbookById():取出由 id 编辑的已出版的工作手册.
copaApi.workbook.getWorkbookDetails():获取完整的工作手册细节.
copaApi.workbook.saveWorkbook():保存工作手册草稿.
copaApi.workbook.publishWorkbook():出版工作手册.
copaApi.workbook.deleteWorkbook():删除工作手册.

工作表

copaApi.worksheet.getWorksheets(): 由 ID 获取工作表.
copaApi.worksheet.getWorksheetsByType(): 列出特定类型的工作表.
copaApi.worksheet.getWorksheetModel(): 以工作表的模型JSON 以工作表 ID 来取取.

语句

copaApi.statement.getData():获取语句数据.
copaApi.statement.getViewsBySheetId(): 列出工作表的语句视图.
copaApi.statement.getViewById():获取 id 的语句视图.
copaApi.statement.getRunsByViewId(): 列表运行一个视图.
copaApi.statement.createNewRun(): 开始一个新的语句运行.
copaApi.statement.getRunResultById():获取语句运行结果.

任务

copaApi.task.getTaskDetails():获取任务的细节.

侦察

copaApi.recon.runRecon():运行 a(v1)调节工作流程.
copaApi.recon.getAllReconWorkflows(): 列出所有(v1) 重组工作流程.

侦察V2

copaApi.reconV2.createReconV2(): 创建侦察v2工作流程.
copaApi.reconV2.updateReconV2(): 更新侦察v2工作流程.
copaApi.reconV2.deleteReconV2(): 删除一个 spec v2 工作流程.
copaApi.reconV2.runReconV2():运行一个侦察v2工作流程.
copaApi.reconV2.getAllReconV2Workflows(): 列出所有 spec v2 工作流程 .
copaApi.reconV2.getReconV2Workflow():获取一个单一的侦察 v2 工作流程.
copaApi.reconV2.getReconV2Runs(): Lists 运行一个 spec v2 工作流程.
copaApi.reconV2.getReconV2RunResult(): 获取 V2 搜索结果 .
copaApi.reconV2.getReconV2SmartResult():获取运行的AI辅助结果.
copaApi.reconV2.startReconV2Profile():开始数据映射工作.
copaApi.reconV2.getReconV2ProfileResult():获取剖析结果.
copaApi.reconV2.startReconV2Clean():开始数据清理工作.
copaApi.reconV2.getReconV2CleanResult():获取清洁结果.
copaApi.reconV2.getReconV2Diff():在数据集/运行之间获取 diff .
copaApi.reconV2.getReconV2Explanation():获取匹配/结果的解释.
copaApi.reconV2.getReconV2Templates():获取 spec v2 模板目录.

表单

copaApi.form.getFormById(): 以 ID 获取一个表.
copaApi.form.getFormSchema():获取表单的图案.
copaApi.form.getFormData():获取已提交的表格数据.
copaApi.form.createOrUpdateForm(): 创建或更新窗体.

审计

copaApi.audit.getAuditLogs():获取审计日志条目.
copaApi.audit.createAuditLog(): 创建审计日志条目.

模板管道

copaApi.templatedPipeline.getAllTemplatedPipelines():列出所有模板管道.

进程

copaApi.process.markTaskDone(): 标记一个已完成的进程任务.
copaApi.process.reassignTask():重新指派一个进程任务.
copaApi.process.getTriggersBySheet(): 列表进程触发工作表.
copaApi.process.registerProcessTrigger(): 登记进程触发器.
copaApi.process.deleteProcessTrigger(): 删除进程触发.
copaApi.process.pauseSchedule():暂停预定的触发.
copaApi.process.resumeSchedule(): 恢复一个已暂停的时间表.
copaApi.process.getScheduleStatus():获得时间表状态.
copaApi.process.executeNow():立即执行一个预定的过程.

进程

copaApi.processTree.createOrUpdateProcessTreeTrigger(): 创建/更新进程树触发器.
copaApi.processTree.executeProcessTreeTrigger():执行进程-树木触发器.
copaApi.processTree.terminatePipelines():终止运行进程树的管道.
copaApi.processTree.logProcessTreeRun():记录一个进程-树跑.
copaApi.processTree.updateProcessTreeRunContext(): 更新运行上下文.
copaApi.processTree.getProcessTreeTrigger(): 由 ID 获取触发 .
copaApi.processTree.deleteProcessTreeTrigger(): 删除触发器.
copaApi.processTree.getProcessTreeTriggersBySheetId(): 列出工作表的触发点.
copaApi.processTree.getProcessTreeRunsBySheetId(): 工作表列表运行.
copaApi.processTree.getProcessTreeRunsBySheetIdPaginated(): 工作表列表运行(页).
copaApi.processTree.getProcessTreeRunByInstanceId():通过实例 ID 获取运行 .

收件箱项目

copaApi.inboxItems.getAllInboxItems(): 列出所有收件箱项目.
copaApi.inboxItems.markItemAsRead(): 将项目标为已读 .
copaApi.inboxItems.markItemAsUnread(): 将项目标为未读 .
copaApi.inboxItems.createInboxItemPerUser(): 每个用户创建一个收件箱项目.

收件箱V2

copaApi.inboxV2.listTypes() 编号 : createType() 编号 : getType() 编号 : updateType() 编号 : deleteType(): 管理收件箱项目类型.
copaApi.inboxV2.listMyItems(): 列出当前用户的收件箱项目.
copaApi.inboxV2.createItem() 编号 : getItem() 编号 : updateItem(): 管理收件箱项目.
copaApi.inboxV2.markRead() 编号 : markUnread(): 标记已读/未读的项目.
copaApi.inboxV2.snoozeItem() 编号 : dismissItem(): Snooze或删除一个项目.
copaApi.inboxV2.claimItem() 编号 : completeItem() 编号 : releaseItem(): 索赔、完成或释放可采取行动的项目.
copaApi.inboxV2.cancelItem() 编号 : reassignItem(): 取消或重新分配一个项目.
copaApi.inboxV2.completeByKey() 编号 : cancelByKey(): 按业务密钥完成/终止.

权限

copaApi.permissions.getPermissions():获取当前用户/对象的权限.

自定义Authz

copaApi.customAuthz.getCustomAuthzModel():获取自定义授权模式.
copaApi.customAuthz.registerCustomAuthzModel(): 登记/替换模型.
copaApi.customAuthz.updateCustomObjectPermissions(): 更新对象上的权限.
copaApi.customAuthz.bulkUpdateCustomObjectPermissions(): Bulk-updates 对象权限.
copaApi.customAuthz.checkCustomPermissions():检查权限.
copaApi.customAuthz.bulkCheckCustomPermissions():批量检查权限.

客户端IP

copaApi.clientIp.getClientIp(): 返回呼叫者的客户端IP.

电子邮件引擎

copaApi.emailEngine.getAllConversations(): 列出电子邮件对话(已页).
copaApi.emailEngine.getConversation():获取单个对话.
copaApi.emailEngine.createConversation():创建对话.
copaApi.emailEngine.replyToConversation():回答谈话.
copaApi.emailEngine.getMessageBySenderId():通过发件人ID获取信件.
copaApi.emailEngine.searchMessages(): 搜索电子邮件.

管理

copaApi.periodManagement.createFiscalCalendar() 编号 : listFiscalCalendars() 编号 : getFiscalCalendar() 编号 : updateFiscalCalendar() 编号 : deleteFiscalCalendar():管理财政日历.
copaApi.periodManagement.createHolidayCalendar() 编号 : listHolidayCalendars() 编号 : getHolidayCalendar() 编号 : updateHolidayCalendar() 编号 : deleteHolidayCalendar(): 管理节日日历.
copaApi.periodManagement.listHolidays() 编号 : importHolidays(): 列出或批量进口节假日.

数据框

copaApi.databox.getDataboxFolder() 编号 : getDataboxFolderFiles() 编号 : getDataboxFolderDatasets() 编号 : getDataboxFolderDuplicates(): 读取一个数据箱文件夹及其内容.
copaApi.databox.getDataboxFolderSchema() 编号 : updateDataboxFolderSchema() 编号 : getDataboxSchemaHistory():管理文件夹的图案.
copaApi.databox.dropFileToDatabox() 编号 : runDataboxFolder(): 上传文件/运行文件夹处理.
copaApi.databox.getDataboxFile() 编号 : getDataboxFileStatus() 编号 : getDataboxFileRuns() 编号 : getDataboxFileDownloadUrl(): 读取一个数据箱文件.
copaApi.databox.getDataboxTrashFiles() 编号 : trashDataboxFiles() 编号 : restoreDataboxFile() 编号 : permanentDeleteDataboxFiles():倒垃圾生命周期.

吨数

TCN(接触-中心)集成. 选中的函数 :

copaApi.tcn.getAuthUrl() 编号 : exchangeCode() 编号 : refreshToken():OAuth流量.
copaApi.tcn.getCurrentAgent() 编号 : getAgentSkills() 编号 : createSession() 编号 : keepAlive(): 代理会话生命周期.
copaApi.tcn.agentGetStatus() 编号 : agentSetReady() 编号 : agentPause() 编号 : agentDisconnect():代理状态.
copaApi.tcn.agentGetConnectedParty() 编号 : getCallData() 编号 : agentPutCallOnHold() 编号 : agentGetCallFromHold():主动调用控制.
copaApi.tcn.getHuntGroupAgentSettings() 编号 : dialManualPrepare() 编号 : manualDialStart() 编号 : processManualDial() 编号 : ftpManualDialReport():手动拨号.

模板

copaApi.templates.renderTemplate(): 用给定的引擎和数据渲染出一个模板.

管道

copaApi.pipeline.getPipelines() 编号 : getPipelineList():列出管线(全/轻).
copaApi.pipeline.getPipelineRuns() 编号 : getPipelineRunStatus():运行和运行状态.
copaApi.pipeline.getPipelineDefinition() 编号 : buildDatasetDefinition(): 读取/构建定义.
copaApi.pipeline.getPipelineOverview():获取输入/输出概览.
copaApi.pipeline.startOutputSample() 编号 : getOutputSampleResult():输出-样本工作.
copaApi.pipeline.savePipeline() 编号 : runPipeline(): 保存/运行 (hub).

正在工作纸张

copaApi.workingPaper.getWorkingPapers() 编号 : getWorkingPaper() 编号 : createWorkingPaper() 编号 : updateWorkingPaper() 编号 : deleteWorkingPaper()工作文件:CRUD.
copaApi.workingPaper.createFxDatasetDefinition() 编号 : fxBaseTable() 编号 : addRuleFilter() 编号 : addSort() 编号 : addMetric() 编号 : addPivot() 编号 : addColumn(): Fx-定义成份帮助器.

解决方案

copaApi.solutions.getSolutionList(): 列出解决方案.
copaApi.solutions.create():创建解决方案.
copaApi.solutions.packagableComponents(): 列出可组合组件.
copaApi.solutions.addObjects(): 将对象添加到解决方案中.
copaApi.solutions.validate() 编号 : publish() 编号 : publishJob():验证,公布,并选取出版工作.
copaApi.solutions.setSolutionSeedData(): 设置部署时间种子数据.

版本

copaApi.versioning.getBranches() 编号 : createBranch() 编号 : pushBranch() 编号 : mergeBranches(): 分行业务.
copaApi.versioning.listCommits() 编号 : commitChanges() 编号 : listTags(): 提交和标签.

外部附录

copaApi.externalApps.create(): 创建外部应用程序.
copaApi.externalApps.setEnv() 编号 : setSchemaMap() 编号 : setAccessControl():配置env, schema映射,和访问控制.
copaApi.externalApps.validateUrl():验证一个外部应用程序 URL.

中心模块`/blui-api`(中文(简体) )

这些攻击目标为: hubClient。。。 .

工作手册 (呼声): create(), (中文(简体) ), listWorkbooks(), (中文(简体) ), getWorkbook()。。。 .
连接 (呼声): createSftpConnection(), (中文(简体) ), createEmailConnection(), (中文(简体) ), createBlobConnection(), (中文(简体) ), testConnection(), (中文(简体) ), listConnections()。。。 .
摄入量 (呼声): createDatabox(), (中文(简体) ), createFileboxFolder(), (中文(简体) ), listDataboxes(), (中文(简体) ), listFileboxFolders()。。。 .
输入表V2 (呼声): listInputTables(), (中文(简体) ), getInputTable(), (中文(简体) ), createInputTable(), (中文(简体) ), deleteInputTable(), (中文(简体) ), getInputTableSchema(), (中文(简体) ), readInputTableRows(), (中文(简体) ), insertInputTableRows(), (中文(简体) ), updateInputTableRows(), (中文(简体) ), deleteInputTableRows()。。。 .
工作流程V2 (呼声): listWorkflows(), (中文(简体) ), getWorkflow(), (中文(简体) ), saveWorkflow()。。。 .
进程 (呼声): registerTrigger(), (中文(简体) ), deleteTrigger(), (中文(简体) ), executeTriggerNow(), (中文(简体) ), pauseTrigger(), (中文(简体) ), resumeTrigger(), (中文(简体) ), skipTrigger(), (中文(简体) ), triggerScheduleStatus(), (中文(简体) ), upcomingSchedules(), (中文(简体) ), triggersBySheet(), (中文(简体) ), sheetRuns(), (中文(简体) ), sheetRunStatus()。。。 .
数据集Hub (呼声): getDatasetSchema(), (中文(简体) ), searchDatasets(), (中文(简体) ), getDatasetStats()。。。 .
虚拟数据 (呼声): listVirtualDatasets(), (中文(简体) ), getVirtualDataset(), (中文(简体) ), createVirtualDataset()。。。 .
导出配置 (呼声): listExportConfigs(), (中文(简体) ), getExportConfig(), (中文(简体) ), createExportConfig(), (中文(简体) ), updateExportConfig(), (中文(简体) ), runExportConfig()。。。 .
仪表板 (呼声): listDashboards(), (中文(简体) ), getDashboard(), (中文(简体) ), createDashboard(), (中文(简体) ), addDashboardWidget(), (中文(简体) ), updateDashboardWidget(), (中文(简体) ), removeDashboardWidget()。。。 .
httpTriggers Hub (英语) (呼声): listHttpTriggers(), (中文(简体) ), getHttpTrigger()。。。 .

顶级出口

再说 copaApi,套接字根导出 :

copaSetConfig 编号 : copaGetConfig ——设置/读取SDK配置.
hubClient - Axios的委托人,负责调查 /blui-api 中枢( 认证/ 工作空间/ 解决方案信头相同 ) apiClient目标 config.hubBaseUrl 或从 apiBaseUrl) (中文(简体) ). 用于中心端点,尚未被包入 copaApi.* 模块.
copaUtils - 公用事业助手,包括 copaUtils.websocketUtils.WebsocketContextFactory (见 WebSocket 连接) (中文(简体) ).
copaInputTableDb ——被动输入表 DB 客户端,加 InputTableColumnType 财务报告和审定财务报表 InputTableError (见下文).
copaTailwindConfig ——共享的"蓝科帕"(Bluecopa Tailwind)配置.

根还再出口一大批类型Script( 审计, 侦察 v2, 管道) sDK消费者的节点目录等).

输入表DB — 反应数据库客户端

用于查询和订阅 Bluecopa 输入表 V2 数据的类似 Firebase 客户端。不需要输入——只是导入和使用.

完整的 SDK 指南 ——包含架构细节,错误处理,框架集成(Svelte/React)等所有可用功能的全面文档.

快速启动

import { copaSetConfig, copaInputTableDb } from '@bluecopa/core';

// Configure once at app startup
copaSetConfig({
    apiBaseUrl: 'https://develop.bluecopa.com/api/v1',
    accessToken: 'your-token',
    workspaceId: 'ws-123',
    solutionId: 'sol-abc' // optional — falls back to SOLUTION_ID cookie
    // websocketProvider: ws — optional, enables realtime sync (see "WebSocket Provider" below)
});

// 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 unsubCount = copaInputTableDb.collection('invoices').count((n) => console.log(n));

查询运算符

运算符	含义
`==`	等于
`!=`	不等于
`<`	小于
`<=`	小于或当量
`>`	大于
`>=`	gte 调用
`in`	数组
`not-in`	未在阵列中

总计查询

计算服务器侧总和( U)sum, (中文(简体) ), avg, (中文(简体) ), count, (中文(简体) ), min, (中文(简体) ), max)不取出出出行. 组合到 where(), (中文(简体) ), limit(),以及 skip() 过滤器.

// 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() 是一个 终端方法 ——它绕过本地RxDB并直接点击PostgREST. 丢出错误 InputTableError空光谱 {} 返回时 {} 没有给API打电话.

分组汇总

添加一个 { groupBy: [...columns] } 第二个参数以获得每组分解。返回数组而不是单个对象.

// 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 } }]

// 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" }]

注释:

orderBy() 当 groupBy 存在(另作说明)
limit()编号 :skip() 适用于数量组输入行
无法同时在集合光谱和 groupBy - 掷出 InputTableError
空 groupBy: [] 行为类似没有组By——返回单个对象

框架整合

斯维尔特5号

<script>
  import { copaInputTableDb } from "@bluecopa/core";
  let rows = $state([]);

  $effect(() =>
    copaInputTableDb.collection("invoices")
      .where("status", "==", "pending")
      .subscribe((r) => { rows = r; })
  );
</script>

反应

useEffect(() => {
    return copaInputTableDb
        .collection('invoices')
        .where('status', '==', 'pending')
        .subscribe(setRows);
}, []);

香草联署材料

const unsub = copaInputTableDb.collection('invoices').subscribe(setRows);
// later:
unsub();

WebSocket 提供者( 可选)

通过推而不是投票实现实时同步 :

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);

如果没有设置提供者,SDK仍然通过HTTP拉式复制工作,并登录一个控制台警告.

清理

await copaInputTableDb.destroy(); // closes all collections + WebSocket

WebSocket 连接

核心软件包提供WebSocket公用设备,用于使用Centrifugo(和Pusher)进行实时通信.

网索厂

import { copaUtils } from '@bluecopa/core';

const websocket = copaUtils.websocketUtils.WebsocketContextFactory.create('centrifugo', {
    connectionUrl: 'wss://your-centrifugo-url'
});

WebSocket 提供者接口

这个 IWebsocketProvider 接口提供:

connect(): 建立连接
bind(channel, event, callback): 订阅私人用户专用频道
bindGlobal(event, callback): 订阅全局频道
unbindAll(channel): 取消对频道上所有事件的订阅
disconnect(): 关闭连接

WebSocket 用法示例

import { copaSetConfig, copaUtils } from '@bluecopa/core';

copaSetConfig({
    apiBaseUrl: 'https://develop.bluecopa.com/api/v1',
    accessToken: 'your-access-token',
    workspaceId: 'your-workspace-id',
    userId: 'your-user-id'
});

const websocket = copaUtils.websocketUtils.WebsocketContextFactory.create('centrifugo', {
    connectionUrl: 'wss://centrifugo.your-domain.com/connection/websocket'
});

websocket.bind('notifications', 'new_message', (data) => {
    console.log('New notification:', data);
});

websocket.bindGlobal('system_updates', (data) => {
    console.log('System update:', data);
});

websocket.disconnect();

WebSocket 要求

用户编号: 私人频道订阅所需(bind(中文(简体) )
访问脚本: 认证离心机所需
连接Url: WebSocket 端点 URL

连接自动使用配置 accessToken 财务报告和审定财务报表 userId 用于认证和信道绑定.

实例

配置, 然后获取输入表

import { copaSetConfig, copaApi } from '@bluecopa/core';

copaSetConfig({
    apiBaseUrl: 'https://api.example.com',
    accessToken: 'token',
    workspaceId: 'ws1',
    userId: 'user123'
});

const inputTables = await copaApi.inputTable.getInputTables();

按类型获得工作簿

import { copaApi } from '@bluecopa/core';

try {
    const workbooks = await copaApi.workbook.getWorkbooksByType('dashboard');
    console.log(workbooks);
} catch (error: any) {
    console.error(error.message, error.status);
}

发展

构建 : npm run build (视频) - npm run build:umd 用于 UMD 捆绑
监视 : npm run dev
测试 : npm run test 编号 : npm run test:watch 编号 : npm run test:coverage
类型脚本配置 : tsconfig.json (英语); 虚拟配置 : vite.config.ts (英语)

@ 蓝色copa/ react ——在这些核心API上反应查询钩
创建- 蓝色copa- react- app – CLI 用于脚手架 Bluecopa React MFE

版本与发布记录

@bluecopa/core 共发布 122 个版本，首次发布于 2025/09/05；过去 12 个月发布了 109 个版本。

版本	发布日期	距今
`0.1.127`latest	2026/10/13	25 天前
`0.1.126`	2026/09/21	1 个月前
`0.1.125`	2026/09/16	1 个月前
`0.1.124`	2026/09/07	2 个月前
`0.1.123`	2026/09/02	2 个月前
`0.1.122`	2026/08/17	2 个月前

关于 @bluecopa/core 的常见问题

@bluecopa/core 是什么？

核心包是Bluecopa的TypeScript API SDK. 它提供了一个配置的 Axios 客户端,一个命名的空格 API 表面(copaApi.*)覆盖了每个平台域,一个被整理的api/hub客户端,一个类似 Firebase 的反应式输入表 DB, Centrifugo/Pusher WebSocket

如何安装 @bluecopa/core？

在项目目录运行 npm install @bluecopa/core，或使用 pnpm add / yarn add / bun add。

@bluecopa/core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@bluecopa/core 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module，更早的版本需要改用动态 import()。

@bluecopa/core 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js ^20.19.0 || >=22.12.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@bluecopa/core 可以商用吗？

@bluecopa/core 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@bluecopa/core 的下载量有多少？

根据 npm 官方下载统计，@bluecopa/core 在 2026/10/09 – 2026/11/07 这 30 天内被下载 9,873 次，日均约 329 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@bluecopa/core 还在维护吗？

最新版本 0.1.127 发布于 2026/10/13（25 天前）；至今共发布 122 个版本，其中过去 12 个月发布了 109 个；首次发布于 2025/09/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。