Marmot-TS
    Preparing search index...

    InviteManager orchestrates the lifecycle of reading Welcome invites.

    It takes gift-wrapped events from the app, handles decryption/parsing, persists invites to storage, and provides interfaces for consumption.

    The app is responsible for:

    • Syncing events from relays
    • Passing gift wrap events (kind 1059) to ingestEvent()
    • Calling decryptGiftWraps() to decrypt (triggers nip-44 decryption prompts)
    • Reading unread invites via getUnread(), watchUnread(), or event listeners
    • Marking invites as read after processing

    State lifecycle:

    1. RECEIVED: Gift wrap ingested, stored, awaiting decryption
    2. UNREAD: Decrypted and parsed, ready for app consumption
    3. SEEN: Event ID tracked to prevent re-processing
    4. (DELETED): Read invites are removed from storage

    Store layout:

    • __seen key holds a serialized set of all seen event IDs
    • received:<eventId> keys hold gift wraps and optional retry/transition state
    • unread:<rumorId> keys hold decrypted welcome rumors

    Hierarchy

    Index
    • Clear all stored invites (received and unread).

      Note: This does NOT clear the seen index to maintain deduplication history. If you need to clear seen events, use clearSeen() or create a fresh store.

      Returns Promise<void>

    • Clear the seen event IDs. Warning: This will allow previously processed events to be re-ingested.

      Returns Promise<void>

    • Process a single received (undecrypted) gift wrap by event ID.

      Attempts to decrypt and parse the specified event.

      • On success: journals the validated rumor, persists unread, then retires received.
      • Signer/cancellation/storage failures emit 'error' and retain the source.
      • Invalid decrypted payloads are retired (or quarantined until cleanup succeeds).

      This is an explicit retry, which may prompt the signer again. A journaled rumor is resumed without prompting or emitting a duplicate 'decrypted' event.

      Parameters

      • eventId: string | ReceivedGiftWrap

        The gift wrap event ID to decrypt, or the gift wrap event itself

      Returns Promise<UnreadInvite | null>

      A newly persisted unread rumor, or null on failure/already delivered

      Error if an event ID is not found in received storage

    • Decrypts all received gift wraps.

      Attempts to decrypt and parse each received gift wrap.

      • On success: moves to 'unread' state and emits 'decrypted'.
      • On retryable failure: emits 'error' and retains received for explicit retry.

      This method prompts the user via signer for each decryption, so it should be called deliberately by the app (not automatically).

      Returns Promise<UnreadInvite[]>

      Array of successfully decrypted welcome rumors

    • Ingest a gift wrap event (kind 1059).

      The event is checked against the seen index for deduplication. If new, it's stored in the 'received' state awaiting decryption.

      Parameters

      Returns Promise<boolean>

      true if event was new and stored, false if already seen

      Error if event is not kind 1059

    • Ingest multiple gift wrap events in batch.

      Parameters

      Returns Promise<number>

      Count of new events stored

    • Subscribes for gift-wrapped invites (kind 1059) addressed to this account on the given relays — the inbound counterpart the app would otherwise hand-wire. Each new gift wrap is ingested (de-duplicated) and then decrypted, so watchUnread / the decrypted event update on their own. Previously unattempted gift wraps are tried once on start. Failed/interrupted attempts require an explicit decrypt call, even after reconnect or restart; journaled transitions resume without prompting. Call .unsubscribe() on the result to stop listening.

      relays should be the account's advertised kind-10050 inbox relays — where inviters deliver Welcomes. Subscribing elsewhere silently misses invites.

      Parameters

      • relays: string[]

      Returns Promise<Unsubscribable>

    • Mark an invite as read and remove it from storage.

      Emits 'inviteRead' event after removal.

      Parameters

      • inviteId: string

        The rumor ID (from the welcome rumor)

      Returns Promise<void>

    • Watch for received (encrypted) invites.

      Yields the current list of received gift wraps, then yields again whenever the received list changes (via 'received' or 'processed' events).

      Pass an AbortSignal to stop watching. Abort, return, throw, and async disposal release listeners and interrupt pending reads without another event. Abandoned reads may finish internally; their results are ignored.

      Parameters

      • options: { signal?: AbortSignal } = {}

      Returns AsyncGenerator<ReceivedGiftWrap[]>

    • Watch for unread invites.

      Yields the current array of unread invites, then yields again whenever the unread list changes or a recovery confirms persisted unread.

      This does NOT automatically mark invites as read - the app must call markAsRead() after processing each invite.

      Pass an AbortSignal to stop watching. Abort, return, throw, and async disposal release listeners and interrupt pending reads without another event. Abandoned reads may finish internally; their results are ignored.

      Parameters

      • options: { signal?: AbortSignal } = {}

      Returns AsyncGenerator<UnreadInvite[]>

    prefixed: string | boolean
    • Type Parameters

      Parameters

      Returns this

    • Return an array listing the events for which the emitter has registered listeners.

      Returns (keyof InviteManagerEvents)[]

    • Return the number of listeners listening to a given event.

      Parameters

      Returns number

    • Return the listeners registered for a given event.

      Type Parameters

      Parameters

      • event: T

      Returns (
          (
              ...args: ArgumentMap<InviteManagerEvents>[Extract<
                  T,
                  keyof InviteManagerEvents,
              >],
          ) => void
      )[]

    • Type Parameters

      Parameters

      • event: T
      • Optionalfn: (
            ...args: ArgumentMap<InviteManagerEvents>[Extract<
                T,
                keyof InviteManagerEvents,
            >],
        ) => void
      • Optionalcontext: any
      • Optionalonce: boolean

      Returns this

    • Add a listener for a given event.

      Type Parameters

      Parameters

      Returns this

    • Add a one-time listener for a given event.

      Type Parameters

      Parameters

      Returns this

    • Remove all listeners, or those of the specified event.

      Parameters

      • Optionalevent: keyof InviteManagerEvents

      Returns this

    • Remove the listeners of a given event.

      Type Parameters

      Parameters

      • event: T
      • Optionalfn: (
            ...args: ArgumentMap<InviteManagerEvents>[Extract<
                T,
                keyof InviteManagerEvents,
            >],
        ) => void
      • Optionalcontext: any
      • Optionalonce: boolean

      Returns this