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

> The official Node.js library for the Clink API.

The Clink Node.js SDK provides convenient access to the Clink API from applications written in server-side JavaScript or TypeScript. It includes TypeScript definitions for all request parameters and response fields.

<Card title="NPM Package" icon="npm" href="https://www.npmjs.com/package/@clink-ai/clink-typescript-sdk">
  View the package on npmjs.com
</Card>

## Installation

Install the package with your preferred package manager:

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

## Quick Start

To start using the SDK, you need to initialize the client with your API Key. You can find your secret keys in the **Developers** section of your Clink dashboard.

<Warning>
  **Security Note:** The SDK is intended for server-side use only. Never expose your **Secret API keys** in client-side code (browsers) or public repositories.
</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({
    originalAmount: 1999,
    originalCurrency: 'USD',
    uiMode: 'hostedPage',
    successUrl: 'https://merchant.example.com/success',
    cancelUrl: 'https://merchant.example.com/cancel',
    allowPromotionCodes: true,
  });

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

main();
```

For embedded checkout, create the session with `uiMode: 'elements'` and provide `returnUrl`, for example `https://YOUR_DOMAIN/complete.html?session_id={ELEMENTS_SESSION_ID}`. Clink replaces `{ELEMENTS_SESSION_ID}` with the created session ID.

## API Overview

* `createCheckoutSession(options)`: Create a checkout session and get the redirect `url`.
* `getCheckoutSession(sessionId)`: Retrieve checkout session details.
* `getOrder(orderId)`: Retrieve order details.
* `getRefund(refundId)`: Retrieve refund details.
* `getSubscription(subscriptionId)`: Retrieve subscription details.
* `getInvoice(invoiceId)`: Retrieve subscription invoice details.
* `customerPortalSession(options)`: Create a customer portal session and get the access link.

All methods are asynchronous and throw on errors.

## Error Handling

When the API returns a non-success status code (4xx or 5xx), the SDK throws an error. You should wrap your API calls in `try/catch` blocks.

```typescript theme={null}
import { ClinkPayClient } 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('ord_123');
    console.log(order.status);
  } catch (e) {
    if (e instanceof ClinkApiError) {
      const { code, message } = e;
      // your code here
    }
    // handle other errors
  }
}

demo();
```

## References

* [Detailed Example for APIs](https://www.npmjs.com/package/@clink-ai/clink-typescript-sdk?activeTab=readme)