{"_id":"@davidmahbubi/tspl-bridge-sdk","name":"@davidmahbubi/tspl-bridge-sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@davidmahbubi/tspl-bridge-sdk","version":"0.1.0","description":"Browser SDK for TSPL Print Bridge — print labels on TSPL/TSPL2 thermal printers from web apps","license":"MIT","author":{"name":"David Mahbubi"},"repository":{"type":"git","url":"git+https://github.com/davidmahbubi/tspl-bridge-sdk.git"},"homepage":"https://github.com/davidmahbubi/tspl-bridge-sdk#readme","keywords":["tspl","tspl2","label","printer","thermal","tsc","barcode","print-bridge"],"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","default":"./dist/index.js"}},"sideEffects":false,"scripts":{"build":"tsc -p tsconfig.build.json","prepare":"tsc -p tsconfig.build.json"},"devDependencies":{"typescript":"^5.5.0"},"_id":"@davidmahbubi/tspl-bridge-sdk@0.1.0","gitHead":"12101506ed29a38abd8c279785bb6cffb4e4e109","bugs":{"url":"https://github.com/davidmahbubi/tspl-bridge-sdk/issues"},"_nodeVersion":"22.22.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-cls/bKy51p1y9UNIFnoeCjJfEhG8odk9vAd6fqcJniPKqimK7Q6cs0ijbRFpepwQflpckiJAvJSfEi6oPZhQkQ==","shasum":"c3f42f5fb789aa3662947f09a317be9c53c35103","tarball":"https://registry.npmjs.org/@davidmahbubi/tspl-bridge-sdk/-/tspl-bridge-sdk-0.1.0.tgz","fileCount":5,"unpackedSize":17656,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICBF7lACHtg7TNFyCyF0azpRyKRrXnOn3O/QjSo8IH9YAiAvJ4TCh+uqI1IPUb0Xc9u+CdD3VVzha8k83oicFCSuDA=="}]},"_npmUser":{"name":"davidmahbubi","email":"ulrichdavid0370@gmail.com"},"directories":{},"maintainers":[{"name":"davidmahbubi","email":"ulrichdavid0370@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/tspl-bridge-sdk_0.1.0_1783779341415_0.5184969118920248"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-11T14:15:41.299Z","0.1.0":"2026-07-11T14:15:41.541Z","modified":"2026-07-11T14:15:41.751Z"},"maintainers":[{"name":"davidmahbubi","email":"ulrichdavid0370@gmail.com"}],"description":"Browser SDK for TSPL Print Bridge — print labels on TSPL/TSPL2 thermal printers from web apps","homepage":"https://github.com/davidmahbubi/tspl-bridge-sdk#readme","keywords":["tspl","tspl2","label","printer","thermal","tsc","barcode","print-bridge"],"repository":{"type":"git","url":"git+https://github.com/davidmahbubi/tspl-bridge-sdk.git"},"author":{"name":"David Mahbubi"},"bugs":{"url":"https://github.com/davidmahbubi/tspl-bridge-sdk/issues"},"license":"MIT","readme":"# @davidmahbubi/tspl-bridge-sdk\n\nBrowser SDK for **TSPL Print Bridge** — print labels on TSPL/TSPL2 thermal printers\n(TSC, Xprinter, HPRT, and compatibles) directly from a web application.\n\nThe SDK talks to the TSPL Print Bridge desktop app (or the standalone bridge server)\nrunning on the user's machine over HTTP. It has no dependencies and works in any\nbrowser with `fetch` support.\n\n```\nYour web app ──HTTP──► TSPL Print Bridge (localhost:9123) ──► thermal printer\n```\n\n## Requirements\n\n- The [TSPL Print Bridge](../../README.md) desktop app installed and running on the\n  machine the printer is connected to.\n- The bridge API key, shown in the desktop app.\n\n## Installation\n\n```bash\nnpm install @davidmahbubi/tspl-bridge-sdk\n# or from a GitHub mirror of this package:\nnpm install github:<owner>/tspl-bridge-sdk\n```\n\nThe published package ships compiled JavaScript with type declarations; no build\nstep or bundler configuration is required.\n\n## Quick start\n\n```ts\nimport { TsplBridge } from \"@davidmahbubi/tspl-bridge-sdk\";\n\nconst bridge = new TsplBridge({ apiKey: \"your-api-key\" });\n\nif (!(await bridge.isAvailable())) {\n  // Bridge is not running — tell the user to start the desktop app.\n  return;\n}\n\nawait bridge.print({\n  label: { width: 78, height: 100, gap: 3, tear: true },\n  elements: [\n    { type: \"text\", x: 24, y: 28, content: \"Arabica Coffee 250g\", scale: 2 },\n    { type: \"barcode\", x: 24, y: 100, content: \"8991234567890\", height: 100 },\n    { type: \"qrcode\", x: 24, y: 260, content: \"https://example.com/p/123\", cellWidth: 5 },\n  ],\n});\n```\n\n## Coordinates and units\n\nLabel dimensions (`label.width`, `label.height`, `gap`, `offset`) are in **millimeters**.\nElement positions and sizes are in **dots**: at 203 dpi, 8 dots = 1 mm; at 300 dpi,\n12 dots = 1 mm. A label 78 mm wide is 624 dots across on a 203 dpi printer.\n\n## API\n\n### `new TsplBridge(options)`\n\n| Option   | Type     | Description                                          |\n|----------|----------|------------------------------------------------------|\n| `apiKey` | `string` | Required. API key from the bridge app.               |\n| `url`    | `string` | Bridge URL. Defaults to `http://127.0.0.1:9123`.     |\n\n### `bridge.isAvailable(): Promise<boolean>`\n\nReturns `true` if the bridge is reachable. Does not require the API key — use it to\ndecide whether to show printing UI at all.\n\n### `bridge.printers(): Promise<{ printers: string[]; default: string | null }>`\n\nLists printers available on the user's machine and the default printer configured\nin the bridge app.\n\n### `bridge.print(request): Promise<void>`\n\nPrints a label described declaratively. The request contains:\n\n- `label` — label configuration (see below)\n- `elements` — array of elements to draw\n- `printer` — optional printer name, overriding the bridge's default\n\n#### Label configuration\n\n| Field       | Type                  | Description                                        |\n|-------------|-----------------------|----------------------------------------------------|\n| `width`     | `number`              | Label width in mm. Required.                       |\n| `height`    | `number`              | Label height in mm. Required.                      |\n| `gap`       | `number`              | Gap between labels in mm. Default `2`.             |\n| `tear`      | `boolean`             | Stop at the label boundary after printing.         |\n| `cut`       | `number \\| \"batch\"`   | Cut every *n* labels, or once at the end of the job. Requires a cutter. |\n| `offset`    | `number`              | Shift the stop/tear position in mm (calibration).  |\n| `density`   | `number`              | Print density, `0`–`15`.                           |\n| `direction` | `0 \\| 1`              | Print direction. Default `1`.                      |\n| `copies`    | `number`              | Number of copies. Default `1`.                     |\n\n#### Elements\n\nEvery element has a `type` and a position (`x`, `y`, in dots).\n\n| Type      | Purpose            | Key fields                                                    |\n|-----------|--------------------|---------------------------------------------------------------|\n| `text`    | Single line of text | `content`, `font`, `scale` (or `xScale`/`yScale`), `rotation` |\n| `block`   | Multi-line text in an area | `content`, `width`, `height`, `font`, `scale`          |\n| `barcode` | 1D barcode         | `content`, `barcodeType` (default Code 128), `height`, `humanReadable`, `narrow`, `wide` |\n| `qrcode`  | QR code            | `content`, `ecc`, `cellWidth`, `mode`                          |\n| `box`     | Rectangle outline  | `xEnd`, `yEnd`, `thickness`                                    |\n| `bar`     | Filled rectangle   | `width`, `height`                                              |\n| `image`   | PNG image (logo)   | `data`, `width`, `threshold`, `mode`                           |\n\n##### Printing an image\n\nThe `image` element prints a PNG as a 1-bit monochrome bitmap — the usual way to put\na logo on a label. `data` is the PNG file encoded as base64; a data URL\n(`data:image/png;base64,...`) is accepted as-is, which makes canvas output directly\nusable:\n\n```ts\nconst canvas = document.querySelector(\"canvas\");\n\nawait bridge.print({\n  label: { width: 40, height: 30 },\n  elements: [\n    { type: \"image\", x: 16, y: 16, data: canvas.toDataURL(\"image/png\"), width: 160 },\n    { type: \"text\", x: 16, y: 130, content: \"Product A\" },\n  ],\n});\n```\n\n- `width` (optional) resizes the image to that many dots wide, preserving aspect\n  ratio. The printer does no scaling of its own, so size the image here: 160 dots\n  = 20 mm at 203 dpi.\n- `threshold` (optional, `0`–`255`, default `128`) is the luminance below which a\n  pixel prints black. Transparent pixels stay white.\n- `mode` (optional) controls how the bitmap combines with the label buffer:\n  `0` overwrite (default), `1` OR, `2` XOR.\n\nThermal printers reproduce hard black-and-white artwork best; grayscale and\nphotographic images lose detail at print time.\n\n### `bridge.printRaw(tspl, printer?): Promise<void>`\n\nSends a raw TSPL command string for full control over the printer:\n\n```ts\nawait bridge.printRaw('SIZE 40 mm,30 mm\\r\\nCLS\\r\\nTEXT 16,16,\"3\",0,1,1,\"Hi\"\\r\\nPRINT 1\\r\\n');\n```\n\n## Error handling\n\nAll methods throw `TsplBridgeError` on failure. `error.status` carries the HTTP\nstatus code when the bridge responded (`401` invalid API key, `400` invalid payload,\n`502` printer unreachable); it is `undefined` when the bridge could not be reached\nat all.\n\n```ts\nimport { TsplBridge, TsplBridgeError } from \"@davidmahbubi/tspl-bridge-sdk\";\n\ntry {\n  await bridge.print(request);\n} catch (err) {\n  if (err instanceof TsplBridgeError && err.status === undefined) {\n    // Bridge not running\n  } else {\n    // Bad payload, auth failure, or printer error — err.message has details\n  }\n}\n```\n\n## Notes on the API key\n\nThe key authenticates requests to the bridge on the *user's own machine* — it is not\na secret from that user. Typical setups let the user paste the key from the bridge\napp into your web app's settings screen and store it in `localStorage`.\n","readmeFilename":"README.md","_rev":"1-180642f723c9bbe2f0773603040f6ee6"}