applesauce-common 0.0.0-next-20251203172109

package/dist/helpers/emoji.js

@@ -0,0 +1,34 @@
+import { getTagValue } from "applesauce-core/helpers/event";
+/** Gets an "emoji" tag that matches an emoji code */
+export function getEmojiTag(tags, code) {
+    code = code.replace(/^:|:$/g, "").toLowerCase();
+    return (Array.isArray(tags) ? tags : tags.tags).find((t) => t[0] === "emoji" && t.length >= 3 && t[1].toLowerCase() === code);
+}
+/** Gets an emoji for a shortcode from an array of tags or event */
+export function getEmojiFromTags(event, code) {
+    const tag = getEmojiTag(event, code);
+    if (!tag)
+        return undefined;
+    return {
+        shortcode: tag[1],
+        url: tag[2],
+    };
+}
+/** Returns the name of a NIP-30 emoji pack */
+export function getPackName(pack) {
+    return getTagValue(pack, "title") || getTagValue(pack, "d");
+}
+/** Returns an array of emojis from a NIP-30 emoji pack */
+export function getEmojis(pack) {
+    return pack.tags
+        .filter((t) => t[0] === "emoji" && t[1] && t[2])
+        .map((t) => ({ shortcode: t[1], url: t[2] }));
+}
+/** Returns the custom emoji for a reaction event */
+export function getReactionEmoji(event) {
+    // Trim and strip colons
+    const shortcode = /^:+(.+?):+$/g.exec(event.content.trim().toLowerCase())?.[1];
+    if (!shortcode)
+        return undefined;
+    return getEmojiFromTags(event, shortcode);
+}

package/dist/helpers/encrypted-content-cache.d.ts

@@ -0,0 +1,22 @@
+import { IEventStoreStreams } from "applesauce-core/event-store";
+import { NostrEvent } from "applesauce-core/helpers/event";
+import { Observable } from "rxjs";
+/** A symbol that is used to mark encrypted content as being from a cache */
+export declare const EncryptedContentFromCacheSymbol: unique symbol;
+/** An interface that is used to cache encrypted content on events */
+export interface EncryptedContentCache {
+    getItem: (key: string) => Promise<string | null>;
+    setItem: (key: string, value: string) => Promise<any>;
+}
+/** Marks the encrypted content as being from a cache */
+export declare function markEncryptedContentFromCache<T extends object>(event: T): void;
+/** Checks if the encrypted content is from a cache */
+export declare function isEncryptedContentFromCache<T extends object>(event: T): boolean;
+/**
+ * Starts a process that persists and restores all encrypted content
+ * @param eventStore - The event store to listen to
+ * @param storage - The storage to use
+ * @param fallback - A function that will be called when the encrypted content is not found in storage
+ * @returns A function that can be used to stop the process
+ */
+export declare function persistEncryptedContent(eventStore: IEventStoreStreams, storage: EncryptedContentCache | Observable<EncryptedContentCache>, fallback?: (event: NostrEvent) => any | Promise<any>): () => void;

package/dist/helpers/encrypted-content-cache.js

