> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK API 参考

> Agent Elements SDK 的构造参数、元素方法、挂载选项、事件与类型。

本页配合 [Agent Elements SDK 指南](https://docs.clinkbill.com/cn/guides/agent/agent_elements) 使用，指南中说明了各个流程和事件的处理方式。

> [!NOTE]
>
> SDK 运行在宿主页面的浏览器环境。卡片、凭据与 3DS 都由 Clink 托管的 iframe 处理，宿主只接收标识和事件。

## 安装

```bash theme={null}
npm install @clink-ai/agent-elements
```

```ts theme={null}
import { AgentElements } from '@clink-ai/agent-elements';
```

## `new AgentElements(options)`

创建 SDK 实例，并解析当前环境对应的 Clink 应用地址。

**environment** `'sandbox' | 'production'` *required*

使用哪个 Clink 应用地址，见 [环境映射](#环境映射)。

**presetOptions** `PresetOptions`

外观与语言设置，见 [预设项](#预设项)。

### 预设项

**locale** `'en-US' | 'zh-CN'` (default: en-US)

界面语言与 antd locale。

**primaryColor** `string` (default: #1677ff)

组件主色，CSS 颜色值。

**radius.components** `number` (default: 8)

组件圆角，单位 px。

**radius.card** `number` (default: 8)

卡片容器圆角，单位 px。

预设项在 SDK 发送 `init` 时应用。运行期只能用 `setLocale` 切换语言；主色和圆角创建后不可更改。

### 元素凭据

凭据在 `createElement` 时按元素类型传入：

**paymentMethods: \{ token }** `string` *required*

服务端签发的 card-session token（scope `card:manage`，有效期 1799s）。必填且不能为空；只保存在内存中。

**vault: \{ vaultId }** `string` *required*

服务端签发的一次性会话 id（有效期约 30 分钟）。元素页面用它兑换 vault token，宿主不持有该 token。

### 方法

**createElement(type, options)** `AgentElement\<T\>`

创建 `type` 对应的元素并传入该元素的凭据：`paymentMethods` 传 `{ token }`，`vault` 传 `{ vaultId }`。一个实例只能创建一个元素，重复调用会抛错；凭据为空也会抛错。元素在调用 `mount()` 之前不会渲染。

**setLocale(locale)** `void`

更新语言。`mount` 之前调用会在下一次 `init` 时下发；`mount` 之后调用会立即发送 `set-locale`。

**destroy()** `void`

卸载元素、关闭已打开的 3DS 浮层、移除消息监听并清空事件订阅。可重复调用。实例销毁后不可复用，`createElement`、`setLocale` 都会抛错。

### 错误

| 场景 | 行为 |
| :- | :- |
| `createElement` 未传凭据或凭据为空 | 抛错 |
| `setToken` 传入空值 | 抛错 |
| 同一实例调用两次 `createElement` | 抛错 |
| `mount` 的容器不存在 | 抛错 |
| 同一元素调用两次 `mount` | 抛错 |
| `destroy()` 之后调用任何方法 | 抛错 |

## `AgentElement`

元素由 `createElement` 创建，事件订阅挂在元素上。

**type** `ElementType`

元素类型：`'paymentMethods'` 或 `'vault'`。

**setToken(token)** `void`

仅 `paymentMethods` 可用。更新元素内的 card-session token：`mount` 之前调用会在下一次 `init` 下发；`mount` 之后调用会发送 `set-token` 并重新加载卡片数据。空值会抛错。vault 的凭据是一次性 `vaultId`，不支持刷新。

**on(event, callback)** `void`

订阅该元素的事件。建议在 `mount()` 之前注册，避免漏掉事件。

**off(event, callback)** `void`

取消订阅。

**mount(target, options?)** `void`

挂载 iframe。`target` 可以是 CSS 选择器或 `HTMLElement`，容器必须存在。见 [挂载选项](#挂载选项)。

**unmount()** `void`

移除 wrapper 与 iframe。事件订阅会保留，可以再次挂载；重新挂载会重新加载 iframe。

**getIframe()** `HTMLIFrameElement | null`

返回当前 iframe；未挂载时返回 `null`。

### 挂载选项

传给 `mount()` 的展示开关与主操作按钮外观，只在下一次挂载时生效。选项类型由元素类型决定，传错字段会在编译期报错。

#### paymentMethods

**hideSkeleton** `boolean` (default: false)

隐藏加载骨架屏。

**hideExistingCards** `boolean` (default: false)

隐藏已保存卡片列表。

**hideDelete** `boolean` (default: false)

隐藏删卡入口。

**hideSetDefault** `boolean` (default: false)

隐藏设为默认卡入口。

**button** `AgentElementButtonOptions`

主操作按钮外观，见 [按钮选项](#按钮选项)。

#### vault

**hideSkeleton** `boolean` (default: false)

隐藏加载骨架屏。

**hideHeader** `boolean` (default: false)

隐藏「选择卡片」标题与副标题。

**button** `AgentElementButtonOptions`

主操作按钮外观，见 [按钮选项](#按钮选项)。

挂载选项只是展示配置，不是密钥。SDK 会把它们编码进 iframe 地址；不要放入 token 等敏感值。

### 按钮选项

主操作按钮指元素底部的「添加银行卡」「解锁银行卡」或「继续」按钮。

**height** `number` (default: 40)

按钮高度，单位 px。

**fontSize** `number` (default: 16)

按钮字号，单位 px。

**radius** `number` (default: presetOptions.radius.components)

按钮圆角，单位 px。

```ts theme={null}
element.mount('#clink-card-management', {
  button: {
    height: 48,
    fontSize: 16,
    radius: 8,
  },
});
```

未传的字段保持默认值，只需要加高按钮的宿主可以只传 `height`。非数字或超出区间的值（高度 16–200、字号 8–40、圆角 0–100）会被忽略。卡列表行内的「设为默认」「删除」按钮与失败重试按钮不受影响。

## 事件

事件按元素划分，事件名与 payload 由元素类型推导。

```ts theme={null}
interface ElementEventDataMap {
  paymentMethods: {
    initialized: undefined;
    'card-added': { paymentInstrumentId: string };
    'card-deleted': { paymentInstrumentId: string };
    'default-changed': { paymentInstrumentId: string };
    'token-expired': undefined;
    error: { message: string; source: 'session' | 'runtime' | 'payment' };
  };
  vault: {
    initialized: undefined;
    'card-added': { paymentInstrumentId: string };
    completed: { paymentInstrumentId: string };
    'token-expired': undefined;
    error: { message: string; source: 'session' | 'runtime' | 'payment' };
  };
}
```

### `paymentMethods` 事件

| 事件 | Payload | 触发时机 |
| :- | :- | :- |
| `initialized` | 无 | 首次卡片数据加载完成 |
| `card-added` | `{ paymentInstrumentId }` | 加卡成功，含 3DS 通过 |
| `card-deleted` | `{ paymentInstrumentId }` | 删卡成功 |
| `default-changed` | `{ paymentInstrumentId }` | 设为默认卡成功 |
| `token-expired` | 无 | 接口返回 401；同一 token 周期最多一次 |
| `error` | `{ message, source }` | 加载、卡片操作、加卡或 3DS 失败 |

### `vault` 事件

| 事件 | Payload | 触发时机 |
| :- | :- | :- |
| `initialized` | 无 | 首次卡片数据加载完成 |
| `card-added` | `{ paymentInstrumentId }` | vault 流程中加卡成功 |
| `completed` | `{ paymentInstrumentId }` | 已保存卡片解锁成功，含 3DS 通过 |
| `token-expired` | 无 | 接口返回 401；同一 token 周期最多一次 |
| `error` | `{ message, source }` | 加载、解锁、加卡或 3DS 失败 |

`error.source` 取值：

| source | 含义 |
| :- | :- |
| `session` | 卡片数据加载等会话级失败 |
| `runtime` | 运行时意外错误 |
| `payment` | 卡片或支付操作失败 |

`unmount()` 不会清除订阅，只有 `destroy()` 会。

## 环境映射

| 环境 | Clink 应用地址 |
| :- | :- |
| `sandbox` | `https://uat-agent-elements.clinkbill.com` |
| `production` | `https://agent-elements.clinkbill.com` |

`environment` 必传：接入联调用 `sandbox`（UAT），上线后用 `production`。

## 模块导出

```ts theme={null}
export const version: string;
export const EVENT_TYPES: readonly ElementEventType[];
export function isEventType(value: string): value is ElementEventType;
export { AgentElements, AgentElement };
```

`version` 由构建时注入。直接引用源码时返回 `0.0.0-dev`。

### 类型

| 类型 | 说明 |
| :- | :- |
| `Environment` | `'sandbox' \| 'production'` |
| `LocaleKey` | `'en-US' \| 'zh-CN'` |
| `ElementType` | `'paymentMethods' \| 'vault'` |
| `AgentElementsOptions` | 构造参数 |
| `PresetOptions` / `PresetRadius` | 外观配置 |
| `AgentElementMountOptions` | `mount()` 的展示开关与按钮外观 |
| `AgentElementButtonOptions` | 主操作按钮外观 |
| `ErrorSource` | `'session' \| 'runtime' \| 'payment'` |
| `AgentElementsErrorData` | `{ message, source }` |
| `CardAddedData` / `CardDeletedData` / `DefaultChangedData` | `{ paymentInstrumentId }` |
| `VaultCompletedData` | `{ paymentInstrumentId }` |
| `ElementEventDataMap` | 每个元素的事件与 payload 表 |
| `ElementEventName<T>` | 指定元素的事件名 |
| `ElementEventCallback<T, K>` | 指定事件的回调类型 |
| `ElementEventType` | 所有元素的事件名合集 |

## 构建产物

| 产物 | 文件 | 说明 |
| :- | :- | :- |
| ESM | `dist/index.js` | 打包器与原生 ESM 的入口 |
| IIFE | `dist/index.iife.js` | 浏览器全局变量 `ClinkAgentElements` |
| 类型 | `dist/index.d.ts` | 不依赖私有包 |

包不提供 CommonJS 产物。内部的 iframe bridge 会在构建时打入产物，发布后的包没有私有运行时依赖。

### Script 标签

```html theme={null}
<div id="clink-card-management"></div>
<script src="https://unpkg.com/@clink-ai/agent-elements@<version>/dist/index.iife.js"></script>
<script>
  const instance = new ClinkAgentElements.AgentElements({
    environment: 'production',
  });

  instance
    .createElement('paymentMethods', { token: 'your token here' })
    .mount('#clink-card-management');
</script>
```

通过 `<script>` 标签加载时，SDK 挂载在全局变量 `ClinkAgentElements` 下。生产环境请把 `@<version>` 固定为实际版本号。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.