@buun_group/gunspec-sdk 0.1.0

package/README.md

@@ -0,0 +1,129 @@
+# @gunspec/sdk
+
+Official TypeScript SDK for the [GunSpec.io](https://gunspec.io) firearms specification database API.
+
+## Installation
+
+```bash
+npm install @gunspec/sdk
+```
+
+## Quick Start
+
+```typescript
+import { GunSpec } from '@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
+
+```typescript
+import { GunSpec } from '@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
+
+```typescript
+for await (const firearm of client.firearms.listAutoPaging({
+  category: 'rifle',
+})) {
+  console.log(firearm.name);
+}
+```
+
+## Error Handling
+
+```typescript
+import {
+  GunSpec,
+  NotFoundError,
+  RateLimitError,
+  AuthenticationError,
+} from '@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)
+
+## Publishing
+
+```bash
+cd packages/sdk
+
+# Build
+npm run build
+
+# Verify package contents
+npm pack --dry-run
+
+# Publish to npm (public scoped package)
+npm publish --access public
+```
+
+## License
+
+MIT