--- name: bijection-progression description: "Evaluate and integrate the Progression component with Bijection." --- # Progression XP, levels, and streak windows as a Bijection component - Package: @bijectionhq/progression - Category: Database & Backend - Status: Preview - License: MIT - Bijection source (repository access required): https://github.com/bijectionhq/progression/tree/3eaf964d67883935ad463f354a20a7b8ea5ab70f - Upstream: https://github.com/vllnt/convex-progression/tree/687bbeb1454d62d1e2bdb111d4544eead212e0f7 - Documentation: https://docs.bijection.com/components/using - Directory: https://bijection.com/components/progression ## Get the source Bijection repository access is required. Request access at https://bijection.com/contact. ```sh git clone https://github.com/bijectionhq/progression.git cd progression git checkout 3eaf964d67883935ad463f354a20a7b8ea5ab70f ``` ## Before using this component Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute. ## 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 @vllnt/convex-progression. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately. > Agents: read this skill fully before writing code that uses Progression. Follow the installation and configuration steps exactly. # Progression ## Instructions Use Progression to convex component that tracks cumulative xp, threshold-based levels, and activity streaks with host-controlled rules and no embedded domain logic. This Convex component integrates directly with your backend. ### Installation ```bash npm install @vllnt/convex-progression ``` Current npm version: `@vllnt/convex-progression@0.1.0-canary.0` ### Capabilities - Add points, levels, and streaks to any Convex backend in minutes without designing your own schema or scheduling logic. - Reuse one component across multiple progress tracks by passing opaque subjectRef and key strings scoped per mount. - Recompute levels on read when thresholds change, avoiding backfill migrations when your XP ladder evolves. - Isolate data per feature by mounting the component multiple times with distinct names, each with its own tables and scheduled work. ## Examples ### how to track XP and levels in Convex Install @vllnt/convex-progression and call xp.accrue(ctx, subjectRef, key, delta, thresholds) from any Convex mutation. The component stores cumulative XP and computes the current level by counting how many thresholds that XP has crossed. Thresholds are passed by the host on every write, so the ladder can change without a migration. ### how to track activity streaks in Convex Use xp.recordActivity(ctx, subjectRef, key, periodKey, thresholds, { expectedPrevious }) from @vllnt/convex-progression. Pass the current period key and the expected previous period key; the component continues the streak if they are consecutive or resets it if there is a gap. The host defines what a period means, such as a date string for daily streaks. ### Convex component for onboarding progress and milestones @vllnt/convex-progression supports SaaS onboarding by translating completed setup steps into points via accrue and defining milestone levels through threshold arrays. Each onboarding track can use a separate key or scope, and xp.get returns the current XP, level, streak, and maxStreak without coupling the component to any domain logic. ### how to run multiple independent progress tracks in one Convex app Mount @vllnt/convex-progression multiple times using app.use(progression, { name: 'gameProgress' }) and app.use(progression, { name: 'learningProgress' }) in convex.config.ts. Each mount has isolated tables and its own scheduled work. Construct a separate Progression client for each component reference to keep data fully separated. ## 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 Progression is not needed ## Troubleshooting **Does @vllnt/convex-progression include any UI or React utilities?** @vllnt/convex-progression is a backend-only component with no React entry point. It exposes mutations and a query that your own backend functions call. UI display, streak freeze logic, leaderboard ranking, and reward delivery remain host responsibilities. **How does @vllnt/convex-progression handle changing XP thresholds?** Thresholds are passed by the host on every call rather than stored in the component. When you call xp.get(ctx, subjectRef, key, scope, thresholds) with a revised threshold array, the component recomputes the level from the stored XP against the new ladder. This avoids backfill migrations when your level design changes. **How does @vllnt/convex-progression authenticate users?** @vllnt/convex-progression is auth-agnostic. The host resolves identity through its own auth mechanism and passes an opaque subjectRef string to each method. The component never receives end-user tokens or raw deltas; your backend authorizes every read and write before calling the component. **Can @vllnt/convex-progression delete data for a user who is removed?** Yes. xp.eraseSubject(ctx, subjectRef, scope?, batch?) deletes all records for a subject in bounded batches and reschedules itself until the data is fully removed. This supports GDPR-style deletion without blocking a single mutation for an unbounded amount of time. **What version of Convex does @vllnt/convex-progression require?** @vllnt/convex-progression requires convex@^1.45.0 as a peer dependency and Node.js 20 or later for the development toolchain. It is currently at version 0.1.0 and is described as an unreleased candidate, so check the repository for current publication status before adding it to a production project. ## Resources - [npm package](https://www.npmjs.com/package/%40vllnt%2Fconvex-progression) - [GitHub repository](https://github.com/vllnt/convex-progression) - [Live demo](https://github.com/vllnt/convex-progression/tree/main/example/convex) - [Convex Components Directory](https://www.convex.dev/components/vllnt/convex-progression) - [Convex documentation](https://docs.convex.dev)