{"_id":"@diagrams-so/sdk","_rev":"3-316c1ec1f36efabf2a871d6043f5e2a8","name":"@diagrams-so/sdk","dist-tags":{"latest":"1.3.0"},"versions":{"1.1.0":{"name":"@diagrams-so/sdk","version":"1.1.0","keywords":["diagram","architecture","aws","azure","gcp","drawio","ai","diagrams.so"],"author":{"name":"RedHold / Diagrams.so"},"license":"Apache-2.0","_id":"@diagrams-so/sdk@1.1.0","maintainers":[{"name":"diagrams-so","email":"success@diagrams.so"}],"homepage":"https://diagrams.so","bugs":{"url":"https://github.com/RedHold/diagrams-sdk/issues"},"dist":{"shasum":"2d1296da53adb8905385ca488f6a813413e129d9","tarball":"https://registry.npmjs.org/@diagrams-so/sdk/-/sdk-1.1.0.tgz","fileCount":6,"integrity":"sha512-Wsjdx1mNbpzy9AbXVt/puI+P5AdeBQyMnrXROl+TMWKPmJNhpVFOA5PBnjv3aftCg7H75UdjrDf8vz69Jpb89Q==","signatures":[{"sig":"MEQCIGyHbbiGczybE50DQuCOxle2XEziQqWY3B7nPtf8/9YtAiBQUMm5ruDeg7YYH/wQGrQtx4GJvd7APQ7qTW/vphYUVQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":48313},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","module":"dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"bdc58bd2b589c1f962c6a847700c7e8622755db4","scripts":{"test":"node --test","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"diagrams-so","email":"success@diagrams.so"},"repository":{"url":"git+https://github.com/RedHold/diagrams-sdk.git","type":"git","directory":"typescript"},"_npmVersion":"10.8.2","description":"TypeScript SDK for the Diagrams.so public API — generate, edit, and manage cloud architecture diagrams with AI.","directories":{},"_nodeVersion":"20.20.2","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.4.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_1.1.0_1785743679025_0.966781858198841","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@diagrams-so/sdk","version":"1.2.0","keywords":["diagram","architecture","aws","azure","gcp","drawio","ai","diagrams.so"],"author":{"name":"RedHold / Diagrams.so"},"license":"Apache-2.0","_id":"@diagrams-so/sdk@1.2.0","maintainers":[{"name":"diagrams-so","email":"success@diagrams.so"}],"homepage":"https://diagrams.so","bugs":{"url":"https://github.com/RedHold/diagrams-sdk/issues"},"dist":{"shasum":"f4acd165365018525a8f9fe93eb4f8d00c6511db","tarball":"https://registry.npmjs.org/@diagrams-so/sdk/-/sdk-1.2.0.tgz","fileCount":6,"integrity":"sha512-8Dhz+ZVsQRfkff94V8P5D+C84ClKh14V1HJpvR08dl6lA5CMu783Kg2+9RWwCyulVSvYk5UfE7dAcqhBs625Gw==","signatures":[{"sig":"MEQCIFqFva3EbDyAL5GGGNumwzpycNQJEaZFRZtcL7a/GAvuAiABMfvapBRM/orF7f0iscsV5CQptlVNh93sfN7venmN/Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":60475},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","module":"dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"d92b7703326ec7f1d20a8851bb74280f4d1a916d","scripts":{"test":"node --test","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"diagrams-so","email":"success@diagrams.so"},"repository":{"url":"git+https://github.com/RedHold/diagrams-sdk.git","type":"git","directory":"typescript"},"_npmVersion":"10.8.2","description":"TypeScript SDK for the Diagrams.so public API — generate, edit, and manage cloud architecture diagrams with AI.","directories":{},"_nodeVersion":"20.20.2","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.4.0","@types/node":"^18.19.130"},"_npmOperationalInternal":{"tmp":"tmp/sdk_1.2.0_1785843002398_0.5068262076799575","host":"s3://npm-registry-packages-npm-production"}},"1.3.0":{"name":"@diagrams-so/sdk","version":"1.3.0","description":"TypeScript SDK for the Diagrams.so public API — generate, edit, and manage cloud architecture diagrams with AI.","type":"module","main":"dist/index.js","module":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc","test":"node --test","prepublishOnly":"npm run build"},"keywords":["diagram","architecture","aws","azure","gcp","drawio","ai","diagrams.so"],"license":"Apache-2.0","author":{"name":"RedHold / Diagrams.so"},"homepage":"https://diagrams.so","engines":{"node":">=18"},"devDependencies":{"@types/node":"^18.19.130","typescript":"^5.4.0"},"repository":{"type":"git","url":"git+https://github.com/RedHold/diagrams-sdk.git","directory":"typescript"},"bugs":{"url":"https://github.com/RedHold/diagrams-sdk/issues"},"_id":"@diagrams-so/sdk@1.3.0","gitHead":"f4213c7f8cb8637489db6dabe80fb272a27d9dbc","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-3tI5tovEiKespsVpBfyXJYGcm2BhY0ynyUlXqqgX8qJmaoKmjG513vRq8bY0AEdenBjo6GYltbLg+PE2kW9pKA==","shasum":"d9a8525bd95cdc350afcf1525ed487255610bce8","tarball":"https://registry.npmjs.org/@diagrams-so/sdk/-/sdk-1.3.0.tgz","fileCount":6,"unpackedSize":62513,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIE9+y0BJlCM+01eLqxXMILHJ/wyeTLMJqbMOwGD7AjK4AiEA5pYLgE4AFoTKIH5KWKL9H6AaS2ebSXFKbQ9IR+wkdNo="}]},"_npmUser":{"name":"diagrams-so","email":"success@diagrams.so"},"directories":{},"maintainers":[{"name":"diagrams-so","email":"success@diagrams.so"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_1.3.0_1785930222636_0.9808954360860263"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-03T07:54:38.842Z","modified":"2026-08-05T11:43:42.929Z","1.1.0":"2026-08-03T07:54:39.153Z","1.2.0":"2026-08-04T11:30:02.539Z","1.3.0":"2026-08-05T11:43:42.784Z"},"bugs":{"url":"https://github.com/RedHold/diagrams-sdk/issues"},"author":{"name":"RedHold / Diagrams.so"},"license":"Apache-2.0","homepage":"https://diagrams.so","keywords":["diagram","architecture","aws","azure","gcp","drawio","ai","diagrams.so"],"repository":{"type":"git","url":"git+https://github.com/RedHold/diagrams-sdk.git","directory":"typescript"},"description":"TypeScript SDK for the Diagrams.so public API — generate, edit, and manage cloud architecture diagrams with AI.","maintainers":[{"name":"diagrams-so","email":"success@diagrams.so"}],"readme":"# @diagrams-so/sdk — TypeScript SDK\n\nA thin, typed, **zero-dependency** client for the [Diagrams.so](https://diagrams.so) public API (`/api/v2`). Works in Node ≥ 18, browsers, and edge/workers (uses platform `fetch`).\n\n- Covers **all 27** `/api/v2` operations · one method per endpoint · fully typed responses\n- Zero deps · single `DiagramsAPIError` with `.code` / `.status` / `.requestId`\n- **Safe billing:** every billable call auto-attaches an `Idempotency-Key` and retries *ambiguous* failures (timeout / 5xx / in-progress) with the **same key**, so a response lost to a gateway timeout is replayed — one charge, never two\n- Built-in `429`/`503` backoff (honors `Retry-After`), async-generator **stream**, re-layout helper, and an in-process credit tally (`sessionCharges`)\n\n## Install\n```bash\nnpm install @diagrams-so/sdk\n```\n\nThen connect once, with no key to copy:\n\n```ts\nimport { login, DiagramsClient } from \"@diagrams-so/sdk\";\n\nawait login();                       // a browser opens, press Approve\nconst client = new DiagramsClient(); // reads the stored credential\n```\n\nPrefer a terminal command? `npm i -g @diagrams-so/mcp` then `diagrams-so login`\nconnects this machine for every Diagrams.so client, including this SDK. For CI,\nset `DIAGRAMS_API_KEY`.\n\n\n## Quickstart\n```ts\nimport { DiagramsClient } from \"@diagrams-so/sdk\";\n\nconst client = new DiagramsClient({ apiKey: \"dgz_live_…\" }); // or dgz_test_… (test mode — bills the same credits)\n\nconst d = await client.generate(\"AWS 3-tier web app: ALB, EC2, RDS\", { cloudProvider: \"aws\" });\nconsole.log(d.id, d.score?.score, d.warnings.length);\n\nconst w = await client.warnings(d.id);\nif (w.length) await client.fix(d.id, w[0].message, { component: w[0].component ?? undefined, warningType: w[0].type });\n\nconst drawio = await client.export(d.id, \"drawio\"); // native .drawio XML string\n```\n\n## Authentication & billing\nPass your key (from **Settings → AI Provider**). `dgz_live_` keys bill credits for `generate`/`edit`/`fix`/`relayout`/`fork`; `dgz_test_` keys are test mode — they bill the same credits (drawing your real balance, like a live key), at lower test rate limits. Reads and `enhancePrompt`/`clarifyPrompt` are free. Check balance with `client.usage()`.\n\n## Errors\n```ts\nimport { DiagramsAPIError } from \"@diagrams-so/sdk\";\ntry {\n  await client.generate(\"…\");\n} catch (e) {\n  if (e instanceof DiagramsAPIError) {\n    console.log(e.code, e.status, e.requestId); // e.g. QUOTA_EXCEEDED 402 req_abc\n  }\n}\n```\n\n## Idempotency\nEvery billable call (`generate`, `edit`, `fix`, `startRelayout`) **auto-attaches a\nfresh `Idempotency-Key`** and retries ambiguous failures with that same key, so a\ntimeout never double-charges. Pass your own key to make the window explicit or to\ndedupe across processes:\n```ts\nawait client.generate(\"…\", { idempotencyKey: \"order-42\" }); // server replays the stored result for 24h\n```\nDefinite rejections (`401`/`402`/`404`/`422`) are never retried; a call whose outcome\nis lost is recorded in `client.sessionCharges` as `status:\"unknown\"` — reconcile with\n`client.usageHistory()`. Streamed generations tally a `confirmed` charge on their\nterminal event; an applied re-layout tallies `unknown` (its credits bill\nasynchronously — the exact amount is in `usageHistory`).\n\n## Streaming\n```ts\nfor await (const { event, data } of client.generateStream(\"AWS event-driven pipeline\")) {\n  if (event === \"progress\") console.log(data.progress, data.message);\n  else if (event === \"complete\") console.log(data.id, data.usage.credits_charged);\n  else if (event === \"error\") throw new Error(data.error.message);\n}\n```\n(The TS SDK yields `{ event, data }` objects; the Python SDK yields `(event, data)` tuples — each idiomatic to its language.)\nThe diagram XML arrives only in the terminal `complete` event (after the charge).\n\n## Async re-layout\nRe-layout is token-billed on **every** run (no free allowance) and charged only on\ndelivery. The first call returns `confirmation_required`; re-call with `confirm:true`\nto accept the charge:\n```ts\nlet job = await client.relayoutAndWait(d.id);\nif ((job as any).status === \"confirmation_required\") { // re-layout always needs confirmation\n  job = await client.relayoutAndWait(d.id, { confirm: true }); // accept the credit charge\n}\n```\n\n## Pagination\n`list` / `searchGallery` / `versions` return `Page<T>` = `{ items, next_cursor, has_more }`:\n```ts\nlet cursor: string | undefined;\ndo {\n  const page = await client.list({ limit: 50, cursor });\n  page.items.forEach((item) => { /* … */ });\n  cursor = page.next_cursor ?? undefined;\n} while (cursor);\n```\n\n## Config, retries & timeouts\n```ts\nnew DiagramsClient({ apiKey, baseUrl?, timeoutMs?, maxRetries?, backoffMs?,\n                     retryDelaysMs?, retryBudgetMs? });\n```\n`timeoutMs` defaults to **450 000** (above the server-side timeout ladder, so the\nclient never aborts work the server would still deliver). `baseUrl` defaults to\n`https://api.diagrams.so/api/v2` (point at `http://localhost:8000/api/v2` for local\ndev). Reads retry `429`/`503` (honoring `Retry-After`). Billable calls retry `429` the\nsame way and every *ambiguous* failure (timeout / `502`/`503`/`504` / in-progress)\nthrough the same-key idempotent ladder (`retryDelaysMs` between attempts, capped at\n`retryBudgetMs` total) — a **single** retry layer, so a busy server is never poked twice.\n\n## Full method list\n`generate` · `generateStream` · `list` · `get` · `update` · `delete` · `edit` · `fix` · `warnings` · `startRelayout` · `relayoutStatus` · `relayoutAndWait` · `export` · `versions` · `getVersion` · `revert` · `import` · `searchGallery` · `fork` · `enhancePrompt` · `clarifyPrompt` · `usage` · `usageHistory` · `iterUsageHistory` · `me` · `meta`\n\n## License\nApache-2.0 · docs at [diagrams.so/developers](https://diagrams.so/developers)\n","readmeFilename":"README.md"}