@kehto/services 0.11.0 → 0.11.1

package/README.md

@@ -36,9 +36,9 @@ import {
 runtime.registerService(
   'identity',
   createIdentityService({
-    getPublicKey: () => signer.getPublicKey(),
-    getRelays: () => signer.getRelays(),
+    getSigner: () => signer,
     getProfile: (pk) => nostrClient.fetchProfile(pk),
+    getFollows: (pk) => contactListCache.getFollows(pk),
   }),
 );
 
@@ -353,6 +353,8 @@ Each factory returns a `ServiceHandler` registrable via `runtime.registerService
 ### Identity NAP
 - `createIdentityService` — `identity.*` reads (`identity:read`). No signing surface; shell mediates signing internally.
 
+`createIdentityService` uses `getSigner()` for `identity.getPublicKey` and `identity.getRelays`. Hosts may also pass optional read-only provider hooks for `getProfile`, `getFollows`, `getList`, `getZaps`, `getMutes`, `getBlocked`, and `getBadges`. These hooks receive the current signer pubkey (or `""` when no signer is connected) and return the payload portion of the corresponding `.result` envelope. Kehto does not query relays itself; the hooks are for hosts that already maintain profile, contact-list, list, zap, moderation, or badge data.
+
 ### Notify NAP
 - `createNotifyService` — canonical `notify.*` envelopes (`notify:send` / `notify:channel`).
 - `createNotificationService` — legacy inc-emit `notifications:*` channel; coexists with `createNotifyService` until retired.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { ServiceHandler, Signer } from '@kehto/runtime';
+import { IdentityGetProfileMessage, IdentityGetProfileResultMessage, IdentityGetFollowsMessage, IdentityGetFollowsResultMessage, IdentityGetListMessage, IdentityGetListResultMessage, IdentityGetZapsMessage, IdentityGetZapsResultMessage, IdentityGetMutesMessage, IdentityGetMutesResultMessage, IdentityGetBlockedMessage, IdentityGetBlockedResultMessage, IdentityGetBadgesMessage, IdentityGetBadgesResultMessage } from '@napplet/nap/identity/types';
 import { NostrFilter, NostrEvent, EventTemplate } from '@napplet/core';
 import { MediaMetadata, MediaAction } from '@napplet/nap/media/types';
 export { MediaAction } from '@napplet/nap/media/types';
@@ -189,11 +190,12 @@ declare function createNotificationService(options?: NotificationServiceOptions)
  *
  * Handles 9 identity.* request types from @napplet/nap/identity. getPublicKey
  * and getRelays return real values sourced from hooks.auth.getSigner(); the
- * remaining 7 (getProfile/getFollows/getList/getZaps/getMutes/getBlocked/
- * getBadges) are stub-level. Host apps plug real backends via
- * runtime.registerService('identity', realHandler).
+ * remaining read-only queries can be backed by optional host providers. When a
+ * provider is absent, the service keeps returning spec-shaped empty results.
  */
 
+/** A value that may be returned synchronously or through a Promise. */
+type MaybePromise<T> = T | Promise<T>;
 /**
  * Options for creating the identity service.
  *
@@ -212,14 +214,75 @@ interface IdentityServiceOptions {
      * availability can change dynamically.
      */
     getSigner: () => Signer | null;
+    /**
+     * Optional host-backed profile lookup for the current user.
+     *
+     * Kehto does not query relays itself; hosts that already maintain kind-0
+     * metadata can provide it here without replacing the whole identity service.
+     *
+     * @param pubkey - Current signer pubkey, or "" when no signer is connected.
+     * @param message - Original identity.getProfile request envelope.
+     * @returns Profile metadata, or null when unavailable.
+     */
+    getProfile?: (pubkey: string, message: IdentityGetProfileMessage) => MaybePromise<IdentityGetProfileResultMessage['profile']>;
+    /**
+     * Optional host-backed follow-list lookup for the current user.
+     *
+     * @param pubkey - Current signer pubkey, or "" when no signer is connected.
+     * @param message - Original identity.getFollows request envelope.
+     * @returns Hex-encoded followed pubkeys.
+     */
+    getFollows?: (pubkey: string, message: IdentityGetFollowsMessage) => MaybePromise<IdentityGetFollowsResultMessage['pubkeys']>;
+    /**
+     * Optional host-backed categorized-list lookup for the current user.
+     *
+     * @param listType - Requested list category from the wire envelope.
+     * @param pubkey - Current signer pubkey, or "" when no signer is connected.
+     * @param message - Original identity.getList request envelope.
+     * @returns List entries.
+     */
+    getList?: (listType: string, pubkey: string, message: IdentityGetListMessage) => MaybePromise<IdentityGetListResultMessage['entries']>;
+    /**
+     * Optional host-backed zap receipt lookup for the current user.
+     *
+     * @param pubkey - Current signer pubkey, or "" when no signer is connected.
+     * @param message - Original identity.getZaps request envelope.
+     * @returns Zap receipts.
+     */
+    getZaps?: (pubkey: string, message: IdentityGetZapsMessage) => MaybePromise<IdentityGetZapsResultMessage['zaps']>;
+    /**
+     * Optional host-backed mute-list lookup for the current user.
+     *
+     * @param pubkey - Current signer pubkey, or "" when no signer is connected.
+     * @param message - Original identity.getMutes request envelope.
+     * @returns Hex-encoded muted pubkeys.
+     */
+    getMutes?: (pubkey: string, message: IdentityGetMutesMessage) => MaybePromise<IdentityGetMutesResultMessage['pubkeys']>;
+    /**
+     * Optional host-backed block-list lookup for the current user.
+     *
+     * @param pubkey - Current signer pubkey, or "" when no signer is connected.
+     * @param message - Original identity.getBlocked request envelope.
+     * @returns Hex-encoded blocked pubkeys.
+     */
+    getBlocked?: (pubkey: string, message: IdentityGetBlockedMessage) => MaybePromise<IdentityGetBlockedResultMessage['pubkeys']>;
+    /**
+     * Optional host-backed badge lookup for the current user.
+     *
+     * @param pubkey - Current signer pubkey, or "" when no signer is connected.
+     * @param message - Original identity.getBadges request envelope.
+     * @returns Badges awarded to the user.
+     */
+    getBadges?: (pubkey: string, message: IdentityGetBadgesMessage) => MaybePromise<IdentityGetBadgesResultMessage['badges']>;
 }
 /**
  * Create an identity service that handles NIP-5D identity.* envelope messages.
  *
  * Supports the 9 read-only identity.* request types from @napplet/nap/identity.
  * The two nostr-info queries (getPublicKey, getRelays) resolve through the
- * caller-supplied signer; the remaining 7 return default/empty payloads with
- * spec-correct envelope shapes so napplets always receive a result envelope.
+ * caller-supplied signer; the remaining read-only queries resolve through
+ * optional host providers or return default/empty payloads with spec-correct
+ * envelope shapes so napplets always receive a result envelope.
  *
  * @param options - Identity service configuration (getSigner)
  * @returns A ServiceHandler ready for runtime.registerService('identity', handler)
@@ -2338,4 +2401,4 @@ interface ManifestArchetypeInput {
  */
 declare function manifestToIntentCatalogEntry(manifest: ManifestArchetypeInput): IntentCatalogEntry;
 
-export { type AudioServiceOptions, type AudioSource, type CacheServiceOptions, type CatalogIntentResolver, type CatalogIntentResolverOptions, type ConfigSchemaValidation, type ConfigService, type ConfigServiceOptions, type CoordinatedRelayOptions, type HostCacheBridge, type HostKeyEvent, type HostKeysBridge, type HostMediaBridge, type HttpUploaderOptions, type HttpUploaderRails, type IdentityServiceOptions, type IntentArchetypeSupport, type IntentAvailability, type IntentBehavior, type IntentCandidate, type IntentCatalogEntry, type IntentHandlerPreference, type IntentOpenParams, type IntentRequest, type IntentResolver, type IntentResolverContext, type IntentResult, type IntentServiceOptions, type IntentWindowController, type KeysServiceOptions, type ManifestArchetypeInput, type MediaMetadataLike, type MediaPlaybackOwner, type MediaServiceOptions, type MediaSessionCreateOptions, type MediaSessionTarget, type MediaSourceRef, type NostrTag, type Notification, type NotificationServiceOptions, type NotifyServiceOptions, type OutboxPublishOptions, type OutboxPublishResult, type OutboxQueryOptions, type OutboxRelayPlan, type OutboxRelayPool, type OutboxResult, type OutboxRouter, type OutboxRouterSubscription, type OutboxServiceOptions, type OutboxStrategy, type OutboxSubscribeOptions, type OutboxSubscriptionSink, type OutboxTarget, type RailServerConfig, type RelayListEntry, type RelayPoolOutboxRouterOptions, type RelayPoolServiceOptions, type ResourceService, type ResourceServiceOptions, type SignEvent, type ThemeService, type ThemeServiceOptions, type UploadDimensions, type UploadRail, type UploadRequest, type UploadResult, type UploadServiceOptions, type UploadState, type UploadStatus, type Uploader, type UploaderContext, createAudioService, createBrowserMediaBridge, createCacheService, createCatalogIntentResolver, createConfigService, createCoordinatedRelay, createHttpUploader, createIdentityService, createIntentService, createKeysService, createMediaService, createNotificationService, createNotifyService, createOutboxService, createRelayPoolOutboxRouter, createRelayPoolService, createResourceService, createThemeService, createUploadService, manifestToIntentCatalogEntry };
+export { type AudioServiceOptions, type AudioSource, type CacheServiceOptions, type CatalogIntentResolver, type CatalogIntentResolverOptions, type ConfigSchemaValidation, type ConfigService, type ConfigServiceOptions, type CoordinatedRelayOptions, type HostCacheBridge, type HostKeyEvent, type HostKeysBridge, type HostMediaBridge, type HttpUploaderOptions, type HttpUploaderRails, type IdentityServiceOptions, type IntentArchetypeSupport, type IntentAvailability, type IntentBehavior, type IntentCandidate, type IntentCatalogEntry, type IntentHandlerPreference, type IntentOpenParams, type IntentRequest, type IntentResolver, type IntentResolverContext, type IntentResult, type IntentServiceOptions, type IntentWindowController, type KeysServiceOptions, type ManifestArchetypeInput, type MaybePromise, type MediaMetadataLike, type MediaPlaybackOwner, type MediaServiceOptions, type MediaSessionCreateOptions, type MediaSessionTarget, type MediaSourceRef, type NostrTag, type Notification, type NotificationServiceOptions, type NotifyServiceOptions, type OutboxPublishOptions, type OutboxPublishResult, type OutboxQueryOptions, type OutboxRelayPlan, type OutboxRelayPool, type OutboxResult, type OutboxRouter, type OutboxRouterSubscription, type OutboxServiceOptions, type OutboxStrategy, type OutboxSubscribeOptions, type OutboxSubscriptionSink, type OutboxTarget, type RailServerConfig, type RelayListEntry, type RelayPoolOutboxRouterOptions, type RelayPoolServiceOptions, type ResourceService, type ResourceServiceOptions, type SignEvent, type ThemeService, type ThemeServiceOptions, type UploadDimensions, type UploadRail, type UploadRequest, type UploadResult, type UploadServiceOptions, type UploadState, type UploadStatus, type Uploader, type UploaderContext, createAudioService, createBrowserMediaBridge, createCacheService, createCatalogIntentResolver, createConfigService, createCoordinatedRelay, createHttpUploader, createIdentityService, createIntentService, createKeysService, createMediaService, createNotificationService, createNotifyService, createOutboxService, createRelayPoolOutboxRouter, createRelayPoolService, createResourceService, createThemeService, createUploadService, manifestToIntentCatalogEntry };

package/dist/index.js

@@ -231,6 +231,184 @@ function createNotificationService(options) {
 
 // src/identity-service.ts
 var IDENTITY_SERVICE_VERSION = "1.0.0";
+function sendProviderError(send, result, fallback, err) {
+  send({
+    ...result,
+    error: err?.message ?? fallback
+  });
+}
+async function getCurrentPubkey(options) {
+  const currentSigner = options.getSigner();
+  if (!currentSigner?.getPublicKey) return "";
+  try {
+    return await currentSigner.getPublicKey() ?? "";
+  } catch {
+    return "";
+  }
+}
+function sendOptionalProviderResult(options, send, fallbackResult, errorFallback, buildResult) {
+  if (!buildResult) {
+    send(fallbackResult);
+    return;
+  }
+  Promise.resolve(getCurrentPubkey(options)).then((pubkey) => buildResult(pubkey)).then((result) => send(result)).catch((err) => sendProviderError(send, fallbackResult, errorFallback, err));
+}
+function sendIdentityError(send, id, typeBase, error) {
+  send({ type: `${typeBase}.error`, id, error });
+}
+function sendSignerError(send, id, typeBase, fallback, err) {
+  sendIdentityError(send, id, typeBase, err?.message ?? fallback);
+}
+function handleGetPublicKey(options, id, send) {
+  const signer = options.getSigner();
+  if (!signer) {
+    const result = {
+      type: "identity.getPublicKey.result",
+      id,
+      pubkey: ""
+    };
+    send(result);
+    return;
+  }
+  Promise.resolve(signer.getPublicKey?.()).then((pubkey) => {
+    const result = {
+      type: "identity.getPublicKey.result",
+      id,
+      pubkey: pubkey ?? ""
+    };
+    send(result);
+  }).catch((err) => sendSignerError(send, id, "identity.getPublicKey", "getPublicKey failed", err));
+}
+function handleGetRelays(options, id, send) {
+  const signer = options.getSigner();
+  if (!signer) {
+    sendIdentityError(send, id, "identity.getRelays", "no signer configured");
+    return;
+  }
+  Promise.resolve(signer.getRelays?.() ?? {}).then((relays) => {
+    const result = {
+      type: "identity.getRelays.result",
+      id,
+      relays
+    };
+    send(result);
+  }).catch((err) => sendSignerError(send, id, "identity.getRelays", "getRelays failed", err));
+}
+function handleReadProvider(options, id, message, send) {
+  switch (message.type) {
+    case "identity.getProfile":
+      sendOptionalProviderResult(
+        options,
+        send,
+        { type: "identity.getProfile.result", id, profile: null },
+        "getProfile failed",
+        options.getProfile ? async (pubkey) => ({
+          type: "identity.getProfile.result",
+          id,
+          profile: await options.getProfile(pubkey, message)
+        }) : void 0
+      );
+      return true;
+    case "identity.getFollows":
+      sendOptionalProviderResult(
+        options,
+        send,
+        { type: "identity.getFollows.result", id, pubkeys: [] },
+        "getFollows failed",
+        options.getFollows ? async (pubkey) => ({
+          type: "identity.getFollows.result",
+          id,
+          pubkeys: await options.getFollows(pubkey, message)
+        }) : void 0
+      );
+      return true;
+    case "identity.getList":
+      handleGetList(options, id, message, send);
+      return true;
+    case "identity.getZaps":
+      sendOptionalProviderResult(
+        options,
+        send,
+        { type: "identity.getZaps.result", id, zaps: [] },
+        "getZaps failed",
+        options.getZaps ? async (pubkey) => ({
+          type: "identity.getZaps.result",
+          id,
+          zaps: await options.getZaps(pubkey, message)
+        }) : void 0
+      );
+      return true;
+    case "identity.getMutes":
+      sendOptionalProviderResult(
+        options,
+        send,
+        { type: "identity.getMutes.result", id, pubkeys: [] },
+        "getMutes failed",
+        options.getMutes ? async (pubkey) => ({
+          type: "identity.getMutes.result",
+          id,
+          pubkeys: await options.getMutes(pubkey, message)
+        }) : void 0
+      );
+      return true;
+    case "identity.getBlocked":
+      sendOptionalProviderResult(
+        options,
+        send,
+        { type: "identity.getBlocked.result", id, pubkeys: [] },
+        "getBlocked failed",
+        options.getBlocked ? async (pubkey) => ({
+          type: "identity.getBlocked.result",
+          id,
+          pubkeys: await options.getBlocked(pubkey, message)
+        }) : void 0
+      );
+      return true;
+    case "identity.getBadges":
+      sendOptionalProviderResult(
+        options,
+        send,
+        { type: "identity.getBadges.result", id, badges: [] },
+        "getBadges failed",
+        options.getBadges ? async (pubkey) => ({
+          type: "identity.getBadges.result",
+          id,
+          badges: await options.getBadges(pubkey, message)
+        }) : void 0
+      );
+      return true;
+    default:
+      return false;
+  }
+}
+function handleGetList(options, id, message, send) {
+  sendOptionalProviderResult(
+    options,
+    send,
+    { type: "identity.getList.result", id, entries: [] },
+    "getList failed",
+    options.getList ? async (pubkey) => ({
+      type: "identity.getList.result",
+      id,
+      entries: await options.getList(message.listType, pubkey, message)
+    }) : void 0
+  );
+}
+function handleIdentityServiceMessage(options, message, send) {
+  const id = message.id ?? "";
+  switch (message.type) {
+    case "identity.getPublicKey":
+      handleGetPublicKey(options, id, send);
+      return;
+    case "identity.getRelays":
+      handleGetRelays(options, id, send);
+      return;
+    default:
+      if (!handleReadProvider(options, id, message, send)) {
+        sendIdentityError(send, id, message.type, `Unknown identity method: ${message.type}`);
+      }
+  }
+}
 function createIdentityService(options) {
   return {
     descriptor: {
@@ -239,116 +417,7 @@ function createIdentityService(options) {
       description: "NIP-5D identity NAP reference handler (9 read-only identity queries)"
     },
     handleMessage(_windowId, message, send) {
-      const id = message.id ?? "";
-      function sendError(typeBase, error) {
-        send({ type: `${typeBase}.error`, id, error });
-      }
-      function sendSignerError(typeBase, fallback, err) {
-        sendError(typeBase, err?.message ?? fallback);
-      }
-      const signer = options.getSigner();
-      switch (message.type) {
-        case "identity.getPublicKey": {
-          if (!signer) {
-            const result = {
-              type: "identity.getPublicKey.result",
-              id,
-              pubkey: ""
-            };
-            send(result);
-            return;
-          }
-          Promise.resolve(signer.getPublicKey?.()).then((pubkey) => {
-            const result = {
-              type: "identity.getPublicKey.result",
-              id,
-              pubkey: pubkey ?? ""
-            };
-            send(result);
-          }).catch((err) => sendSignerError("identity.getPublicKey", "getPublicKey failed", err));
-          return;
-        }
-        case "identity.getRelays": {
-          if (!signer) {
-            sendError("identity.getRelays", "no signer configured");
-            return;
-          }
-          Promise.resolve(signer.getRelays?.() ?? {}).then((relays) => {
-            const result = {
-              type: "identity.getRelays.result",
-              id,
-              relays
-            };
-            send(result);
-          }).catch((err) => sendSignerError("identity.getRelays", "getRelays failed", err));
-          return;
-        }
-        case "identity.getProfile": {
-          const result = {
-            type: "identity.getProfile.result",
-            id,
-            profile: null
-          };
-          send(result);
-          return;
-        }
-        case "identity.getFollows": {
-          const result = {
-            type: "identity.getFollows.result",
-            id,
-            pubkeys: []
-          };
-          send(result);
-          return;
-        }
-        case "identity.getList": {
-          const result = {
-            type: "identity.getList.result",
-            id,
-            entries: []
-          };
-          send(result);
-          return;
-        }
-        case "identity.getZaps": {
-          const result = {
-            type: "identity.getZaps.result",
-            id,
-            zaps: []
-          };
-          send(result);
-          return;
-        }
-        case "identity.getMutes": {
-          const result = {
-            type: "identity.getMutes.result",
-            id,
-            pubkeys: []
-          };
-          send(result);
-          return;
-        }
-        case "identity.getBlocked": {
-          const result = {
-            type: "identity.getBlocked.result",
-            id,
-            pubkeys: []
-          };
-          send(result);
-          return;
-        }
-        case "identity.getBadges": {
-          const result = {
-            type: "identity.getBadges.result",
-            id,
-            badges: []
-          };
-          send(result);
-          return;
-        }
-        default:
-          sendError(message.type, `Unknown identity method: ${message.type}`);
-      }
+      handleIdentityServiceMessage(options, message, send);
     },
     // Identity service has no per-window state to clean up.
     onWindowDestroyed(_windowId) {
@@ -383,7 +452,8 @@ function createRelayPoolService(options) {
           send({ type: "relay.eose", subId });
           return;
         }
-        const relayUrls = options.selectRelayTier(filters);
+        const relayHint = typeof relayMessage.relay === "string" && relayMessage.relay.length > 0 ? relayMessage.relay : void 0;
+        const relayUrls = relayHint ? [relayHint] : options.selectRelayTier(filters);
         let eoseSent = false;
         const eoseTimer = setTimeout(() => {
           if (!eoseSent) {
@@ -563,7 +633,8 @@ function createCoordinatedRelay(options) {
               maybeSendEose(subKey, subId, send);
             }
           }, timeoutMs);
-          const relayUrls = options.relayPool.selectRelayTier(filters);
+          const relayHint = typeof relayMessage.relay === "string" && relayMessage.relay.length > 0 ? relayMessage.relay : void 0;
+          const relayUrls = relayHint ? [relayHint] : options.relayPool.selectRelayTier(filters);
           tracked.relayHandle = options.relayPool.subscribe(filters, (item) => {
             if (item === "EOSE") {
               clearTimeout(tracked.eoseTimer);