@napplet/sdk 0.24.0 → 0.24.1

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 +55 -22
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -11,7 +11,7 @@
11
11
 
12
12
  ### How It Works
13
13
 
14
- 1. Import named exports from `@napplet/sdk` -- `relay`, `inc`, `storage`, `keys`, `ble`, `count`, `lists`
14
+ 1. Import named exports from `@napplet/sdk` -- `outbox`, `common`, `relay`, `inc`, `storage`, `keys`, `ble`, `count`, `lists`
15
15
  2. Each SDK method delegates to its injected `window.napplet.*` counterpart at call time
16
16
  3. If `window.napplet` or a requested domain is unavailable when a method is called, a descriptive error is thrown
17
17
 
@@ -24,22 +24,30 @@ npm install @napplet/sdk
24
24
  ## Quick Start
25
25
 
26
26
  ```ts
27
- import { relay, inc, storage, keys, media, notify, config, resource, ble, webrtc, link, count, lists, type NostrEvent } from '@napplet/sdk';
27
+ import { outbox, common, inc, storage, keys, media, notify, config, resource, ble, webrtc, link, count, lists } from '@napplet/sdk';
28
28
 
29
- // Subscribe to kind 1 notes
30
- const sub = relay.subscribe(
31
- { kinds: [1], limit: 20 },
32
- (event) => console.log('New note:', event.content),
33
- () => console.log('End of stored events'),
29
+ // Read kind 1 notes through outbox-aware routing
30
+ const { events } = await outbox.query(
31
+ [{ kinds: [1], limit: 20 }],
32
+ { timeoutMs: 3000 },
34
33
  );
34
+ for (const result of events) console.log('Note:', result.event.content);
35
35
 
36
- // Publish a signed note
37
- const signed = await relay.publish({
36
+ // Subscribe to live updates through the same outbox boundary
37
+ const sub = outbox.subscribe([{ kinds: [1], limit: 20 }], { timeoutMs: 3000 });
38
+ sub.on('event', (result) => console.log('New note:', result.event.content));
39
+
40
+ // Publish a signed note through the user's outbox/write relays
41
+ const published = await outbox.publish({
38
42
  kind: 1,
39
43
  content: 'Hello from my napplet!',
40
44
  tags: [],
41
45
  created_at: Math.floor(Date.now() / 1000),
42
46
  });
47
+ if (!published.ok || !published.event) throw new Error(published.error ?? 'publish failed');
48
+
49
+ // Common social actions keep consent, event construction, signing, and relay routing in the shell
50
+ await common.react(published.event.id, '+');
43
51
 
44
52
  // Inter-napplet messaging
45
53
  inc.emit('chat:message', [], JSON.stringify({ text: 'hi' }));
@@ -118,7 +126,10 @@ configSub.close();
118
126
 
119
127
  ### `relay`
120
128
 
121
- Relay operations through the shell's relay pool. Mirrors `window.napplet.relay`.
129
+ Low-level relay operations through the shell's relay pool. Mirrors `window.napplet.relay`.
130
+ Use this for explicit relay-local behavior such as group relays, diagnostics,
131
+ and protocol tooling. For normal social reads/publishes, prefer `outbox` or a
132
+ higher-level domain such as `common`, `lists`, `count`, or `dm`.
122
133
 
123
134
  | Method | Returns | Description |
124
135
  |--------|---------|-------------|
@@ -127,6 +138,26 @@ Relay operations through the shell's relay pool. Mirrors `window.napplet.relay`.
127
138
  | `publishEncrypted(template, recipient, encryption?)` | `Promise<NostrEvent>` | Send event template for encryption, signing, and broadcast |
128
139
  | `query(filters)` | `Promise<RelayEventResult[]>` | One-shot query: collect `RelayEventResult` records until EOSE, resolve |
129
140
 
141
+ ### `outbox`
142
+
143
+ Outbox-aware relay routing. Mirrors `window.napplet.outbox`. The napplet supplies
144
+ filters, event ids, templates, and intent; the shell owns NIP-65 relay discovery,
145
+ fallback, deduplication, signature validation, signing, and publish fanout.
146
+
147
+ | Method | Returns | Description |
148
+ |--------|---------|-------------|
149
+ | `getEvent(eventId, options?)` | `Promise<OutboxEventResult>` | Fetch one event through author/relay-aware routing |
150
+ | `query(filters, options?)` | `Promise<OutboxResult>` | One-shot outbox-aware query returning `RelayEventResult[]` |
151
+ | `subscribe(filters, options?)` | `OutboxSubscription` | Live outbox-aware stream with `on('event')` and `close()` |
152
+ | `publish(template, options?)` | `Promise<OutboxPublishResult>` | Shell-sign and fan out through the user's write relays and directed inbox relays |
153
+ | `resolveRelays(target)` | `Promise<OutboxRelayPlan>` | Diagnostic/advisory relay plan; prefer query/subscribe/publish for app behavior |
154
+
155
+ ### `common`
156
+
157
+ Common social actions. Mirrors `window.napplet.common`. Use it for NIP-19
158
+ helpers, profile lookup, follows, follow/unfollow, reactions, and reports so the
159
+ shell owns consent, event construction, signing, publishing, and lookup policy.
160
+
130
161
  ### `inc`
131
162
 
132
163
  Inter-napplet communication between napplets. Mirrors `window.napplet.inc`.
@@ -268,29 +299,30 @@ Keyboard forwarding and action keybindings. Mirrors `window.napplet.keys`.
268
299
 
269
300
  ### `identity`
270
301
 
271
- Read-only user identity queries (NAP-IDENTITY). The identity namespace
272
- is NOT exported as a top-level SDK object — use `window.napplet.identity.*` directly
273
- after runtime injection, or use the bare-name helpers below.
302
+ Read-only user identity queries (NAP-IDENTITY). Use the exported `identity`
303
+ object, `window.napplet.identity.*` directly after runtime injection, or the
304
+ bare-name helpers below.
274
305
 
275
306
  | Method | Returns | Description |
276
307
  |--------|---------|-------------|
277
- | `window.napplet.identity.getPublicKey()` | `Promise<string>` | Shell-user pubkey, or `""` when no user/signer is connected |
278
- | `window.napplet.identity.onChanged(handler)` | `{ close(): void }` | Listen for shell-pushed identity changes; handler receives a pubkey or `""` |
308
+ | `identity.getPublicKey()` | `Promise<string>` | Shell-user pubkey, or `""` when no user/signer is connected |
309
+ | `identity.onChanged(handler)` | `{ close(): void }` | Listen for shell-pushed identity changes; handler receives a pubkey or `""` |
279
310
 
280
311
  Bare helper aliases are also re-exported for consumers that prefer functional imports:
281
312
 
282
313
  ```ts
