Node.js SDK

Official Node.js/TypeScript SDK for Windback.

Node.js SDK

The official Windback SDK for Node.js and TypeScript. Use it to track events, create churn events, and manage recovery flows from your server.

Installation

npm

npm install @windback/sdk

Quick Start

import { Windback } from "@windback/sdk";

const windback = new Windback({
  apiKey: "sk_live_your_secret_key",
  projectSlug: "my-project",
});

// Track a customer event
await windback.trackEvent({
  event: "feature_used",
  customerEmail: "[e-mail]",
  properties: {
    feature: "exports",
    plan: "pro",
  },
});

Use your secret key (sk_) for server-side SDK calls. Never expose it in client-side code.

Track Events

Track customer behavior events to improve churn prediction and recovery personalization.

// Track a single event
await windback.trackEvent({
  event: "feature_used",
  customerEmail: "[e-mail]",
  properties: {
    feature: "dashboard",
    duration_seconds: 120,
  },
});

// Track a batch of events
await windback.trackEvents([
  {
    event: "login",
    customerEmail: "[e-mail]",
    timestamp: "2025-12-01T10:00:00Z",
  },
  {
    event: "subscription_renewed",
    customerEmail: "[e-mail]",
    properties: { plan: "pro", mrr: 2999 },
  },
]);

Cancel Flow

Submit cancellation data from your custom cancel flow.

// Submit a cancel flow response
await windback.submitCancelFlow({
  customerEmail: "[e-mail]",
  cancelReason: "Too expensive for our team",
  feedbackText: "Love the product but budget is tight",
  selectedOffer: "downgrade", // optional: if they accepted a retention offer
});

// Report just the cancel reason
await windback.reportCancelReason({
  customerEmail: "[e-mail]",
  reason: "switching_competitor",
});

Create Churn Events

Manually create churn events when not using webhooks.

const event = await windback.createChurnEvent({
  customerEmail: "[e-mail]",
  customerName: "Jane Smith",
  eventType: "cancellation",
  cancelReason: "Missing integrations we need",
  mrr: 4999,
  currency: "usd",
  planName: "Team Pro",
  tenureDays: 180,
});

console.log(event.id); // "evt_abc123"
console.log(event.status); // "new"

Recovery Templates

Create custom recovery email templates.

await windback.createRecoveryTemplate({
  name: "Win-back discount",
  subject: "We'd love to have you back, {{name}}",
  body: "Hi {{name}},\n\nWe noticed you recently canceled...",
  strategy: "discount",
});

Method Reference

Method	Description
trackEvent(event)	Track a single customer behavior event
trackEvents(events)	Track a batch of events
createChurnEvent(data)	Create a churn event manually
submitCancelFlow(data)	Submit cancel flow data (reason + feedback)
reportCancelReason(data)	Report a cancel reason for an existing event
createRecoveryTemplate(data)	Create a custom recovery email template

Error Handling

import { WindbackError } from "@windback/sdk";

try {
  await windback.createChurnEvent({ /* ... */ });
} catch (error) {
  if (error instanceof WindbackError) {
    console.error(error.status);  // HTTP status code
    console.error(error.message); // Error message
    console.error(error.code);    // Error code (e.g., "INVALID_API_KEY")
  }
}

TypeScript Support

The SDK is written in TypeScript and ships with full type definitions. All methods, parameters, and responses are fully typed.

import type {
  TrackEventInput,
  ChurnEventInput,
  ChurnEvent,
  CancelFlowInput,
} from "@windback/sdk";

The SDK automatically retries failed requests up to 3 times with exponential backoff.