{"id":23970585,"url":"https://github.com/humanjavaenterprises/nostr-websocket-utils","last_synced_at":"2026-02-16T09:35:53.616Z","repository":{"id":266792547,"uuid":"899361241","full_name":"HumanjavaEnterprises/nostr-websocket-utils","owner":"HumanjavaEnterprises","description":"The nostr-websocket-utils repository offers a TypeScript library that provides robust WebSocket utilities for Nostr applications. It features automatic reconnection with configurable attempts, heartbeat monitoring, message queuing during disconnections, channel-based broadcasting, type-safe message handling, and built-in logging.","archived":false,"fork":false,"pushed_at":"2025-01-28T23:26:01.000Z","size":867,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-24T20:50:33.565Z","etag":null,"topics":["channel-broadcasting","heartbeat-monitoring","logging","message-queuing","nostr","real-time-communication","reconnection","type-safety","websocket"],"latest_commit_sha":null,"homepage":"","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/HumanjavaEnterprises.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["humanjavaenterprises"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":["https://getalby.com/p/vveerrgg","https://blockchair.com/bitcoin/address/bc1qw6kasfudkd64sts2q5a0lpm8zgea9txjc4gxj7","https://blockchair.com/litecoin/address/ltc1qhvt82z3308nr2gmpfuhldmu9cw3d943n7lf2we"]}},"created_at":"2024-12-06T05:34:55.000Z","updated_at":"2025-09-01T06:53:53.000Z","dependencies_parsed_at":"2025-01-02T20:22:42.408Z","dependency_job_id":"c5b9b473-cc61-4c65-9b78-723e207e9681","html_url":"https://github.com/HumanjavaEnterprises/nostr-websocket-utils","commit_stats":null,"previous_names":["humanjavaenterprises/nostr-websocket-utils"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/HumanjavaEnterprises/nostr-websocket-utils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumanjavaEnterprises%2Fnostr-websocket-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumanjavaEnterprises%2Fnostr-websocket-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumanjavaEnterprises%2Fnostr-websocket-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumanjavaEnterprises%2Fnostr-websocket-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HumanjavaEnterprises","download_url":"https://codeload.github.com/HumanjavaEnterprises/nostr-websocket-utils/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HumanjavaEnterprises%2Fnostr-websocket-utils/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29504820,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-16T09:05:14.864Z","status":"ssl_error","status_checked_at":"2026-02-16T08:55:59.364Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["channel-broadcasting","heartbeat-monitoring","logging","message-queuing","nostr","real-time-communication","reconnection","type-safety","websocket"],"created_at":"2025-01-07T02:07:17.139Z","updated_at":"2026-02-16T09:35:53.598Z","avatar_url":"https://github.com/HumanjavaEnterprises.png","language":"TypeScript","funding_links":["https://github.com/sponsors/humanjavaenterprises","https://getalby.com/p/vveerrgg","https://blockchair.com/bitcoin/address/bc1qw6kasfudkd64sts2q5a0lpm8zgea9txjc4gxj7","https://blockchair.com/litecoin/address/ltc1qhvt82z3308nr2gmpfuhldmu9cw3d943n7lf2we"],"categories":[],"sub_categories":[],"readme":"# nostr-websocket-utils\n\n[![npm version](https://img.shields.io/npm/v/@humanjavaenterprises/nostr-websocket-utils.svg)](https://www.npmjs.com/package/@humanjavaenterprises/nostr-websocket-utils)\n[![License](https://img.shields.io/npm/l/@humanjavaenterprises/nostr-websocket-utils.svg)](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/blob/main/LICENSE)\n[![Build Status](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/workflows/CI/badge.svg)](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/actions)\n[![Documentation](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/workflows/Documentation/badge.svg)](https://humanjavaenterprises.github.io/nostr-websocket-utils/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org)\n[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)\n\nA TypeScript library for building Nostr protocol WebSocket clients and servers.\n\n## Features\n\n- 🚀 Full Nostr protocol support with nostr-crypto-utils integration\n- 🔒 Secure WebSocket connections\n- ♥️ Heartbeat mechanism for connection health\n- 🔄 Automatic reconnection handling\n- 📝 Comprehensive logging with Pino v8\n- 🎯 Type-safe message handling\n- 📦 Easy to use API\n- 🧪 Vitest-powered test suite\n\n## NIPs Support Status\n\n🟢 Fully implemented 🟡 Partially implemented 🔴 Not implemented\n\n| NIP | Status | Description |\n|-----|--------|-------------|\n| 01 | 🟢 | Basic protocol flow \u0026 WebSocket connections |\n| 02 | 🟢 | Contact List and Petnames |\n| 11 | 🟢 | Relay Information Document |\n| 15 | 🟢 | End of Stored Events Notice |\n| 16 | 🟢 | Event Treatment |\n| 20 | 🟢 | Command Results |\n| 42 | 🟢 | Authentication of clients to relays |\n\n### WebSocket Protocol Implementation Details\n\nThis package implements the Nostr WebSocket protocol with full support for the core NIPs that define WebSocket behavior. Here's how it works:\n\n#### Key Features \u0026 Compliance\n\n1. **Protocol Implementation**:\n   - Full implementation of Nostr WebSocket protocol\n   - Support for all standard message types (EVENT, REQ, CLOSE, etc.)\n   - Robust error handling and status reporting\n\n2. **Connection Management**:\n   - Automatic reconnection with configurable backoff\n   - Heartbeat mechanism for connection health\n   - Connection pooling and load balancing\n\n3. **Message Handling**:\n   - Type-safe message processing\n   - Support for subscription management\n   - Efficient event filtering\n\n4. **Security \u0026 Best Practices**:\n   - Secure WebSocket connections (WSS)\n   - Implementation of authentication protocols\n   - Rate limiting and protection mechanisms\n\n#### Interoperability\n\nThis implementation ensures compatibility with:\n- All major Nostr relays\n- Other Nostr clients and libraries\n- Standard WebSocket tooling and infrastructure\n\n#### Validation \u0026 Testing\n\nThe package includes:\n- Comprehensive test suites for protocol compliance\n- Connection reliability testing\n- Performance benchmarks for message handling\n\n## Installation\n\n```bash\nnpm install nostr-websocket-utils\n```\n\n## Quick Start\n\n### Creating a Nostr WebSocket Client\n\n```typescript\nimport { NostrWSClient } from 'nostr-websocket-utils';\n\nconst client = new NostrWSClient('wss://relay.example.com', {\n  logger: console,\n  heartbeatInterval: 30000,\n  handlers: {\n    message: async (msg) =\u003e console.log('Received:', msg),\n    error: (err) =\u003e console.error('Error:', err),\n    close: () =\u003e console.log('Connection closed')\n  }\n});\n\nawait client.connect();\n```\n\n### Creating a Nostr WebSocket Server\n\n```typescript\nimport { createNostrServer } from '@humanjavaenterprises/nostr-websocket-utils';\n\nconst server = await createNostrServer(8080, {\n  logger: console,\n  heartbeatInterval: 30000,\n  handlers: {\n    message: async (ws, msg) =\u003e {\n      console.log('Received message:', msg);\n      // Handle the message\n    }\n  }\n});\n```\n\n## Browser Usage\n\nThis library now supports direct browser usage! You can use it in your client-side applications in two ways:\n\n### Via NPM (Recommended)\n\n```javascript\nimport { NostrWSClient } from 'nostr-websocket-utils';\n\nconst client = new NostrWSClient({\n  url: 'wss://relay.damus.io',\n  options: {\n    autoReconnect: true,\n    maxRetries: 3\n  }\n});\n\nclient.onMessage((message) =\u003e {\n  console.log('Received:', message);\n});\n\nclient.connect();\n```\n\n### Via CDN\n\n```html\n\u003cscript src=\"https://unpkg.com/nostr-websocket-utils/dist/browser/nostr-websocket-utils.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  const client = new NostrWebSocketUtils.NostrWSClient({\n    url: 'wss://relay.damus.io',\n    options: {\n      autoReconnect: true,\n      maxRetries: 3\n    }\n  });\n\n  client.onMessage((message) =\u003e {\n    console.log('Received:', message);\n  });\n\n  client.connect();\n\u003c/script\u003e\n```\n\n### Features in Browser Environment\n\n- Direct WebSocket connections to Nostr relays\n- Automatic reconnection handling\n- Message queueing\n- Type-safe handlers\n- Full compatibility with browser environments\n- Source maps for better debugging\n\nSee the `examples/browser.html` file for a complete example of browser usage.\n\n## Dependencies\n\nThis package uses:\n- nostr-crypto-utils (^0.4.2) for cryptographic operations\n- pino (^8.17.2) for logging\n- ws (^8.16.0) for WebSocket functionality\n- uuid (^9.0.0) for unique identifiers\n\n## Documentation\n\nComprehensive API documentation is available in our [documentation site](https://humanjavaenterprises.github.io/nostr-websocket-utils/). Here's what you'll find:\n\n### Core Components\n- [NostrWSClient](docs/classes/NostrWSClient.md) - WebSocket client implementation\n- [NostrWSServer](docs/classes/NostrWSServer.md) - WebSocket server implementation\n- [NostrServer](docs/classes/NostrServer.md) - High-level Nostr server\n\n### Types and Interfaces\n- [NostrWSMessage](docs/interfaces/NostrWSMessage.md) - Message structure\n- [NostrWSOptions](docs/interfaces/NostrWSOptions.md) - Configuration options\n- [NostrWSSubscription](docs/interfaces/NostrWSSubscription.md) - Subscription interface\n- [ExtendedWebSocket](docs/interfaces/ExtendedWebSocket.md) - Enhanced WebSocket interface\n\n### Utility Functions\n- [createServer](docs/functions/createServer.md) - Server creation helper\n- [getLogger](docs/functions/getLogger.md) - Logging utility\n\n### Type Definitions\n- [MessageType](docs/enumerations/NostrWSMessageType.md) - Message type enumeration\n- [Global Types](docs/globals.md) - Global type definitions\n\n## Examples\n\n### Subscribe to a Channel\n\n```typescript\nclient.subscribe('my-channel', {\n  filter: {\n    authors: ['pubkey1', 'pubkey2'],\n    kinds: [1]\n  }\n});\n```\n\n### Broadcast a Message\n\n```typescript\nserver.broadcast({\n  type: 'event',\n  data: {\n    content: 'Hello everyone!',\n    kind: 1\n  }\n});\n```\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Related Projects\n\n- [nostr-protocol](https://github.com/nostr-protocol/nostr)\n\n## Support\n\nIf you have any questions or need help, please:\n\n1. Check the [documentation](https://humanjavaenterprises.github.io/nostr-websocket-utils/)\n2. Open an [issue](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhumanjavaenterprises%2Fnostr-websocket-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhumanjavaenterprises%2Fnostr-websocket-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhumanjavaenterprises%2Fnostr-websocket-utils/lists"}