{"id":51037193,"url":"https://github.com/dpup/meshcore-ts","last_synced_at":"2026-06-22T07:30:43.822Z","repository":{"id":360325054,"uuid":"1249603587","full_name":"dpup/meshcore-ts","owner":"dpup","description":"Typed, ergonomic TypeScript client for MeshCore Companion Radio devices (TCP/WiFi + USB serial).","archived":false,"fork":false,"pushed_at":"2026-05-25T23:16:33.000Z","size":57,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T01:18:33.436Z","etag":null,"topics":["lora","mesh-networking","meshcore","nodejs","off-grid","radio","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dpup.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-25T21:56:34.000Z","updated_at":"2026-05-25T23:16:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dpup/meshcore-ts","commit_stats":null,"previous_names":["dpup/meshcore-ts"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dpup/meshcore-ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpup%2Fmeshcore-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpup%2Fmeshcore-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpup%2Fmeshcore-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpup%2Fmeshcore-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dpup","download_url":"https://codeload.github.com/dpup/meshcore-ts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpup%2Fmeshcore-ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34639700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lora","mesh-networking","meshcore","nodejs","off-grid","radio","typescript"],"created_at":"2026-06-22T07:30:43.095Z","updated_at":"2026-06-22T07:30:43.808Z","avatar_url":"https://github.com/dpup.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# meshcore-ts\n\n\u003e A typed, ergonomic TypeScript client for [MeshCore](https://meshcore.co.uk) Companion Radio devices.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)\n[![Types: included](https://img.shields.io/badge/types-included-blue.svg)](#)\n[![Node](https://img.shields.io/badge/node-%E2%89%A518-brightgreen.svg)](#)\n[![Module: ESM](https://img.shields.io/badge/module-ESM-f7df1e.svg)](#)\n\n`meshcore-ts` is a **thin, typed wrapper** over the official\n[`@liamcottle/meshcore.js`](https://github.com/meshcore-dev/meshcore.js) — it does\n**not** reimplement the protocol. That library does the wire work; this one\ndelegates to it and adds a first-class TypeScript surface: typed methods, named\nevents, normalized values, and proper errors. So you talk to a MeshCore node over\nWiFi or USB without wrangling raw numeric byte codes and `Uint8Array`s — and you\nget upstream protocol updates for free.\n\n```ts\nimport { MeshCoreClient, TxtType } from \"@dpup/meshcore-ts\";\n\nconst client = MeshCoreClient.tcp(\"192.168.1.50\", 5000); // or .serial(\"/dev/ttyACM0\")\nclient.on(\"contactMessage\", (msg) =\u003e console.log(`${msg.pubKeyPrefix}: ${msg.text}`));\n\nawait client.connect();\n\nconst self = await client.getSelfInfo();\nconsole.log(`Connected to \"${self.name}\" — ${self.publicKey}`);\n\nconst alice = await client.findContactByName(\"alice\");\nif (alice) await client.sendTextMessage(alice, \"hello from typescript\", TxtType.Plain);\n```\n\nSave as `index.ts` and run with `bunx tsx index.ts` (the snippet uses top-level `await`, so it needs an ESM/TS runner).\n\n## Features\n\n- 🧩 **Fully typed** — typed methods, events, and data models (`Contact`, `Channel`, `SelfInfo`, `RepeaterStats`, …).\n- 📡 **Named events** — `client.on(\"contactMessage\", …)` instead of `connection.on(0x83, …)`.\n- 🔤 **Normalized data** — hex-string keys \u0026 paths, `Date` timestamps, real `boolean` flags.\n- 🛡️ **Safe by default** — typed errors (`MeshCoreError` / `…DeviceError` / `…TimeoutError`) and request timeouts so a silent device never hangs your program.\n- 🔌 **Node transports** — TCP/WiFi and USB serial, with simple factories.\n- 🪝 **Escape hatch** — the raw `meshcore.js` connection stays reachable via `client.raw`.\n\n## Install\n\n```sh\nnpm install @dpup/meshcore-ts      # or: bun add @dpup/meshcore-ts / pnpm add @dpup/meshcore-ts\n```\n\nESM-only, **Node.js ≥ 18**. The `@liamcottle/meshcore.js` dependency is installed automatically.\n\n## Documentation\n\n- **[Guide](./docs/guide.md)** — concepts and recipes: connecting, events \u0026 auto-sync, messaging, contacts, errors \u0026 timeouts, remote nodes.\n- **[API reference](./docs/api.md)** — the complete, generated reference: every method, event, model, error, and enum with full signatures.\n\nAny method that takes a contact accepts a `Contact`, a hex public-key string, or\nraw `Uint8Array` bytes. The client auto-drains incoming messages and emits\n`contactMessage` / `channelMessage` / `channelData` events by default — see the\n[guide](./docs/guide.md#events) for the full event catalog and options. When\n`autoSync` is on, attach an `error` listener so background-drain failures aren't\nlost.\n\n## Design notes\n\n- **All protocol logic lives in `@liamcottle/meshcore.js`.** This package owns\n  only the types, normalization, and safety layered on top.\n- **Node-focused, ESM-only.** Transports are TCP/WiFi and USB serial. This mirrors\n  `meshcore.js` and keeps the `serialport` dependency out of browser bundles;\n  browser BLE/WebSerial transports are intentionally not exposed.\n\n## Examples\n\n- [`examples/list-contacts.ts`](examples/list-contacts.ts) — connect and print self info + contacts.\n- [`examples/monitor.ts`](examples/monitor.ts) — a live, color-coded traffic monitor.\n\n```sh\nbun examples/monitor.ts 172.16.0.23 5000 30     # monitor a node for 30 seconds\n```\n\n## Development\n\n```sh\nbun install\nbun run typecheck   # tsc --noEmit (strict)\nbun run test        # vitest unit tests (no hardware needed)\nbun run build       # emit dist/ (ESM + .d.ts)\nbun run docs        # regenerate docs/api.md from the source\n```\n\nSee [AGENTS.md](./AGENTS.md) for architecture and contribution notes.\n\n## License\n\n[MIT](./LICENSE) © Dan Pupius\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdpup%2Fmeshcore-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdpup%2Fmeshcore-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdpup%2Fmeshcore-ts/lists"}