# @slotforge/sdk

Official Node.js SDK for the **SlotForge Studio API** — generate, edit, search and approve slot-symbol artwork at production scale.

Zero dependencies. Native `fetch`. Node 18+ / modern browsers.

## Install

```bash
npm install @slotforge/sdk
# or, while the package is published privately, drop the single file in your repo:
curl -O https://kobowlotto.com/products/slotforge/sdk/slotforge-sdk.js
```

## Quickstart

```js
const { SlotForge } = require('@slotforge/sdk');

const sf = new SlotForge({
  apiKey: process.env.SLOTFORGE_API_KEY,   // grab one at https://kobowlotto.com/products/slotforge/api-keys.html
  baseUrl: 'https://kobowlotto.com',       // default
});

(async () => {
  // 1) Generate a symbol
  const img = await sf.gen({
    prompt: 'a glowing mermaid coin, polished gold, ocean treasure, white background',
    size: '1024x1024',
    brand_slug: 'pollard',
  });
  console.log('file:', img.file, 'cost (¢):', img.cost_cents);

  // 2) Approve it
  await sf.assets.approve(img.asset_id, 'looks great');

  // 3) Search for similar later
  const hits = await sf.search('mermaid gold coin');
  console.log(hits.results.slice(0, 3));

  // 4) Pull this month's spend
  const cost = await sf.costs.summary();
  console.log('month spend (USD):', cost.month_total_usd);
})();
```

## Auth

Each call sends `X-API-Key: <your key>`. Keys are workspace-scoped and revocable
in the Studio UI. Browser sessions (`sf_session` cookie from Google SSO) work
automatically when the SDK runs in a browser.

## API surface

| Resource | Methods |
|---|---|
| Top-level | `gen`, `genWithRefs`, `edit`, `upscale`, `search`, `chatPromptEdit`, `formats`, `providers`, `health`, `whoami` |
| `sf.projects` | `list`, `get`, `create`, `assets`, `attachAsset`, `symbols`, `putSymbol`, `paytable`, `setPaytable`, `simulate`, `mathSummary`, `complianceReport` |
| `sf.brands` | `list`, `get`, `create`, `previewPrompt` |
| `sf.assets` | `get`, `byFile`, `setStatus`, `approve`, `reject`, `statusBulk`, `versions`, `versionDiff`, `revert` |
| `sf.costs` | `summary` |
| `sf.audit` | `list`, `facets`, `pubkey` |
| `sf.webhooks` | `list`, `get`, `create`, `update`, `delete`, `test`, `deliveries`, `eventTypes` |
| `sf.billing` | `plans`, `me`, `checkout`, `portal`, `invoices`, `events` |
| `sf.exports` | `spriteAtlas`, `multires`, `projectZip`, `list` |
| `sf.jobs` | `enqueue`, `get`, `list`, `retry`, `stats`, `waitFor` |

## Error handling

Every failure throws a `SlotForgeError` with `status`, `code`, `body`, `requestId`:

```js
try {
  await sf.gen({ prompt: '' });
} catch (e) {
  if (e.code === 'quota_exceeded') console.log('Upgrade your plan');
  else throw e;
}
```

5xx and 429 are retried automatically (3 attempts, exponential backoff).

## Examples

See `examples/` for runnable scripts:

* `generate_symbol_set.js` — generate a full 12-symbol slot reel in one go.
* `batch_brand_swap.js` — re-skin every approved asset for a new brand.
* `watch_for_approvals.js` — long-poll approvals, fire your CI.
* `export_project_ci.js` — generate sprite atlas + multi-res from CI.
* `compliance_report.js` — pull a signed GLI report PDF for a jurisdiction.

## License

MIT © Oktop.AI / Kobow Lotto.