@@ -0,0 +1,138 @@
+import { logger } from "applesauce-core";
+import { canHaveEncryptedContent, getEncryptedContent, isEncryptedContentUnlocked, setEncryptedContentCache, } from "applesauce-core/helpers/encrypted-content";
+import { kinds, notifyEventUpdate } from "applesauce-core/helpers/event";
+import { catchError, combineLatest, distinct, EMPTY, filter, isObservable, map, merge, mergeMap, of, switchMap, } from "rxjs";
+import { getGiftWrapSeal, getSealGiftWrap, getSealRumor } from "./gift-wrap.js";
+/** A symbol that is used to mark encrypted content as being from a cache */
+export const EncryptedContentFromCacheSymbol = Symbol.for("encrypted-content-from-cache");
+/** Marks the encrypted content as being from a cache */
+export function markEncryptedContentFromCache(event) {
+    Reflect.set(event, EncryptedContentFromCacheSymbol, true);
+}
+/** Checks if the encrypted content is from a cache */
+export function isEncryptedContentFromCache(event) {
+    return Reflect.has(event, EncryptedContentFromCacheSymbol);
+}
+const log = logger.extend("EncryptedContentCache");
+/**
+ * Starts a process that persists and restores all encrypted content
+ * @param eventStore - The event store to listen to
+ * @param storage - The storage to use
+ * @param fallback - A function that will be called when the encrypted content is not found in storage
+ * @returns A function that can be used to stop the process
+ */
+export function persistEncryptedContent(eventStore, storage, fallback) {
+    const storage$ = isObservable(storage) ? storage : of(storage);
+    // Get the encrypted content from storage or call the fallback
+    const getItem = async (storage, event) => {
+        return (await storage.getItem(event.id)) || (fallback ? await fallback(event) : null);
+    };
+    // Restore encrypted content when it is inserted
+    const restore = eventStore.insert$
+        .pipe(
+    // Look for events that support encrypted content and are locked
+    filter((e) => canHaveEncryptedContent(e.kind) && isEncryptedContentUnlocked(e) === false), 
+    // Get the encrypted content from storage
+    mergeMap((event) => 
+    // Wait for storage to be available
+    storage$.pipe(switchMap((storage) => combineLatest([of(event), getItem(storage, event)])), catchError((error) => {
+        log(`Failed to restore encrypted content for ${event.id}`, error);
+        return EMPTY;
+    }))))
+        .subscribe(async ([event, content]) => {
+        if (!content)
+            return;
+        // Restore the encrypted content and set it as from a cache
+        markEncryptedContentFromCache(event);
+        setEncryptedContentCache(event, content);
+        log(`Restored encrypted content for ${event.id}`);
+    });
+    // Restore seals when they are unlocked
+    const restoreSeals = eventStore.update$
+        .pipe(
+    // Look for gift wraps that are unlocked
+    filter((e) => e.kind === kinds.GiftWrap && isEncryptedContentUnlocked(e)), 
+    // Get the seal event
+    map((gift) => getGiftWrapSeal(gift)), 
+    // Look for gift wraps with locked seals
+    filter((seal) => seal !== undefined && isEncryptedContentUnlocked(seal) === false), 
+    // Only attempt to unlock seals once
+    distinct((seal) => seal.id), 
+    // Get encrypted content from storage
+    mergeMap((seal) => 
+    // Wait for storage to be available
+    storage$.pipe(switchMap((storage) => combineLatest([of(seal), getItem(storage, seal)])), catchError((error) => {
+        log(`Failed to restore encrypted content for ${seal.id}`, error);
+        return EMPTY;
+    }))))
+        .subscribe(async ([seal, content]) => {
+        if (!seal || !content)
+            return;
+        markEncryptedContentFromCache(seal);
+        setEncryptedContentCache(seal, content);
+        // Parse the rumor event
+        getSealRumor(seal);
+        // Trigger an update to the gift wrap event
+        const gift = getSealGiftWrap(seal);
+        if (gift)
+            notifyEventUpdate(gift);
+        log(`Restored encrypted content for ${seal.id}`);
+    });
+    // Persist encrypted content when it is updated or inserted
+    const persist = combineLatest([merge(eventStore.update$, eventStore.insert$), storage$])
+        .pipe(
+    // Look for events that support encrypted content and are unlocked and not from the cache
+    filter(([event]) => canHaveEncryptedContent(event.kind) &&
+        isEncryptedContentUnlocked(event) &&
+        !isEncryptedContentFromCache(event)), 
+    // Only persist the encrypted content once
+    distinct(([event]) => event.id))
+        .subscribe(async ([event, storage]) => {
+        try {
+            const content = getEncryptedContent(event);
+            if (content) {
+                await storage.setItem(event.id, content);
+                log(`Persisted encrypted content for ${event.id}`);
+            }
+        }
+        catch (error) {
+            // Ignore errors when saving encrypted content
+            log(`Failed to persist encrypted content for ${event.id}`, error);
+        }
+    });
+    // Persist seals when the gift warp is unlocked or inserted unlocked
+    // This relies on the gift wrap event being updated when a seal is unlocked
+    const persistSeals = combineLatest([merge(eventStore.update$, eventStore.insert$), storage$])
+        .pipe(
+    // Look for gift wraps that are unlocked
+    filter(([event]) => event.kind === kinds.GiftWrap && isEncryptedContentUnlocked(event)), 
+    // Get the seal event
+    map(([gift, storage]) => [getGiftWrapSeal(gift), storage]), 
+    // Make sure the seal is defined
+    filter(([seal]) => seal !== undefined), 
+    // Make sure seal is unlocked and not from cache
+    filter(([seal]) => isEncryptedContentUnlocked(seal) && !isEncryptedContentFromCache(seal)), 
+    // Only persist the seal once
+    distinct(([seal]) => seal.id))
+        .subscribe(async ([seal, storage]) => {
+        if (!seal)
+            return;
+        try {
+            const content = getEncryptedContent(seal);
+            if (content) {
+                await storage.setItem(seal.id, content);
+                log(`Persisted encrypted content for ${seal.id}`);
+            }
+        }
+        catch (error) {
+            // Ignore errors when saving encrypted content
+            log(`Failed to persist encrypted content for ${seal.id}`, error);
+        }
+    });
+    return () => {
+        restore.unsubscribe();
+        persist.unsubscribe();
+        restoreSeals.unsubscribe();
+        persistSeals.unsubscribe();
+    };
+}

