# @agenticprimitives/connect-client 中文文档

规范地址：https://npmcn.com/package/%40agenticprimitives/connect-client/

版本：1\.0\.0-alpha\.36
npm 元数据更新时间：2026-10-26T11:48:11.197Z
中文译文更新时间：2026-11-06T16:34:45.211Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40agenticprimitives/connect-client
原文对照：https://npmcn.com/package/%40agenticprimitives/connect-client/?lang=original
项目主页：https://agenticprimitives.dev/
源码仓库：https://github.com/agentictrustlabs/agenticprimitives

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

- 包体积（解压后）：79.6 kB，28 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-07-01T10:44:08.160Z
- 最新版本发布：2026-10-26T11:48:10.391Z
- 近 30 天下载量：2733（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：32（近 12 个月 32 个）

## 中文简介

通用依赖方连接客户端:手交给中央-自动之家(FedCM-first → OIDC transferm/poup),将代码交换给SA署名的放范围代表团. 依赖光谱230/259的一半;没有证书永远起源于依赖的应用程序.

## 安装

```sh
npm install @agenticprimitives/connect-client
```

也可以使用：`pnpm add @agenticprimitives/connect-client`、`yarn add @agenticprimitives/connect-client`、`bun add @agenticprimitives/connect-client`

## README

# @ agenticprimitives/ 连接客户端

> 部分 **[代理先导](https://agenticprimitives.dev/)** ——代理应用程序的开源信任底板:可以签名的身份,行为时间检查权限,所有者携带的证据. [开发者工具包](https://github.com/agentictrustlabs/agentic-primitives) • 妇女 [所有软件包](https://agenticprimitives.dev/developers)

这个 **依赖方** 连接的一半。 依赖的应用程序不会使证书或OAuth请求本身:它手接 关闭到用户的中央原子 **内容** (IdP)——主持证书仪式(wallet / Google /) YouVersion / passkey)和监护权——并带回由SA署署名的放箭代表团. 标准OIDC (单位:千美元)`authorize → code → /token`与无缝 **FedCM 首个** 前面 。 .

见 [第295区](https://npmcn.com/package/specs/295-relying-connect-client.md), (中文(简体) ), [第230区/259区](https://npmcn.com/package/specs/259-relying-idp-responsibility-split.md), (中文(简体) ), [ADR-0019 (英语)](https://npmcn.com/package/docs/architecture/decisions/0019-relying-site-authority-is-a-scoped-delegation.md), (中文(简体) ), [ADR-0021 (英语)](https://npmcn.com/package/docs/architecture/decisions/0021-generic-packages-vs-white-label-apps.md), (中文(简体) ), [ADR-0032 (英语)](https://npmcn.com/package/docs/architecture/decisions/0032-fedcm-delegation-via-substrate-grant-endpoint.md)。 。 。 .

## 为什么

YouVersion/ Google OAuth 客户端为 **由登记在册的原籍**如果依赖应用程序 来源于 OAuth 本身( 来源于它自己), 严格的提供者拒绝它 。 定律——和学说—— 是 Home 是单一的证书/ Outh 来源; 依赖应用程序只交换返回代码 。 这个 软件包是依赖边协议, 提取一次而不是复制每个应用程序.

## 使用量

```ts
import { createConnectClient, connectViaFedcm, connectViaPopup, connectViaRedirect } from '@agenticprimitives/connect-client';

// The app injects its domain.ts — NO hostnames live in this package (ADR-0021).
const connect = createConnectClient({
  clientId: 'demo-web',
  delegate: '0x…',                       // the relying-site backend account the Home scopes its grant to
  redirectUri: () => window.location.origin + '/',
  resolveAuthOrigin: (name) => resolveHomeOrigin(name),   // app: name → <home> | apex
  isAllowedIssuerOrigin: (o) => isAllowedHome(o),         // app: issuer allowlist
});

// FedCM-first, then popup, then redirect (the seamless launcher):
try {
  const r = await connectViaFedcm(await resolveHomeOrigin(''), 'demo-web', onProgress);
  // r.idToken + r.delegation — done, no /token round-trip
} catch {
  const p = await connectViaPopup(connect, name, 'demo-web-connect-relay', onProgress, signal);
  if (p.status === 'blocked') {
    const { url, stash } = await connectViaRedirect(connect, name);
    sessionStorage.setItem('connect', JSON.stringify(stash));
    window.location.href = url;                            // returns ?code&state
  } else if (p.status === 'success') {
    const tok = await connect.exchangeCode(p.authOrigin, p.code, p.codeVerifier);
    await connect.verifyIdToken(p.authOrigin, tok.idToken, p.stash.nonce);
  }
}
```

打开 `?code&state` 返回(方向路径),读取隐藏, `exchangeCode`,则 `verifyIdToken`。 。 。 .

## 边界

唯倚侧相. 经纪人/家庭一方是 `@agenticprimitives/connect`;证书仪式在 Ưμ㼯A`connect-auth`) (中文(简体) ). 只导入此套件 `@agenticprimitives/types` + 键 `@agenticprimitives/fedcm-rp`, (中文(简体) ), 是 WebCrypto 的,没有主机名.

## 常见问题

### @agenticprimitives/connect-client 是什么？

通用依赖方连接客户端:手交给中央-自动之家\(FedCM-first → OIDC transferm/poup\),将代码交换给SA署名的放范围代表团\. 依赖光谱230/259的一半;没有证书永远起源于依赖的应用程序\.

### 如何安装 @agenticprimitives/connect-client？

在项目目录运行 npm install @agenticprimitives/connect-client，或使用 pnpm add / yarn add / bun add。

### @agenticprimitives/connect-client 支持 TypeScript 吗？

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

### @agenticprimitives/connect-client 支持 ESM 还是 CommonJS？

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

### @agenticprimitives/connect-client 可以商用吗？

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

### @agenticprimitives/connect-client 的下载量有多少？

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

### @agenticprimitives/connect-client 还在维护吗？

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