nostr-double-ratchet 0.0.96 → 0.0.97

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +52 -0
  2. package/package.json +9 -10
package/README.md CHANGED
@@ -37,6 +37,36 @@ If you are unsure, start with `NdrRuntime`. Drop down to `SessionManager` only w
37
37
  keep more app-owned runtime structure, and use plain `Session` only when a small 1:1-only surface
38
38
  is actually the goal.
39
39
 
40
+ ## Minimal Integration Contract
41
+
42
+ Reference web integrations:
43
+ [`iris-client`](https://git.iris.to/#/npub1xdhnr9mrv47kkrn95k6cwecearydeh8e895990n3acntwvmgk2dsdeeycm/iris-client),
44
+ [`iris-chat`](https://git.iris.to/#/npub1xdhnr9mrv47kkrn95k6cwecearydeh8e895990n3acntwvmgk2dsdeeycm/iris-chat).
45
+
46
+ They use one `NdrRuntime` singleton over app-owned transport and persistent storage.
47
+
48
+ ```typescript
49
+ type NostrSubscribe = (
50
+ filter: Filter,
51
+ onEvent: (event: VerifiedEvent) => void,
52
+ ) => () => void;
53
+
54
+ type NostrFetch = (filter: Filter) => Promise<VerifiedEvent[]>;
55
+
56
+ type NostrPublish = (
57
+ event: UnsignedEvent | VerifiedEvent,
58
+ ) => Promise<VerifiedEvent>;
59
+
60
+ interface StorageAdapter {
61
+ get<T = unknown>(key: string): Promise<T | undefined>;
62
+ put<T = unknown>(key: string, value: T): Promise<void>;
63
+ del(key: string): Promise<void>;
64
+ list(prefix?: string): Promise<string[]>;
65
+ }
66
+ ```
67
+
68
+ If you can provide those four pieces, start with `NdrRuntime`.
69
+
40
70
  ## Quick Start (`NdrRuntime`)
41
71
 
42
72
  ```typescript
@@ -77,6 +107,14 @@ logins that should participate in multi-device fanout, call
77
107
  `ensureCurrentDeviceRegistered(...)` or `registerCurrentDevice(...)` before treating private
78
108
  messaging as fully ready.
79
109
 
110
+ `setupUser(peerPubkey)` is optional prewarm, not a hard prerequisite. Web consumers call it before
111
+ opening a chat when they want subscriptions and bootstrap to start early, but `sendEvent(...)`
112
+ already calls it internally and `sendMessage(...)` queues delivery if sessions are not ready yet.
113
+
114
+ For groups, initialize the runtime/session path before `createGroup(...)` or `sendGroupEvent(...)`.
115
+ If you want metadata fanout immediately instead of waiting for queue flush, prewarm peers with
116
+ `setupUser(...)`.
117
+
80
118
  ### Runtime Group API
81
119
 
82
120
  If you want the high-level path, keep groups on `NdrRuntime` instead of building a parallel
@@ -94,6 +132,20 @@ group transport layer:
94
132
 
95
133
  `GroupManager` is still available directly when you want to own more of the app wiring yourself.
96
134
 
135
+ ## Reference Web Pattern
136
+
137
+ Reference web integrations do this:
138
+
139
+ 1. Create one long-lived `NdrRuntime` per active identity with persistent storage.
140
+ 2. Wrap `nostrSubscribe` with `DirectMessageSubscriptionTracker` +
141
+ `buildDirectMessageBackfillFilter(...)` so newly added direct-message authors trigger a short
142
+ relay backfill immediately.
143
+ 3. Call `initForOwner(ownerPubkey)`, then `ensureCurrentDeviceRegistered(ownerPubkey)` or
144
+ `registerCurrentDevice(...)` when owner-key logins should participate in multi-device fanout.
145
+ 4. Attach `onSessionEvent(...)` / `onGroupEvent(...)` once for app lifetime.
146
+ 5. Optionally call `setupUser(peerPubkey)` before opening a chat or creating a group to prewarm
147
+ subscriptions and bootstrap.
148
+
97
149
  ## Mid-Level Setup (`SessionGroupRuntime`)
98
150
 
99
151
  If your app already owns `SessionManager`, `SessionGroupRuntime` gives you the same group-focused
package/package.json CHANGED
@@ -1,8 +1,7 @@
1
1
  {
2
2
  "name": "nostr-double-ratchet",
3
- "version": "0.0.96",
3
+ "version": "0.0.97",
4
4
  "type": "module",
5
- "packageManager": "pnpm@9.15.0",
6
5
  "description": "Nostr double ratchet library",
7
6
  "main": "dist/nostr-double-ratchet.es.js",
8
7
  "module": "dist/nostr-double-ratchet.es.js",
@@ -14,13 +13,6 @@
14
13
  "default": "./dist/nostr-double-ratchet.es.js"
15
14
  }
16
15
  },
17
- "scripts": {
18
- "test": "vitest --exclude '**/*.integration.test.ts'",
19
- "test:once": "vitest run --exclude '**/*.integration.test.ts'",
20
- "test:integration": "DEBUG='ndk:*' vitest run tests/*.integration.test.ts",
21
- "build": "vite build && tsc",
22
- "lint": "eslint src --ext .ts --fix"
23
- },
24
16
  "repository": "https://files.iris.to/#/npub1xdhnr9mrv47kkrn95k6cwecearydeh8e895990n3acntwvmgk2dsdeeycm/nostr-double-ratchet",
25
17
  "author": "Martti Malmi",
26
18
  "license": "MIT",
@@ -47,5 +39,12 @@
47
39
  },
48
40
  "dependencies": {
49
41
  "nostr-tools": "^2.23.1"
42
+ },
43
+ "scripts": {
44
+ "test": "vitest --exclude '**/*.integration.test.ts'",
45
+ "test:once": "vitest run --exclude '**/*.integration.test.ts'",
46
+ "test:integration": "DEBUG='ndk:*' vitest run tests/*.integration.test.ts",
47
+ "build": "vite build && tsc",
48
+ "lint": "eslint src --ext .ts --fix"
50
49
  }
51
- }
50
+ }