package/dist/helpers/file-metadata.d.ts

@@ -0,0 +1,55 @@
+import { NostrEvent } from "applesauce-core/helpers/event";
+import { NameValueTag } from "applesauce-core/helpers";
+export type FileMetadata = {
+    /** URL of the file */
+    url?: string;
+    /** MIME type */
+    type?: string;
+    /** sha256 hash of the file */
+    sha256?: string;
+    /**
+     * The original sha256 hash before the file was transformed
+     * @deprecated
+     */
+    originalSha256?: string;
+    /** size of the file in bytes */
+    size?: number;
+    /** size of file in pixels in the form <width>x<height> */
+    dimensions?: string;
+    /** magnet */
+    magnet?: string;
+    /** torrent infohash */
+    infohash?: string;
+    /** URL to a thumbnail */
+    thumbnail?: string;
+    /** URL to a preview image with the same dimensions */
+    image?: string;
+    /** summary */
+    summary?: string;
+    /** description for accessability */
+    alt?: string;
+    /** blurhash */
+    blurhash?: string;
+    /** fallback URLs */
+    fallback?: string[];
+};
+/** Alias for {@link FileMetadata} */
+export type MediaAttachment = FileMetadata;
+/**
+ * Parses file metadata tags into {@link FileMetadata}
+ * @throws
+ */
+export declare function parseFileMetadataTags(tags: string[][]): FileMetadata;
+/** Parses a imeta tag into a {@link FileMetadata} */
+export declare function getFileMetadataFromImetaTag(tag: string[]): FileMetadata;
+export declare const MediaAttachmentsSymbol: unique symbol;
+/** Gets all the media attachments on an event */
+export declare function getMediaAttachments(event: NostrEvent): FileMetadata[];
+/** Gets {@link FileMetadata} for a NIP-94 kind 1063 event */
+export declare function getFileMetadata(file: NostrEvent): FileMetadata;
+/** Returns the last 64 length hex string in a URL */
+export declare function getSha256FromURL(url: string | URL): string | undefined;
+/** Creates tags for {@link FileMetadata} */
+export declare function createFileMetadataTags(attachment: FileMetadata): NameValueTag[];
+/** Creates an imeta tag for a media attachment */
+export declare function createImetaTagForAttachment(attachment: FileMetadata): string[];

package/dist/helpers/file-metadata.js

