GunSpec
SDK-Referenz

GunSpec SDK

Typsicheres TypeScript-SDK für die GunSpec-API. Vollständige IntelliSense, automatische Paginierung und integrierte Wiederholungslogik.

Paket
@buun_group/gunspec-sdk
Registry
npm
Neueste Version
0.10.0
Voraussetzung
Node.js 18+
Auf npm ansehen

Erste Schritte

Installiere das SDK und frage die GunSpec-API mit voller TypeScript-Typsicherheit in unter einer Minute ab.

1

Installieren

bash
npm install @buun_group/gunspec-sdk
2

Initialisieren

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

Abfragen

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

Importe

Ein Paket bedient ESM und CommonJS, die Typen sind gebündelt. Node, Bun, Deno, Cloudflare Workers und Browser nutzen denselben Import; die einzige Laufzeitvoraussetzung ist natives 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';

Konfiguration

Das SDK liest die Umgebungsvariable GUNSPEC_API_KEY automatisch aus, oder du kannst sie explizit übergeben.

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,  },});

Fehlerbehandlung

Das SDK wirft typisierte Fehler, die du gezielt abfangen und behandeln kannst.

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');  }}

Automatische Paginierung

Verwende asynchrone Iteratoren, um automatisch durch große Ergebnismengen zu paginieren.

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}

Für Agenten und Tools

@buun_group/gunspec-sdk/tools ist die API als Manifest schreibgeschützter Tools: je ein stabiler Name, eine Beschreibung für das Modell und ein JSON-Schema, dazu Adapter für die Tool-Formate von Anthropic und OpenAI und ein Runner. Übergib das Manifest dem Modell, führe aus, was es aufruft. Die Tool-Referenz listet jedes Tool; die KI-Seite hat die Anleitungspakete.

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' });

Aktuell bleiben

Diese Seite beschreibt 0.10.0, veröffentlicht am 17. September 2026. Das Changelog listet, was sich in jeder Version geändert hat, und jede Version erscheint auch auf npm. Additive Änderungen erscheinen ohne Ankündigung; eine brechende wird dort zuerst mit datiertem Hinweis angekündigt.

bash
npm install @buun_group/gunspec-sdk@latest