JustTCG
Documentation

JavaScript / TypeScript SDK

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

Install

bash — install
install
npm install justtcg-js

Configure

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

typescript — client.ts
client.ts
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 — example.ts
example.ts
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 — response.d.ts
response.d.ts
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 — errors.ts
errors.ts
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.