ChimeKit Node SDK

Official Node.js SDK for the ChimeKit API. ChimeKit is a notifications platform for sending, managing, and displaying in-app messages and emails for your users.

What you get:

• Identify and manage audience members with custom attributes.
• Send messages via templates or custom content (in-app and email).
• Trigger workflows programmatically.
• Manage suppressions (opt-outs) per member and category.
• Generate member tokens for the React/Vue client SDKs.

Installation

npm install @chimekit/node

pnpm add @chimekit/node

yarn add @chimekit/node

Requirements: Node.js 18+ (uses native fetch and crypto).

Usage

1) Quickstart

import { ChimeKit } from "@chimekit/node";

const chimekit = new ChimeKit({
  secretKey: process.env.CHIMEKIT_SECRET_KEY!,
});

// Identify a user
const member = await chimekit.identify("user_123", {
  displayName: "Jane Doe",
  identities: [{ type: "email", value: "[email protected]", verified: true }],
  attributes: { plan: "pro", signupDate: "2024-01-15" },
});

// Send a message
await member.messages.sendMessage({
  content: { templateId: "welcome-email" },
});

// Generate a token for the React/Vue SDK
const token = member.createToken();

2) Client setup

Create a client with your secret key:

import { ChimeKit } from "@chimekit/node";

const chimekit = new ChimeKit({
  secretKey: process.env.CHIMEKIT_SECRET_KEY!,
});

Optional configuration:

const chimekit = new ChimeKit({
  secretKey: process.env.CHIMEKIT_SECRET_KEY!,
  baseUrl: "https://api.chimekit.com/sdk/v1", // default
  timeout: 30000, // request timeout in ms
  retries: 2, // retry count for failed requests
});

3) Identifying members

identify creates or updates an audience member and returns a handle for further operations:

const member = await chimekit.identify("user_123", {
  displayName: "Jane Doe",
  identities: [
    { type: "email", value: "[email protected]", verified: true },
  ],
  attributes: {
    plan: "pro",
    company: "Acme Inc",
  },
});

// Access member data
console.log(member.id, member.email, member.displayName);

// Update the member
await member.update({
  attributes: { plan: "enterprise" },
});

// Refresh data from the server
await member.refresh();

You can also find existing members:

const member = await chimekit.audience.findMember("user_123");
if (member) {
  console.log(member.displayName);
}

4) Sending messages

Send messages using templates or custom content:

// Using a template
await member.messages.sendMessage({
  content: { templateId: "order-confirmation" },
});

// With template variables
await member.messages.sendMessage({
  content: {
    templateId: "order-confirmation",
    variables: { orderId: "ORD-123", total: "$99.00" },
  },
});

// Custom in-app notification
await member.messages.sendMessage({
  content: {
    in_app: {
      title: "New feature available",
      snippet: "Check out our new dashboard",
      body: "<p>We've redesigned the dashboard for better insights.</p>",
      actions: {
        primary: { type: "link", label: "View Dashboard", href: "/dashboard" },
      },
    },
  },
});

// Custom email
await member.messages.sendMessage({
  content: {
    email: {
      title: "Your weekly summary",
      body: "<h1>This week at a glance</h1><p>...</p>",
    },
  },
});

Retrieve message details:

const message = await chimekit.messages.getMessage("msg_abc123");
console.log(message.dispatchStatus);

5) Running workflows

Trigger workflows by key:

const run = await member.workflows.run("onboarding-sequence", {
  context: { source: "signup", campaign: "summer-2024" },
});

console.log(run.runId, run.status); // "queued"

// Check workflow run status
const status = await chimekit.workflow.getRun(run.runId);
console.log(status.status); // "running" | "completed" | "failed"

6) Managing suppressions

Suppressions allow members to opt out of notifications:

// Suppress all emails for a member
await member.suppress({
  identity: { type: "email", value: "[email protected]" },
});

// Suppress a specific category
await member.suppress({
  identity: { type: "email", value: "[email protected]" },
  categoryId: "marketing",
});

// List suppressions
const suppressions = await member.listSuppressions();

// Remove a suppression
await member.removeSuppression("sup_abc123");

7) Generating tokens

Generate tokens for the React/Vue client SDKs:

// From a member handle
const token = member.createToken();

// Or directly with member ID
const token = chimekit.audience.createToken({
  externalUserId: "user_123",
});

Tokens are JWTs valid for 1 hour. Use them with ChimeKitProvider (React) or ChimeKitRoot (Vue).

API Reference

Client

• new ChimeKit(options) - Create a new client
• chimekit.identify(id, options) - Identify a member (returns handle)

Audience

• chimekit.audience.identify(id, options) - Create/update member
• chimekit.audience.findMember(id) - Find member by ID
• chimekit.audience.updateMember(id, options) - Update member
• chimekit.audience.deleteMember(id) - Delete member
• chimekit.audience.suppress(id, options) - Add suppression
• chimekit.audience.listSuppressions(id) - List suppressions
• chimekit.audience.removeSuppression(id, suppressionId) - Remove suppression
• chimekit.audience.createToken(options) - Generate member token

Messages

• chimekit.messages.sendMessage(id, options) - Send message
• chimekit.messages.getMessage(messageId) - Get message details
• chimekit.messages.listMessagesForUser(userId, options) - List messages

Workflows

• chimekit.workflow.run(key, options) - Run workflow
• chimekit.workflow.getRun(runId) - Get workflow run status

Member Handle

The handle returned from identify or findMember provides convenience methods:

• member.update(options) - Update member
• member.delete() - Delete member
• member.refresh() - Reload from server
• member.suppress(options) - Add suppression
• member.listSuppressions() - List suppressions
• member.removeSuppression(id) - Remove suppression
• member.createToken() - Generate token
• member.messages.sendMessage(options) - Send message
• member.workflows.run(key, options) - Run workflow

Error Handling

The SDK throws typed errors for different failure modes:

import { ChimeKitError, HTTPError, AuthError, RateLimitError } from "@chimekit/node";

try {
  await chimekit.identify("user_123", { identities: [] });
} catch (error) {
  if (error instanceof AuthError) {
    // Invalid or expired API key
    console.error("Authentication failed:", error.message);
  } else if (error instanceof RateLimitError) {
    // Too many requests
    console.error("Rate limited, retry after:", error.retryAfterMs);
  } else if (error instanceof HTTPError) {
    // Other API error
    console.error("API error:", error.status, error.body);
  } else if (error instanceof ChimeKitError) {
    // SDK error
    console.error("ChimeKit error:", error.message);
  }
}

The SDK automatically retries on 5xx errors and rate limits with exponential backoff.

Documentation

Full API reference and guides: https://docs.chimekit.com/server-sdks

License

MIT License - see LICENSE for details.