Quickstart

This is the fastest path from install to a working score.

1. Install


npm install tiaude


pnpm add tiaude

2. Create a scorer

Create the scorer once from a stable config.


import { createChurnScorer } from "tiaude";
 
export const scorer = createChurnScorer({
    baseRisk: 20,
    signals: [
        {
            id: "inactive",
            type: "absence",
            event: "app.opened",
            weight: 30,
            halfLifeDays: 7,
            reason: "No recent activity",
            action: "Send a re-engagement message",
        },
        {
            id: "billing_failed",
            type: "occurrence",
            event: "billing.payment_failed",
            weight: 40,
            halfLifeDays: 3,
            reason: "Recent billing failure",
            action: "Ask the user to update their payment method",
        },
        {
            id: "strong_usage",
            type: "frequency_above",
            event: "feature.used",
            weight: -20,
            halfLifeDays: 7,
            threshold: 5,
            reason: "Strong recent product usage",
        },
    ],
});

3. Track a new event

Use track() when a new product event arrives.


const result = scorer.track({
    userId: "user_123",
    previousState: user.churnState ?? null,
    event: {
        name: "feature.used",
        timestamp: new Date(),
    },
});

The first call can use previousState: null.

After that, pass the latest saved result.state.

4. Persist the result

Save the state so the next event can be processed incrementally.


await db.user.update({
    where: { id: "user_123" },
    data: {
        churnState: result.state,
        churnRiskScore: result.riskScore,
        churnRiskLevel: result.riskLevel,
    },
});

At minimum, persist:


result.state
result.riskScore
result.riskLevel

5. Use the output


return {
    score: result.riskScore,
    level: result.riskLevel,
    confidence: result.confidence,
    freshness: result.freshness,
    reasons: result.reasons,
    actions: result.recommendedActions,
};

6. Keep raw events

Tiaude state is not a replacement for your event history.

You should still store product events in your own database.


raw events   -> source of truth
Tiaude state -> fast incremental scoring

Raw events are needed when you want to rebuild with scoreUser() after config changes, out-of-order delivery, or corrupted state.