Marmot-TS
    Preparing search index...

    Class GroupsManager<THistory, TMedia>

    Orchestrates the lifecycle of MarmotGroup instances. Delegates in-memory caching and store hydration to an internal GroupRegistry and group construction to an internal GroupFactory, layering the public lifecycle events (created/imported/joined/destroyed/left) and the send/ingest facade on top.

    Type Parameters

    Hierarchy

    Index
    cryptoProvider: CryptoProvider

    Crypto provider for cryptographic operations

    ingestPersistence: IngestPersistenceCapability

    The nostr relay pool to use for the client

    signer: EventSigner

    The signer used for the clients identity

    The backend storing serialized group state bytes

    • Persists and caches a group built from a ClientState, emitting the given lifecycle event. Used by higher-level flows (e.g. joining from a welcome message) that construct ClientStates themselves.

      Parameters

      • state: ClientState

        The ClientState to adopt

      • Optionaloptions: { beforeAdopt?: () => Promise<void>; emit?: "imported" | "joined" }
        • OptionalbeforeAdopt?: () => Promise<void>

          Runs after duplicate rejection while adoption for this group is serialized.

        • Optionalemit?: "imported" | "joined"

          Which lifecycle event to emit. Defaults to "imported".

      Returns Promise<MarmotGroup<THistory, TMedia>>

      The persisted and cached MarmotGroup

      Error if a group with the same id already exists

    • Creates a commit from proposals and publishes it to the group.

      Resolves the committing member from the manager's signer, builds a commit intent, and drives it through the group session/runtime. See GroupSessionSendIntent for how extraProposals, proposalRefs, and welcomeRecipients are interpreted. Requires a group admin.

      Parameters

      • groupId: string | Uint8Array<ArrayBufferLike>
      • Optionaloptions: Omit<
            {
                actorPubkey: string;
                expectedParent?: string;
                extraProposals?: CommitProposalInputs;
                kind: "commit";
                proposalRefs?: string[];
                signal?: AbortSignal;
                welcomeRecipients?: WelcomeRecipient[];
            },
            "kind"
            | "actorPubkey",
        >

      Returns Promise<Record<string, PublishResponse>>

      Per-relay publish responses for the commit group event.

    • Connects a single group to its relays: backfills its kind-445 transport events (by #h routing tag) and drains them through MarmotGroup.ingest, then opens a live subscription that ingests each subsequent event. Inbound events are de-duplicated, and unreadable ones surface via the unreadable event. Call .unsubscribe() on the result to disconnect.

      This is the inbound counterpart to the library's outbound publishing — the relay-subscription/backfill/drain loop an app would otherwise hand-write.

      Parameters

      • groupId: string | Uint8Array<ArrayBufferLike>
      • Optionaloptions: ConnectOptions

      Returns Promise<Unsubscribable>

    • Connects every loaded group (see connect) and keeps the set of connections in lockstep with the loaded groups: newly created/joined/ imported/loaded groups are connected automatically, and destroyed/left/unloaded/removed groups are disconnected. Returns a handle whose .unsubscribe() tears down every connection and stops tracking.

      Parameters

      Returns Unsubscribable

    • Destroys a group and purges the group history

      Parameters

      • groupId: string | Uint8Array<ArrayBufferLike>

      Returns Promise<void>

    • Checks if a group exists in the backend

      Parameters

      • groupId: string | Uint8Array<ArrayBufferLike>

      Returns Promise<boolean>

    • Invites a user to a group from their KeyPackage event (kind 30443).

      Resolves the committing member from the manager's signer, builds an Add commit intent via createInviteIntent (gated on the same injected verifier as the 445/1059/30443 inbound boundaries — SEC-01/WIRE-01/ WIRE-02), and drives it through the group session/runtime. After the commit acks, the runtime delivers a Welcome to the invitee via NIP-59 gift wrap.

      Parameters

      • groupId: string | Uint8Array<ArrayBufferLike>
      • keyPackageEvent: NostrEvent

      Returns Promise<Record<string, PublishResponse>>

      Per-relay publish responses for the commit group event.

      Error if the event is not a KeyPackage kind, fails signature verification, has invalid required-tag cardinality, has an over-long or not-current Lifetime, or the credential identity does not match the event author.

    • Joins a group from a decoded MLS Welcome using locally held key package candidates (produced by KeyPackageManager.selectForWelcome).

      Mirrors the darkmatter engine do_join_welcome: the KeyPackageRef→private bundle match and the MLS join happen here, in the group layer, not in the composition root. Tries candidates in priority order, then requires the joined GroupContext to classify as the current 0x8009 profile (rejecting legacy, mixed, and neither) and every member leaf's proof to validate against the group ciphersuite — both before adopting state, per refs/marmot/app-components/account-identity-proof-v2.md "Migration from v1" — then adopts the resulting state and emits joined.

      Parameters

      • options: {
            beforeAdopt?: (
                groupId: Uint8Array,
                keyPackageRef: Uint8Array,
            ) => Promise<void>;
            candidates: WelcomeKeyPackageCandidate[];
            ciphersuiteImpl: CiphersuiteImpl;
            welcome: Welcome;
        }
        • OptionalbeforeAdopt?: (groupId: Uint8Array, keyPackageRef: Uint8Array) => Promise<void>

          Records durable cleanup intent only after validation and duplicate rejection.

        • candidates: WelcomeKeyPackageCandidate[]
        • ciphersuiteImpl: CiphersuiteImpl
        • welcome: Welcome

      Returns Promise<
          {
              consumedKeyPackageRef: Uint8Array<ArrayBufferLike>
              | null;
              group: MarmotGroup<THistory, TMedia>;
          },
      >

      The joined group and the KeyPackageRef that was consumed (so the caller can mark it used), or consumedKeyPackageRef: null if none matched.

    • Leaves a group by publishing a self-remove proposal and purging all local group data from storage.

      At least one relay must acknowledge the proposals before local state is destroyed. If no relay acks, an error is thrown and local state is preserved so the caller can retry.

      Parameters

      • groupId: string | Uint8Array<ArrayBufferLike>

        The group ID as a hex string or Uint8Array.

      Returns Promise<Record<string, PublishResponse>>

      The relay publish responses for the leave proposal event(s).

    • Lists all persisted group IDs, decoded from their hex storage keys.

      Returns Promise<Uint8Array<ArrayBufferLike>[]>

    • Returns the runtime publisher for a loaded or persisted group.

      Parameters

      • groupId: string | Uint8Array<ArrayBufferLike>

      Returns Promise<GroupRuntime>

    • Sends a session intent through the group, convergence-gated (B5): published immediately when convergence is Settled, otherwise queued until the quiescence window settles and the queue drains. Used by commit/invite and direct application-message sends; leave bypasses the gate.

      Parameters

      Returns Promise<GroupPublishResult[]>

    • Unloads a group from the client but does not remove it from the store

      Parameters

      • groupId: string | Uint8Array<ArrayBufferLike>

      Returns Promise<void>

    • Watches for changes to the groups in the store. Returns an async generator that yields the current list of groups whenever the store changes.

      Parameters

      • Optionaloptions: { includeStateChanges?: boolean; signal?: AbortSignal }
        • OptionalincludeStateChanges?: boolean

          Watch loaded groups and their UI state without loading storage. Call loadAll() to hydrate first.

        • Optionalsignal?: AbortSignal

      Returns AsyncGenerator<MarmotGroup<THistory, TMedia>[]>

    prefixed: string | boolean
    • Return an array listing the events for which the emitter has registered listeners.

      Returns (keyof GroupsManagerEvents<THistory, TMedia>)[]

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

      Parameters

      Returns number

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

      Parameters

      • Optionalevent: keyof GroupsManagerEvents<THistory, TMedia>

      Returns this