How to use

Tiaude turns product events into explainable churn risk scores.

This section is about usage, not internals. The goal is to help you integrate Tiaude quickly, persist the right data, and know when to use each scoring method.

Start here

• Quickstart: install, configure, score, persist
• Configuration: define signals for your product
• Runtime scoring: choose between track(), scoreUser(), and refreshScore()
• ChurnResult: Understand the standardized structure that all Tiaude scoring methods return
• Production: persistence and backend patterns
• Errors and recovery: what can fail and how to recover

The core integration model

Tiaude has two important pieces of data:

raw events      = your source of truth
Tiaude state    = compact runtime optimization

The state lets you avoid recomputing a user from all historical events every time something happens.

But it does not replace raw event storage.

In a serious backend integration, you should store both:

• raw product events in your own database;
• the latest Tiaude state for each user.

The three methods

track()        -> normal event ingestion path
scoreUser()    -> full recompute from raw events
refreshScore() -> time-only recalculation without a new event

Use track() for the hot path.

Use scoreUser() when you need to rebuild safely.

Use refreshScore() when time passes and you want scores to age.

Recommended production pattern

The recommended backend convention is:

try track() or refreshScore()
if incremental reuse fails -> load raw events -> scoreUser()

That gives you a fast path and a safe recovery path.

try {
    const result = scorer.track({
        userId,
        previousState: user.churnState ?? null,
        event,
    });
 
    await saveChurnState(userId, result.state);
    return result;
} catch (error) {
    if (shouldRecompute(error)) {
        const events = await loadUserEvents(userId);
 
        const result = scorer.scoreUser({
            userId,
            events,
        });
 
        await saveChurnState(userId, result.state);
        return result;
    }
 
    throw error;
}

Mental model for LLMs and agents

When generating code that uses Tiaude:

1. create one scorer from a stable config;
2. store raw events in the app database;
3. store result.state per user;
4. call track() when a new event arrives;
5. call refreshScore() for scheduled aging;
6. call scoreUser() when state cannot be reused;
7. never treat Tiaude state as the only source of truth.

The safest generated integration is always:

hot path: track(previousState, event)
fallback: scoreUser(rawEvents)