churnsignal-sdk

v1.0.2

Published

14 days ago

Track user behavior and predict churn before it happens. Official ChurnSignal SDK.

0High
0Medium
0Low

ashishsharma0198

churn analytics saas retention user-tracking churn-prediction

churnsignal

Track user behavior and predict churn before it happens.

ChurnSignal detects at-risk users in your SaaS app and alerts you before they cancel. This is the official JavaScript/TypeScript SDK.

Installation

npm install churnsignal
# or
yarn add churnsignal
# or
pnpm add churnsignal

Quick Start

import { ChurnSignal } from 'churnsignal'

// 1. Initialize once (app root / layout)
ChurnSignal.init({
  apiKey: process.env.NEXT_PUBLIC_CHURNSIGNAL_KEY!
})

// 2. Track events anywhere
ChurnSignal.track({
  userId: user.id,
  event: 'login'
})

// 3. Identify users (optional but recommended)
ChurnSignal.identify({
  userId: user.id,
  email: user.email,
  metadata: {
    plan: 'pro',
    country: 'US'
  }
})

Framework Examples

Next.js (App Router)

// app/layout.tsx
import { ChurnSignal } from 'churnsignal'

ChurnSignal.init({
  apiKey: process.env.NEXT_PUBLIC_CHURNSIGNAL_KEY!
})

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return <html><body>{children}</body></html>
}

// Track on user actions
import { ChurnSignal } from 'churnsignal'

ChurnSignal.track({ userId: user.id, event: 'export_csv' })
ChurnSignal.track({ userId: user.id, event: 'plan_downgraded', metadata: { from: 'pro', to: 'free' } })

Node.js / Express

import { ChurnSignal } from 'churnsignal'

ChurnSignal.init({ apiKey: process.env.CHURNSIGNAL_KEY! })

app.post('/auth/login', async (req, res) => {
  const user = await login(req.body)
  ChurnSignal.track({ userId: user.id, event: 'login' })
  res.json({ user })
})

API

`ChurnSignal.init(config)`

Initialize the SDK. Call this once at app startup before any track() or identify() calls.

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | required | Your ChurnSignal API key (cs_live_...) | | debug | boolean | false | Log events to console | | disabled | boolean | false | Disable all tracking | | flushInterval | number | 5000 | Batch send interval in ms | | maxRetries | number | 3 | Retry attempts on network failure |

`ChurnSignal.track(options)`

Track a user event.

| Option | Type | Required | Description | |---|---|---|---| | userId | string | ✓ | Your user's unique ID | | event | string | ✓ | Event name (snake_case recommended) | | metadata | object | — | Any extra JSON data (max 5KB) |

High-signal events to track:

// These most affect churn scoring
ChurnSignal.track({ userId, event: 'login' })
ChurnSignal.track({ userId, event: 'logout' })
ChurnSignal.track({ userId, event: 'plan_downgraded' })
ChurnSignal.track({ userId, event: 'payment_failed' })
ChurnSignal.track({ userId, event: 'support_ticket_opened' })
ChurnSignal.track({ userId, event: 'export_data' })
ChurnSignal.track({ userId, event: 'onboarding_completed' })

`ChurnSignal.identify(options)`

Set or update user properties. Call on signup or when user properties change.

| Option | Type | Required | Description | |---|---|---|---| | userId | string | ✓ | Your user's unique ID | | email | string | — | User's email address | | metadata | object | — | Any user properties |

ChurnSignal.identify({
  userId: 'user_123',
  email: '[email protected]',
  metadata: {
    plan: 'pro',
    company: 'Acme Corp',
    country: 'US',
    signupSource: 'google'
  }
})

`ChurnSignal.reset()`

Clear config and stop tracking. Useful for logout flows.

// On user logout
ChurnSignal.reset()

Debug Mode

ChurnSignal.init({
  apiKey: 'cs_live_xxx',
  debug: process.env.NODE_ENV === 'development'
})

// Now all events are logged to console:
// [ChurnSignal] track { userId: 'u1', event: 'login' }

Disabling Tracking (GDPR / Opt-out)

// Disable for users who opted out
ChurnSignal.init({
  apiKey: 'cs_live_xxx',
  disabled: !user.analyticsConsent
})

TypeScript

Full TypeScript support included. No @types package needed.

import { ChurnSignal, ChurnSignalConfig, TrackOptions } from 'churnsignal'

How It Works

You call track() from your app
Events are batched and sent to api.churnsignal.io
ChurnSignal writes events to your own Supabase database (BYOD model)
Every 6 hours, ChurnSignal recalculates churn scores for all your users
When a user's score crosses your threshold → you get a Slack/email alert

Your data never leaves your infrastructure.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme