@angadie/chittie-transport-web 0.1.0

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Asyncdot Engineering
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+Portions of this software are vendored from MIT-licensed projects and retain
+their original copyright notices; see VENDOR.md.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @angadie/chittie-transport-web
+
+Web transports for chittie: **Web Serial**, **WebUSB**, and **Web Bluetooth**. Browser platform APIs only — no third-party dependencies. Each factory returns a [`Transport`](../chittie-transport).
+
+> Web Serial / WebUSB / Web Bluetooth require a Chromium browser (Chrome/Edge desktop) over HTTPS, and `connect()` must be called from a user gesture (click).
+
+## Install
+
+```bash
+pnpm add @angadie/chittie-transport-web @angadie/chittie-transport
+```
+
+## Web Serial (most desktop POS printers)
+
+```ts
+import { print } from '@angadie/chittie-transport';
+import { createWebSerialTransport } from '@angadie/chittie-transport-web';
+
+const transport = createWebSerialTransport({ baudRate: 9600 });
+button.onclick = () => print(transport, bytes); // connect() prompts for the port
+```
+
+`createWebSerialTransport` reconnects silently to a previously-granted port; otherwise it prompts.
+
+## Web Bluetooth (BLE printers)
+
+You supply the printer's GATT service + characteristic UUIDs:
+
+```ts
+import { createWebBluetoothTransport } from '@angadie/chittie-transport-web';
+
+const transport = createWebBluetoothTransport({
+  serviceUuid: 0x18f0,
+  characteristicUuid: 0x2af1,
+  namePrefix: 'Printer',   // optional device filter
+  chunkSize: 180,          // BLE write size
+});
+```
+
+## Bridge (USB / network printers a browser can't reach)
+
+Browsers can't open USB printer-class devices or raw TCP. Run the [`chittie print-agent`](../../tools/print-agent) on the terminal and POST bytes to it:
+
+```ts
+import { print } from '@angadie/chittie-transport';
+import { createBridgeTransport } from '@angadie/chittie-transport-web';
+
+const transport = createBridgeTransport({ url: 'http://localhost:8930', token: 'secret', printer: 'usb' });
+await print(transport, bytes); // connect() pings /health, write() POSTs /print
+```
+
+The agent raw-prints to the OS queue (Windows winspool / CUPS) or, in virtual mode, renders a PNG.
+
+## WebUSB
+
+```ts
+import { createWebUsbTransport } from '@angadie/chittie-transport-web';
+
+const transport = createWebUsbTransport({ filters: [{ vendorId: 0x0416 }] });
+```
+
+Claims the device's first interface and writes to its first OUT endpoint. Some printers need a specific interface/endpoint — open an issue if yours differs.
+
+## License
+
+MIT.

package/dist/index.d.mts

@@ -0,0 +1,39 @@
+import { Transport } from "@angadie/chittie-transport";
+
+//#region src/index.d.ts
+/** Web Serial (Chrome/Edge desktop). Reconnects to a previously-granted port silently. */
+interface WebSerialOptions {
+  baudRate?: number;
+}
+declare function createWebSerialTransport(options?: WebSerialOptions): Transport;
+/** Web Bluetooth (GATT). You supply the printer's service + characteristic UUIDs. */
+interface WebBluetoothOptions {
+  serviceUuid: string | number;
+  characteristicUuid: string | number;
+  namePrefix?: string;
+  /** BLE write size (default 180). */
+  chunkSize?: number;
+}
+declare function createWebBluetoothTransport(options: WebBluetoothOptions): Transport;
+/** WebUSB — claims the first interface and writes to its first OUT endpoint. */
+interface WebUsbOptions {
+  filters?: unknown[];
+}
+declare function createWebUsbTransport(options?: WebUsbOptions): Transport;
+/** Print-agent bridge — POST bytes to a localhost agent that drives a USB/queue printer. */
+interface BridgeOptions {
+  /** Agent base URL (default `http://localhost:8930`). */
+  url?: string;
+  /** Shared secret — sent as the `x-agent-token` header if set. */
+  token?: string;
+  /** Target OS print queue / `usb`; the agent's default if omitted. */
+  printer?: string;
+}
+/**
+ * Transport that POSTs ESC/POS bytes to the chittie print-agent (`tools/print-agent`)
+ * — the way a browser reaches a USB printer-class device (or any OS queue) that it
+ * can't open directly. `connect()` pings `/health`; `write()` POSTs to `/print`.
+ */
+declare function createBridgeTransport(options?: BridgeOptions): Transport;
+//#endregion
+export { BridgeOptions, WebBluetoothOptions, WebSerialOptions, WebUsbOptions, createBridgeTransport, createWebBluetoothTransport, createWebSerialTransport, createWebUsbTransport };

