import { EventEmitter } from 'tseep'; import debug$1, { Debugger } from 'debug'; import { LRUCache } from 'typescript-lru-cache'; import { nip19 as nip19$1 } from 'nostr-tools'; import * as nip19 from 'nostr-tools/nip19'; import * as nip49 from 'nostr-tools/nip49'; function _mergeNamespaces(n, m) { m.forEach(function (e) { e && typeof e !== 'string' && !Array.isArray(e) && Object.keys(e).forEach(function (k) { if (k !== 'default' && !(k in n)) { var d = Object.getOwnPropertyDescriptor(e, k); Object.defineProperty(n, k, d.get ? d : { enumerable: true, get: function () { return e[k]; } }); } }); }); return Object.freeze(n); } declare enum NDKKind { Metadata = 0, Text = 1, RecommendRelay = 2, Contacts = 3, EncryptedDirectMessage = 4, EventDeletion = 5, Repost = 6, Reaction = 7, BadgeAward = 8, GroupChat = 9, Thread = 11, GroupReply = 12, GiftWrapSeal = 13, PrivateDirectMessage = 14, Image = 20, Video = 21, ShortVideo = 22, Story = 23, Vanish = 62, CashuWalletBackup = 375, GiftWrap = 1059, GenericRepost = 16, ChannelCreation = 40, ChannelMetadata = 41, ChannelMessage = 42, ChannelHideMessage = 43, ChannelMuteUser = 44, WikiMergeRequest = 818, GenericReply = 1111, Media = 1063, VoiceMessage = 1222, VoiceReply = 1244, DraftCheckpoint = 1234, Task = 1934, Report = 1984, Label = 1985, DVMReqTextExtraction = 5000, DVMReqTextSummarization = 5001, DVMReqTextTranslation = 5002, DVMReqTextGeneration = 5050, DVMReqImageGeneration = 5100, DVMReqTextToSpeech = 5250, DVMReqDiscoveryNostrContent = 5300, DVMReqDiscoveryNostrPeople = 5301, DVMReqTimestamping = 5900, DVMEventSchedule = 5905, DVMJobFeedback = 7000, Subscribe = 7001, Unsubscribe = 7002, SubscriptionReceipt = 7003, CashuReserve = 7373, CashuQuote = 7374, CashuToken = 7375, CashuWalletTx = 7376, GroupAdminAddUser = 9000, GroupAdminRemoveUser = 9001, GroupAdminEditMetadata = 9002, GroupAdminEditStatus = 9006, GroupAdminCreateGroup = 9007, GroupAdminRequestJoin = 9021, MuteList = 10000, PinList = 10001, RelayList = 10002, BookmarkList = 10003, CommunityList = 10004, PublicChatList = 10005, BlockRelayList = 10006, SearchRelayList = 10007, SimpleGroupList = 10009, RelayFeedList = 10012, InterestList = 10015, CashuMintList = 10019, EmojiList = 10030, DirectMessageReceiveRelayList = 10050, BlossomList = 10063, NostrWaletConnectInfo = 13194, TierList = 17000, CashuWallet = 17375, FollowSet = 30000, CategorizedPeopleList = 30000,// Deprecated but left for backwards compatibility CategorizedBookmarkList = 30001,// Deprecated but left for backwards compatibility RelaySet = 30002, CategorizedRelayList = 30002,// Deprecated but left for backwards compatibility BookmarkSet = 30003, /** * @deprecated Use ArticleCurationSet instead */ CurationSet = 30004,// Deprecated but left for backwards compatibility ArticleCurationSet = 30004, VideoCurationSet = 30005, ImageCurationSet = 30006, InterestSet = 30015, InterestsList = 30015,// Deprecated but left for backwards compatibility ProjectTemplate = 30717, EmojiSet = 30030, ModularArticle = 30040, ModularArticleItem = 30041, Wiki = 30818, Draft = 31234, Project = 31933, SubscriptionTier = 37001, EcashMintRecommendation = 38000, CashuMintAnnouncement = 38172, FedimintMintAnnouncement = 38173, P2POrder = 38383, CollaborativeEvent = 39382, HighlightSet = 39802, CategorizedHighlightList = 39802,// Deprecated but left for backwards compatibility Nutzap = 9321, ZapRequest = 9734, Zap = 9735, Highlight = 9802, ClientAuth = 22242, NostrWalletConnectReq = 23194, NostrWalletConnectRes = 23195, NostrConnect = 24133, BlossomUpload = 24242, HttpAuth = 27235, ProfileBadge = 30008, BadgeDefinition = 30009, MarketStall = 30017, MarketProduct = 30018, Article = 30023, AppSpecificData = 30078, Classified = 30402, HorizontalVideo = 34235, VerticalVideo = 34236, GroupMetadata = 39000,// NIP-29 GroupAdmins = 39001,// NIP-29 GroupMembers = 39002,// NIP-29 FollowPack = 39089, MediaFollowPack = 39092, AppRecommendation = 31989, AppHandler = 31990 } declare const NDKListKinds: NDKKind[]; /** * NIP-45 COUNT with HyperLogLog (HLL) support * * This module provides support for COUNT requests with HLL cardinality estimation * as specified in NIP-45. * * HLL allows relays to provide approximate unique counts that can be merged * across multiple relays without double-counting. */ /** * The number of HLL registers (256 as per NIP-45) */ declare const HLL_REGISTER_COUNT = 256; /** * Represents an HLL (HyperLogLog) data structure for cardinality estimation. * Contains 256 uint8 registers as specified in NIP-45. */ declare class NDKCountHll { /** * The 256 uint8 registers used for HLL estimation */ readonly registers: Uint8Array; constructor(registers?: Uint8Array); /** * Creates an NDKCountHll from a hex-encoded string (512 characters). * Each register is a uint8 value encoded as 2 hex characters. * * @param hex - The hex string (512 characters = 256 bytes) * @returns A new NDKCountHll instance * @throws Error if the hex string is invalid */ static fromHex(hex: string): NDKCountHll; /** * Converts the HLL registers to a hex-encoded string. * * @returns The hex string representation (512 characters) */ toHex(): string; /** * Merges this HLL with another HLL by taking the maximum value for each register. * This is the standard HLL merge operation that allows combining counts * from multiple relays without double-counting. * * @param other - The other HLL to merge with * @returns A new NDKCountHll with the merged registers */ merge(other: NDKCountHll): NDKCountHll; /** * Merges multiple HLLs by taking the maximum value for each register. * * @param hlls - Array of HLLs to merge * @returns A new NDKCountHll with the merged registers */ static merge(hlls: NDKCountHll[]): NDKCountHll; /** * Estimates the cardinality (unique count) using the HyperLogLog algorithm. * * Uses the standard HLL formula with bias correction for small and large cardinalities. * * @returns The estimated unique count */ estimate(): number; /** * Checks if this HLL is empty (all registers are zero). * * @returns True if all registers are zero */ isEmpty(): boolean; /** * Creates a copy of this HLL. * * @returns A new NDKCountHll with the same register values */ clone(): NDKCountHll; } /** * Result of a COUNT request, including optional HLL data. */ interface NDKCountResult { /** * The count value returned by the relay. * This is the exact count if HLL is not available, * or an approximate count if HLL is used. */ count: number; /** * The HLL data if returned by the relay. * Can be used to merge counts from multiple relays. */ hll?: NDKCountHll; } /** * Aggregated result from multiple relays for a COUNT request. */ interface NDKAggregatedCountResult { /** * The best estimate of the count. * If HLL data is available from multiple relays, this is computed from the merged HLL. * Otherwise, it's the maximum count from all relays. */ count: number; /** * The merged HLL from all relays that returned HLL data. * Can be used for further aggregation or analysis. */ mergedHll?: NDKCountHll; /** * Individual results from each relay. */ relayResults: Map; } /** * Options for count requests. */ interface NDKCountOptions { /** * Custom ID for the count request. */ id?: string; /** * Timeout in milliseconds for the count request. * @default 5000 */ timeout?: number; } /** * NDKUserProfile represents a user's kind 0 profile metadata */ interface NDKUserProfile { [key: string]: string | number | undefined; created_at?: number; name?: string; displayName?: string; /** * @deprecated Use picture instead */ image?: string; picture?: string; banner?: string; bio?: string; nip05?: string; lud06?: string; lud16?: string; about?: string; website?: string; profileEvent?: string; } declare function profileFromEvent(event: NDKEvent): NDKUserProfile; declare function serializeProfile(profile: NDKUserProfile): string; type Hexpubkey = string; type Npub = string; type ProfilePointer = { pubkey: string; relays?: string[]; nip46?: string[]; }; type EventPointer = { id: string; relays?: string[]; author?: string; kind?: number; }; interface NDKUserParams { npub?: Npub; hexpubkey?: Hexpubkey; pubkey?: Hexpubkey; nip05?: string; relayUrls?: string[]; nip46Urls?: string[]; nprofile?: string; } /** * Represents a pubkey. */ declare class NDKUser { ndk: NDK | undefined; profile?: NDKUserProfile; profileEvent?: NDKEvent; private _npub?; private _pubkey?; relayUrls: string[]; readonly nip46Urls: string[]; constructor(opts: NDKUserParams); get npub(): string; get nprofile(): string; set npub(npub: Npub); /** * Get the user's pubkey * @returns {string} The user's pubkey */ get pubkey(): string; /** * Set the user's pubkey * @param pubkey {string} The user's pubkey */ set pubkey(pubkey: string); /** * Equivalent to NDKEvent.filters(). * @returns {NDKFilter} */ filter(): NDKFilter; /** * Gets NIP-57 and NIP-61 information that this user has signaled * * @param getAll {boolean} Whether to get all zap info or just the first one */ getZapInfo(timeoutMs?: number): Promise>; /** * Instantiate an NDKUser from a NIP-05 string * @param nip05Id {string} The user's NIP-05 * @param ndk {NDK} An NDK instance * @param skipCache {boolean} Whether to skip the cache or not * @returns {NDKUser | undefined} An NDKUser if one is found for the given NIP-05, undefined otherwise. */ static fromNip05(nip05Id: string, ndk: NDK, skipCache?: boolean): Promise; /** * Fetch a user's profile * @param opts {NDKSubscriptionOptions} A set of NDKSubscriptionOptions * @param storeProfileEvent {boolean} Whether to store the profile event or not * @returns User Profile */ fetchProfile(opts?: NDKSubscriptionOptions, storeProfileEvent?: boolean): Promise; /** * Returns a set of users that this user follows. * * @deprecated Use followSet instead */ follows: (opts?: NDKSubscriptionOptions | undefined, outbox?: boolean | undefined, kind?: number | undefined) => Promise>; /** * Returns a set of pubkeys that this user follows. * * @param opts - NDKSubscriptionOptions * @param outbox - boolean * @param kind - number */ followSet(opts?: NDKSubscriptionOptions, outbox?: boolean, kind?: number): Promise>; /** @deprecated Use referenceTags instead. */ /** * Get the tag that can be used to reference this user in an event * @returns {NDKTag} an NDKTag */ tagReference(): NDKTag; /** * Get the tags that can be used to reference this user in an event * @returns {NDKTag[]} an array of NDKTag */ referenceTags(marker?: string): NDKTag[]; /** * Publishes the current profile. */ publish(): Promise; /** * Add one or more follows to this user's contact list * * @param newFollow {NDKUser | Hexpubkey | Array} The user(s) to follow * @param currentFollowList {Set} The current follow list * @param kind {NDKKind} The kind to use for this contact list (defaults to `3`) * @returns {Promise} True if any follows were added, false if all already exist */ follow(newFollow: NDKUser | Hexpubkey | (NDKUser | Hexpubkey)[], currentFollowList?: Set, kind?: NDKKind): Promise; /** * Remove one or more follows from this user's contact list * * @param user {NDKUser | Hexpubkey | Array} The user(s) to unfollow * @param currentFollowList {Set} The current follow list * @param kind {NDKKind} The kind to use for this contact list (defaults to `3`) * @returns The relays where the follow list was published or false if none were found */ unfollow(user: NDKUser | Hexpubkey | (NDKUser | Hexpubkey)[], currentFollowList?: Set, kind?: NDKKind): Promise | boolean>; /** * Validate a user's NIP-05 identifier (usually fetched from their kind:0 profile data) * * @param nip05Id The NIP-05 string to validate * @returns {Promise} True if the NIP-05 is found and matches this user's pubkey, * False if the NIP-05 is found but doesn't match this user's pubkey, * null if the NIP-05 isn't found on the domain or we're unable to verify (because of network issues, etc.) */ validateNip05(nip05Id: string): Promise; } /** * Interface for NDK signers. */ /** * Interface for a serialized signer payload */ interface NDKSignerPayload { type: string; payload: string; } interface NDKSigner { /** * Synchronously get the public key of the signer. * @throws {Error} "Not ready" when the signer is not ready to provide a pubkey synchronously (e.g., NIP-07 or NIP-46 signers) * @returns The public key in hex format */ get pubkey(): string; /** * Blocks until the signer is ready and returns the associated NDKUser. * @returns A promise that resolves to the NDKUser instance. */ blockUntilReady(): Promise; /** * Getter for the user property. * @returns A promise that resolves to the NDKUser instance. */ user(): Promise; get userSync(): NDKUser; /** * Signs the given Nostr event. * @param event - The Nostr event to be signed. * @returns A promise that resolves to the signature of the signed event. */ sign(event: NostrEvent): Promise; /** * Getter for the preferred relays. * @returns A promise containing a simple map of preferred relays and their read/write policies. */ relays?(ndk?: NDK): Promise; /** * Determine the types of encryption (by nip) that this signer can perform. * Implementing classes SHOULD return a value even for legacy (only nip04) third party signers. * @nip Optionally returns an array with single supported nip or empty, to check for truthy or falsy. * @return A promised list of any (or none) of these strings ['nip04', 'nip44'] */ encryptionEnabled?(scheme?: NDKEncryptionScheme): Promise; /** * Encrypts the given Nostr event for the given recipient. * Implementing classes SHOULD equate legacy (only nip04) to nip == `nip04` || undefined * @param recipient - The recipient (pubkey or conversationKey) of the encrypted value. * @param value - The value to be encrypted. * @param nip - which NIP is being implemented ('nip04', 'nip44') */ encrypt(recipient: NDKUser, value: string, scheme?: NDKEncryptionScheme): Promise; /** * Decrypts the given value. * Implementing classes SHOULD equate legacy (only nip04) to nip == `nip04` || undefined * @param sender - The sender (pubkey or conversationKey) of the encrypted value * @param value - The value to be decrypted * @param scheme - which NIP is being implemented ('nip04', 'nip44', 'nip49') */ decrypt(sender: NDKUser, value: string, scheme?: NDKEncryptionScheme): Promise; /** * Serializes the signer's essential data into a storable format. * @returns A JSON string containing the type and payload. */ toPayload(): string; } /** * Interface for Signer classes that support static deserialization */ interface NDKSignerStatic { /** * Deserializes the signer from a payload string. * @param payload The JSON string obtained from toPayload(). * @param ndk Optional NDK instance, required by some signers (e.g., NIP-46). * @returns An instance of the specific signer class. */ fromPayload(payload: string, ndk?: NDK): Promise; } type NDKPoolStats = { total: number; connected: number; disconnected: number; connecting: number; }; /** * Handles connections to all relays. A single pool should be used per NDK instance. * * @emit connecting - Emitted when a relay in the pool is connecting. * @emit connect - Emitted when all relays in the pool are connected, or when the specified timeout has elapsed, and some relays are connected. * @emit notice - Emitted when a relay in the pool sends a notice. * @emit flapping - Emitted when a relay in the pool is flapping. * @emit relay:connect - Emitted when a relay in the pool connects. * @emit relay:ready - Emitted when a relay in the pool is ready to serve requests. * @emit relay:disconnect - Emitted when a relay in the pool disconnects. */ declare class NDKPool extends EventEmitter<{ notice: (relay: NDKRelay, notice: string) => void; flapping: (relay: NDKRelay) => void; connect: () => void; "relay:connecting": (relay: NDKRelay) => void; /** * Emitted when a relay in the pool connects. * @param relay - The relay that connected. */ "relay:connect": (relay: NDKRelay) => void; "relay:ready": (relay: NDKRelay) => void; "relay:disconnect": (relay: NDKRelay) => void; "relay:auth": (relay: NDKRelay, challenge: string) => void; "relay:authed": (relay: NDKRelay) => void; }> { private _relays; private status; autoConnectRelays: Set; private debug; private temporaryRelayTimers; private flappingRelays; private backoffTimes; private ndk; private disconnectionTimes; private systemEventDetector?; /** * @param relayUrls - The URLs of the relays to connect to. * @param ndk - The NDK instance. * @param opts - Options for the pool. */ constructor(relayUrls: WebSocket["url"][], ndk: NDK, { debug, name, }?: { debug?: debug$1.Debugger; name?: string; }); get relays(): Map; set relayUrls(urls: WebSocket["url"][]); private _name; get name(): string; set name(name: string); /** * Adds a relay to the pool, and sets a timer to remove it if it is not used within the specified time. * @param relay - The relay to add to the pool. * @param removeIfUnusedAfter - The time in milliseconds to wait before removing the relay from the pool after it is no longer used. */ useTemporaryRelay(relay: NDKRelay, removeIfUnusedAfter?: number, filters?: NDKFilter[] | string): void; /** * Adds a relay to the pool. * * @param relay - The relay to add to the pool. * @param connect - Whether or not to connect to the relay. */ addRelay(relay: NDKRelay, connect?: boolean): void; /** * Removes a relay from the pool. * @param relayUrl - The URL of the relay to remove. * @returns {boolean} True if the relay was removed, false if it was not found. */ removeRelay(relayUrl: string): boolean; /** * Checks whether a relay is already connected in the pool. */ isRelayConnected(url: WebSocket["url"]): boolean; /** * Fetches a relay from the pool, or creates a new one if it does not exist. * * New relays will be attempted to be connected. */ getRelay(url: WebSocket["url"], connect?: boolean, temporary?: boolean, filters?: NDKFilter[]): NDKRelay; private handleRelayConnect; private handleRelayReady; /** * Attempts to establish a connection to each relay in the pool. * * @async * @param {number} [timeoutMs] - Optional timeout in milliseconds for each connection attempt. * @returns {Promise} A promise that resolves when all connection attempts have completed. * @throws {Error} If any of the connection attempts result in an error or timeout. */ connect(timeoutMs?: number): Promise; private checkOnFlappingRelays; /** * Records when a relay disconnects to detect system-wide events */ private recordDisconnection; /** * Checks if multiple relays disconnected simultaneously, indicating a system event */ private checkForSystemWideDisconnection; /** * Handles system-wide reconnection (e.g., after sleep/wake or network change) */ private handleSystemWideReconnection; private handleFlapping; size(): number; /** * Returns the status of each relay in the pool. * @returns {NDKPoolStats} An object containing the number of relays in each status. */ stats(): NDKPoolStats; connectedRelays(): NDKRelay[]; permanentAndConnectedRelays(): NDKRelay[]; /** * Get a list of all relay urls in the pool. */ urls(): string[]; } /** * NDKAuthPolicies are functions that are called when a relay requests authentication * so that you can define a behavior for your application. * * @param relay The relay that requested authentication. * @param challenge The challenge that the relay sent. */ type NDKAuthPolicy = (relay: NDKRelay, challenge: string) => Promise; /** * This policy will disconnect from relays that request authentication. */ declare function disconnect(pool: NDKPool, debug?: debug.Debugger): (relay: NDKRelay) => Promise; type ISignIn = { ndk?: NDK; signer?: NDKSigner; debug?: debug.Debugger; }; /** * Uses the signer to sign an event and then authenticate with the relay. * If no signer is provided the NDK signer will be used. * If none is not available it will wait for one to be ready. */ declare function signIn({ ndk, signer, debug }?: ISignIn): (relay: NDKRelay, challenge: string) => Promise; declare const NDKRelayAuthPolicies: { disconnect: typeof disconnect; signIn: typeof signIn; }; type NDKFilterFingerprint = string; /** * Creates a fingerprint for this filter * * This a deterministic association of the filters * used in a filters. When the combination of filters makes it * possible to group them, the fingerprint is used to group them. * * The different filters in the array are differentiated so that * filters can only be grouped with other filters that have the same signature * * The calculated group ID uses a + prefix to avoid grouping subscriptions * that intend to close immediately after EOSE and those that are probably * going to be kept open. * * @returns The fingerprint, or undefined if the filters are not groupable. */ declare function filterFingerprint(filters: NDKFilter[], closeOnEose: boolean): NDKFilterFingerprint | undefined; /** * Go through all the passed filters, which should be * relatively similar, and merge them. */ declare function mergeFilters(filters: NDKFilter[]): NDKFilter[]; type NDKSubscriptionId = string; /** * This class monitors active subscriptions. */ declare class NDKSubscriptionManager { subscriptions: Map; seenEvents: LRUCache; constructor(); add(sub: NDKSubscription): void; seenEvent(eventId: NDKEventId, relay: NDKRelay): void; /** * Whenever an event comes in, this function is called. * This function matches the received event against all the * known (i.e. active) NDKSubscriptions, and if it matches, * it sends the event to the subscription. * * This is the single place in the codebase that matches * incoming events with parties interested in the event. * * This is also what allows for reactivity in NDK apps, such that * whenever an active subscription receives an event that some * other active subscription would want to receive, both receive it. * * TODO This also allows for subscriptions that overlap in meaning * to be collapsed into one. * * I.e. if a subscription with filter: kinds: [1], authors: [alice] * is created and EOSEs, and then a subsequent subscription with * kinds: [1], authors: [alice] is created, once the second subscription * EOSEs we can safely close it, increment its refCount and close it, * and when the first subscription receives a new event from Alice this * code will make the second subscription receive the event even though * it has no active subscription on a relay. * @param event Raw event received from a relay * @param relay Relay that sent the event * @param optimisticPublish Whether the event is coming from an optimistic publish */ dispatchEvent(event: NostrEvent, relay?: NDKRelay, optimisticPublish?: boolean): void; } type Item = { subscription: NDKSubscription; filters: NDKFilter[]; }; declare enum NDKRelaySubscriptionStatus { INITIAL = 0, /** * The subscription is pending execution. */ PENDING = 1, /** * The subscription is waiting for the relay to be ready. */ WAITING = 2, /** * The subscription is currently running. */ RUNNING = 3, CLOSED = 4 } /** * Groups together a number of NDKSubscriptions (as created by the user), * filters (as computed internally), executed, or to be executed, within * a single specific relay. */ declare class NDKRelaySubscription { fingerprint: NDKFilterFingerprint; items: Map; topSubManager: NDKSubscriptionManager; debug: debug.Debugger; /** * Tracks the status of this REQ. */ status: NDKRelaySubscriptionStatus; onClose?: (sub: NDKRelaySubscription) => void; private relay; /** * Whether this subscription has reached EOSE. */ private eosed; /** * Timeout at which this subscription will * start executing. */ private executionTimer?; /** * Track the time at which this subscription will fire. */ private fireTime?; /** * The delay type that the current fireTime was calculated with. */ private delayType?; /** * The filters that have been executed. */ executeFilters?: NDKFilter[]; readonly id: string; /** * * @param fingerprint The fingerprint of this subscription. */ constructor(relay: NDKRelay, fingerprint: NDKFilterFingerprint | null, topSubManager: NDKSubscriptionManager); private _subId?; get subId(): string; private subIdParts; private addSubIdPart; addItem(subscription: NDKSubscription, filters: NDKFilter[]): void; /** * A subscription has been closed, remove it from the list of items. * @param subscription */ removeItem(subscription: NDKSubscription): void; private close; cleanup(): void; private evaluateExecutionPlan; private schedule; private executeOnRelayReady; private finalizeSubId; private reExecuteAfterAuth; private execute; onstart(): void; onevent(event: NostrEvent): void; oneose(subId: string): void; onclose(_reason?: string): void; onclosed(reason?: string): void; /** * Grabs the filters from all the subscriptions * and merges them into a single filter. */ private compileFilters; } declare class NDKRelayConnectivity { private ndkRelay; private ws?; private _status; private timeoutMs?; private connectedAt?; private _connectionStats; private debug; netDebug?: NDKNetDebug; private connectTimeout; private reconnectTimeout; private ndk?; openSubs: Map; private openCountRequests; private openEventPublishes; private pendingAuthPublishes; private serial; baseEoseTimeout: number; private keepalive?; private wsStateMonitor?; private sleepDetector?; private lastSleepCheck; private lastMessageSent; private wasIdle; constructor(ndkRelay: NDKRelay, ndk?: NDK); /** * Sets up keepalive, WebSocket state monitoring, and sleep detection */ private setupMonitoring; /** * Handles detection of a stale connection by cleaning up and triggering reconnection. */ private handleStaleConnection; /** * Handles possible system wake event */ private handlePossibleWake; /** * Resets the reconnection state for system-wide events * Used by NDKPool when detecting system sleep/wake */ resetReconnectionState(): void; /** * Connects to the NDK relay and handles the connection lifecycle. * * This method attempts to establish a WebSocket connection to the NDK relay specified in the `ndkRelay` object. * If the connection is successful, it updates the connection statistics, sets the connection status to `CONNECTED`, * and emits `connect` and `ready` events on the `ndkRelay` object. * * If the connection attempt fails, it handles the error by either initiating a reconnection attempt or emitting a * `delayed-connect` event on the `ndkRelay` object, depending on the `reconnect` parameter. * * @param timeoutMs - The timeout in milliseconds for the connection attempt. If not provided, the default timeout from the `ndkRelay` object is used. * @param reconnect - Indicates whether a reconnection should be attempted if the connection fails. Defaults to `true`. * @returns A Promise that resolves when the connection is established, or rejects if the connection fails. */ connect(timeoutMs?: number, reconnect?: boolean): Promise; /** * Disconnects the WebSocket connection to the NDK relay. * This method sets the connection status to `NDKRelayStatus.DISCONNECTING`, * attempts to close the WebSocket connection, and sets the status to * `NDKRelayStatus.DISCONNECTED` if the disconnect operation fails. */ disconnect(): void; /** * Handles the error that occurred when attempting to connect to the NDK relay. * If `reconnect` is `true`, this method will initiate a reconnection attempt. * Otherwise, it will emit a `delayed-connect` event on the `ndkRelay` object, * indicating that a reconnection should be attempted after a delay. * * @param reconnect - Indicates whether a reconnection should be attempted. */ onConnectionError(reconnect: boolean): void; /** * Handles the connection event when the WebSocket connection is established. * This method is called when the WebSocket connection is successfully opened. * It clears any existing connection and reconnection timeouts, updates the connection statistics, * sets the connection status to `CONNECTED`, and emits `connect` and `ready` events on the `ndkRelay` object. */ private onConnect; /** * Handles the disconnection event when the WebSocket connection is closed. * This method is called when the WebSocket connection is successfully closed. * It updates the connection statistics, sets the connection status to `DISCONNECTED`, * initiates a reconnection attempt if we didn't disconnect ourselves, * and emits a `disconnect` event on the `ndkRelay` object. */ private onDisconnect; /** * Handles incoming messages from the NDK relay WebSocket connection. * This method is called whenever a message is received from the relay. * It parses the message data and dispatches the appropriate handling logic based on the message type. * * @param event - The MessageEvent containing the received message data. */ private onMessage; /** * Handles an authentication request from the NDK relay. * * If an authentication policy is configured, it will be used to authenticate the connection. * Otherwise, the `auth` event will be emitted to allow the application to handle the authentication. * * @param challenge - The authentication challenge provided by the NDK relay. */ private onAuthRequested; /** * Handles errors that occur on the WebSocket connection to the relay. * @param error - The error or event that occurred. */ private onError; /** * Gets the current status of the NDK relay connection. * @returns {NDKRelayStatus} The current status of the NDK relay connection. */ get status(): NDKRelayStatus; /** * Checks if the NDK relay connection is currently available. * @returns {boolean} `true` if the relay connection is in the `CONNECTED` status, `false` otherwise. */ isAvailable(): boolean; /** * Checks if the NDK relay connection is flapping, which means the connection is rapidly * disconnecting and reconnecting. This is determined by analyzing the durations of the * last three connection attempts. If the standard deviation of the durations is less * than 1000 milliseconds, the connection is considered to be flapping. * * @returns {boolean} `true` if the connection is flapping, `false` otherwise. */ private isFlapping; /** * Handles a notice received from the NDK relay. * If the notice indicates the relay is complaining (e.g. "too many" or "maximum"), * the method disconnects from the relay and attempts to reconnect after a 2-second delay. * A debug message is logged with the relay URL and the notice text. * The "notice" event is emitted on the ndkRelay instance with the notice text. * * @param notice - The notice text received from the NDK relay. */ private onNotice; /** * Attempts to reconnect to the NDK relay after a connection is lost. * This function is called recursively to handle multiple reconnection attempts. * It checks if the relay is flapping and emits a "flapping" event if so. * It then calculates a delay before the next reconnection attempt based on the number of previous attempts. * The function sets a timeout to execute the next reconnection attempt after the calculated delay. * If the maximum number of reconnection attempts is reached, a debug message is logged. * * @param attempt - The current attempt number (default is 0). */ private handleReconnection; /** * Sends a message to the NDK relay if the connection is in the CONNECTED state and the WebSocket is open. * If the connection is not in the CONNECTED state or the WebSocket is not open, logs a debug message and throws an error. * * @param message - The message to send to the NDK relay. * @throws {Error} If attempting to send on a closed relay connection. */ send(message: string): Promise; /** * Authenticates the NDK event by sending it to the NDK relay and returning a promise that resolves with the result. * * @param event - The NDK event to authenticate. * @returns A promise that resolves with the authentication result. */ private auth; /** * Clears all pending publish promises by rejecting them with the provided error. * This is called on disconnection to prevent memory leaks and ensure promises * don't hang indefinitely. * @param error The error to reject the promises with */ private clearPendingPublishes; /** * Retries all pending publishes that failed due to auth-required. * Called after successful authentication. */ private retryPendingAuthPublishes; /** * Rejects all pending publishes that failed due to auth-required. * Called when authentication fails. */ private rejectPendingAuthPublishes; /** * Publishes an NDK event to the relay and returns a promise that resolves with the result. * * @param event - The NDK event to publish. * @returns A promise that resolves with the result of the event publication. * @throws {Error} If attempting to publish on a closed relay connection. */ publish(event: NostrEvent): Promise; /** * Counts the number of events that match the provided filters. * * @param filters - The filters to apply to the count request. * @param params - An optional object containing a custom id for the count request. * @returns A promise that resolves with the count result including optional HLL data. * @throws {Error} If attempting to send the count request on a closed relay connection. */ count(filters: NDKFilter[], params: { id?: string | null; }): Promise; close(subId: string, reason?: string): void; /** * Subscribes to the NDK relay with the provided filters and parameters. * * @param filters - The filters to apply to the subscription. * @param params - The subscription parameters, including an optional custom id. * @returns A new NDKRelaySubscription instance. */ req(relaySub: NDKRelaySubscription): void; /** * Utility functions to update the connection stats. */ private updateConnectionStats; /** Returns the connection stats. */ get connectionStats(): NDKRelayConnectionStats; /** Returns the relay URL */ get url(): WebSocket["url"]; get connected(): boolean; } /** * NIP-11: Relay Information Document * https://github.com/nostr-protocol/nips/blob/master/11.md */ interface NDKRelayInformation { name?: string; description?: string; banner?: string; icon?: string; pubkey?: string; contact?: string; supported_nips?: number[]; software?: string; version?: string; privacy_policy?: string; terms_of_service?: string; limitation?: { max_message_length?: number; max_subscriptions?: number; max_subid_length?: number; max_limit?: number; max_event_tags?: number; max_content_length?: number; min_pow_difficulty?: number; auth_required?: boolean; payment_required?: boolean; restricted_writes?: boolean; created_at_lower_limit?: number; created_at_upper_limit?: number; default_limit?: number; }; retention?: Array<{ kinds?: Array; time?: number | null; count?: number; }>; relay_countries?: string[]; language_tags?: string[]; tags?: string[]; posting_policy?: string; payments_url?: string; fees?: { admission?: Array<{ amount: number; unit: string; }>; subscription?: Array<{ amount: number; unit: string; period: number; }>; publication?: Array<{ kinds?: number[]; amount: number; unit: string; }>; }; [key: string]: unknown; } /** * Fetches NIP-11 relay information document from a relay. * * @param relayUrl The WebSocket URL of the relay (e.g., "wss://relay.example.com") * @returns The relay information document * @throws Error if the fetch fails or returns invalid JSON */ declare function fetchRelayInformation(relayUrl: string): Promise; type NDKRelayScore = number; /** * SignatureVerificationStats - A class to track and report signature verification statistics * for all relays in an NDK instance. */ declare class SignatureVerificationStats { private ndk; private debug; private intervalId; private intervalMs; /** * Creates a new SignatureVerificationStats instance * * @param ndk - The NDK instance to track stats for * @param intervalMs - How often to print stats (in milliseconds) */ constructor(ndk: NDK, intervalMs?: number); /** * Start tracking and reporting signature verification statistics */ start(): void; /** * Stop tracking and reporting signature verification statistics */ stop(): void; /** * Report current signature verification statistics for all relays */ reportStats(): void; /** * Collect statistics from all relays */ private collectStats; } /** * Create and start a signature verification stats tracker for the given NDK instance * * @param ndk - The NDK instance to track stats for * @param intervalMs - How often to print stats (in milliseconds) * @returns The created SignatureVerificationStats instance */ declare function startSignatureVerificationStats(ndk: NDK, intervalMs?: number): SignatureVerificationStats; /** * The subscription manager of an NDKRelay is in charge of orchestrating the subscriptions * that are created and closed in a given relay. * * The manager is responsible for: * * restarting subscriptions when they are unexpectedly closed * * scheduling subscriptions that are received before the relay is connected * * grouping similar subscriptions to be compiled into individual REQs */ declare class NDKRelaySubscriptionManager { private relay; subscriptions: Map; private generalSubManager; /** * @param relay - The relay instance. * @param generalSubManager - The subscription manager instance. */ constructor(relay: NDKRelay, generalSubManager: NDKSubscriptionManager); /** * Adds a subscription to the manager. */ addSubscription(sub: NDKSubscription, filters: NDKFilter[]): void; createSubscription(_sub: NDKSubscription, _filters: NDKFilter[], fingerprint?: NDKFilterFingerprint): NDKRelaySubscription; private onRelaySubscriptionClose; } /** @deprecated Use `WebSocket['url']` instead. */ type NDKRelayUrl = WebSocket["url"]; /** * Protocol handler function type for handling custom relay messages. * @param relay The relay that received the message * @param message The parsed message array from the relay */ type NDKProtocolHandler = (relay: NDKRelay, message: unknown[]) => void; declare enum NDKRelayStatus { DISCONNECTING = 0,// 0 DISCONNECTED = 1,// 1 RECONNECTING = 2,// 2 FLAPPING = 3,// 3 CONNECTING = 4,// 4 CONNECTED = 5,// 5 AUTH_REQUESTED = 6,// 6 AUTHENTICATING = 7,// 7 AUTHENTICATED = 8 } interface NDKRelayConnectionStats { /** * The number of times a connection has been attempted. */ attempts: number; /** * The number of times a connection has been successfully established. */ success: number; /** * The durations of the last 100 connections in milliseconds. */ durations: number[]; /** * The time the current connection was established in milliseconds. */ connectedAt?: number; /** * Timestamp of the next reconnection attempt. */ nextReconnectAt?: number; /** * Signature validation ratio for this relay. * @see NDKRelayOptions.validationRatio */ validationRatio?: number; } /** * The NDKRelay class represents a connection to a relay. * * @emits NDKRelay#connect * @emits NDKRelay#ready * @emits NDKRelay#disconnect * @emits NDKRelay#notice * @emits NDKRelay#event * @emits NDKRelay#published when an event is published to the relay * @emits NDKRelay#publish:failed when an event fails to publish to the relay * @emits NDKRelay#eose when the relay has reached the end of stored events * @emits NDKRelay#auth when the relay requires authentication * @emits NDKRelay#authed when the relay has authenticated * @emits NDKRelay#delayed-connect when the relay will wait before reconnecting */ declare class NDKRelay extends EventEmitter<{ connect: () => void; ready: () => void; /** * Emitted when the relay has reached the end of stored events. */ disconnect: () => void; flapping: (stats: NDKRelayConnectionStats) => void; notice: (notice: string) => void; auth: (challenge: string) => void; authed: () => void; "auth:failed": (error: Error) => void; published: (event: NDKEvent) => void; "publish:failed": (event: NDKEvent, error: Error) => void; "delayed-connect": (delayInMs: number) => void; }> { readonly url: WebSocket["url"]; readonly scores: Map; connectivity: NDKRelayConnectivity; subs: NDKRelaySubscriptionManager; private publisher; authPolicy?: NDKAuthPolicy; /** * Protocol handlers for custom relay message types (e.g., NEG-OPEN, NEG-MSG). * Allows external packages to handle non-standard relay messages. */ private protocolHandlers; /** * Cached relay information from NIP-11. */ private _relayInfo?; /** * The lowest validation ratio this relay can reach. */ lowestValidationRatio?: number; /** * Current validation ratio this relay is targeting. */ targetValidationRatio?: number; validationRatioFn?: (relay: NDKRelay, validatedCount: number, nonValidatedCount: number) => number; /** * This tracks events that have been seen by this relay * with a valid signature. */ validatedEventCount: number; /** * This tracks events that have been seen by this relay * but have not been validated. */ nonValidatedEventCount: number; /** * Whether this relay is trusted. * * Trusted relay's events do not get their signature verified. */ trusted: boolean; complaining: boolean; readonly debug: debug$1.Debugger; static defaultValidationRatioUpdateFn: (relay: NDKRelay, validatedCount: number, _nonValidatedCount: number) => number; constructor(url: WebSocket["url"], authPolicy: NDKAuthPolicy | undefined, ndk: NDK); private updateValidationRatio; get status(): NDKRelayStatus; get connectionStats(): NDKRelayConnectionStats; /** * Connects to the relay. */ connect(timeoutMs?: number, reconnect?: boolean): Promise; /** * Disconnects from the relay. */ disconnect(): void; /** * Queues or executes the subscription of a specific set of filters * within this relay. * * @param subscription NDKSubscription this filters belong to. * @param filters Filters to execute */ subscribe(subscription: NDKSubscription, filters: NDKFilter[]): void; /** * Publishes an event to the relay with an optional timeout. * * If the relay is not connected, the event will be published when the relay connects, * unless the timeout is reached before the relay connects. * * @param event The event to publish * @param timeoutMs The timeout for the publish operation in milliseconds * @returns A promise that resolves when the event has been published or rejects if the operation times out */ publish(event: NDKEvent, timeoutMs?: number): Promise; referenceTags(): NDKTag[]; addValidatedEvent(): void; addNonValidatedEvent(): void; /** * The current validation ratio this relay has achieved. */ get validationRatio(): number; shouldValidateEvent(): boolean; get connected(): boolean; req: (relaySub: NDKRelaySubscription) => void; close: (subId: string) => void; /** * Registers a protocol handler for a specific message type. * This allows external packages to handle custom relay messages (e.g., NIP-77 NEG-* messages). * * @param messageType The message type to handle (e.g., "NEG-OPEN", "NEG-MSG") * @param handler The function to call when a message of this type is received * * @example * ```typescript * relay.registerProtocolHandler('NEG-MSG', (relay, message) => { * console.log('Received NEG-MSG:', message); * }); * ``` */ registerProtocolHandler(messageType: string, handler: NDKProtocolHandler): void; /** * Unregisters a protocol handler for a specific message type. * * @param messageType The message type to stop handling */ unregisterProtocolHandler(messageType: string): void; /** * Checks if a protocol handler is registered for a message type. * This is used internally by the connectivity layer to route messages. * * @internal * @param messageType The message type to check * @returns The handler function if registered, undefined otherwise */ getProtocolHandler(messageType: string): NDKProtocolHandler | undefined; /** * Fetches relay information (NIP-11) from the relay. * Results are cached in persistent storage when cache adapter is available (24-hour TTL). * Falls back to in-memory cache. Pass force=true to bypass all caches. * * @param force Force a fresh fetch, bypassing all caches * @returns The relay information document * @throws Error if the fetch fails * * @example * ```typescript * const info = await relay.fetchInfo(); * console.log(`Relay: ${info.name}`); * console.log(`Supported NIPs: ${info.supported_nips?.join(', ')}`); * ``` */ fetchInfo(force?: boolean): Promise; /** * Returns cached relay information if available, undefined otherwise. * Use fetchInfo() to retrieve fresh information. */ get info(): NDKRelayInformation | undefined; } /** * Filter validation modes for NDK subscriptions. * * @example * ```typescript * const ndk = new NDK({ * filterValidationMode: "validate" // Throw on invalid filters (default) * }); * ``` */ declare enum NDKFilterValidationMode { /** * Throw an error when invalid filters are detected (default). * Use this in development to catch filter bugs early. */ VALIDATE = "validate", /** * Automatically fix invalid filters by removing undefined values. * Use this in production for lenient handling of dynamic filters. */ FIX = "fix", /** * Skip validation entirely (legacy behavior). */ IGNORE = "ignore" } /** * Validates or fixes filters based on the specified mode. * * This function checks for: * - Undefined values in arrays * - Invalid data types (non-strings in author/id arrays, non-numbers in kinds) * - Invalid hex strings (authors, ids, #e and #p tags must be 64-char hex) * - Out-of-range kind numbers (must be 0-65535) * * @param filters - The filters to validate or fix * @param mode - The validation mode to use * @param debug - Optional debug instance for logging warnings * @returns Original filters (if valid or ignored) or fixed filters (if fix mode) * @throws Error if validation fails in VALIDATE mode * * @example * ```typescript * // Validate filters (throws on invalid) * const validated = processFilters(filters, NDKFilterValidationMode.VALIDATE); * * // Fix filters (returns cleaned) * const cleaned = processFilters(filters, NDKFilterValidationMode.FIX); * ``` */ declare function processFilters(filters: NDKFilter[], mode?: NDKFilterValidationMode, debug?: Debugger, ndk?: NDK): NDKFilter[]; type NDKSubscriptionInternalId = string; type NDKSubscriptionDelayedType = "at-least" | "at-most"; type NDKFilter = { ids?: string[]; kinds?: K[]; authors?: string[]; since?: number; until?: number; limit?: number; search?: string; [key: `#${string}`]: string[] | undefined; }; declare enum NDKSubscriptionCacheUsage { ONLY_CACHE = "ONLY_CACHE", CACHE_FIRST = "CACHE_FIRST", PARALLEL = "PARALLEL", ONLY_RELAY = "ONLY_RELAY" } interface NDKSubscriptionOptions { /** * Whether to close the subscription when all relays have reached the end of the event stream. * @default false */ closeOnEose?: boolean; cacheUsage?: NDKSubscriptionCacheUsage; /** * Whether to skip caching events coming from this subscription **/ dontSaveToCache?: boolean; /** * Groupable subscriptions are created with a slight time * delayed to allow similar filters to be grouped together. */ groupable?: boolean; /** * The delay to use when grouping subscriptions, specified in milliseconds. * @default 100 * @example * const sub1 = ndk.subscribe({ kinds: [1], authors: ["alice"] }, { groupableDelay: 100 }); * const sub2 = ndk.subscribe({ kinds: [0], authors: ["alice"] }, { groupableDelay: 1000 }); * // sub1 and sub2 will be grouped together and executed 100ms after sub1 was created */ groupableDelay?: number; /** * Specifies how this delay should be interpreted. * "at-least" means "wait at least this long before sending the subscription" * "at-most" means "wait at most this long before sending the subscription" * @default "at-most" * @example * const sub1 = ndk.subscribe({ kinds: [1], authors: ["alice"] }, { groupableDelay: 100, groupableDelayType: "at-least" }); // 3 args * const sub2 = ndk.subscribe({ kinds: [0], authors: ["alice"] }, { groupableDelay: 1000, groupableDelayType: "at-most" }); // 3 args * // sub1 and sub2 will be grouped together and executed 1000ms after sub1 was created */ groupableDelayType?: NDKSubscriptionDelayedType; /** * The subscription ID to use for the subscription. */ subId?: string; /** * Pool to use */ pool?: NDKPool; /** * Skip signature verification * @default false */ skipVerification?: boolean; /** * Skip event validation. Event validation, checks whether received * kinds conform to what the expected schema of that kind should look like.rtwle * @default false */ skipValidation?: boolean; /** * Skip emitting on events before they are received from a relay. (skip optimistic publish) * @default false */ skipOptimisticPublishEvent?: boolean; /** * Remove filter constraints when querying the cache. * * This allows setting more aggressive filters that will be removed when hitting the cache. * * Useful uses of this include removing `since` or `until` constraints or `limit` filters. * * @example * ndk.subscribe({ kinds: [1], since: 1710000000, limit: 10 }, { cacheUnconstrainFilter: ['since', 'limit'] }); // 3 args * * This will hit relays with the since and limit constraints, while loading from the cache without them. */ cacheUnconstrainFilter?: (keyof NDKFilter)[]; /** * Whether to wrap events in kind-specific classes when possible. * @default false */ wrap?: boolean; /** * Explicit relay set to use for this subscription instead of calculating it. * If `relayUrls` is also provided in the options, this `relaySet` takes precedence. * @since 2.13.0 Moved from `ndk.subscribe` parameter to options. */ relaySet?: NDKRelaySet; /** * Explicit relay URLs to use for this subscription instead of calculating the relay set. * An `NDKRelaySet` will be created internally from these URLs. * If `relaySet` is also provided in the options, the explicit `relaySet` takes precedence over these URLs. * @since 2.13.0 */ relayUrls?: string[]; /** * When set, the cache will be queried first, and, when hitting relays, * a `since` filter will be added to the subscription that is one second * after the last event received from the cache. * * This option implies cacheUsage: CACHE_FIRST. */ addSinceFromCache?: boolean; /** * Include muted events in subscription results. * When false (default), events that match ndk.muteFilter are filtered out. * When true, muted events are included. * @default false */ includeMuted?: boolean; /** * Number of relays to query for each author in the subscription. * This controls the outbox model relay selection when the filter has authors. * Higher values improve redundancy but increase bandwidth usage. * @default 2 * @example * // Query 3 relays for each author * ndk.subscribe( * { kinds: [1], authors: ["alice", "bob"] }, * { relayGoalPerAuthor: 3 } * ); * @example * // Use all available relays for each author * ndk.subscribe( * { kinds: [1], authors: ["alice", "bob"] }, * { relayGoalPerAuthor: Infinity } * ); */ relayGoalPerAuthor?: number; /** * Called for each event received by the subscription. * This eliminates the race condition of subscribing and then attaching event handlers. * @param event The received NDKEvent. * @param relay The relay the event was received from (undefined if from cache). * @param subscription The subscription that received the event. * @param fromCache Whether the event came from cache. * @param optimisticPublish Whether this is an optimistic publish event. */ onEvent?: (event: NDKEvent, relay?: NDKRelay, subscription?: NDKSubscription, fromCache?: boolean, optimisticPublish?: boolean) => void; /** * Called with a batch of events from cache. * When this is provided, cached events are processed in batch instead of individually. * @param events Array of cached events to process in batch. */ onEvents?: (events: NDKEvent[]) => void; /** * Called when the subscription receives an EOSE (End of Stored Events) marker * from all connected relays. * @param subscription The subscription that reached EOSE. */ onEose?: (subscription: NDKSubscription) => void; /** * Called when a duplicate event is received by the subscription. * @param event The duplicate event received by the subscription. * @param relay The relay that received the event (undefined if from cache). * @param timeSinceFirstSeen The time elapsed since the first time the event was seen. * @param subscription The subscription that received the event. * @param fromCache Whether the event came from cache. * @param optimisticPublish Whether this is an optimistic publish event. */ onEventDup?: (event: NDKEvent | NostrEvent, relay: NDKRelay | undefined, timeSinceFirstSeen: number, subscription: NDKSubscription, fromCache: boolean, optimisticPublish: boolean) => void; /** * Called when the subscription is closed. * @param subscription The subscription that was closed. */ onClose?: (subscription: NDKSubscription) => void; /** * When true, only accept events from the relays specified in relaySet/relayUrls. * When false (default), events matching the filter from any relay will be delivered * to this subscription (cross-subscription matching behavior). * * This is useful when you need strict relay provenance, such as: * - Fetching events exclusively from a specific relay * - Implementing relay-based isolation or routing * - Testing relay-specific behavior * * @default false * @example * // Only receive events from relay-a.com, ignore matches from other relays * ndk.subscribe( * { kinds: [1] }, * { relayUrls: ["wss://relay-a.com"], exclusiveRelay: true } * ); */ exclusiveRelay?: boolean; } /** * Default subscription options. */ declare const defaultOpts: NDKSubscriptionOptions; /** * Represents a subscription to an NDK event stream. * * @emits event * Emitted when an event is received by the subscription. * * ({NDKEvent} event - The event received by the subscription, * * {NDKRelay} relay - The relay that received the event, * * {NDKSubscription} subscription - The subscription that received the event.) * * @emits event:dup * Emitted when a duplicate event is received by the subscription. * * {NDKEvent} event - The duplicate event received by the subscription. * * {NDKRelay} relay - The relay that received the event. * * {number} timeSinceFirstSeen - The time elapsed since the first time the event was seen. * * {NDKSubscription} subscription - The subscription that received the event. * * @emits cacheEose - Emitted when the cache adapter has reached the end of the events it had. * * @emits eose - Emitted when all relays have reached the end of the event stream. * * {NDKSubscription} subscription - The subscription that received EOSE. * * @emits close - Emitted when the subscription is closed. * * {NDKSubscription} subscription - The subscription that was closed. * * @example * const sub = ndk.subscribe( * { kinds: [1] }, // Get all kind:1s * { * onEvent: (event) => console.log(event.content), // Show the content * onEose: () => console.log("All relays have reached the end of the event stream"), * onClose: () => console.log("Subscription closed") * } * ); * setTimeout(() => sub.stop(), 10000); // Stop the subscription after 10 seconds * * @description * Subscriptions are created using {@link NDK.subscribe}. * * # Event validation * By defaults, subscriptions will validate events to comply with the minimal requirement * of each known NIP. * This can be disabled by setting the `skipValidation` option to `true`. * * @example * const sub = ndk.subscribe( * { kinds: [1] }, * { * skipValidation: false, * onEvent: (event) => console.log(event.content) // Only valid events will be received * } * ); */ declare class NDKSubscription extends EventEmitter<{ cacheEose: () => void; eose: (sub: NDKSubscription) => void; close: (sub: NDKSubscription) => void; /** * Emitted when a duplicate event is received by the subscription. * @param event - The duplicate event received by the subscription. * @param relay - The relay that received the event. * @param timeSinceFirstSeen - The time elapsed since the first time the event was seen. * @param sub - The subscription that received the event. */ "event:dup": (event: NDKEvent | NostrEvent, relay: NDKRelay | undefined, timeSinceFirstSeen: number, sub: NDKSubscription, fromCache: boolean, optimisticPublish: boolean) => void; /** * Emitted when an event is received by the subscription. * @param event - The event received by the subscription. * @param relay - The relay that received the event. * @param sub - The subscription that received the event. * @param fromCache - Whether the event was received from the cache. * @param optimisticPublish - Whether the event was received from an optimistic publish. */ event: (event: NDKSignedEvent, relay: NDKRelay | undefined, sub: NDKSubscription, fromCache: boolean, optimisticPublish: boolean) => void; /** * Emitted when a relay unilaterally closes the subscription. * @param relay * @param reason * @returns */ closed: (relay: NDKRelay, reason: string) => void; }> { readonly subId?: string; readonly filters: NDKFilter[]; readonly opts: NDKSubscriptionOptions; readonly pool: NDKPool; readonly skipVerification: boolean; readonly skipValidation: boolean; readonly exclusiveRelay: boolean; /** * Tracks the filters as they are executed on each relay */ relayFilters?: Map; relaySet?: NDKRelaySet; ndk: NDK; debug: debug.Debugger; /** * Events that have been seen by the subscription, with the time they were first seen. */ eventFirstSeen: Map; /** * Relays that have sent an EOSE. */ eosesSeen: Set; /** * The time the last event was received by the subscription. * This is used to calculate when EOSE should be emitted. */ private lastEventReceivedAt; /** * The most recent event timestamp from cache results. * This is used for addSinceFromCache functionality. */ private mostRecentCacheEventTimestamp?; internalId: NDKSubscriptionInternalId; /** * Whether the subscription should close when all relays have reached the end of the event stream. */ closeOnEose: boolean; /** * Pool monitor callback */ private poolMonitor; skipOptimisticPublishEvent: boolean; /** * Filters to remove when querying the cache. */ cacheUnconstrainFilter?: Array; constructor(ndk: NDK, filters: NDKFilter | NDKFilter[], opts?: NDKSubscriptionOptions, subId?: string); /** * Returns the relays that have not yet sent an EOSE. */ relaysMissingEose(): WebSocket["url"][]; /** * Provides access to the first filter of the subscription for * backwards compatibility. */ get filter(): NDKFilter; get groupableDelay(): number | undefined; get groupableDelayType(): NDKSubscriptionDelayedType; isGroupable(): boolean; private shouldQueryCache; private shouldQueryRelays; private shouldWaitForCache; /** * Start the subscription. This is the main method that should be called * after creating a subscription. * * @param emitCachedEvents - Whether to emit events coming from a synchronous cache * * When using a synchronous cache, the events will be returned immediately * by this function. If you will use those returned events, you should * set emitCachedEvents to false to prevent seeing them as duplicate events. */ start(emitCachedEvents?: boolean): NDKEvent[] | null; /** * We want to monitor for new relays that are coming online, in case * they should be part of this subscription. */ private startPoolMonitor; onStopped?: () => void; stop(): void; /** * @returns Whether the subscription has an authors filter. */ hasAuthorsFilter(): boolean; private startWithCache; /** * Find available relays that should be part of this subscription and execute in them. * * Note that this is executed in addition to using the pool monitor, so even if the relay set * that is computed (i.e. we don't have any relays available), when relays come online, we will * check if we need to execute in them. */ private startWithRelays; /** * Refresh relay connections when outbox data becomes available. * This recalculates which relays should receive this subscription and * connects to any newly discovered relays. */ refreshRelayConnections(): void; /** * Called when an event is received from a relay or the cache * @param event * @param relay * @param fromCache Whether the event was received from the cache * @param optimisticPublish Whether this event is coming from an optimistic publish */ eventReceived(event: NDKEvent | NostrEvent, relay: NDKRelay | undefined, fromCache?: boolean, optimisticPublish?: boolean): void; /** * Optionally wraps, sync or async, and emits the event (if one comes back from the wrapper) */ private emitEvent; closedReceived(relay: NDKRelay, reason: string): void; private eoseTimeout; private eosed; eoseReceived(relay: NDKRelay): void; } /** * Creates a NDKRelaySet for the specified event. * TODO: account for relays where tagged pubkeys or hashtags * tend to write to. * @param ndk {NDK} * @param event {Event} * @returns Promise */ declare function calculateRelaySetFromEvent(ndk: NDK, event: NDKEvent, requiredRelayCount?: number): Promise; declare class NDKPublishError extends Error { errors: Map; publishedToRelays: Set; /** * Intended relay set where the publishing was intended to happen. */ intendedRelaySet?: NDKRelaySet; constructor(message: string, errors: Map, publishedToRelays: Set, intendedRelaySet?: NDKRelaySet); get relayErrors(): string; } /** * A relay set is a group of relays. This grouping can be short-living, for a single * REQ or can be long-lasting, for example for the explicit relay list the user * has specified. * * Requests to relays should be sent through this interface. */ declare class NDKRelaySet { readonly relays: Set; private debug; private ndk; private pool; constructor(relays: Set, ndk: NDK, pool?: NDKPool); /** * Adds a relay to this set. */ addRelay(relay: NDKRelay): void; get relayUrls(): WebSocket["url"][]; /** * Creates a relay set from a list of relay URLs. * * If no connection to the relay is found in the pool it will temporarily * connect to it. * * @param relayUrls - list of relay URLs to include in this set * @param ndk * @param connect - whether to connect to the relay immediately if it was already in the pool but not connected * @returns NDKRelaySet */ static fromRelayUrls(relayUrls: readonly string[], ndk: NDK, connect?: boolean, pool?: NDKPool): NDKRelaySet; /** * Publish an event to all relays in this relay set. * * This method implements a robust mechanism for publishing events to multiple relays with * built-in handling for race conditions, timeouts, and partial failures. The implementation * uses a dual-tracking mechanism to ensure accurate reporting of which relays successfully * received an event. * * Key aspects of this implementation: * * 1. DUAL-TRACKING MECHANISM: * - Promise-based tracking: Records successes/failures from the promises returned by relay.publish() * - Event-based tracking: Listens for 'relay:published' events that indicate successful publishing * This approach ensures we don't miss successful publishes even if there are subsequent errors in * the promise chain. * * 2. RACE CONDITION HANDLING: * - If a relay emits a success event but later fails in the promise chain, we still count it as a success * - If a relay times out after successfully publishing, we still count it as a success * - All relay operations happen in parallel, with proper tracking regardless of completion order * * 3. TIMEOUT MANAGEMENT: * - Individual timeouts for each relay operation * - Proper cleanup of timeouts to prevent memory leaks * - Clear timeout error reporting * * 4. ERROR HANDLING: * - Detailed tracking of specific errors for each failed relay * - Special handling for ephemeral events (which don't expect acknowledgement) * - RequiredRelayCount parameter to control the minimum success threshold * * @param event Event to publish * @param timeoutMs Timeout in milliseconds for each relay publish operation * @param requiredRelayCount The minimum number of relays we expect the event to be published to * @returns A set of relays the event was published to * @throws {NDKPublishError} If the event could not be published to at least `requiredRelayCount` relays * @example * ```typescript * const relaySet = new NDKRelaySet(new Set([relay1, relay2]), ndk); * const publishedToRelays = await relaySet.publish(event); * // publishedToRelays can contain relay1, relay2, both, or none * // depending on which relays the event was successfully published to * if (publishedToRelays.size > 0) { * console.log("Event published to at least one relay"); * } * ``` */ publish(event: NDKEvent, timeoutMs?: number, requiredRelayCount?: number): Promise>; get size(): number; /** * Counts events matching the given filters across all relays in this set. * * This method implements NIP-45 COUNT with HyperLogLog (HLL) support for * accurate cardinality estimation across multiple relays. * * When relays return HLL data, the counts are merged using the HLL algorithm * to avoid double-counting events that appear on multiple relays. * * @param filters - The filters to count events for * @param opts - Optional count options (timeout, custom id) * @returns An aggregated count result with the best estimate and per-relay results * * @example * ```typescript * const relaySet = new NDKRelaySet(new Set([relay1, relay2]), ndk); * const result = await relaySet.count([{ kinds: [1], authors: [pubkey] }]); * console.log(`Estimated unique count: ${result.count}`); * console.log(`Relay 1 reported: ${result.relayResults.get(relay1.url)?.count}`); * ``` */ count(filters: NDKFilter | NDKFilter[], opts?: NDKCountOptions): Promise; } /** * Options on how to handle when a relay hint doesn't respond * with the requested event. * * When a tag includes a relay hint, and the relay hint doesn't come back * with the event, the fallback options are used to try to fetch the event * from somewhere else. */ type NDKFetchFallbackOptions = { /** * Relay set to use as a fallback when the hint relay doesn't respond. * If not provided, the normal NDK calculation is used (whether explicit relays or outbox calculation) * Default is `undefined`. */ relaySet?: NDKRelaySet; /** * Type of fallback to use when the hint relay doesn't respond. * - "timeout" will wait for a timeout before falling back * - "eose" will wait for the EOSE before falling back * - "none" will not fall back * Default is "timeout". */ type: "timeout" | "eose" | "none"; /** * Timeout in milliseconds for the fallback relay. * Default is 1500ms. */ timeout?: number; }; interface AIGuardrailConfig { skip?: Set; } type AIGuardrailsMode = boolean | AIGuardrailConfig; /** * AI Guardrails - Runtime validation to catch common mistakes made by LLMs and developers. * * This module provides a flexible system for warning about or preventing common anti-patterns * when using NDK. It's designed to be: * - Off by default (zero performance impact in production) * - Granularly configurable (can disable specific checks) * - Educational (provides actionable error messages) * * Architecture: * - Inline checks for synchronous validation (must block operations) * - Hook methods for observational warnings (async, non-blocking) * - All guardrail logic organized by domain (ndk, event, relay, etc.) * - Core code stays clean - just calls typed hook methods * * @example Enable all guardrails * ```typescript * const ndk = new NDK({ aiGuardrails: true }); * ``` * * @example Enable with exceptions * ```typescript * const ndk = new NDK({ * aiGuardrails: { skip: new Set(['filter-large-limit']) } * }); * ``` * * @example Programmatic control * ```typescript * ndk.aiGuardrails.skip('filter-large-limit'); * ndk.aiGuardrails.enable('filter-bech32-in-array'); * ``` * * @example Temporarily disable for one call * ```typescript * // Disable all guardrails for one call * ndk.guardrailOff().fetchEvents({ kinds: [1] }); * * // Disable specific guardrail for one call * ndk.guardrailOff('fetch-events-usage').fetchEvents({ kinds: [1] }); * * // Disable multiple guardrails for one call * ndk.guardrailOff(['fetch-events-usage', 'filter-large-limit']) * .fetchEvents({ kinds: [1], limit: 5000 }); * * // Next call has guardrails re-enabled automatically * ndk.fetchEvents({ kinds: [1] }); // Guardrails active again * ``` * * @example Hook usage in core code * ```typescript * // Clean, type-safe hook calls * this.aiGuardrails.ndkInstantiated(this); * this.aiGuardrails.eventReceived(event, relay); * ``` */ /** * Central guardrails manager. * Provides both inline validation methods and hook methods for observational checks. */ declare class AIGuardrails { private enabled; private skipSet; private extensions; private _nextCallDisabled; private _replyEvents; private _fetchEventsCount; private _subscribeCount; constructor(mode?: AIGuardrailsMode); /** * Register an extension namespace with custom guardrail hooks. * This allows external packages to add their own guardrails. * * @example * ```typescript * // In NDKSvelte package: * ndk.aiGuardrails.register('ndkSvelte', { * constructing: (params) => { * if (!params.session) { * warn('ndksvelte-no-session', 'NDKSvelte instantiated without session parameter...'); * } * } * }); * * // In NDKSvelte constructor: * this.ndk.aiGuardrails?.ndkSvelte?.constructing(params); * ``` */ register(namespace: string, hooks: any): void; /** * Set the guardrails mode. */ setMode(mode: AIGuardrailsMode): void; /** * Check if guardrails are enabled at all. */ isEnabled(): boolean; /** * Check if a specific guardrail check should run. */ shouldCheck(id: string): boolean; /** * Disable a specific guardrail check. */ skip(id: string): void; /** * Re-enable a specific guardrail check. */ enable(id: string): void; /** * Get all currently skipped guardrails. */ getSkipped(): string[]; /** * Capture the current _nextCallDisabled set and clear it atomically. * This is used by hook methods to handle one-time guardrail disabling. */ captureAndClearNextCallDisabled(): Set | "all" | null; /** * Increment fetchEvents call counter for ratio tracking. */ incrementFetchEventsCount(): void; /** * Increment subscribe call counter for ratio tracking. */ incrementSubscribeCount(): void; /** * Check if fetchEvents usage ratio exceeds the threshold. * Returns true if more than 50% of calls are fetchEvents AND total calls > 6. */ shouldWarnAboutFetchEventsRatio(): boolean; /** * Throw an error if the check should run. * Also logs to console.error in case the throw gets swallowed. * @param canDisable - If false, this is a fatal error that cannot be disabled (default: true) */ error(id: string, message: string, hint?: string, canDisable?: boolean): never | undefined; /** * Throw a warning if the check should run. * Also logs to console.error in case the throw gets swallowed. * Warnings can always be disabled. */ warn(id: string, message: string, hint?: string): never | undefined; /** * Format a guardrail message with helpful metadata. */ private formatMessage; /** * Called when NDK instance is created. * Checks for cache presence and other initialization concerns. */ ndkInstantiated(ndk: NDK): void; /** * NDK-related guardrails */ ndk: { /** * Called when fetchEvents is about to be called */ fetchingEvents: (filters: any, opts?: any) => void; }; /** * Event-related guardrails */ event: { /** * Called when an event is about to be signed */ signing: (event: NDKEvent) => void; /** * Called before an event is published */ publishing: (event: NDKEvent) => void; /** * Called when an event is received from a relay */ received: (_event: NDKEvent, _relay: NDKRelay) => void; /** * Called when a reply event is being created via .reply() * This allows guardrails to track legitimate reply events */ creatingReply: (event: NDKEvent) => void; }; /** * Subscription-related guardrails */ subscription: { /** * Called when a subscription is created */ created: (_filters: any[], _opts?: any) => void; }; /** * Relay-related guardrails */ relay: { /** * Called when a relay connection is established */ connected: (_relay: NDKRelay) => void; }; } type NDKZapConfirmationLN = { preimage: string; }; type NDKPaymentConfirmationLN = { preimage: string; }; type LNPaymentRequest = string; type LnPaymentInfo = { pr: LNPaymentRequest; }; type NDKLUD18ServicePayerData = Partial<{ name: { mandatory: boolean; }; pubkey: { mandatory: boolean; }; identifier: { mandatory: boolean; }; email: { mandatory: boolean; }; auth: { mandatory: boolean; k1: string; }; }> & Record; type NDKLnUrlData = { tag: string; callback: string; minSendable: number; maxSendable: number; metadata: string; payerData?: NDKLUD18ServicePayerData; commentAllowed?: number; /** * Pubkey of the zapper that should publish zap receipts for this user */ nostrPubkey?: Hexpubkey; allowsNostr?: boolean; }; declare function getNip57ZapSpecFromLud({ lud06, lud16 }: { lud06?: string; lud16?: string; }, ndk: NDK): Promise; /** * Checks if a kind is ephemeral (20000-29999 range). * Ephemeral events are not stored in cache, so there's no point querying for them. */ declare function isEphemeralKind(kind: number): boolean; /** * Filters out ephemeral kinds from a filter's kinds array. * Returns null if the filter had kinds but all were ephemeral (meaning the filter should be skipped entirely). * Returns the original filter if no kinds were specified (don't break REQs without kind filters). * Returns a new filter with non-ephemeral kinds if some kinds were valid. */ declare function filterEphemeralKindsFromFilter(filter: NDKFilter): NDKFilter | null; /** * Processes filters for cache queries by: * 1. Removing constrained fields (limit, since, until) if cacheUnconstrainFilter is set * 2. Filtering out ephemeral kinds (20000-29999) since they're never cached * * Returns an empty array if all filters should be skipped (all kinds were ephemeral). */ declare function filterForCache(subscription: NDKSubscription): NDKFilter[]; type NDKCacheEntry = T & { cachedAt?: number; }; /** * Cache module definition for packages to extend the cache with their own data structures. * Packages define their schemas, indexes, and migrations. */ interface CacheModuleDefinition { /** * Unique namespace for this module (e.g., "messages", "wallet", "sync") */ namespace: string; /** * Current version of this module's schema */ version: number; /** * Collection definitions for this module */ collections: { [name: string]: { /** * Primary key field name */ primaryKey: string; /** * Fields to create indexes on for efficient querying */ indexes?: string[]; /** * Optional schema definition (for validation or TypeScript generation) */ schema?: Record; /** * Compound indexes for multi-field queries */ compoundIndexes?: Array; }; }; /** * Migration functions keyed by version number * Version 1 is the initial setup, 2+ are upgrades */ migrations: { [version: number]: (adapter: CacheModuleMigrationContext) => Promise; }; } /** * Migration context passed to module migration functions */ interface CacheModuleMigrationContext { /** * Get a collection by name within the module's namespace */ getCollection(name: string): Promise>; /** * Create a new collection */ createCollection(name: string, definition: CacheModuleDefinition["collections"][string]): Promise; /** * Delete a collection */ deleteCollection(name: string): Promise; /** * Add an index to a collection */ addIndex(collection: string, field: string | string[]): Promise; /** * Current version being migrated from */ fromVersion: number; /** * Target version being migrated to */ toVersion: number; } /** * Collection interface for module data access */ interface CacheModuleCollection { /** * Get an item by its primary key */ get(id: string): Promise; /** * Get multiple items by their primary keys */ getMany(ids: string[]): Promise; /** * Save an item (upsert) */ save(item: T): Promise; /** * Save multiple items (bulk upsert) */ saveMany(items: T[]): Promise; /** * Delete an item by its primary key */ delete(id: string): Promise; /** * Delete multiple items by their primary keys */ deleteMany(ids: string[]): Promise; /** * Query items by a single field */ findBy(field: string, value: any): Promise; /** * Query items with multiple conditions */ where(conditions: Record): Promise; /** * Get all items in the collection */ all(): Promise; /** * Count items matching conditions */ count(conditions?: Record): Promise; /** * Clear all items from the collection */ clear(): Promise; } /** * Storage interface for cache modules that bridges to NDKCacheAdapter */ interface CacheModuleStorage { /** * Register a cache module with the adapter */ registerModule(module: CacheModuleDefinition): Promise; /** * Get a collection from a module */ getCollection(namespace: string, collection: string): Promise>; /** * Check if a module is registered */ hasModule(namespace: string): boolean; /** * Get the current version of a module */ getModuleVersion(namespace: string): Promise; } interface NDKCacheAdapter { /** * Whether this cache adapter is expected to be fast. * If this is true, the cache will be queried before the relays. * When this is false, the cache will be queried in addition to the relays. */ locking: boolean; /** * Weather the cache is ready. */ ready?: boolean; initializeAsync?(ndk: NDK): Promise; initialize?(ndk: NDK): void; /** * Either synchronously or asynchronously queries the cache. * * Cache adapters that return values synchronously should return an array of events. * Asynchronous cache adapters should call the subscription.eventReceived method for each event. */ query(subscription: NDKSubscription): NDKEvent[] | Promise; setEvent(event: NDKEvent, filters: NDKFilter[], relay?: NDKRelay): Promise; /** * Called when we receive a duplicate event from a relay. * This associates the relay with an existing cached event without re-processing the event data. * @param event - The duplicate event received. * @param relay - The relay that sent the duplicate event. */ setEventDup?(event: NDKEvent, relay: NDKRelay): Promise | void; /** * Called when an event is deleted by the client. * Cache adapters should remove the event from their cache. * @param eventIds - The ids of the events that were deleted. */ deleteEventIds?(eventIds: NDKEventId[]): Promise; /** * Fetches a profile from the cache synchronously. * @param pubkey - The pubkey of the profile to fetch. * @returns The profile, or null if it is not in the cache. */ fetchProfileSync?(pubkey: Hexpubkey): NDKCacheEntry | null; /** * Retrieve all profiles from the cache synchronously. * @returns A map of pubkeys to profiles. */ getAllProfilesSync?(): Map>; /** * Special purpose */ fetchProfile?(pubkey: Hexpubkey): Promise | null>; saveProfile?(pubkey: Hexpubkey, profile: NDKUserProfile): void | Promise; /** * Fetches profiles that match the given filter. * @param filter - Either a filter function or a filter descriptor object * @returns NDKUserProfiles that match the filter. * @example * // Using a filter function * const searchFunc = (pubkey, profile) => profile.name.toLowerCase().includes("alice"); * const allAliceProfiles = await cache.getProfiles(searchFunc); * * @example * // Using a filter descriptor (supported by some cache adapters like cache-sqlite-wasm) * const aliceProfiles = await cache.getProfiles({ field: 'name', contains: 'alice' }); * // Or search multiple fields * const aliceProfiles = await cache.getProfiles({ fields: ['name', 'displayName'], contains: 'alice' }); */ getProfiles?: (filter: ((pubkey: Hexpubkey, profile: NDKUserProfile) => boolean) | { field?: string; fields?: string[]; contains: string; }) => Promise | undefined>; loadNip05?(nip05: string, maxAgeForMissing?: number): Promise; saveNip05?(nip05: string, profile: ProfilePointer | null): void; /** * Fetches a user's LNURL data from the cache. * @param pubkey The pubkey of the user to fetch the LNURL data for. * @param maxAgeInSecs The maximum age of the data in seconds. * @param maxAgeForMissing The maximum age of the data in seconds if it is missing before it returns that it should be refetched. * @returns The LNURL data, null if it is not in the cache and under the maxAgeForMissing, or "missing" if it should be refetched. */ loadUsersLNURLDoc?(pubkey: Hexpubkey, maxAgeInSecs?: number, maxAgeForMissing?: number): Promise; saveUsersLNURLDoc?(pubkey: Hexpubkey, doc: NDKLnUrlData | null): void; /** * Updates information about the relay. */ updateRelayStatus?(relayUrl: WebSocket["url"], info: NDKCacheRelayInfo): void | Promise; /** * Fetches information about the relay. */ getRelayStatus?(relayUrl: WebSocket["url"]): NDKCacheRelayInfo | undefined | Promise; /** * Tracks a publishing event. * @param event * @param relayUrls List of relays that the event will be published to. */ addUnpublishedEvent?(event: NDKEvent, relayUrls: WebSocket["url"][]): void | Promise; /** * Fetches all unpublished events. */ getUnpublishedEvents?(): Promise<{ event: NDKEvent; relays?: WebSocket["url"][]; lastTryAt?: number; }[]>; /** * Removes an unpublished event. */ discardUnpublishedEvent?(eventId: NDKEventId): void | Promise; /** * Called when the cache is ready. */ onReady?(callback: () => void): void; /** * Get a decrypted event from the cache by its wrapper ID. * @param wrapperId - The ID of the gift-wrapped event (kind 1059). * @returns The decrypted rumor event, or null if it doesn't exist. */ getDecryptedEvent?(wrapperId: NDKEventId): NDKEvent | null | Promise; /** * Store a decrypted event in the cache. * @param wrapperId - The ID of the gift-wrapped event (kind 1059) to use as the cache key. * @param decryptedEvent - The decrypted rumor event to store. */ addDecryptedEvent?(wrapperId: NDKEventId, decryptedEvent: NDKEvent): void | Promise; /** * Cleans up the cache. This is called when the user logs out. */ clear?(): Promise; /** * Gets all nutzap states from the cache. * @returns A map of event IDs to nutzap states. */ getAllNutzapStates?(): Promise>; /** * Sets the state of a nutzap in the cache. * @param id The ID of the nutzap event. * @param stateChange The partial state change to apply. */ setNutzapState?(id: NDKEventId, stateChange: Partial): Promise; /** * Generic key-value cache storage for packages. * Packages should namespace their keys (e.g., "wallet:mint:info:https://mint.url"). * @param namespace The namespace for the data (e.g., "wallet", "sync") * @param key The key within the namespace * @param maxAgeInSecs Maximum age of cached data in seconds (optional) * @returns The cached data, or undefined if not cached or expired */ getCacheData?(namespace: string, key: string, maxAgeInSecs?: number): Promise; /** * Generic key-value cache storage for packages. * @param namespace The namespace for the data (e.g., "wallet", "sync") * @param key The key within the namespace * @param data The data to cache */ setCacheData?(namespace: string, key: string, data: T): Promise; /** * Cache module support - Register a module with its schema and migrations * @param module Module definition with schema, indexes, and migrations * @returns Promise that resolves when the module is registered and migrations are complete */ registerModule?(module: CacheModuleDefinition): Promise; /** * Cache module support - Get a collection from a registered module * @param namespace Module namespace * @param collection Collection name within the module * @returns Collection interface for data operations */ getModuleCollection?(namespace: string, collection: string): Promise>; } /** * Relay metadata and statistics stored in cache. * * This type supports both core connection tracking and extensible package-specific metadata. * Packages can store custom data using the metadata field with namespacing. * * @example * ```typescript * // Core connection tracking * await cache.updateRelayStatus(url, { * lastConnectedAt: Date.now(), * consecutiveFailures: 0 * }); * * // Package-specific metadata (sync package) * await cache.updateRelayStatus(url, { * metadata: { * sync: { * supportsNegentropy: false, * lastChecked: Date.now() * } * } * }); * * // Package-specific metadata (auth/rate limiting) * await cache.updateRelayStatus(url, { * metadata: { * auth: { * token: 'AUTH_TOKEN_HERE', * expiresAt: Date.now() + 3600000 * }, * rateLimit: { * requestCount: 42, * windowStart: Date.now(), * maxPerWindow: 100 * } * } * }); * * // NIP-11 caching * await cache.updateRelayStatus(url, { * nip11: { * data: relayInfo, * fetchedAt: Date.now() * } * }); * ``` */ type NDKCacheRelayInfo = { /** * Timestamp of last successful connection */ lastConnectedAt?: number; /** * Don't attempt connection before this timestamp */ dontConnectBefore?: number; /** * Number of consecutive connection failures */ consecutiveFailures?: number; /** * Timestamp of last connection failure */ lastFailureAt?: number; /** * Cached NIP-11 relay information document */ nip11?: { data: NDKRelayInformation; fetchedAt: number; }; /** * Package-specific metadata (namespaced). * * Packages should use their package name as the namespace key. * * @example * ```typescript * metadata: { * sync: { supportsNegentropy: false, lastChecked: 1234567890 }, * auth: { token: 'abc123', expiresAt: 1234567890 }, * rateLimit: { requestCount: 42, windowStart: 1234567890, maxPerWindow: 100 } * } * ``` */ metadata?: Record>; }; type OutboxItemType = "user" | "kind"; /** * Tracks outbox scoring of an item. An item can be any of: * * - A user * - A tag */ declare class OutboxItem { /** * Type of item */ type: OutboxItemType; /** * The relay URLs that are of interest to this item */ relayUrlScores: Map; readRelays: Set; writeRelays: Set; constructor(type: OutboxItemType); } /** * The responsibility of this class is to track relay:outbox-item associations * so that we can intelligently choose which relays to query for which items. * * A single instance of this class should be shared across all subscriptions within * an NDK instance. * * TODO: The state of this tracker needs to be added to cache adapters so that we * can rehydrate-it when a cache is present. */ declare class OutboxTracker extends EventEmitter { data: LRUCache; private ndk; private debug; constructor(ndk: NDK); /** * Adds a list of users to the tracker. * @param items * @param skipCache */ trackUsers(items: NDKUser[] | Hexpubkey[], skipCache?: boolean): Promise; /** * * @param key * @param score */ track(item: NDKUser | Hexpubkey, type?: OutboxItemType, _skipCache?: boolean): OutboxItem; } type Proof$1 = { /** * Keyset id, used to link proofs to a mint an its MintKeys. */ id: string; /** * Amount denominated in Satoshis. Has to match the amount of the mints signing key. */ amount: number; /** * The initial secret that was (randomly) chosen for the creation of this proof. */ secret: string; /** * The unblinded signature for this secret, signed by the mints private key. */ C: string; }; declare enum NutzapValidationCode { NO_PROOFS = "NO_PROOFS", INVALID_PROOF_COUNT = "INVALID_PROOF_COUNT", MULTIPLE_RECIPIENTS = "MULTIPLE_RECIPIENTS", NO_RECIPIENT = "NO_RECIPIENT", MULTIPLE_MINTS = "MULTIPLE_MINTS", NO_MINT = "NO_MINT", MULTIPLE_EVENT_TAGS = "MULTIPLE_EVENT_TAGS", MALFORMED_PROOF_SECRET = "MALFORMED_PROOF_SECRET", MISSING_EVENT_TAG_IN_PROOF = "MISSING_EVENT_TAG_IN_PROOF", MISMATCHED_EVENT_TAG_IN_PROOF = "MISMATCHED_EVENT_TAG_IN_PROOF", MISSING_SENDER_TAG_IN_PROOF = "MISSING_SENDER_TAG_IN_PROOF", MISMATCHED_SENDER_TAG_IN_PROOF = "MISMATCHED_SENDER_TAG_IN_PROOF", NO_EVENT_TAG_IN_EVENT = "NO_EVENT_TAG_IN_EVENT" } declare enum NutzapValidationSeverity { ERROR = "ERROR", WARNING = "WARNING" } type NutzapValidationIssue = { code: NutzapValidationCode; severity: NutzapValidationSeverity; message: string; proofIndex?: number; }; type NutzapValidationResult = { valid: boolean; issues: NutzapValidationIssue[]; }; declare function createValidationIssue(code: NutzapValidationCode, proofIndex?: number): NutzapValidationIssue; /** * Represents a NIP-61 nutzap */ declare class NDKNutzap extends NDKEvent { private debug; private _proofs; static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk?: NDK, event?: NostrEvent | NDKEvent); static from(event: NDKEvent): NDKNutzap | undefined; set comment(comment: string | undefined); get comment(): string; set proofs(proofs: Proof$1[]); get proofs(): Proof$1[]; get rawP2pk(): string | undefined; /** * Gets the p2pk pubkey that is embedded in the first proof. * * Note that this returns a nostr pubkey, not a cashu pubkey (no "02" prefix) */ get p2pk(): string | undefined; /** * Get the mint where this nutzap proofs exist */ get mint(): string; set mint(value: string); get unit(): string; set unit(value: string | undefined); get amount(): number; sender: NDKUser; /** * Set the target of the nutzap * @param target The target of the nutzap (a user or an event) */ set target(target: NDKEvent | NDKUser); set recipientPubkey(pubkey: Hexpubkey); get recipientPubkey(): Hexpubkey; get recipient(): NDKUser; toNostrEvent(): Promise; /** * Validates that the nutzap conforms to NIP-61 * @deprecated Use validateNIP61() instead for detailed validation results */ get isValid(): boolean; /** * Performs comprehensive validation of the nutzap according to NIP-61. * Returns detailed validation results including errors and warnings. * * Errors make the nutzap invalid, warnings are recommendations for best practices. */ validateNIP61(): NutzapValidationResult; } /** * Returns the p2pk pubkey a proof is locked to. * * Note that this function does NOT make cashu pubkey into nostr pubkey * (i.e. it does NOT remove the "02" prefix) * @param proof */ declare function proofP2pk(proof: Proof$1): Hexpubkey | undefined; /** * Returns the p2pk pubkey a proof is locked to. * * Note that this function makes cashu pubkey into nostr pubkey * (i.e. it removes the "02" prefix) * @param proof */ declare function proofP2pkNostr(proof: Proof$1): Hexpubkey | undefined; /** * * @param cashuPubkey * @returns */ declare function cashuPubkeyToNostrPubkey(cashuPubkey: string): string | undefined; /** * Provides information that should be used to send a NIP-61 nutzap. * mints: URLs of the mints that can be used. * relays: URLs of the relays where nutzap must be published * p2pk: Optional pubkey to use for P2PK lock */ type CashuPaymentInfo = { /** * Mints that must be used for the payment */ mints?: string[]; /** * Relays where nutzap must be published */ relays?: string[]; /** * Optional pubkey to use for P2PK lock */ p2pk?: string; /** * Tags to include in the proof secrets (e.g., [["e", "event-id"], ["P", "sender-pubkey"]]) * These tags will be added to the P2PK lock structure for replay protection and sender verification. */ proofTags?: [string, string][]; /** * Intramint fallback allowed: * * When set to true, if cross-mint payments fail, we will * fallback to sending an intra-mint payment. */ allowIntramintFallback?: boolean; }; type NDKZapConfirmationCashu = NDKNutzap; /** * This is what a wallet implementing Cashu payments should provide back * when a payment has been requested. */ type NDKPaymentConfirmationCashu = { /** * Proof of the payment */ proofs: Proof$1[]; /** * Mint */ mint: string; }; type NDKZapDetails = T & { /** * Target of the zap */ target: NDKEvent | NDKUser; /** * Comment for the zap */ comment?: string; /** * Tags to add to the zap */ tags?: NDKTag[]; /** * Pubkey of the user to zap to */ recipientPubkey: string; /** * Amount of the payment */ amount: number; /** * Unit of the payment (e.g. msat) */ unit: string; /** * Description of the payment for the sender's record */ paymentDescription?: string; /** * If this payment is for a nip57 zap, this will contain the zap request. */ nip57ZapRequest?: NDKEvent; /** * When set to true, when a pubkey is not zappable, we will * automatically fallback to using NIP-61. * * Every pubkey must be able to receive money. * * @default false */ nutzapAsFallback?: boolean; }; type NDKZapConfirmation = NDKZapConfirmationLN | NDKZapConfirmationCashu; type NDKPaymentConfirmation = NDKPaymentConfirmationLN | NDKNutzap; type NDKZapSplit = { pubkey: string; amount: number; }; type NDKZapMethod = "nip57" | "nip61"; type NDKLnLudData = { lud06?: string; lud16?: string; }; type NDKZapMethodInfo = NDKLnLudData | CashuPaymentInfo; type LnPayCb = (payment: NDKZapDetails) => Promise; type CashuPayCb = (payment: NDKZapDetails, onLnInvoice?: (pr: string) => void) => Promise; type OnCompleteCb = (results: Map) => void; interface NDKZapperOptions { /** * Comment to include in the zap event */ comment?: string; /** * Extra tags to add to the zap event */ tags?: NDKTag[]; signer?: NDKSigner; lnPay?: LnPayCb; cashuPay?: CashuPayCb; onComplete?: OnCompleteCb; nutzapAsFallback?: boolean; ndk?: NDK; } /** * */ declare class NDKZapper extends EventEmitter<{ /** * An LN invoice has been fetched. * @param param0 * @returns */ ln_invoice: ({ amount, recipientPubkey, unit, nip57ZapRequest, pr, type, }: { amount: number; recipientPubkey: string; unit: string; nip57ZapRequest?: NDKEvent; pr: string; type: NDKZapMethod; }) => void; ln_payment: ({ preimage, amount, recipientPubkey, unit, nip57ZapRequest, pr, }: { preimage: string; amount: number; recipientPubkey: string; pr: string; unit: string; nip57ZapRequest?: NDKEvent; type: NDKZapMethod; }) => void; /** * Emitted when a zap split has been completed */ "split:complete": (split: NDKZapSplit, info: NDKPaymentConfirmation | Error | undefined) => void; complete: (results: Map) => void; notice: (message: string) => void; }> { target: NDKEvent | NDKUser; ndk: NDK; comment?: string; amount: number; unit: string; tags?: NDKTag[]; signer?: NDKSigner; zapMethod?: NDKZapMethod; nutzapAsFallback?: boolean; lnPay?: LnPayCb; /** * Called when a cashu payment is to be made. * This function should swap/mint proofs for the required amount, in the required unit, * in any of the provided mints and return the proofs and mint used. */ cashuPay?: CashuPayCb; onComplete?: OnCompleteCb; maxRelays: number; /** * * @param target The target of the zap * @param amount The amount to send indicated in the unit * @param unit The unit of the amount * @param opts Options for the zap */ constructor(target: NDKEvent | NDKUser, amount: number, unit?: string, opts?: NDKZapperOptions); /** * Initiate zapping process * * This function will calculate the splits for this zap and initiate each zap split. */ zap(methods?: NDKZapMethod[]): Promise>; private zapNip57; /** * Fetches information about a NIP-61 zap and asks the caller to create cashu proofs for the zap. * * (note that the cashuPay function can use any method to create the proofs, including using lightning * to mint proofs in the specified mint, the responsibility of minting the proofs is delegated to the caller (e.g. ndk-wallet)) */ zapNip61(split: NDKZapSplit, data?: CashuPaymentInfo): Promise; /** * Get the zap methods available for the recipient and initiates the zap * in the desired method. * @param split * @param methods - The methods to try, if not provided, all methods will be tried. * @returns */ zapSplit(split: NDKZapSplit, methods?: NDKZapMethod[]): Promise; /** * Gets a bolt11 for a nip57 zap * @param event * @param amount * @param zapEndpoint * @returns */ getLnInvoice(zapRequest: NDKEvent, amount: number, data: NDKLnUrlData): Promise; getZapSplits(): NDKZapSplit[]; /** * Get the zap methods available for all recipients (all splits) * Returns a map of pubkey -> zap methods for that recipient * * @example * ```ts * const zapper = new NDKZapper(event, 1000, "msat"); * const methods = await zapper.getRecipientZapMethods(); * for (const [pubkey, zapMethods] of methods) { * console.log(`${pubkey} accepts:`, Array.from(zapMethods.keys())); * } * ``` */ getRecipientZapMethods(timeout?: number): Promise>>; /** * Gets the zap method that should be used to zap a pubbkey * @param ndk * @param pubkey * @returns */ getZapMethods(ndk: NDK, recipient: Hexpubkey, timeout?: number): Promise>; /** * @returns the relays to use for the zap request */ relays(pubkey: Hexpubkey): Promise; } type QueueItem = { /** * Deterministic id of the item */ id: string; /** * A function to process the item * @returns */ func: () => Promise; }; declare class Queue { private queue; private maxConcurrency; private processing; private promises; constructor(_name: string, maxConcurrency: number); add(item: QueueItem): Promise; private process; clear(): void; clearProcessing(): void; clearAll(): void; length(): number; } type NDKValidationRatioFn = (relay: NDKRelay, validatedCount: number, nonValidatedCount: number) => number; type NDKNetDebug = (msg: string, relay: NDKRelay, direction?: "send" | "recv") => void; /** * An interface compatible with ndk-wallet that allows setting multiple handlers and callbacks. */ interface NDKWalletInterface { lnPay?: LnPayCb; cashuPay?: CashuPayCb; onPaymentComplete?: (results: Map) => void; } interface NDKConstructorParams { /** * Relays we should explicitly connect to */ explicitRelayUrls?: string[]; /** * When this is set, we always write only to this relays. */ devWriteRelayUrls?: string[]; /** * Outbox relay URLs. */ outboxRelayUrls?: string[]; /** * Enable outbox model (defaults to true) */ enableOutboxModel?: boolean; /** * Auto-connect to main user's relays. The "main" user is determined * by the presence of a signer. Upon connection to the explicit relays, * the user's relays will be fetched and connected to if this is set to true. * @default true */ autoConnectUserRelays?: boolean; /** * Signer to use for signing events by default */ signer?: NDKSigner; /** * Cache adapter to use for caching events */ cacheAdapter?: NDKCacheAdapter; /** * Debug instance to use */ debug?: debug$1.Debugger; /** * Provide a caller function to receive all networking traffic from relays */ netDebug?: NDKNetDebug; /** * Custom filter function to determine if an event should be muted. * @param event - The event to check * @returns true if the event should be muted */ muteFilter?: (event: NDKEvent) => boolean; /** * Custom filter function to determine if a relay connection should be allowed. * @param relayUrl - The relay URL to check * @returns true if the connection should be allowed, false to block it */ relayConnectionFilter?: (relayUrl: string) => boolean; /** * Client name to add to events' tag */ clientName?: string; /** * Client nip89 to add to events' tag */ clientNip89?: string; /** * Default relay-auth policy */ relayAuthDefaultPolicy?: NDKAuthPolicy; /** * Set a Web Worker for signature verification. * * @default undefined * * When provided, signature verification will be processed in a web worker. * You should listen for the `event:invalid-sig` event to handle invalid signatures. * * @example * ```typescript * const worker = new Worker("path/to/signature-verification.js"); * ndk.signatureVerificationWorker = worker; * ndk.on("event:invalid-sig", (event) => { * console.error("Invalid signature", event); * }); * ``` */ signatureVerificationWorker?: Worker | undefined; /** * The signature verification validation ratio for new relays. */ initialValidationRatio?: number; /** * The lowest validation ratio any single relay can have. * Relays will have a sample of events verified based on this ratio. * When using this, you MUST listen for event:invalid-sig events * to handle invalid signatures and disconnect from evil relays. * * @default 0.1 */ lowestValidationRatio?: number; /** * A function that is invoked to calculate the validation ratio for a relay. */ validationRatioFn?: NDKValidationRatioFn; /** * A custom function to verify event signatures. * When provided, this function will be used instead of the default verification logic. * This is particularly useful for platforms like React Native where Web Workers are not available. * * @example * ```typescript * import { verifySignatureAsync } from "@nostr-dev-kit/mobile"; * * const ndk = new NDK({ * signatureVerificationFunction: verifySignatureAsync * }); * ``` */ signatureVerificationFunction?: (event: NDKEvent) => Promise; /** * Filter validation mode for subscriptions. * * @default "validate" - Throws an error when filters contain undefined values * "fix" - Automatically removes undefined values from filters * "ignore" - Skip validation entirely (legacy behavior) */ filterValidationMode?: "validate" | "fix" | "ignore"; /** * ⚠️ STRONGLY RECOMMENDED: Enable AI Guardrails during development * * AI Guardrails catch 90% of common mistakes before they cause silent failures: * - Using bech32 (npub/note1) in filter arrays instead of hex * - Missing required fields on events (kind, content, etc.) * - Invalid tag formats and duplicate tags * - Performance anti-patterns (fetchEvents abuse, no cache adapter) * - Wrong data types (milliseconds vs seconds for created_at) * * When enabled, you'll get clear, actionable error messages instead of silent failures. * * @default false - Guardrails are disabled (zero performance impact) * * @example RECOMMENDED: Enable during development * ```typescript * const ndk = new NDK({ * explicitRelayUrls: ['wss://relay.primal.net'], * aiGuardrails: true // ⚠️ Enable this! * }); * ``` * * @example Disable in production * ```typescript * const ndk = new NDK({ * aiGuardrails: process.env.NODE_ENV !== 'production' * }); * ``` * * @example Enable with specific checks disabled * ```typescript * const ndk = new NDK({ * aiGuardrails: { skip: new Set(['filter-large-limit']) } * }); * ``` * * @example Programmatic control * ```typescript * ndk.aiGuardrails.skip('fetch-events-usage'); * ndk.aiGuardrails.enable('filter-bech32-in-array'); * ``` * * @see https://github.com/nostr-dev-kit/ndk/tree/master/ndk/src/ai-guardrails */ aiGuardrails?: boolean | { skip?: Set; }; /** * Optional grace period (in seconds) for future timestamps. * * When set, subscriptions will automatically discard events where * `created_at` is more than this many seconds ahead of the current time. * This helps protect against malicious relays sending events with * manipulated timestamps. * * Set to `undefined` (default) to disable this check and accept all events * regardless of timestamp. * * @default undefined * * @example Reject events more than 5 minutes in the future * ```typescript * const ndk = new NDK({ * explicitRelayUrls: ['wss://relay.primal.net'], * futureTimestampGrace: 300 // 5 minutes * }); * ``` */ futureTimestampGrace?: number; } interface GetUserParams extends NDKUserParams { npub?: string; pubkey?: string; /** * @deprecated Use `pubkey` instead */ hexpubkey?: string; } /** * Defines handlers that can be passed to `ndk.subscribe` via the `autoStart` parameter * to react to subscription lifecycle events. */ interface NDKSubscriptionEventHandlers { /** * Called for each individual event received from relays *after* the initial cache load (if `onEvents` is provided), * or for *all* events (including cached ones) if `onEvents` is not provided. * @param event The received NDKEvent. * @param relay The relay the event was received from (undefined if from cache). */ onEvent?: (event: NDKEvent, relay?: NDKRelay) => void; /** * Called *once* with an array of all events found synchronously in the cache when the subscription starts. * If this handler is provided, `onEvent` will *not* be called for this initial batch of cached events. * This is useful for bulk processing or batching UI updates based on the initial cached state. * @param events An array of NDKEvents loaded synchronously from the cache. */ onEvents?: (events: NDKEvent[]) => void; /** * Called when the subscription receives an EOSE (End of Stored Events) marker * from all connected relays involved in this subscription request. * @param sub The NDKSubscription instance that reached EOSE. */ onEose?: (sub: NDKSubscription) => void; /** * Called when the subscription is closed. * @param sub The NDKSubscription instance that was closed. */ onClose?: (sub: NDKSubscription) => void; } /** * The NDK class is the main entry point to the library. * * @emits signer:ready when a signer is ready * @emits activeUser:change when the active user changes * @emits invalid-signature when an event with an invalid signature is received */ declare class NDK extends EventEmitter<{ "signer:ready": (signer: NDKSigner) => void; "signer:required": () => void; /** * Emitted when the active user changes. * This can happen when a signer is set or when activeUser is set directly. */ "activeUser:change": (user: NDKUser | undefined) => void; /** * Emitted when an event with an invalid signature is received. * Includes the relay that provided the invalid signature. */ "event:invalid-sig": (event: NDKEvent, relay?: NDKRelay) => void; /** * Emitted when an event fails to publish. * @param event The event that failed to publish * @param error The error that caused the event to fail to publish * @param relays The relays that the event was attempted to be published to */ "event:publish-failed": (event: NDKEvent, error: NDKPublishError, relays: WebSocket["url"][]) => void; }> { private _explicitRelayUrls?; pool: NDKPool; outboxPool?: NDKPool; private _signer?; private _activeUser?; cacheAdapter?: NDKCacheAdapter; debug: debug$1.Debugger; devWriteRelaySet?: NDKRelaySet; outboxTracker?: OutboxTracker; muteFilter?: (event: NDKEvent) => boolean; relayConnectionFilter?: (relayUrl: string) => boolean; clientName?: string; clientNip89?: string; queuesZapConfig: Queue; queuesNip05: Queue; asyncSigVerification: boolean; initialValidationRatio: number; lowestValidationRatio: number; validationRatioFn?: NDKValidationRatioFn; filterValidationMode: "validate" | "fix" | "ignore"; subManager: NDKSubscriptionManager; aiGuardrails: AIGuardrails; futureTimestampGrace?: number; /** * Private storage for the signature verification function */ private _signatureVerificationFunction?; /** * Private storage for the signature verification worker */ private _signatureVerificationWorker?; /** * Rolling total of time spent (in ms) performing signature verifications. * Users can read this to monitor or display aggregate verification cost. */ signatureVerificationTimeMs: number; publishingFailureHandled: boolean; pools: NDKPool[]; /** * Default relay-auth policy that will be used when a relay requests authentication, * if no other policy is specified for that relay. * * @example Disconnect from relays that request authentication: * ```typescript * ndk.relayAuthDefaultPolicy = NDKAuthPolicies.disconnect(ndk.pool); * ``` * * @example Sign in to relays that request authentication: * ```typescript * ndk.relayAuthDefaultPolicy = NDKAuthPolicies.signIn({ndk}) * ``` * * @example Sign in to relays that request authentication, asking the user for confirmation: * ```typescript * ndk.relayAuthDefaultPolicy = (relay: NDKRelay) => { * const signIn = NDKAuthPolicies.signIn({ndk}); * if (confirm(`Relay ${relay.url} is requesting authentication, do you want to sign in?`)) { * signIn(relay); * } * } * ``` */ relayAuthDefaultPolicy?: NDKAuthPolicy; /** * Fetch function to use for HTTP requests. * * @example * ```typescript * import fetch from "node-fetch"; * * ndk.httpFetch = fetch; * ``` */ httpFetch: typeof fetch | undefined; /** * Provide a caller function to receive all networking traffic from relays */ readonly netDebug?: NDKNetDebug; autoConnectUserRelays: boolean; private _wallet?; walletConfig?: NDKWalletInterface; constructor(opts?: NDKConstructorParams); set explicitRelayUrls(urls: WebSocket["url"][]); get explicitRelayUrls(): WebSocket["url"][]; /** * Set a Web Worker for signature verification. * * This method initializes the worker and sets the asyncSigVerification flag. * The actual verification is handled by the verifySignatureAsync function in signature.ts, * which will use the worker if available. */ set signatureVerificationWorker(worker: Worker | undefined); /** * Set a custom signature verification function. * * This method is particularly useful for platforms that don't support Web Workers, * such as React Native. * * When a function is provided, it will be used for signature verification * instead of the default worker-based verification. This enables signature * verification on platforms where Web Workers are not available. * * @example * ```typescript * import { verifySignatureAsync } from "@nostr-dev-kit/mobile"; * * ndk.signatureVerificationFunction = verifySignatureAsync; * ``` */ set signatureVerificationFunction(fn: ((event: NDKEvent) => Promise) | undefined); /** * Get the custom signature verification function */ get signatureVerificationFunction(): ((event: NDKEvent) => Promise) | undefined; /** * Adds an explicit relay to the pool. * @param url * @param relayAuthPolicy Authentication policy to use if different from the default * @param connect Whether to connect to the relay automatically * @returns */ addExplicitRelay(urlOrRelay: string | NDKRelay, relayAuthPolicy?: NDKAuthPolicy, connect?: boolean): NDKRelay; toJSON(): string; get activeUser(): NDKUser | undefined; /** * Sets the active user for this NDK instance, typically this will be * called when assigning a signer to the NDK instance. * * This function will automatically connect to the user's relays if * `autoConnectUserRelays` is set to true. */ set activeUser(user: NDKUser | undefined); get signer(): NDKSigner | undefined; set signer(newSigner: NDKSigner | undefined); /** * Connect to relays with optional timeout. * If the timeout is reached, the connection will be continued to be established in the background. */ connect(timeoutMs?: number): Promise; /** * Centralized method to report an invalid signature, identifying the relay that provided it. * A single invalid signature means the relay is considered malicious. * All invalid signature detections (synchronous or asynchronous) should delegate to this method. * * @param event The event with an invalid signature * @param relay The relay that provided the invalid signature */ reportInvalidSignature(event: NDKEvent, relay?: NDKRelay): void; /** * Default function to calculate validation ratio based on historical validation results. * The more events validated successfully, the lower the ratio goes (down to the minimum). */ private defaultValidationRatioFn; /** * Get a NDKUser object * * @deprecated Use `fetchUser` instead - this method will be removed in the next major version * @param opts - User parameters object or a string (npub, nprofile, or hex pubkey) * @returns NDKUser instance * * @example * ```typescript * // Using parameters object * const user1 = ndk.getUser({ pubkey: "hex..." }); * * // Using npub string * const user2 = ndk.getUser("npub1..."); * * // Using nprofile string (includes relay hints) * const user3 = ndk.getUser("nprofile1..."); * * // Using hex pubkey directly * const user4 = ndk.getUser("deadbeef..."); * ``` */ getUser(opts: GetUserParams | string): NDKUser; /** * Get a NDKUser from a NIP05 * @deprecated Use `fetchUser` instead - this method will be removed in the next major version * @param nip05 NIP-05 ID * @param skipCache Skip cache * @returns */ getUserFromNip05(nip05: string, skipCache?: boolean): Promise; /** * Fetch a NDKUser from a string identifier * * Supports multiple input formats: * - NIP-05 identifiers (e.g., "pablo@test.com" or "test.com") * - npub (NIP-19 encoded public key) * - nprofile (NIP-19 encoded profile with optional relay hints) * - Hex public key * * @param input - String identifier for the user (NIP-05, npub, nprofile, or hex pubkey) * @param skipCache - Skip cache when resolving NIP-05 (only applies to NIP-05 lookups) * @returns Promise resolving to NDKUser or undefined if not found * * @example * ```typescript * // Using NIP-05 * const user1 = await ndk.fetchUser("pablo@test.com"); * const user2 = await ndk.fetchUser("test.com"); // defaults to _@test.com * * // Using npub * const user3 = await ndk.fetchUser("npub1..."); * * // Using nprofile (includes relay hints) * const user4 = await ndk.fetchUser("nprofile1..."); * * // Using hex pubkey * const user5 = await ndk.fetchUser("deadbeef..."); * ``` */ fetchUser(input: string, skipCache?: boolean): Promise; /** * Creates and starts a new subscription. * * Subscriptions automatically start unless `autoStart` is set to `false`. * You can control automatic closing on EOSE via `opts.closeOnEose`. * * @param filters - A single NDKFilter object or an array of filters. * @param opts - Optional NDKSubscriptionOptions to customize behavior (e.g., caching, grouping). * @param handlers - Optional handlers for subscription events. Passing handlers is the preferred method of using ndk.subscribe. * - `onEvent`: Called for each event received. * - `onEvents`: Called once with an array of events when the subscription starts (from the cache). * - `onEose`: Called when the subscription receives EOSE. * For backwards compatibility, this third parameter also accepts a relaySet, the relaySet should be passed via `opts.relaySet`. * * @param _autoStart - For backwards compatibility, this can be a boolean indicating whether to start the subscription immediately. * This parameter is deprecated and will be removed in a future version. * - `false`: Creates the subscription but does not start it (call `subscription.start()` manually). * @returns The created NDKSubscription instance. * * @example Basic subscription * ```typescript * const sub = ndk.subscribe( * { kinds: [1], authors: [pubkey] }, * { * onEvent: (event) => console.log("Kind 1 event:", event.content) * } * ); * ``` * * @example Subscription with options and direct handlers * ```typescript * const sub = ndk.subscribe( * { kinds: [0], authors: [pubkey] }, * { * closeOnEose: true, * cacheUsage: NDKSubscriptionCacheUsage.PARALLEL, * onEvents: (events) => console.log(`Got ${events.length} profile events from cache:`, events[0].content), * onEvent: (event) => console.log("Got profile update from relay:", event.content), * onEose: () => console.log("Profile subscription finished.") * } * ); * ``` * * @since 2.13.0 `relaySet` parameter removed; pass `relaySet` or `relayUrls` via `opts`. */ subscribe(filters: NDKFilter | NDKFilter[], opts?: NDKSubscriptionOptions, autoStartOrRelaySet?: NDKRelaySet | boolean | NDKSubscriptionEventHandlers, _autoStart?: boolean): NDKSubscription; /** * Attempts to fetch an event from a tag, following relay hints and * other best practices. * @param tag Tag to fetch the event from * @param originalEvent Event where the tag came from * @param subOpts Subscription options to use when fetching the event * @param fallback Fallback options to use when the hint relay doesn't respond * @returns */ fetchEventFromTag: (tag: NDKTag, originalEvent: NDKEvent, subOpts?: NDKSubscriptionOptions | undefined, fallback?: NDKFetchFallbackOptions | undefined) => Promise; /** * Fetch an event from the cache synchronously. * @param idOrFilter event id in bech32 format or filter * @returns events from the cache or null if the cache is empty */ fetchEventSync(idOrFilter: string | NDKFilter[]): NDKEvent[] | null; /** * Fetch a single event. * * @param idOrFilter event id in bech32 format or filter * @param opts subscription options * @param relaySetOrRelay explicit relay set to use */ fetchEvent(idOrFilter: string | NDKFilter | NDKFilter[], opts?: NDKSubscriptionOptions, relaySetOrRelay?: NDKRelaySet | NDKRelay): Promise; /** * Fetch events */ fetchEvents(filters: NDKFilter | NDKFilter[], opts?: NDKSubscriptionOptions, relaySet?: NDKRelaySet): Promise>; /** * Count events matching the given filters using NIP-45. * * This method queries multiple relays and aggregates their COUNT responses. * When relays return HyperLogLog (HLL) data, it uses the HLL algorithm to * provide accurate cardinality estimation without double-counting events * that appear on multiple relays. * * @param filters - The filters to count events for * @param opts - Optional count options (timeout, custom id) * @param relaySet - Optional relay set to use for the count request * @returns An aggregated count result with the best estimate and per-relay results * * @example Basic count * ```typescript * const result = await ndk.count([{ kinds: [1], authors: [pubkey] }]); * console.log(`Found approximately ${result.count} events`); * ``` * * @example Count with specific relays * ```typescript * const relaySet = NDKRelaySet.fromRelayUrls(['wss://relay1.com', 'wss://relay2.com'], ndk); * const result = await ndk.count([{ kinds: [7], "#e": [eventId] }], {}, relaySet); * console.log(`Approximately ${result.count} reactions`); * ``` * * @example Using HLL data for further analysis * ```typescript * const result = await ndk.count([{ kinds: [3] }]); * if (result.mergedHll) { * console.log('HLL data available for further merging'); * } * ``` */ count(filters: NDKFilter | NDKFilter[], opts?: NDKCountOptions, relaySet?: NDKRelaySet): Promise; /** * Ensures that a signer is available to sign an event. */ assertSigner(): void; getEntity: (entity: string) => NDKUser | nip19$1.DecodedNevent | nip19$1.DecodedNaddr | nip19$1.DecodedNsec | nip19$1.DecodedNote | null; /** * Temporarily disable AI guardrails for the next method call. * * @param ids - Optional guardrail IDs to disable. If omitted, all guardrails are disabled for the next call. * Can be a single string or an array of strings. * @returns This NDK instance for method chaining * * @example Disable all guardrails for one call * ```typescript * ndk.guardrailOff().fetchEvents({ kinds: [1] }); * ``` * * @example Disable specific guardrail * ```typescript * ndk.guardrailOff('fetch-events-usage').fetchEvents({ kinds: [1] }); * ``` * * @example Disable multiple guardrails * ```typescript * ndk.guardrailOff(['fetch-events-usage', 'filter-large-limit']).fetchEvents({ kinds: [1], limit: 5000 }); * ``` */ guardrailOff(ids?: string | string[]): this; set wallet(wallet: NDKWalletInterface | undefined); get wallet(): NDKWalletInterface | undefined; } type ContentTag = { tags: NDKTag[]; content: string; }; /** * Merges two arrays of NDKTag, ensuring uniqueness and preferring more specific tags. * * This function consolidates `tags1` and `tags2` by: * - Combining both tag arrays. * - Removing duplicate tags based on containment (one tag containing another). * - Retaining the longer or more detailed tag when overlaps are found. * * @param tags1 - The first array of NDKTag. * @param tags2 - The second array of NDKTag. * @returns A merged array of unique NDKTag. */ declare function mergeTags(tags1: NDKTag[], tags2: NDKTag[]): NDKTag[]; /** * Compares a tag to see if they are the same or if one is preferred * over the other (i.e. it includes more information) and returns * the tags that should be used. * @returns */ declare function uniqueTag(a: NDKTag, b: NDKTag): NDKTag[]; /** * Generates a unique list of hashtags as used in the content. If multiple variations * of the same hashtag are used, only the first one will be used (#ndk and #NDK both resolve to the first one that was used in the content) * @param content * @returns */ declare function generateHashtags(content: string): string[]; declare function generateContentTags(content: string, tags?: NDKTag[], opts?: ContentTaggingOptions, ctx?: NDKEvent): Promise; /** * NIP-73 entity types */ type NIP73EntityType = "url" | "hashtag" | "geohash" | "isbn" | "podcast:guid" | "podcast:item:guid" | "podcast:publisher:guid" | "isan" | "doi"; type NDKEventSerialized = string; /** * Serializes an event object into a string representation. * * @param this - The event object to serialize. * @returns A string representation of the serialized event. */ declare function serialize(this: NDKEvent | NostrEvent, includeSig?: boolean, includeId?: boolean): NDKEventSerialized; /** * Deserialize a nostr event from a string * @param serializedEvent string * @returns NostrEvent */ declare function deserialize(serializedEvent: NDKEventSerialized): NostrEvent; type NDKEventId = string; type NDKTag = string[]; type ParsedContentMatch = { original: string; decoded: string; type: "npub" | "nprofile" | "note" | "nevent" | "naddr"; data: any; }; type ContentTaggingOptions = { skipContentTagging?: boolean; pTagOnQTags?: boolean; pTagOnATags?: boolean; pTags?: boolean; copyPTagsFromTarget?: boolean; filters?: { includeTypes?: Array<"npub" | "nprofile" | "note" | "nevent" | "naddr" | "hashtag">; excludeTypes?: Array<"npub" | "nprofile" | "note" | "nevent" | "naddr" | "hashtag">; }; }; type NostrEvent = { created_at: number; content: string; tags: NDKTag[]; kind?: NDKKind | number; pubkey: string; id?: string; sig?: string; }; /** * A finalized event */ type NDKRawEvent = { created_at: number; content: string; tags: NDKTag[]; kind: NDKKind | number; pubkey: string; id: string; sig: string; }; /** * NDKEvent is the basic building block of NDK; most things * you do with NDK will revolve around writing or consuming NDKEvents. */ declare class NDKEvent extends EventEmitter { ndk?: NDK; created_at?: number; content: string; tags: NDKTag[]; kind: NDKKind | number; id: string; sig?: string; pubkey: string; signatureVerified?: boolean; private _author; /** * The relay that this event was first received from. */ relay: NDKRelay | undefined; /** * The relays that this event was received from and/or successfully published to. */ get onRelays(): NDKRelay[]; /** * The status of the publish operation. */ publishStatus?: "pending" | "success" | "error"; publishError?: Error; constructor(ndk?: NDK, event?: Partial | NDKEvent); /** * Deserialize an NDKEvent from a serialized payload. * @param ndk * @param event * @returns */ static deserialize(ndk: NDK | undefined, event: NDKEventSerialized): NDKEvent; /** * Returns the event as is. */ rawEvent(): NDKRawEvent; set author(user: NDKUser); /** * Returns an NDKUser for the author of the event. */ get author(): NDKUser; /** * NIP-73 tagging of external entities * @param entity to be tagged * @param type of the entity * @param markerUrl to be used as the marker URL * * @example * ```typescript * event.tagExternal("https://example.com/article/123#nostr", "url"); * event.tags => [["i", "https://example.com/123"], ["k", "https://example.com"]] * ``` * * @example tag a podcast:item:guid * ```typescript * event.tagExternal("e32b4890-b9ea-4aef-a0bf-54b787833dc5", "podcast:item:guid"); * event.tags => [["i", "podcast:item:guid:e32b4890-b9ea-4aef-a0bf-54b787833dc5"], ["k", "podcast:item:guid"]] * ``` * * @see https://github.com/nostr-protocol/nips/blob/master/73.md */ tagExternal(entity: string, type: NIP73EntityType, markerUrl?: string): void; /** * Tag a user with an optional marker. * @param target What is to be tagged. Can be an NDKUser, NDKEvent, or an NDKTag. * @param marker The marker to use in the tag. * @param skipAuthorTag Whether to explicitly skip adding the author tag of the event. * @param forceTag Force a specific tag to be used instead of the default "e" or "a" tag. * @param opts Optional content tagging options to control p tag behavior. * @example * ```typescript * reply.tag(opEvent, "reply"); * // reply.tags => [["e", , , "reply"]] * ``` */ tag(target: NDKTag | NDKUser | NDKEvent, marker?: string, skipAuthorTag?: boolean, forceTag?: string, opts?: ContentTaggingOptions): void; /** * Return a NostrEvent object, trying to fill in missing fields * when possible, adding tags when necessary. * @param pubkey {string} The pubkey of the user who the event belongs to. * @param opts {ContentTaggingOptions} Options for content tagging. * @returns {Promise} A promise that resolves to a NostrEvent. */ toNostrEvent(pubkey?: string, opts?: ContentTaggingOptions): Promise; serialize: (includeSig?: boolean | undefined, includeId?: boolean | undefined) => string; getEventHash: () => string; validate: () => boolean; verifySignature: (persist: boolean) => boolean | undefined; /** * Is this event replaceable (whether parameterized or not)? * * This will return true for kind 0, 3, 10k-20k and 30k-40k */ isReplaceable: () => boolean; isEphemeral: () => boolean; isDvm: () => boolean | 0; /** * Is this event parameterized replaceable? * * This will return true for kind 30k-40k */ isParamReplaceable: () => boolean; /** * Encodes a bech32 id. * * @param relays {string[]} The relays to encode in the id * @returns {string} - Encoded naddr, note or nevent. */ encode: (maxRelayCount?: number | undefined) => string; encrypt: (recipient?: NDKUser | undefined, signer?: NDKSigner | undefined, scheme?: NDKEncryptionScheme | undefined) => Promise; decrypt: (sender?: NDKUser | undefined, signer?: NDKSigner | undefined, scheme?: NDKEncryptionScheme | undefined) => Promise; /** * Get all tags with the given name * @param tagName {string} The name of the tag to search for * @returns {NDKTag[]} An array of the matching tags */ getMatchingTags(tagName: string, marker?: string): NDKTag[]; /** * Check if the event has a tag with the given name * @param tagName * @param marker * @returns */ hasTag(tagName: string, marker?: string): boolean; /** * Get the first tag with the given name * @param tagName Tag name to search for * @returns The value of the first tag with the given name, or undefined if no such tag exists */ tagValue(tagName: string, marker?: string): string | undefined; /** * Gets the NIP-31 "alt" tag of the event. */ get alt(): string | undefined; /** * Sets the NIP-31 "alt" tag of the event. Use this to set an alt tag so * clients that don't handle a particular event kind can display something * useful for users. */ set alt(alt: string | undefined); /** * Gets the NIP-33 "d" tag of the event. */ get dTag(): string | undefined; /** * Sets the NIP-33 "d" tag of the event. */ set dTag(value: string | undefined); /** * Remove all tags with the given name (e.g. "d", "a", "p") * @param tagName Tag name(s) to search for and remove * @param marker Optional marker to check for too * * @example * Remove a tags with a "defer" marker * ```typescript * event.tags = [ * ["a", "....", "defer"], * ["a", "....", "no-defer"], * ] * * event.removeTag("a", "defer"); * * // event.tags => [["a", "....", "no-defer"]] * * @returns {void} */ removeTag(tagName: string | string[], marker?: string): void; /** * Replace a tag with a new value. If not found, it will be added. * @param tag The tag to replace. * @param value The new value for the tag. */ replaceTag(tag: NDKTag): void; /** * Sign the event if a signer is present. * * It will generate tags. * Repleacable events will have their created_at field set to the current time. * @param signer {NDKSigner} The NDKSigner to use to sign the event * @param opts {ContentTaggingOptions} Options for content tagging. * @returns {Promise} A Promise that resolves to the signature of the signed event. */ sign(signer?: NDKSigner, opts?: ContentTaggingOptions): Promise; /** * * @param relaySet * @param timeoutMs * @param requiredRelayCount * @returns */ publishReplaceable(relaySet?: NDKRelaySet, timeoutMs?: number, requiredRelayCount?: number): Promise>; /** * Attempt to sign and then publish an NDKEvent to a given relaySet. * If no relaySet is provided, the relaySet will be calculated by NDK. * @param relaySet {NDKRelaySet} The relaySet to publish the even to. * @param timeoutM {number} The timeout for the publish operation in milliseconds. * @param requiredRelayCount The number of relays that must receive the event for the publish to be considered successful. * @param opts {ContentTaggingOptions} Options for content tagging. * @returns A promise that resolves to the relays the event was published to. */ publish(relaySet?: NDKRelaySet, timeoutMs?: number, requiredRelayCount?: number, opts?: ContentTaggingOptions): Promise>; /** * Generates tags for users, notes, and other events tagged in content. * Will also generate random "d" tag for parameterized replaceable events where needed. * @param opts {ContentTaggingOptions} Options for content tagging. * @returns {ContentTag} The tags and content of the event. */ generateTags(opts?: ContentTaggingOptions): Promise; get shouldAddClientTag(): boolean; get shouldStripClientTag(): boolean; muted(): string | null; /** * Returns the "d" tag of a parameterized replaceable event or throws an error if the event isn't * a parameterized replaceable event. * @returns {string} the "d" tag of the event. * * @deprecated Use `dTag` instead. */ replaceableDTag(): string; /** * Provides a deduplication key for the event. * * For kinds 0, 3, 10k-20k this will be the event : * For kinds 30k-40k this will be the event :: * For all other kinds this will be the event id */ deduplicationKey(): string; /** * Returns the id of the event or, if it's a parameterized event, the generated id of the event using "d" tag, pubkey, and kind. * @returns {string} The id */ tagId(): string; /** * Returns a stable reference value for a replaceable event. * * Param replaceable events are returned in the expected format of `::`. * Kind-replaceable events are returned in the format of `::`. * * @returns {string} A stable reference value for replaceable events */ tagAddress(): string; /** * Determines the type of tag that can be used to reference this event from another event. * @returns {string} The tag type * @example * event = new NDKEvent(ndk, { kind: 30000, pubkey: 'pubkey', tags: [ ["d", "d-code"] ] }); * event.tagType(); // "a" */ tagType(): "e" | "a"; /** * Get the tag that can be used to reference this event from another event. * * Consider using referenceTags() instead (unless you have a good reason to use this) * * @example * event = new NDKEvent(ndk, { kind: 30000, pubkey: 'pubkey', tags: [ ["d", "d-code"] ] }); * event.tagReference(); // ["a", "30000:pubkey:d-code"] * * event = new NDKEvent(ndk, { kind: 1, pubkey: 'pubkey', id: "eventid" }); * event.tagReference(); // ["e", "eventid"] * @returns {NDKTag} The NDKTag object referencing this event */ tagReference(marker?: string): NDKTag; /** * Get the tags that can be used to reference this event from another event * @param marker The marker to use in the tag * @param skipAuthorTag Whether to explicitly skip adding the author tag of the event * @param forceTag Force a specific tag to be used instead of the default "e" or "a" tag * @example * event = new NDKEvent(ndk, { kind: 30000, pubkey: 'pubkey', tags: [ ["d", "d-code"] ] }); * event.referenceTags(); // [["a", "30000:pubkey:d-code"], ["e", "parent-id"]] * * event = new NDKEvent(ndk, { kind: 1, pubkey: 'pubkey', id: "eventid" }); * event.referenceTags(); // [["e", "parent-id"]] * @returns {NDKTag} The NDKTag object referencing this event */ referenceTags(marker?: string, skipAuthorTag?: boolean, forceTag?: string, opts?: ContentTaggingOptions): NDKTag[]; /** * Provides the filter that will return matching events for this event. * * @example * event = new NDKEvent(ndk, { kind: 30000, pubkey: 'pubkey', tags: [ ["d", "d-code"] ] }); * event.filter(); // { "#a": ["30000:pubkey:d-code"] } * @example * event = new NDKEvent(ndk, { kind: 1, pubkey: 'pubkey', id: "eventid" }); * event.filter(); // { "#e": ["eventid"] } * * @returns The filter that will return matching events for this event */ filter(): NDKFilter; nip22Filter(): NDKFilter; /** * Generates a deletion event of the current event * * @param reason The reason for the deletion * @param publish Whether to publish the deletion event automatically * @returns The deletion event */ delete(reason?: string, publish?: boolean): Promise; /** * Establishes whether this is a NIP-70-protectede event. * @@satisfies NIP-70 */ set isProtected(val: boolean); /** * Whether this is a NIP-70-protected event. * @@satisfies NIP-70 */ get isProtected(): boolean; /** * Fetch an event tagged with the given tag following relay hints if provided. * @param tag The tag to search for * @param marker The marker to use in the tag (e.g. "root") * @returns The fetched event or null if no event was found, undefined if no matching tag was found in the event * * @example * const replyEvent = await ndk.fetchEvent("nevent1qqs8x8vnycyha73grv380gmvlury4wtmx0nr9a5ds2dngqwgu87wn6gpzemhxue69uhhyetvv9ujuurjd9kkzmpwdejhgq3ql2vyh47mk2p0qlsku7hg0vn29faehy9hy34ygaclpn66ukqp3afqz4cwjd") * const originalEvent = await replyEvent.fetchTaggedEvent("e", "reply"); * console.log(replyEvent.encode() + " is a reply to event " + originalEvent?.encode()); */ fetchTaggedEvent: (tag: string, marker?: string | undefined) => Promise; /** * Fetch the root event of the current event. * @returns The fetched root event or null if no event was found * @example * const replyEvent = await ndk.fetchEvent("nevent1qqs8x8vnycyha73grv380gmvlury4wtmx0nr9a5ds2dngqwgu87wn6gpzemhxue69uhhyetvv9ujuurjd9kkzmpwdejhgq3ql2vyh47mk2p0qlsku7hg0vn29faehy9hy34ygaclpn66ukqp3afqz4cwjd") * const rootEvent = await replyEvent.fetchRootEvent(); * console.log(replyEvent.encode() + " is a reply in the thread " + rootEvent?.encode()); */ fetchRootEvent: (subOpts?: NDKSubscriptionOptions | undefined) => Promise; /** * Fetch the event the current event is replying to. * @returns The fetched reply event or null if no event was found */ fetchReplyEvent: (subOpts?: NDKSubscriptionOptions | undefined) => Promise; /** * NIP-18 reposting event. * * @param publish Whether to publish the reposted event automatically @default true * @param signer The signer to use for signing the reposted event * @returns The reposted event * * @function */ repost: (publish?: boolean | undefined, signer?: NDKSigner | undefined) => Promise; /** * React to an existing event * * @param content The content of the reaction */ react(content: string, publish?: boolean): Promise; /** * Checks whether the event is valid per underlying NIPs. * * This method is meant to be overridden by subclasses that implement specific NIPs * to allow the enforcement of NIP-specific validation rules. * * Otherwise, it will only check for basic event properties. * */ get isValid(): boolean; get inspect(): string; /** * Dump the event to console for debugging purposes. * Prints a JSON stringified version of rawEvent() with indentation * and also lists all relay URLs for onRelays. */ dump(): void; /** * Creates a reply event for the current event. * * This function will use NIP-22 when appropriate (i.e. replies to non-kind:1 events). * This function does not have side-effects; it will just return an event with the appropriate tags * to generate the reply event; the caller is responsible for publishing the event. * * @param forceNip22 - Optional flag to force NIP-22 style replies (kind 1111) regardless of the original event's kind * @param opts - Optional content tagging options */ reply(forceNip22?: boolean, opts?: ContentTaggingOptions): NDKEvent; } /** * Discriminated union types for signed and unsigned events */ /** * An NDKEvent that has been signed and has all required fields for relay transmission */ type NDKSignedEvent = NDKEvent & { readonly signed: true; id: string; sig: string; created_at: number; }; /** * An NDKEvent that has not been signed yet */ type NDKUnsignedEvent = NDKEvent & { readonly signed: false; id?: string; sig?: string; created_at?: number; }; /** * Union type representing either signed or unsigned NDKEvent */ type NDKEventVariant = NDKSignedEvent | NDKUnsignedEvent; /** * Type guard to check if an event is signed */ declare function isSignedEvent(event: NDKEvent): event is NDKSignedEvent; /** * Type guard to check if an event is unsigned */ declare function isUnsignedEvent(event: NDKEvent): event is NDKUnsignedEvent; /** * Assertion function for when you know an event must be signed */ declare function assertSignedEvent(event: NDKEvent): asserts event is NDKSignedEvent; /** * Factory function to create a typed signed event (used internally by subscriptions) */ declare function createSignedEvent(event: NDKEvent): NDKSignedEvent; type NDKEncryptionScheme = "nip04" | "nip44"; declare enum NdkNutzapStatus { INITIAL = "initial", PROCESSING = "processing", REDEEMED = "redeemed", SPENT = "spent", MISSING_PRIVKEY = "missing_privkey", TEMPORARY_ERROR = "temporary_error", PERMANENT_ERROR = "permanent_error", INVALID_NUTZAP = "invalid_nutzap" } interface NDKNutzapState { nutzap?: NDKNutzap; status: NdkNutzapStatus; redeemedById?: NDKEventId; errorMessage?: string; redeemedAmount?: number; } /** * Implements NIP-78 App Settings * * @example * const appSettings = new NDKAppSettings(ndk) * appSettings.appName = "My App"; * appSettings.set("my_key", "my_value"); * await appSettings.save(); * * @example * const appSettings = NDKAppSettings.from(event); * appSettings.appName = "My App"; * console.log(appSettings.get("my_key")); * * @group Kind Wrapper * * @see https://github.com/nostr-protocol/nips/blob/master/78.md */ declare class NDKAppSettings extends NDKEvent { appName: string | undefined; settings: Record; constructor(ndk: NDK | undefined, rawEvent?: NostrEvent | NDKEvent); static from(event: NDKEvent): NDKAppSettings; /** * Set a value for a given key. * * @param key * @param value */ set(key: string, value: unknown): void; /** * Get a value for a given key. * * @param key * @returns */ get(key: string): unknown; publishReplaceable(relaySet?: NDKRelaySet, timeoutMs?: number, requiredRelayCount?: number): Promise>; } /** * Schedule a post for publishing at a later time using * a NIP-90 DVM. * * @param dvm {NDKUser} The DVM to use for scheduling. * @param relays {string[]} The relays the schedule event should be published to by the DVM. Defaults to all relays in the pool. * @param encrypted {boolean} Whether to encrypt the event. Defaults to true. * @param waitForConfirmationForMs {number} How long to wait for the DVM to confirm the schedule event. If none is provided, the event will be scheduled but not confirmed. * * @example * const event = new NDKEvent(ndk, { kind: 1, content: "hello world" }); * event.created_at = Date.now()/1000 + 60 // schedule for 60 seconds from now * await event.sign(); * * const dvm = ndk.getUser({ pubkey: "" }); * * const result = await dvmSchedule(event, dvm); * console.log(result.status); // "success" */ declare function dvmSchedule(events: NDKEvent | NDKEvent[], dvm: NDKUser, relays?: string[], encrypted?: boolean, waitForConfirmationForMs?: number): Promise; type GiftWrapParams = { scheme?: NDKEncryptionScheme; rumorKind?: number; wrapTags?: string[][]; }; /** * Instantiate a new (Nip59 gift wrapped) NDKEvent from any NDKEvent * * NIP-17 AI Guardrails - Common Mistakes to Avoid: * ❌ DON'T sign the rumor event before passing it to giftWrap (it should be unsigned) * ❌ DON'T use the wrapper's created_at for display - use the rumor's created_at * ❌ DON'T forget to publish to BOTH sender and recipient relays (per NIP-17) * * @param event - The rumor event to wrap (will auto-set pubkey if missing) * @param recipient - The recipient's NDKUser * @param signer - The signer (defaults to event.ndk.signer) * @param params - Optional parameters (scheme, rumorKind, wrapTags) * @returns The gift-wrapped event (kind 1059) */ declare function giftWrap(event: NDKEvent, recipient: NDKUser, signer?: NDKSigner, params?: GiftWrapParams): Promise; /** * Instantiate a new (Nip59 un-wrapped rumor) NDKEvent from any gift wrapped NDKEvent * @param event */ declare function giftUnwrap(event: NDKEvent, sender?: NDKUser, signer?: NDKSigner, scheme?: NDKEncryptionScheme): Promise; /** * Represents a NIP-23 article. * * @group Kind Wrapper */ declare class NDKArticle extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk: NDK | undefined, rawEvent?: NostrEvent | NDKEvent); /** * Creates a NDKArticle from an existing NDKEvent. * * @param event NDKEvent to create the NDKArticle from. * @returns NDKArticle */ static from(event: NDKEvent): NDKArticle; /** * Getter for the article title. * * @returns {string | undefined} - The article title if available, otherwise undefined. */ get title(): string | undefined; /** * Setter for the article title. * * @param {string | undefined} title - The title to set for the article. */ set title(title: string | undefined); /** * Getter for the article image. * * @returns {string | undefined} - The article image if available, otherwise undefined. */ get image(): string | undefined; /** * Setter for the article image. * * @param {string | undefined} image - The image to set for the article. */ set image(image: string | undefined); get summary(): string | undefined; set summary(summary: string | undefined); /** * Getter for the article's publication timestamp. * * @returns {number | undefined} - The Unix timestamp of when the article was published or undefined. */ get published_at(): number | undefined; /** * Setter for the article's publication timestamp. * * @param {number | undefined} timestamp - The Unix timestamp to set for the article's publication date. */ set published_at(timestamp: number | undefined); /** * Generates content tags for the article. * * This method first checks and sets the publication date if not available, * and then generates content tags based on the base NDKEvent class. * * @returns {ContentTag} - The generated content tags. */ generateTags(): Promise; /** * Getter for the article's URL. * * @returns {string | undefined} - The article's URL if available, otherwise undefined. */ get url(): string | undefined; /** * Setter for the article's URL. * * @param {string | undefined} url - The URL to set for the article. */ set url(url: string | undefined); } /** * Represents a Blossom server list for a user, kind:10063 * @group Kind Wrapper */ declare class NDKBlossomList extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk?: NDK, rawEvent?: NostrEvent); static from(ndkEvent: NDKEvent): NDKBlossomList; /** * Returns all Blossom servers in the list */ get servers(): string[]; /** * Sets the list of Blossom servers */ set servers(servers: string[]); /** * Returns the default Blossom server (first in the list) */ get default(): string | undefined; /** * Sets the default Blossom server by moving it to the beginning of the list */ set default(server: string); /** * Adds a server to the list if it doesn't already exist */ addServer(server: string): void; /** * Removes a server from the list */ removeServer(server: string): void; } /** * NIP-87: Fedimint Mint Announcement (kind 38173) * * Describes a Fedimint federation, its capabilities, and network. */ declare class NDKFedimintMint extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk?: NDK, event?: NostrEvent | NDKEvent); static from(event: NDKEvent): Promise; /** * The federation ID */ get identifier(): string | undefined; set identifier(value: string | undefined); /** * Invite codes (multiple allowed) */ get inviteCodes(): string[]; set inviteCodes(values: string[]); /** * Supported modules */ get modules(): string[]; set modules(values: string[]); /** * Network (mainnet/testnet/signet/regtest) */ get network(): string | undefined; set network(value: string | undefined); /** * Optional metadata */ get metadata(): Record | undefined; set metadata(value: Record | undefined); } /** * NIP-87: Cashu Mint Announcement (kind 38172) * * Describes a Cashu mint, its capabilities, and network. */ declare class NDKCashuMintAnnouncement extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk?: NDK, event?: NostrEvent | NDKEvent); static from(event: NDKEvent): Promise; /** * The mint's identifier (pubkey) */ get identifier(): string | undefined; set identifier(value: string | undefined); /** * The mint URL */ get url(): string | undefined; set url(value: string | undefined); /** * Supported NUT protocols */ get nuts(): string[]; set nuts(values: string[]); /** * Network (mainnet/testnet/signet/regtest) */ get network(): string | undefined; set network(value: string | undefined); /** * Optional metadata */ get metadata(): Record | undefined; set metadata(value: Record | undefined); } /** * NIP-87: Ecash Mint Recommendation Event (kind 38000) * * Allows users to recommend and review ecash mints. * This is a parameterized-replaceable event so users can edit their recommendations. */ declare class NDKMintRecommendation extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk?: NDK, event?: NostrEvent | NDKEvent); static from(event: NDKEvent): Promise; /** * Event kind being recommended (38173 for Fedimint or 38172 for Cashu) */ get recommendedKind(): number | undefined; set recommendedKind(value: number | undefined); /** * Identifier for the recommended mint event */ get identifier(): string | undefined; set identifier(value: string | undefined); /** * Mint connection URLs/invite codes (multiple allowed) */ get urls(): string[]; set urls(values: string[]); /** * Pointers to specific mint events * Returns array of {kind, identifier, relay} objects */ get mintEventPointers(): Array<{ kind: number; identifier: string; relay?: string; }>; /** * Add a pointer to a specific mint event */ addMintEventPointer(kind: number, pubkey: string, identifier: string, relay?: string): void; /** * Review/recommendation text */ get review(): string; set review(value: string); } type Proof = { id: string; amount: number; secret: string; C: string; }; /** * Calculates the total balance from an array of proofs. * * @param {Proof[]} proofs - An array of Proof objects. * @returns {number} The total balance. * @throws {Error} If any proof has a negative amount. */ declare function proofsTotalBalance(proofs: Proof[]): number; declare class NDKCashuToken extends NDKEvent { private _proofs; private _mint; static kind: NDKKind; static kinds: NDKKind[]; /** * Tokens that this token superseeds */ private _deletes; private original; constructor(ndk?: NDK, event?: NostrEvent | NDKEvent); static from(event: NDKEvent): Promise; get proofs(): Proof[]; set proofs(proofs: Proof[]); /** * Returns a minimal proof object with only essential properties */ private cleanProof; toNostrEvent(pubkey?: string): Promise; set mint(mint: string); get mint(): string | undefined; /** * Tokens that were deleted by the creation of this token. */ get deletedTokens(): NDKEventId[]; /** * Marks tokens that were deleted by the creation of this token. */ set deletedTokens(tokenIds: NDKEventId[]); get amount(): number; publish(relaySet?: NDKRelaySet, timeoutMs?: number, requiredRelayCount?: number): Promise>; } type DIRECTIONS = "in" | "out"; /** * This class represents a balance change in the wallet, whether money being added or removed. */ declare class NDKCashuWalletTx extends NDKEvent { static MARKERS: { readonly REDEEMED: "redeemed"; readonly CREATED: "created"; readonly DESTROYED: "destroyed"; readonly RESERVED: "reserved"; }; static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk?: NDK, event?: NostrEvent | NDKEvent); static from(event: NDKEvent): Promise; set direction(direction: DIRECTIONS | undefined); get direction(): DIRECTIONS | undefined; set amount(amount: number); get amount(): number | undefined; set fee(fee: number); get fee(): number | undefined; set unit(unit: string | undefined); get unit(): string | undefined; set description(description: string | undefined); get description(): string | undefined; set mint(mint: string | undefined); get mint(): string | undefined; /** * Tags tokens that were created in this history event */ set destroyedTokens(events: NDKCashuToken[]); set destroyedTokenIds(ids: NDKEventId[]); /** * Tags tokens that were created in this history event */ set createdTokens(events: NDKCashuToken[]); set reservedTokens(events: NDKCashuToken[]); addRedeemedNutzap(event: NDKEvent): void; toNostrEvent(pubkey?: string): Promise; /** * Whether this entry includes a redemption of a Nutzap */ get hasNutzapRedemption(): boolean; private shouldEncryptTag; } interface NDKClassifiedPriceTag { amount: number; currency?: string; frequency?: string; } /** * Represents a NIP-99 Classified Listing. * * @group Kind Wrapper */ declare class NDKClassified extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk: NDK | undefined, rawEvent?: NostrEvent | NDKEvent); /** * Creates a NDKClassified from an existing NDKEvent. * * @param event NDKEvent to create the NDKClassified from. * @returns NDKClassified */ static from(event: NDKEvent): NDKClassified; /** * Getter for the classified title. * * @returns {string | undefined} - The classified title if available, otherwise undefined. */ get title(): string | undefined; /** * Setter for the classified title. * * @param {string | undefined} title - The title to set for the classified. */ set title(title: string | undefined); /** * Getter for the classified summary. * * @returns {string | undefined} - The classified summary if available, otherwise undefined. */ get summary(): string | undefined; /** * Setter for the classified summary. * * @param {string | undefined} summary - The summary to set for the classified. */ set summary(summary: string | undefined); /** * Getter for the classified's publication timestamp. * * @returns {number | undefined} - The Unix timestamp of when the classified was published or undefined. */ get published_at(): number | undefined; /** * Setter for the classified's publication timestamp. * * @param {number | undefined} timestamp - The Unix timestamp to set for the classified's publication date. */ set published_at(timestamp: number | undefined); /** * Getter for the classified location. * * @returns {string | undefined} - The classified location if available, otherwise undefined. */ get location(): string | undefined; /** * Setter for the classified location. * * @param {string | undefined} location - The location to set for the classified. */ set location(location: string | undefined); /** * Getter for the classified price. * * @returns {NDKClassifiedPriceTag | undefined} - The classified price if available, otherwise undefined. */ get price(): NDKClassifiedPriceTag | undefined; /** * Setter for the classified price. * * @param price - The price to set for the classified. */ set price(priceTag: NDKClassifiedPriceTag | string | undefined); /** * Generates content tags for the classified. * * This method first checks and sets the publication date if not available, * and then generates content tags based on the base NDKEvent class. * * @returns {ContentTag} - The generated content tags. */ generateTags(): Promise; } /** * Callback type for collaborative event updates */ type CollaborativeEventUpdateCallback = (event: NDKEvent) => void; /** * Represents a NIP-C1 collaborative event (kind 39382). * * Collaborative events allow multiple users to collaborate on a single document/event. * The pointer event contains p-tags for all authors/owners and references the target * event kind via a k-tag. * * @example Creating a collaborative document * ```typescript * const article = new NDKArticle(ndk); * article.title = "hello world"; * article.content = "an article by bob, alice and me"; * await article.publish(); * * const collabDoc = new NDKCollaborativeEvent(ndk); * collabDoc.authors.push(new NDKUser({ pubkey: 'bob' })); * collabDoc.authors.push(alice); * collabDoc.save(article); * await collabDoc.publish(); * ``` * * @example Reading a collaborative document * ```typescript * const collabDoc = await ndk.fetchEvent('naddr1-to-collaborative-document'); * collabDoc.start(); * * collabDoc.onUpdate((e: NDKEvent) => { * console.log('collaborative document updated by', e.pubkey); * }); * * const latestVersion = collabDoc.currentVersion; * collabDoc.stop(); * ``` * * @group Kind Wrapper */ declare class NDKCollaborativeEvent extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; /** * The list of authors/owners of the collaborative document. * These are reflected as p-tags in the event. */ private _authors; /** * The current best version of the collaborative document. * This is the event with the highest created_at from any of the authors. */ private _currentVersion; /** * Active subscription for live updates */ private _subscription; /** * Callbacks for update notifications */ private _updateCallbacks; constructor(ndk: NDK | undefined, rawEvent?: NostrEvent | NDKEvent); /** * Creates an NDKCollaborativeEvent from an existing NDKEvent. * * @param event NDKEvent to create the NDKCollaborativeEvent from. * @returns NDKCollaborativeEvent */ static from(event: NDKEvent): NDKCollaborativeEvent; /** * Parse p-tags from the event into NDKUser objects */ private _parseAuthorsFromTags; /** * Get the list of authors/owners of the collaborative document. * Modifying this array directly will update the p-tags on publish. */ get authors(): NDKUser[]; /** * Set the authors of the collaborative document. */ set authors(users: NDKUser[]); /** * Get all author pubkeys as an array of strings. */ get authorPubkeys(): string[]; /** * Get the target event kind that this collaborative event references. */ get targetKind(): number | undefined; /** * Set the target event kind. */ set targetKind(kind: number | undefined); /** * Get the current best version of the collaborative document. * This is the event with the highest created_at from any of the authors. */ get currentVersion(): NDKEvent | undefined; /** * Synchronize the internal tags with the current authors list. * This should be called before publishing. */ private _syncAuthorsToTags; /** * Save an event as the collaborative document. * This sets up the d-tag to match the target event's d-tag and the k-tag * to specify the target kind. * * @param targetEvent The event to be referenced by this collaborative pointer */ save(targetEvent: NDKEvent): void; /** * Publish the collaborative event. * This will: * 1. Sync authors to p-tags * 2. Publish the pointer event (kind 39382) * 3. Check if the target event has a backlink to this pointer * 4. If not, add the backlink and republish the target event */ publish(relaySet?: NDKRelaySet, timeoutMs?: number, requiredRelayCount?: number): Promise>; /** * Ensure the target event has an 'a' tag pointing back to this collaborative pointer. * If not, add it and republish the target event. */ private _ensureBacklink; /** * Start a live subscription for updates to this collaborative document. * This subscribes to all events from the authors with the matching d-tag and kind. * * @param opts Optional subscription options */ start(opts?: NDKSubscriptionOptions): void; /** * Handle an incoming event from the subscription. * Updates the current best version if this event is newer. */ private _handleIncomingEvent; /** * Register a callback to be called when the collaborative document is updated. * * @param callback Function to call when an update is received */ onUpdate(callback: CollaborativeEventUpdateCallback): void; /** * Remove an update callback. * * @param callback The callback to remove */ offUpdate(callback: CollaborativeEventUpdateCallback): void; /** * Stop the live subscription and cleanup resources. */ stop(): void; /** * Check if the subscription is currently active. */ get isRunning(): boolean; } /** * NIP-37 drafts. * @group Kind Wrapper * * @example * const myArticle = new NDKArticle(); * myArticle.content = "This is my artic" * * const draft = new NDKDraft(); * draft.event = myArticle; * draft.publish(); */ declare class NDKDraft extends NDKEvent { _event?: NDKEvent; static kind: NDKKind; static kinds: NDKKind[]; /** * Can be used to include a different pubkey as part of the draft. * This is useful when we want to make the draft a proposal for a different user to publish. */ counterparty?: NDKUser; constructor(ndk: NDK | undefined, rawEvent?: NostrEvent | NDKEvent); static from(event: NDKEvent): NDKDraft; /** * Sets an identifier (i.e. d-tag) */ set identifier(id: string); get identifier(): string | undefined; /** * Event that is to be saved. */ set event(e: NDKEvent | NostrEvent); /** * Marks the event as a checkpoint for another draft event. */ set checkpoint(parent: NDKDraft | null); get isCheckpoint(): boolean; get isProposal(): boolean; /** * Gets the event. * @param param0 * @returns NDKEvent of the draft event or null if the draft event has been deleted (emptied). */ getEvent(signer?: NDKSigner): Promise; private prepareEvent; /** * Generates draft event. * * @param signer: Optional signer to encrypt with * @param publish: Whether to publish, optionally specifying relaySet to publish to */ save({ signer, publish, relaySet }: { signer?: NDKSigner; publish?: boolean; relaySet?: NDKRelaySet; }): Promise | undefined>; } declare enum NDKDvmJobFeedbackStatus { Processing = "processing", Success = "success", Scheduled = "scheduled", PayReq = "payment_required" } declare class NDKDVMJobFeedback extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk?: NDK, event?: NostrEvent); static from(event: NDKEvent): Promise; get status(): NDKDvmJobFeedbackStatus | string | undefined; set status(status: NDKDvmJobFeedbackStatus | string | undefined); get encrypted(): boolean; dvmDecrypt(): Promise; } /** * NIP-90: Data vending machine request * * A generic Job request class for Data Vending Machines * * @example * const request = new NDKDVMRequest(ndk); * request.kind = NDKKind.DVMReqTextExtraction; * request.addInput(["https://allenfarrington.medium.com/modeling-bitcoin-value-with-vibes-99eca0997c5f", "url"]) * await request.publish() */ declare class NDKDVMRequest extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; static from(event: NDKEvent): NDKDVMRequest; set bid(msatAmount: number | undefined); get bid(): number | undefined; /** * Adds a new input to the job * @param args The arguments to the input */ addInput(...args: string[]): void; /** * Adds a new parameter to the job */ addParam(...args: string[]): void; set output(output: string | string[] | undefined); get output(): string[] | undefined; get params(): string[][]; getParam(name: string): string | undefined; createFeedback(status: NDKDvmJobFeedbackStatus | string): NDKDVMJobFeedback; /** * Enables job encryption for this event * @param dvm DVM that will receive the event * @param signer Signer to use for encryption */ encryption(dvm: NDKUser, signer?: NDKSigner): Promise; /** * Sets the DVM that will receive the event */ set dvm(dvm: NDKUser | undefined); } /** * NIP-90 * * This class creates DVM transcription job types */ declare class NDKTranscriptionDVM extends NDKDVMRequest { constructor(ndk: NDK | undefined, event?: NostrEvent); static from(event: NDKEvent): NDKTranscriptionDVM; /** * Returns the original source of the transcription */ get url(): string | undefined; /** * Getter for the title tag */ get title(): string | undefined; /** * Setter for the title tag */ set title(value: string | undefined); /** * Getter for the image tag */ get image(): string | undefined; /** * Setter for the image tag */ set image(value: string | undefined); } /** * This event is published by Data Vending Machines when * they have finished processing a job. */ declare class NDKDVMJobResult extends NDKEvent { static kind: number; static kinds: number[]; static from(event: NDKEvent): NDKDVMJobResult; setAmount(msat: number, invoice?: string): void; set result(result: string | undefined); get result(): string | undefined; set status(status: string | undefined); get status(): string | undefined; get jobRequestId(): string | undefined; set jobRequest(event: NDKEvent | undefined); get jobRequest(): NDKEvent | undefined; } type NDKDvmParam = [string, string, ...string[]]; interface NDKImetaTag { url?: string; blurhash?: string; dim?: string; alt?: string; m?: string; x?: string; size?: string; fallback?: string[]; [key: string]: string | string[] | undefined; } /** * Maps an imeta NDKTag to an NDKImetaTag */ declare function mapImetaTag(tag: NDKTag): NDKImetaTag; /** * Converts an NDKImetaTag to an NDKTag */ declare function imetaTagToTag(imeta: NDKImetaTag): NDKTag; /** * Represents a FollowPack or MediaFollowPack event. * @group Kind Wrapper */ declare class NDKFollowPack extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk?: NDK, rawEvent?: NDKEvent | NDKRawEvent); /** * Converts a generic NDKEvent to an NDKFollowPack. */ static from(ndkEvent: NDKEvent): NDKFollowPack; /** * Gets the title from the tags. */ get title(): string | undefined; /** * Sets the title tag. */ set title(value: string | undefined); /** * Gets the image URL from the tags. */ /** * Gets the image URL from the tags. * Looks for an imeta tag first (returns its url), then falls back to the image tag. */ get image(): string | undefined; /** * Sets the image URL tag. */ /** * Sets the image tag. * Accepts a string (URL) or an NDKImetaTag. * If given an NDKImetaTag, sets both the imeta tag and the image tag (using the url). * If undefined, removes both tags. */ set image(value: string | NDKImetaTag | undefined); /** * Gets all pubkeys from p tags. */ get pubkeys(): Hexpubkey[]; /** * Sets the pubkeys (replaces all p tags). */ set pubkeys(pubkeys: Hexpubkey[]); /** * Gets the description from the tags. */ get description(): string | undefined; /** * Sets the description tag. */ set description(value: string | undefined); } /** * Highlight as defined by NIP-84 (kind:9802). * @group Kind Wrapper */ declare class NDKHighlight extends NDKEvent { private _article; static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk?: NDK, rawEvent?: NostrEvent | NDKEvent); static from(event: NDKEvent): NDKHighlight; get url(): string | undefined; /** * Context tag. */ set context(context: string | undefined); get context(): string | undefined; /** * Will return the article URL or NDKEvent if they have already been * set (it won't attempt to load remote events) */ get article(): NDKEvent | string | undefined; /** * Article the highlight is coming from. * * @param article Article URL or NDKEvent. */ set article(article: NDKEvent | string); getArticleTag(): NDKTag | undefined; getArticle(): Promise; } /** * Represents an image. * @kind 20 * @group Kind Wrapper */ declare class NDKImage extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; private _imetas; constructor(ndk: NDK | undefined, rawEvent?: NostrEvent); /** * Creates a NDKImage from an existing NDKEvent. * * @param event NDKEvent to create the NDKImage from. * @returns NDKImage */ static from(event: NDKEvent): NDKImage; get isValid(): boolean; get imetas(): NDKImetaTag[]; set imetas(tags: NDKImetaTag[]); } /** * Represents a NIP-51 Interest List (kind:10015). * This list contains topics a user is interested in using "t" tags for hashtags. * @group Kind Wrapper */ declare class NDKInterestList extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk?: NDK, rawEvent?: NostrEvent); static from(ndkEvent: NDKEvent): NDKInterestList; /** * Get all interest hashtags from the list. */ get interests(): string[]; /** * Set interest hashtags, replacing all existing ones. */ set interests(hashtags: string[]); /** * Add a single interest hashtag to the list. * @param hashtag The hashtag to add (without the # symbol) */ addInterest(hashtag: string): void; /** * Remove an interest hashtag from the list. * @param hashtag The hashtag to remove */ removeInterest(hashtag: string): void; /** * Check if the list contains a specific interest hashtag. * @param hashtag The hashtag to check for */ hasInterest(hashtag: string): boolean; /** * Get interest set references (kind:30015) from "a" tags. */ get interestSetReferences(): string[]; } type NDKListItem = NDKRelay | NDKUser | NDKEvent; /** * Represents any NIP-51 list kind. * * This class provides some helper methods to manage the list, particularly * a CRUD interface to list items. * * List items can be encrypted or not. Encrypted items are JSON-encoded and * self-signed by the user's key. * * @example Adding an event to the list. * const event1 = new NDKEvent(...); * const list = new NDKList(); * list.addItem(event1); * * @example Adding an encrypted `p` tag to the list with a "person" mark. * const secretFollow = new NDKUser(...); * list.addItem(secretFollow, 'person', true); * * @emits change * @group Kind Wrapper */ declare class NDKList extends NDKEvent { _encryptedTags: NDKTag[] | undefined; static kind: NDKKind; static kinds: NDKKind[]; /** * Stores the number of bytes the content was before decryption * to expire the cache when the content changes. */ private encryptedTagsLength; constructor(ndk?: NDK, rawEvent?: NostrEvent | NDKEvent); /** * Wrap a NDKEvent into a NDKList */ static from(ndkEvent: NDKEvent): NDKList; /** * Returns the title of the list. Falls back on fetching the name tag value. */ get title(): string | undefined; /** * Sets the title of the list. */ set title(title: string | undefined); /** * Returns the name of the list. * @deprecated Please use "title" instead. */ get name(): string | undefined; /** * Sets the name of the list. * @deprecated Please use "title" instead. This method will use the `title` tag instead. */ set name(name: string | undefined); /** * Returns the description of the list. */ get description(): string | undefined; /** * Sets the description of the list. */ set description(name: string | undefined); /** * Returns the image of the list. */ get image(): string | undefined; /** * Sets the image of the list. */ set image(name: string | undefined); private isEncryptedTagsCacheValid; /** * Returns the decrypted content of the list. */ encryptedTags(useCache?: boolean): Promise; /** * This method can be overriden to validate that a tag is valid for this list. * * (i.e. the NDKPersonList can validate that items are NDKUser instances) */ validateTag(_tagValue: string): boolean | string; getItems(type: string): NDKTag[]; /** * Returns the unecrypted items in this list. */ get items(): NDKTag[]; /** * Adds a new item to the list. * @param relay Relay to add * @param mark Optional mark to add to the item * @param encrypted Whether to encrypt the item * @param position Where to add the item in the list (top or bottom) */ addItem(item: NDKListItem | NDKTag, mark?: string | undefined, encrypted?: boolean, position?: "top" | "bottom"): Promise; /** * Removes an item from the list from both the encrypted and unencrypted lists. * @param value value of item to remove from the list * @param publish whether to publish the change * @returns */ removeItemByValue(value: string, publish?: boolean): Promise | undefined>; /** * Removes an item from the list. * * @param index The index of the item to remove. * @param encrypted Whether to remove from the encrypted list or not. */ removeItem(index: number, encrypted: boolean): Promise; has(item: string): boolean; /** * Creates a filter that will result in fetching * the items of this list * @example * const list = new NDKList(...); * const filters = list.filterForItems(); * const events = await ndk.fetchEvents(filters); */ filterForItems(): NDKFilter[]; } /** * This is a NIP-89 app handler wrapper. * * @summary NIP-89 App Handler * @group Kind Wrapper * @implements kind:31990 */ declare class NDKAppHandlerEvent extends NDKEvent { private profile; static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk?: NDK, rawEvent?: NostrEvent); static from(ndkEvent: NDKEvent): NDKAppHandlerEvent | null; get isValid(): boolean; /** * Fetches app handler information * If no app information is available on the kind:31990, * we fetch the event's author's profile and return that instead. */ fetchProfile(): Promise; } declare class NDKCashuMintList extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; private _p2pk?; constructor(ndk?: NDK, event?: NostrEvent | NDKEvent); static from(event: NDKEvent): NDKCashuMintList; set relays(urls: WebSocket["url"][]); get relays(): WebSocket["url"][]; set mints(urls: WebSocket["url"][]); get mints(): WebSocket["url"][]; get p2pk(): string; set p2pk(pubkey: string | undefined); get relaySet(): NDKRelaySet | undefined; } interface NDKZapInvoice { id?: NDKEventId; /** * The pubkey of the zapper app */ zapper: string; /** * The pubkey of the user sending the zap */ zappee: string; /** * The pubkey of the user receiving the zap */ zapped: string; /** * The event that was zapped */ zappedEvent?: string; /** * The amount zapped in millisatoshis */ amount: number; /** * A comment attached to the zap */ comment?: string; } /** * Parses a zap invoice from a kind 9735 event * * @param event The event to parse * * @returns NDKZapInvoice | null */ declare function zapInvoiceFromEvent(event: NDKEvent): NDKZapInvoice | null; /** * Represents a NIP-57 zap event (kind 9735) * * @example * ```typescript * const zapEvent = await ndk.fetchEvent(zapId); * const zap = NDKZap.from(zapEvent); * * if (zap) { * console.log(`${zap.amount} sats from ${zap.sender.npub}`); * console.log(`Comment: ${zap.comment}`); * console.log(`Recipient: ${zap.recipient.npub}`); * } * ``` */ declare class NDKZap extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; private _invoice?; constructor(ndk?: NDK, rawEvent?: NostrEvent); /** * Creates an NDKZap instance from an NDKEvent * * @param event The event to convert * @returns NDKZap instance or null if invalid */ static from(event: NDKEvent): NDKZap | null; /** * Get the parsed zap invoice (lazy loaded, cached) * Returns null if the zap event is invalid or malformed */ get invoice(): NDKZapInvoice | null; /** * Amount in sats (converted from millisats in the invoice) * Returns 0 if invoice is invalid */ get amount(): number; /** * The user who sent the zap (zappee) * * @throws Error if zap is invalid or NDK instance is not available */ get sender(): NDKUser; /** * The user who received the zap (zapped) * * @throws Error if zap is invalid or NDK instance is not available */ get recipient(): NDKUser; /** * Zap comment/message from the zap request */ get comment(): string | undefined; /** * The event that was zapped (if any) * Can be an event ID (e tag) or address (a tag) */ get zappedEventId(): string | undefined; /** * The zapper service pubkey that processed this zap */ get zapper(): string | undefined; /** * Check if this is a valid zap */ get isValid(): boolean; } /** * A signer that uses an in-memory private key (nsec). * * @example * ```ts * const signer = NDKPrivateKeySigner.generate(); * console.log('your nsec is', signer.nsec); * console.log('your pubkey is', signer.pubkey); * console.log('your npub is', signer.npub); * ``` * * @example * ```ts * const signer = new NDKPrivateKeySigner(nsec); * ``` */ declare class NDKPrivateKeySigner implements NDKSigner { private _user; private _privateKey; private _pubkey?; /** * Create a new signer from a private key. * @param privateKey - The private key to use in hex form or nsec. * @param ndk - The NDK instance to use. * * @ai-guardrail * If you have an nsec (bech32-encoded private key starting with "nsec1"), you can pass it directly * to this constructor without decoding it first. The constructor handles both hex and nsec formats automatically. * DO NOT use nip19.decode() to convert nsec to hex before passing it here - just pass the nsec string directly. */ constructor(privateKeyOrNsec: Uint8Array | string, ndk?: NDK); /** * Get the private key in hex form. */ get privateKey(): string; /** * Get the public key in hex form. */ get pubkey(): string; /** * Get the private key in nsec form. */ get nsec(): string; /** * Get the public key in npub form. */ get npub(): string; /** * Encrypt the private key with a password to ncryptsec format. * @param password - The password to encrypt the private key. * @param logn - The log2 of the scrypt N parameter (default: 16). * @param ksb - The key security byte (0x00, 0x01, or 0x02, default: 0x02). * @returns The encrypted private key in ncryptsec format. * * @example * ```ts * const signer = new NDKPrivateKeySigner(nsec); * const ncryptsec = signer.encryptToNcryptsec("my-password"); * console.log('encrypted key:', ncryptsec); * ``` */ encryptToNcryptsec(password: string, logn?: number, ksb?: 0x00 | 0x01 | 0x02): string; /** * Generate a new private key. */ static generate(): NDKPrivateKeySigner; /** * Create a signer from an encrypted private key (ncryptsec) using a password. * @param ncryptsec - The encrypted private key in ncryptsec format. * @param password - The password to decrypt the private key. * @param ndk - Optional NDK instance. * @returns A new NDKPrivateKeySigner instance. * * @example * ```ts * const signer = NDKPrivateKeySigner.fromNcryptsec( * "ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p", * "my-password" * ); * console.log('your pubkey is', signer.pubkey); * ``` */ static fromNcryptsec(ncryptsec: string, password: string, ndk?: NDK): NDKPrivateKeySigner; /** * Noop in NDKPrivateKeySigner. */ blockUntilReady(): Promise; /** * Get the user. */ user(): Promise; /** * Get the user. */ get userSync(): NDKUser; sign(event: NostrEvent): Promise; encryptionEnabled(scheme?: NDKEncryptionScheme): Promise; encrypt(recipient: NDKUser, value: string, scheme?: NDKEncryptionScheme): Promise; decrypt(sender: NDKUser, value: string, scheme?: NDKEncryptionScheme): Promise; /** * Serializes the signer's private key into a storable format. * @returns A JSON string containing the type and the hex private key. */ toPayload(): string; /** * Deserializes the signer from a payload string. * @param payloadString The JSON string obtained from toPayload(). * @param ndk Optional NDK instance. * @returns An instance of NDKPrivateKeySigner. */ static fromPayload(payloadString: string, ndk?: NDK): Promise; } /** * Represents a project event in Nostr (kind 31933). * Projects are a special type of article event used by TENEX and other project management tools. */ declare class NDKProject extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; private _signer; constructor(ndk?: NDK, rawEvent?: NostrEvent); static from(event: NDKEvent): NDKProject; set repo(value: string | undefined); set hashtags(values: string[]); get hashtags(): string[]; get repo(): string | undefined; get title(): string | undefined; set title(value: string | undefined); get picture(): string | undefined; set picture(value: string | undefined); set description(value: string); get description(): string; /** * The project slug, derived from the 'd' tag. */ get slug(): string; getSigner(): Promise; getNsec(): Promise; setNsec(value: string): Promise; private encryptAndSaveNsec; } /** * Represents a project template event in Nostr (kind 30717). * Templates are parameterized replaceable events used to define reusable project structures. */ declare class NDKProjectTemplate extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk?: NDK, rawEvent?: NostrEvent); static from(event: NDKEvent): NDKProjectTemplate; /** * Template identifier from 'd' tag */ get templateId(): string; set templateId(value: string); /** * Template name from 'title' tag */ get name(): string; set name(value: string); /** * Template description from 'description' tag */ get description(): string; set description(value: string); /** * Git repository URL from 'uri' tag */ get repoUrl(): string; set repoUrl(value: string); /** * Template preview image URL from 'image' tag */ get image(): string | undefined; set image(value: string | undefined); /** * Command to run from 'command' tag */ get command(): string | undefined; set command(value: string | undefined); /** * Agent configuration from 'agent' tag */ get agentConfig(): object | undefined; set agentConfig(value: object | undefined); /** * Template tags from 't' tags */ get templateTags(): string[]; set templateTags(values: string[]); } /** * Represents a relay list for a user, ideally coming from a NIP-65 kind:10002 or alternatively from a kind:3 event's content. * @group Kind Wrapper */ declare class NDKRelayList extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk?: NDK, rawEvent?: NostrEvent); static from(ndkEvent: NDKEvent): NDKRelayList; get readRelayUrls(): WebSocket["url"][]; set readRelayUrls(relays: WebSocket["url"][]); get writeRelayUrls(): WebSocket["url"][]; set writeRelayUrls(relays: WebSocket["url"][]); get bothRelayUrls(): WebSocket["url"][]; set bothRelayUrls(relays: WebSocket["url"][]); get relays(): WebSocket["url"][]; /** * Provides a relaySet for the relays in this list. */ get relaySet(): NDKRelaySet; } declare function relayListFromKind3(ndk: NDK, contactList: NDKEvent): NDKRelayList | undefined; /** * Represents a NIP-51 kind 10012 Relay Feed List. * * This list contains user's favorite browsable relays and relay sets. * Items can be: * - `relay` tags pointing to relay URLs * - `a` tags pointing to kind:30002 relay sets * * @example * const relayFeedList = new NDKRelayFeedList(ndk); * relayFeedList.addRelay("wss://relay.damus.io"); * relayFeedList.addRelaySet("30002:pubkey:dtagvalue"); * await relayFeedList.publish(); * * @group Kind Wrapper */ declare class NDKRelayFeedList extends NDKList { static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk?: NDK, rawEvent?: NostrEvent | NDKEvent); static from(ndkEvent: NDKEvent): NDKRelayFeedList; /** * Gets all relay URLs from the list. */ get relayUrls(): string[]; /** * Gets all relay set references (kind:30002 naddr) from the list. * Returns them in the format "kind:pubkey:dtag". */ get relaySets(): string[]; /** * Adds a relay URL to the list. * @param relayUrl - WebSocket URL of the relay * @param mark - Optional mark to add to the relay tag * @param encrypted - Whether to encrypt the item * @param position - Where to add the item in the list */ addRelay(relayUrl: string, mark?: string, encrypted?: boolean, position?: "top" | "bottom"): Promise; /** * Adds a relay set reference to the list. * @param relaySetNaddr - NIP-33 address in format "kind:pubkey:dtag" (kind should be 30002) * @param mark - Optional mark to add to the relay set tag * @param encrypted - Whether to encrypt the item * @param position - Where to add the item in the list */ addRelaySet(relaySetNaddr: string, mark?: string, encrypted?: boolean, position?: "top" | "bottom"): Promise; /** * Removes a relay URL from the list. * @param relayUrl - The relay URL to remove * @param publish - Whether to publish the change */ removeRelay(relayUrl: string, publish?: boolean): Promise; /** * Removes a relay set from the list. * @param relaySetNaddr - The relay set naddr to remove * @param publish - Whether to publish the change */ removeRelaySet(relaySetNaddr: string, publish?: boolean): Promise; } type classWithConvertFunction = { from: (event: NDKEvent) => T; }; /** * Handles NIP-18 reposts. * @group Kind Wrapper */ declare class NDKRepost extends NDKEvent { private _repostedEvents; static kind: NDKKind; static kinds: NDKKind[]; static from(event: NDKEvent): NDKRepost; /** * Returns all reposted events by the current event. * * @param klass Optional class to convert the events to. * @returns */ repostedEvents(klass?: classWithConvertFunction, opts?: NDKSubscriptionOptions): Promise; /** * Returns the reposted event IDs. */ repostedEventIds(): string[]; } declare class NDKSimpleGroupMemberList extends NDKEvent { relaySet: NDKRelaySet | undefined; memberSet: Set; static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk: NDK | undefined, rawEvent?: NostrEvent | NDKEvent); static from(event: NDKEvent): NDKSimpleGroupMemberList; get members(): string[]; hasMember(member: Hexpubkey): boolean; publish(relaySet?: NDKRelaySet, timeoutMs?: number, requiredRelayCount?: number): Promise>; } declare class NDKSimpleGroupMetadata extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk: NDK | undefined, rawEvent?: NostrEvent | NDKEvent); static from(event: NDKEvent): NDKSimpleGroupMetadata; get name(): string | undefined; get picture(): string | undefined; get about(): string | undefined; get scope(): "public" | "private" | undefined; set scope(scope: "public" | "private" | undefined); get access(): "open" | "closed" | undefined; set access(access: "open" | "closed" | undefined); } /** * Represents a NIP-29 group. * @catergory Kind Wrapper */ declare class NDKSimpleGroup { readonly ndk: NDK; groupId: string; readonly relaySet: NDKRelaySet; private fetchingMetadata; metadata: NDKSimpleGroupMetadata | undefined; memberList: NDKSimpleGroupMemberList | undefined; adminList: NDKSimpleGroupMemberList | undefined; constructor(ndk: NDK, relaySet: NDKRelaySet, groupId?: string); get id(): string; relayUrls(): string[]; get name(): string | undefined; get about(): string | undefined; get picture(): string | undefined; get members(): Hexpubkey[] | []; get admins(): Hexpubkey[] | []; getMetadata(): Promise; /** * Creates the group by publishing a kind:9007 event. * @param signer * @returns */ createGroup(signer?: NDKSigner): Promise>; setMetadata({ name, about, picture }: { name?: string; about?: string; picture?: string; }): Promise>; /** * Adds a user to the group using a kind:9000 event * @param user user to add * @param opts options */ addUser(user: NDKUser): Promise; getMemberListEvent(): Promise; /** * Gets a list of users that belong to this group */ getMembers(): Promise; /** * Generates an event that lists the members of a group. * @param groupId * @returns */ static generateUserListEvent(groupId: string): NDKEvent; /** * Generates an event that adds a user to a group. * @param userPubkey pubkey of the user to add * @param groupId group to add the user to * @returns */ static generateAddUserEvent(userPubkey: string, groupId: string): NDKEvent; requestToJoin(_pubkey: Hexpubkey, content?: string): Promise>; /** * Makes sure that a metadata event exists locally */ ensureMetadataEvent(): Promise; } /** * Sticker type for NDKStory */ declare enum NDKStoryStickerType { Pubkey = "pubkey", Event = "event", Prompt = "prompt", Text = "text", Countdown = "countdown" } /** * Interface representing a sticker position */ interface NDKStickerPosition { x: number; y: number; } /** * Interface representing sticker dimensions */ interface StickerDimension { width: number; height: number; } /** * Interface representing sticker properties */ interface StickerProperties { [key: string]: string; } /** * Interface for a story sticker (used in tests and for the addSticker method) */ interface StorySticker { type: NDKStoryStickerType; value: NDKEvent | NDKUser | string; position: NDKStickerPosition; dimension: StickerDimension; properties?: StickerProperties; } /** * Converts a string in the format "x,y" to a position object */ declare function strToPosition(positionStr: string): NDKStickerPosition; /** * Converts a string in the format "widthxheight" to a dimension object */ declare function strToDimension(dimensionStr: string): StickerDimension; /** * Maps sticker types to their value types */ type StoryValueType = T extends NDKStoryStickerType.Event ? NDKEvent : T extends NDKStoryStickerType.Pubkey ? NDKUser : string; /** * Interface representing story dimensions */ interface NDKStoryDimension { width: number; height: number; } /** * Represents a sticker in an NDK story. * * Example usage: * ```typescript * // Create a text sticker * const textSticker = new NDKStorySticker(NDKStoryStickerType.Text); * textSticker.value = "Hello World!"; * textSticker.position = { x: 540, y: 960 }; * textSticker.dimension = { width: 500, height: 150 }; * textSticker.style = "bold"; * textSticker.rotation = 15; * * // Create a mention sticker (Pubkey type) * const mentionSticker = new NDKStorySticker(NDKStoryStickerType.Pubkey); * mentionSticker.value = new NDKUser("pubkey-value"); * mentionSticker.position = { x: 300, y: 500 }; * mentionSticker.dimension = { width: 200, height: 50 }; * * // Create a sticker from a tag * const tagSticker = new NDKStorySticker([ * "sticker", * "event", * "event-id", * "540,960", * "500x150", * "style italic" * ]); * ``` */ declare class NDKStorySticker { static Text: NDKStoryStickerType; static Pubkey: NDKStoryStickerType; static Event: NDKStoryStickerType; static Prompt: NDKStoryStickerType; static Countdown: NDKStoryStickerType; readonly type: T; value: StoryValueType; position: NDKStickerPosition; dimension: StickerDimension; properties?: StickerProperties; constructor(type: T); constructor(tag: NDKTag); static fromTag(tag: NDKTag): NDKStorySticker | null; get style(): string | undefined; set style(style: string | undefined); get rotation(): number | undefined; set rotation(rotation: number | undefined); /** * Checks if the sticker is valid. * * @returns {boolean} - True if the sticker is valid, false otherwise. */ get isValid(): boolean; hasValidDimensions: () => boolean; hasValidPosition: () => boolean; toTag(): NDKTag; } /** * Represents a NIP-XX Story. * * @group Kind Wrapper */ declare class NDKStory extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; private _imeta; private _dimensions; constructor(ndk: NDK | undefined, rawEvent?: NostrEvent | NDKEvent); /** * Creates a NDKStory from an existing NDKEvent. * * @param event NDKEvent to create the NDKStory from. * @returns NDKStory */ static from(event: NDKEvent): NDKStory; /** * Checks if the story is valid (has exactly one imeta tag). */ get isValid(): boolean; /** * Gets the first imeta tag (there should only be one). */ get imeta(): NDKImetaTag | undefined; /** * Sets a single imeta tag, replacing any existing ones. */ set imeta(tag: NDKImetaTag | undefined); /** * Getter for the story dimensions. * * @returns {NDKStoryDimension | undefined} - The story dimensions if available, otherwise undefined. */ get dimensions(): NDKStoryDimension | undefined; /** * Setter for the story dimensions. * * @param {NDKStoryDimension | undefined} dimensions - The dimensions to set for the story. */ set dimensions(dimensions: NDKStoryDimension | undefined); /** * Getter for the story duration. * * @returns {number | undefined} - The story duration in seconds if available, otherwise undefined. */ get duration(): number | undefined; /** * Setter for the story duration. * * @param {number | undefined} duration - The duration in seconds to set for the story. */ set duration(duration: number | undefined); /** * Gets all stickers from the story. * * @returns {NDKStorySticker[]} - Array of stickers in the story. */ get stickers(): NDKStorySticker[]; /** * Adds a sticker to the story. * * @param {NDKStorySticker|StorySticker} sticker - The sticker to add. */ addSticker(sticker: NDKStorySticker | StorySticker): void; /** * Removes a sticker from the story. * * @param {number} index - The index of the sticker to remove. */ removeSticker(index: number): void; } type NDKIntervalFrequency = "daily" | "weekly" | "monthly" | "quarterly" | "yearly"; declare const possibleIntervalFrequencies: NDKIntervalFrequency[]; type NDKSubscriptionAmount = { amount: number; currency: string; term: NDKIntervalFrequency; }; declare function calculateTermDurationInSeconds(term: NDKIntervalFrequency): number; /** * Creates a new amount tag * @param amount Amount in base unit of the currency (e.g. cents, msats) * @param currency Currency code. Use msat for millisatoshis * @param term One of daily, weekly, monthly, quarterly, yearly * @returns */ declare function newAmount(amount: number, currency: string, term: NDKIntervalFrequency): NDKTag; declare function parseTagToSubscriptionAmount(tag: NDKTag): NDKSubscriptionAmount | undefined; /** * @description * Implements NIP-88 (TBD)'s subscription tiers * * This class will validate that incoming events are valid subscription tiers. Incomplete or invalid * amounts will be ignored. * * @example * const tier = new NDKSubscriptionTier; * tier.title = "Tier 1"; * tier.addAmount(100000, "msat", "monthly"); // 100 sats per month * tier.addAmount(499, "usd", "monthly"); // $4.99 per month * tier.relayUrl = "wss://relay.highlighter.com/"; * tier.relayUrl = "wss://relay.creator.com/"; * tier.verifierPubkey = ""; * tier.addPerk("Access to my private content"); */ declare class NDKSubscriptionTier extends NDKArticle { static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk: NDK | undefined, rawEvent?: NostrEvent | NDKEvent); /** * Creates a new NDKSubscriptionTier from an event * @param event * @returns NDKSubscriptionTier */ static from(event: NDKEvent): NDKSubscriptionTier; /** * Returns perks for this tier */ get perks(): string[]; /** * Adds a perk to this tier */ addPerk(perk: string): void; /** * Returns the amount for this tier */ get amounts(): NDKSubscriptionAmount[]; /** * Adds an amount to this tier * @param amount Amount in the smallest unit of the currency (e.g. cents, msats) * @param currency Currency code. Use msat for millisatoshis * @param term One of daily, weekly, monthly, quarterly, yearly */ addAmount(amount: number, currency: string, term: NDKIntervalFrequency): void; /** * Sets a relay where content related to this tier can be found * @param relayUrl URL of the relay */ set relayUrl(relayUrl: string); /** * Returns the relay URLs for this tier */ get relayUrls(): string[]; /** * Gets the verifier pubkey for this tier. This is the pubkey that will generate * subscription payment receipts */ get verifierPubkey(): string | undefined; /** * Sets the verifier pubkey for this tier. */ set verifierPubkey(pubkey: string | undefined); /** * Checks if this tier is valid */ get isValid(): boolean; } /** * Represents a subscription start event. * @example * const creator = new NDKUser; * const subscriber = new NDKUser; * * const subscriptionStart = new NDKSubscriptionStart(ndk); * subscriptionStart.amount = { amount: 100, currency: "USD", term: "monthly" }; * subscriptionStart.recipient = creator; * subscriptionStart.author = subscriber; * * // { * // kind: 7001, * // pubkey: "" * // tags: [ * // ["amount", "100", "USD", "monthly"], * // ["p", ""] * // ] * // } */ declare class NDKSubscriptionStart extends NDKEvent { private debug; static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk: NDK | undefined, rawEvent?: NostrEvent); static from(event: NDKEvent): NDKSubscriptionStart; /** * Recipient of the subscription. I.e. The author of this event subscribes to this user. */ get recipient(): NDKUser | undefined; set recipient(user: NDKUser | undefined); /** * The amount of the subscription. */ get amount(): NDKSubscriptionAmount | undefined; set amount(amount: NDKSubscriptionAmount | undefined); /** * The event id or NIP-33 tag id of the tier that the user is subscribing to. */ get tierId(): string | undefined; set tier(tier: NDKSubscriptionTier | undefined); /** * Fetches the tier that the user is subscribing to. */ fetchTier(): Promise; get isValid(): boolean; } type ValidPeriod = { start: Date; end: Date; }; /** * A subscription receipt event. * * @example * const creator = new NDKUser; * const subscriber = new NDKUser; * const receipt = new NDKSubscriptionReceipt(ndk, event); * event.recipient = creator; * event.subscriber = subscriber; */ declare class NDKSubscriptionReceipt extends NDKEvent { private debug; static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk: NDK | undefined, rawEvent?: NostrEvent); static from(event: NDKEvent): NDKSubscriptionReceipt; /** * This is the person being subscribed to */ get recipient(): NDKUser | undefined; set recipient(user: NDKUser | undefined); /** * This is the person subscribing */ get subscriber(): NDKUser | undefined; set subscriber(user: NDKUser | undefined); set subscriptionStart(event: NDKSubscriptionStart); get tierName(): string | undefined; get isValid(): boolean; get validPeriod(): ValidPeriod | undefined; set validPeriod(period: ValidPeriod | undefined); get startPeriod(): Date | undefined; get endPeriod(): Date | undefined; /** * Whether the subscription is currently active */ isActive(time?: Date): boolean; } /** * Represents a task associated with a project. * Tasks are regular events with kind 1934. */ declare class NDKTask extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk?: NDK, rawEvent?: NostrEvent); static from(event: NDKEvent): NDKTask; set title(value: string); get title(): string | undefined; set project(project: NDKProject); get projectSlug(): string | undefined; } /** * Represents a NIP-7D Thread event. * * @group Kind Wrapper */ declare class NDKThread extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk: NDK | undefined, rawEvent?: NostrEvent | NDKEvent); /** * Creates an NDKThread from an existing NDKEvent. * * @param event NDKEvent to create the NDKThread from. * @returns NDKThread */ static from(event: NDKEvent): NDKThread; /** * Gets the title of the thread. */ get title(): string | undefined; /** * Sets the title of the thread. */ set title(title: string | undefined); } /** * Represents a horizontal or vertical video. * @group Kind Wrapper */ declare class NDKVideo extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; private _imetas; /** * Creates a NDKArticle from an existing NDKEvent. * * @param event NDKEvent to create the NDKArticle from. * @returns NDKArticle */ static from(event: NDKEvent): NDKVideo; /** * Getter for the article title. * * @returns {string | undefined} - The article title if available, otherwise undefined. */ get title(): string | undefined; /** * Setter for the article title. * * @param {string | undefined} title - The title to set for the article. */ set title(title: string | undefined); /** * Getter for the article thumbnail. * * @returns {string | undefined} - The article thumbnail if available, otherwise undefined. */ get thumbnail(): string | undefined; get imetas(): NDKImetaTag[]; set imetas(tags: NDKImetaTag[]); get url(): string | undefined; /** * Getter for the article's publication timestamp. * * @returns {number | undefined} - The Unix timestamp of when the article was published or undefined. */ get published_at(): number | undefined; /** * Generates content tags for the article. * * This method first checks and sets the publication date if not available, * and then generates content tags based on the base NDKEvent class. * * @returns {ContentTag} - The generated content tags. */ generateTags(): Promise; get duration(): number | undefined; /** * Setter for the video's duration * * @param {number | undefined} duration - The duration to set for the video (in seconds) */ set duration(dur: number | undefined); } /** * Represents a NIP-A0 voice message (kind 1222). * * @group Kind Wrapper */ declare class NDKVoiceMessage extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk: NDK | undefined, rawEvent?: NostrEvent | NDKEvent); /** * Creates a NDKVoiceMessage from an existing NDKEvent. * * @param event NDKEvent to create the NDKVoiceMessage from. * @returns NDKVoiceMessage */ static from(event: NDKEvent): NDKVoiceMessage; /** * Getter for the audio URL. * * @returns {string | undefined} - The audio file URL if available, otherwise undefined. */ get url(): string | undefined; /** * Setter for the audio URL. * * @param {string | undefined} url - The audio URL to set for the voice message. */ set url(url: string | undefined); /** * Getter for the waveform data from imeta tag. * * @returns {number[] | undefined} - Array of amplitude values if available, otherwise undefined. */ get waveform(): number[] | undefined; /** * Setter for the waveform data in imeta tag. * * @param {number[] | undefined} waveform - Array of amplitude values (0-100). */ set waveform(waveform: number[] | undefined); /** * Getter for the audio duration in seconds from imeta tag. * * @returns {number | undefined} - The audio duration in seconds if available, otherwise undefined. */ get duration(): number | undefined; /** * Setter for the audio duration in imeta tag. * * @param {number | undefined} duration - The audio duration in seconds. */ set duration(duration: number | undefined); } /** * Represents a NIP-A0 voice reply (kind 1244). * * @group Kind Wrapper */ declare class NDKVoiceReply extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; constructor(ndk: NDK | undefined, rawEvent?: NostrEvent | NDKEvent); /** * Creates a NDKVoiceReply from an existing NDKEvent. * * @param event NDKEvent to create the NDKVoiceReply from. * @returns NDKVoiceReply */ static from(event: NDKEvent): NDKVoiceReply; /** * Getter for the audio URL. * * @returns {string | undefined} - The audio file URL if available, otherwise undefined. */ get url(): string | undefined; /** * Setter for the audio URL. * * @param {string | undefined} url - The audio URL to set for the voice reply. */ set url(url: string | undefined); /** * Getter for the waveform data from imeta tag. * * @returns {number[] | undefined} - Array of amplitude values if available, otherwise undefined. */ get waveform(): number[] | undefined; /** * Setter for the waveform data in imeta tag. * * @param {number[] | undefined} waveform - Array of amplitude values (0-100). */ set waveform(waveform: number[] | undefined); /** * Getter for the audio duration in seconds from imeta tag. * * @returns {number | undefined} - The audio duration in seconds if available, otherwise undefined. */ get duration(): number | undefined; /** * Setter for the audio duration in imeta tag. * * @param {number | undefined} duration - The audio duration in seconds. */ set duration(duration: number | undefined); } /** * Represents a NIP-54 wiki event. * * Wiki events use */ declare class NDKWiki extends NDKArticle { static kind: NDKKind; static kinds: NDKKind[]; static from(event: NDKEvent): NDKWiki; get isDefered(): boolean; get deferedId(): string | undefined; /** * Defers the author's wiki event to another wiki event. * * Wiki-events can tag other wiki-events with a `defer` marker to indicate that it considers someone else's entry as a "better" version of itself. If using a `defer` marker both `a` and `e` tags SHOULD be used. * * @example * myWiki.defer = betterWikiEntryOnTheSameTopic; * myWiki.publishReplaceable() */ set defer(deferedTo: NDKWiki); } /** * Represents a NIP-54 wiki merge request event. * * Users can request other users to get their entries merged into someone else's entry by creating a `kind:818` event. */ declare class NDKWikiMergeRequest extends NDKEvent { static kind: NDKKind; static kinds: NDKKind[]; static from(event: NDKEvent): NDKWikiMergeRequest; /** * The target ID () of the wiki event to merge into. */ get targetId(): string | undefined; /** * Sets the target ID () of the wiki event to merge into. */ set target(targetEvent: NDKWiki); /** * The source ID of the wiki event to merge from. */ get sourceId(): string | undefined; /** * Sets the event we are asking to get merged into the target. */ set source(sourceEvent: NDKWiki); } type NDKEventClass = { kinds: number[]; from(event: NDKEvent): NDKEvent; }; /** * Register a custom event class that can be used with wrapEvent(). * The class must have a static 'kinds' property (array of numbers) and a static 'from' method. * * @param eventClass - The event class to register * @example * ```typescript * class MyCustomEvent extends NDKEvent { * static kinds = [12345]; * static from(event: NDKEvent) { * return new MyCustomEvent(event.ndk, event); * } * } * registerEventClass(MyCustomEvent); * ``` */ declare function registerEventClass(eventClass: NDKEventClass): void; /** * Unregister a previously registered event class. * * @param eventClass - The event class to unregister */ declare function unregisterEventClass(eventClass: NDKEventClass): void; /** * Get all registered event classes. * * @returns Set of registered event classes */ declare function getRegisteredEventClasses(): Set; declare function wrapEvent(event: NDKEvent): T | Promise | NDKEvent; /** * Re-export nip19 utilities from nostr-tools for lightweight data conversion * This allows NDK users to encode/decode NIP-19 identifiers without instantiating NDK objects */ var index$1 = /*#__PURE__*/_mergeNamespaces({ __proto__: null }, [nip19]); /** * Re-export nip49 utilities from nostr-tools for private key encryption * This allows NDK users to encrypt/decrypt private keys with passwords (ncryptsec format) */ var index = /*#__PURE__*/_mergeNamespaces({ __proto__: null }, [nip49]); /** * Deserializes a signer from a payload string using the signer registry. * @param payloadString The JSON string obtained from a signer's toPayload(). * @param ndk Optional NDK instance, required by some signers. * @returns An instance of the specific signer class, or undefined if the type is unknown. */ declare function ndkSignerFromPayload(payloadString: string, ndk?: NDK): Promise; type EncryptionMethod = "encrypt" | "decrypt"; type EncryptionQueueItem = { scheme: NDKEncryptionScheme; method: EncryptionMethod; counterpartyHexpubkey: string; value: string; resolve: (value: string) => void; reject: (reason?: Error) => void; }; type Nip07RelayMap = { [key: string]: { read: boolean; write: boolean; }; }; /** * NDKNip07Signer implements the NDKSigner interface for signing Nostr events * with a NIP-07 browser extension (e.g., getalby, nos2x). */ declare class NDKNip07Signer implements NDKSigner { private _userPromise; encryptionQueue: EncryptionQueueItem[]; private encryptionProcessing; private debug; private waitTimeout; private _pubkey; private ndk?; private _user; /** * @param waitTimeout - The timeout in milliseconds to wait for the NIP-07 to become available */ constructor(waitTimeout?: number, ndk?: NDK); get pubkey(): string; blockUntilReady(): Promise; /** * Getter for the user property. * @returns The NDKUser instance. */ user(): Promise; get userSync(): NDKUser; /** * Signs the given Nostr event. * @param event - The Nostr event to be signed. * @returns The signature of the signed event. * @throws Error if the NIP-07 is not available on the window object. */ sign(event: NostrEvent): Promise; relays(ndk: NDK): Promise; encryptionEnabled(nip?: NDKEncryptionScheme): Promise; encrypt(recipient: NDKUser, value: string, nip?: NDKEncryptionScheme): Promise; decrypt(sender: NDKUser, value: string, nip?: NDKEncryptionScheme): Promise; private queueEncryption; private processEncryptionQueue; private waitForExtension; /** * Serializes the signer type into a storable format. * NIP-07 signers don't have persistent state to serialize beyond their type. * @returns A JSON string containing the type. */ toPayload(): string; /** * Deserializes the signer from a payload string. * Creates a new NDKNip07Signer instance. * @param payloadString The JSON string obtained from toPayload(). * @param ndk Optional NDK instance. * @returns An instance of NDKNip07Signer. */ static fromPayload(payloadString: string, ndk?: NDK): Promise; } type Nip44 = { encrypt: (recipient: Hexpubkey, value: string) => Promise; decrypt: (sender: Hexpubkey, value: string) => Promise; }; declare global { interface Window { nostr?: { getPublicKey(): Promise; signEvent(event: NostrEvent): Promise<{ sig: string; }>; getRelays?: () => Promise; nip04?: { encrypt(recipientHexPubKey: string, value: string): Promise; decrypt(senderHexPubKey: string, value: string): Promise; }; nip44?: Nip44; }; } } interface NDKRpcRequest { id: string; pubkey: string; method: string; params: string[]; event: NDKEvent; } interface NDKRpcResponse { id: string; result: string; error?: string; event: NDKEvent; } declare class NDKNostrRpc extends EventEmitter { private ndk; private signer; private relaySet; private debug; encryptionType: "nip04" | "nip44"; private pool; constructor(ndk: NDK, signer: NDKSigner, debug: debug.Debugger, relayUrls?: string[]); /** * Updates the relay set used for RPC communication. * Disconnects from old relays and connects to new ones. */ updateRelays(relayUrls: string[]): void; /** * Subscribe to a filter. This function will resolve once the subscription is ready. */ subscribe(filter: NDKFilter): Promise; parseEvent(event: NDKEvent): Promise; sendResponse(id: string, remotePubkey: string, result: string, kind?: NDKKind, error?: string): Promise; /** * Sends a request. * @param remotePubkey * @param method * @param params * @param kind * @param id */ sendRequest(remotePubkey: string, method: string, params?: string[], kind?: number, cb?: (res: NDKRpcResponse) => void): Promise; } type NIP46Method = "connect" | "sign_event" | "nip04_encrypt" | "nip04_decrypt" | "nip44_encrypt" | "nip44_decrypt" | "get_public_key" | "ping" | "switch_relays"; type Nip46PermitCallbackParams = { /** * ID of the request */ id: string; pubkey: string; method: NIP46Method; params?: any; }; type Nip46PermitCallback = (params: Nip46PermitCallbackParams) => Promise; type Nip46ApplyTokenCallback = (pubkey: string, token: string) => Promise; interface IEventHandlingStrategy { handle(backend: NDKNip46Backend, id: string, remotePubkey: string, params: string[]): Promise; } /** * This class implements a NIP-46 backend, meaning that it will hold a private key * of the npub that wants to be published as. * * This backend is meant to be used by an NDKNip46Signer, which is the class that * should run client-side, where the user wants to sign events from. */ declare class NDKNip46Backend { readonly ndk: NDK; readonly signer: NDKSigner; localUser?: NDKUser; readonly debug: debug.Debugger; rpc: NDKNostrRpc; private permitCallback; relayUrls: WebSocket["url"][]; /** * @param ndk The NDK instance to use * @param signer The signer for the private key that wants to be published as * @param permitCallback Callback executed when permission is requested */ constructor(ndk: NDK, signer: NDKSigner, permitCallback: Nip46PermitCallback, relayUrls?: WebSocket["url"][]); /** * @param ndk The NDK instance to use * @param privateKey The private key of the npub that wants to be published as * @param permitCallback Callback executed when permission is requested */ constructor(ndk: NDK, privateKey: string, permitCallback: Nip46PermitCallback, relayUrls?: WebSocket["url"][]); /** * This method starts the backend, which will start listening for incoming * requests. */ start(): Promise; handlers: { [method: string]: IEventHandlingStrategy; }; /** * Enables the user to set a custom strategy for handling incoming events. * @param method - The method to set the strategy for * @param strategy - The strategy to set */ setStrategy(method: string, strategy: IEventHandlingStrategy): void; /** * Overload this method to apply tokens, which can * wrap permission sets to be applied to a pubkey. * @param pubkey public key to apply token to * @param token token to apply */ applyToken(_pubkey: string, _token: string): Promise; protected handleIncomingEvent(event: NDKEvent): Promise; /** * This method should be overriden by the user to allow or reject incoming * connections. */ pubkeyAllowed(params: Nip46PermitCallbackParams): Promise; } /** * Options for generating a nostrconnect:// URI. */ interface NostrConnectOptions { name?: string; url?: string; image?: string; perms?: string; } /** * This NDKSigner implements NIP-46, which allows remote signing of events. * This class is meant to be used client-side, paired with the NDKNip46Backend or a NIP-46 backend (like Nostr-Connect) * * @emits authUrl -- Emitted when the user should take an action in certain URL. * When a client receives this event, it should direct the user * to go to that URL to authorize the application. * * @example * const ndk = new NDK() * const nip05 = await prompt("enter your scheme-05") // Get a NIP-05 the user wants to login with * const privateKey = localStorage.getItem("nip46-local-key") // If we have a private key previously saved, use it * const signer = NDKNip46Signer.bunker(ndk, nip05, privateKey) // Create a signer with (or without) a private key * * // Save generated private key for future use * localStorage.setItem("nip46-local-key", signer.localSigner.privateKey) * * // If the backend sends an auth_url event, open that URL as a popup so the user can authorize the app * signer.on("authUrl", (url) => { window.open(url, "auth", "width=600,height=600") }) * * // wait until the signer is ready * const loggedinUser = await signer.blockUntilReady() * * alert("You are now logged in as " + loggedinUser.npub) */ declare class NDKNip46Signer extends EventEmitter implements NDKSigner { private ndk; private _user?; /** * The pubkey of the bunker that will be providing signatures */ bunkerPubkey: string | undefined; /** * The pubkey of the user that events will be published as */ userPubkey?: string | null; get pubkey(): string; /** * An optional secret value provided to connect to the bunker */ secret?: string | null; localSigner: NDKPrivateKeySigner; private nip05?; rpc: NDKNostrRpc; private debug; relayUrls: string[] | undefined; private subscription; /** * If using nostrconnect://, stores the nostrConnectURI */ nostrConnectUri?: string; /** * The random secret used for nostrconnect:// flows. */ private nostrConnectSecret?; /** * * Don't instantiate this directly. Use the static methods instead. * * @example: * // for bunker:// flow * const signer = NDKNip46Signer.bunker(ndk, "bunker://") * const signer = NDKNip46Signer.bunker(ndk, ""); // with nip05 flow * // for nostrconnect:// flow * const signer = NDKNip46Signer.nostrconnect(ndk, "wss://relay.example.com") * * @param ndk - The NDK instance to use * @param userOrConnectionToken - The public key, or a connection token, of the npub that wants to be published as * @param localSigner - The signer that will be used to request events to be signed */ constructor(ndk: NDK, userOrConnectionToken?: string | false, localSigner?: NDKPrivateKeySigner | string, relayUrls?: string[], nostrConnectOptions?: NostrConnectOptions); /** * Connnect with a bunker:// flow * @param ndk * @param userOrConnectionToken bunker:// connection string * @param localSigner If you have previously authenticated with this signer, you can restore the session by providing the previously authenticated key */ static bunker(ndk: NDK, userOrConnectionToken?: string, localSigner?: NDKPrivateKeySigner | string): NDKNip46Signer; /** * Connect with a nostrconnect:// flow * @param ndk * @param relay - Relay used to connect with the signer * @param localSigner If you have previously authenticated with this signer, you can restore the session by providing the previously authenticated key */ static nostrconnect(ndk: NDK, relay: string, localSigner?: NDKPrivateKeySigner | string, nostrConnectOptions?: NostrConnectOptions): NDKNip46Signer; private nostrconnectFlowInit; private bunkerFlowInit; private nip05Init; /** * We start listening for events from the bunker */ private startListening; /** * Get the user that is being published as */ user(): Promise; get userSync(): NDKUser; blockUntilReadyNostrConnect(): Promise; blockUntilReady(): Promise; /** * Sends a switch_relays request to the bunker. * If the bunker responds with new relay URLs, updates the RPC layer * and resubscribes on the new relays. */ private switchRelays; stop(): void; getPublicKey(): Promise; encryptionEnabled(scheme?: NDKEncryptionScheme): Promise; encrypt(recipient: NDKUser, value: string, scheme?: NDKEncryptionScheme): Promise; decrypt(sender: NDKUser, value: string, scheme?: NDKEncryptionScheme): Promise; private encryption; sign(event: NostrEvent): Promise; /** * Allows creating a new account on the remote server. * @param username Desired username for the NIP-05 * @param domain Desired domain for the NIP-05 * @param email Email address to associate with this account -- Remote servers may use this for recovery * @returns The public key of the newly created account */ createAccount(username?: string, domain?: string, email?: string): Promise; /** * Serializes the signer's connection details and local signer state. * @returns A JSON string containing the type, connection info, and local signer payload. */ toPayload(): string; /** * Deserializes the signer from a payload string. * @param payloadString The JSON string obtained from toPayload(). * @param ndk The NDK instance, required for NIP-46. * @returns An instance of NDKNip46Signer. */ static fromPayload(payloadString: string, ndk: NDK): Promise; } /** * Register a signer in the registry */ declare function registerSigner(type: string, signerClass: NDKSignerStatic): void; /** * Checks if a subscription is fully guaranteed to have been filled. * * This is useful to determine if a cache hit fully satisfies a subscription. * * @param subscription * @returns */ declare function queryFullyFilled(subscription: NDKSubscription): boolean; /** * Compares whether a filter includes another filter. * @param filter1 Filter to compare from * @param filter2 Filter to compare to * @example * const filter1 = { authors: ["a", "b"] }; * const filter2 = { authors: ["a", "b", "c"] }; * compareFilter(filter1, filter2); // true * * const filter1 = { authors: ["a", "b"] }; * const filter2 = { authors: ["a", "c"] }; * compareFilter(filter1, filter2); // false * @returns */ declare function compareFilter(filter1: NDKFilter, filter2: NDKFilter): boolean; /** * Generates a subscription ID based on the subscriptions and filter. * * When some of the subscriptions specify a subId, those are used, * joining them with a comma. * * If none of the subscriptions specify a subId, a subId is generated * by joining all the filter keys, and expanding the kinds with the requested kinds. */ declare function generateSubId(subscriptions: NDKSubscription[], filters: NDKFilter[]): string; /** * Creates a valid nostr filter to REQ events that are tagging a NIP-19 bech32 * @param id Bech32 of the event * @example * const bech32 = "nevent1qgs9kqvr4dkruv3t7n2pc6e6a7v9v2s5fprmwjv4gde8c4fe5y29v0spzamhxue69uhhyetvv9ujuurjd9kkzmpwdejhgtcqype6ycavy2e9zpx9mzeuekaahgw96ken0mzkcmgz40ljccwyrn88gxv2ewr" * const filter = filterForEventsTaggingId(bech32); * // filter => { "#e": [] } * * @example * const bech32 = "naddr1qvzqqqr4gupzpjjwt0eqm6as279wf079c0j42jysp2t4s37u8pg5w2dfyktxgkntqqxnzde38yen2desxqmn2d3332u3ff"; * const filter = filterForEventsTaggingId(bech32); * // filter => { "#a": ["30023:ca4e5bf20debb0578ae4bfc5c3e55548900a975847dc38514729a92596645a6b:1719357007561"]} */ declare function filterForEventsTaggingId(id: string): NDKFilter | undefined; /** * Creates a valid nostr filter from a bech32 encoding along with a relay set (if one is present in the encoding). * @param id Bech32 of the event * @param ndk * @returns * @example * const bech32 = "nevent1qgs9kqvr4dkruv3t7n2pc6e6a7v9v2s5fprmwjv4gde8c4fe5y29v0spzamhxue69uhhyetvv9ujuurjd9kkzmpwdejhgtcqype6ycavy2e9zpx9mzeuekaahgw96ken0mzkcmgz40ljccwyrn88gxv2ewr"; * const { filter, relaySet } = filterAndRelaySetFromBech32(bech32, ndk); * // filter => { ids: [...], authors: [...] } */ declare function filterAndRelaySetFromBech32(bech32: string, ndk: NDK): { filter: NDKFilter; relaySet?: NDKRelaySet; }; /** * Creates a valid nostr filter from an event id or a NIP-19 bech32. * * @example * const bech32 = "nevent1qgs9kqvr4dkruv3t7n2pc6e6a7v9v2s5fprmwjv4gde8c4fe5y29v0spzamhxue69uhhyetvv9ujuurjd9kkzmpwdejhgtcqype6ycavy2e9zpx9mzeuekaahgw96ken0mzkcmgz40ljccwyrn88gxv2ewr" * const filter = filterFromBech32(bech32); * // filter => { ids: [...], authors: [...] } */ declare function filterFromId(id: string): NDKFilter; declare function isNip33AValue(value: string): boolean; /** * Matches an `a` tag of a NIP-33 (kind:pubkey:[identifier]) */ declare const NIP33_A_REGEX: RegExp; declare const BECH32_REGEX: RegExp; /** * Returns the specified relays from a NIP-19 bech32. * * @param bech32 The NIP-19 bech32. */ declare function relaysFromBech32(bech32: string, ndk: NDK): NDKRelay[]; declare function eventsBySameAuthor(op: NDKEvent, events: NDKEvent[]): Map; /** * Checks if an event is a reply to an original post or to a thread. * @param op The original event * @param event The event to check * @param threadIds An optional map of all events in the thread * @param tagType The tag type to search for (default: "e" for non-replaceable events and "a" for replaceable events) * @returns True if the event is a reply, false otherwise */ declare function eventIsReply(op: NDKEvent, event: NDKEvent, threadIds?: Set, tagType?: string): boolean; /** * Filters the returned events so that the result is the events that are * part of a thread. * * Threads are defined as a sequence of events that are related to each other * and authored by the same user. * @param op The original event * @param events All candidate events (e.g. events tagging the OP) * @returns The events that are part of the thread sorted by creation time */ declare function eventThreads(op: NDKEvent, events: NDKEvent[]): NDKEvent[]; /** * Returns the reply ID of an event. * @param event The event to get the reply ID from * @returns The reply ID or undefined if the event is not a reply */ declare function getEventReplyId(event: NDKEvent): NDKEventId | undefined; declare function isEventOriginalPost(event: NDKEvent): boolean; declare function eventThreadIds(op: NDKEvent, events: NDKEvent[]): Map; declare function eventReplies(op: NDKEvent, events: NDKEvent[], threadEventIds: Set): NDKEvent[]; /** * Checks if an event is part of a thread. * @param op The original event * @param event The event to check * @param eventsByAuthor A map of all candidate events by the original author * @returns True if the event is part of the thread, false otherwise */ declare function eventIsPartOfThread(op: NDKEvent, event: NDKEvent, eventsByAuthor: Map): boolean; /** * Checks if an event has ETag markers. */ declare function eventHasETagMarkers(event: NDKEvent): boolean; /** * Returns the root event ID of an event. * @param event The event to get the root event ID from * @param searchTag The tags to search for the root event ID @default "a" or "e" * @returns The root event ID or undefined if the event does not have a root event ID */ declare function getRootEventId(event: NDKEvent, searchTag?: string): NDKEventId | null | undefined; /** * Returns the root tag of an event. * @param event The event to get the root tag from * @param searchTags The tags to search for the root tag (default: ["a", "e"]) * @returns The root tag or undefined if the event does not have a root tag */ declare function getRootTag(event: NDKEvent, searchTag?: string): NDKTag | undefined; declare function getReplyTag(event: NDKEvent, searchTag?: string): NDKTag | undefined; /** * Pins an event */ declare function pinEvent(user: NDKUser, event: NDKEvent, pinEvent?: NDKEvent, publish?: boolean): Promise; /** * Matches a filter against an event * @param filter - The filter to match against * @param event - The event to match * @returns True if the event matches the filter, false otherwise */ declare function matchFilter(filter: NDKFilter, event: NDKRawEvent): boolean; /** * Validates if a string is a valid 64-character hexadecimal string. * Used for pubkeys and event IDs. * * @param value - The string to validate * @returns true if the string is exactly 64 hex characters, false otherwise */ declare function isValidHex64(value: string): boolean; /** * Validates if a string is a valid nostr pubkey (64-character hex string). * * @param pubkey - The string to validate * @returns true if the string is a valid pubkey, false otherwise * * @example * ```typescript * if (isValidPubkey(pubkey)) { * // Safe to use * } * ``` */ declare function isValidPubkey(pubkey: string): boolean; /** * Validates if a string is a valid event ID (64-character hex string). * * @param id - The string to validate * @returns true if the string is a valid event ID, false otherwise * * @example * ```typescript * if (isValidEventId(eventId)) { * // Safe to use * } * ``` */ declare function isValidEventId(id: string): boolean; /** * Check if a string is a NIP-05 identifier (contains a dot indicating a domain). * This performs a simple format check, not full NIP-05 validation. * * @param input - String to check * @returns true if the input appears to be a NIP-05 identifier * * @example * ```typescript * isValidNip05("user@domain.com") // true * isValidNip05("domain.com") // true * isValidNip05("npub1...") // false * ``` */ declare function isValidNip05(input: string): boolean; declare function getRelayListForUser(pubkey: Hexpubkey, ndk: NDK): Promise; /** * Fetches a map of relay lists for a number of users * @param pubkeys * @param ndk * @param skipCache * @param timeout * @param relayHints - Optional map of pubkey to relay URLs to augment the relay set for fetching that user's relay list * @returns */ declare function getRelayListForUsers(pubkeys: Hexpubkey[], ndk: NDK, skipCache?: boolean, timeout?: number, relayHints?: Map): Promise>; declare function tryNormalizeRelayUrl(url: string): string | undefined; /** * Normalizes a relay URL by removing authentication, www, and hash, * and ensures that it ends with a slash. * * @param url - The URL to be normalized. * @returns The normalized URL. */ declare function normalizeRelayUrl(url: string): string; /** * Normalizes an array of URLs by removing duplicates and applying a normalization function to each URL. * Any URLs that fail to normalize will be ignored. * * @param urls - An array of URLs to be normalized. * @returns An array of normalized URLs without duplicates. */ declare function normalize(urls: string[]): string[]; declare function normalizeUrl(urlString: string, options?: any): string; /** * Generates a NIP-57 zap request (kind 9734) * * @param target - The user or event being zapped * @param ndk - NDK instance * @param data - LNURL data containing callback endpoint * @param pubkey - Recipient's pubkey * @param amount - Amount to zap in millisatoshis * @param relays - Relay URLs for the zap receipt * @param comment - Optional comment for the zap * @param tags - Additional tags to include * @param signer - Signer to use for signing the zap request * @returns The signed zap request event */ declare function generateZapRequest(target: NDKEvent | NDKUser, ndk: NDK, data: NDKLnUrlData, pubkey: string, amount: number, // amount to zap in millisatoshis relays: string[], comment?: string, tags?: NDKTag[], signer?: NDKSigner): Promise; export { BECH32_REGEX, type CacheModuleCollection, type CacheModuleDefinition, type CacheModuleMigrationContext, type CacheModuleStorage, type CashuPayCb, type CashuPaymentInfo, type CollaborativeEventUpdateCallback, type ContentTag, type ContentTaggingOptions, type DIRECTIONS, type EventPointer, type GiftWrapParams, HLL_REGISTER_COUNT, type Hexpubkey, type IEventHandlingStrategy, type LNPaymentRequest, type LnPayCb, type LnPaymentInfo, type NDKAggregatedCountResult, NDKAppHandlerEvent, NDKAppSettings, NDKArticle, type NDKAuthPolicy, NDKBlossomList, type NDKCacheAdapter, type NDKCacheEntry, type NDKCacheRelayInfo, NDKCashuMintAnnouncement, NDKCashuMintList, NDKCashuToken, NDKCashuWalletTx, NDKClassified, NDKCollaborativeEvent, type NDKConstructorParams, NDKCountHll, type NDKCountOptions, type NDKCountResult, NDKDVMJobFeedback, NDKDVMJobResult, NDKDVMRequest, NDKDraft, NDKDvmJobFeedbackStatus, type NDKDvmParam, type NDKEncryptionScheme, NDKEvent, type NDKEventId, type NDKEventSerialized, type NDKEventVariant, NDKFedimintMint, type NDKFilter, type NDKFilterFingerprint, NDKFilterValidationMode, NDKFollowPack, NDKHighlight, NDKImage, type NDKImetaTag, NDKInterestList, type NDKIntervalFrequency, NDKKind, type NDKLUD18ServicePayerData, NDKList, type NDKListItem, NDKListKinds, type NDKLnLudData, type NDKLnUrlData, NDKMintRecommendation, NDKNip07Signer, NDKNip46Backend, NDKNip46Signer, NDKNostrRpc, NDKNutzap, type NDKNutzapState, type NDKPaymentConfirmation, type NDKPaymentConfirmationCashu, type NDKPaymentConfirmationLN, NDKPool, NDKPrivateKeySigner, NDKProject, NDKProjectTemplate, type NDKProtocolHandler, NDKPublishError, type NDKRawEvent, NDKRelay, NDKRelayAuthPolicies, type NDKRelayConnectionStats, NDKRelayFeedList, type NDKRelayInformation, NDKRelayList, NDKRelaySet, NDKRelayStatus, type NDKRelayUrl, NDKRepost, type NDKRpcRequest, type NDKRpcResponse, type NDKSignedEvent, type NDKSigner, type NDKSignerPayload, type NDKSignerStatic, NDKSimpleGroup, NDKSimpleGroupMemberList, NDKSimpleGroupMetadata, type NDKStickerPosition, NDKStory, type NDKStoryDimension, NDKStorySticker, NDKStoryStickerType, NDKSubscription, type NDKSubscriptionAmount, NDKSubscriptionCacheUsage, type NDKSubscriptionDelayedType, type NDKSubscriptionInternalId, type NDKSubscriptionOptions, NDKSubscriptionReceipt, NDKSubscriptionStart, NDKSubscriptionTier, type NDKTag, NDKTask, NDKThread, NDKTranscriptionDVM, type NDKUnsignedEvent, NDKUser, type NDKUserParams, type NDKUserProfile, NDKVideo, NDKVoiceMessage, NDKVoiceReply, type NDKWalletInterface, NDKWiki, NDKWikiMergeRequest, NDKZap, type NDKZapConfirmation, type NDKZapConfirmationCashu, type NDKZapConfirmationLN, type NDKZapDetails, type NDKZapInvoice, type NDKZapMethod, type NDKZapMethodInfo, type NDKZapSplit, NDKZapper, NIP33_A_REGEX, type NIP46Method, NdkNutzapStatus, type Nip46ApplyTokenCallback, type Nip46PermitCallback, type Nip46PermitCallbackParams, type NostrEvent, type Npub, NutzapValidationCode, type NutzapValidationIssue, type NutzapValidationResult, NutzapValidationSeverity, type OnCompleteCb, type ParsedContentMatch, type ProfilePointer, SignatureVerificationStats, type StickerDimension, type StickerProperties, type StorySticker, type StoryValueType, assertSignedEvent, calculateRelaySetFromEvent, calculateTermDurationInSeconds, cashuPubkeyToNostrPubkey, compareFilter, createSignedEvent, createValidationIssue, NDK as default, defaultOpts, deserialize, dvmSchedule, eventHasETagMarkers, eventIsPartOfThread, eventIsReply, eventReplies, eventThreadIds, eventThreads, eventsBySameAuthor, fetchRelayInformation, filterAndRelaySetFromBech32, filterEphemeralKindsFromFilter, filterFingerprint, filterForCache, filterForEventsTaggingId, filterFromId, generateContentTags, generateHashtags, generateSubId, generateZapRequest, getEventReplyId, getNip57ZapSpecFromLud, getRegisteredEventClasses, getRelayListForUser, getRelayListForUsers, getReplyTag, getRootEventId, getRootTag, giftUnwrap, giftWrap, imetaTagToTag, isEphemeralKind, isEventOriginalPost, isNip33AValue, isSignedEvent, isUnsignedEvent, isValidEventId, isValidHex64, isValidNip05, isValidPubkey, mapImetaTag, matchFilter, mergeFilters, mergeTags, ndkSignerFromPayload, newAmount, index$1 as nip19, index as nip49, normalize, normalizeRelayUrl, normalizeUrl, parseTagToSubscriptionAmount, pinEvent, possibleIntervalFrequencies, processFilters, profileFromEvent, proofP2pk, proofP2pkNostr, proofsTotalBalance, queryFullyFilled, registerEventClass, registerSigner, relayListFromKind3, relaysFromBech32, serialize, serializeProfile, startSignatureVerificationStats, strToDimension, strToPosition, tryNormalizeRelayUrl, uniqueTag, unregisterEventClass, wrapEvent, zapInvoiceFromEvent };