@napplet/sdk 0.20.1 → 0.20.2
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 +33 -56
- package/dist/index.d.ts +1 -1
- package/dist/index.js +125 -115
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -6,26 +6,24 @@
|
|
|
6
6
|
|
|
7
7
|
### Prerequisites
|
|
8
8
|
|
|
9
|
-
-
|
|
9
|
+
- A NIP-5D runtime injects `window.napplet` before SDK methods are called
|
|
10
10
|
- A shell host running a napplet protocol shell implementation
|
|
11
11
|
|
|
12
12
|
### How It Works
|
|
13
13
|
|
|
14
|
-
1. Import `@napplet/
|
|
15
|
-
2.
|
|
16
|
-
3.
|
|
17
|
-
4. If `window.napplet` is not installed when a method is called, a descriptive error is thrown
|
|
14
|
+
1. Import named exports from `@napplet/sdk` -- `relay`, `inc`, `storage`, `keys`, `ble`, `lists`
|
|
15
|
+
2. Each SDK method delegates to its injected `window.napplet.*` counterpart at call time
|
|
16
|
+
3. If `window.napplet` or a requested domain is unavailable when a method is called, a descriptive error is thrown
|
|
18
17
|
|
|
19
18
|
### Installation
|
|
20
19
|
|
|
21
20
|
```bash
|
|
22
|
-
npm install @napplet/sdk
|
|
21
|
+
npm install @napplet/sdk
|
|
23
22
|
```
|
|
24
23
|
|
|
25
24
|
## Quick Start
|
|
26
25
|
|
|
27
26
|
```ts
|
|
28
|
-
import '@napplet/shim';
|
|
29
27
|
import { relay, inc, storage, keys, media, notify, config, resource, ble, webrtc, link, lists, type NostrEvent } from '@napplet/sdk';
|
|
30
28
|
|
|
31
29
|
// Subscribe to kind 1 notes
|
|
@@ -210,7 +208,6 @@ Per-napplet declarative configuration (NAP-CONFIG). Mirrors `window.napplet.conf
|
|
|
210
208
|
`json-schema-to-ts` is declared as an optional `peerDependency` of `@napplet/nap` (scoped to the `@napplet/nap/config` domain's `FromSchema` typing). Install it in your napplet to get `FromSchema<typeof schema>` typing for your `config.subscribe` callback -- the `values` parameter is inferred directly from your schema (enums, required fields, defaults all flow through). Authors who skip `json-schema-to-ts` pay no install cost and `config.subscribe` still works with the default `Record<string, unknown>` typing.
|
|
211
209
|
|
|
212
210
|
```ts
|
|
213
|
-
import '@napplet/shim';
|
|
214
211
|
import { config } from '@napplet/sdk';
|
|
215
212
|
import type { FromSchema } from 'json-schema-to-ts';
|
|
216
213
|
|
|
@@ -271,7 +268,7 @@ Keyboard forwarding and action keybindings. Mirrors `window.napplet.keys`.
|
|
|
271
268
|
|
|
272
269
|
Read-only user identity queries (NAP-IDENTITY). The identity namespace
|
|
273
270
|
is NOT exported as a top-level SDK object — use `window.napplet.identity.*` directly
|
|
274
|
-
after
|
|
271
|
+
after runtime injection, or use the bare-name helpers below.
|
|
275
272
|
|
|
276
273
|
| Method | Returns | Description |
|
|
277
274
|
|--------|---------|-------------|
|
|
@@ -293,30 +290,16 @@ NAP-IDENTITY is strictly read-only. Signing remains delegated through
|
|
|
293
290
|
`relay.publish()`, encryption through `relay.publishEncrypted()`, and identity
|
|
294
291
|
changes arrive through `identity.changed` rather than polling.
|
|
295
292
|
|
|
296
|
-
###
|
|
293
|
+
### Runtime-Injected Domains
|
|
297
294
|
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
| Method | Returns | Description |
|
|
303
|
-
|--------|---------|-------------|
|
|
304
|
-
| `supports(capability, protocol?)` | `boolean` | Check shell support for a NAP (`nap:relay`), permission (`perm:popups`), or numbered NAP-NN protocol over an interface (`inc`, `NAP-01`). Bare NAP names are also accepted (`relay`). |
|
|
305
|
-
|
|
306
|
-
**Example:**
|
|
295
|
+
NIP-5D runtimes inject `window.napplet` before napplet code runs. Available NAP
|
|
296
|
+
domains are present as properties; unavailable domains are absent. Gate optional
|
|
297
|
+
behavior with property presence:
|
|
307
298
|
|
|
308
299
|
```ts
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
if (window.napplet.shell.supports('relay')) { /* ... */ }
|
|
313
|
-
if (window.napplet.shell.supports('nap:identity')) { /* ... */ }
|
|
314
|
-
|
|
315
|
-
// Permissions
|
|
316
|
-
if (window.napplet.shell.supports('perm:popups')) { /* ... */ }
|
|
317
|
-
|
|
318
|
-
// Numbered NAP-NN message protocols
|
|
319
|
-
if (window.napplet.shell.supports('inc', 'NAP-01')) { /* ... */ }
|
|
300
|
+
if (window.napplet?.relay) { /* relay API is available */ }
|
|
301
|
+
if (window.napplet?.identity) { /* identity API is available */ }
|
|
302
|
+
if (window.napplet?.inc) { /* inter-napplet channel API is available */ }
|
|
320
303
|
```
|
|
321
304
|
|
|
322
305
|
### Namespace Import
|
|
@@ -344,9 +327,6 @@ import type {
|
|
|
344
327
|
EventTemplate,
|
|
345
328
|
NappletMessage,
|
|
346
329
|
NapDomain,
|
|
347
|
-
NamespacedCapability,
|
|
348
|
-
NapProtocolId,
|
|
349
|
-
ShellSupports,
|
|
350
330
|
// NAP message types (re-exported from NAP packages)
|
|
351
331
|
RelayNapMessage,
|
|
352
332
|
IdentityNapMessage,
|
|
@@ -369,9 +349,6 @@ import type {
|
|
|
369
349
|
| `EventTemplate` | Unsigned event for `relay.publish()` |
|
|
370
350
|
| `NappletMessage` | Base JSON envelope type for all protocol messages |
|
|
371
351
|
| `NapDomain` | String literal union of NAP domain names |
|
|
372
|
-
| `NamespacedCapability` | Union of `NapDomain \| nap:* \| perm:*` for `supports()` |
|
|
373
|
-
| `NapProtocolId` | Numbered NAP protocol id such as `NAP-01` for the optional second `supports()` argument |
|
|
374
|
-
| `ShellSupports` | Interface for the shell capability query API |
|
|
375
352
|
|
|
376
353
|
### NAP Message Types
|
|
377
354
|
|
|
@@ -406,61 +383,61 @@ import { RELAY_DOMAIN, IDENTITY_DOMAIN, STORAGE_DOMAIN, INC_DOMAIN, THEME_DOMAIN
|
|
|
406
383
|
// Values: 'relay', 'identity', 'storage', 'inc', 'theme', 'keys', 'media', 'notify', 'config', 'resource', 'cvm', 'outbox', 'upload', 'intent', 'ble', 'webrtc', 'link', 'lists', 'common', 'serial'
|
|
407
384
|
```
|
|
408
385
|
|
|
409
|
-
These constants are re-exported from the individual domain packages. Use
|
|
410
|
-
|
|
386
|
+
These constants are re-exported from the individual domain packages. Use
|
|
387
|
+
property presence for type-safe conditional logic:
|
|
411
388
|
|
|
412
389
|
```ts
|
|
413
|
-
if (window.napplet
|
|
390
|
+
if (window.napplet?.relay) {
|
|
414
391
|
// relay operations are available
|
|
415
392
|
}
|
|
416
393
|
|
|
417
|
-
if (window.napplet
|
|
394
|
+
if (window.napplet?.identity) {
|
|
418
395
|
// identity queries are available
|
|
419
396
|
}
|
|
420
397
|
|
|
421
|
-
if (window.napplet
|
|
398
|
+
if (window.napplet?.config) {
|
|
422
399
|
// NAP-CONFIG is available -- schema registration and subscribe()
|
|
423
400
|
}
|
|
424
401
|
|
|
425
|
-
if (window.napplet
|
|
426
|
-
// resource.bytes(url) is available
|
|
427
|
-
if (window.napplet.shell.supports('resource:scheme:blossom')) { /* ... */ }
|
|
402
|
+
if (window.napplet?.resource) {
|
|
403
|
+
// resource.bytes(url) is available.
|
|
428
404
|
}
|
|
429
405
|
```
|
|
430
406
|
|
|
431
407
|
## Runtime Guard
|
|
432
408
|
|
|
433
|
-
If `window.napplet` is
|
|
409
|
+
If `window.napplet` or a requested domain is unavailable when an SDK method is
|
|
410
|
+
called, a clear error is thrown:
|
|
434
411
|
|
|
435
412
|
```
|
|
436
|
-
Error: window.napplet
|
|
413
|
+
Error: window.napplet.relay is unavailable -- runtime did not inject this domain
|
|
437
414
|
```
|
|
438
415
|
|
|
439
|
-
This protects
|
|
416
|
+
This protects napplets from assuming optional domains are always present.
|
|
440
417
|
|
|
441
418
|
## SDK vs Shim
|
|
442
419
|
|
|
443
420
|
| | `@napplet/sdk` | `@napplet/shim` |
|
|
444
421
|
|---|---|---|
|
|
445
|
-
| **Import style** | `import { relay } from '@napplet/sdk'` | `import '@napplet/shim'`
|
|
446
|
-
| **What it does** | Named exports wrapping
|
|
422
|
+
| **Import style** | `import { relay } from '@napplet/sdk'` | `import { installNappletGlobal } from '@napplet/shim'` |
|
|
423
|
+
| **What it does** | Named exports wrapping injected domains | Runtime-side global installer |
|
|
447
424
|
| **Dependencies** | `@napplet/core` (types only) | None (types from `@napplet/core`) |
|
|
448
|
-
| **Side effects** | None | Yes -- installs globals
|
|
449
|
-
| **Required** | Optional convenience |
|
|
425
|
+
| **Side effects** | None | Yes -- installs globals on a target window |
|
|
426
|
+
| **Required** | Optional convenience for napplets | Runtime implementation detail |
|
|
450
427
|
|
|
451
|
-
**Typical usage:**
|
|
428
|
+
**Typical napplet usage:** import the SDK for typed API access:
|
|
452
429
|
|
|
453
430
|
```ts
|
|
454
|
-
import '@napplet/
|
|
455
|
-
import { relay, inc, storage, keys, media, notify } from '@napplet/sdk'; // optional: typed API
|
|
431
|
+
import { relay, inc, storage, keys, media, notify } from '@napplet/sdk';
|
|
456
432
|
```
|
|
457
433
|
|
|
458
|
-
If you are writing a vanilla napplet with no build step, use
|
|
434
|
+
If you are writing a vanilla napplet with no build step, use the injected
|
|
435
|
+
`window.napplet.*` namespace directly -- the SDK is not required.
|
|
459
436
|
|
|
460
437
|
## Protocol Reference
|
|
461
438
|
|
|
462
439
|
- [NIP-5D](https://github.com/nostr-protocol/nips/pull/2303) -- Napplet-shell protocol specification
|
|
463
|
-
- [@napplet/shim](../shim/) --
|
|
440
|
+
- [@napplet/shim](../shim/) -- Runtime-side injected global installer
|
|
464
441
|
- [@napplet/core](../core/) -- Shared protocol types
|
|
465
442
|
|
|
466
443
|
## License
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { NostrEvent, Subscription, NostrFilter, EventTemplate, ResourceBytesItem, CvmDiscoverQuery, CvmServer, CvmServerRef, McpMessage, CvmRequestOptions, McpTool, McpToolResult, McpResource, McpResourceContent, IntentRequest, IntentResult, IntentAvailability, OutboxQueryOptions, OutboxResult, OutboxSubscribeOptions, OutboxSubscription, OutboxPublishOptions, OutboxPublishResult, OutboxTarget, OutboxRelayPlan, UploadRequest, UploadResult, UploadStatus, WebrtcOpenRequest, WebrtcOpenResult, WebrtcEvent, BleOpenRequest, BleOpenResult, BleService, BleAttribute, BleWriteOptions, BleEvent, CommonNip19EncodeInput, CommonNip19EncodeResult, CommonNip19DecodeResult, CommonProfileTarget, CommonProfileResult, CommonFollowsResult, CommonActionResult, CommonReaction, CommonReportTarget, CommonReportReason, DmStatus, DmConversationQuery, DmConversationPage, DmMessageQuery, DmMessagePage, DmSendRequest, DmSendResult, DmSubscribeRequest, DmSubscription, DmOk, DmMessage, LinkOpenOptions, LinkOpenResult, ListSupport, ListRef, ListItem, ListOptions, ListMutationResult, SerialOpenRequest, SerialOpenResult, SerialEvent } from '@napplet/core';
|
|
2
|
-
export { EventTemplate, NAP_DOMAINS,
|
|
2
|
+
export { EventTemplate, NAP_DOMAINS, NapDomain, NappletMessage, NostrEvent, NostrFilter, Subscription } from '@napplet/core';
|
|
3
3
|
import { MediaSessionCreate, MediaSessionResult, MediaMetadata, MediaState, MediaAction } from '@napplet/nap/media';
|
|
4
4
|
export { DOMAIN as MEDIA_DOMAIN, MediaAction, MediaArtwork, MediaCapabilitiesMessage, MediaCommandMessage, MediaControlsMessage, MediaMessage, MediaMetadata, MediaNapMessage, MediaPlaybackOwner, MediaRequestMessage, MediaResultMessage, MediaSessionCreate, MediaSessionCreateMessage, MediaSessionCreateResultMessage, MediaSessionDestroyMessage, MediaSessionResult, MediaSessionUpdateMessage, MediaSourceRef, MediaState, MediaStateMessage, installMediaShim, mediaCreateSession, mediaDestroySession, mediaOnCapabilities, mediaOnCommand, mediaOnControls, mediaOnState, mediaReportCapabilities, mediaReportState, mediaSendCommand, mediaUpdateSession } from '@napplet/nap/media';
|
|
5
5
|
export { DOMAIN as RELAY_DOMAIN, RelayCloseMessage, RelayClosedMessage, RelayEoseMessage, RelayEventMessage, RelayInboundMessage, RelayMessage, RelayNapMessage, RelayOutboundMessage, RelayPublishEncryptedMessage, RelayPublishEncryptedResultMessage, RelayPublishMessage, RelayPublishResultMessage, RelayQueryMessage, RelayQueryResultMessage, RelaySubscribeMessage, installRelayShim, relayPublish, relayPublishEncrypted, relayQuery, relaySubscribe } from '@napplet/nap/relay';
|