@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.
- package/README.md +55 -22
- 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 {
|
|
27
|
+
import { outbox, common, inc, storage, keys, media, notify, config, resource, ble, webrtc, link, count, lists } from '@napplet/sdk';
|
|
28
28
|
|
|
29
|
-
//
|
|
30
|
-
const
|
|
31
|
-
{ kinds: [1], limit: 20 },
|
|
32
|
-
|
|
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
|
-
//
|
|
37
|
-
const
|
|
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
|
-
|
|
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).
|
|
272
|
-
|
|
273
|
-
|
|
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
|
-
| `
|
|
278
|
-
| `
|
|
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
|
|
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
|
-
`
|
|
293
|
-
|
|
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?.
|
|
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.
|
|
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 `
|
|
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.
|
|
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.
|
|
24
|
+
"@napplet/nap": "0.27.1"
|
|
25
25
|
},
|
|
26
26
|
"devDependencies": {
|
|
27
27
|
"tsup": "^8.5.0",
|