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

# TypeScript SDK

> Clink API 官方 Node.js 库。

Clink Node.js SDK 为服务端 JavaScript 和 TypeScript 应用提供了便捷的 Clink API 调用方式，并内置了完整的 TypeScript 类型定义。

<Card title="NPM Package" icon="npm" href="https://www.npmjs.com/package/@clink-ai/clink-typescript-sdk">
  在 npmjs.com 查看该包
</Card>

## 安装

使用你偏好的包管理器安装：

<CodeGroup>
  ```bash npm theme={null}
  npm install @clink-ai/clink-typescript-sdk
  ```

  ```bash yarn theme={null}
  yarn add @clink-ai/clink-typescript-sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @clink-ai/clink-typescript-sdk
  ```
</CodeGroup>

## 快速开始

开始使用前，需要先用你的 API Key 初始化客户端。你可以在 Clink Dashboard 的 **Developers** 页面找到密钥。

<Warning>
  **安全提示：** 该 SDK 仅适用于服务端。不要在浏览器端代码或公开仓库中暴露 **Secret API keys**。
</Warning>

```typescript theme={null}
import { ClinkPayClient } from '@clink-ai/clink-typescript-sdk';

const client = new ClinkPayClient({
  apiKey: 'YOUR_API_KEY',
  env: 'sandbox',
});

async function main() {
  const session = await client.createCheckoutSession({
    customerEmail: 'customer@example.com',
    originalAmount: 19.99,
    originalCurrency: 'USD',
    uiMode: 'hostedPage',
    priceDataList: [
      { name: '测试商品', quantity: 1, unitAmount: 19.99, currency: 'USD' },
    ],
    successUrl: 'https://merchant.example.com/success',
    cancelUrl: 'https://merchant.example.com/cancel',
    allowPromotionCodes: true,
  });

  console.log(session.sessionId);
  console.log(session.url);
}

main();
```

如果你要用 [Elements](/cn/elements)，请将 `uiMode` 设置为 `elements`，并提供 `returnUrl`，例如 `https://YOUR_DOMAIN/complete.html?session_id={ELEMENTS_SESSION_ID}`。Clink 会将 `{ELEMENTS_SESSION_ID}` 替换为创建出的 session ID。

如果你用的是 [`@clink-ai/clink-js`](/cn/api-reference/javascript_sdk) 的嵌入式 iframe，则改用 `uiMode: 'hostedPage'`——那个 SDK 原样挂载托管结账页。

## API 概览

* `createCheckoutSession(options)`：创建 checkout session，并返回跳转 `url`
* `getCheckoutSession(sessionId)`：查询 checkout session 详情
* `getOrder(orderId)`：查询订单详情
* `getRefund(refundId)`：查询退款详情
* `getSubscription(subscriptionId)`：查询订阅详情
* `getInvoice(invoiceId)`：查询订阅发票详情
* `customerPortalSession(options)`：创建 customer portal session，并返回访问链接

所有方法都是异步的，接口返回错误时会抛出异常。

## 错误处理

当 API 返回非成功状态码（4xx 或 5xx）时，SDK 会抛出错误。建议用 `try/catch` 包裹调用逻辑。

```typescript theme={null}
import { ClinkPayClient, ClinkApiError } from '@clink-ai/clink-typescript-sdk';

const client = new ClinkPayClient({ apiKey: 'YOUR_API_KEY', env: 'sandbox' });

async function demo() {
  try {
    const order = await client.getOrder('order_123');
    console.log(order.status);
  } catch (e) {
    if (e instanceof ClinkApiError) {
      const { code, message } = e;
      // your code here
    }
    // handle other errors
  }
}

demo();
```

## 验证 Webhook 签名

`ClinkWebhook` 会帮你算并比对 HMAC，不用自己写。

```typescript theme={null}
import { ClinkWebhook, ClinkWebhookSignatureError } from '@clink-ai/clink-typescript-sdk';

const webhook = new ClinkWebhook({ signatureKey: process.env.CLINK_WEBHOOK_SIGNING_KEY });

const REPLAY_WINDOW_MS = 5 * 60 * 1000;

// SDK 只管 HMAC，这两道要在调它之前自己挡
if (headers['x-clink-signtype'] !== 'SHA256') return reject401();

const ts = Number(headers['x-clink-timestamp']);
if (!Number.isFinite(ts) || Math.abs(Date.now() - ts) > REPLAY_WINDOW_MS) return reject401();

try {
  const event = webhook.verifyAndGet({
    timestamp: headers['x-clink-timestamp'],
    body: rawBody,              // 原始请求体，JSON 解析之前的
    headerSignature: headers['x-clink-signature'],
  });

  // event.id、event.type、event.data.object
} catch (e) {
  if (e instanceof ClinkWebhookSignatureError) {
    // 返回 401
  }
}
```

<Warning>
  **`1.0.1` 的 `verifyAndGet()` 只验 HMAC。** 它不校验 `X-Clink-SignType`，不校验时间戳新鲜度，签名比较用的是 `===` 而不是恒定时间比较。

  前两条上面已经挡了。第三条要自己算 HMAC 才能绕开，用 `crypto.timingSafeEqual`，写法见 [Hosted Checkout 接入](/cn/build-integration)。

  另外，验签通过不等于可以直接处理。动手之前先用唯一索引按 `event.id` 去重。
</Warning>

`verifySignature()` 返回布尔值而不抛异常，`signature()` 用来生成签名——本地造测试事件时用得上。

## 参考资料

* [API 详细示例](https://www.npmjs.com/package/@clink-ai/clink-typescript-sdk?activeTab=readme)


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