---
title: "JavaScript / TypeScript SDK — JustTCG"
description: "Install and use justtcg-js, the official type-safe JavaScript and TypeScript SDK for the JustTCG API: configuration, usage, response shape, and error handling."
url: https://justtcg.com/docs/sdk
markdown_url: https://justtcg.com/docs/sdk.md
---

# JavaScript / TypeScript SDK

The official SDK for the JustTCG API. Type-safe, zero dependencies, optimized for Node.js.

## Install

```bash
npm install justtcg-js
```

## Configure

The client reads `JUSTTCG_API_KEY` from the environment by default. You can also pass the key directly.

```typescript
import { JustTCG } from 'justtcg-js';

// Reads JUSTTCG_API_KEY from env
const client = new JustTCG();

// Or pass the key explicitly
const client2 = new JustTCG({ apiKey: 'tcg_your_api_key_here' });
```

**Environment variable:** Setting `JUSTTCG_API_KEY` is the recommended approach for production deployments — secrets stay out of source code and rotate without redeploys.

## Basic usage

```typescript
import { JustTCG } from 'justtcg-js';

async function getTopCards() {
  try {
    const client = new JustTCG();
    const response = await client.v1.cards.get({
      game: 'Disney Lorcana',
      set: 'the-first-chapter-disney-lorcana',
      orderBy: 'price',
      order: 'desc',
      limit: 10,
      condition: ['NM', 'LP', 'MP', 'HP', 'D'],
    });

    console.log('Top cards:', response.data);
    console.log('Requests remaining:', response.usage.apiDailyRequestsRemaining);
  } catch (error) {
    console.error('An error occurred:', (error as Error).message);
  }
}

getTopCards();
```

## Response shape

Every successful call returns a typed `JustTCGApiResponse<T>`. The SDK transforms the raw API `meta` and `_metadata` fields into the friendlier `pagination` and `usage` properties.

```typescript
interface JustTCGApiResponse<T> {
  data: T;
  pagination?: {
    total: number;
    limit: number;
    offset: number;
    hasMore: boolean;
  };
  usage: {
    apiRequestLimit: number;
    apiDailyLimit: number;
    apiRateLimit: number;
    apiRequestsUsed: number;
    apiDailyRequestsUsed: number;
    apiRequestsRemaining: number;
    apiDailyRequestsRemaining: number;
    apiPlan: string;
  };
  error?: string;
  code?: string;
}
```

## Error handling

The SDK surfaces errors two ways: thrown exceptions for SDK-level issues (auth, invalid params) and an `error` property on the response for API-level issues (validation, rate limits).

```typescript
try {
  const client = new JustTCG();
  const response = await client.v1.sets.list();

  if (response.error) {
    console.log('API Error:', response.error, response.code);
  } else {
    console.log('Data:', response.data);
  }
} catch (error) {
  console.error('SDK Error:', (error as Error).message);
}
```

Looking for end-to-end recipes? See [Examples](https://justtcg.com/docs/examples).