# @bluecopa/core 中文文档

规范地址：https://npmcn.com/package/%40bluecopa/core/

版本：0\.1\.127
npm 元数据更新时间：2026-10-13T13:39:09.809Z
中文译文更新时间：2026-11-08T08:24:30.376Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bluecopa/core
原文对照：https://npmcn.com/package/%40bluecopa/core/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.1 MB，433 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^20\.19\.0 \|\| \>=22\.12\.0
- 运行依赖：6 个
- 首次发布：2025-09-05T14:12:37.704Z
- 最新版本发布：2026-10-13T13:39:09.598Z
- 近 30 天下载量：9873（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：122（近 12 个月 109 个）

## 中文简介

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

## 安装

```sh
npm install @bluecopa/core
```

也可以使用：`pnpm add @bluecopa/core`、`yarn add @bluecopa/core`、`bun add @bluecopa/core`

## README

# @ 蓝色copa/ 核心 [![npm version](https://img.shields.io/npm/v/@bluecopa/core)](https://www.npmjs.com/package/@bluecopa/core) [![License](https://img.shields.io/npm/l/@bluecopa/core)](https://github.com/bluecopa/blui/blob/main/packages/core/LICENSE)

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

## 目录

-   [安装](https://npmcn.com/package/%40bluecopa/core/#readme-installation)
-   [所需资源](https://npmcn.com/package/%40bluecopa/core/#readme-requirements)
-   [配置](https://npmcn.com/package/%40bluecopa/core/#readme-configuration)
-   [API 参考](https://npmcn.com/package/%40bluecopa/core/#readme-api-reference)
-   [顶级出口](https://npmcn.com/package/%40bluecopa/core/#readme-top-level-exports)
-   [输入表DB — 反应数据库客户端](https://npmcn.com/package/%40bluecopa/core/#readme-inputtabledb--reactive-database-client)
-   [WebSocket 连接](https://npmcn.com/package/%40bluecopa/core/#readme-websocket-connection)
-   [实例](https://npmcn.com/package/%40bluecopa/core/#readme-examples)
-   [发展](https://npmcn.com/package/%40bluecopa/core/#readme-development)
-   [相关软件包](https://npmcn.com/package/%40bluecopa/core/#readme-related-packages)

## 安装

```bash
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通话前设定一次.

```typescript
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()` ——返回当前配置的副本.

### 配置接口

```typescript
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

```typescript
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 连接](https://npmcn.com/package/%40bluecopa/core/#readme-websocket-connection)) (中文(简体) ).
-   `copaInputTableDb` ——被动输入表 DB 客户端,加 `InputTableColumnType` 财务报告和审定财务报表 `InputTableError` (见下文).
-   `copaTailwindConfig` ——共享的"蓝科帕"(Bluecopa Tailwind)配置.

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

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

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

> **[完整的 SDK 指南](https://npmcn.com/package/%40bluecopa/core/docs/input-table-db-guide.md)** ——包含架构细节,错误处理,框架集成(Svelte/React)等所有可用功能的全面文档.

### 快速启动

```typescript
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();
```

### 拥挤

```typescript
// 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()` 过滤器.

```typescript
// 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] }` 第二个参数以获得每组分解。 返回数组而不是单个对象.

```typescript
// 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号**

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

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

**反应**

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

**香草联署材料**

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

### WebSocket 提供者( 可选)

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

```typescript
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拉式复制工作,并登录一个控制台警告.

### 清理

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

* * *

## WebSocket 连接

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

### 网索厂

```typescript
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 用法示例

```typescript
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` 用于认证和信道绑定.

## 实例

### 配置, 然后获取输入表

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

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

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

### 按类型获得工作簿

```typescript
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 (英语)](https://npmcn.com/package/%40bluecopa/core/tsconfig.json); 虚拟配置 : [vite.config.ts (英语)](https://npmcn.com/package/%40bluecopa/core/vite.config.ts)

## 相关软件包

-   [@ 蓝色copa/ react](https://www.npmjs.com/package/@bluecopa/react) ——在这些核心API上反应查询钩
-   [创建- 蓝色copa- react- app](https://www.npmjs.com/package/create-bluecopa-react-app) – CLI 用于脚手架 Bluecopa React MFE

## 常见问题

### @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 和提交记录判断。