Node.js SDK

import { initialize, captureEvent, shutdown, Metrics, RawEvents } from "churn-warn-node-sdk";

initialize({
baseUrl: "https://your-gateway.example.com",
apiToken: process.env.CHURNWARN_TOKEN, // or apiKey for X-Api-Key
defaultTenantId: null,
defaultSource: "node_sdk",
batchSize: 50,
flushIntervalMs: 5000,
maxQueueSize: 10000,
onSendError: (e) => console.error("send failed", e),
});

captureEvent("acct-1", Metrics.LOGIN, { payload: { path: "/" } });
captureEvent({ externalAccountId: "acct-2", eventType: RawEvents.APP_LOGIN, payload: { x: 1 } });

await shutdown();

Add the churn-warn-node-sdk to this Node service.

How it works: call initialize({ ... }) once at boot, then captureEvent(externalAccountId,
eventType, { payload }) from anywhere. It is fire-and-forget, queued, and flushed in batches
to POST /api/events/batch. Zero dependencies; needs Node 18+ (global fetch).

Please:
1. initialize() once at startup. Read config from the environment: apiKey = CHURNWARN_API_KEY
 (X-Api-Key) or apiToken = CHURNWARN_TOKEN (Bearer), baseUrl = the gateway URL,
 defaultSource = "<this-service-name>".
2. Wire onSendError to our logger so dropped/failed sends are observable.
3. Call await shutdown() in the process's graceful-shutdown path (SIGTERM/SIGINT) so the
 queue drains before exit.
4. Use the account id from our own database as externalAccountId (the tenant/org id, NOT the
 per-user id), and keep payloads to a few small fields.
5. Import and use the Metrics and RawEvents constants instead of raw strings.

Leave redactPayload at its default. Do not await captureEvent or try/catch it — it never throws.

Instrument the business signals that feed ChurnWarn's default Product Health dashboard by
adding captureEvent(externalAccountId, <metric>, { payload: <object> }) calls in this codebase.
The browser SDK already auto-captures usage, sessions, clicks, frustration and JS errors —
do NOT re-send those from the server. Add only the signals below, each at the call site
described:

- Metrics.LOGIN — in the authentication success path, right after the session/token is issued
(the same place you already record a successful sign-in). payload: { external_user_id: the
signed-in user's id }.
- Metrics.ACTIVE_USER — once per user per day. Add it to auth middleware and guard it with a
cheap per-user-per-day check (cache/Redis/DB flag) so it fires at most once a day per user.
payload: { external_user_id }. Drives the distinct-active-users count.
- Metrics.ONBOARDING_COMPLETED — where the onboarding/setup flow marks itself done (the final
step handler, or where you flip an "onboarded" flag). Fire once per account.
- Metrics.FEATURE_USED — in the handler of a high-value action (report generated, export run,
integration connected), not on every request. payload: { feature: "<stable-short-name>" }.
- Metrics.SESSION — where a session ends / on logout, if you track session length. Skip it
entirely if you have no session concept. payload: { session_minutes: <number> }.
- Metrics.SEAT_USED and Metrics.SEAT_PURCHASED — in your billing/subscription code where seat
counts can change (a subscription-updated webhook, a member invited/removed, a plan change).
Emit BOTH with current counts. payload: { count: <int> } on each (utilization = used ÷ purchased).
- Metrics.SEAT_EXPANDED / Metrics.PLAN_UPGRADED — in that same billing path, when seats
increase or the plan moves to a higher tier.
- Metrics.REFERRAL — where a referral is recorded as successful (accepted/converted) in your
invite/referral flow.
- Metrics.NPS_RESPONSE / Metrics.CSAT_RESPONSE — in your survey-submission handler or survey
webhook. payload: { score: <0-10 for NPS / 1-5 for CSAT> }.
- Metrics.SUPPORT_TICKET_OPENED / RESOLVED / NEGATIVE — in your ticket lifecycle / support
webhook, ONLY if you do NOT use a Zendesk/Intercom/Freshdesk integration (those map
automatically). payload on resolved: { resolution_hours: <number> }.

Always pass our own DB account id (the tenant/organization id) as externalAccountId.

Make these changes non-breaking — they must be pure additive telemetry:
- Add each call AFTER the existing operation has fully succeeded (after the DB commit / after
the response is decided). Never change control flow, return values, function signatures, or
business logic.
- captureEvent is fire-and-forget and never throws — do NOT await it, do NOT wrap surrounding
code in new try/catch, and do NOT let it block the request path.
- Don't add new blocking I/O; the SDK buffers and sends in the background. Reuse the existing
initialize() — do not re-initialize.
- If you can't confidently find the correct call site for a signal, SKIP it and leave a
// TODO: ChurnWarn <metric> here comment instead of guessing. Omitting a signal is fine;
firing it from the wrong place is not.
- Keep each edit small and reviewable, and keep payloads to the documented fields only.