Define milestone rules for user activity and trigger automated actions when thresholds are met in Convex applications.
npm install @abdssamie/convex-checkpointsConvex Checkpoints tracks user activity milestones and triggers automated actions when thresholds are met. You define rules with factors (like 'signup' or 'create_post') and thresholds, then the component monitors progress across users and executes your callback functions when milestones are reached. It handles rule configuration, progress tracking, and completion detection while your app owns the actual side effects.
Convex Checkpoints lets you register a rule that tracks signup events and schedules a welcome email 30 minutes later. Define the rule with factor 'signup' and threshold 1, then use ctx.scheduler.runAfter in your callback to delay the email action.
Register checkpoint rules that monitor specific user activities like post creation or profile completion. When users reach defined thresholds, the component automatically triggers your callback functions to unlock badges, grant credits, or enable features.
Use the HTTP helper to expose checkpoint tracking endpoints for external systems. Configure token-based authentication and accept factor updates via POST requests to /checkpoints/{factor} routes from webhooks or backend jobs.
Convex Checkpoints schedules your app-owned callback function immediately when progress crosses a threshold. The component passes details like userId, factor, and actionName to your internal mutation, where you can write to tables, schedule delayed work, or call other functions.
Yes, Convex Checkpoints supports multiple factors per user. Each factor like 'signup', 'create_post', or 'profile_complete' tracks independently, and users can have progress on multiple rules simultaneously with separate thresholds and actions.
Mutation tracking runs inside your Convex functions with full authentication and validation context. HTTP tracking is for external systems like webhooks that need to report progress server-to-server, requiring token authentication and treating requests as public endpoints.
Import the test component from '@abdssamie/convex-checkpoints/test' and register it with your convex-test instance. This provides the same checkpoint tracking functionality in your test environment for validating rule completion and callback execution.