Client Module

The Client module (marmot-ts/client) provides a high-level, production-ready implementation for building Marmot applications.

What's in the Client Module

• MarmotClient: Multi-group orchestration with lifecycle management
• MarmotGroup: Group operations (messaging, proposals, commits) — a facade over the engine
• GroupsManager: Group creation, loading, watching, leaving, and destruction via client.groups
• KeyPackageManager: Key package creation, publishing, watching, and rotation via client.keyPackages
• InviteManager: Gift-wrap ingestion, decryption, and unread tracking via client.invites
• History Management: Optional message storage with querying and pagination
• Proposal System: Type-safe builders for group operations (Proposals)
• Network Abstraction: Pluggable Nostr client integration
• Storage Abstraction: Pluggable persistence backends

Architecture

MarmotClient (Orchestration Layer)
    ↓  client.groups / client.keyPackages / client.invites
MarmotGroup (Group Operations Facade)
    ↓  GroupSession + GroupRuntime
Engine Module (Protocol State Machine)
    ↓
Core Module (Protocol Layer)
    ↓
MLS (ts-mls) + Nostr

Installation

import {
  MarmotClient,
  MarmotGroup,
  Proposals,
} from "@internet-privacy/marmot-ts";

Topics

MarmotClient

Multi-group management, creating/joining/loading groups, lifecycle events.

MarmotGroup

Single group operations, sending messages, processing events, proposals and commits.

Proposals

Type-safe proposal builders for inviting users, removing users, and updating metadata.

History

Message storage, querying, and pagination with GroupRumorHistory.

Network

NostrNetworkInterface abstraction for integrating with Nostr clients.

Storage

Key/value stores for persisting serialized group state, key packages, and invites.

Best Practices

Recommended patterns for commits, state persistence, relay selection, and more.

Complete API documentation for all Client module classes and functions.

When to Use Client

Use the Client module for:

• Production applications with full group management
• Chat applications needing message history
• Applications requiring reactive updates (event-driven)
• Most use cases - it's the recommended starting point

For fine-grained control or protocol research, use the Core module directly.

Quick Example

import {
  MarmotClient,
  createApplicationMessageIntent,
  createChatRumor,
  deserializeApplicationData,
} from "@internet-privacy/marmot-ts";

// Create client
const client = new MarmotClient({
  signer,
  network,
  groupStateStore,
  keyPackageStore,
});

// Create group
const group = await client.groups.create("My Group", {
  relays: ["wss://relay.example.com"],
  adminPubkeys: [myPubkey],
});

// Send message
const rumor = createChatRumor({ pubkey: myPubkey, content: "Hello, Marmot!" });
await client.groups.send(group.id, createApplicationMessageIntent(rumor));

// Listen for messages
group.on("applicationMessage", (message) => {
  const rumor = deserializeApplicationData(message);
  console.log(`${rumor.pubkey}: ${rumor.content}`);
});

Key Features

Event-Driven Architecture

GroupsManager, KeyPackageManager, InviteManager, and MarmotGroup emit events for reactive UI updates.

Type Safety

Generic type system ensures type consistency between client and groups.

Pluggable Components

• Storage backends (in-memory, IndexedDB, filesystem)
• Network interfaces (nostr-tools, NDK, etc.)
• History implementations (custom storage)
• Crypto providers

Performance

• Group caching and deduplication
• Lazy loading
• Efficient batch processing
• Non-blocking history operations

Protocol Compliance

Implements Marmot v2 (MIP-00 through MIP-03, with MIP-04 media in progress) and is wire-compatible with the darkmatter reference implementation.