@codebox/sdk

Official TypeScript SDK for the CodeBox QR code platform.

Zero runtime dependencies. Uses native fetch. Requires Node.js 18+.

Install

npm install @codebox/sdk

Quick Start

import { CodeBox } from '@codebox/sdk';

const client = new CodeBox({ apiKey: 'cb_sk_xxx' });

// Create a dynamic QR code
const qr = await client.qrcodes.create({
  content: 'https://example.com',
  mode: 'DYNAMIC',
  name: 'My QR Code',
});
console.log(qr.id, qr.shortLink);

API

new CodeBox(options)

| Option | Type | Required | Description | |--------|------|----------|-------------| | apiKey | string | Yes | Your CodeBox API key | | baseUrl | string | No | API base URL (default: https://www.codebox.club) |

QR Codes

| Method | Description | |--------|-------------| | client.qrcodes.create(params) | Create a QR code | | client.qrcodes.getStats(id, opts?) | Get scan analytics | | client.qrcodes.update(id, params) | Update target URL / name / status | | client.qrcodes.list(params?) | List QR codes with pagination | | client.qrcodes.delete(id) | Soft-delete a QR code | | client.qrcodes.clone(id, params?) | Clone a QR code | | client.qrcodes.batchCreate(items) | Batch create up to 20 QR codes | | client.qrcodes.getScans(id, params?) | Get raw scan events |

Templates

| Method | Description | |--------|-------------| | client.templates.list() | List available style templates |

Webhooks

| Method | Description | |--------|-------------| | client.webhooks.create(params) | Create a webhook | | client.webhooks.list(params?) | List webhooks | | client.webhooks.update(id, params) | Update a webhook | | client.webhooks.delete(id) | Delete a webhook |

Error Handling

import { CodeBox, AuthenticationError, RateLimitError, CodeBoxError } from '@codebox/sdk';

try {
  await client.qrcodes.create({ content: 'https://example.com' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid or expired API key (401)
  } else if (error instanceof RateLimitError) {
    // Rate limited (429), check error.retryAfter
  } else if (error instanceof CodeBoxError) {
    // Other API error, check error.status and error.code
  }
}

Documentation

Full documentation: https://www.codebox.club/docs/sdk