@@ -0,0 +1,130 @@
+import { getOrComputeCachedValue } from "applesauce-core/helpers/cache";
+/**
+ * Parses file metadata tags into {@link FileMetadata}
+ * @throws
+ */
+export function parseFileMetadataTags(tags) {
+    const fields = {};
+    let fallback = undefined;
+    for (const [name, value] of tags) {
+        switch (name) {
+            case "fallback":
+                fallback = fallback ? [...fallback, value] : [value];
+                break;
+            default:
+                fields[name] = value;
+                break;
+        }
+    }
+    const metadata = { url: fields.url, fallback };
+    // parse size
+    if (fields.size)
+        metadata.size = parseInt(fields.size);
+    // copy optional fields
+    if (fields.m)
+        metadata.type = fields.m;
+    if (fields.x)
+        metadata.sha256 = fields.x;
+    if (fields.ox)
+        metadata.originalSha256 = fields.ox;
+    if (fields.dim)
+        metadata.dimensions = fields.dim;
+    if (fields.magnet)
+        metadata.magnet = fields.magnet;
+    if (fields.i)
+        metadata.infohash = fields.i;
+    if (fields.thumb)
+        metadata.thumbnail = fields.thumb;
+    if (fields.image)
+        metadata.image = fields.image;
+    if (fields.summary)
+        metadata.summary = fields.summary;
+    if (fields.alt)
+        metadata.alt = fields.alt;
+    if (fields.blurhash)
+        metadata.blurhash = fields.blurhash;
+    return metadata;
+}
+/** Parses a imeta tag into a {@link FileMetadata} */
+export function getFileMetadataFromImetaTag(tag) {
+    const parts = tag.slice(1);
+    const tags = [];
+    for (const part of parts) {
+        const match = part.match(/^(.+?)\s(.+)$/);
+        if (match) {
+            const [_, name, value] = match;
+            tags.push([name, value]);
+        }
+    }
+    return parseFileMetadataTags(tags);
+}
+export const MediaAttachmentsSymbol = Symbol.for("media-attachments");
+/** Gets all the media attachments on an event */
+export function getMediaAttachments(event) {
+    return getOrComputeCachedValue(event, MediaAttachmentsSymbol, () => {
+        return event.tags
+            .filter((t) => t[0] === "imeta")
+            .map((tag) => {
+            try {
+                return getFileMetadataFromImetaTag(tag);
+            }
+            catch (error) {
+                // ignore invalid attachments
+                return undefined;
+            }
+        })
+            .filter((a) => !!a);
+    });
+}
+/** Gets {@link FileMetadata} for a NIP-94 kind 1063 event */
+export function getFileMetadata(file) {
+    return parseFileMetadataTags(file.tags);
+}
+/** Returns the last 64 length hex string in a URL */
+export function getSha256FromURL(url) {
+    if (typeof url === "string")
+        url = new URL(url);
+    const hashes = Array.from(url.pathname.matchAll(/[0-9a-f]{64}/gi));
+    if (hashes.length > 0)
+        return hashes[hashes.length - 1][0];
+    return;
+}
+/** Creates tags for {@link FileMetadata} */
+export function createFileMetadataTags(attachment) {
+    const tags = [];
+    const add = (name, value) => tags.push([name, String(value)]);
+    if (attachment.url)
+        add("url", attachment.url);
+    if (attachment.type)
+        add("m", attachment.type);
+    if (attachment.sha256)
+        add("x", attachment.sha256);
+    if (attachment.originalSha256)
+        add("ox", attachment.originalSha256);
+    if (attachment.size !== undefined)
+        add("size", attachment.size);
+    if (attachment.dimensions)
+        add("dim", attachment.dimensions);
+    if (attachment.magnet)
+        add("magnet", attachment.magnet);
+    if (attachment.infohash)
+        add("i", attachment.infohash);
+    if (attachment.blurhash)
+        add("blurhash", attachment.blurhash);
+    if (attachment.thumbnail)
+        add("thumb", attachment.thumbnail);
+    if (attachment.image)
+        add("image", attachment.image);
+    if (attachment.summary)
+        add("summary", attachment.summary);
+    if (attachment.alt)
+        add("alt", attachment.alt);
+    if (attachment.fallback && attachment.fallback?.length > 0)
+        for (const url of attachment.fallback)
+            add("fallback", url);
+    return tags;
+}
+/** Creates an imeta tag for a media attachment */
+export function createImetaTagForAttachment(attachment) {
+    return ["imeta", ...createFileMetadataTags(attachment).map((t) => t.join(" "))];
+}

package/dist/helpers/gift-wrap.d.ts

