@churndown/sdk 0.0.2 → 0.0.3

package/README.md

@@ -0,0 +1,127 @@
+# @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,
+})
+```
+
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@churndown/sdk",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "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",