@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 CHANGED
@@ -6,26 +6,24 @@
6
6
 
7
7
  ### Prerequisites
8
8
 
9
- - `@napplet/shim` must be imported (side-effect) to install `window.napplet` before SDK methods are called
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/shim` in your entry point to install the `window.napplet` global
15
- 2. Import named exports from `@napplet/sdk` -- `relay`, `inc`, `storage`, `keys`, `ble`, `lists`
16
- 3. Each SDK method delegates to its `window.napplet.*` counterpart at call time
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 @napplet/shim
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 importing `@napplet/shim`, or use the bare-name helpers below.
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
- ### `shell`
293
+ ### Runtime-Injected Domains
297
294
 
298
- Namespaced capability query. Access via `window.napplet.shell.supports()` after importing `@napplet/shim`.
299
-
300
- > Note: The SDK does not export a top-level `shell` object. Use `window.napplet.shell.supports()` directly.
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
- import '@napplet/shim';
310
-
311
- // NAP domains (bare shorthand or nap: prefix)
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 them with the shell capability query
410
- API for type-safe conditional logic:
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.shell.supports('nap:relay')) {
390
+ if (window.napplet?.relay) {
414
391
  // relay operations are available
415
392
  }
416
393
 
417
- if (window.napplet.shell.supports('nap:identity')) {
394
+ if (window.napplet?.identity) {
418
395
  // identity queries are available
419
396
  }
420
397
 
421
- if (window.napplet.shell.supports('nap:config')) {
398
+ if (window.napplet?.config) {
422
399
  // NAP-CONFIG is available -- schema registration and subscribe()
423
400
  }
424
401
 
425
- if (window.napplet.shell.supports('nap:resource')) {
426
- // resource.bytes(url) is available; check per-scheme too:
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 not installed when an SDK method is called, a clear error is thrown:
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 not installed -- import @napplet/shim first
413
+ Error: window.napplet.relay is unavailable -- runtime did not inject this domain
437
414
  ```
438
415
 
439
- This protects against importing `@napplet/sdk` without the side-effect shim import.
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'` (side-effect) |
446
- | **What it does** | Named exports wrapping `window.napplet` | Installs `window.napplet` + shell registration |
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, registers with shell |
449
- | **Required** | Optional convenience | Required in every napplet |
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:** Import both -- shim for runtime, SDK for developer API:
428
+ **Typical napplet usage:** import the SDK for typed API access:
452
429
 
453
430
  ```ts
454
- import '@napplet/shim'; // required: installs window.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 `window.napplet.*` directly after importing the shim -- the SDK is not required.
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/) -- Window installer package
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, NamespacedCapability, NapDomain, NapProtocolId, NappletMessage, NostrEvent, NostrFilter, ProtocolId, ShellSupports, Subscription } from '@napplet/core';
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';