TypeScript SDK

Node.js / TypeScript SDK

A zero-dependency, fully typed client with resource classes, async pagination, automatic retries, and rate-limit awareness.

gunspec-sdk.ts

Setup

Download the file using the button above

Drop it into your project and import:

import { GunSpec } from './gunspec-sdk';

const gs = new GunSpec({
  apiKey: 'test_key',
  baseUrl: 'http://localhost:8787',
});

Zero dependencies - uses native fetch (Node 18+, Bun, Deno, browsers).

Resources

// Firearms
const list = await gs.firearms.list({ limit: 20 });
const m4 = await gs.firearms.get('m4a1-carbine');
const results = await gs.firearms.search('carbine');
const compared = await gs.firearms.compare(['m4a1-carbine', 'hk416-a5']);
const variants = await gs.firearms.variants('m4a1-carbine');
const stats = await gs.firearms.gameStats('m4a1-carbine');

// Manufacturers
const mfrs = await gs.manufacturers.list({ limit: 50 });
const colt = await gs.manufacturers.get('colt-defense');
const coltGuns = await gs.manufacturers.firearms('colt-defense');

// Calibers & Categories
const cals = await gs.calibers.list();
const cats = await gs.categories.list();
const ars = await gs.categories.firearms('assault-rifle');

Pagination

The SDK includes an async generator for iterating all pages, plus a convenience method that collects everything:

// Page by page
for await (const page of gs.paginate('/v1/firearms', { limit: 50 })) {
  console.log(`Got ${page.length} firearms`);
}

// Or collect all into one array
const all = await gs.firearms.all();
console.log(`Total: ${all.length}`);

Error Handling

import { GunSpec, GunSpecError } from './gunspec-sdk';

try {
  const firearm = await gs.firearms.get('nonexistent');
} catch (err) {
  if (err instanceof GunSpecError) {
    console.log(err.status); // 404
    console.log(err.body);   // API error response
  }
}

Automatic retries: 429 (rate limit) and 5xx errors are retried up to 3 times with exponential backoff. Configure with maxRetries in the constructor.

Configuration

Option	Default	Description
`apiKey`	(required)	Your GunSpec API key
`baseUrl`	Auto-detected	API base URL
`maxRetries`	3	Max retries on 429/5xx

Back to Assets