@candypoets/nipworker 0.92.0 → 0.94.0

package/README.md

@@ -1,342 +1,117 @@
 # @candypoets/nipworker
 
-A high-performance Nostr client library with worker-based architecture using Rust WebAssembly for optimal performance and non-blocking operations.
+A high-performance Nostr client library that moves everything off the main thread and becomes your entire application state layer.
 
 [![npm version](https://badge.fury.io/js/@candypoets%2Fnipworker.svg)](https://badge.fury.io/js/@candypoets%2Fnipworker)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-![NipWorker](static/nipworker.jpg)
+## What is NIPWorker?
 
-## 🚀 Features
+Big, opinionated, and built for speed. FlatBuffers and Web Workers at its core, compiled from Rust to WASM.
 
-- **High Performance**: Rust WASM core for cryptographic operations and message processing
-- **Worker-Based Architecture**: Non-blocking operations using Web Workers
-- **TypeScript Support**: Full TypeScript definitions included
-- **Dual Module Support**: Both ES modules and UMD builds
-- **Efficient Serialization**: Uses MessagePack for optimal data transfer
-- **Comprehensive NIP Support**: Implements 12+ standard Nostr Implementation Possibilities (NIPs)
+## Framework Agnostic
 
+Works with any frontend. No React dependency, no Svelte stores to learn, no Vue composables. Just hook-like methods with callbacks that you wire to your framework's reactivity however you want.
 
-## 📋 Supported NIPs
+## 4 Dedicated Workers
 
-| NIP | Name | Description | Event Kinds | Status |
-|-----|------|-------------|-------------|---------|
-| [NIP-01](https://github.com/nostr-protocol/nips/blob/master/01.md) | Basic Protocol | Core protocol flow description | 0, 1 | ✅ Full |
-| [NIP-02](https://github.com/nostr-protocol/nips/blob/master/02.md) | Contact List | Contact lists and petnames | 3 | ✅ Full |
-| [NIP-04](https://github.com/nostr-protocol/nips/blob/master/04.md) | Encrypted DMs | Encrypted direct messages | 4 | ✅ Full |
-| [NIP-05](https://github.com/nostr-protocol/nips/blob/master/05.md) | DNS Identifiers | Mapping keys to DNS identifiers | - | 🔄 Partial |
-| [NIP-10](https://github.com/nostr-protocol/nips/blob/master/10.md) | Text Note References | Threading and replies | - | ✅ Full |
-| [NIP-18](https://github.com/nostr-protocol/nips/blob/master/18.md) | Reposts | Event reposts | 6 | ✅ Full |
-| [NIP-19](https://github.com/nostr-protocol/nips/blob/master/19.md) | bech32 Entities | npub, note, nevent, nprofile encoding | - | ✅ Full |
-| [NIP-25](https://github.com/nostr-protocol/nips/blob/master/25.md) | Reactions | Event reactions and emoji | 7 | ✅ Full |
-| [NIP-27](https://github.com/nostr-protocol/nips/blob/master/27.md) | Text References | Mentions and references in content | - | ✅ Full |
-| [NIP-44](https://github.com/nostr-protocol/nips/blob/master/44.md) | Versioned Encryption | Advanced encryption for private events | - | ✅ Full |
-| [NIP-51](https://github.com/nostr-protocol/nips/blob/master/51.md) | Lists | Categorized lists (people, bookmarks) | 39089 | ✅ Full |
-| [NIP-57](https://github.com/nostr-protocol/nips/blob/master/57.md) | Lightning Zaps | Bitcoin Lightning Network integration | 9735 | ✅ Full |
-| [NIP-60](https://github.com/nostr-protocol/nips/blob/master/60.md) | Cashu Wallet | Cashu ecash wallet functionality | 7374, 7375, 7376, 10019, 17375 | ✅ Full |
-| [NIP-61](https://github.com/nostr-protocol/nips/blob/master/61.md) | Nutzaps | Cashu token zaps | 9321 | ✅ Full |
-| [NIP-65](https://github.com/nostr-protocol/nips/blob/master/65.md) | Relay Lists | User relay preferences | 10002 | ✅ Full |
+• **Connections** — Relay connections, WebSocket lifecycle, reconnection backoff. Owns all network I/O.
 
-### NIP-60 Cashu Wallet Events
+• **Cache** — Stores FlatBuffers in ring buffers in real time and IndexedDB in timeout chunks. No refetching what you already have.
 
-The library provides complete support for **NIP-60 Cashu wallet functionality**:
+• **Parser** — Event validation, signature verification, content parsing. Receives raw JSON from relays, outputs FlatBuffers to your frontend. No JSON.parse on the main thread. Ever.
 
-| Event Kind | Description | Encryption | Purpose |
-|------------|-------------|------------|---------|
-| 7374 | Quote events | NIP-44 | Token redemption quotes |
-| 7375 | Token events | NIP-44 | Cashu proofs and tokens |
-| 7376 | Spending history | NIP-44 | Transaction history |
-| 9321 | Nutzaps | - | Cashu token zaps |
-| 10019 | Wallet settings | - | User wallet preferences |
-| 17375 | Encrypted wallets | NIP-44 | Private wallet data |
+• **Crypto** — Signing, NIP:04/44 encryption, NIP:46 remote signer sessions, Cashu proof verification.
 
+Each worker runs in its own Web Worker. The main thread just orchestrates. Heavy work happens in parallel.
 
-### Legend
-- ✅ **Full**: Complete implementation with all features
-- 🔄 **Partial**: Basic support, some features may be limited
-- ❌ **Not Supported**: NIP is not implemented
+## FlatBuffers Instead of JSON
 
-## 📦 Installation
+NIPWorker speaks FlatBuffers end to end. Raw relay messages get parsed once in Rust, then flow through the system as zero-copy binary views. No JSON.parse. No object allocation. No GC pauses on infinite scroll.
 
-```bash
-npm install @candypoets/nipworker
-```
-
-That's it! No additional dependencies needed.
+Your components read directly from FlatBuffers tables. A Kind1 note's content blocks (images, videos, hashtags) arrive pre-parsed. You iterate them with `fbArray()` and render straight from the binary buffer to the DOM. The schema lives from wire to HTML.
 
-## 🔧 Usage
+## Apollo-Inspired State Management
 
-### Import Structure
+Like Apollo Client, NIPWorker IS your store. You do not need Redux, Zustand, or custom state libraries.
 
-The library is organized into logical modules for better tree-shaking:
+`useSubscribe` pulls FlatBuffers from the worker pool and feeds your UI directly. Subscriptions accept fetch policies: `cacheFirst` serves from memory immediately if available, `noCache` always bypass the cache and hits the network. You control the speed versus freshness tradeoff per query.
 
-```javascript
-// Core API - main functionality
-import { nostrManager, createNostrManager } from '@candypoets/nipworker';
+`usePublish` sends events and tracks relay acknowledgments. Your entire app state flows through these two hooks. Subscriptions are deduped across components automatically. The library manages the cache, merge logic, and reactive updates.
 
-// Hooks - React-style subscription hooks
-import { useSubscription } from '@candypoets/nipworker/hooks';
+## Pipeline Architecture
 
-// Types - TypeScript type definitions
-import type { 
-  ParsedEvent, 
-  Kind1Parsed, 
-  NostrManagerConfig,
-  Request 
-} from '@candypoets/nipworker/types';
+Events flow through a processing pipeline: verify → dedupe → filter → transform → store. Each subscription configures its own pipeline. The pipeline runs in the Parser worker before FlatBuffers reach your callback.
 
-// Utils - type guards and helper functions
-import { isKind1, isKind0, SignerTypes } from '@candypoets/nipworker/utils';
-```
-
-### Basic Usage
+## Opinionated by Design
 
-```javascript
-import { nostrManager } from '@candypoets/nipworker';
-import { useSubscription } from '@candypoets/nipworker/hooks';
+NIPWorker enforces outbox model by default. It reads every author's NIP:65 relay list to discover where they publish. The library manages relay discovery and publication strategy for you.
 
-// Login by setting up a signer (private key)
-nostrManager.setSigner('privkey', 'your-private-key-hex');
+Built for clients that need to render thousands of events without dropping frames.
 
-// Subscribe to events using the hook
-const unsubscribe = useSubscription(
-  'my-subscription',
-  [{
-    kinds: [1], // Text notes
-    limit: 10
-  }],
-  (events, eventType) => {
-    if (eventType === 'EVENTS') {
-      console.log('Received events:', events);
-    } else if (eventType === 'EOSE') {
-      console.log('End of stored events');
-    }
-  },
-  { closeOnEose: false }
-);
+## Installation
 
-// Publish an event
-const event = {
-  kind: 1,
-  content: 'Hello Nostr!',
-  tags: [],
-  created_at: Math.floor(Date.now() / 1000)
-};
+```bash
+npm install @candypoets/nipworker
+```
 
-nostrManager.publish('publish-id-123', event, (status, type) => {
-  console.log('Publish status:', status);
-});
+Install the skill for AI assistance:
 
-// Clean up subscription when done
-// unsubscribe();
+```bash
+npx skills add candypoets/skills@nipworker
 ```
 
-### Advanced Usage
-
-```javascript
-import { createNostrManager } from '@candypoets/nipworker';
-import { useSubscription } from '@candypoets/nipworker/hooks';
+## Quick Start
 
-// Create a custom manager instance with configuration
-const customManager = createNostrManager();
+```typescript
+import { createNostrManager, setManager } from '@candypoets/nipworker';
+import { useSubscription, usePublish } from '@candypoets/nipworker/hooks';
+import { isKind1, asKind1, fbArray } from '@candypoets/nipworker/utils';
 
-// Set up multiple signers
-customManager.setSigner('privkey', 'main-private-key-hex');
+// Create and set the global manager
+const manager = createNostrManager();
+setManager(manager);
 
-// Subscribe to specific authors with multiple filters
+// Subscribe to events
 const unsubscribe = useSubscription(
-  'author-feed',
-  [
-    {
-      kinds: [1, 6, 7],
-      authors: ['pubkey1', 'pubkey2'],
-      since: Math.floor(Date.now() / 1000) - 3600, // Last hour
-      limit: 50
-    },
-    {
-      kinds: [30023], // Long-form content
-      authors: ['pubkey1'],
-      limit: 10
-    }
-  ],
-  (events, eventType) => {
-    if (eventType === 'EVENTS') {
-      events.forEach(event => {
-        switch (event.kind) {
-          case 1:
-            console.log('Text note:', event.content);
-            break;
-          case 6:
-            console.log('Repost:', event);
-            break;
-          case 7:
-            console.log('Reaction:', event);
-            break;
-          case 30023:
-            console.log('Long-form content:', event);
-            break;
-        }
-      });
-    } else if (eventType === 'EOSE') {
-      console.log('End of stored events for author feed');
+  'feed_home',
+  [{ kinds: [1], limit: 50, relays: ['wss://relay.example.com'] }],
+  (msg) => {
+    const kind1 = isKind1(msg);
+    if (kind1) {
+      // Access content blocks directly from FlatBuffers view
+      const blocks = fbArray(kind1, 'contentBlocks');
+      renderNote(blocks);
     }
-  },
-  { closeOnEose: false }
+  }
 );
-
-// Global publish status monitoring
-customManager.addPublishCallbackAll((status, eventId) => {
-  console.log(`Event ${eventId} status:`, status);
-});
-
-// Clean up when done
-setTimeout(() => {
-  unsubscribe();
-  customManager.cleanup();
-}, 60000);
-```
-
-## 🏗️ Architecture
-
-NipWorker uses a multi-layered architecture:
-
-1. **Main Thread**: Your application code
-2. **Web Worker**: Handles network operations and message routing
-3. **Rust WASM Core**: Performs cryptographic operations and message validation
-
-This architecture ensures that heavy operations don't block your main thread, providing a smooth user experience.
-
-## 📚 API Reference
-
-### NostrManager
-
-#### Factory Function
-
-```typescript
-createNostrManager(config?: NostrManagerConfig): NostrManager
 ```
 
-#### Methods
-
-- `setSigner(name: string, secretKeyHex: string): void` - Set up a signer for publishing
-- `subscribe(subscriptionId: string, requests: Request[], options?: SubscriptionOptions): SharedArrayBuffer` - Subscribe to events
-- `publish(publishId: string, event: NostrEvent, callback?: PublishCallback): void` - Publish an event
-- `signEvent(event: NostrEvent): void` - Sign an event without publishing
-- `getPublicKey(): void` - Get the public key of the current signer
-- `unsubscribe(subscriptionId: string): void` - Unsubscribe from events
-- `cleanup(): void` - Clean up unused subscriptions
-- `addPublishCallbackAll(callback: Function): void` - Monitor all publish statuses
-
-### useSubscription Hook
-
-```typescript
-useSubscription(
-  subId: string,
-  requests: Request[],
-  callback: SubscriptionCallback,
-  options?: SubscriptionOptions
-): () => void
-```
-
-#### Parameters
-
-- `subId` - Unique subscription identifier
-- `requests` - Array of Nostr filter objects
-- `callback` - Function called when events are received
-- `options` - Subscription options (closeOnEose, skipCache, force)
-
-#### Returns
-
-- Function to unsubscribe and clean up resources
-
-### Event Types
-
-- `EVENTS` - New events received
-- `EOSE` - End of stored events
-- `EOCE` - End of cached events
-- `PUBLISH_STATUS` - Status update for published events
-
-## 🛠️ Development
-
-### Prerequisites
-
-- Node.js 18+
-- Rust 1.70+
-- wasm-pack
-
-### Building from Source
-
-```bash
-# Clone the repository
-git clone https://github.com/candypoets/nipworker.git
-cd nipworker
-
-# Install dependencies
-npm install
-
-# Build WASM modules
-npm run build:wasm
-
-# Build the library
-npm run build
-```
-
-### Scripts
-
-- `npm run dev` - Start development server
-- `npm run build` - Build for production
-- `npm run build:wasm` - Build WASM modules only
-- `npm run build:types` - Generate TypeScript declarations
-- `npm run clean` - Clean build artifacts
-
-## 🤝 Contributing
-
-We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
-
-### Development Workflow
-
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/amazing-feature`
-3. Make your changes
-4. Add tests if applicable
-5. Commit your changes: `git commit -m 'Add amazing feature'`
-6. Push to the branch: `git push origin feature/amazing-feature`
-7. Open a Pull Request
-
-## 📄 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## 🔗 Links
-
-- [GitHub Repository](https://github.com/candypoets/nipworker)
-- [Issue Tracker](https://github.com/candypoets/nipworker/issues)
-- [Nostr Protocol](https://github.com/nostr-protocol/nostr)
-- [NIPs Repository](https://github.com/nostr-protocol/nips)
-
-## 🙏 Acknowledgments
-
-- [Nostr Protocol](https://nostr.com/) - The decentralized social protocol
-- [nostr-tools](https://github.com/nbd-wtf/nostr-tools) - Essential Nostr utilities
-- [wasm-pack](https://rustwasm.github.io/wasm-pack/) - Rust to WebAssembly workflow
-
-## 📊 Performance
-
-NipWorker is designed for high performance:
+## Supported NIPs
 
-- **Fast Event Processing**: Rust WASM core processes events up to 10x faster than pure JavaScript
-- **Non-blocking Operations**: Web Worker architecture prevents UI freezing
-- **Efficient Serialization**: MessagePack reduces bandwidth usage by ~30%
-- **Connection Pooling**: Intelligent relay connection management
+| NIP | Description | Status |
+|-----|-------------|--------|
+| NIP-01 | Basic Protocol | ✅ Full |
+| NIP-02 | Contact List | ✅ Full |
+| NIP-04 | Encrypted DMs | ✅ Full |
+| NIP-18 | Reposts | ✅ Full |
+| NIP-19 | bech32 Entities | ✅ Full |
+| NIP-25 | Reactions | ✅ Full |
+| NIP-44 | Versioned Encryption | ✅ Full |
+| NIP-46 | Nostr Connect | ✅ Full |
+| NIP-51 | Lists | ✅ Full |
+| NIP-57 | Lightning Zaps | ✅ Full |
+| NIP-60 | Cashu Wallet | ✅ Full |
+| NIP-61 | Nutzaps | ✅ Full |
+| NIP-65 | Relay Lists | ✅ Full |
 
+## Documentation
 
+See [AGENTS.md](AGENTS.md) for detailed architecture documentation.
 
-## 🔒 Security
+## License
 
-- All cryptographic operations are handled by the Rust WASM core
-- Private keys never leave the worker thread
-- Event validation is performed at the WASM level
-- Secure random number generation for key operations
+MIT License - see [LICENSE](LICENSE) for details.
 
 ---