@unicitylabs/nostr-js-sdk 0.1.1 → 0.2.1

package/README.md

@@ -4,8 +4,10 @@ A TypeScript SDK for Nostr protocol with Unicity extensions. Works in both Node.
 
 ## Features
 
+- **NIP-17 Private Messages** - Gift-wrapped private direct messages with sender anonymity
+- **NIP-44 Encryption** - Modern ChaCha20-Poly1305 AEAD encryption with HKDF
 - **BIP-340 Schnorr Signatures** - Full support for secp256k1 Schnorr signatures
-- **NIP-04 Encryption** - AES-256-CBC encryption with ECDH key agreement
+- **NIP-04 Encryption** - Legacy AES-256-CBC encryption with ECDH key agreement
 - **GZIP Compression** - Automatic compression for large messages (>1KB)
 - **Multi-Relay Support** - Connect to multiple relays with automatic reconnection
 - **Token Transfers** - Encrypted Unicity token transfers over Nostr
@@ -73,7 +75,7 @@ const event = Event.create(keyManager, {
 const eventId = await client.publishEvent(event);
 ```
 
-### Encrypted Direct Messages
+### Encrypted Direct Messages (NIP-04 Legacy)
 
 ```typescript
 // Send encrypted DM
@@ -85,6 +87,67 @@ const encrypted = await keyManager.encryptHex('Hello!', recipientPubkey);
 const decrypted = await keyManager.decryptHex(encrypted, senderPubkey);
 ```
 
+### NIP-17 Private Messages (Recommended)
+
+NIP-17 provides enhanced privacy using gift-wrapping with ephemeral keys:
+
+```typescript
+// Send private message by nametag (auto-resolves to pubkey)
+const eventId = await client.sendPrivateMessageToNametag(
+  'alice',                              // recipient nametag
+  'Hello, this is a private message!'
+);
+
+// Or send by pubkey directly
+const recipientPubkey = '...';
+const eventId = await client.sendPrivateMessage(
+  recipientPubkey,
+  'Hello, this is a private message!'
+);
+
+// Send reply to a previous message
+const eventId = await client.sendPrivateMessage(
+  recipientPubkey,
+  'This is a reply!',
+  { replyToEventId: originalEventId }
+);
+
+// Send read receipt
+await client.sendReadReceipt(senderPubkey, messageEventId);
+```
+
+Receive and unwrap private messages:
+
+```typescript
+import { Filter, EventKinds } from '@unicitylabs/nostr-sdk';
+
+// Subscribe to gift-wrapped messages
+const filter = Filter.builder()
+  .kinds(EventKinds.GIFT_WRAP)
+  .pTags(keyManager.getPublicKeyHex())
+  .build();
+
+client.subscribe(filter, {
+  onEvent: (event) => {
+    try {
+      const message = client.unwrapPrivateMessage(event);
+
+      if (message.kind === EventKinds.CHAT_MESSAGE) {
+        console.log('From:', message.senderPubkey);
+        console.log('Content:', message.content);
+
+        // Send read receipt
+        client.sendReadReceipt(message.senderPubkey, message.eventId);
+      } else if (message.kind === EventKinds.READ_RECEIPT) {
+        console.log('Read receipt for:', message.replyToEventId);
+      }
+    } catch (e) {
+      // Message not for us or decryption failed
+    }
+  },
+});
+```
+
 ### Subscriptions
 
 ```typescript
@@ -127,8 +190,28 @@ const event = await TokenTransferProtocol.createTokenTransferEvent(
 
 await client.publishEvent(event);
 
+// Create token transfer in response to a payment request
+const paymentRequestEventId = '...'; // Event ID of the original payment request
+const event = await TokenTransferProtocol.createTokenTransferEvent(
+  keyManager,
+  recipientPubkey,
+  tokenJson,
+  {
+    amount: 100n,
+    symbol: 'UNIT',
+    replyToEventId: paymentRequestEventId  // Links transfer to the payment request
+  }
+);
+
 // Parse received token transfer
 const tokenJson = await TokenTransferProtocol.parseTokenTransfer(event, keyManager);
+
+// Get reply-to event ID (for payment request correlation)
+const replyToId = TokenTransferProtocol.getReplyToEventId(event);
+if (replyToId) {
+  // This transfer is in response to a payment request
+  const originalRequest = pendingRequests.get(replyToId);
+}
 ```
 
 ### Payment Requests
@@ -223,6 +306,7 @@ Token transfers use Nostr event kind 31113 with NIP-04 encryption.
 | `type` | Yes | Always `"token_transfer"` |
 | `amount` | No | Transfer amount (metadata for filtering) |
 | `symbol` | No | Token symbol (metadata for filtering) |
+| `e` | No | Reply-to event ID (for payment request correlation) |
 
 ### Encrypted Content
 
@@ -247,10 +331,11 @@ gz:<base64_ciphertext>?iv=<base64_iv>
 TokenTransferProtocol.isTokenTransfer(event); // boolean
 
 // Get metadata from tags
-TokenTransferProtocol.getAmount(event);    // bigint | undefined
-TokenTransferProtocol.getSymbol(event);    // string | undefined
-TokenTransferProtocol.getRecipient(event); // string | undefined
-TokenTransferProtocol.getSender(event);    // string
+TokenTransferProtocol.getAmount(event);         // bigint | undefined
+TokenTransferProtocol.getSymbol(event);         // string | undefined
+TokenTransferProtocol.getRecipient(event);      // string | undefined
+TokenTransferProtocol.getSender(event);         // string
+TokenTransferProtocol.getReplyToEventId(event); // string | undefined (payment request correlation)
 ```
 
 ## Payment Request Format
@@ -350,7 +435,9 @@ const parsed = await PaymentRequestProtocol.parsePaymentRequest(event, keyManage
 
 - **Bech32** - Bech32 encoding/decoding (npub, nsec)
 - **SchnorrSigner** - BIP-340 Schnorr signatures
-- **NIP04** - NIP-04 encryption/decryption
+- **NIP04** - NIP-04 encryption/decryption (legacy)
+- **NIP44** - NIP-44 encryption/decryption (ChaCha20-Poly1305)
+- **NIP17** - NIP-17 private direct messages with gift-wrapping
 - **EventKinds** - Event kind constants
 - **NametagUtils** - Nametag normalization and hashing
 - **NametagBinding** - Nametag binding event creation
@@ -363,7 +450,11 @@ const parsed = await PaymentRequestProtocol.parsePaymentRequest(event, keyManage
 |------|------|-------------|
 | 0 | PROFILE | User profile metadata |
 | 1 | TEXT_NOTE | Short text note |
-| 4 | ENCRYPTED_DM | Encrypted direct message |
+| 4 | ENCRYPTED_DM | Encrypted direct message (NIP-04) |
+| 13 | SEAL | Encrypted seal for gift-wrapping (NIP-17) |
+| 14 | CHAT_MESSAGE | Private direct message rumor (NIP-17) |
+| 15 | READ_RECEIPT | Read receipt rumor (NIP-17) |
+| 1059 | GIFT_WRAP | Gift-wrapped message (NIP-17) |
 | 30078 | APP_DATA | Application-specific data (nametag bindings) |
 | 31111 | AGENT_PROFILE | Agent profile information |
 | 31112 | AGENT_LOCATION | Agent GPS location |
@@ -392,22 +483,34 @@ npm run lint
 
 ## E2E Testing with Relay
 
+### NIP-17 Private Messages
+
+```bash
+# Run NIP-17 E2E tests against real relay
+npm test tests/integration/nip17-relay.test.ts
+
+# Use a custom relay
+NOSTR_TEST_RELAY=wss://your-relay.com npm test tests/integration/nip17-relay.test.ts
+```
+
+### Payment Requests (Manual)
+
 To test payment requests against a real wallet:
 
 ```bash
 # Send a single payment request
-TARGET_NAMETAG=mp-6 npm test -- --testNamePattern="send single payment request"
+TARGET_NAMETAG=mp-9 npm test -- --testNamePattern="send single payment request"
 
 # Send multiple payment requests (for UI testing)
-TARGET_NAMETAG=mp-6 npm test -- --testNamePattern="send multiple payment requests"
+TARGET_NAMETAG=mp-9 npm test -- --testNamePattern="send multiple payment requests"
 
 # Full flow with token transfer verification (requires wallet interaction)
-TARGET_NAMETAG=mp-6 npm test -- --testNamePattern="full payment request flow"
+TARGET_NAMETAG=mp-9 npm test -- --testNamePattern="full payment request flow"
 ```
 
 Environment variables:
 - `TARGET_NAMETAG` - Nametag of the wallet to send requests to (required)
-- `NOSTR_RELAY` - Relay URL (default: `wss://nostr-relay.testnet.unicity.network`)
+- `NOSTR_TEST_RELAY` - Relay URL (default: `wss://nostr-relay.testnet.unicity.network`)
 - `AMOUNT` - Amount in smallest units (default: `1000000`)
 - `TIMEOUT` - Timeout in seconds for full flow test (default: `120`)