package/dist/index.mjs

@@ -0,0 +1,113 @@
+import { chunk } from "@angadie/chittie-transport";
+//#region src/index.ts
+const nav = () => globalThis.navigator;
+function createWebSerialTransport(options = {}) {
+	let port = null;
+	const baudRate = options.baudRate ?? 9600;
+	return {
+		async connect() {
+			const serial = nav().serial;
+			if (!serial) throw new Error("Web Serial is not supported (use Chrome/Edge desktop over HTTPS).");
+			port = (await serial.getPorts())[0] ?? await serial.requestPort();
+			await port.open({ baudRate });
+		},
+		async write(data) {
+			if (!port?.writable) throw new Error("Printer not connected — call connect() first.");
+			const writer = port.writable.getWriter();
+			try {
+				await writer.write(data);
+			} finally {
+				writer.releaseLock();
+			}
+		},
+		async disconnect() {
+			await port?.close();
+			port = null;
+		}
+	};
+}
+function createWebBluetoothTransport(options) {
+	let characteristic = null;
+	let device = null;
+	const chunkSize = options.chunkSize ?? 180;
+	return {
+		async connect() {
+			const bluetooth = nav().bluetooth;
+			if (!bluetooth) throw new Error("Web Bluetooth is not supported in this browser.");
+			device = await bluetooth.requestDevice({
+				filters: options.namePrefix ? [{ namePrefix: options.namePrefix }] : void 0,
+				optionalServices: [options.serviceUuid],
+				acceptAllDevices: options.namePrefix ? void 0 : true
+			});
+			characteristic = await (await (await device.gatt.connect()).getPrimaryService(options.serviceUuid)).getCharacteristic(options.characteristicUuid);
+		},
+		async write(data) {
+			if (!characteristic) throw new Error("Printer not connected — call connect() first.");
+			for (const part of chunk(data, chunkSize)) if (characteristic.writeValueWithoutResponse) await characteristic.writeValueWithoutResponse(part);
+			else await characteristic.writeValue(part);
+		},
+		async disconnect() {
+			device?.gatt?.disconnect();
+			characteristic = null;
+			device = null;
+		}
+	};
+}
+function createWebUsbTransport(options = {}) {
+	let device = null;
+	let endpoint = 1;
+	let iface = 0;
+	return {
+		async connect() {
+			const usb = nav().usb;
+			if (!usb) throw new Error("WebUSB is not supported in this browser.");
+			device = await usb.requestDevice({ filters: options.filters ?? [] });
+			await device.open();
+			if (device.configuration === null) await device.selectConfiguration(1);
+			const intf = device.configuration.interfaces[0];
+			iface = intf.interfaceNumber;
+			await device.claimInterface(iface);
+			const out = intf.alternate.endpoints.find((e) => e.direction === "out");
+			if (!out) throw new Error("No USB OUT endpoint found on this device.");
+			endpoint = out.endpointNumber;
+		},
+		async write(data) {
+			if (!device) throw new Error("Printer not connected — call connect() first.");
+			await device.transferOut(endpoint, data);
+		},
+		async disconnect() {
+			await device?.close();
+			device = null;
+		}
+	};
+}
+/**
+* Transport that POSTs ESC/POS bytes to the chittie print-agent (`tools/print-agent`)
+* — the way a browser reaches a USB printer-class device (or any OS queue) that it
+* can't open directly. `connect()` pings `/health`; `write()` POSTs to `/print`.
+*/
+function createBridgeTransport(options = {}) {
+	const base = (options.url ?? "http://localhost:8930").replace(/\/+$/, "");
+	const headers = { "content-type": "application/json" };
+	if (options.token) headers["x-agent-token"] = options.token;
+	return {
+		async connect() {
+			const res = await fetch(`${base}/health`);
+			if (!res.ok) throw new Error(`chittie: print agent not reachable at ${base} (HTTP ${res.status}).`);
+		},
+		async write(data) {
+			const body = JSON.stringify({
+				bytes: Array.from(data),
+				...options.printer ? { printer: options.printer } : {}
+			});
+			const res = await fetch(`${base}/print`, {
+				method: "POST",
+				headers,
+				body
+			});
+			if (!res.ok) throw new Error(`chittie: print agent /print failed (HTTP ${res.status}).`);
+		}
+	};
+}
+//#endregion
+export { createBridgeTransport, createWebBluetoothTransport, createWebSerialTransport, createWebUsbTransport };

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@angadie/chittie-transport-web",
+  "version": "0.1.0",
+  "description": "Web transports for chittie: Web Serial, WebUSB, Web Bluetooth. Browser platform APIs only.",
+  "license": "MIT",
+  "type": "module",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@angadie/chittie-transport": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx spikes/web-serial.spike.ts"
+  }
+}