# @biggora/klix

> TypeScript SDK and NestJS adapter for Klix API.

Latest version **1.0.6** (published 2026-08-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install @biggora/klix
pnpm add @biggora/klix
yarn add @biggora/klix
bun add @biggora/klix
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.6 |
| Published | 2026-08-12 |
| First published | 2026-04-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20 |
| Dependencies | 0 |
| Unpacked size | 547.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| Maintainers | biggora |
| Keywords | klix, payments, checkout, webhooks, refunds, payment-gateway, payment-api, sdk, api-client, typescript, nodejs, nestjs, ecommerce |

## Links

- npm: https://www.npmjs.com/package/@biggora/klix
- Repository: https://github.com/biggora/klix
- Homepage: https://github.com/biggora/klix#readme
- Issues: https://github.com/biggora/klix/issues
- npm.io page: https://npm.io/package/@biggora/klix

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 1.0.6 (latest) — 2026-08-12
- 1.0.3-oidc-test.0 (oidc-test) — 2026-05-09
- 1.0.5 — 2026-08-06
- 1.0.3 — 2026-06-30
- 1.0.2 — 2026-05-10
- 1.0.1 — 2026-04-19
- 1.0.0 — 2026-04-19

## README

# Klix

[![npm version](https://img.shields.io/npm/v/@biggora/klix.svg)](https://www.npmjs.com/package/@biggora/klix)
[![Unit Tests](https://github.com/biggora/klix/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/biggora/klix/actions/workflows/unit-tests.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

TypeScript SDK and NestJS adapter for [Klix API](https://developers.klix.app/api/).

Targets Node.js `20+`. Ships dual `ESM`/`CommonJS` builds and a first-class NestJS subpath export.

## Install

```bash
npm install @biggora/klix
```

NestJS apps also need peer deps:

```bash
npm install @nestjs/common @nestjs/core reflect-metadata rxjs
```

## Quick Start: Checkout

Create a purchase, redirect the customer to `checkout_url`, then confirm the final state with a success callback or webhook before fulfilling the order.

## Features

- Full current REST surface from Klix OpenAPI schema
- Typed resources for purchases, clients, billing, webhooks, statements, balance, payment methods
- Built-in auth, timeout handling, error normalization, and pagination helpers
- `paymentMethods.list()` server-side cache enabled by default for 60 seconds
- Success callback signature verification through `/public_key/`
- Pure webhook signature verification helper
- NestJS `KlixModule.forRoot()` and `KlixModule.forRootAsync()`

## Plain Node.js

```ts
import { createKlixClient } from '@biggora/klix';

const klix = createKlixClient({
  apiKey: process.env.KLIX_API_KEY!,
  brandId: process.env.KLIX_BRAND_ID!,
});

const purchase = await klix.purchases.create({
  currency: 'EUR',
  reference: 'ORDER-1001',
  client: {
    email: 'customer@example.com',
  },
  purchase: {
    products: [
      {
        name: 'Pro subscription',
        price: 1999,
        quantity: 1,
      },
    ],
  },
  success_callback: 'https://example.com/api/klix/callback',
  success_redirect: 'https://example.com/checkout/success',
  failure_redirect: 'https://example.com/checkout/failure',
});

console.log(purchase.checkout_url);
```

Use a durable order reference and store the returned purchase `id`. Klix can return asynchronous states for capture, charge, release, and refund operations, so webhook delivery is the safest place to finalize order state.

## Main API Surface

```ts
klix.balance.get();
klix.paymentMethods.list({ currency: 'EUR' });
klix.payoutMethods.list({ currency: 'EUR' });

klix.purchases.create(...);
klix.purchases.read(id);
klix.purchases.cancel(id);
klix.purchases.capture(id, { amount: 500 });
klix.purchases.charge(id, { recurring_token: token });
klix.purchases.refund(id, { client_name: 'Jane Doe', amount: 500 });
klix.purchases.release(id);

klix.clients.create(...);
klix.clients.list();
klix.clients.iterateAll();
klix.clients.listRecurringTokens(clientId);

klix.billing.sendInvoice(...);
klix.billingTemplates.create(...);
klix.billingTemplates.list();
klix.billingTemplates.addSubscriber(templateId, ...);
klix.billingTemplates.sendInvoice(templateId, ...);
klix.billingTemplates.listClients(templateId);

klix.companyStatements.create(...);
klix.companyStatements.list();

klix.webhooks.create(...);
klix.webhooks.list();
klix.webhooks.listDeliveries({ id: purchaseId, source_type: 'purchase' });
```

## Error Handling

SDK throws `KlixApiError`.

```ts
import { KlixApiError } from '@biggora/klix';

try {
  await klix.balance.get();
} catch (error) {
  if (error instanceof KlixApiError) {
    console.error(error.status, error.code, error.message, error.details);
  }
}
```

## Callback and Webhook Verification

### Success callback verification

`KlixClient` can fetch Klix callback public key and verify callback payload signatures.

```ts
const valid = await klix.verifySuccessCallback(rawBodyBuffer, signatureHeader);
```

### Webhook verification

For webhook deliveries, Klix provides dedicated public key per webhook.

```ts
import { verifyWebhookPayload } from '@biggora/klix';

const valid = verifyWebhookPayload(rawBodyBuffer, signatureHeader, webhook.public_key);
```

Create a webhook from code when you want setup to be repeatable across environments:

```ts
const webhook = await klix.webhooks.create({
  title: 'Production purchase events',
  callback: 'https://example.com/api/klix/webhook',
  all_events: false,
  events: ['purchase.paid', 'purchase.payment_failure', 'payment.refunded'],
});

console.log(webhook.public_key);
```

## NestJS

Use `@biggora/klix/nestjs` subpath export.

```ts
import { Module } from '@nestjs/common';
import { KlixModule } from '@biggora/klix/nestjs';

@Module({
  imports: [
    KlixModule.forRoot({
      apiKey: process.env.KLIX_API_KEY!,
      brandId: process.env.KLIX_BRAND_ID!,
    }),
  ],
})
export class PaymentsModule {}
```

Async config:

```ts
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { KlixModule } from '@biggora/klix/nestjs';

@Module({
  imports: [
    ConfigModule.forRoot(),
    KlixModule.forRootAsync({
      inject: [ConfigService],
      useFactory: async (config: ConfigService) => ({
        apiKey: config.getOrThrow<string>('KLIX_API_KEY'),
        brandId: config.getOrThrow<string>('KLIX_BRAND_ID'),
      }),
    }),
  ],
})
export class PaymentsModule {}
```

Inject client into services:

```ts
import { Injectable } from '@nestjs/common';
import { InjectKlixClient } from '@biggora/klix/nestjs';
import type { KlixClient } from '@biggora/klix';

@Injectable()
export class PaymentsService {
  constructor(@InjectKlixClient() private readonly klix: KlixClient) {}

  async getBalance() {
    return this.klix.balance.get();
  }
}
```

Use verifier service:

```ts
import { Controller, Post, Req } from '@nestjs/common';
import type { RawBodyRequest } from '@nestjs/common';
import type { Request } from 'express';
import { KlixSignatureVerifier } from '@biggora/klix/nestjs';

@Controller('klix')
export class KlixCallbackController {
  constructor(private readonly verifier: KlixSignatureVerifier) {}

  @Post('callback')
  async callback(@Req() req: RawBodyRequest<Request>) {
    const signature = String(req.headers['x-signature'] ?? '');
    const valid = await this.verifier.verifySuccessCallback(req.rawBody ?? Buffer.alloc(0), signature);

    return { valid };
  }

  @Post('webhook')
  webhook(@Req() req: RawBodyRequest<Request>) {
    const signature = String(req.headers['x-signature'] ?? '');
    const webhookPublicKey = process.env.KLIX_WEBHOOK_PUBLIC_KEY!;
    const valid = this.verifier.verifyWebhookPayload(req.rawBody ?? Buffer.alloc(0), signature, webhookPublicKey);

    return { valid };
  }
}
```

Enable raw body before registering callback or webhook routes:

### Express

```ts
const app = await NestFactory.create(AppModule, { rawBody: true });
```

### Fastify

```ts
const app = await NestFactory.create(
  AppModule,
  new FastifyAdapter(),
  { rawBody: true },
);
```

## Notes

- `paymentMethods.list()` injects configured `brandId` automatically and caches results by query for 60 seconds.
- `payoutMethods.list()` also injects configured `brandId`.
- `purchases.create()` and billing template creation helpers inject configured `brandId` when omitted in request body.
- Source of truth for generated types is current Klix OpenAPI schema at `https://portal.klix.app/api/schema/v1/`.

---
_Source: https://npm.io/package/@biggora/klix · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._