@customerlog/sdk

The official Node.js / TypeScript SDK for customer.log.

Monitor events from your backend, CLI, or anywhere JavaScript runs. One function call — events appear in your live dashboard and ping your team on Slack, email, and more.

import { CustomerLog } from "@customerlog/sdk";

const customer = new CustomerLog({ apiKey: "cl_xxx" });

await customer.log({
  channel: "signups",
  title: "User signed up",
  level: "success",
  user: { id: "usr_123", email: "[email protected]" },
});

Installation

npm install @customerlog/sdk
# or
yarn add @customerlog/sdk
# or
pnpm add @customerlog/sdk

Quick start

import { CustomerLog } from "@customerlog/sdk";

const customer = new CustomerLog({
  apiKey: process.env.CUSTOMER_LOG_API_KEY!,
});

// Log an event
await customer.log({
  channel: "payments",
  title: "Payment succeeded",
  message: "User purchased the Pro plan",
  level: "success",
  user: { id: "usr_456", email: "[email protected]", name: "Alex" },
  metadata: { plan: "pro", amount: 29.99, currency: "USD" },
  url: "https://yourapp.com/admin/orders/ord_789",
  notify: true,
});

API

new CustomerLog(config)

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | — | Required. Your project's API key | | baseUrl | string | https://event.customerlog.byorello.space | Override the ingestion endpoint (for self-hosted or dev) |

customer.log(options)

| Field | Type | Default | Description | |-------|------|---------|-------------| | channel | string | — | Required. Routing bucket, e.g. "signups", "payments" | | title | string | — | Required. Human-readable headline | | message | string? | — | Free-text detail | | level | string? | "info" | One of "info", "success", "warning", "error" — drives default icon and color | | user | object? | — | { id: string; email?: string; name?: string } | | metadata | object? | — | Anything structured — passed through to your dashboard | | tags | string[]? | — | Categorisation tags | | icon | string? | — | Override the level-based default icon (any Phosphor icon name) | | url | string? | — | Deep link back to the record in your own app | | notify | boolean? | true | Whether to trigger channel delivery | | dedupeKey | string? | — | Idempotency guard — same key returns existing event | | timestamp | string \| Date? | now | Override event time (for backfills / batched imports) | | groupId | string? | — | Links related events into one thread in the dashboard |

Returns

{
  message: string;
  event: {
    id: string;
    channel: string;
    title: string;
    message?: string;
    level?: string;
    user?: { id: string; email?: string; name?: string };
    metadata?: Record<string, unknown>;
    tags?: string[];
    icon?: string;
    url?: string;
    notify: boolean;
    groupId?: string;
    createdAt: string;
  };
}

Errors

customer.log() throws CustomerLogError on validation or server errors. The status property contains the HTTP status code.

import { CustomerLog, CustomerLogError } from "@customerlog/sdk";

try {
  await customer.log({ channel: "", title: "" });
} catch (err) {
  if (err instanceof CustomerLogError) {
    console.error(err.status, err.message); // 400, "channel is required"
  }
}

Examples

Track a signup

await customer.log({
  channel: "signups",
  title: "New user registered",
  level: "success",
  user: { id: "usr_789", email: "[email protected]", name: "Sam" },
  metadata: { source: "google-oauth", referral: "friend-invite" },
});

Alert on failure

await customer.log({
  channel: "payments",
  title: "Payment failed",
  message: "Stripe charge declined: card_not_supported",
  level: "error",
  user: { id: "usr_456" },
  metadata: { charge_id: "ch_xxx", error_code: "card_declined" },
  url: "https://yourapp.com/admin/orders/ord_789",
  notify: true,
});

Deduplicate webhook retries

await customer.log({
  channel: "stripe-webhooks",
  title: "Invoice paid",
  dedupeKey: "evt_webhook_abc123", // Stripe may retry; this key ensures one event
  metadata: { invoice_id: "in_xxx" },
});

License

MIT