serialstation

A TypeScript/JavaScript client library for interacting with the SerialStation API. This package provides a comprehensive interface for accessing PlayStation title IDs, content IDs, games, franchises, and companies.

Features

• 🎮 Full API Coverage - Access to all SerialStation API endpoints
• 🔄 Automatic Retries - Built-in retry logic for failed requests
• 🚀 Modern ESM & CJS - Supports both ES modules and CommonJS
• 📦 Tree-shakeable - Import only the modules you need via sub-path exports

Installation

npm install serialstation

or

yarn add serialstation

or

pnpm add serialstation

Quick Start

import { SerialStationAPI } from 'serialstation';

// Create an API client instance
const api = new SerialStationAPI();

// List title IDs (Console: PS1, PS2, PS3, PS4, PS5, PSP, PSV, PSM)
const titleIds = await api.titleIds.listTitleIDs({ 
  system: 'PS4',
  limit: 10 
});

console.log(`Found ${titleIds.count} title IDs`);
titleIds.items.forEach(item => {
  console.log(`${item.name} (${item.title_id})`);
});

Package Exports

The package supports sub-path imports for tree-shaking. Import from the main entry or specific modules:

| Import Path | Description | |-------------|-------------| | serialstation | Main package – SerialStationAPI and all API modules | | serialstation/client | Base client (SerialStationClient) for custom API implementations | | serialstation/title-ids | Title IDs API | | serialstation/content-ids | Content IDs API | | serialstation/games | Games API | | serialstation/franchises | Franchises API | | serialstation/companies | Companies API | | serialstation/types | Shared types and enums |

// Full import (recommended for most use cases)
import { SerialStationAPI } from 'serialstation';

// Tree-shaken imports – only include what you need
import { SerialStationClient } from 'serialstation/client';
import { TitleIDsAPI } from 'serialstation/title-ids';
import { GamesAPI } from 'serialstation/games';

Configuration

You can configure the API client with custom options:

import { SerialStationAPI } from 'serialstation';

const api = new SerialStationAPI({
  baseURL: 'https://api.serialstation.com/v1',  // Default API URL
  timeout: 10000,                                // Request timeout in ms (default: 10000)
  retries: 3,                                    // Number of retry attempts (default: 3)
  retryDelay: 1000,                              // Delay between retries in ms (default: 1000)
  headers: {                                      // Additional HTTP headers
    'Custom-Header': 'value'
  }
});

API Modules

The SerialStation API provides the following endpoints (see OpenAPI spec):

• Title IDs – PlayStation title ID information
• Content IDs – Content ID lookup
• Games – Game metadata with franchises, developers, publishers
• Franchises – Franchise information
• Companies – Developer and publisher data

Title IDs API

Query PlayStation title ID information.

import { SerialStationAPI } from 'serialstation';

const api = new SerialStationAPI();

// List title IDs (system: PS1, PS2, PS3, PS4, PS5, PSP, PSV, PSM)
const titleIds = await api.titleIds.listTitleIDs({
  name: 'Gran Turismo',
  system: 'PS4',
  limit: 20,
  offset: 0
});

// Get title ID details (9-character ID, e.g. CUSA01234)
const titleId = await api.titleIds.getTitleID('CUSA01234');

Content IDs API

Query content ID information.

import { SerialStationAPI } from 'serialstation';

const api = new SerialStationAPI();

// List content IDs
const contentIds = await api.contentIds.listContentIDs({
  title_id: 'CUSA01234',
  name: 'Gran Turismo',
  limit: 20
});

// Get content ID by UUID (36 characters)
const contentId = await api.contentIds.getContentID('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx');

Games API

Query game metadata with franchises, developers, and publishers.

import { SerialStationAPI } from 'serialstation';

const api = new SerialStationAPI();

// List games with filtering
const games = await api.games.listGames({
  name: 'Gran Turismo',
  franchise: 'franchise-uuid',
  developer: 'company-uuid',
  publisher: 'company-uuid',
  limit: 20
});

// Get game by UUID
const game = await api.games.getGame('game-uuid-here');

Franchises API

Query franchise information.

import { SerialStationAPI } from 'serialstation';

const api = new SerialStationAPI();

// List franchises
const franchises = await api.franchises.listFranchises({
  limit: 100,
  offset: 0
});

Companies API

Query developer and publisher company data.

import { SerialStationAPI } from 'serialstation';

const api = new SerialStationAPI();

// List companies
const companies = await api.companies.listCompanies({
  limit: 100,
  offset: 0
});

TypeScript Support

This package is written in TypeScript and includes full type definitions. All API methods and responses are fully typed:

import { 
  SerialStationAPI, 
  TitleIDSchema, 
  type TitleIDFilterParams 
} from 'serialstation';

const api = new SerialStationAPI();

const params: TitleIDFilterParams = {
  system: 'PS4',
  limit: 10
};

const result = await api.titleIds.listTitleIDs(params);

Error Handling

The client includes automatic retry logic for rate-limited (429) and server error (5xx) responses. Failed requests will be retried up to the configured number of times with exponential backoff.

import { SerialStationAPI } from 'serialstation';

const api = new SerialStationAPI({
  retries: 5,        // Retry up to 5 times
  retryDelay: 2000  // Wait 2 seconds between retries
});

try {
  const titleIds = await api.titleIds.listTitleIDs();
} catch (error) {
  // Handle errors
  console.error('Failed to fetch title IDs:', error);
}

Available Enums

The API uses the following console values for filtering:

// Console values (for system filter)
type Console = 'PS1' | 'PS2' | 'PS3' | 'PS4' | 'PS5' | 'PSP' | 'PSV' | 'PSM';

Requirements

• Node.js >= 16.0.0
• npm, yarn, or pnpm

Dependencies

• axios ^1.6.0 – HTTP client

License

MIT

Links

• SerialStation API
• SerialStation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Tazhys