JustTCG
Status

JavaScript/TypeScript SDK

The official JavaScript/TypeScript SDK for the JustTCG API. Access real-time and historical pricing data with type safety and clean data models.

Overview

The JustTCG JavaScript/TypeScript SDK provides a modern, type-safe way to interact with the JustTCG API. Built with TypeScript from the ground up, it offers superior developer experience with static typing, autocomplete, and clean data models.

Key Features

  • ✅ Modern & Type-Safe: Written entirely in TypeScript
  • 🔐 Versioned API Access: Clean access to API versions
  • 🧼 Clean Data Models: Automatic response transformation
  • 🚨 Robust Error Handling: Predictable, typed errors
  • 🚀 Zero Dependencies: Lightweight package
  • 🤖 Node.js First: Optimized for server-side

Quick Start

npm install justtcg-js
import { JustTCG } from 'justtcg-js';

const client = new JustTCG();
const response = await client.v1.games.list();
Environment Variable: The SDK automatically looks for the JUSTTCG_API_KEY environment variable, making authentication seamless in production environments.

Basic Usage

import { JustTCG } from 'justtcg-js';

async function getTopCards() {
  try {
    // The client automatically looks for the JUSTTCG_API_KEY environment variable
    const client = new JustTCG();

    // Or, you can provide the key directly
    // const client = new JustTCG({ apiKey: 'your_api_key_here' });

    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'], // Exclude sealed cards
    });

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

getTopCards();

Understanding Responses

All successful method calls from the client return a consistent JustTCGApiResponse object. This provides a predictable structure for handling API responses.

Response Structure

interface JustTCGApiResponse<T> {
  /** The main data payload from the API */
  data: T;
  
  /** Pagination metadata (only on paginated endpoints) */
  pagination?: {
    total: number;
    limit: number;
    offset: number;
    hasMore: boolean;
  };
  
  /** API usage metadata (included in every response) */
  usage: {
    apiRequestLimit: number;
    apiDailyLimit: number;
    apiRateLimit: number;
    apiRequestsUsed: number;
    apiDailyRequestsUsed: number;
    apiRequestsRemaining: number;
    apiDailyRequestsRemaining: number;
    apiPlan: string;
  };
  
  /** Error message (if API returns an error) */
  error?: string;
  code?: string;
}
Data Transformation: The SDK automatically transforms raw API responses into clean JavaScript objects. Furthermore, we transform the raw _metadata and metafields to pagination and usage for better clarity.

Error Handling

The SDK surfaces errors in two primary ways: thrown exceptions for critical SDK issues and an error property on the response object for API issues.

Thrown Exceptions (SDK-level)

try {
  const client = new JustTCG();
  await client.v1.games.list();
} catch (error) {
  // Handle SDK-level errors (authentication, invalid parameters, etc.)
  console.error((error as Error).message);
}

Response Error Property (API-level)

const client = new JustTCG();
const response = await client.v1.sets.list();

if (response.error) {
  // Handle API-level errors (validation, rate limits, etc.)
  console.log('API Error:', response.error);
  console.log('Error Code:', response.code);
} else {
  // Process successful response
  console.log('Data:', response.data);
}