buzz-ts

buzz-ts is a pre-1.0, runtime-neutral TypeScript SDK for one authenticated Buzz Community Session. It exposes Community, Channel, Community Member, Channel Member, and Message concepts while keeping Nostr filters, tags, event kinds, NIP-42 authentication, signing, and relay acknowledgements behind active resources.

Install

bun add buzz-ts nostr-tools

The same ESM package supports Bun, Node.js 22+, and modern browsers.

Connect

Provide a nostr-tools/signer Signer. The SDK never accepts a raw secret key and does not create or retain one.

import { BuzzClient } from "buzz-ts";

const client = await BuzzClient.connect({
  communityUrl: "wss://community.example",
  signer,
});

console.log(client.identity.publicKey);
console.log(client.community.name, client.community.admission);

connect() resolves only after the WebSocket is open, proactive NIP-42 authentication is accepted, and NIP-11 Community metadata is available. A failed initialization closes the underlying relay and never returns a half-authenticated client. Each client remains permanently bound to its original Community URL and Identity.

Domain resources

const channels = await client.community.channels.listVisible();
const channel = await client.community.channels.get(channelId);

if (channel) {
  await channel.join();

  const recent = await channel.messages.listRecent({ limit: 50 });
  const message = await channel.messages.send("Hello");
  const reply = await message.reply("Welcome!");
  await reply.react("👍");
  await reply.delete();

  const subscription = channel.messages.subscribe({
    onMessage: (liveMessage) => console.log(liveMessage.content),
    onError: (error) => console.error(error.code, error.cause),
  });

  subscription.close();
}

Channel and Message properties are immutable snapshots. Operations wait for relay acceptance and return new active resources instead of mutating existing ones. toJSON() returns passive, serializable data with no signer, relay, or session capability.

Plain-text Message content is limited to 64 KiB, and reaction content to 64 Unicode characters, matching the pinned Buzz relay builders.

Membership is deliberately exposed as self() and listVisible(): NIP-43 and NIP-29 lists can be partial, so the API does not imply that a visible roster is complete. Role labels remain opaque relay-defined strings.

Channel Access is represented independently as metadata, read, write, and join; it is not collapsed into a single visibility flag. The source Nostr event remains available on event-backed Channel and Message resources.

Raw protocol access

Unsupported standard events are available through a separate surface:

const events = await client.raw.query([{ kinds: [10000] }]);
const accepted = await client.raw.publish({
  kind: 10000,
  content: "",
  created_at: Math.floor(Date.now() / 1000),
  tags: [],
});

There are no duplicate client-level commands for operations already owned by resources.

Errors and lifecycle

Every expected SDK failure is a BuzzError with one stable code:

connection, authentication, disconnected, closed, signing, relay-rejected, invalid-input, invalid-relay-event, authorization, timeout, or cancelled.

cause preserves the original failure and relayReason preserves relay acknowledgement text. New one-shot operations fail while disconnected and are never queued. Existing live subscriptions use nostr-tools' basic reconnection behavior; the SDK does not promise replay, deduplication, gap repair, or lossless delivery.

client.close() closes the relay and active subscriptions idempotently. Snapshot properties remain readable afterward, while resource operations fail with code: "closed".

Testing and advanced relay injection

The package exports the relay adapter contract for deterministic integration seams. The test-only entrypoint includes the in-memory adapter used by the behavior suite:

import { FakeRelayAdapter } from "buzz-ts/testing";

const relay = new FakeRelayAdapter({ events, relayInformation });
const client = await BuzzClient.connect({
  communityUrl: "wss://test.example",
  signer,
  relayFactory: () => relay,
});

The fake controls authentication, query results, publish acceptance/rejection, disconnection, reconnection, live events, subscription errors, and closure. Tests generate ephemeral signing keys and never store or print them.

Run all verification:

bun run check

Set BUZZ_TEST_RELAY_URL to include the opt-in local Buzz relay conformance test. The reproducible relay fixture must use a stable relay signing key (advertised as NIP-11 self), admit an ephemeral Identity, and seed at least one open Channel; the test authenticates, reads NIP-29 state, joins, publishes, receives acknowledgements, and deletes its probe Message.

See protocol conformance and the acceptance trace.

License

MIT. See LICENSE.