@kehto/services 0.16.1 → 0.17.0
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 +129 -33
- package/dist/cvm-nostr-transport.d.ts +2 -0
- package/dist/cvm-nostr-transport.js.map +1 -1
- package/dist/index.d.ts +249 -376
- package/dist/index.js +1041 -580
- package/dist/index.js.map +1 -1
- package/package.json +7 -8
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { ServiceHandler, Signer, RelayEventResult } from '@kehto/runtime';
|
|
2
2
|
import { IdentityGetProfileMessage, IdentityGetProfileResultMessage, IdentityGetFollowsMessage, IdentityGetFollowsResultMessage, IdentityGetListMessage, IdentityGetListResultMessage, IdentityGetZapsMessage, IdentityGetZapsResultMessage, IdentityGetMutesMessage, IdentityGetMutesResultMessage, IdentityGetBlockedMessage, IdentityGetBlockedResultMessage, IdentityGetBadgesMessage, IdentityGetBadgesResultMessage } from '@napplet/nap/identity/types';
|
|
3
|
-
import { NostrFilter, NostrEvent, EventTemplate, LinkOpenOptions, LinkOpenResult, ListSupport, ListRef, ListItem, ListOptions, ListMutationResult, SerialOpenRequest, SerialOpenResult, BleEvent, BleOpenRequest, BleOpenResult, BleService, BleAttribute, BleWriteOptions, WebrtcEvent, WebrtcOpenRequest, WebrtcOpenResult, CommonProfileTarget, CommonProfileResult, CommonFollowsResult, CommonActionResult, CommonReaction, CommonReportTarget, CommonReportReason } from '@napplet/core';
|
|
3
|
+
import { NostrFilter, NostrEvent, EventTemplate, IntentRequest, IntentRejectedResult, IntentAcceptedResult, IntentAvailability, IntentContract, IntentDelivery, IntentBehavior, IntentCandidate, LinkOpenOptions, LinkOpenResult, ListSupport, ListRef, ListItem, ListOptions, ListMutationResult, SerialOpenRequest, SerialOpenResult, BleEvent, BleOpenRequest, BleOpenResult, BleService, BleAttribute, BleWriteOptions, WebrtcEvent, WebrtcOpenRequest, WebrtcOpenResult, CommonProfileTarget, CommonProfileResult, CommonFollowsResult, CommonActionResult, CommonReaction, CommonReportTarget, CommonReportReason } from '@napplet/core';
|
|
4
|
+
export { IntentAcceptedResult, IntentAvailability, IntentBehavior, IntentCandidate, IntentContract, IntentDelivery, IntentHandlerPreference, IntentInvokeOptions, IntentRejectedResult, IntentRequest, IntentResult } from '@napplet/core';
|
|
4
5
|
import { MediaMetadata, MediaAction } from '@napplet/nap/media/types';
|
|
5
6
|
export { MediaAction } from '@napplet/nap/media/types';
|
|
6
7
|
import { NotifySendMessage } from '@napplet/nap/notify/types';
|
|
@@ -14,46 +15,6 @@ export { a as CvmCloseMessage, b as CvmCloseResultMessage, c as CvmDiscoverMessa
|
|
|
14
15
|
* These types describe the internal state that services manage and expose
|
|
15
16
|
* to the shell host via callbacks. They are NOT NIP-01 wire types.
|
|
16
17
|
*/
|
|
17
|
-
/**
|
|
18
|
-
* An active audio source registered by a napplet.
|
|
19
|
-
*
|
|
20
|
-
* @example
|
|
21
|
-
* ```ts
|
|
22
|
-
* const source: AudioSource = {
|
|
23
|
-
* windowId: 'win-1',
|
|
24
|
-
* nappletClass: 'music-player',
|
|
25
|
-
* title: 'Now Playing',
|
|
26
|
-
* muted: false,
|
|
27
|
-
* };
|
|
28
|
-
* ```
|
|
29
|
-
*/
|
|
30
|
-
interface AudioSource {
|
|
31
|
-
/** The napplet window that registered this audio source. */
|
|
32
|
-
windowId: string;
|
|
33
|
-
/** The napplet class/type (e.g., 'music-player'). */
|
|
34
|
-
nappletClass: string;
|
|
35
|
-
/** Human-readable title for the audio source. */
|
|
36
|
-
title: string;
|
|
37
|
-
/** Whether this source is currently muted. */
|
|
38
|
-
muted: boolean;
|
|
39
|
-
}
|
|
40
|
-
/**
|
|
41
|
-
* Options for creating an audio service via createAudioService().
|
|
42
|
-
*
|
|
43
|
-
* @example
|
|
44
|
-
* ```ts
|
|
45
|
-
* const audioService = createAudioService({
|
|
46
|
-
* onChange: (sources) => console.log('Audio sources changed:', sources.size),
|
|
47
|
-
* });
|
|
48
|
-
* ```
|
|
49
|
-
*/
|
|
50
|
-
interface AudioServiceOptions {
|
|
51
|
-
/**
|
|
52
|
-
* Called when the audio source registry changes (register, unregister,
|
|
53
|
-
* mute, state update). The shell host uses this to update UI.
|
|
54
|
-
*/
|
|
55
|
-
onChange?: (sources: ReadonlyMap<string, AudioSource>) => void;
|
|
56
|
-
}
|
|
57
18
|
/**
|
|
58
19
|
* A notification created by a napplet.
|
|
59
20
|
*
|
|
@@ -107,49 +68,13 @@ interface NotificationServiceOptions {
|
|
|
107
68
|
maxPerWindow?: number;
|
|
108
69
|
}
|
|
109
70
|
|
|
110
|
-
/**
|
|
111
|
-
* audio-service.ts — Audio source registry as a ServiceHandler.
|
|
112
|
-
*
|
|
113
|
-
* Tracks which napplet windows are producing audio. Shell hosts wire this
|
|
114
|
-
* into the runtime via registerService('audio', createAudioService(opts)).
|
|
115
|
-
* Browser-agnostic — no DOM, no window, no postMessage.
|
|
116
|
-
*/
|
|
117
|
-
|
|
118
|
-
/**
|
|
119
|
-
* Create an audio service handler.
|
|
120
|
-
*
|
|
121
|
-
* The audio service is a state registry that tracks active audio sources
|
|
122
|
-
* per napplet window. Napplets announce audio state via `audio:*` topic
|
|
123
|
-
* events; the service tracks sources and can relay mute commands back.
|
|
124
|
-
*
|
|
125
|
-
* @param options - Optional configuration (onChange callback for UI updates)
|
|
126
|
-
* @returns A ServiceHandler to register with the runtime
|
|
127
|
-
*
|
|
128
|
-
* @example
|
|
129
|
-
* ```ts
|
|
130
|
-
* import { createAudioService } from '@kehto/services';
|
|
131
|
-
*
|
|
132
|
-
* const audio = createAudioService({
|
|
133
|
-
* onChange: (sources) => {
|
|
134
|
-
* // Update UI with current audio sources
|
|
135
|
-
* for (const [windowId, source] of sources) {
|
|
136
|
-
* console.log(`${source.title} (${source.muted ? 'muted' : 'playing'})`);
|
|
137
|
-
* }
|
|
138
|
-
* },
|
|
139
|
-
* });
|
|
140
|
-
*
|
|
141
|
-
* runtime.registerService('audio', audio);
|
|
142
|
-
* ```
|
|
143
|
-
*/
|
|
144
|
-
declare function createAudioService(options?: AudioServiceOptions): ServiceHandler;
|
|
145
|
-
|
|
146
71
|
/**
|
|
147
72
|
* Create a notification service handler.
|
|
148
73
|
*
|
|
149
74
|
* The notification service is a state registry that tracks notifications
|
|
150
|
-
* per napplet window.
|
|
151
|
-
*
|
|
152
|
-
*
|
|
75
|
+
* per napplet window. It accepts direct `notify.*` service envelopes; INC
|
|
76
|
+
* topics are opaque application data and never select a host service. The
|
|
77
|
+
* shell host controls presentation through the onChange callback.
|
|
153
78
|
*
|
|
154
79
|
* @param options - Optional configuration (onChange callback, maxPerWindow limit)
|
|
155
80
|
* @returns A ServiceHandler to register with the runtime
|
|
@@ -166,7 +91,7 @@ declare function createAudioService(options?: AudioServiceOptions): ServiceHandl
|
|
|
166
91
|
* maxPerWindow: 50,
|
|
167
92
|
* });
|
|
168
93
|
*
|
|
169
|
-
* runtime.registerService('
|
|
94
|
+
* runtime.registerService('notify', notifications);
|
|
170
95
|
* ```
|
|
171
96
|
*/
|
|
172
97
|
declare function createNotificationService(options?: NotificationServiceOptions): ServiceHandler;
|
|
@@ -346,8 +271,9 @@ interface RelayPoolServiceOptions {
|
|
|
346
271
|
* Publish an event to relays.
|
|
347
272
|
*
|
|
348
273
|
* @param event - The event to publish
|
|
274
|
+
* @returns Nothing, or a promise that settles when the publish request completes
|
|
349
275
|
*/
|
|
350
|
-
publish(event: NostrEvent): void
|
|
276
|
+
publish(event: NostrEvent): void | Promise<void>;
|
|
351
277
|
/**
|
|
352
278
|
* Select relay URLs appropriate for the given filters.
|
|
353
279
|
*
|
|
@@ -577,29 +503,30 @@ declare function createCoordinatedRelay(options: CoordinatedRelayOptions): Servi
|
|
|
577
503
|
*
|
|
578
504
|
* Handles the 3 napplet -> shell request types from @napplet/nap/keys:
|
|
579
505
|
* - keys.forward -> invokes options.onForward (hotkey passthrough, fire-and-forget)
|
|
580
|
-
* - keys.registerAction -> parses action.defaultKey into a chord
|
|
581
|
-
*
|
|
582
|
-
* tracks windowId ownership so onWindowDestroyed
|
|
583
|
-
* unsubscribe,
|
|
584
|
-
*
|
|
506
|
+
* - keys.registerAction -> parses action.defaultKey into a normalized chord binding,
|
|
507
|
+
* stores bound subscriptions in an in-memory registry keyed
|
|
508
|
+
* by actionId, tracks windowId ownership so onWindowDestroyed
|
|
509
|
+
* can auto-unsubscribe, echoes { actionId, binding } as .result
|
|
510
|
+
* when a binding is assigned, and pushes the window's complete
|
|
511
|
+
* keys.bindings list
|
|
512
|
+
* - keys.unregisterAction -> removes the subscription and pushes the window's
|
|
513
|
+
* updated keys.bindings list
|
|
585
514
|
*
|
|
586
515
|
* Real listener: on service construction the handler attaches a single
|
|
587
516
|
* `keydown` listener to `options.listenerTarget` (default: `document`). Each
|
|
588
517
|
* keydown is matched against the chord-subscription registry; matches invoke
|
|
589
|
-
* `options.onForward` with the DOM-shape payload
|
|
518
|
+
* `options.onForward` with the DOM-shape payload and push a canonical
|
|
590
519
|
* `keys.action` envelope back to the owning napplet via the per-window `send`
|
|
591
520
|
* callback captured at `keys.registerAction` time. Subscriptions persist
|
|
592
521
|
* across messages; `onWindowDestroyed(windowId)` drops all subscriptions owned
|
|
593
522
|
* by the destroyed window as well as its cached `send` handle.
|
|
594
523
|
*
|
|
595
|
-
* On each document keydown matching a registered action, the service
|
|
596
|
-
*
|
|
597
|
-
*
|
|
598
|
-
*
|
|
599
|
-
*
|
|
600
|
-
*
|
|
601
|
-
* base shape unchanged, downstream SDKs that only read `{ type, actionId }`
|
|
602
|
-
* ignore `chord` silently).
|
|
524
|
+
* On each document keydown matching a registered action, the service emits a
|
|
525
|
+
* `keys.action` envelope to the action's owning napplet via the per-window
|
|
526
|
+
* `send` callback — this is the canonical @napplet/nap/keys surface the SDK's
|
|
527
|
+
* `keys.onAction(...)` helper consumes. Forwarded keydowns do not trigger
|
|
528
|
+
* `keys.action`; the active napplet suppresses bound keys locally from the
|
|
529
|
+
* `keys.bindings` list before forwarding.
|
|
603
530
|
*
|
|
604
531
|
* Field-name translation: @napplet/nap/keys uses the compact
|
|
605
532
|
* { ctrl, alt, shift, meta } form on the wire; the shell's HotkeyHooks
|
|
@@ -607,9 +534,9 @@ declare function createCoordinatedRelay(options: CoordinatedRelayOptions): Servi
|
|
|
607
534
|
* { ctrlKey, altKey, shiftKey, metaKey } form. This service performs the
|
|
608
535
|
* translation so callers of `onForward` see the DOM shape.
|
|
609
536
|
*
|
|
610
|
-
* Shell -> napplet push envelopes `keys.bindings`
|
|
611
|
-
*
|
|
612
|
-
*
|
|
537
|
+
* Shell -> napplet push envelopes `keys.bindings` are emitted here whenever
|
|
538
|
+
* the registered bindings for a window change. The injected shim consumes
|
|
539
|
+
* that complete list to suppress locally-bound keydowns before forwarding.
|
|
613
540
|
*/
|
|
614
541
|
|
|
615
542
|
/**
|
|
@@ -708,8 +635,8 @@ interface HostKeysBridge {
|
|
|
708
635
|
*/
|
|
709
636
|
interface KeysServiceOptions {
|
|
710
637
|
/**
|
|
711
|
-
* Called on `keys.forward` (napplet-forwarded chord)
|
|
712
|
-
*
|
|
638
|
+
* Called on `keys.forward` (napplet-forwarded chord) and on document keydown
|
|
639
|
+
* handled by the reference listener. Receives the DOM-style field names
|
|
713
640
|
* (ctrlKey/altKey/shiftKey/metaKey) to match the shell's HotkeyHooks
|
|
714
641
|
* contract. The service translates from the wire shape
|
|
715
642
|
* ({ ctrl, alt, shift, meta }) before invoking this callback.
|
|
@@ -727,7 +654,7 @@ interface KeysServiceOptions {
|
|
|
727
654
|
* global `document` when running in a DOM environment, else an isolated
|
|
728
655
|
* `new EventTarget()` (SSR / Node-test safe). Passing a fresh
|
|
729
656
|
* `new EventTarget()` is useful for unit tests. Mirrors the pattern used
|
|
730
|
-
* by
|
|
657
|
+
* by the shell and service test harnesses.
|
|
731
658
|
*
|
|
732
659
|
* Ignored when `hostBridge` is provided — the bridge owns subscription
|
|
733
660
|
* lifecycle and no document listener is attached.
|
|
@@ -743,13 +670,9 @@ interface KeysServiceOptions {
|
|
|
743
670
|
hostBridge?: HostKeysBridge;
|
|
744
671
|
/**
|
|
745
672
|
* Optional set of shell-reserved chords. Strings in the `@napplet/nap/keys`
|
|
746
|
-
* wire format (e.g. `'Ctrl+Shift+K'`, `'Cmd+P'`).
|
|
747
|
-
*
|
|
748
|
-
*
|
|
749
|
-
* (or the `hostBridge`-registered handler) but suppresses the
|
|
750
|
-
* `keys.action` push to any napplet that registered the same chord via
|
|
751
|
-
* `keys.registerAction`. Precedence: reserved > registered. The shell
|
|
752
|
-
* WANTS the forward — that is why it reserved the chord.
|
|
673
|
+
* wire format (e.g. `'Ctrl+Shift+K'`, `'Cmd+P'`). Reserved chords are not
|
|
674
|
+
* assigned as napplet action bindings; document keydowns that match them
|
|
675
|
+
* invoke `onForward` but do not push `keys.action`.
|
|
753
676
|
*
|
|
754
677
|
* Normalized once at service construction via the same chord parser used
|
|
755
678
|
* for `action.defaultKey` — `'Ctrl+K'` / `'Control+k'` / `'ctrl+K'` all
|
|
@@ -771,7 +694,7 @@ interface KeysServiceOptions {
|
|
|
771
694
|
*
|
|
772
695
|
* Attaches a single `keydown` listener to `options.listenerTarget`
|
|
773
696
|
* (default `document`). Matching chord subscriptions invoke `options.onForward`
|
|
774
|
-
* with a DOM-shape payload
|
|
697
|
+
* with a DOM-shape payload and push a `keys.action` envelope back to the
|
|
775
698
|
* owning napplet via the per-window `send` callback captured at
|
|
776
699
|
* `keys.registerAction` time. Returns a `ServiceHandler` augmented with a
|
|
777
700
|
* `destroy()` method that detaches the listener and clears all registries.
|
|
@@ -895,11 +818,8 @@ declare function createBrowserMediaBridge(opts?: {
|
|
|
895
818
|
* via bridge.setMetadata / bridge.setPlaybackState. When the active session is
|
|
896
819
|
* destroyed, the next-most-recently-touched session is promoted automatically.
|
|
897
820
|
*
|
|
898
|
-
*
|
|
899
|
-
*
|
|
900
|
-
* over inc.emit). media-service is the canonical @napplet/nap/media NIP-5D
|
|
901
|
-
* path and they coexist — audio-service continues to track audio sources for
|
|
902
|
-
* shell UI, while media-service handles the NAP protocol envelope surface.
|
|
821
|
+
* This is the canonical @napplet/nap/media NIP-5D path. It handles media
|
|
822
|
+
* protocol envelopes directly and does not depend on convention-topic routing.
|
|
903
823
|
*
|
|
904
824
|
* Shell -> Napplet push types (media.command) are emitted here when
|
|
905
825
|
* bridge.onAction callbacks fire — this is the canonical Phase 27 real backend.
|
|
@@ -1107,14 +1027,12 @@ declare function createMediaService(options?: MediaServiceOptions): ServiceHandl
|
|
|
1107
1027
|
* Host apps wire a real backend via
|
|
1108
1028
|
* `runtime.registerService('notify', realHandler)`.
|
|
1109
1029
|
*
|
|
1110
|
-
*
|
|
1111
|
-
*
|
|
1112
|
-
*
|
|
1113
|
-
* under `notifications:*`). `notify-service.ts` is the canonical
|
|
1114
|
-
* `@napplet/nap/notify` NIP-5D path and lives alongside the legacy module.
|
|
1030
|
+
* `notify-service.ts` is the canonical `@napplet/nap/notify` NIP-5D path.
|
|
1031
|
+
* It lives alongside the direct notification state registry in
|
|
1032
|
+
* `notification-service.ts`; neither service interprets an `inc.emit` topic.
|
|
1115
1033
|
* If the host app registers this service via
|
|
1116
1034
|
* `runtime.registerService('notify', ...)`, @napplet/nap/notify messages
|
|
1117
|
-
* land here
|
|
1035
|
+
* land here.
|
|
1118
1036
|
*
|
|
1119
1037
|
* Shell -> napplet push messages (`notify.action`, `notify.clicked`,
|
|
1120
1038
|
* `notify.dismissed`, `notify.controls`) are not emitted by this stub —
|
|
@@ -1678,10 +1596,12 @@ interface OutboxSubscribeOptions extends OutboxQueryOptions {
|
|
|
1678
1596
|
}
|
|
1679
1597
|
/** Options for an outbox publish. */
|
|
1680
1598
|
interface OutboxPublishOptions {
|
|
1681
|
-
/**
|
|
1599
|
+
/** Explicit relay URL fanout candidates, subject to shell validation. */
|
|
1682
1600
|
relays?: string[];
|
|
1683
|
-
/**
|
|
1684
|
-
|
|
1601
|
+
/** Include the shell user's NIP-65 write relays. Defaults to true. */
|
|
1602
|
+
toOutbox?: boolean;
|
|
1603
|
+
/** Recipient pubkeys whose NIP-65 read relays are required fanout targets. */
|
|
1604
|
+
toInboxes?: string[];
|
|
1685
1605
|
}
|
|
1686
1606
|
/** A read/write target for relay-plan resolution. */
|
|
1687
1607
|
interface OutboxTarget {
|
|
@@ -1739,6 +1659,18 @@ interface OutboxSubscriptionSink {
|
|
|
1739
1659
|
/** Signal that the subscription was closed upstream; `reason` is optional. */
|
|
1740
1660
|
closed(reason?: string): void;
|
|
1741
1661
|
}
|
|
1662
|
+
/** Sink a bounded outbox query streams verified events through as they arrive. */
|
|
1663
|
+
interface OutboxQueryStreamSink {
|
|
1664
|
+
/** Deliver one deduplicated, signature-validated event result. */
|
|
1665
|
+
event(result: RelayEventResult): void;
|
|
1666
|
+
}
|
|
1667
|
+
/** Handle for a bounded streaming query and its compatibility aggregation. */
|
|
1668
|
+
interface OutboxQueryStream {
|
|
1669
|
+
/** Aggregated result, settled on all-relay EOSE or the overall deadline. */
|
|
1670
|
+
readonly result: Promise<OutboxResult>;
|
|
1671
|
+
/** Stop relay reads and settle {@link result} as incomplete. */
|
|
1672
|
+
close(): void;
|
|
1673
|
+
}
|
|
1742
1674
|
/** Handle to a router-owned subscription. */
|
|
1743
1675
|
interface OutboxRouterSubscription {
|
|
1744
1676
|
/** Stop the subscription and release its relay connections. */
|
|
@@ -1761,6 +1693,16 @@ interface OutboxRouter {
|
|
|
1761
1693
|
/** Return the relay plan the shell would use for a read/write target. */
|
|
1762
1694
|
resolveRelays(target: OutboxTarget): Promise<OutboxRelayPlan>;
|
|
1763
1695
|
}
|
|
1696
|
+
/** Outbox router with an incremental surface for bounded queries. */
|
|
1697
|
+
interface StreamingOutboxRouter extends OutboxRouter {
|
|
1698
|
+
/**
|
|
1699
|
+
* Start policy/fallback reads immediately, stream verified events through
|
|
1700
|
+
* `sink`, and attach author relays when concurrent discovery resolves.
|
|
1701
|
+
* `options.limit` applies to the final aggregate; the sink receives every
|
|
1702
|
+
* verified unique arrival until EOSE, close, or the overall deadline.
|
|
1703
|
+
*/
|
|
1704
|
+
queryStream(filters: NostrFilter[], options: OutboxQueryOptions | undefined, sink: OutboxQueryStreamSink): OutboxQueryStream;
|
|
1705
|
+
}
|
|
1764
1706
|
/** Options for {@link createOutboxService}. */
|
|
1765
1707
|
interface OutboxServiceOptions {
|
|
1766
1708
|
/** The outbox router the shell uses to reach relays. Required. */
|
|
@@ -1776,7 +1718,52 @@ interface OutboxServiceOptions {
|
|
|
1776
1718
|
declare function createOutboxService(options: OutboxServiceOptions): ServiceHandler;
|
|
1777
1719
|
|
|
1778
1720
|
/**
|
|
1779
|
-
*
|
|
1721
|
+
* Relay-pool contracts for the concrete outbox router.
|
|
1722
|
+
*
|
|
1723
|
+
* @module
|
|
1724
|
+
*/
|
|
1725
|
+
|
|
1726
|
+
/** A NIP-65 relay list for a single pubkey. */
|
|
1727
|
+
interface RelayListEntry {
|
|
1728
|
+
/** Relays the author reads from (their inbox). */
|
|
1729
|
+
read: string[];
|
|
1730
|
+
/** Relays the author writes to (where their events land). */
|
|
1731
|
+
write: string[];
|
|
1732
|
+
}
|
|
1733
|
+
/**
|
|
1734
|
+
* Relay pool contract the router drives. Implementors adapt their pool library
|
|
1735
|
+
* while the router retains relay selection and event attribution.
|
|
1736
|
+
*/
|
|
1737
|
+
interface OutboxRelayPool {
|
|
1738
|
+
/** Subscribe to `filters` on exactly `relayUrls`. */
|
|
1739
|
+
subscribe(filters: NostrFilter[], relayUrls: string[], callback: (item: NostrEvent | 'EOSE') => void): {
|
|
1740
|
+
unsubscribe(): void;
|
|
1741
|
+
};
|
|
1742
|
+
/** Publish `event` to `relayUrls`, optionally returning per-relay outcomes. */
|
|
1743
|
+
publish(event: NostrEvent, relayUrls: string[]): Promise<Record<string, boolean>> | Record<string, boolean> | void;
|
|
1744
|
+
/** Whether the relay pool can handle requests. */
|
|
1745
|
+
isAvailable(): boolean;
|
|
1746
|
+
}
|
|
1747
|
+
/** Options for the relay-pool-backed outbox router. */
|
|
1748
|
+
interface RelayPoolOutboxRouterOptions {
|
|
1749
|
+
/** Relay pool the router subscribes and publishes through. */
|
|
1750
|
+
relayPool: OutboxRelayPool;
|
|
1751
|
+
/** Resolve NIP-65 relay lists for the requested pubkeys. */
|
|
1752
|
+
loadRelayLists(pubkeys: string[]): Promise<Map<string, RelayListEntry>> | Map<string, RelayListEntry>;
|
|
1753
|
+
/** Relays used when hints and NIP-65 data are unavailable. */
|
|
1754
|
+
fallbackRelays: string[];
|
|
1755
|
+
/** Sign a template before publish. Omission denies publishing. */
|
|
1756
|
+
signEvent?(template: EventTemplate): Promise<NostrEvent>;
|
|
1757
|
+
/** Validate an event before delivery. Host pools may pre-verify. */
|
|
1758
|
+
verifyEvent?(event: NostrEvent): Promise<boolean> | boolean;
|
|
1759
|
+
/** Gate every relay URL, including caller hints. */
|
|
1760
|
+
isRelayAllowed?(url: string): boolean;
|
|
1761
|
+
/** Default bounded-query and initial-discovery timeout in milliseconds. */
|
|
1762
|
+
defaultTimeoutMs?: number;
|
|
1763
|
+
}
|
|
1764
|
+
|
|
1765
|
+
/**
|
|
1766
|
+
* relay-pool-outbox-router.ts — concrete {@link StreamingOutboxRouter} backed by a relay pool.
|
|
1780
1767
|
*
|
|
1781
1768
|
* Implements the outbox-model routing that NAP-OUTBOX centralizes so napplets
|
|
1782
1769
|
* don't each reinvent it: derive authors, resolve their NIP-65 relays, fan a
|
|
@@ -1812,74 +1799,16 @@ declare function createOutboxService(options: OutboxServiceOptions): ServiceHand
|
|
|
1812
1799
|
* @packageDocumentation
|
|
1813
1800
|
*/
|
|
1814
1801
|
|
|
1815
|
-
/** A NIP-65 relay list for a single pubkey. */
|
|
1816
|
-
interface RelayListEntry {
|
|
1817
|
-
/** Relays the author reads from (their inbox). */
|
|
1818
|
-
read: string[];
|
|
1819
|
-
/** Relays the author writes to (where their events land). */
|
|
1820
|
-
write: string[];
|
|
1821
|
-
}
|
|
1822
1802
|
/**
|
|
1823
|
-
*
|
|
1824
|
-
* (nostr-tools SimplePool, applesauce-relay, etc.). Unlike the lower-level
|
|
1825
|
-
* relay NAP pool, both methods take an explicit relay-URL set so the router
|
|
1826
|
-
* controls outbox routing and can attribute events to the relay they arrived on.
|
|
1827
|
-
*/
|
|
1828
|
-
interface OutboxRelayPool {
|
|
1829
|
-
/**
|
|
1830
|
-
* Subscribe to `filters` on exactly `relayUrls`. The callback receives each
|
|
1831
|
-
* matching event or the literal `'EOSE'` once stored events are exhausted.
|
|
1832
|
-
* Returns a handle to cancel the subscription.
|
|
1833
|
-
*/
|
|
1834
|
-
subscribe(filters: NostrFilter[], relayUrls: string[], callback: (item: NostrEvent | 'EOSE') => void): {
|
|
1835
|
-
unsubscribe(): void;
|
|
1836
|
-
};
|
|
1837
|
-
/**
|
|
1838
|
-
* Publish `event` to `relayUrls`. May return a per-relay success map; a
|
|
1839
|
-
* `void`/missing return is treated as optimistic success on every target.
|
|
1840
|
-
*/
|
|
1841
|
-
publish(event: NostrEvent, relayUrls: string[]): Promise<Record<string, boolean>> | Record<string, boolean> | void;
|
|
1842
|
-
/** Whether the relay pool is connected and able to handle requests. */
|
|
1843
|
-
isAvailable(): boolean;
|
|
1844
|
-
}
|
|
1845
|
-
/** Options for {@link createRelayPoolOutboxRouter}. */
|
|
1846
|
-
interface RelayPoolOutboxRouterOptions {
|
|
1847
|
-
/** Relay pool the router subscribes/publishes through. Required. */
|
|
1848
|
-
relayPool: OutboxRelayPool;
|
|
1849
|
-
/**
|
|
1850
|
-
* Resolve NIP-65 relay lists for a set of pubkeys. Pubkeys with no known
|
|
1851
|
-
* list are simply omitted from the returned map (they become `missingAuthors`).
|
|
1852
|
-
*/
|
|
1853
|
-
loadRelayLists(pubkeys: string[]): Promise<Map<string, RelayListEntry>> | Map<string, RelayListEntry>;
|
|
1854
|
-
/** Relays to fall back to when NIP-65 data is absent, stale, or empty. Required. */
|
|
1855
|
-
fallbackRelays: string[];
|
|
1856
|
-
/**
|
|
1857
|
-
* Sign a template before publish (shell-mediated; napplets never sign). When
|
|
1858
|
-
* omitted, `publish` resolves with `{ ok: false, error: 'publish denied' }`.
|
|
1859
|
-
*/
|
|
1860
|
-
signEvent?(template: EventTemplate): Promise<NostrEvent>;
|
|
1861
|
-
/**
|
|
1862
|
-
* Validate an event signature before delivering it to a napplet. May be sync
|
|
1863
|
-
* or async. Defaults to accepting every event (host pools often pre-verify).
|
|
1864
|
-
*/
|
|
1865
|
-
verifyEvent?(event: NostrEvent): Promise<boolean> | boolean;
|
|
1866
|
-
/**
|
|
1867
|
-
* Gate relay URLs (e.g. block private-network hosts). Defaults to allowing
|
|
1868
|
-
* only `ws://` / `wss://` URLs — `options.relays` hints pass through this too.
|
|
1869
|
-
*/
|
|
1870
|
-
isRelayAllowed?(url: string): boolean;
|
|
1871
|
-
/** Default query timeout when `options.timeoutMs` is unset. Default 4000ms. */
|
|
1872
|
-
defaultTimeoutMs?: number;
|
|
1873
|
-
}
|
|
1874
|
-
/**
|
|
1875
|
-
* Create a relay-pool-backed {@link OutboxRouter}.
|
|
1803
|
+
* Create a relay-pool-backed {@link StreamingOutboxRouter}.
|
|
1876
1804
|
*
|
|
1877
1805
|
* @param options - Relay pool, NIP-65 loader, fallback relays, and optional
|
|
1878
1806
|
* signer / verifier / relay gate / timeout.
|
|
1879
|
-
* @returns
|
|
1807
|
+
* @returns A {@link StreamingOutboxRouter} for direct incremental reads and
|
|
1808
|
+
* compatibility use through {@link createOutboxService}.
|
|
1880
1809
|
* @throws If `relayPool`, `loadRelayLists`, or `fallbackRelays` are missing.
|
|
1881
1810
|
*/
|
|
1882
|
-
declare function createRelayPoolOutboxRouter(options: RelayPoolOutboxRouterOptions):
|
|
1811
|
+
declare function createRelayPoolOutboxRouter(options: RelayPoolOutboxRouterOptions): StreamingOutboxRouter;
|
|
1883
1812
|
|
|
1884
1813
|
/**
|
|
1885
1814
|
* upload-service.ts — NAP-UPLOAD (shell-mediated file/blob upload) reference service.
|
|
@@ -2139,109 +2068,17 @@ interface HttpUploaderOptions {
|
|
|
2139
2068
|
*/
|
|
2140
2069
|
declare function createHttpUploader(options: HttpUploaderOptions): Uploader;
|
|
2141
2070
|
|
|
2142
|
-
/**
|
|
2143
|
-
* intent-types.ts — NAP-INTENT (archetype intent dispatch) value types.
|
|
2144
|
-
*
|
|
2145
|
-
* Kehto-internal model for the NAP-INTENT wire contract (upstream draft:
|
|
2146
|
-
* napplet/naps NAP-INTENT, namespace `window.napplet.intent`). The installed
|
|
2147
|
-
* `@napplet/core` peer predates these types, so — as with {@link ./cvm-types} —
|
|
2148
|
-
* kehto defines them here, wire-compatible with the upstream shapes, rather
|
|
2149
|
-
* than redefining the generic NIP-5D envelope.
|
|
2150
|
-
*
|
|
2151
|
-
* NAP-INTENT standardizes the *envelope*, not the payload. `archetype` is the
|
|
2152
|
-
* routing axis (which role, whose default), `protocol` is the parsing axis
|
|
2153
|
-
* (which NAP-N wire format shapes `payload`); the two are orthogonal.
|
|
2154
|
-
*
|
|
2155
|
-
* @packageDocumentation
|
|
2156
|
-
*/
|
|
2157
|
-
/**
|
|
2158
|
-
* How the shell should pick the handling napplet for an intent.
|
|
2159
|
-
*
|
|
2160
|
-
* - `"default"` — route to the user's default handler for the archetype.
|
|
2161
|
-
* - `"choose"` — prompt the user with an "open with…" chooser.
|
|
2162
|
-
* - any other string — a specific napplet dTag (cross-napplet targeting; the
|
|
2163
|
-
* shell SHOULD require the user to have authorized this for the caller).
|
|
2164
|
-
*/
|
|
2165
|
-
type IntentHandlerPreference = 'default' | 'choose' | (string & {});
|
|
2166
|
-
/** Window-behavior hints carried with an intent invoke. */
|
|
2167
|
-
interface IntentBehavior {
|
|
2168
|
-
/** Bring the handler window to the foreground. */
|
|
2169
|
-
focus?: boolean;
|
|
2170
|
-
/** Force a new window rather than reusing an existing handler instance. */
|
|
2171
|
-
newWindow?: boolean;
|
|
2172
|
-
/** Prefer reusing an already-open handler instance when one exists. */
|
|
2173
|
-
reuse?: boolean;
|
|
2174
|
-
}
|
|
2175
|
-
/** A request to dispatch an action to a napplet of a given archetype. */
|
|
2176
|
-
interface IntentRequest {
|
|
2177
|
-
/** Role slug, e.g. `"note"` (see the archetype registry). */
|
|
2178
|
-
archetype: string;
|
|
2179
|
-
/** Verb, default `"open"` (e.g. `"open"` | `"edit"` | `"pick"` | `"share"`). */
|
|
2180
|
-
action?: string;
|
|
2181
|
-
/** NAP-N id shaping `payload`; omit to use the archetype's recommended default. */
|
|
2182
|
-
protocol?: string;
|
|
2183
|
-
/** Opaque payload, typed by `protocol`. */
|
|
2184
|
-
payload?: unknown;
|
|
2185
|
-
/** Handler-selection preference. */
|
|
2186
|
-
handler?: IntentHandlerPreference;
|
|
2187
|
-
/** Window-behavior hints. */
|
|
2188
|
-
behavior?: IntentBehavior;
|
|
2189
|
-
}
|
|
2190
|
-
/** A napplet that can fulfill an archetype, sourced from the manifest catalog. */
|
|
2191
|
-
interface IntentCandidate {
|
|
2192
|
-
/** dTag of the napplet that can fulfill the archetype. */
|
|
2193
|
-
dTag: string;
|
|
2194
|
-
/** Human-readable title from the manifest. */
|
|
2195
|
-
title?: string;
|
|
2196
|
-
/** Verbs this candidate supports for the archetype. */
|
|
2197
|
-
actions: string[];
|
|
2198
|
-
/** NAP-N ids this candidate accepts for the archetype. */
|
|
2199
|
-
protocols: string[];
|
|
2200
|
-
/** Whether this candidate is the user/runtime default for the archetype. */
|
|
2201
|
-
isDefault?: boolean;
|
|
2202
|
-
}
|
|
2203
|
-
/** Availability of an archetype, sourced from the installed-napplet catalog. */
|
|
2204
|
-
interface IntentAvailability {
|
|
2205
|
-
/** The archetype this availability describes. */
|
|
2206
|
-
archetype: string;
|
|
2207
|
-
/** True when at least one installed napplet fulfills the archetype. */
|
|
2208
|
-
available: boolean;
|
|
2209
|
-
/** Candidate napplets that fulfill the archetype (from manifests, not instances). */
|
|
2210
|
-
candidates: IntentCandidate[];
|
|
2211
|
-
/** True when a user/runtime default handler is set for the archetype. */
|
|
2212
|
-
hasDefault: boolean;
|
|
2213
|
-
}
|
|
2214
|
-
/** The result of an intent invocation. */
|
|
2215
|
-
interface IntentResult {
|
|
2216
|
-
/** Whether the intent was dispatched successfully. */
|
|
2217
|
-
ok: boolean;
|
|
2218
|
-
/** The requested archetype, echoed back. */
|
|
2219
|
-
archetype: string;
|
|
2220
|
-
/** The resolved action (defaults to `"open"` when the request omits it). */
|
|
2221
|
-
action: string;
|
|
2222
|
-
/** True when a handler accepted the dispatch. */
|
|
2223
|
-
handled: boolean;
|
|
2224
|
-
/** dTag of the napplet that handled the intent, when one did. */
|
|
2225
|
-
handler?: string;
|
|
2226
|
-
/** Window id the handler was created or focused in. */
|
|
2227
|
-
windowId?: string;
|
|
2228
|
-
/** The wire format actually used to deliver `payload`. */
|
|
2229
|
-
protocol?: string;
|
|
2230
|
-
/** Error reason when the intent could not be fulfilled. */
|
|
2231
|
-
error?: string;
|
|
2232
|
-
}
|
|
2233
|
-
|
|
2234
2071
|
/**
|
|
2235
2072
|
* intent-service.ts — NAP-INTENT (archetype intent dispatch) reference service.
|
|
2236
2073
|
*
|
|
2237
2074
|
* Shell-side handler for the NAP-INTENT wire protocol. It is a pure envelope
|
|
2238
2075
|
* router: it validates `intent.*` envelopes, delegates archetype resolution,
|
|
2239
|
-
* default handling
|
|
2240
|
-
* {@link IntentResolver},
|
|
2241
|
-
*
|
|
2076
|
+
* default handling and retained target delivery to an injected
|
|
2077
|
+
* {@link IntentResolver}, then posts correlated result and push messages back
|
|
2078
|
+
* to the napplet.
|
|
2242
2079
|
*
|
|
2243
2080
|
* The resolver is injected (options-as-bridge) so this service has no shell or
|
|
2244
|
-
*
|
|
2081
|
+
* target-lifecycle dependency and is fully unit-testable. A concrete
|
|
2245
2082
|
* catalog-backed resolver ships alongside as {@link createCatalogIntentResolver}.
|
|
2246
2083
|
*
|
|
2247
2084
|
* ──────────────────────────── Responsibilities ────────────────────────────
|
|
@@ -2250,15 +2087,15 @@ interface IntentResult {
|
|
|
2250
2087
|
* intent.handlers.result, intent.changed
|
|
2251
2088
|
*
|
|
2252
2089
|
* The shell owns archetype→handler resolution, the user's default-handler
|
|
2253
|
-
* preference,
|
|
2254
|
-
*
|
|
2255
|
-
* fans `intent.changed` pushes out to
|
|
2090
|
+
* preference, chooser, and retained target policy behind the
|
|
2091
|
+
* {@link IntentResolver}. This service only marshals the wire protocol and
|
|
2092
|
+
* fans `intent.changed` pushes out to eligible napplets.
|
|
2256
2093
|
*
|
|
2257
2094
|
* @example
|
|
2258
2095
|
* ```ts
|
|
2259
2096
|
* import { createIntentService, createCatalogIntentResolver } from '@kehto/services';
|
|
2260
2097
|
*
|
|
2261
|
-
* const resolver = createCatalogIntentResolver({ loadCatalog,
|
|
2098
|
+
* const resolver = createCatalogIntentResolver({ loadCatalog, targets });
|
|
2262
2099
|
* runtime.registerService('intent', createIntentService({ resolver }));
|
|
2263
2100
|
* ```
|
|
2264
2101
|
*
|
|
@@ -2267,22 +2104,53 @@ interface IntentResult {
|
|
|
2267
2104
|
|
|
2268
2105
|
/** Context passed to {@link IntentResolver.invoke} for trust/attribution. */
|
|
2269
2106
|
interface IntentResolverContext {
|
|
2270
|
-
/**
|
|
2271
|
-
|
|
2107
|
+
/** Runtime-attested dTag of the napplet that issued the request. */
|
|
2108
|
+
sender: string;
|
|
2272
2109
|
}
|
|
2110
|
+
/**
|
|
2111
|
+
* Opaque runtime-owned delivery responsibility retained before acceptance.
|
|
2112
|
+
*
|
|
2113
|
+
* Starting the task may wait for target readiness and apply host retry,
|
|
2114
|
+
* replacement, or terminal-failure policy. It never produces a second source
|
|
2115
|
+
* result.
|
|
2116
|
+
*/
|
|
2117
|
+
interface IntentRetainedDelivery {
|
|
2118
|
+
/**
|
|
2119
|
+
* Begin target lifecycle and eventual delivery policy.
|
|
2120
|
+
*
|
|
2121
|
+
* @returns Nothing, or a promise settled when controller policy completes.
|
|
2122
|
+
*/
|
|
2123
|
+
start(): void | Promise<void>;
|
|
2124
|
+
}
|
|
2125
|
+
/** A resolver rejection before delivery responsibility was retained. */
|
|
2126
|
+
interface IntentRejectedResolverOutcome {
|
|
2127
|
+
/** Exact canonical pre-acceptance rejection. */
|
|
2128
|
+
result: IntentRejectedResult;
|
|
2129
|
+
}
|
|
2130
|
+
/** A resolver acceptance backed by already-retained delivery responsibility. */
|
|
2131
|
+
interface IntentAcceptedResolverOutcome {
|
|
2132
|
+
/** Exact canonical acceptance result. */
|
|
2133
|
+
result: IntentAcceptedResult;
|
|
2134
|
+
/** Opaque task that the service starts only after sending the source result. */
|
|
2135
|
+
retained: IntentRetainedDelivery;
|
|
2136
|
+
}
|
|
2137
|
+
/** Pre-acceptance rejection or accepted retained-delivery responsibility. */
|
|
2138
|
+
type IntentResolverOutcome = IntentRejectedResolverOutcome | IntentAcceptedResolverOutcome;
|
|
2273
2139
|
/**
|
|
2274
2140
|
* Abstract intent resolver. Implementors own the installed-napplet catalog,
|
|
2275
2141
|
* archetype→handler resolution, the user's default-handler preference, the
|
|
2276
|
-
*
|
|
2142
|
+
* chooser and retained target delivery policy. The
|
|
2277
2143
|
* service translates wire envelopes into these calls and back.
|
|
2278
2144
|
*/
|
|
2279
2145
|
interface IntentResolver {
|
|
2280
2146
|
/**
|
|
2281
|
-
* Resolve
|
|
2282
|
-
*
|
|
2283
|
-
*
|
|
2147
|
+
* Resolve the request and retain target delivery responsibility.
|
|
2148
|
+
*
|
|
2149
|
+
* @param request - Validated normalized intent request.
|
|
2150
|
+
* @param context - Runtime-attested source identity.
|
|
2151
|
+
* @returns A structured rejection, or an acceptance plus an unstarted task.
|
|
2284
2152
|
*/
|
|
2285
|
-
invoke(request: IntentRequest, context: IntentResolverContext):
|
|
2153
|
+
invoke(request: IntentRequest, context: IntentResolverContext): IntentResolverOutcome | Promise<IntentResolverOutcome>;
|
|
2286
2154
|
/** Report whether the runtime can currently satisfy `archetype`, and how. */
|
|
2287
2155
|
available(archetype: string): IntentAvailability | Promise<IntentAvailability>;
|
|
2288
2156
|
/** Report availability for every archetype the runtime can currently satisfy. */
|
|
@@ -2312,35 +2180,32 @@ declare function createIntentService(options: IntentServiceOptions): ServiceHand
|
|
|
2312
2180
|
/**
|
|
2313
2181
|
* catalog-intent-resolver.ts — NAP-INTENT concrete {@link IntentResolver}.
|
|
2314
2182
|
*
|
|
2315
|
-
* A reference resolver
|
|
2316
|
-
*
|
|
2317
|
-
*
|
|
2318
|
-
*
|
|
2319
|
-
*
|
|
2320
|
-
*
|
|
2321
|
-
*
|
|
2322
|
-
*
|
|
2323
|
-
*
|
|
2324
|
-
*
|
|
2325
|
-
*
|
|
2326
|
-
*
|
|
2327
|
-
*
|
|
2328
|
-
*
|
|
2329
|
-
* 4. Open or focus the handler window and return its id.
|
|
2330
|
-
*
|
|
2331
|
-
* The catalog, defaults, chooser, and window controller are all injected, so
|
|
2332
|
-
* this resolver carries no shell, manifest, or DOM dependency and is fully
|
|
2333
|
-
* unit-testable.
|
|
2183
|
+
* A reference resolver backed by installed, verified NIP-5A manifest contracts
|
|
2184
|
+
* plus host-supplied user policy. Contract compatibility is exact complete
|
|
2185
|
+
* convention equality. Catalog order, payload contents, quick action indexes,
|
|
2186
|
+
* and event-kind metadata never select a handler.
|
|
2187
|
+
*
|
|
2188
|
+
* Selection policy:
|
|
2189
|
+
* 1. Filter installed candidates by exact manifest contract.
|
|
2190
|
+
* 2. Require positive host authorization for an explicit handler dTag.
|
|
2191
|
+
* 3. Otherwise use an explicit chooser, a compatible user default, the sole
|
|
2192
|
+
* compatible candidate, or an injected chooser.
|
|
2193
|
+
* 4. Reject ambiguity when no chooser policy exists.
|
|
2194
|
+
*
|
|
2195
|
+
* The catalog, defaults, chooser, authorization hook, and target controller are
|
|
2196
|
+
* injected, so this resolver has no shell, manifest, or DOM dependency.
|
|
2334
2197
|
*
|
|
2335
2198
|
* @packageDocumentation
|
|
2336
2199
|
*/
|
|
2337
2200
|
|
|
2338
|
-
/** The
|
|
2201
|
+
/** The exact manifest-derived conventions a napplet fulfills for one archetype. */
|
|
2339
2202
|
interface IntentArchetypeSupport {
|
|
2340
|
-
/** Verbs this napplet
|
|
2203
|
+
/** Verbs derived from this napplet's accepted conventions. */
|
|
2341
2204
|
actions: string[];
|
|
2342
|
-
/**
|
|
2343
|
-
|
|
2205
|
+
/** Stable queryless convention identities derived from {@link contracts}. */
|
|
2206
|
+
conventions: string[];
|
|
2207
|
+
/** Authoritative ordered contracts parsed from the installed manifest. */
|
|
2208
|
+
contracts: IntentContract[];
|
|
2344
2209
|
}
|
|
2345
2210
|
/**
|
|
2346
2211
|
* One installed napplet's intent surface, derived from its signed NIP-5A
|
|
@@ -2352,57 +2217,60 @@ interface IntentCatalogEntry {
|
|
|
2352
2217
|
dTag: string;
|
|
2353
2218
|
/** Human-readable title from the manifest. */
|
|
2354
2219
|
title?: string;
|
|
2355
|
-
/** Archetype slug
|
|
2220
|
+
/** Archetype slug to exact manifest-derived support. */
|
|
2356
2221
|
archetypes: Record<string, IntentArchetypeSupport>;
|
|
2357
2222
|
}
|
|
2358
|
-
/**
|
|
2359
|
-
interface
|
|
2360
|
-
/**
|
|
2361
|
-
|
|
2362
|
-
/**
|
|
2363
|
-
|
|
2364
|
-
/**
|
|
2365
|
-
|
|
2366
|
-
|
|
2367
|
-
|
|
2368
|
-
|
|
2369
|
-
|
|
2370
|
-
|
|
2371
|
-
|
|
2372
|
-
|
|
2373
|
-
|
|
2374
|
-
|
|
2375
|
-
|
|
2376
|
-
interface IntentWindowController {
|
|
2377
|
-
/**
|
|
2378
|
-
* Create or focus the handler window and deliver `payload` via `protocol`.
|
|
2379
|
-
* Returns the window id the handler was created or focused in.
|
|
2380
|
-
*/
|
|
2381
|
-
open(params: IntentOpenParams): {
|
|
2382
|
-
windowId: string;
|
|
2383
|
-
} | Promise<{
|
|
2384
|
-
windowId: string;
|
|
2385
|
-
}>;
|
|
2223
|
+
/** Exact carrier-neutral values retained for one selected intent target. */
|
|
2224
|
+
interface IntentRetentionParams {
|
|
2225
|
+
/** Selected target napplet dTag. */
|
|
2226
|
+
readonly handler: string;
|
|
2227
|
+
/** Immutable canonical delivery retained independently of the source. */
|
|
2228
|
+
readonly delivery: Readonly<IntentDelivery>;
|
|
2229
|
+
/** Copied non-authoritative target lifecycle hints. */
|
|
2230
|
+
readonly behavior?: Readonly<IntentBehavior>;
|
|
2231
|
+
}
|
|
2232
|
+
/** Host controller that retains source-independent target delivery policy. */
|
|
2233
|
+
interface IntentTargetController {
|
|
2234
|
+
/**
|
|
2235
|
+
* Retain delivery responsibility without starting target policy.
|
|
2236
|
+
*
|
|
2237
|
+
* @param params - Immutable selected target and canonical delivery values.
|
|
2238
|
+
* @returns An opaque unstarted delivery task.
|
|
2239
|
+
*/
|
|
2240
|
+
retain(params: IntentRetentionParams): IntentRetainedDelivery | Promise<IntentRetainedDelivery>;
|
|
2386
2241
|
}
|
|
2387
2242
|
/** Options for {@link createCatalogIntentResolver}. */
|
|
2388
2243
|
interface CatalogIntentResolverOptions {
|
|
2389
|
-
/** Return the installed-napplet catalog
|
|
2244
|
+
/** Return the installed-napplet catalog sourced from signed manifests. */
|
|
2390
2245
|
loadCatalog(): IntentCatalogEntry[] | Promise<IntentCatalogEntry[]>;
|
|
2391
|
-
/**
|
|
2392
|
-
|
|
2246
|
+
/** Target controller that retains responsibility before resolver acceptance. */
|
|
2247
|
+
targets: IntentTargetController;
|
|
2393
2248
|
/**
|
|
2394
|
-
*
|
|
2395
|
-
*
|
|
2249
|
+
* Return the user's default handler dTag for an archetype.
|
|
2250
|
+
*
|
|
2251
|
+
* @param archetype - Normalized archetype slug.
|
|
2252
|
+
* @returns The user-selected default dTag, or `undefined`.
|
|
2396
2253
|
*/
|
|
2397
2254
|
getDefaultHandler?(archetype: string): string | undefined;
|
|
2398
2255
|
/**
|
|
2399
|
-
*
|
|
2400
|
-
*
|
|
2401
|
-
*
|
|
2256
|
+
* Ask user policy to select one exact-compatible candidate.
|
|
2257
|
+
*
|
|
2258
|
+
* @param archetype - Normalized archetype slug.
|
|
2259
|
+
* @param candidates - Only candidates with an exact matching contract.
|
|
2260
|
+
* @param sender - Runtime-attested source napplet dTag.
|
|
2261
|
+
* @returns A candidate dTag, or `undefined` when the user cancels.
|
|
2402
2262
|
*/
|
|
2403
|
-
chooseHandler?(archetype: string, candidates: IntentCandidate[],
|
|
2404
|
-
/**
|
|
2405
|
-
|
|
2263
|
+
chooseHandler?(archetype: string, candidates: IntentCandidate[], sender: string): string | undefined | Promise<string | undefined>;
|
|
2264
|
+
/**
|
|
2265
|
+
* Authorize a caller's explicit handler dTag preference.
|
|
2266
|
+
*
|
|
2267
|
+
* @param sender - Runtime-attested source napplet dTag.
|
|
2268
|
+
* @param handler - Explicit requested handler dTag.
|
|
2269
|
+
* @param request - Normalized intent request.
|
|
2270
|
+
* @param candidate - Installed exact-compatible candidate.
|
|
2271
|
+
* @returns `true` only when explicit targeting is user-authorized.
|
|
2272
|
+
*/
|
|
2273
|
+
authorizeExplicitHandler?(sender: string, handler: string, request: IntentRequest, candidate: IntentCandidate): boolean | Promise<boolean>;
|
|
2406
2274
|
}
|
|
2407
2275
|
/**
|
|
2408
2276
|
* A {@link IntentResolver} backed by a catalog, with a host hook to announce
|
|
@@ -2410,26 +2278,27 @@ interface CatalogIntentResolverOptions {
|
|
|
2410
2278
|
*/
|
|
2411
2279
|
interface CatalogIntentResolver extends IntentResolver {
|
|
2412
2280
|
/**
|
|
2413
|
-
* Announce that the catalog or default handler for `archetype` changed.
|
|
2414
|
-
*
|
|
2415
|
-
*
|
|
2281
|
+
* Announce that the catalog or default handler for `archetype` changed.
|
|
2282
|
+
*
|
|
2283
|
+
* @param archetype - Changed archetype slug.
|
|
2284
|
+
* @returns Nothing.
|
|
2416
2285
|
*/
|
|
2417
2286
|
notifyChanged(archetype: string): void;
|
|
2418
2287
|
}
|
|
2419
2288
|
/**
|
|
2420
2289
|
* Create a catalog-backed NAP-INTENT resolver.
|
|
2421
2290
|
*
|
|
2422
|
-
* @param options - Catalog loader and
|
|
2423
|
-
*
|
|
2424
|
-
* @returns A
|
|
2425
|
-
* @throws If
|
|
2291
|
+
* @param options - Catalog loader and target controller plus optional user
|
|
2292
|
+
* default, chooser, and explicit-handler authorization hooks.
|
|
2293
|
+
* @returns A catalog-backed resolver.
|
|
2294
|
+
* @throws If required catalog or target-controller options are missing.
|
|
2426
2295
|
*
|
|
2427
2296
|
* @example
|
|
2428
2297
|
* ```ts
|
|
2429
2298
|
* const resolver = createCatalogIntentResolver({
|
|
2430
2299
|
* loadCatalog: () => installedNapplets,
|
|
2431
|
-
*
|
|
2432
|
-
* getDefaultHandler: (
|
|
2300
|
+
* targets: { retain: (params) => retainTargetDelivery(params) },
|
|
2301
|
+
* getDefaultHandler: (archetype) => userDefaults[archetype],
|
|
2433
2302
|
* });
|
|
2434
2303
|
* ```
|
|
2435
2304
|
*/
|
|
@@ -2463,22 +2332,22 @@ interface ManifestArchetypeInput {
|
|
|
2463
2332
|
/** Optional human-readable title from the manifest. */
|
|
2464
2333
|
title?: string;
|
|
2465
2334
|
/**
|
|
2466
|
-
*
|
|
2467
|
-
* the optional `nap` is the recommended default wire protocol.
|
|
2335
|
+
* Ordered convention contracts from the manifest's `archetype` tags.
|
|
2468
2336
|
*/
|
|
2469
2337
|
archetypes: Array<{
|
|
2470
2338
|
slug: string;
|
|
2471
|
-
|
|
2339
|
+
convention: string;
|
|
2340
|
+
eventKinds?: number[];
|
|
2472
2341
|
}>;
|
|
2473
2342
|
}
|
|
2474
2343
|
/**
|
|
2475
2344
|
* Map a resolved napplet manifest's archetype data into an
|
|
2476
2345
|
* {@link IntentCatalogEntry}.
|
|
2477
2346
|
*
|
|
2478
|
-
* Each
|
|
2479
|
-
*
|
|
2480
|
-
*
|
|
2481
|
-
*
|
|
2347
|
+
* Each manifest tag remains one ordered contract. Repeated slugs group into one
|
|
2348
|
+
* support record while repeated conventions remain distinct contracts; action
|
|
2349
|
+
* and convention arrays are stable, deduplicated indexes derived from those
|
|
2350
|
+
* contracts.
|
|
2482
2351
|
*
|
|
2483
2352
|
* @param manifest - A resolved manifest's structural archetype data.
|
|
2484
2353
|
* @returns The `IntentCatalogEntry` for `createCatalogIntentResolver`.
|
|
@@ -2488,10 +2357,14 @@ interface ManifestArchetypeInput {
|
|
|
2488
2357
|
* manifestToIntentCatalogEntry({
|
|
2489
2358
|
* dTag: 'profile-viewer',
|
|
2490
2359
|
* title: 'Profile',
|
|
2491
|
-
* archetypes: [{ slug: 'profile',
|
|
2360
|
+
* archetypes: [{ slug: 'profile', convention: 'napplet:profile/open' }],
|
|
2492
2361
|
* });
|
|
2493
2362
|
* // → { dTag: 'profile-viewer', title: 'Profile',
|
|
2494
|
-
* // archetypes: { profile: {
|
|
2363
|
+
* // archetypes: { profile: {
|
|
2364
|
+
* // actions: ['open'],
|
|
2365
|
+
* // conventions: ['napplet:profile/open'],
|
|
2366
|
+
* // contracts: [{ convention: 'napplet:profile/open' }],
|
|
2367
|
+
* // } } }
|
|
2495
2368
|
* ```
|
|
2496
2369
|
*/
|
|
2497
2370
|
declare function manifestToIntentCatalogEntry(manifest: ManifestArchetypeInput): IntentCatalogEntry;
|
|
@@ -3001,4 +2874,4 @@ declare function createCordnRelayCoordinatorClient(options: CordnRelayCoordinato
|
|
|
3001
2874
|
/** Create a Cordn/ContextVM-backed NAP-DM adapter. */
|
|
3002
2875
|
declare function createCordnDmAdapter(options: CordnDmAdapterOptions): DmAdapter;
|
|
3003
2876
|
|
|
3004
|
-
export { type
|
|
2877
|
+
export { type BleServiceContext, type BleServiceOptions, type CacheServiceOptions, type CatalogIntentResolver, type CatalogIntentResolverOptions, type CommonServiceContext, type CommonServiceOptions, type ConfigSchemaValidation, type ConfigService, type ConfigServiceOptions, type CoordinatedRelayOptions, type CordnCodecResult, type CordnCoordinatorClient, type CordnCoordinatorSubscription, type CordnDmAdapterOptions, type CordnDmClient, type CordnGroupMessage, type CordnRelayCoordinatorOptions, type CountRequest, type CountResult, type CountServiceOptions, type DmAdapter, type DmConversation, type DmConversationPage, type DmConversationQuery, type DmHexPubkey, DmMemoryStore, type DmMessage, type DmMessagePage, type DmMessageQuery, type DmMessageStatus, type DmOk, type DmPeer, type DmRelayPool, type DmSendRequest, type DmSendResult, type DmService, type DmServiceOptions, type DmStatus, type DmSubscribeRequest, type DmSubscription, type DmTimestamp, type HostCacheBridge, type HostKeyEvent, type HostKeysBridge, type HostMediaBridge, type HttpUploaderOptions, type HttpUploaderRails, type IdentityServiceOptions, type IntentAcceptedResolverOutcome, type IntentArchetypeSupport, type IntentCatalogEntry, type IntentRejectedResolverOutcome, type IntentResolver, type IntentResolverContext, type IntentResolverOutcome, type IntentRetainedDelivery, type IntentRetentionParams, type IntentServiceOptions, type IntentTargetController, type KeysServiceOptions, type LinkOpenContext, type LinkServiceOptions, type ListsServiceContext, type ListsServiceOptions, type ManifestArchetypeInput, type MaybePromise, type MediaMetadataLike, type MediaPlaybackOwner, type MediaServiceOptions, type MediaSessionCreateOptions, type MediaSessionTarget, type MediaSourceRef, type NdrDmAdapterOptions, type NdrRelayTransport, type NdrRelayTransportOptions, type NdrRumorLike, type NdrRuntimeLike, type Nip17DmAdapterOptions, type NostrTag, type Notification, type NotificationServiceOptions, type NotifyServiceOptions, type OutboxEventOptions, type OutboxEventResult, type OutboxPublishOptions, type OutboxPublishResult, type OutboxQueryOptions, type OutboxQueryStream, type OutboxQueryStreamSink, type OutboxRelayPlan, type OutboxRelayPool, type OutboxResult, type OutboxRouter, type OutboxRouterSubscription, type OutboxServiceOptions, type OutboxSubscribeOptions, type OutboxSubscriptionSink, type OutboxTarget, type RailServerConfig, type RelayListEntry, type RelayPoolOutboxRouterOptions, type RelayPoolServiceOptions, type ResourceInfo, type ResourceInfoContext, type ResourceInfoProvider, type ResourceSchemeInfo, type ResourceService, type ResourceServiceOptions, type SerialServiceContext, type SerialServiceOptions, type SignEvent, type StreamingOutboxRouter, type ThemeService, type ThemeServiceOptions, type UploadDimensions, type UploadInfo, type UploadInfoContext, type UploadInfoProvider, type UploadRail, type UploadRailInfo, type UploadRequest, type UploadResult, type UploadServiceOptions, type UploadState, type UploadStatus, type Uploader, type UploaderContext, type WebrtcServiceContext, type WebrtcServiceOptions, createBleService, createBrowserMediaBridge, createCacheService, createCatalogIntentResolver, createCommonService, createConfigService, createCoordinatedRelay, createCordnDmAdapter, createCordnRelayCoordinatorClient, createCountService, createDmService, createHttpUploader, createIdentityService, createIntentService, createKeysService, createLinkService, createListsService, createMediaService, createNdrDmAdapter, createNdrRelayTransport, createNip17DmAdapter, createNotificationService, createNotifyService, createOutboxService, createRelayPoolOutboxRouter, createRelayPoolService, createResourceService, createSerialService, createThemeService, createUploadService, createWebrtcService, manifestToIntentCatalogEntry };
|