@xmtp/notifications-client

TypeScript client for the XMTP push notification server. Provides a high-level API over the ConnectRPC service, hiding protobuf details behind idiomatic TypeScript types.

Installation

npm install @xmtp/notifications-client

Usage

The package provides platform-specific entry points that handle transport automatically:

// Node.js
import { createNotificationsClient } from "@xmtp/notifications-client/node";

// Browser
import { createNotificationsClient } from "@xmtp/notifications-client/browser";

const client = createNotificationsClient({ baseUrl: "http://localhost:8080" });

// Register a device
await client.register("installation-id", {
  kind: "apns",
  token: "device-token",
});

// Subscribe to topics
await client.subscribe("installation-id", [
  { topic: "/xmtp/mls/1/g-group-id" },
  {
    topic: "/xmtp/mls/1/g-other-group",
    isSilent: true,
    hmacKeys: [
      {
        thirtyDayPeriodsSinceEpoch: 678,
        key: new Uint8Array([1, 2, 3]),
      },
    ],
  },
]);

// Unsubscribe
await client.unsubscribe("installation-id", ["/xmtp/mls/1/g-group-id"]);

// Delete an installation
await client.delete("installation-id");

Entry Points

| Import | Description | | ------------------------------------ | ---------------------------------------- | | @xmtp/notifications-client | NotificationsClient class + types | | @xmtp/notifications-client/node | createNotificationsClient for Node.js | | @xmtp/notifications-client/browser | createNotificationsClient for browsers |

The /node and /browser entry points accept ConnectTransportOptions from their respective @connectrpc packages.

API

createNotificationsClient(options: ConnectTransportOptions)

Creates a client with the platform transport wired up automatically. This is the recommended way to create a client.

register(installationId: string, mechanism: DeliveryMechanism): Promise<void>

Registers a device for push notifications.

delete(installationId: string): Promise<void>

Deletes an installation and all its subscriptions.

subscribe(installationId: string, subscriptions: Subscription[]): Promise<void>

Subscribes to one or more topics. Each subscription can optionally include isSilent and hmacKeys.

unsubscribe(installationId: string, topics: string[]): Promise<void>

Unsubscribes from one or more topics.

Types

DeliveryMechanism

Discriminated union for push delivery targets:

type DeliveryMechanism =
  | { kind: "apns"; token: string }
  | { kind: "fcm"; token: string }
  | { kind: "custom"; token: string }
  | { kind: "webPush"; endpoint: string; p256dh: string; auth: string };

Subscription

interface Subscription {
  topic: string;
  isSilent?: boolean;
  hmacKeys?: HmacKey[];
}

HmacKey

interface HmacKey {
  thirtyDayPeriodsSinceEpoch: number;
  key: Uint8Array;
}