@@ -0,0 +1,66 @@
+import { EventMemory } from "applesauce-core/event-store";
+import { EncryptedContentSigner } from "applesauce-core/helpers/encrypted-content";
+import { kinds, KnownEvent, NostrEvent, UnsignedEvent } from "applesauce-core/helpers/event";
+/**
+ * An internal event set to keep track of seals and rumors
+ * This is intentionally isolated from the main applications event store so to prevent seals and rumors from being leaked
+ */
+export declare const internalGiftWrapEvents: EventMemory;
+export type Rumor = UnsignedEvent & {
+    id: string;
+};
+/** Used to store a reference to the seal event on gift wraps (downstream) or the seal event on rumors (upstream[]) */
+export declare const SealSymbol: unique symbol;
+/** Used to store a reference to the rumor on seals (downstream) */
+export declare const RumorSymbol: unique symbol;
+/** Used to store a reference to the parent gift wrap event on seals (upstream) */
+export declare const GiftWrapSymbol: unique symbol;
+/** A gift wrap event that knows its seal event */
+export type UnlockedGiftWrapEvent = KnownEvent<kinds.GiftWrap> & {
+    /** Downstream seal event */
+    [SealSymbol]: UnlockedSeal;
+};
+/** A seal that knows its parent gift wrap event */
+export type UnlockedSeal = KnownEvent<kinds.Seal> & {
+    /** Upstream gift wrap event */
+    [SealSymbol]: UnlockedGiftWrapEvent;
+    /** Downstream rumor event */
+    [RumorSymbol]: Rumor;
+};
+/** Checks if an event is a rumor (normal event with "id" and no "sig") */
+export declare function isRumor(event: any): event is Rumor;
+/** Returns all the parent gift wraps for a seal event */
+export declare function getSealGiftWrap(seal: UnlockedSeal): UnlockedGiftWrapEvent;
+export declare function getSealGiftWrap(seal: NostrEvent): UnlockedGiftWrapEvent | undefined;
+/** Returns all the parent seals for a rumor event */
+export declare function getRumorSeals(rumor: Rumor): UnlockedSeal[];
+/** Returns all the parent gift wraps for a rumor event */
+export declare function getRumorGiftWraps(rumor: Rumor): UnlockedGiftWrapEvent[];
+/** Checks if a seal event is locked and casts it to the {@link UnlockedSeal} type */
+export declare function isSealUnlocked(seal: NostrEvent): seal is UnlockedSeal;
+/** Returns if a gift-wrap event or gift-wrap seal is locked */
+export declare function isGiftWrapUnlocked(gift: NostrEvent): gift is UnlockedGiftWrapEvent;
+/**
+ * Gets the rumor from a seal event
+ * @throws {Error} If the author of the rumor event does not match the author of the seal
+ */
+export declare function getSealRumor(seal: UnlockedSeal): Rumor;
+export declare function getSealRumor(seal: NostrEvent): Rumor | undefined;
+/** Returns the seal event in a gift-wrap -> seal (downstream) */
+export declare function getGiftWrapSeal(gift: UnlockedGiftWrapEvent): UnlockedSeal;
+export declare function getGiftWrapSeal(gift: NostrEvent): NostrEvent | undefined;
+/** Returns the unsigned rumor in the gift-wrap -> seal -> rumor (downstream) */
+export declare function getGiftWrapRumor(gift: UnlockedGiftWrapEvent): Rumor;
+export declare function getGiftWrapRumor(gift: NostrEvent): Rumor | undefined;
+/**
+ * Unlocks a seal event and returns the rumor event
+ * @throws {Error} If the author of the rumor event does not match the author of the seal
+ */
+export declare function unlockSeal(seal: NostrEvent, signer: EncryptedContentSigner): Promise<Rumor>;
+/**
+ * Unlocks and returns the unsigned seal event in a gift-wrap
+ * @throws {Error} If the author of the rumor event does not match the author of the seal
+ */
+export declare function unlockGiftWrap(gift: NostrEvent, signer: EncryptedContentSigner): Promise<Rumor>;
+/** Locks a gift-wrap event and seals its seal event */
+export declare function lockGiftWrap(gift: NostrEvent): void;

package/dist/helpers/gift-wrap.js

