applesauce-core 5.1.0 → 6.0.0

package/dist/observable/timeout-with-ignore.d.ts

@@ -0,0 +1,24 @@
+import { type ObservableInput, type ObservedValueOf, type OperatorFunction, type TimeoutConfig } from "rxjs";
+/**
+ * Like RxJS `timeout`, but only for emissions that are not ignored.
+ *
+ * Values that match `config.ignore` are forwarded immediately and do not affect
+ * timeout state (`first`/`each`). Timeout timing only observes non-ignored values.
+ *
+ * Example usage:
+ *
+ *   source$.pipe(
+ *     timeoutWithIgnore({
+ *       first: 1500,
+ *       each: 1000,
+ *       with: () => of(null),
+ *       ignore: value => value === undefined,
+ *     })
+ *   )
+ *
+ * @param config RxJS timeout config with an additional `ignore` matcher
+ * (`(value) => boolean` or array of values) used to bypass timeout checks.
+ */
+export declare function timeoutWithIgnore<T, O extends ObservableInput<unknown> = ObservableInput<T>, M = unknown>(config: TimeoutConfig<T, O, M> & {
+    ignore: readonly T[] | ((value: T) => boolean);
+}): OperatorFunction<T, T | ObservedValueOf<O>>;

package/dist/observable/timeout-with-ignore.js

@@ -0,0 +1,33 @@
+import { endWith, filter, ignoreElements, merge, share, takeUntil, timeout, } from "rxjs";
+/**
+ * Like RxJS `timeout`, but only for emissions that are not ignored.
+ *
+ * Values that match `config.ignore` are forwarded immediately and do not affect
+ * timeout state (`first`/`each`). Timeout timing only observes non-ignored values.
+ *
+ * Example usage:
+ *
+ *   source$.pipe(
+ *     timeoutWithIgnore({
+ *       first: 1500,
+ *       each: 1000,
+ *       with: () => of(null),
+ *       ignore: value => value === undefined,
+ *     })
+ *   )
+ *
+ * @param config RxJS timeout config with an additional `ignore` matcher
+ * (`(value) => boolean` or array of values) used to bypass timeout checks.
+ */
+export function timeoutWithIgnore(config) {
+    return (source) => {
+        const { ignore, ...timeoutConfig } = config;
+        const isIgnored = (value) => (typeof ignore === "function" ? ignore(value) : ignore.includes(value));
+        const shared$ = source.pipe(share());
+        const watched$ = shared$.pipe(filter((value) => !isIgnored(value)));
+        const ignored$ = shared$.pipe(filter(isIgnored));
+        const timed$ = watched$.pipe(timeout(timeoutConfig), share());
+        // Stop forwarding ignored values as soon as the timed branch completes/errors.
+        return merge(timed$, ignored$).pipe(takeUntil(timed$.pipe(ignoreElements(), endWith(true))));
+    };
+}

package/dist/operations/client.d.ts

@@ -1,4 +1,4 @@
-import { EventOperation } from "../event-factory/types.js";
+import type { EventOperation } from "../factories/types.js";
 import { AddressPointer } from "../helpers/pointers.js";
 /** Includes a NIP-89 client tag in an event*/
 export declare function setClient(name: string, pointer?: Omit<AddressPointer, "kind" | "relays">, replace?: boolean): EventOperation;

package/dist/operations/client.js

@@ -6,7 +6,7 @@ import { includeSingletonTag } from "./tags.js";
 const NEVER_ATTACH_CLIENT_TAG = [kinds.EncryptedDirectMessage, kinds.GiftWrap, kinds.Seal, kinds.PrivateDirectMessage];
 /** Includes a NIP-89 client tag in an event*/
 export function setClient(name, pointer, replace = true) {
-    return (draft, ctx) => {
+    return (draft) => {
         if (NEVER_ATTACH_CLIENT_TAG.includes(draft.kind))
             return draft;
         else {
@@ -17,7 +17,7 @@ export function setClient(name, pointer, replace = true) {
                     kind: kinds.Handlerinformation,
                 })
                 : undefined;
-            return includeSingletonTag(fillAndTrimTag(["client", name, coordinate]), replace)(draft, ctx);
+            return includeSingletonTag(fillAndTrimTag(["client", name, coordinate]), replace)(draft);
         }
     };
 }

