GunSpec
SDK Reference

GunSpec SDK

Type-safe TypeScript SDK for the GunSpec API. Full IntelliSense, auto-pagination, and built-in retry logic.

Package
@buun_group/gunspec-sdk
Registry
npm
Latest release
0.10.0
Requires
Node.js 18+
View on npm

Getting Started

Install the SDK and start querying the GunSpec API with full TypeScript type safety in under a minute.

1

Install

bash
npm install @buun_group/gunspec-sdk
2

Initialize

typescript
// .env.localGUNSPEC_API_KEY=your_api_key // app.tsimport { GunSpec } from '@buun_group/gunspec-sdk';const client = new GunSpec();
3

Query

typescript
const { data } = await client.firearms.list({  category: 'pistol',});console.log(data[0].name);

Imports

One package serves ESM and CommonJS, with its types bundled. Node, Bun, Deno, Cloudflare Workers and browsers all take the same import; the only runtime requirement is native fetch.

typescript
// ESM (Node 18+, Bun, Deno, Cloudflare Workers, browsers)import { GunSpec, VERSION } from '@buun_group/gunspec-sdk'; // CommonJSconst { GunSpec } = require('@buun_group/gunspec-sdk'); // Types are bundled: nothing else to install.import type { Firearm, Provenance } from '@buun_group/gunspec-sdk';

Configuration

The SDK reads the GUNSPEC_API_KEY environment variable automatically, or you can pass it explicitly.

typescript
import { GunSpec } from '@buun_group/gunspec-sdk'; // Reads GUNSPEC_API_KEY from .env automaticallyconst client = new GunSpec(); // Or pass from environment explicitly (never hardcode!)const client = new GunSpec({  apiKey: process.env.GUNSPEC_API_KEY,  baseURL: 'https://api.gunspec.io', // optional  timeout: 30000,                     // optional  retry: {    maxRetries: 3,    initialDelayMs: 500,  },});

Error Handling

The SDK throws typed errors that you can catch and handle specifically.

typescript
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('Firearm not found:', error.message);    console.log('Request ID:', error.requestId);  } else if (error instanceof RateLimitError) {    console.log('Rate limited, retry after:', error.retryAfter);  } else if (error instanceof AuthenticationError) {    console.log('Invalid API key');  }}

Auto-Pagination

Use async iterators to automatically paginate through large result sets.

typescript
// Automatically fetches next pages as neededfor await (const firearm of client.firearms.listAutoPaging({  category: 'rifle',})) {  console.log(firearm.name);  // Breaks or continues as needed - pages fetched on demand}

For agents and tools

@buun_group/gunspec-sdk/tools is the API restated as a manifest of read-only tools: a stable name, a model-facing description and a JSON Schema for each, plus adapters for the Anthropic and OpenAI tool formats and a runner. Hand the manifest to the model, run what it calls. The tools reference lists every tool; the AI page has the instruction packs.

typescript
import { GunSpec } from '@buun_group/gunspec-sdk';import { GUNSPEC_TOOLS, asAnthropicTools, asOpenAITools, executeTool } from '@buun_group/gunspec-sdk/tools'; const client = new GunSpec(); // Hand the manifest to the model as tools ...const tools = asAnthropicTools(GUNSPEC_TOOLS); // or asOpenAITools(GUNSPEC_TOOLS) // ... and run whatever it calls. Every tool is read-only.const result = await executeTool(client, 'gunspec_resolve_firearm', { name: 'G19 gen 5' });

Stay current

This page describes 0.10.0, released September 17, 2026. The changelog lists what changed in every release, and every release also appears on npm. Additive changes ship without notice; a breaking one is announced there first with a dated notice.

bash
npm install @buun_group/gunspec-sdk@latest