{"_id":"@aossie-org/thrubox-client","name":"@aossie-org/thrubox-client","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.2":{"name":"@aossie-org/thrubox-client","version":"1.0.2","description":"TypeScript SDK for ThruBox Server — a simple, self-hostable encrypted message relay","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup","test":"vitest run","test:watch":"vitest","coverage":"vitest run --coverage","lint":"eslint src/ tests/","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","format:check":"prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"","prepublishOnly":"npm run build"},"keywords":["relay","encrypted","messaging","thrubox","aossie","sdk","mailbox"],"author":{"name":"AOSSIE"},"license":"GPL-3.0","repository":{"type":"git","url":"git+https://github.com/AOSSIE-Org/ThruBox-Client.git"},"bugs":{"url":"https://github.com/AOSSIE-Org/ThruBox-Client/issues"},"homepage":"https://github.com/AOSSIE-Org/ThruBox-Client#readme","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"engines":{"node":">=18.0.0"},"devDependencies":{"@eslint/js":"^10.0.1","eslint":"^10.5.0","prettier":"^3.5.0","tsup":"^8.4.0","typescript":"^5.7.0","typescript-eslint":"^8.61.1","vitest":"^3.2.0","@vitest/coverage-v8":"^3.2.0"},"gitHead":"a29c5a2a7a582142a5b4571d242d4bed0f46bad4","_id":"@aossie-org/thrubox-client@1.0.2","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-/bEhn+Uo82j8JjSX5F/PYKYSkS3HAmMHDroisTFdEnCB1nypyYSQRC/3zH6Xs657JdUKtMqgArt+Kbh5RDG4uA==","shasum":"2015375be30525c8d906b3efa559170cc5598bce","tarball":"https://registry.npmjs.org/@aossie-org/thrubox-client/-/thrubox-client-1.0.2.tgz","fileCount":9,"unpackedSize":81731,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIH6bhvV2hrLwfrLLSVum2jlPZKb1Ba52tW3BWhWrOoMgAiEA4Q3fR2ucbqMI0+8mCOqKaGyW2JVH1SWzXtPi/69VIFo="}]},"_npmUser":{"name":"atharva0506","email":"atharvan.coder@gmail.com"},"directories":{},"maintainers":[{"name":"zahnentferner","email":"zahnentferner@gmail.com"},{"name":"kpj2006","email":"24ucs074@lnmiit.ac.in"},{"name":"atharva0506","email":"atharvan.coder@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/thrubox-client_1.0.2_1785923974917_0.8474973761237619"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-05T09:59:34.619Z","1.0.2":"2026-08-05T09:59:35.060Z","modified":"2026-08-05T09:59:35.368Z"},"maintainers":[{"name":"zahnentferner","email":"zahnentferner@gmail.com"},{"name":"kpj2006","email":"24ucs074@lnmiit.ac.in"},{"name":"atharva0506","email":"atharvan.coder@gmail.com"}],"description":"TypeScript SDK for ThruBox Server — a simple, self-hostable encrypted message relay","homepage":"https://github.com/AOSSIE-Org/ThruBox-Client#readme","keywords":["relay","encrypted","messaging","thrubox","aossie","sdk","mailbox"],"repository":{"type":"git","url":"git+https://github.com/AOSSIE-Org/ThruBox-Client.git"},"author":{"name":"AOSSIE"},"bugs":{"url":"https://github.com/AOSSIE-Org/ThruBox-Client/issues"},"license":"GPL-3.0","readme":"<!-- Don't delete it -->\r\n<div name=\"readme-top\"></div>\r\n\r\n<!-- Organization Logo -->\r\n<div align=\"center\" style=\"display: flex; align-items: center; justify-content: center; gap: 16px;\">\r\n  <img alt=\"AOSSIE\" src=\"public/aossie-logo.svg\" width=\"175\">\r\n  <img alt=\"ThruBox\" src=\"public/thrubox-logo.svg\" width=\"175\" />\r\n</div>\r\n\r\n&nbsp;\r\n\r\n<!-- Organization Name -->\r\n<div align=\"center\">\r\n\r\n[![Static Badge](https://img.shields.io/badge/aossie.org-228B22?style=for-the-badge&labelColor=FFC517)](https://aossie.org/)\r\n\r\n</div>\r\n\r\n<!-- Organization/Project Social Handles -->\r\n<p align=\"center\">\r\n<!-- Telegram -->\r\n<a href=\"https://t.me/StabilityNexus\">\r\n<img src=\"https://img.shields.io/badge/Telegram-black?style=flat&logo=telegram&logoColor=white&logoSize=auto&color=24A1DE\" alt=\"Telegram Badge\"/></a>\r\n&nbsp;&nbsp;\r\n<!-- X (formerly Twitter) -->\r\n<a href=\"https://x.com/aossie_org\">\r\n<img src=\"https://img.shields.io/twitter/follow/aossie_org\" alt=\"X (formerly Twitter) Badge\"/></a>\r\n&nbsp;&nbsp;\r\n<!-- Discord -->\r\n<a href=\"https://discord.gg/hjUhu33uAn\">\r\n<img src=\"https://img.shields.io/discord/1022871757289422898?style=flat&logo=discord&logoColor=white&logoSize=auto&label=Discord&labelColor=5865F2&color=57F287\" alt=\"Discord Badge\"/></a>\r\n&nbsp;&nbsp;\r\n<!-- LinkedIn -->\r\n<a href=\"https://www.linkedin.com/company/aossie/\">\r\n  <img src=\"https://img.shields.io/badge/LinkedIn-black?style=flat&logo=LinkedIn&logoColor=white&logoSize=auto&color=0A66C2\" alt=\"LinkedIn Badge\"></a>\r\n&nbsp;&nbsp;\r\n<!-- Youtube -->\r\n<a href=\"https://www.youtube.com/@AOSSIE-Org\">\r\n  <img src=\"https://img.shields.io/youtube/channel/subscribers/UCKVVLbawY7Gej_3o2WKsoiA?style=flat&logo=youtube&logoColor=white%20&logoSize=auto&labelColor=FF0000&color=FF0000\" alt=\"Youtube Badge\"></a>\r\n</p>\r\n\r\n\r\n<p align=\"center\">\r\n  <a href=\"https://scorecard.dev/viewer/?uri=github.com/AOSSIE-Org/ThruBox-Client\">\r\n    <img src=\"https://api.scorecard.dev/projects/github.com/AOSSIE-Org/ThruBox-Client/badge\" alt=\"OpenSSF Scorecard\"/>\r\n  </a>\r\n  &nbsp;&nbsp;\r\n  <a href=\"./BestPracticesChecklist.md\">\r\n    <img src=\"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FAOSSIE-Org%2FThruBox-Client%2Fmain%2Fchecklist-status.json&query=%24.percent&suffix=%25&label=Best%20Practices&logo=openssf\" alt=\"Best Practices\"/>\r\n  </a>\r\n  &nbsp;&nbsp;\r\n  <a href=\"https://github.com/gitleaks/gitleaks\">\r\n    <img src=\"https://img.shields.io/badge/protected%20by-gitleaks-blue\" alt=\"Protected by Gitleaks\"/>\r\n  </a>\r\n</p>\r\n\r\n---\r\n\r\n<div align=\"center\">\r\n<h1>ThruBox Client SDK</h1>\r\n</div>\r\n\r\nA **zero-dependency** TypeScript SDK for the [ThruBox Server](https://github.com/AOSSIE-Org/ThruBox-Server). Send, receive, and manage encrypted messages with a simple API. Works in Node.js 18+ and modern browsers.\r\n\r\n---\r\n\r\n## 🚀 Features\r\n\r\n- **Zero Runtime Dependencies**: Only devDependencies for build/test\r\n- **Typed Errors**: Specific error classes for rate limiting, payload size, not found, etc.\r\n- **Automatic Retry**: Exponential backoff on 5xx and network errors\r\n- **Polling**: Built-in `poll()` helper with a stop function\r\n- **Dual Format**: Ships ESM + CJS with TypeScript declarations\r\n- **Tiny**: ~2.5 KB minified\r\n\r\n---\r\n\r\n## 💻 Tech Stack\r\n\r\n- TypeScript 5+\r\n- tsup (build)\r\n- Vitest (testing)\r\n- Native `fetch` API (no HTTP library dependency)\r\n\r\n---\r\n\r\n## 🍀 Getting Started\r\n\r\n### Install\r\n\r\n```bash\r\nnpm install @aossie/thrubox-client\r\n```\r\n\r\n### Quick Start\r\n\r\n```typescript\r\nimport { RelayClient } from '@aossie/thrubox-client';\r\n\r\nconst relay = new RelayClient('https://relay.example.com');\r\n\r\n// Send an encrypted message\r\nawait relay.send({\r\n  to: '0xRecipientWallet',\r\n  from: '0xSenderWallet',\r\n  payload: encryptedBase64String,\r\n});\r\n\r\n// Receive messages\r\nconst messages = await relay.receive('0xMyWallet');\r\n\r\n// Delete a message after reading\r\nawait relay.delete(messages[0].id);\r\n```\r\n\r\n---\r\n\r\n## 📖 API Reference\r\n\r\n### `new RelayClient(baseUrl, options?)`\r\n\r\n| Option | Type | Default | Description |\r\n|--------|------|---------|-------------|\r\n| `apiKey` | `string` | — | API key for authenticated servers |\r\n| `timeout` | `number` | `10000` | Request timeout in ms |\r\n| `retries` | `number` | `3` | Retry attempts on network errors / 5xx |\r\n\r\n### `relay.send(params): Promise<Message>`\r\n\r\nSend an encrypted message to the relay.\r\n\r\n### `relay.receive(address): Promise<Message[]>`\r\n\r\nFetch all messages for a wallet address.\r\n\r\n### `relay.delete(id): Promise<void>`\r\n\r\nDelete a specific message by ID.\r\n\r\n### `relay.poll(address, callback, options?): () => void`\r\n\r\nAuto-poll for new messages. Returns a stop function.\r\n\r\n```typescript\r\nconst stop = relay.poll('0xMyWallet', (messages) => {\r\n  console.log('New messages:', messages);\r\n}, { intervalMs: 5000 });\r\n\r\n// Later: stop polling\r\nstop();\r\n```\r\n\r\n### `relay.health(): Promise<HealthResponse>`\r\n\r\nCheck server health.\r\n\r\n---\r\n\r\n## ⚠️ Error Handling\r\n\r\n```typescript\r\nimport { RelayRateLimitError, RelayPayloadTooLargeError } from '@aossie/thrubox-client';\r\n\r\ntry {\r\n  await relay.send({ to, from, payload });\r\n} catch (e) {\r\n  if (e instanceof RelayRateLimitError) {\r\n    console.log(`Rate limited. Retry after ${e.retryAfter}s`);\r\n  }\r\n  if (e instanceof RelayPayloadTooLargeError) {\r\n    console.log('Payload exceeds server limit');\r\n  }\r\n}\r\n```\r\n\r\n---\r\n\r\n## 🔗 Repository Links\r\n\r\n1. [ThruBox Client](https://github.com/AOSSIE-Org/ThruBox-Client) — This repository (TypeScript SDK)\r\n2. [ThruBox Server](https://github.com/AOSSIE-Org/ThruBox-Server) — Go relay server\r\n\r\n---\r\n\r\n## 🙌 Contributing\r\n\r\n⭐ Don't forget to star this repository if you find it useful! ⭐\r\n\r\nThank you for considering contributing to this project! Contributions are highly appreciated and welcomed. To ensure smooth collaboration, please refer to our [Contribution Guidelines](./CONTRIBUTING.md).\r\n\r\n---\r\n\r\n## ✨ Maintainers\r\n\r\n- [Bruno](https://github.com/Zahnentferner)\r\n- [Atharva](https://github.com/Atharva0506)\r\n\r\n---\r\n\r\n## 📍 License\r\n\r\nThis project is licensed under the GNU General Public License v3.0.\r\nSee the [LICENSE](LICENSE) file for details.\r\n\r\n---\r\n\r\n## 💪 Thanks To All Contributors\r\n\r\nThanks a lot for spending your time helping ThruBox grow. Keep rocking 🥂\r\n\r\n[![Contributors](https://contrib.rocks/image?repo=AOSSIE-Org/ThruBox-Client)](https://github.com/AOSSIE-Org/ThruBox-Client/graphs/contributors)\r\n\r\n© 2025 AOSSIE\r\n","readmeFilename":"README.md","_rev":"1-a02326f0bb52d94a8620a8941723fe64"}