{"_id":"@byok-gg/sdk","name":"@byok-gg/sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@byok-gg/sdk","version":"0.1.0","description":"TypeScript SDK for the BYOK API — AI-powered NPC interactions for games","license":"MIT","type":"module","main":"./dist/cjs/index.js","module":"./dist/esm/index.js","types":"./dist/esm/index.d.ts","exports":{".":{"import":{"types":"./dist/esm/index.d.ts","default":"./dist/esm/index.js"},"require":{"types":"./dist/cjs/index.d.ts","default":"./dist/cjs/index.js"}}},"scripts":{"build":"npm run build:esm && npm run build:cjs","build:esm":"tsc --project tsconfig.json","build:cjs":"tsc --project tsconfig.cjs.json","clean":"rm -rf dist","prepublishOnly":"npm run clean && npm run build"},"devDependencies":{"typescript":"^5.4.0"},"engines":{"node":">=18.0.0"},"keywords":["byok","ai","npc","game","sdk","streaming","sse"],"repository":{"type":"git","url":"git+https://github.com/chronicle-code/byok-sdk-ts.git"},"_id":"@byok-gg/sdk@0.1.0","gitHead":"04a457fc35e8d9ad24c559d0c2e2a71e770a8552","bugs":{"url":"https://github.com/chronicle-code/byok-sdk-ts/issues"},"homepage":"https://github.com/chronicle-code/byok-sdk-ts#readme","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-qg7MHS9zU/cJaKEuLIA2PqbZYU0rrJCptyOylptvSz19KqgPZy3R7OZPzftC+gi4P0s7qIcDNtTIis9cwFiYkA==","shasum":"7c9314e9afa83e98876a4c4bbf5c5549d3536eba","tarball":"https://registry.npmjs.org/@byok-gg/sdk/-/sdk-0.1.0.tgz","fileCount":82,"unpackedSize":138481,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDgcfLt12Vd3a7sqbl9ZrFq7Ht5pgqak2b4cjr/hhgcXwIgVaHroqZRjJJbQjLfeVUUYMxmJ0qHH1St+bX1Z1BlJyY="}]},"_npmUser":{"name":"byok-gg","email":"admin@byok.gg"},"directories":{},"maintainers":[{"name":"byok-gg","email":"admin@byok.gg"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.0_1771008953791_0.26721459330938524"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-13T18:55:53.602Z","0.1.0":"2026-02-13T18:55:53.971Z","modified":"2026-02-13T18:55:54.536Z"},"maintainers":[{"name":"byok-gg","email":"admin@byok.gg"}],"description":"TypeScript SDK for the BYOK API — AI-powered NPC interactions for games","homepage":"https://github.com/chronicle-code/byok-sdk-ts#readme","keywords":["byok","ai","npc","game","sdk","streaming","sse"],"repository":{"type":"git","url":"git+https://github.com/chronicle-code/byok-sdk-ts.git"},"bugs":{"url":"https://github.com/chronicle-code/byok-sdk-ts/issues"},"license":"MIT","readme":"# @byok/sdk\n\nTypeScript SDK for the [BYOK](https://byok.gg) API — AI-powered NPC interactions for games.\n\n- Zero dependencies (native `fetch`)\n- Full TypeScript types for every request and response\n- Async iterators for streaming chat\n- Works in Node.js (>=18) and browsers\n- ESM + CommonJS dual output\n\n## Install\n\n```bash\nnpm install @byok/sdk\n```\n\n## Quickstart\n\n```typescript\nimport { ByokClient } from \"@byok/sdk\";\n\nconst client = new ByokClient({\n  apiKey: \"byok_sk_...\",\n  defaultUserId: \"player_123\",\n});\n\n// Chat with an NPC\nconst response = await client.chat.create({\n  messages: [{ role: \"user\", content: \"What do you have for sale?\" }],\n  lorevaultEntityRef: \"characters/blacksmith-thorn\",\n  qualityTier: \"standard\",\n  gameState: { location: \"market_square\", gold: 150 },\n});\n\nconsole.log(response.choices[0].message.content);\n```\n\n## Streaming\n\n```typescript\nfor await (const chunk of client.chat.stream({\n  messages: [{ role: \"user\", content: \"Tell me about the ancient ruins.\" }],\n  lorevaultEntityRef: \"characters/sage-miriel\",\n})) {\n  if (!chunk.done) {\n    process.stdout.write(chunk.content);\n  }\n}\n```\n\n## Player Registration\n\n```typescript\nconst result = await client.players.register({\n  steamId: \"76561198000000000\",\n  displayName: \"DragonSlayer42\",\n});\n\nconsole.log(result.user_id); // UUID\nconsole.log(result.created); // true if new account\n```\n\n## Game Events\n\n```typescript\n// Ingest a world event (deterministic processing, no AI cost)\nawait client.events.ingest({\n  eventType: \"world.discovery\",\n  payload: { location: \"hidden_cave\", discoverer: \"player_123\" },\n});\n\n// Poll for triggered events\nconst { events } = await client.events.poll({ since: \"2025-01-01T00:00:00Z\" });\n\n// Acknowledge events\nawait client.events.ack(events[0].id);\n\n// Or batch-acknowledge\nawait client.events.ackBatch(events.map((e) => e.id));\n```\n\n## Player State\n\n```typescript\n// Get current state\nconst state = await client.state.get();\n// { markers_activated: [], location: null, custom: {} }\n\n// Update state (markers merge additively, custom deep-merges)\nawait client.state.update({\n  markers_activated: [\"bridge_unlocked\", \"blacksmith_met\"],\n  location: \"market_square\",\n  custom: { questLog: { mainQuest: \"act_2\" } },\n});\n```\n\n## Player Intelligence\n\n```typescript\n// Behavioral profile for adaptive difficulty\nconst profile = await client.players.getProfile(\"player_123\");\nconsole.log(profile.dimensions.curiosity); // 0.85\nconsole.log(profile.tags); // [\"explorer\", \"diplomat\"]\n\n// Highlight reel — memorable NPC moments\nconst { highlights } = await client.players.getHighlights(\"player_123\", {\n  limit: 20,\n});\n\n// Spending intelligence — narrative-value breakdown\nconst spending = await client.players.getSpending(\"player_123\");\n```\n\n## Wallet\n\n```typescript\nconst wallet = await client.wallet.get();\nconsole.log(`Balance: ${wallet.available_cents / 100} ${wallet.currency}`);\n```\n\n## Cross-Game Passport\n\n```typescript\n// Get a player's cross-game profile\nconst passport = await client.players.getPassport(\"user_uuid\");\nconsole.log(passport.game_count);\nconsole.log(passport.profile);\n\n// Grant passport sharing consent\nawait client.players.setPassportConsent({ consent: true });\n```\n\n## Error Handling\n\nAll API errors throw typed exceptions:\n\n```typescript\nimport {\n  ByokError,\n  AuthenticationError,\n  RateLimitError,\n  PaymentRequiredError,\n} from \"@byok/sdk\";\n\ntry {\n  await client.chat.create({ messages: [{ role: \"user\", content: \"Hi\" }] });\n} catch (err) {\n  if (err instanceof RateLimitError) {\n    console.log(`Rate limited. Retry after ${err.retryAfter}s`);\n  } else if (err instanceof AuthenticationError) {\n    console.log(\"Bad API key\");\n  } else if (err instanceof PaymentRequiredError) {\n    console.log(\"Player needs to add funds at byok.gg\");\n  } else if (err instanceof ByokError) {\n    console.log(`API error ${err.status}: ${err.message}`);\n  }\n}\n```\n\n### Error Classes\n\n| Class | HTTP Status | When |\n| --- | --- | --- |\n| `AuthenticationError` | 401 | Invalid API key, missing user, invalid session |\n| `PaymentRequiredError` | 402 | No wallet, insufficient balance, wallet frozen |\n| `ForbiddenError` | 403 | Game not active, tier unavailable, no consent |\n| `NotFoundError` | 404 | Entity/resource not found |\n| `ValidationError` | 422 | Invalid request parameters |\n| `RateLimitError` | 429 | Quota exceeded, spending limit, circuit breaker |\n| `ProviderError` | 502 | Upstream AI provider failure |\n\n## API Reference\n\n### `ByokClient`\n\n```typescript\nnew ByokClient({\n  apiKey: string;          // Required. Your SDK API key.\n  baseUrl?: string;        // Default: \"https://byok.gg\"\n  defaultUserId?: string;  // Default X-Byok-User for all requests.\n  fetch?: typeof fetch;    // Custom fetch (for testing or custom transports).\n});\n```\n\n### Namespaces\n\n| Namespace | Methods |\n| --- | --- |\n| `client.chat` | `create(req)`, `stream(req)` |\n| `client.players` | `register(req)`, `getProfile(id)`, `getHighlights(id, params?)`, `getSpending(id)`, `getPassport(userId)`, `setPassportConsent(req)` |\n| `client.events` | `poll(params?)`, `ack(id)`, `ackBatch(ids)`, `ingest(req)` |\n| `client.state` | `get()`, `update(req)` |\n| `client.wallet` | `get()` |\n\nAll methods accept an optional trailing `userId` parameter to override the client-level `defaultUserId` for that specific call.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-d94884558fa4cfb7d844a27e1e4d084e"}