---
name: bijection-abdssamie-convex-checkpoints
description: "Evaluate and integrate the Convex Checkpoints component with Bijection."
---

# Convex Checkpoints

Define user checkpoints and trigger actions when activity thresholds are met

This is an upstream package. It has not been adapted or qualified for Bijection.

- Package: @abdssamie/convex-checkpoints
- Source: https://github.com/Abdssamie/convex-checkpoints
- npm: https://www.npmjs.com/package/%40abdssamie%2Fconvex-checkpoints
- Directory: https://bijection.com/components/abdssamie-convex-checkpoints

Read the upstream README for setup, license, and compatibility before using it.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @abdssamie/convex-checkpoints. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


# Convex Checkpoints

## Instructions

Use Convex Checkpoints to define milestone rules for user activity and trigger automated actions when thresholds are met in convex applications. This Convex component integrates directly with your backend.

### Installation

```bash
npm install @abdssamie/convex-checkpoints
```

### Capabilities

- Track user progress across multiple activities with automatic threshold detection
- Trigger custom actions when milestones are reached without manual polling
- Separate business logic from progress tracking with component-owned rule configuration
- Handle delayed actions with built-in scheduler integration for timed workflows

## Examples

### how to send welcome email after user signup delay

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.

### track user milestones and unlock features

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.

### webhook integration user progress tracking

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.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Convex Checkpoints is not needed

## Troubleshooting

**How does Convex Checkpoints handle rule completion callbacks?**

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.

**Can I track multiple activities for the same user?**

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.

**What's the difference between tracking in mutations vs HTTP endpoints?**

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.

**How do I test components that use Convex Checkpoints?**

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.

## Resources

- [npm package](https://www.npmjs.com/package/%40abdssamie%2Fconvex-checkpoints)
- [GitHub repository](https://github.com/Abdssamie/convex-checkpoints)
- [Live demo](https://convex-checkpoints-demo.pages.dev)
- [Convex Components Directory](https://www.convex.dev/components/abdssamie/convex-checkpoints)
- [Convex documentation](https://docs.convex.dev)