# @happy-technologies/connector-core 中文文档

规范地址：https://npmcn.com/package/%40happy-technologies/connector-core/

版本：0\.3\.0
npm 元数据更新时间：2026-07-10T21:30:12.093Z
中文译文更新时间：2026-11-17T19:51:28.824Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40happy-technologies/connector-core
原文对照：https://npmcn.com/package/%40happy-technologies/connector-core/?lang=original
项目主页：https://github.com/Happy-Technologies-LLC/happy-connector-core#readme
源码仓库：https://github.com/Happy-Technologies-LLC/happy-connector-core

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

- 包体积（解压后）：146 kB，73 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-06-21T10:49:06.362Z
- 最新版本发布：2026-07-10T21:30:11.976Z
- 近 30 天下载量：4459（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

Happy Technologies产品的共享连接子底盘: express/description schema,一个通用的注册,配置验证,以及 OAuth/证书底盘. 域-不可知;产品提供自己的连接器合同,密码和存储.

## 安装

```sh
npm install @happy-technologies/connector-core
```

也可以使用：`pnpm add @happy-technologies/connector-core`、`yarn add @happy-technologies/connector-core`、`bun add @happy-technologies/connector-core`

## README

# @happy-technology/连接器-核心

快乐科技产品共享接通基底. 它提供 连接器平台中产品完全相同的部分,没有 具体如下:

-   说明/说明计划`ConnectorDescriptor`: 单一来源 连接器元数据的真实性,驱动配置验证,目录,以及 登记表.
-   通用软件 `ConnectorRegistry<T>`: 注册连接器, 查找它们, 列出 目录, 验证配置 。 替换已关闭的enum和DB CHECK限制.
-   描述器驱动的配置验证,包括拒绝的守护 非秘密配置路径上的证书形状密钥 .
-   OAuth 和 证书底盘(`OAuthSubstrate`: 授权码 流,令牌刷新,并加密令牌存储,被注入接口后.
-   可选的单证连接合同(`SourceConnector`用于产品 摄入文件.

## 设计边界

此软件包拥有元数据、 登记力学、 验证和认证 管弦乐 它不拥有:

-   出品域逻辑(编译为文物,与CIS相协调).
-   密码 你注射一个 `SecretCipher`。 。 。 .
-   存储。 你注射一个 `CredentialStore` 可选 `OAuthStateStore`。 。 。 .
-   一个特定的 OAuth 库. 您给每个提供者注射 `OAuthClient` 实例.

这是让认证后端稍后被互换的接合器( 例如到一个 自我托管的"南戈"),没有触摸连接器代码.

## 将OAuth基底与北极连接

北极地区(`arcticjs.dev`, MIT)为微软提供打入了 OAuth 2.0 客户端 Entra ID, Google, Atlassian, GitHub, Slack, 等. 星洲网. 北极的标志对象 暴露方法`accessToken()`),将每个客户端包装到 `OAuthClient` 形状

```ts
import * as arctic from "arctic";
import { OAuthSubstrate, type OAuthClient } from "@happy-technologies/connector-core";

function wrap(provider: {
  createAuthorizationURL: (state: string, codeVerifier: string, scopes: string[]) => URL;
  validateAuthorizationCode: (code: string, codeVerifier: string) => Promise<arctic.OAuth2Tokens>;
  refreshAccessToken: (refreshToken: string, scopes?: string[]) => Promise<arctic.OAuth2Tokens>;
}): OAuthClient {
  const toTokens = (t: arctic.OAuth2Tokens) => ({
    accessToken: t.accessToken(),
    refreshToken: t.hasRefreshToken() ? t.refreshToken() : undefined,
    accessTokenExpiresAt: t.accessTokenExpiresAt(),
  });
  return {
    createAuthorizationURL: (state, verifier, scopes) =>
      provider.createAuthorizationURL(state, verifier, scopes),
    validateAuthorizationCode: async (code, verifier) =>
      toTokens(await provider.validateAuthorizationCode(code, verifier)),
    refreshAccessToken: async (refreshToken, scopes) =>
      toTokens(await provider.refreshAccessToken(refreshToken, scopes)),
  };
}

const google = new arctic.Google(clientId, clientSecret, redirectUri);

const oauth = new OAuthSubstrate({
  clients: new Map([["google", wrap(google)]]),
  credentials: myCredentialStore, // backed by your DB + envelope crypto
  cipher: myEnvelopeCipher,        // encryptSecret / decryptSecret
});

// In a fetch path:
const cred = await oauth.resolve(sourceId);
const res = await fetch(url, { headers: cred.headers });
```

对于客户端证书/只应用的赠款(微软图形只应用,ServiceNow) 服务账户),执行 `OAuthClient` 直接在一个符号端点上,或 使用情况 `openid-client`。 。 。 .

## 脚本

-   `bun test` 运行单元套房.
-   `bun run type-check` 运行 `tsc --noEmit`。 。 。 .
-   `bun run build` 发射 `dist/` 与声明.
-   `bun run check:no-em-dash` 执行 org 内容规则.

## 状态

v0.1: 底部核心(描述、登记、验证、认证、文档) 合同),并附有测试. 首先由"快乐知识"(Happy Knowledge;HappyCMDB)所拥有 框架随时间推移而迁移到同样的明确计划.

## 常见问题

### @happy-technologies/connector-core 是什么？

Happy Technologies产品的共享连接子底盘: express/description schema,一个通用的注册,配置验证,以及 OAuth/证书底盘\. 域-不可知;产品提供自己的连接器合同,密码和存储\.

### 如何安装 @happy-technologies/connector-core？

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

### @happy-technologies/connector-core 支持 TypeScript 吗？

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

### @happy-technologies/connector-core 支持 ESM 还是 CommonJS？

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

### @happy-technologies/connector-core 可以商用吗？

@happy-technologies/connector-core 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @happy-technologies/connector-core 的下载量有多少？

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

### @happy-technologies/connector-core 还在维护吗？

最新版本 0\.3\.0 发布于 2026/07/11（4 个月前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/06/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

