|
| 1 | +# @szum-io/sdk |
| 2 | + |
| 3 | +Official TypeScript SDK for [szum](https://szum.io), a chart image API. |
| 4 | + |
| 5 | +Turn a JSON config into an SVG or PNG. Embed it in transactional emails, weekly digests, PDF reports, Slack messages, dashboards – anywhere an `<img>` tag works. No headless browser, no canvas, no client-side JavaScript. |
| 6 | + |
| 7 | + |
| 8 | + |
| 9 | +## Install |
| 10 | + |
| 11 | +```bash |
| 12 | +npm install @szum-io/sdk |
| 13 | +``` |
| 14 | + |
| 15 | +> **Server-side only.** The SDK sends your API key on every request. Never import it into browser code – generate signed URLs server-side and pass them to the client. |
| 16 | +
|
| 17 | +## Quick start |
| 18 | + |
| 19 | +```typescript |
| 20 | +import { Szum } from "@szum-io/sdk"; |
| 21 | + |
| 22 | +const szum = new Szum({ apiKey: process.env.SZUM_KEY! }); |
| 23 | + |
| 24 | +const png = await szum.render({ |
| 25 | + format: "png", |
| 26 | + theme: "editorial", |
| 27 | + title: "Quarterly Revenue", |
| 28 | + subtitle: "By region, FY 2025", |
| 29 | + marks: [ |
| 30 | + { |
| 31 | + type: "barY", |
| 32 | + data: [ |
| 33 | + { x: "Q1", y: 4.2, region: "Americas" }, |
| 34 | + { x: "Q2", y: 5.1, region: "Americas" }, |
| 35 | + { x: "Q1", y: 2.1, region: "EMEA" }, |
| 36 | + { x: "Q2", y: 2.8, region: "EMEA" }, |
| 37 | + ], |
| 38 | + fill: "region", |
| 39 | + }, |
| 40 | + ], |
| 41 | +}); |
| 42 | +``` |
| 43 | + |
| 44 | +## A few marks |
| 45 | + |
| 46 | +| barY | line | dot | |
| 47 | +| ----------------------- | ------------------------ | ---------------------- | |
| 48 | +|  |  |  | |
| 49 | + |
| 50 | +## Signed URLs |
| 51 | + |
| 52 | +Generate authenticated `<img>` embed URLs (Pro plan): |
| 53 | + |
| 54 | +```typescript |
| 55 | +const url = await szum.signedUrl({ |
| 56 | + format: "svg", |
| 57 | + theme: "editorial", |
| 58 | + marks: [ |
| 59 | + { |
| 60 | + type: "barY", |
| 61 | + data: [ |
| 62 | + { x: "Q1", y: 42 }, |
| 63 | + { x: "Q2", y: 58 }, |
| 64 | + ], |
| 65 | + }, |
| 66 | + ], |
| 67 | +}); |
| 68 | + |
| 69 | +// Use in HTML: <img src={url} /> |
| 70 | +``` |
| 71 | + |
| 72 | +## Configuration |
| 73 | + |
| 74 | +```typescript |
| 75 | +const szum = new Szum({ |
| 76 | + apiKey: process.env.SZUM_KEY!, |
| 77 | + timeout: 30_000, // ms, default 30s |
| 78 | + maxRetries: 2, // default 2; retries 429, 502, 503, 504, and network errors |
| 79 | +}); |
| 80 | +``` |
| 81 | + |
| 82 | +Every method accepts an optional second argument for per-call overrides: |
| 83 | + |
| 84 | +```typescript |
| 85 | +const controller = new AbortController(); |
| 86 | + |
| 87 | +await szum.render(config, { |
| 88 | + timeout: 60_000, // override client timeout |
| 89 | + signal: controller.signal, // caller-initiated cancellation |
| 90 | +}); |
| 91 | +``` |
| 92 | + |
| 93 | +Set `SZUM_DEBUG=true` in your environment to log every request, response status, timing, and retry attempt to stderr. |
| 94 | + |
| 95 | +## Error handling |
| 96 | + |
| 97 | +Errors are typed by category. Match by subclass instead of status codes: |
| 98 | + |
| 99 | +```typescript |
| 100 | +import { |
| 101 | + Szum, |
| 102 | + SzumError, |
| 103 | + SzumAuthenticationError, |
| 104 | + SzumRateLimitError, |
| 105 | + SzumInvalidRequestError, |
| 106 | + SzumConnectionError, |
| 107 | +} from "@szum-io/sdk"; |
| 108 | + |
| 109 | +try { |
| 110 | + await szum.render(config); |
| 111 | +} catch (err) { |
| 112 | + if (err instanceof SzumAuthenticationError) { |
| 113 | + // 401 – bad or missing API key |
| 114 | + } else if (err instanceof SzumRateLimitError) { |
| 115 | + // 429 – wait err.retryAfter seconds |
| 116 | + } else if (err instanceof SzumInvalidRequestError) { |
| 117 | + // 400 / 413 – bad config |
| 118 | + } else if (err instanceof SzumConnectionError) { |
| 119 | + // timeout or network error |
| 120 | + } else if (err instanceof SzumError) { |
| 121 | + console.error(err.code); // "api_error", "invalid_request", etc. |
| 122 | + console.error(err.message); |
| 123 | + console.error(err.status); // HTTP status |
| 124 | + console.error(err.retryAfter); // seconds (on 429) |
| 125 | + console.error(err.requestId); // from x-vercel-id – include in support tickets |
| 126 | + } |
| 127 | +} |
| 128 | +``` |
| 129 | + |
| 130 | +All errors serialize cleanly via `JSON.stringify(err)` (they implement `toJSON`), so they work with Sentry, Datadog, and standard loggers. |
| 131 | + |
| 132 | +## Exports |
| 133 | + |
| 134 | +| Export | Description | |
| 135 | +| ------------------------- | ------------------------------------------------------------------- | |
| 136 | +| `Szum` | Client class (`render`, `signedUrl`) | |
| 137 | +| `SzumOptions` | Constructor options (`apiKey`, `timeout`, `maxRetries`, …) | |
| 138 | +| `RequestOptions` | Per-call options (`timeout`, `signal`) | |
| 139 | +| `SzumError` | Base error (`code`, `status`, `message`, `retryAfter`, `requestId`) | |
| 140 | +| `SzumAuthenticationError` | 401 | |
| 141 | +| `SzumPermissionError` | 403 | |
| 142 | +| `SzumInvalidRequestError` | 400 / 413 | |
| 143 | +| `SzumRateLimitError` | 429 | |
| 144 | +| `SzumAPIError` | 5xx | |
| 145 | +| `SzumConnectionError` | Timeout / network | |
| 146 | +| `ChartConfig` | Config type for SDK methods (`version` optional) | |
| 147 | +| `ChartConfigInput` | Full config type including required `version` | |
| 148 | +| `SCHEMA_VERSION` | Schema version this SDK was built against | |
| 149 | + |
| 150 | +## Documentation |
| 151 | + |
| 152 | +Full reference at [szum.io/docs](https://szum.io/docs). |
0 commit comments