package/dist/operations/content.d.ts

@@ -1,4 +1,4 @@
-import { Emoji, EventOperation } from "../event-factory/types.js";
+import type { EventOperation, Emoji } from "../factories/types.js";
 /** Override the event content */
 export declare function setContent(content: string): EventOperation;
 /** Replaces any `@npub` or bare npub mentions with nostr: prefix */
@@ -11,7 +11,10 @@ export declare function setContentWarning(warning: boolean | string): EventOpera
 export declare function includeQuoteTags(): EventOperation;
 /** Adds "t" tags for every #hashtag in the content */
 export declare function includeContentHashtags(): EventOperation;
-/** Adds "emoji" tags for NIP-30 emojis used in the content */
+/**
+ * Adds "emoji" tags for NIP-30 emojis used in the content
+ * @param emojis - Array of custom emojis to check for in content
+ */
 export declare function includeEmojis(emojis?: Emoji[]): EventOperation;
 export type TextContentOptions = {
     emojis?: Emoji[];

package/dist/operations/content.js

@@ -1,7 +1,7 @@
 import { EncryptedContentSymbol } from "../helpers/encrypted-content.js";
 import { ensureProfilePointerTag, ensureQuoteEventPointerTag } from "../helpers/factory.js";
 import { eventPipe, skip } from "../helpers/pipeline.js";
-import { getContentPointers, getPubkeyFromDecodeResult } from "../helpers/pointers.js";
+import { getContentPointers, getPubkeyFromDecodeResult, getReplaceableAddressFromPointer, } from "../helpers/pointers.js";
 import { Expressions } from "../helpers/regexp.js";
 import { ensureNamedValueTag } from "../helpers/tags.js";
 /** Override the event content */
@@ -16,7 +16,7 @@ export function setContent(content) {
 export function repairNostrLinks() {
     return (draft) => ({
         ...draft,
-        content: draft.content.replaceAll(/(?<=^|\s)(?:@)?((?:npub|note|nprofile|nevent|naddr)1[qpzry9x8gf2tvdw0s3jn54khce6mua7l]{58})/gi, "nostr:$1"),
+        content: draft.content.replaceAll(/(?<=^|\s)(?:@)?((?:npub|note|nprofile|nevent|naddr)1[qpzry9x8gf2tvdw0s3jn54khce6mua7l]{58,})/gi, "nostr:$1"),
     });
 }
 /** "p" tag any pubkey mentioned in the content using nostr: links */
@@ -76,17 +76,21 @@ export function includeContentHashtags() {
         return { ...draft, tags };
     };
 }
-/** Adds "emoji" tags for NIP-30 emojis used in the content */
-export function includeEmojis(emojis) {
-    return (draft, ctx) => {
-        const all = [...(ctx.emojis ?? []), ...(emojis ?? [])];
+/**
+ * Adds "emoji" tags for NIP-30 emojis used in the content
+ * @param emojis - Array of custom emojis to check for in content
+ */
+export function includeEmojis(emojis = []) {
+    return (draft) => {
         const tags = Array.from(draft.tags);
-        // create tags for all occurrences of #hashtag
+        // create tags for all occurrences of :emoji:
         const matches = draft.content.matchAll(Expressions.emoji);
         for (const [_, name] of matches) {
-            const emoji = all.find((e) => e.shortcode === name);
+            const emoji = emojis.find((e) => e.shortcode === name);
             if (emoji?.url) {
-                tags.push(["emoji", emoji.shortcode, emoji.url]);
+                tags.push(emoji.address
+                    ? ["emoji", emoji.shortcode, emoji.url, getReplaceableAddressFromPointer(emoji.address)]
+                    : ["emoji", emoji.shortcode, emoji.url]);
             }
         }
         return { ...draft, tags };

package/dist/operations/delete.d.ts

@@ -1,4 +1,4 @@
-import { EventOperation } from "../event-factory/types.js";
+import type { EventOperation } from "../factories/types.js";
 import { NostrEvent } from "../helpers/event.js";
 /** Sets the necessary tags for a NIP-09 delete event to point to a the events being deleted */
 export declare function setDeleteEvents(events: (string | NostrEvent)[]): EventOperation;

package/dist/operations/encrypted-content.d.ts

@@ -1,4 +1,10 @@
-import { EventOperation } from "../event-factory/types.js";
+import type { EventOperation } from "../factories/types.js";
 import { EncryptionMethod } from "../helpers/encrypted-content.js";
-/** Sets the content to be encrypted to the pubkey with optional override method */
-export declare function setEncryptedContent(pubkey: string, content: string, override?: EncryptionMethod): EventOperation;
+/**
+ * Sets the content to be encrypted to the pubkey with optional override method
+ * @param pubkey - Pubkey to encrypt the content for
+ * @param content - Plaintext content to encrypt
+ * @param signer - EventSigner for encryption
+ * @param override - Optional encryption method override
+ */
+export declare function setEncryptedContent(pubkey: string, content: string, signer?: import("../factories/types.js").EventSigner, override?: EncryptionMethod): EventOperation;

package/dist/operations/encrypted-content.js

@@ -1,7 +1,13 @@
 import { EncryptedContentSymbol, getEncryptedContentEncryptionMethods, } from "../helpers/encrypted-content.js";
-/** Sets the content to be encrypted to the pubkey with optional override method */
-export function setEncryptedContent(pubkey, content, override) {
-    return async (draft, { signer }) => {
+/**
+ * Sets the content to be encrypted to the pubkey with optional override method
+ * @param pubkey - Pubkey to encrypt the content for
+ * @param content - Plaintext content to encrypt
+ * @param signer - EventSigner for encryption
+ * @param override - Optional encryption method override
+ */
+export function setEncryptedContent(pubkey, content, signer, override) {
+    return async (draft) => {
         if (!signer)
             throw new Error("Signer required for encrypted content");
         // Set method based on kind if not provided

package/dist/operations/event.d.ts

@@ -1,5 +1,5 @@
-import { EventOperation } from "../event-factory/types.js";
-import { EventTemplate, NostrEvent, UnsignedEvent } from "../helpers/event.js";
+import type { EventOperation } from "../factories/types.js";
+import { EventTemplate, KnownEvent, KnownEventTemplate, KnownUnsignedEvent, NostrEvent, UnsignedEvent } from "../helpers/event.js";
 /** An operation that removes the signature from the event template */
 export declare function stripSignature<Input extends NostrEvent | UnsignedEvent | EventTemplate>(): EventOperation<Input, Omit<Input, "sig">>;
 /** An operation that removes the id and pubkey from the event template */
@@ -29,11 +29,13 @@ export type MetaTagOptions = {
 export declare function setMetaTags(options?: MetaTagOptions): EventOperation;
 /**
  * An operation that adds the signers pubkey to the event
+ * @param signer - Optional EventSigner (throws if not provided)
  * @throws {Error} if no signer is provided
  */
-export declare function stamp(): EventOperation<EventTemplate, UnsignedEvent>;
+export declare function stamp<K extends number = number>(signer?: import("../factories/types.js").EventSigner): EventOperation<KnownEventTemplate<K>, KnownUnsignedEvent<K>>;
 /**
  * An operation that signs the event
+ * @param signer - Optional EventSigner (throws if not provided)
  * @throws {Error} if no signer is provided
  */
-export declare function sign(): EventOperation<EventTemplate | UnsignedEvent, NostrEvent>;
+export declare function sign<K extends number = number, T extends KnownEventTemplate<K> = KnownEventTemplate<K>>(signer?: import("../factories/types.js").EventSigner): EventOperation<T, KnownEvent<K>>;

package/dist/operations/event.js

@@ -1,12 +1,12 @@
 import { nanoid } from "nanoid";
-import { getTagValue } from "../helpers/event.js";
-import { isAddressableKind } from "../helpers/event.js";
+import { isKind } from "nostr-tools/kinds";
+import { EncryptedContentSymbol } from "../helpers/encrypted-content.js";
+import { getTagValue, isAddressableKind, } from "../helpers/event.js";
 import { eventPipe, skip } from "../helpers/pipeline.js";
 import { ensureSingletonTag } from "../helpers/tags.js";
 import { unixNow } from "../helpers/time.js";
 import { removeSingletonTag, setSingletonTag } from "./tag/common.js";
 import { includeSingletonTag, modifyPublicTags } from "./tags.js";
-import { EncryptedContentSymbol } from "../helpers/encrypted-content.js";
 /** An operation that removes the signature from the event template */
 export function stripSignature() {
     return (draft) => {
@@ -72,16 +72,17 @@ export function setMetaTags(options) {
 }
 /**
  * An operation that adds the signers pubkey to the event
+ * @param signer - Optional EventSigner (throws if not provided)
  * @throws {Error} if no signer is provided
  */
-export function stamp() {
-    return async (draft, ctx) => {
-        if (!ctx.signer)
+export function stamp(signer) {
+    return async (draft) => {
+        if (!signer)
             throw new Error("Missing signer");
         // Remove old fields from signed nostr event
         Reflect.deleteProperty(draft, "id");
         Reflect.deleteProperty(draft, "sig");
-        const pubkey = await ctx.signer.getPublicKey();
+        const pubkey = await signer.getPublicKey();
         const newDraft = { ...draft, pubkey };
         // copy the plaintext hidden content if its on the draft
         if (Reflect.has(draft, EncryptedContentSymbol))
@@ -91,14 +92,21 @@ export function stamp() {
 }
 /**
  * An operation that signs the event
+ * @param signer - Optional EventSigner (throws if not provided)
  * @throws {Error} if no signer is provided
  */
-export function sign() {
-    return async (draft, ctx) => {
-        if (!ctx.signer)
+export function sign(signer) {
+    return async (draft) => {
+        if (!signer)
             throw new Error("Missing signer");
-        draft = await stamp()(draft, ctx);
-        const signed = await ctx.signer.signEvent(draft);
+        const unsigned = await stamp(signer)(draft);
+        const signed = await signer.signEvent(unsigned);
+        // Verify the pubkey has not changed
+        if (Reflect.has(draft, "pubkey") && Reflect.get(draft, "pubkey") !== signed.pubkey)
+            throw new Error("Signer modified pubkey");
+        // If its the same kind, return the signed event
+        if (!isKind(signed, draft.kind))
+            throw new Error("Signer modified event kind");
         // copy the plaintext hidden content if its on the draft
         if (Reflect.has(draft, EncryptedContentSymbol))
             Reflect.set(signed, EncryptedContentSymbol, Reflect.get(draft, EncryptedContentSymbol));

package/dist/operations/hidden-content.d.ts

@@ -1,4 +1,9 @@
-import { EventOperation } from "../event-factory/types.js";
+import type { EventOperation } from "../factories/types.js";
 import { EncryptionMethod } from "../helpers/encrypted-content.js";
-/** Sets the hidden content on an event */
-export declare function setHiddenContent(content: string, override?: EncryptionMethod): EventOperation;
+/**
+ * Sets the hidden content on an event
+ * @param content - Plaintext content to encrypt
+ * @param signer - EventSigner for encryption
+ * @param override - Optional encryption method override
+ */
+export declare function setHiddenContent(content: string, signer?: import("../factories/types.js").EventSigner, override?: EncryptionMethod): EventOperation;

package/dist/operations/hidden-content.js

@@ -1,10 +1,15 @@
 import { setEncryptedContent } from "./encrypted-content.js";
-/** Sets the hidden content on an event */
-export function setHiddenContent(content, override) {
-    return async (draft, ctx) => {
-        if (!ctx.signer)
+/**
+ * Sets the hidden content on an event
+ * @param content - Plaintext content to encrypt
+ * @param signer - EventSigner for encryption
+ * @param override - Optional encryption method override
+ */
+export function setHiddenContent(content, signer, override) {
+    return async (draft) => {
+        if (!signer)
             throw new Error("Signer required for encrypted content");
-        const pubkey = await ctx.signer.getPublicKey();
-        return setEncryptedContent(pubkey, content, override)(draft, ctx);
+        const pubkey = await signer.getPublicKey();
+        return setEncryptedContent(pubkey, content, signer, override)(draft);
     };
 }

package/dist/operations/mailboxes.d.ts

@@ -1,4 +1,4 @@
-import { EventOperation } from "../event-factory/types.js";
+import type { EventOperation } from "../factories/types.js";
 /** Add an outbox relay in NIP-65 mailboxes */
 export declare function addOutboxRelay(url: string | URL): EventOperation;
 /** Remove an outbox relay in NIP-65 mailboxes */
@@ -11,3 +11,7 @@ export declare function removeInboxRelay(url: string | URL): EventOperation;
 export declare function addMailboxRelay(url: string | URL): EventOperation;
 /** Completely removes a mailbox relay from NIP-65 */
 export declare function removeMailboxRelay(url: string | URL): EventOperation;
+/** Sets all inbox relays, replacing existing ones while preserving outbox dimension */
+export declare function setInboxRelays(urls: (string | URL)[]): EventOperation;
+/** Sets all outbox relays, replacing existing ones while preserving inbox dimension */
+export declare function setOutboxRelays(urls: (string | URL)[]): EventOperation;

package/dist/operations/mailboxes.js

@@ -78,3 +78,79 @@ export function addMailboxRelay(url) {
 export function removeMailboxRelay(url) {
     return modifyPublicTags(removeRelayTag(url, "r"));
 }
+/** Sets all inbox relays, replacing existing ones while preserving outbox dimension */
+export function setInboxRelays(urls) {
+    const normalizedUrls = urls.map((url) => normalizeURL(url).toString());
+    return modifyPublicTags((tags) => {
+        // Step 1: Remove all "read" markers from existing relays
+        const withoutInboxes = tags
+            .map((tag) => {
+            if (!isRTag(tag))
+                return tag;
+            // Remove inbox-only relays (read marker)
+            if (tag[2] === "read")
+                return null;
+            // Convert both (no marker) to outbox-only (write marker)
+            if (tag[2] === undefined)
+                return ["r", tag[1], "write"];
+            // Keep outbox-only relays (write marker) as is
+            return tag;
+        })
+            .filter((t) => t !== null);
+        // Step 2: Add "read" markers to the specified URLs
+        const result = [...withoutInboxes];
+        for (const url of normalizedUrls) {
+            const existingIndex = result.findIndex((t) => isRTag(t) && isSameURL(t[1], url));
+            if (existingIndex >= 0) {
+                const existing = result[existingIndex];
+                // Convert outbox-only (write) to both (no marker)
+                if (existing[2] === "write") {
+                    result[existingIndex] = ["r", url];
+                }
+            }
+            else {
+                // Add as inbox-only (read marker)
+                result.push(["r", url, "read"]);
+            }
+        }
+        return result;
+    });
+}
+/** Sets all outbox relays, replacing existing ones while preserving inbox dimension */
+export function setOutboxRelays(urls) {
+    const normalizedUrls = urls.map((url) => normalizeURL(url).toString());
+    return modifyPublicTags((tags) => {
+        // Step 1: Remove all "write" markers from existing relays
+        const withoutOutboxes = tags
+            .map((tag) => {
+            if (!isRTag(tag))
+                return tag;
+            // Remove outbox-only relays (write marker)
+            if (tag[2] === "write")
+                return null;
+            // Convert both (no marker) to inbox-only (read marker)
+            if (tag[2] === undefined)
+                return ["r", tag[1], "read"];
+            // Keep inbox-only relays (read marker) as is
+            return tag;
+        })
+            .filter((t) => t !== null);
+        // Step 2: Add "write" markers to the specified URLs
+        const result = [...withoutOutboxes];
+        for (const url of normalizedUrls) {
+            const existingIndex = result.findIndex((t) => isRTag(t) && isSameURL(t[1], url));
+            if (existingIndex >= 0) {
+                const existing = result[existingIndex];
+                // Convert inbox-only (read) to both (no marker)
+                if (existing[2] === "read") {
+                    result[existingIndex] = ["r", url];
+                }
+            }
+            else {
+                // Add as outbox-only (write marker)
+                result.push(["r", url, "write"]);
+            }
+        }
+        return result;
+    });
+}

package/dist/operations/profile.d.ts

@@ -1,4 +1,4 @@
-import { EventOperation } from "../event-factory/types.js";
+import type { EventOperation } from "../factories/types.js";
 import { ProfileContent } from "../helpers/index.js";
 /** Sets the content of a kind 0 metadata event */
 export declare function setProfile(content: ProfileContent): EventOperation;

package/dist/operations/tag/common.d.ts

@@ -1,16 +1,31 @@
 import { NostrEvent } from "nostr-tools";
-import { TagOperation } from "../../event-factory/types.js";
+import type { TagOperation } from "../../factories/types.js";
 import { AddressPointer, EventPointer, ProfilePointer } from "../../helpers/pointers.js";
-/** Adds a single "p" tag for a ProfilePointer */
-export declare function addProfilePointerTag(pubkey: string | ProfilePointer, replace?: boolean): TagOperation;
+/**
+ * Adds a single "p" tag for a ProfilePointer
+ * @param pubkey - Pubkey string or ProfilePointer object
+ * @param relayHint - Optional relay hint (string) or function to get relay hint
+ * @param replace - If true, removes existing "p" tags for this pubkey
+ */
+export declare function addProfilePointerTag(pubkey: string | ProfilePointer, relayHint?: string | ((pubkey: string) => Promise<string | undefined>), replace?: boolean): TagOperation;
 /** Removes all "p" tags matching a pubkey */
 export declare function removeProfilePointerTag(pubkey: string | ProfilePointer): TagOperation;
-/** Adds a single "e" tag for an EventPointer */
-export declare function addEventPointerTag(id: string | EventPointer | NostrEvent, replace?: boolean): TagOperation;
+/**
+ * Adds a single "e" tag for an EventPointer
+ * @param id - Event ID string, EventPointer object, or NostrEvent
+ * @param relayHint - Optional relay hint (string) or function to get relay hint
+ * @param replace - If true, removes existing "e" tags for this event ID
+ */
+export declare function addEventPointerTag(id: string | EventPointer | NostrEvent, relayHint?: string | ((eventId: string) => Promise<string | undefined>), replace?: boolean): TagOperation;
 /** Removes all "e" tags matching EventPointer or id */
 export declare function removeEventPointerTag(id: string | EventPointer): TagOperation;
-/** Adds a single "a" tag based on an AddressPointer */
-export declare function addAddressPointerTag(address: string | AddressPointer | NostrEvent, replace?: boolean): TagOperation;
+/**
+ * Adds a single "a" tag based on an AddressPointer
+ * @param address - Address string, AddressPointer object, or NostrEvent
+ * @param relayHint - Optional relay hint (string) or function to get relay hint
+ * @param replace - If true, removes existing "a" tags for this address
+ */
+export declare function addAddressPointerTag(address: string | AddressPointer | NostrEvent, relayHint?: string | ((pubkey: string) => Promise<string | undefined>), replace?: boolean): TagOperation;
 /** Removes all "a" tags for address pointer */
 export declare function removeAddressPointerTag(address: string | AddressPointer | NostrEvent): TagOperation;
 /** Adds a name / value tag */

package/dist/operations/tag/common.js

@@ -2,13 +2,18 @@ import { createATagFromAddressPointer, createETagFromEventPointer, createPTagFro
 import { getAddressPointerForEvent, getEventPointerForEvent, getReplaceableAddressFromPointer, parseReplaceableAddress, } from "../../helpers/pointers.js";
 import { ensureNamedValueTag, ensureSingletonTag } from "../../helpers/tags.js";
 import { getReplaceableAddress, isEvent, skip } from "../../helpers/index.js";
-/** Adds a single "p" tag for a ProfilePointer */
-export function addProfilePointerTag(pubkey, replace = true) {
-    return async (tags, { getPubkeyRelayHint }) => {
+/**
+ * Adds a single "p" tag for a ProfilePointer
+ * @param pubkey - Pubkey string or ProfilePointer object
+ * @param relayHint - Optional relay hint (string) or function to get relay hint
+ * @param replace - If true, removes existing "p" tags for this pubkey
+ */
+export function addProfilePointerTag(pubkey, relayHint, replace = true) {
+    return async (tags) => {
         const pointer = typeof pubkey === "string" ? { pubkey: pubkey } : { ...pubkey };
-        // add relay hint
-        if (getPubkeyRelayHint && pointer.relays?.[0] === undefined) {
-            const hint = await getPubkeyRelayHint(pointer.pubkey);
+        // add relay hint (hybrid: string or function)
+        if (!pointer.relays?.[0] && relayHint) {
+            const hint = typeof relayHint === "string" ? relayHint : await relayHint(pointer.pubkey);
             if (hint)
                 pointer.relays = [hint];
         }
@@ -24,13 +29,18 @@ export function removeProfilePointerTag(pubkey) {
     pubkey = typeof pubkey !== "string" ? pubkey.pubkey : pubkey;
     return (tags) => tags.filter((t) => !(t[0] === "p" && t[1] === pubkey));
 }
-/** Adds a single "e" tag for an EventPointer */
-export function addEventPointerTag(id, replace = true) {
-    return async (tags, { getEventRelayHint }) => {
+/**
+ * Adds a single "e" tag for an EventPointer
+ * @param id - Event ID string, EventPointer object, or NostrEvent
+ * @param relayHint - Optional relay hint (string) or function to get relay hint
+ * @param replace - If true, removes existing "e" tags for this event ID
+ */
+export function addEventPointerTag(id, relayHint, replace = true) {
+    return async (tags) => {
         const pointer = typeof id === "string" ? { id } : isEvent(id) ? getEventPointerForEvent(id) : id;
-        // add relay hint
-        if (getEventRelayHint && pointer.relays?.[0] === undefined) {
-            const hint = await getEventRelayHint(pointer.id);
+        // add relay hint (hybrid: string or function)
+        if (!pointer.relays?.[0] && relayHint) {
+            const hint = typeof relayHint === "string" ? relayHint : await relayHint(pointer.id);
             if (hint)
                 pointer.relays = [hint];
         }
@@ -46,8 +56,13 @@ export function removeEventPointerTag(id) {
     id = typeof id === "string" ? id : id.id;
     return (tags) => tags.filter((t) => !(t[0] === "e" && t[1] === id));
 }
-/** Adds a single "a" tag based on an AddressPointer */
-export function addAddressPointerTag(address, replace = true) {
+/**
+ * Adds a single "a" tag based on an AddressPointer
+ * @param address - Address string, AddressPointer object, or NostrEvent
+ * @param relayHint - Optional relay hint (string) or function to get relay hint
+ * @param replace - If true, removes existing "a" tags for this address
+ */
+export function addAddressPointerTag(address, relayHint, replace = true) {
     // convert the string into an address pointer object
     const pointer = typeof address === "string"
         ? parseReplaceableAddress(address)
@@ -56,11 +71,11 @@ export function addAddressPointerTag(address, replace = true) {
             : address;
     if (!pointer)
         throw new Error("Unable to resolve address pointer");
-    return async (tags, { getPubkeyRelayHint }) => {
+    return async (tags) => {
         const replaceableAddress = typeof address === "string" ? address : getReplaceableAddressFromPointer(pointer);
-        // add relay hint if there isn't one
-        if (getPubkeyRelayHint && pointer.relays?.[0] === undefined) {
-            const hint = await getPubkeyRelayHint(pointer.pubkey);
+        // add relay hint if there isn't one (hybrid: string or function)
+        if (!pointer.relays?.[0] && relayHint) {
+            const hint = typeof relayHint === "string" ? relayHint : await relayHint(pointer.pubkey);
             if (hint)
                 pointer.relays = [hint];
         }

package/dist/operations/tag/relay.d.ts

@@ -1,4 +1,4 @@
-import { TagOperation } from "../../event-factory/types.js";
+import type { TagOperation } from "../../factories/types.js";
 /** Adds a relay tag */
 export declare function addRelayTag(url: string | URL, tagName?: string, replace?: boolean): TagOperation;
 /** Removes all relay tags matching the relay */

package/dist/operations/tags.d.ts

@@ -1,4 +1,4 @@
-import { EventOperation, TagOperation } from "../event-factory/types.js";
+import type { EventOperation, TagOperation } from "../factories/types.js";
 import { EventTemplate, NostrEvent, UnsignedEvent } from "../helpers/event.js";
 /** Includes only a single instance of tag in an events public tags */
 export declare function includeSingletonTag(tag: [string, ...string[]], replace?: boolean): EventOperation;
@@ -8,13 +8,19 @@ export declare function includeNameValueTag(tag: [string, string, ...string[]],
 export declare function modifyPublicTags<E extends EventTemplate | UnsignedEvent | NostrEvent>(...operations: (TagOperation | undefined)[]): EventOperation<E, E>;
 /**
  * Creates an event operation that modifies the hidden tags on an event with {@link TagOperation}s
+ * @param signer - EventSigner for encrypting/decrypting hidden tags
+ * @param operations - Tag operations to apply to hidden tags
  * @throws {Error} if no signer is provided
  * @throws {Error} if the event kind does not support hidden tags
  */
-export declare function modifyHiddenTags<E extends EventTemplate | UnsignedEvent | NostrEvent>(...operations: (TagOperation | undefined)[]): EventOperation<E, E>;
+export declare function modifyHiddenTags<E extends EventTemplate | UnsignedEvent | NostrEvent>(signer: import("../factories/types.js").EventSigner | undefined, ...operations: (TagOperation | undefined)[]): EventOperation<E, E>;
 export type ModifyTagsOptions = TagOperation | TagOperation[] | {
     public?: TagOperation | TagOperation[];
     hidden?: TagOperation | TagOperation[];
 };
-/** A flexible method for creating an event operation that modifies the tags */
-export declare function modifyTags(tagOperations?: ModifyTagsOptions): EventOperation;
+/**
+ * A flexible method for creating an event operation that modifies the tags
+ * @param tagOperations - Tag operations for public and/or hidden tags
+ * @param signer - Optional signer (required if modifying hidden tags)
+ */
+export declare function modifyTags(tagOperations?: ModifyTagsOptions, signer?: import("../factories/types.js").EventSigner): EventOperation;