Documentation
    Preparing search index...

    Interface ServiceHandler

    Handler for service-specific messages from napplets. Services receive NIP-5D NappletMessage envelopes and respond via the send callback. The same interface is used for all services regardless of what NAP domain they handle.

    const exampleHandler: ServiceHandler = {
    descriptor: { name: 'example', version: '1.0.0' },
    messageCapabilities: { 'example.ping': null },
    handleMessage(_windowId, message, send) {
    if (message.type === 'example.ping') {
    send({ type: 'example.pong' });
    }
    },
    };
    interface ServiceHandler {
        descriptor: ServiceDescriptor;
        messageCapabilities?: Readonly<
            Record<
                string,
                | "relay:read"
                | "relay:write"
                | "cache:read"
                | "cache:write"
                | "hotkey:forward"
                | "state:read"
                | "state:write"
                | "identity:read"
                | "keys:bind"
                | "keys:forward"
                | "media:control"
                | "notify:send"
                | "notify:channel"
                | "theme:read"
                | "config:read"
                | "resource:fetch"
                | "cvm:call"
                | "outbox:read"
                | "outbox:write"
                | "upload:write"
                | "intent:read"
                | "intent:write"
                | "dm:read"
                | "dm:write"
                | "fs:read"
                | "fs:write"
                | "llm:generate"
                | null,
            >,
        >;
        pushCapabilities?: Readonly<
            Record<
                string,
                | "relay:read"
                | "relay:write"
                | "cache:read"
                | "cache:write"
                | "hotkey:forward"
                | "state:read"
                | "state:write"
                | "identity:read"
                | "keys:bind"
                | "keys:forward"
                | "media:control"
                | "notify:send"
                | "notify:channel"
                | "theme:read"
                | "config:read"
                | "resource:fetch"
                | "cvm:call"
                | "outbox:read"
                | "outbox:write"
                | "upload:write"
                | "intent:read"
                | "intent:write"
                | "dm:read"
                | "dm:write"
                | "fs:read"
                | "fs:write"
                | "llm:generate"
                | null,
            >,
        >;
        handleMessage(
            windowId: string,
            message: NappletMessage,
            send: (msg: NappletMessage) => void,
        ): void;
        onCapabilityRevoked?(
            windowId: string,
            capability:
                | "relay:read"
                | "relay:write"
                | "cache:read"
                | "cache:write"
                | "hotkey:forward"
                | "state:read"
                | "state:write"
                | "identity:read"
                | "keys:bind"
                | "keys:forward"
                | "media:control"
                | "notify:send"
                | "notify:channel"
                | "theme:read"
                | "config:read"
                | "resource:fetch"
                | "cvm:call"
                | "outbox:read"
                | "outbox:write"
                | "upload:write"
                | "intent:read"
                | "intent:write"
                | "dm:read"
                | "dm:write"
                | "fs:read"
                | "fs:write"
                | "llm:generate"
                | null,
        ): void;
        onPermissionDenied?(
            windowId: string,
            message: NappletMessage,
            reason: ApprovalFailure,
            send: (message: NappletMessage) => void,
        ): void;
        onPermissionRevoked?(windowId: string): void;
        onRegistered?(context: ServiceRuntimeContext): void;
        onUnregistered?(): void;
        onWindowDestroyed?(windowId: string): void;
    }

    Hierarchy (View Summary)

    Index

    Properties

    descriptor: ServiceDescriptor

    Metadata describing this service.

    messageCapabilities?: Readonly<
        Record<
            string,
            | "relay:read"
            | "relay:write"
            | "cache:read"
            | "cache:write"
            | "hotkey:forward"
            | "state:read"
            | "state:write"
            | "identity:read"
            | "keys:bind"
            | "keys:forward"
            | "media:control"
            | "notify:send"
            | "notify:channel"
            | "theme:read"
            | "config:read"
            | "resource:fetch"
            | "cvm:call"
            | "outbox:read"
            | "outbox:write"
            | "upload:write"
            | "intent:read"
            | "intent:write"
            | "dm:read"
            | "dm:write"
            | "fs:read"
            | "fs:write"
            | "llm:generate"
            | null,
        >,
    >

    Explicit inbound types for a domain outside the built-in dispatcher. Each own key is an exact domain.action type; its value is an existing ACL capability or explicit null for no additional capability requirement. Omission keeps non-built-in services attachment-only. Built-in NAP routes ignore this map and retain their canonical capability mapping.

    Extension dispatch also requires a live, unblocked source, an explicit RuntimeAdapter.isDomainAllowed grant, and firewall admission. This map neither injects a namespace binding nor grants any capability. The handler owns payload validation and its extension's response contract.

    pushCapabilities?: Readonly<
        Record<
            string,
            | "relay:read"
            | "relay:write"
            | "cache:read"
            | "cache:write"
            | "hotkey:forward"
            | "state:read"
            | "state:write"
            | "identity:read"
            | "keys:bind"
            | "keys:forward"
            | "media:control"
            | "notify:send"
            | "notify:channel"
            | "theme:read"
            | "config:read"
            | "resource:fetch"
            | "cvm:call"
            | "outbox:read"
            | "outbox:write"
            | "upload:write"
            | "intent:read"
            | "intent:write"
            | "dm:read"
            | "dm:write"
            | "fs:read"
            | "fs:write"
            | "llm:generate"
            | null,
        >,
    >

    Shell -> napplet push types for a custom domain: exact type -> recipient ACL capability or explicit null. sendToEligibleNapplet delivers declared types to live, unblocked, isDomainAllowed-granted sources; built-ins keep their map.

    Methods

    • Handle a NIP-5D envelope from a napplet.

      Parameters

      • windowId: string

        The requesting napplet's window identifier

      • message: NappletMessage

        NappletMessage JSON envelope (e.g., { type: 'signer.signEvent', id, event })

      • send: (msg: NappletMessage) => void

        Callback to send NappletMessage responses back to the napplet

      Returns void

    • Revoke live output when this endpoint loses a capability or is blocked.

      Parameters

      • windowId: string
      • capability:
            | "relay:read"
            | "relay:write"
            | "cache:read"
            | "cache:write"
            | "hotkey:forward"
            | "state:read"
            | "state:write"
            | "identity:read"
            | "keys:bind"
            | "keys:forward"
            | "media:control"
            | "notify:send"
            | "notify:channel"
            | "theme:read"
            | "config:read"
            | "resource:fetch"
            | "cvm:call"
            | "outbox:read"
            | "outbox:write"
            | "upload:write"
            | "intent:read"
            | "intent:write"
            | "dm:read"
            | "dm:write"
            | "fs:read"
            | "fs:write"
            | "llm:generate"
            | null

      Returns void

    • Project a denied registered extension request onto its host-owned contract. Only exact declared requests reach this callback. Omission stays silent; runtime never invents extension error envelopes. Retired sources get no reply.

      Parameters

      Returns void

    • Cancel operations whose permissions changed while the source remains live. Preserve replay history and send protocol-required terminal denials where applicable. Older handlers fall back to onWindowDestroyed for cleanup.

      Parameters

      • windowId: string

      Returns void

    • Attach this handler to one runtime instance.

      Parameters

      • context: ServiceRuntimeContext

        Narrow runtime-owned identity and recipient-send access.

      Returns void

    • Release runtime attachment state when replaced, unregistered, or destroyed.

      Returns void

    • Called when a napplet window is destroyed. Services should clean up any state associated with the window. Runtime calls this at most once per session registration, whichever teardown path retires it; a later registration of the same windowId gets its own call. A handler without onPermissionRevoked also receives this as its revocation fallback.

      Parameters

      • windowId: string

        The destroyed napplet's window identifier

      Returns void