# @basis-theory/web-agentic 中文文档

规范地址：https://npmcn.com/package/%40basis-theory/web-agentic/

版本：1\.4\.1
npm 元数据更新时间：2026-11-02T18:33:34.221Z
中文译文更新时间：2026-11-07T18:02:30.320Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40basis-theory/web-agentic
原文对照：https://npmcn.com/package/%40basis-theory/web-agentic/?lang=original
项目主页：https://developers.basistheory.com/docs/sdks/agentic/web-agentic
源码仓库：https://github.com/Basis-Theory/web-agentic

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

- 包体积（解压后）：177 kB，25 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-08-05T12:41:50.733Z
- 最新版本发布：2026-10-02T17:08:39.843Z
- 近 30 天下载量：72046（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

基础理论代理支付浏览器 SDK

## 安装

```sh
npm install @basis-theory/web-agentic
```

也可以使用：`pnpm add @basis-theory/web-agentic`、`yarn add @basis-theory/web-agentic`、`bun add @basis-theory/web-agentic`

## README

# @ basis-理论/网络代理

[![npm](https://img.shields.io/npm/v/@basis-theory/web-agentic)](https://www.npmjs.com/package/@basis-theory/web-agentic) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)

`@basis-theory/web-agentic` 是浏览器的一面 [基础理论代理付款](https://developers.basistheory.com/docs/guides/agentic/overview)数字 : {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}所有需要帮助的 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}我需要一个 私钥留在您的服务器上 。 SDK包括: **`AgenticVerification`**, (中文(简体) ), 运行提供方仪式,以验证客户并激活 备用铁道.

这个 README 覆盖了安装和足够的 API 运行第一个 核查。 完整的参考资料——每个选项、错误和整合 模式——处于 [SDK 文档](https://developers.basistheory.com/docs/sdks/agentic/web-agentic)。 。 。 .

## 安装

```bash
npm install @basis-theory/web-agentic
```

TypeScript声明包含在内,而SDK没有运行时间依赖性.

或者装上全球包裹 释放到不可改变的版本路径—— 被钉入 准确版本( 没有) `latest`并取其散去从兄弟会 `sri.json`数字 :

```html
<script
  src="https://js.basistheory.com/web-agentic/1.2.0/index.js"
  integrity="sha384-…"
  crossorigin="anonymous"
></script>
```

捆绑发布整个SDK `window.BasisTheoryAgentic` 下划线 相同名称 npm 导出,所以下面的每一个示例都通过互换其 `import` 建筑结构:

```js
// npm
import { AgenticVerification, ApiError } from '@basis-theory/web-agentic';

// script tag
const { AgenticVerification, ApiError } = window.BasisTheoryAgentic;
```

## 代理验证

需要核查的备抵栏在 `pending_verification`,只有供应商自己拥有的仪式才能 启动它. `AgenticVerification` 运行仪式: 它推进 \* 核查状态机器,使每个迎合客户的步骤,并解决 当铁路是 `active`。 。 。 .

### 快速启动

创建一个 **公开** 应用程序 [基础理论门户](https://portal.basistheory.com/) 仅限 `agentic:allowance:verify` 允许.

```js
import { AgenticVerification } from '@basis-theory/web-agentic';

const av = AgenticVerification({
  apiKey: 'key_test_us_pub_REPLACE_ME', // PUBLIC application key
  apiBaseUrl: 'https://api.test.basistheory.com/agentic',
  displayName: 'Example Agent',
});

// Read `provider` from the allowance rail — never infer it.
const result = await av.verifyAllowance('alw_...', { provider: 'vic' });
console.log(`Rail is ${result.status} on ${result.provider}`);
```

如果客户放弃流量,则再次提出核查——没有 清净步. 浏览器发送的任何信息都无法单独激活一条栏; Basic 理论确认每个终端与提供者服务器到服务器的过渡.

> **从不将私钥放入浏览器中.** 公共密钥为浏览器安全 设计; SDK 如果 `apiKey` 包含 `_pvt_`。 。 。 .

| 环境 | `apiBaseUrl` |
| --- | --- |
| 生产 | `https://api.basistheory.com/agentic` (默认) |
| 测试 | `https://api.test.basistheory.com/agentic` |
| 当地运行 `agentic-commerce` | `http://localhost:3001/api` |

### 浏览器要求

-   **HTTPS 顶级来源** 仪式需要安全的环境。 当地: `cloudflared tunnel --url http://localhost:3000`。 。 。 .
-   **社区支助方案** —— 说 `frame-src` 必须允许任何仪式的起源 iframe 验证 响应返回; `connect-src` 必须允许您 `apiBaseUrl` 或习惯 运输端点; 随着全球捆绑, `script-src` 必须允许 CDN 剧本. SDK没有装入遥测或外部UI资产.
-   **弹出** ——大多数仪式从用户姿态打开窗口;内置 间歇提供它。 内容屏蔽器也可以停止主机iframes.

### 值得了解的行为

-   `verifyAllowance(allowanceId, { provider, rail?, displayName?, timeoutMs?, signal? })` 决定 `{ status: 'active', rail, provider }`。 。 。 . `rail` 默认为 `'agentic-token'`,并终止 `signal` 拒绝方式 `VerificationCancelledError`。 。 。 .
-   支持的铁路/提供者对: `agentic-token`编号 :`vic` (维萨), `agentic-token`编号 :`agentpay` (硕士)和 `virtual-card`编号 :`link` (按键) 链接). 名称 `rail: 'virtual-card'` 明确为林克. 任何其它东西 `ConfigurationError` 在发出任何请求之前.
-   电话是连续的——一个在飞行时打第二通电话。 正在验证 已经..`active` 铁路在不举行仪式的情况下解决,铁路也是如此 无需举行持卡人仪式(授权的花纹链接津贴, 消费者在连接钱包时批准了一次.
-   `dispose()` 中止任何飞行中验证 并撕下iframes,弹出, 收听者和UI主机;在飞行中的跑跑 撕裂完成作为 运行和解。 它具有特异性,使实例可以使用,因此重新挂起 -- 反应严格模式,快速刷新——可以立即再次核实,不进行 等待中止运行 .
-   每次启动和重启时自动收集设备上下文; `collectDeviceContext` 用于海关运输.

如果你通过一个完整的 `strings` 对象,注意此释放添加 `linkRedirectTitle` 财务报告和审定财务报表 `linkRedirectSubtitle`。您不提供的密钥退后 到英语默认值,所以本地化的集成使得英语在Link上 暂停,直到你加入它们.

工厂还接受主题,无头,运输和调试选项—— [工厂选项](https://developers.basistheory.com/docs/sdks/agentic/web-agentic#factory-options) 全部记录.

### 活动

`onEvent` 接收这些对象。 调用时抛出例外被忽略 因此,可观察性不能中断核查.

| `type` | 其他领域 |
| --- | --- |
| `state_change` | `allowanceId`, (中文(简体) ), `action`, (中文(简体) ), `status`, (中文(简体) ), `nextActionType` |
| `ceremony_open` | `network`签证活动还包括: `action` |
| `restart` | `reason`数字 : `register_complete`, (中文(简体) ), `state_invalid`,或 `user_retry` |
| `error` | `error` ——完全错误值 |
| `success` | `allowanceId` |

### 错误

SDK 扩展产生的错误 `AgenticVerificationError`。 。 。 .

```js
import {
  ApiError,
  VerificationCancelledError,
  VerificationNotSupportedError,
} from '@basis-theory/web-agentic';

try {
  await av.verifyAllowance('alw_...', { provider: 'vic' });
} catch (error) {
  if (error instanceof VerificationCancelledError) return; // safe to offer again
  if (error instanceof VerificationNotSupportedError) return; // offer another payment method
  if (error instanceof ApiError) {
    console.error(error.type, error.status, error.traceId); // quote traceId to support
  }
  throw error;
}
```

`ApiError.type` 是一个 **打开集** - 永远不要彻底改变. `PopupBlockedError` 从新点击可恢复, SDK 重试 `INVALID_OTP` 设立和 `409 *_IN_PROGRESS` 与极限的后退。 每个 类和每类行为: [处理出错](https://developers.basistheory.com/docs/sdks/agentic/web-agentic#handle-errors)。 。 。 .

### 自定义

每个表面都是可替换的,而不放弃SDK对iframes的所有权, 弹出、协议和投票:

-   **内容和副本** —— 说 `appearance` (六色 k取出 `strings` 重新样式 内置的阴影 DOM UI , 它两相隔开, 使零 外部请求. [自定义 UI](https://developers.basistheory.com/docs/sdks/agentic/web-agentic#customize-the-ui)
-   **无头** —— 说 `ui: false` 与 `handlers` 带来自己的UI;通过一个 单处理器 `ui: true` 超过这个提示。 硬规则是: `confirmCeremony` 必须调用所供应的 `openPopup` 内部同步 单击处理器, 在任何操作器之前 `await`,或浏览器取消用户手势. [带上自己的UI](https://developers.basistheory.com/docs/sdks/agentic/web-agentic#bring-your-own-ui)
-   **自定义运输** —— 说 `verify` 财务报告和审定财务报表 `getAllowance` 路由 API 调用 您自己的后端, 而不是使用公钥; 仪式仍然在 浏览器. [路由 API 通过您的后端调用](https://developers.basistheory.com/docs/sdks/agentic/web-agentic#route-api-calls-through-your-backend)

## 测试

在一个测试的租户中,仪式与Basy Theory主持模拟网页相对应 说出确切的生产协议,没有请求到达提供者. 切换 `4242424242424242` (维萨)或 `5555555555554444` (硕士) 快乐的道路 [测试参考](https://developers.basistheory.com/docs/api/agentic-commerce/testing) 列出每个失败情景的测试源.

## 浏览器支持

常绿乔木、边缘、火狐和Safari 16.4 (WebAuthn基线),开通 桌面和移动网络。 导入 SDK 是安全的 SSR , 但构建 客户端访问 DOM : 在挂载或内创建实例 只使用客户端的边界,然后在卸载时处理。 对于网页视图和本地 贝壳见 [浏览器支持](https://developers.basistheory.com/docs/sdks/agentic/web-agentic#browser-support)。 。 。 .

## 许可证

[阿帕奇 - 2.0](https://www.apache.org/licenses/LICENSE-2.0)

## 常见问题

### @basis-theory/web-agentic 是什么？

基础理论代理支付浏览器 SDK

### 如何安装 @basis-theory/web-agentic？

在项目目录运行 npm install @basis-theory/web-agentic，或使用 pnpm add / yarn add / bun add。

### @basis-theory/web-agentic 支持 TypeScript 吗？

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

### @basis-theory/web-agentic 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @basis-theory/web-agentic 需要什么版本的 Node\.js？

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

### @basis-theory/web-agentic 可以商用吗？

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

### @basis-theory/web-agentic 的下载量有多少？

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

### @basis-theory/web-agentic 还在维护吗？

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