283
- import { identityGetPublicKey, identityOnChanged } from '@napplet/sdk';
314
+ import { identity, identityGetPublicKey, identityOnChanged } from '@napplet/sdk';
284
315
 
285
- const pubkey = await identityGetPublicKey();
316
+ const pubkey = await identity.getPublicKey();
286
317
  const sub = identityOnChanged((nextPubkey) => {
287
318
  console.log(nextPubkey || 'signed out');
288
319
  });
289
320
  ```
290
321
 
291
322
  NAP-IDENTITY is strictly read-only. Signing remains delegated through
292
- `relay.publish()`, encryption through `relay.publishEncrypted()`, and identity
293
- changes arrive through `identity.changed` rather than polling.
323
+ `outbox.publish()` or higher-level action domains (`common`, `lists`, `dm`).
324
+ Use `relay.publish()` only for explicit low-level relay escape hatches.
325
+ Identity changes arrive through `identity.changed` rather than polling.
294
326
 
295
327
  ### Runtime-Injected Domains
296
328
 
@@ -299,7 +331,8 @@ domains are present as properties; unavailable domains are absent. Gate optional
299
331
  behavior with property presence:
300
332
 
301
333
  ```ts
302
- if (window.napplet?.relay) { /* relay API is available */ }
334
+ if (window.napplet?.outbox) { /* outbox API is available */ }
335
+ if (window.napplet?.relay) { /* low-level relay API is available */ }
303
336
  if (window.napplet?.identity) { /* identity API is available */ }
304
337
  if (window.napplet?.inc) { /* inter-napplet channel API is available */ }
305
338
  ```
@@ -311,7 +344,7 @@ if (window.napplet?.inc) { /* inter-napplet channel API is available */ }
311
344
  ```ts
312
345
  import * as napplet from '@napplet/sdk';
313
346
 
314
- napplet.relay.subscribe({ kinds: [1] }, (e) => console.log(e));
347
+ const { events } = await napplet.outbox.query([{ kinds: [1], limit: 20 }]);
315
348
  napplet.storage.setItem('key', 'value');
316
349
  napplet.config.subscribe((v) => console.log(v));
317
350
  ```
@@ -348,7 +381,7 @@ import type {
348
381
  | `NostrEvent` | Standard Nostr event object |
349
382
  | `NostrFilter` | Relay subscription filter |
350
383
  | `Subscription` | Handle with `close()` method |
351
- | `EventTemplate` | Unsigned event for `relay.publish()` |
384
+ | `EventTemplate` | Unsigned event template for shell-mediated publish domains such as `outbox.publish()` |
352
385
  | `NappletMessage` | Base JSON envelope type for all protocol messages |
353
386
  | `NapDomain` | String literal union of NAP domain names |
354
387
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@napplet/sdk",
3
- "version": "0.24.0",
3
+ "version": "0.24.1",
4
4
  "description": "Typed named exports wrapping window.napplet for bundler-consuming napplet developers",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -21,7 +21,7 @@
21
21
  },
22
22
  "dependencies": {
23
23
  "@napplet/core": "0.27.0",
24
- "@napplet/nap": "0.27.0"
24
+ "@napplet/nap": "0.27.1"
25
25
  },
26
26
  "devDependencies": {
27
27
  "tsup": "^8.5.0",