> ## 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.

# Agent Elements SDK

> 在宿主应用中嵌入 Clink 卡片管理：服务端签发元素凭据，前端挂载由 Clink 托管的 iframe。

`@clink-ai/agent-elements` 把 Clink 的钱包卡片界面嵌进宿主应用。宿主服务端按元素类型签发凭据，前端创建一个元素并挂载到容器里；卡片表单、卡片数据和 3DS 都在 Clink 托管的 iframe 中处理，宿主页面不接触卡数据。

> [!NOTE]
>
> 生产环境请锁定 `@clink-ai/agent-elements` 的版本号。完整参数和方法见 [SDK API 参考](https://docs.clinkbill.com/cn/guides/agent/agent_elements/api_reference.md)。

## 完整链路

Agent Elements 只替换前端卡片界面。**凭据仍然必须由宿主服务端签发**，因为换取凭据要用 Clink 分配的 client secret。

```mermaid theme={null}
sequenceDiagram
  participant B as 宿主前端
  participant M as 宿主后端
  participant C as Clink 平台（API / BFF）
  participant E as Agent Elements iframe

  B->>M: 1. 请求元素凭据（paymentMethods 或 vault）
  M->>C: 2. 用 client secret 换 portal token
  M->>C: 3. 创建 card-session 或 vault-session
  C-->>M: 4. 返回 card-session token / vaultId
  M-->>B: 5. 只返回该元素的凭据
  B->>E: 6. createElement + mount
  E->>C: 7. 加载卡片数据（vault 先兑换 vault token）
  E-->>B: 8. initialized / card-added / completed
  B->>M: 9. 用 paymentInstrumentId 继续业务流程
```

第 2 步的 client secret 和 portal token 不能下发浏览器。前端能拿到的只有两种东西：`paymentMethods` 的 card-session token，或 `vault` 的 vaultId。

### 四方职责

| 参与方 | 负责 | 不能做 |
| - | - | - |
| 宿主前端 | 创建实例与元素、挂载 iframe、按事件更新自己的 UI | 不能持有 client secret / portal token，不能把凭据写进 iframe 地址 |
| 宿主后端 | 换取并保管平台凭据、签发元素凭据、关联本地用户与卡片 | 不能把 client secret 或 portal token 透传给浏览器 |
| Clink 平台 | 校验凭据、签发 card-session token 与 vaultId、渲染卡片 UI | 不创建宿主订单，不扣款 |
| Clink 托管 iframe | 加载卡片数据、处理加卡 / 解锁 / 3DS、上报事件 | 不保存宿主业务状态，不接触宿主后端凭据 |

## 一、服务端：签发元素凭据

两种元素的凭据来源不同，但都要经过同一套平台鉴权。

### 1. 换 client token 与 portal token

client token 只用 `client_credentials` 换取，portal token 再按用户邮箱换取。

```javascript theme={null}
const API = 'https://uat-api.clinkbill.com'; // sandbox（UAT）环境，见「环境」

// client token
const client = await postForm(`${API}/agent/cwallet/oauth/token`, {
  grant_type: 'client_credentials',
  client_id: CLIENT_ID,
  client_secret: CLIENT_SECRET,
});

// portal token，按已授权的用户邮箱
const portal = await postJson(
  `${API}/agent/cwallet/platform/portal/tokens`,
  { email: user.email },
  client.access_token,
);
```

* `client_id` / `client_secret` 由 Clink 分配，只放服务端。
* portal token 只支持 `email`，**不支持传 `customer_id`**。
* 邮箱必须已经授权给该 client；未授权会返回 `71211003 The redirect URI is not registered for this client`。
* client token 与 portal token 有效期都是 3600s。

### 2. paymentMethods：创建 card-session

```javascript theme={null}
const session = await postJson(
  `${API}/agent/platform/card-sessions`,
  {},
  portal.access_token,
);

res.json({ token: session.access_token });
```

响应里的 `access_token`（scope `card:manage`）就是 `paymentMethods` 元素的凭据，有效期 1799s。它只能访问当前用户的卡片接口，可以下发给浏览器。

### 3. vault：创建 vault session

```javascript theme={null}
const vault = await postJson(
  `${API}/agent/platform/vault-sessions`,
  {},
  portal.access_token,
);

res.json({ vaultId: vault.vault_id });
```

```json theme={null}
{
  "vault_id": "vs_xxxxxxxx",
  "url": "https://uat-agent.clinkbill.com/vault/vs_xxxxxxxx",
  "expires_at": "2026-11-16T08:30:15.649Z"
}
```

* `vault_id` 下发给 `vault` 元素，有效期约 30 分钟。
* `url` 是免登录绑卡页，供用户直接在浏览器打开；SDK 接入不使用它。
* vault token 由 iframe 用 `vaultId` 兑换，有效期约 899s，宿主不接触。

> [!WARNING]
>
> client secret、client token、portal token 都只能留在服务端。包装接口向前端只返回 `{ token }` 或 `{ vaultId }`。

## 二、前端：初始化并挂载

### 环境

`environment` 决定 iframe 加载哪个 Clink 应用地址，也决定服务端该请求哪套 API。

| `environment` | iframe 应用地址 | 服务端 API |
| :- | :- | :- |
| `sandbox` | `https://uat-agent-elements.clinkbill.com` | `https://uat-api.clinkbill.com` |
| `production` | `https://agent-elements.clinkbill.com` | 由 Clink 提供 |

`environment` 必传：接入联调用 `sandbox`（UAT），上线用 `production`。跨环境不要混用凭据，否则会 401。应用地址只由 `environment` 决定，SDK 不接受运行时覆盖。

### 安装

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

包同时提供 ESM 与 IIFE 产物，见 [构建产物](https://docs.clinkbill.com/cn/guides/agent/agent_elements/api_reference.md#构建产物)。

### 创建实例

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

const instance = new AgentElements({
  environment: 'sandbox',
  presetOptions: { locale: 'zh-CN' },
});
```

一个 `AgentElements` 实例只能创建一个元素。同时使用两个元素时创建两个实例。

### 创建元素

元素类型决定凭据和可用的挂载选项。凭据在 `createElement` 时传入，必填且不能为空。

```ts theme={null}
// paymentMethods：服务端签发的 card-session token
const cardManager = instance.createElement('paymentMethods', { token });

// vault：服务端签发的一次性 vaultId
const vaultElement = new AgentElements({ environment: 'sandbox' }).createElement(
  'vault',
  { vaultId },
);
```

| 元素 | 用户可以做什么 | 凭据 |
| :- | :- | :- |
| `paymentMethods` | 查看已保存卡片、加卡、设为默认卡、删卡 | card-session token（1799s） |
| `vault` | 选一张已保存卡片并用 CVV 解锁，或新增卡片 | vaultId（一次性，约 30 分钟） |

### 挂载

```ts theme={null}
element.mount('#clink-card-management', {
  hideExistingCards: false,
  hideDelete: false,
  hideSetDefault: false,
  button: { height: 48 },
});
```

容器可以是 CSS 选择器或 `HTMLElement`，需要有稳定宽度；高度由 SDK 设置，加载后随内容增长，宿主不要固定高度。宿主运行在支持 iframe 与 `postMessage` 的现代浏览器中。

挂载选项只在下一次挂载时生效；需要调整时先 `unmount` 再 `mount`。

| 元素 | 选项 | 作用 |
| :- | :- | :- |
| 通用 | `hideSkeleton` | 隐藏加载骨架屏 |
| 通用 | `button` | 主操作按钮外观：`height` / `fontSize` / `radius`，单位 px |
| `paymentMethods` | `hideExistingCards` | 隐藏已保存卡片列表 |
| `paymentMethods` | `hideDelete` | 隐藏删卡入口 |
| `paymentMethods` | `hideSetDefault` | 隐藏设为默认卡入口 |
| `vault` | `hideHeader` | 隐藏标题与副标题 |

挂载选项只是展示配置，会被编码进 iframe 地址。**不要放 token 等敏感值**。

## 三、事件与状态同步

事件按元素划分，通过 `element.on` / `element.off` 订阅。在 `mount()` 之前注册，避免漏掉事件。

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

```ts theme={null}
element.on('card-added', ({ paymentInstrumentId }) => {
  // 同步宿主侧的卡片列表。
});
element.on('completed', ({ paymentInstrumentId }) => {
  // vault：拿到已解锁的卡，继续宿主业务流程。
});
element.on('error', ({ message, source }) => {
  console.error(source, message);
});
```

`error.source` 取值：

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

### token 过期

`paymentMethods` 收到 `token-expired` 后，从宿主后端换新的 card-session token，再调用 `setToken`：

```ts theme={null}
element.on('token-expired', async () => {
  element.setToken(await fetchCardSessionToken());
});
```

新 token 到达后 iframe 会重新加载卡片数据，并重置「每周期只上报一次」的计数。`mount` 之前调用 `setToken` 只更新内存值，等下一次 `init` 才下发。

`vault` 没有可刷新的 token：session 失效后重新申请 `vaultId` 并重建元素。

### 清理

```ts theme={null}
instance.destroy();
```

`destroy()` 会移除 iframe、关闭已打开的 3DS 浮层并清理元素上的监听。实例不可复用。`unmount()` 只移除 iframe 和 wrapper，订阅会保留，可以再次挂载。

## 四、外观

外观只在创建实例时设置：

```ts theme={null}
const instance = new AgentElements({
  environment: 'sandbox',
  presetOptions: {
    locale: 'zh-CN',
    primaryColor: '#1677ff',
    radius: { components: 8, card: 8 },
  },
});
```

| 选项 | 默认值 | 作用 |
| :- | :- | :- |
| `locale` | `en-US` | 界面语言与 antd locale，可选 `en-US` / `zh-CN` |
| `primaryColor` | `#1677ff` | 组件主色 |
| `radius.components` | `8` | 组件圆角，单位 px |
| `radius.card` | `8` | 卡片容器圆角，单位 px |

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

## 五、限制

* 一个 `AgentElements` 实例只能创建一个元素；需要同时使用 `paymentMethods` 与 `vault` 时创建两个实例。
* 卡片界面只能通过预设项调整，不提供自定义 CSS。
* 3DS 只通过 iframe 浮层承载，不支持弹窗或整页跳转方式。
* `token` / `vaultId` 的获取与刷新由宿主服务端负责。


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