@buun_group/gunspec-sdk

Official TypeScript SDK for the GunSpec.io firearms specification database API.

Installation

npm install @buun_group/gunspec-sdk

Quick Start

import { GunSpec } from '@buun_group/gunspec-sdk';

// Reads GUNSPEC_API_KEY from process.env automatically
const client = new GunSpec();

// List firearms
const { data, pagination } = await client.firearms.list({
  category: 'pistol',
  manufacturer: 'glock',
});

for (const firearm of data) {
  console.log(firearm.name, firearm.caliber);
}

// Get a single firearm
const { data: glock } = await client.firearms.get('glock-g17');
console.log(glock.name);

Configuration

import { GunSpec } from '@buun_group/gunspec-sdk';

const client = new GunSpec({
  apiKey: process.env.GUNSPEC_API_KEY,  // or set env var
  baseURL: 'https://api.gunspec.io',    // default
  timeout: 30000,                        // 30s default
  retry: {
    maxRetries: 2,                       // default
    initialDelayMs: 500,                 // default
  },
});

Resources

| Resource | Methods | |----------|---------| | client.firearms | list, get, search, compare, gameMeta, actionTypes, filterOptions, random, top, headToHead, byFeature, byAction, byMaterial, byDesigner, powerRating, timeline, byConflict, getVariants, getImages, getGameStats, getDimensions, getUsers, getFamilyTree, getSimilar, getAdoptionMap, getGameProfile, getSilhouette, calculate, load, listAutoPaging | | client.manufacturers | list, get, getFirearms, getTimeline, getStats, listAutoPaging | | client.calibers | list, get, compare, ballistics, getFirearms, getParentChain, getFamily, getAmmunition, listAutoPaging | | client.categories | list, getFirearms | | client.stats | summary, productionStatus, fieldCoverage, popularCalibers, prolificManufacturers, byCategory, byEra, materials, adoptionByCountry, adoptionByType, actionTypes, featureFrequency, caliberPopularityByEra | | client.game | balanceReport, tierList, matchups, roleRoster, statDistribution | | client.gameStats | listVersions, listFirearms, getFirearm | | client.ammunition | list, get, getBulletSvg, ballistics, listAutoPaging | | client.countries | list, getArsenal | | client.conflicts | list | | client.dataQuality | coverage, confidence | | client.favorites | list, add, remove | | client.reports | create, list | | client.support | create, list, get, reply | | client.webhooks | list, create, get, update, delete, test | | client.usage | get |

Auto-Pagination

for await (const firearm of client.firearms.listAutoPaging({
  category: 'rifle',
})) {
  console.log(firearm.name);
}

Error Handling

import {
  GunSpec,
  NotFoundError,
  RateLimitError,
  AuthenticationError,
} from '@buun_group/gunspec-sdk';

const client = new GunSpec();

try {
  const { data } = await client.firearms.get('nonexistent');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Not found:', error.message);
    console.log('Request ID:', error.requestId);
  } else if (error instanceof RateLimitError) {
    console.log('Retry after:', error.retryAfter, 'ms');
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  }
}

Requirements

• Node.js >= 18
• TypeScript >= 5.0 (for type-checking; not required at runtime)

License

MIT