@ basis-理论/网络代理

@basis-theory/web-agentic 是浏览器的一面 基础理论代理付款数字 : {\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 文档。 。 。 .

安装

npm install @basis-theory/web-agentic

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

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

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

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

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

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

代理验证

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

快速启动

创建一个 公开 应用程序 基础理论门户 仅限 agentic:allowance:verify 允许.

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_。 。 。 .

浏览器要求

• 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上 暂停,直到你加入它们.

工厂还接受主题,无头,运输和调试选项—— 工厂选项 全部记录.

活动

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

错误

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

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 与极限的后退。 每个 类和每类行为: 处理出错。 。 。 .

自定义

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

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

测试

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

浏览器支持

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

许可证

阿帕奇 - 2.0