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

> Constructor options, element methods, mount options, events, and types in the Agent Elements SDK.

Use this page with the [Agent Elements SDK guide](https://docs.clinkbill.com/guides/agent/agent_elements), which explains the flows and how to handle each event.

> [!NOTE]
>
> The SDK runs in the browser, in the host page. The Clink-hosted iframe handles cards, credentials, and 3DS; the host receives identifiers and events only.

## Install

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

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

## `new AgentElements(options)`

Creates the SDK instance and resolves the Clink app address for the environment.

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

Which Clink app address to use. See [Environment mapping](#environment-mapping).

**presetOptions** `PresetOptions`

Appearance and locale settings. See [Preset options](#preset-options).

### Preset options

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

UI language and antd locale.

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

Component primary color, as a CSS color value.

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

Corner radius for components, in px.

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

Corner radius for the card container, in px.

Preset options are applied when the SDK sends `init`. `setLocale` updates the language at runtime; the color and radius options cannot change after construction.

### Element credentials

Credentials are passed per element when calling `createElement`:

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

A card-session token issued by your server (scope `card:manage`, 1799s). Required and non-empty; held in memory only.

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

A server-issued one-time session id (valid for about 30 minutes). The element exchanges it for a vault token; the host never holds that token.

### Methods

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

Creates the element for `type` with its credentials: `paymentMethods` takes `{ token }`, `vault` takes `{ vaultId }`. An instance can create one element; a second call throws, and missing or empty credentials throw. The element is not rendered until `mount()` is called.

**setLocale(locale)** `void`

Updates the locale. Before `mount`, it is sent with the next `init`. After `mount`, the iframe receives `set-locale` immediately.

**destroy()** `void`

Unmounts the element, closes any open 3DS overlay, removes message listeners, and clears event subscriptions. Idempotent. The instance cannot be reused; `createElement` and `setLocale` throw after `destroy()`.

### Errors

| Situation | Behavior |
| :- | :- |
| `createElement` is called without credentials, or with empty ones | Throws |
| `setToken` receives an empty value | Throws |
| `createElement` is called twice on one instance | Throws |
| `mount` target does not exist | Throws |
| `mount` is called twice on one element | Throws |
| Any method is called after `destroy()` | Throws |

## `AgentElement`

An element is created by `createElement` and owns its event subscriptions.

**type** `ElementType`

The element type: `'paymentMethods'` or `'vault'`.

**setToken(token)** `void`

`paymentMethods` only. Updates the element's card-session token: before `mount`, it is sent with the next `init`; after `mount`, the iframe receives `set-token` and reloads its card data. An empty value throws. The vault credential is a one-time `vaultId` and cannot be refreshed.

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

Subscribes to one of the element's events. Register before `mount()` so no event is missed.

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

Removes a subscription.

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

Mounts the iframe. `target` is a CSS selector or an `HTMLElement`. The container must exist. See [Mount options](#mount-options).

**unmount()** `void`

Removes the wrapper and iframe. Event subscriptions are kept, so the element can be mounted again. A remount reloads the iframe.

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

Returns the current iframe, or `null` while unmounted.

### Mount options

Display switches and primary button styling passed to `mount()`. They are applied to the next mount only. The option type depends on the element type, so passing a field the element does not support fails at compile time.

#### paymentMethods

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

Hides the loading skeleton.

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

Hides the saved-card list.

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

Hides delete actions.

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

Hides the set-default action.

**button** `AgentElementButtonOptions`

Appearance of the primary action button. See [Button options](#button-options).

#### vault

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

Hides the loading skeleton.

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

Hides the "Select a card" title and subtitle.

**button** `AgentElementButtonOptions`

Appearance of the primary action button. See [Button options](#button-options).

Mount options are display flags, not secrets. The SDK serializes them onto the iframe URL; do not put tokens or other sensitive values there.

### Button options

The primary action button is the "Add card", "Unlock card", or "Continue" button at the bottom of the element.

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

Button height, in px.

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

Button font size, in px.

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

Button corner radius, in px.

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

Fields you leave out keep their defaults, so a host that only needs a taller button can pass `height` alone. Values that are not numbers or fall outside the supported range (height 16–200, font size 8–40, radius 0–100) are ignored. List action buttons (set default, delete) and retry buttons are not affected.

## Events

Events are scoped to the element. The event name and payload are inferred from the element type.

```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` events

| Event | Payload | Fired when |
| :- | :- | :- |
| `initialized` | None | Card data loads for the first time |
| `card-added` | `{ paymentInstrumentId }` | A card is added, including after 3DS |
| `card-deleted` | `{ paymentInstrumentId }` | A card is deleted |
| `default-changed` | `{ paymentInstrumentId }` | A card becomes the default |
| `token-expired` | None | The API returns 401; at most once per token cycle |
| `error` | `{ message, source }` | A load, card action, add-card, or 3DS step fails |

### `vault` events

| Event | Payload | Fired when |
| :- | :- | :- |
| `initialized` | None | Card data loads for the first time |
| `card-added` | `{ paymentInstrumentId }` | A card is added during the vault flow |
| `completed` | `{ paymentInstrumentId }` | A saved card is unlocked, including after 3DS |
| `token-expired` | None | The API returns 401; at most once per token cycle |
| `error` | `{ message, source }` | A load, unlock, add-card, or 3DS step fails |

`error.source`:

| Source | Meaning |
| :- | :- |
| `session` | A card-data load or session-level failure |
| `runtime` | An unexpected runtime error |
| `payment` | The card or payment operation failed |

Subscriptions survive `unmount()` and are cleared only by `destroy()`.

## Environment mapping

| Environment | Clink app origin |
| :- | :- |
| `sandbox` | `https://uat-agent-elements.clinkbill.com` |
| `production` | `https://agent-elements.clinkbill.com` |

`environment` is required: use `sandbox` (UAT) while integrating and `production` after go-live.

## Module exports

```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` is injected at build time. When the SDK is used directly from source, it reports `0.0.0-dev`.

### Types

| Type | Description |
| :- | :- |
| `Environment` | `'sandbox' \| 'production'` |
| `LocaleKey` | `'en-US' \| 'zh-CN'` |
| `ElementType` | `'paymentMethods' \| 'vault'` |
| `AgentElementsOptions` | Constructor options |
| `PresetOptions` / `PresetRadius` | Appearance options |
| `AgentElementMountOptions` | Display switches and button styling for `mount()` |
| `AgentElementButtonOptions` | Primary action button styling |
| `ErrorSource` | `'session' \| 'runtime' \| 'payment'` |
| `AgentElementsErrorData` | `{ message, source }` |
| `CardAddedData` / `CardDeletedData` / `DefaultChangedData` | `{ paymentInstrumentId }` |
| `VaultCompletedData` | `{ paymentInstrumentId }` |
| `ElementEventDataMap` | Event and payload table per element |
| `ElementEventName<T>` | Event names for one element type |
| `ElementEventCallback<T, K>` | Callback type for one event |
| `ElementEventType` | All event names across elements |

## Package formats

| Output | File | Notes |
| :- | :- | :- |
| ESM | `dist/index.js` | Package entry for bundlers and native ESM |
| IIFE | `dist/index.iife.js` | Browser global `ClinkAgentElements` |
| Types | `dist/index.d.ts` | No private package dependency |

The package has no CommonJS build. The internal iframe bridge is bundled into the output, so the published package has no private runtime dependency.

### Script tag

```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>
```

When loaded with a `<script>` tag, the SDK is exposed on the `ClinkAgentElements` global. Pin `@<version>` to a concrete version in production.


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