@churndown/sdk 0.0.2 → 0.0.4

package/README.md

@@ -0,0 +1,146 @@
+# @churndown/sdk
+
+Official SDK for [Churndown](https://churndown.sh) — predict which users are about to churn so you can intervene.
+
+## Install
+
+```bash
+npm install @churndown/sdk
+```
+
+## Quick start
+
+```typescript
+import Churndown from "@churndown/sdk"
+
+const churndown = new Churndown("cd_YOUR_API_KEY")
+
+// Identify a user (call on sign up and every login)
+await churndown.identify({
+  userId: "user_123",
+  email: "sam@example.com",
+  name: "Sam Shore",
+})
+
+// Track a key action
+await churndown.track("user_123", "send-message")
+```
+
+That's it — two calls and you're done.
+
+## API
+
+### `new Churndown(apiKey, config?)`
+
+Create a new client instance.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `apiKey` | `string` | Yes | Your API key (starts with `cd_`) |
+| `config.baseUrl` | `string` | No | Override the API URL. Defaults to `https://churndown.sh/api` |
+
+### `churndown.identify(params)`
+
+Identify a user. Call this when a user signs up or logs in. Safe to call multiple times — it creates the user on the first call and updates on subsequent calls.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `userId` | `string` | Yes | Your internal user ID |
+| `email` | `string` | Yes | User's email address |
+| `name` | `string` | No | User's display name |
+| `image` | `string` | No | URL to user's avatar |
+| `properties` | `Record<string, unknown>` | No | Any additional user data |
+
+```typescript
+await churndown.identify({
+  userId: "user_123",
+  email: "sam@example.com",
+  name: "Sam Shore",
+  image: "https://example.com/avatar.jpg",
+  properties: {
+    plan: "pro",
+    company: "Acme Inc",
+  },
+})
+```
+
+### `churndown.track(userId, event, properties?)`
+
+Track a key action. Call this each time a user performs the action that signals they're active.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `userId` | `string` | Yes | The user's ID (same as in `identify`) |
+| `event` | `string` | Yes | Event name |
+| `properties` | `Record<string, unknown>` | No | Any additional event data |
+
+```typescript
+await churndown.track("user_123", "send-message", {
+  channel: "general",
+  messageLength: 142,
+})
+```
+
+### `churndown.importEvents(events)`
+
+Import historical events to backfill data. Each event must include a `timestamp`.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `events[].userId` | `string` | Yes | The user's ID |
+| `events[].event` | `string` | Yes | Event name |
+| `events[].timestamp` | `string` | Yes | ISO 8601 timestamp |
+| `events[].properties` | `Record<string, unknown>` | No | Any additional event data |
+
+```typescript
+await churndown.importEvents([
+  { userId: "user_123", event: "send-message", timestamp: "2026-01-15T10:30:00Z" },
+  { userId: "user_123", event: "send-message", timestamp: "2026-02-01T14:22:00Z" },
+  { userId: "user_456", event: "send-message", timestamp: "2026-02-10T09:15:00Z" },
+])
+```
+
+## Frameworks
+
+Works everywhere — server-side, client-side, edge functions, serverless. The SDK is just a thin `fetch` wrapper with no dependencies.
+
+### Next.js (App Router)
+
+```typescript
+// app/api/auth/callback/route.ts
+import Churndown from "@churndown/sdk"
+
+const churndown = new Churndown(process.env.CHURNDOWN_API_KEY!)
+
+export async function GET(request: Request) {
+  const user = await getUser(request)
+
+  await churndown.identify({
+    userId: user.id,
+    email: user.email,
+    name: user.name,
+  })
+
+  // ...
+}
+```
+
+### Express
+
+```typescript
+import Churndown from "@churndown/sdk"
+
+const churndown = new Churndown(process.env.CHURNDOWN_API_KEY!)
+
+app.post("/api/messages", async (req, res) => {
+  // ... create message ...
+
+  await churndown.track(req.user.id, "send-message")
+
+  res.json({ ok: true })
+})
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -14,13 +14,22 @@ interface TrackParams {
     event: string;
     properties?: Record<string, unknown>;
 }
+interface ImportEvent {
+    userId: string;
+    event: string;
+    timestamp: string;
+    properties?: Record<string, unknown>;
+}
 declare class Churndown {
     private apiKey;
     private baseUrl;
     constructor(apiKey: string, config?: Omit<ChurndownConfig, "apiKey">);
     identify(params: IdentifyParams): Promise<void>;
     track(userId: string, event: string, properties?: Record<string, unknown>): Promise<void>;
+    importEvents(events: ImportEvent[]): Promise<{
+        imported: number;
+    }>;
     private post;
 }
 
-export { Churndown, type ChurndownConfig, type IdentifyParams, type TrackParams, Churndown as default };
+export { Churndown, type ChurndownConfig, type IdentifyParams, type ImportEvent, type TrackParams, Churndown as default };

package/dist/index.d.ts

@@ -14,13 +14,22 @@ interface TrackParams {
     event: string;
     properties?: Record<string, unknown>;
 }
+interface ImportEvent {
+    userId: string;
+    event: string;
+    timestamp: string;
+    properties?: Record<string, unknown>;
+}
 declare class Churndown {
     private apiKey;
     private baseUrl;
     constructor(apiKey: string, config?: Omit<ChurndownConfig, "apiKey">);
     identify(params: IdentifyParams): Promise<void>;
     track(userId: string, event: string, properties?: Record<string, unknown>): Promise<void>;
+    importEvents(events: ImportEvent[]): Promise<{
+        imported: number;
+    }>;
     private post;
 }
 
-export { Churndown, type ChurndownConfig, type IdentifyParams, type TrackParams, Churndown as default };
+export { Churndown, type ChurndownConfig, type IdentifyParams, type ImportEvent, type TrackParams, Churndown as default };

package/dist/index.js

@@ -39,6 +39,10 @@ var Churndown = class {
   async track(userId, event, properties) {
     await this.post("/v1/track", { userId, event, properties });
   }
+  async importEvents(events) {
+    const res = await this.post("/v1/import", { events });
+    return res;
+  }
   async post(path, body) {
     const res = await fetch(`${this.baseUrl}${path}`, {
       method: "POST",

package/dist/index.mjs

@@ -14,6 +14,10 @@ var Churndown = class {
   async track(userId, event, properties) {
     await this.post("/v1/track", { userId, event, properties });
   }
+  async importEvents(events) {
+    const res = await this.post("/v1/import", { events });
+    return res;
+  }
   async post(path, body) {
     const res = await fetch(`${this.baseUrl}${path}`, {
       method: "POST",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@churndown/sdk",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Official Churndown SDK — identify users and track key actions",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -12,7 +12,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",