@@ -0,0 +1,204 @@
+import { EventMemory } from "applesauce-core/event-store";
+import { getEncryptedContent, isEncryptedContentUnlocked, lockEncryptedContent, unlockEncryptedContent, } from "applesauce-core/helpers/encrypted-content";
+import { kinds, notifyEventUpdate, verifyWrappedEvent, } from "applesauce-core/helpers/event";
+/**
+ * An internal event set to keep track of seals and rumors
+ * This is intentionally isolated from the main applications event store so to prevent seals and rumors from being leaked
+ */
+export const internalGiftWrapEvents = new EventMemory();
+/** Used to store a reference to the seal event on gift wraps (downstream) or the seal event on rumors (upstream[]) */
+export const SealSymbol = Symbol.for("seal");
+/** Used to store a reference to the rumor on seals (downstream) */
+export const RumorSymbol = Symbol.for("rumor");
+/** Used to store a reference to the parent gift wrap event on seals (upstream) */
+export const GiftWrapSymbol = Symbol.for("gift-wrap");
+/** Adds a parent reference to a seal or rumor */
+function addParentSealReference(rumor, seal) {
+    const parents = Reflect.get(rumor, SealSymbol);
+    if (!parents)
+        Reflect.set(rumor, SealSymbol, new Set([seal]));
+    else
+        parents.add(seal);
+}
+/** Removes a parent reference from a seal or rumor */
+function removeParentSealReference(rumor, seal) {
+    const parents = Reflect.get(rumor, SealSymbol);
+    if (parents)
+        parents.delete(seal);
+}
+/** Checks if an event is a rumor (normal event with "id" and no "sig") */
+export function isRumor(event) {
+    if (event === undefined || event === null)
+        return false;
+    return (event.id?.length === 64 &&
+        !("sig" in event) &&
+        typeof event.pubkey === "string" &&
+        event.pubkey.length === 64 &&
+        typeof event.content === "string" &&
+        Array.isArray(event.tags) &&
+        typeof event.created_at === "number" &&
+        event.created_at > 0);
+}
+export function getSealGiftWrap(seal) {
+    return Reflect.get(seal, GiftWrapSymbol);
+}
+/** Returns all the parent seals for a rumor event */
+export function getRumorSeals(rumor) {
+    let set = Reflect.get(rumor, SealSymbol);
+    if (!set) {
+        set = new Set();
+        Reflect.set(rumor, SealSymbol, set);
+    }
+    return Array.from(set);
+}
+/** Returns all the parent gift wraps for a rumor event */
+export function getRumorGiftWraps(rumor) {
+    const giftWraps = new Set();
+    const seals = getRumorSeals(rumor);
+    for (const seal of seals) {
+        const upstream = getSealGiftWrap(seal);
+        if (upstream)
+            giftWraps.add(upstream);
+    }
+    return Array.from(giftWraps);
+}
+/** Checks if a seal event is locked and casts it to the {@link UnlockedSeal} type */
+export function isSealUnlocked(seal) {
+    return isEncryptedContentUnlocked(seal) === true && Reflect.has(seal, RumorSymbol) === true;
+}
+/** Returns if a gift-wrap event or gift-wrap seal is locked */
+export function isGiftWrapUnlocked(gift) {
+    if (isEncryptedContentUnlocked(gift) === false)
+        return false;
+    // Get the seal event
+    const seal = getGiftWrapSeal(gift);
+    if (!seal)
+        return false;
+    // If seal is locked, return false
+    if (!isSealUnlocked(seal))
+        return false;
+    return true;
+}
+export function getSealRumor(seal) {
+    // Non seal events cant have rumors
+    if (seal.kind !== kinds.Seal)
+        return undefined;
+    // If unlocked return the rumor
+    if (isSealUnlocked(seal))
+        return seal[RumorSymbol];
+    // Get the encrypted content plaintext
+    const content = getEncryptedContent(seal);
+    // Return undefined if the content is not found
+    if (!content)
+        return undefined;
+    // Parse the content as a rumor event
+    let rumor = JSON.parse(content);
+    // Check if the rumor event already exists in the internal event set
+    const existing = internalGiftWrapEvents.getEvent(rumor.id);
+    if (existing)
+        // Reuse the existing rumor instance
+        rumor = existing;
+    else
+        // Add to the internal event set
+        internalGiftWrapEvents.add(rumor);
+    // Throw an error if the seal and rumor authors do not match
+    if (rumor.pubkey !== seal.pubkey)
+        throw new Error("Seal author does not match rumor author");
+    // Save a reference to the parent seal event
+    addParentSealReference(rumor, seal);
+    // Cache the rumor event
+    Reflect.set(seal, RumorSymbol, rumor);
+    return rumor;
+}
+export function getGiftWrapSeal(gift) {
+    // Returned cached seal if it exists (downstream)
+    if (Reflect.has(gift, SealSymbol))
+        return Reflect.get(gift, SealSymbol);
+    // Get the encrypted content
+    const content = getEncryptedContent(gift);
+    // Return undefined if the content is not found
+    if (!content)
+        return undefined;
+    // Parse seal as nostr event
+    let seal = JSON.parse(content);
+    // Check if the seal event already exists in the internal event set
+    const existing = internalGiftWrapEvents.getEvent(seal.id);
+    if (existing) {
+        // Reuse the existing seal instance
+        seal = existing;
+    }
+    else {
+        // Verify the seal event
+        verifyWrappedEvent(seal);
+        // Add to the internal event set
+        internalGiftWrapEvents.add(seal);
+        // Set the reference to the parent gift wrap event (upstream)
+        Reflect.set(seal, GiftWrapSymbol, gift);
+    }
+    // Save a reference to the seal on the gift wrap (downstream)
+    Reflect.set(gift, SealSymbol, seal);
+    return seal;
+}
+export function getGiftWrapRumor(gift) {
+    const seal = getGiftWrapSeal(gift);
+    if (!seal)
+        return undefined;
+    return getSealRumor(seal);
+}
+/**
+ * Unlocks a seal event and returns the rumor event
+ * @throws {Error} If the author of the rumor event does not match the author of the seal
+ */
+export async function unlockSeal(seal, signer) {
+    // If already unlocked, return the rumor
+    if (isSealUnlocked(seal))
+        return seal[RumorSymbol];
+    // unlock encrypted content as needed
+    await unlockEncryptedContent(seal, seal.pubkey, signer);
+    const rumor = getSealRumor(seal);
+    if (!rumor)
+        throw new Error("Failed to read rumor in gift wrap");
+    // Notify event store
+    notifyEventUpdate(seal);
+    return rumor;
+}
+/**
+ * Unlocks and returns the unsigned seal event in a gift-wrap
+ * @throws {Error} If the author of the rumor event does not match the author of the seal
+ */
+export async function unlockGiftWrap(gift, signer) {
+    // If already unlocked, return the rumor
+    if (isGiftWrapUnlocked(gift))
+        return getGiftWrapRumor(gift);
+    // Unlock the encrypted content
+    await unlockEncryptedContent(gift, gift.pubkey, signer);
+    // Parse seal as nostr event
+    let seal = getGiftWrapSeal(gift);
+    if (!seal)
+        throw new Error("Failed to read seal in gift wrap");
+    // Unlock the seal event
+    const rumor = await unlockSeal(seal, signer);
+    // if the event has been added to an event store, notify it
+    notifyEventUpdate(gift);
+    return rumor;
+}
+/** Locks a gift-wrap event and seals its seal event */
+export function lockGiftWrap(gift) {
+    const seal = getGiftWrapSeal(gift);
+    if (seal) {
+        const rumor = getSealRumor(seal);
+        // Remove the rumors parent seal reference (upstream)
+        if (rumor)
+            removeParentSealReference(rumor, seal);
+        // Remove the seal's parent gift wrap reference (upstream)
+        Reflect.deleteProperty(seal, GiftWrapSymbol);
+        // Remove the seal's rumor reference (downstream)
+        Reflect.deleteProperty(seal, RumorSymbol);
+        // Lock the seal's encrypted content
+        lockEncryptedContent(seal);
+    }
+    // Remove the gift wrap's seal reference (downstream)
+    Reflect.deleteProperty(gift, SealSymbol);
+    // Lock the gift wrap's encrypted content
+    lockEncryptedContent(gift);
+}

package/dist/helpers/groups-helper.d.ts

@@ -0,0 +1,6 @@
+import { NameValueTag } from "applesauce-core/helpers";
+import { GroupPointer } from "./groups.js";
+/** Creates a "h" tag for chat messages from a {@link GroupPointer} */
+export declare function createGroupHTagFromGroupPointer(group: GroupPointer): NameValueTag;
+/** Creates a "group" tag from a {@link GroupPointer} */
+export declare function createGroupTagFromGroupPointer(group: GroupPointer): NameValueTag;

package/dist/helpers/groups-helper.js

@@ -0,0 +1,9 @@
+import { ensureWebSocketURL, fillAndTrimTag } from "applesauce-core/helpers";
+/** Creates a "h" tag for chat messages from a {@link GroupPointer} */
+export function createGroupHTagFromGroupPointer(group) {
+    return fillAndTrimTag(["h", group.id, ensureWebSocketURL(group.relay)]);
+}
+/** Creates a "group" tag from a {@link GroupPointer} */
+export function createGroupTagFromGroupPointer(group) {
+    return fillAndTrimTag(["group", group.id, ensureWebSocketURL(group.relay), group.name], 3);
+}