dboxtools

A TypeScript/JavaScript client library for interacting with the DBox Tools API. This package provides a comprehensive interface for accessing Xbox disc information, releases, files, achievements, marketplace data, and store products.

Features

• 🎮 Full API Coverage - Access to all DBox Tools API endpoints
• 🔄 Automatic Retries - Built-in retry logic for failed requests
• 🚀 Modern ESM & CJS - Supports both ES modules and CommonJS

Installation

npm install dboxtools

or

yarn add dboxtools

or

pnpm add dboxtools

Quick Start

import { DBoxAPI, System } from 'dboxtools';

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

// List Xbox discs
const discs = await api.discs.listDiscs({ 
  system: System.XBOX,
  limit: 10 
});

console.log(`Found ${discs.count} discs`);
discs.items.forEach(disc => {
  console.log(`${disc.redump_name} (${disc.system})`);
});

Configuration

You can configure the API client with custom options:

import { DBoxAPI } from 'dboxtools';

const api = new DBoxAPI({
  baseURL: 'https://dbox.tools/api',  // 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

Discs API

Query and retrieve disc information from the DBox database.

import { DBoxAPI, System } from 'dboxtools';

const api = new DBoxAPI();

// List discs with filtering
const discs = await api.discs.listDiscs({
  name: 'Halo',
  system: System.XBOX360,
  limit: 20,
  offset: 0
});

// Get disc by ID
const disc = await api.discs.getDiscById(12345);

// Get disc by Redump ID
const discByRedump = await api.discs.getDiscByRedumpId(67890);

// Get disc by XMID
const discByXmid = await api.discs.getDiscByXmid('ABCD1234');

// Get disc by XEMID
const discByXemid = await api.discs.getDiscByXemid('EFGH5678');

// Get disc by Media ID
const discByMediaId = await api.discs.getDiscByMediaId('IJKL9012');

// Get files on a disc
const files = await api.discs.getDiscFiles(12345);

Releases API

Access release information for Xbox games.

import { DBoxAPI, System } from 'dboxtools';

const api = new DBoxAPI();

// List releases
const releases = await api.releases.listReleases({
  name: 'Halo',
  system: System.XBOX,
  limit: 10
});

// Get release by ID
const release = await api.releases.getReleaseById('release-id-123');

Files API

Query file information including XBE and STFS files.

import { DBoxAPI, CertificateRegionChoices } from 'dboxtools';

const api = new DBoxAPI();

// Get discs containing a specific file
const discs = await api.files.getDiscsForFile('md5-hash-here');

// List XBE files with filtering
const xbeFiles = await api.files.listXbeFiles({
  title_id: '4D530064',
  region: CertificateRegionChoices.ONE,
  limit: 50
});

// Get XBE file details
const xbeFile = await api.files.getXbeFile('md5-hash-here');

// Get STFS file details
const stfsFile = await api.files.getStfsFile('md5-hash-here');

Title IDs API

Query Xbox title ID information.

import { DBoxAPI, System } from 'dboxtools';

const api = new DBoxAPI();

// List title IDs
const titleIds = await api.titleIds.listTitleIDs({
  name: 'Halo',
  system: System.XBOX360,
  limit: 20
});

// Get title ID details
const titleId = await api.titleIds.getTitleID('4D530064');

Achievements API

Retrieve Xbox achievement data for titles.

import { DBoxAPI } from 'dboxtools';

const api = new DBoxAPI();

// Get V1 achievements
const v1Achievements = await api.achievements.getV1Achievements('4D530064');

// Get V2 achievements
const v2Achievements = await api.achievements.getV2Achievements('4D530064');

Marketplace API

Access Xbox Marketplace product information.

import { DBoxAPI } from 'dboxtools';

const api = new DBoxAPI();

// List marketplace products
const products = await api.marketplace.listProducts({
  product_type: 1,
  limit: 50
});

// Get product details
const product = await api.marketplace.getProduct('product-id-here');

// Get product children
const children = await api.marketplace.getProductChildren('product-id-here', {
  product_type: 2
});

// List product instances
const instances = await api.marketplace.listProductInstances({
  product_id: 'product-id-here',
  limit: 20
});

// Get product instance
const instance = await api.marketplace.getProductInstance('instance-id-here');

// List product types
const productTypes = await api.marketplace.listProductTypes();

// Get product type
const productType = await api.marketplace.getProductType(1);

// List categories
const categories = await api.marketplace.listCategories({
  parent: 1
});

// Get category
const category = await api.marketplace.getCategory(1);

// List locales
const locales = await api.marketplace.listLocales();

// Get locale
const locale = await api.marketplace.getLocale('en-US');

Store API

Access Xbox Store product information.

import { DBoxAPI, StoreProductType, StoreProductFamily } from 'dboxtools';

const api = new DBoxAPI();

// List store products
const products = await api.store.listProducts({
  product_type: StoreProductType.Game,
  product_family: StoreProductFamily.Games,
  limit: 50
});

// Get product details
const product = await api.store.getProduct('product-id-here');

// Get related products
const related = await api.store.getProductRelated('product-id-here');

// Get product SKU
const sku = await api.store.getProductSku('product-id-here', 'sku-id-here');

TypeScript Support

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

import { 
  DBoxAPI, 
  DiscSchema, 
  System,
  type ListDiscsParams 
} from 'dboxtools';

const api = new DBoxAPI();

const params: ListDiscsParams = {
  system: System.XBOX360,
  limit: 10
};

const result: PagedDiscSchema = await api.discs.listDiscs(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 { DBoxAPI } from 'dboxtools';

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

try {
  const discs = await api.discs.listDiscs();
} catch (error) {
  // Handle errors
  console.error('Failed to fetch discs:', error);
}

Available Enums

import { 
  System,
  CertificateRegionChoices,
  StoreProductType,
  StoreProductFamily,
  StoreProductOrderFields,
  StoreProductOrderDirection
} from 'dboxtools';

// System enum values
System.XBOX
System.XBOX360
System.XBOXONE
System.XBOXSERIESXS
System.PC
System.MOBILE

// Store product types
StoreProductType.Game
StoreProductType.Application
StoreProductType.Movie
// ... and more

Requirements

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

License

MIT

Links

• Dbox Tools Discord
• DBox Tools API

Contributing

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

Author

Tazhys