--- name: bijection-quota description: "Evaluate and integrate the Quota component with Bijection." --- # Quota Scheduled-reset per-subject allowances as a Bijection component — calendar, rolling, or epoch windows with readable remaining - Package: @bijectionhq/quota - Category: Database & Backend - Status: Reference - License: MIT - Bijection source (repository access required): https://github.com/bijectionhq/quota/tree/e15196de18be568ddc4768e831268fc632aa647b - Upstream: https://github.com/vllnt/convex-quota/tree/cbb12fae1feb948461a1936f8fae859d992e4f8c - Documentation: https://docs.bijection.com/components/using - Directory: https://bijection.com/components/quota ## Get the source Bijection repository access is required. Request access at https://bijection.com/contact. ```sh git clone https://github.com/bijectionhq/quota.git cd quota git checkout e15196de18be568ddc4768e831268fc632aa647b ``` ## 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-quota. 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 Quotas. Follow the installation and configuration steps exactly. # Quotas ## Instructions Use Quotas to track per-subject usage allowances with calendar, rolling, or epoch reset windows in convex, including timezone-aware daily/weekly/monthly caps. This Convex component integrates directly with your backend. ### Installation ```bash npm install @vllnt/convex-quota ``` Current npm version: `@vllnt/convex-quota@0.1.0-canary.0` ### Capabilities - Read remaining allowance, used amount, and exact reset time from a single query without maintaining separate counter tables - Enforce calendar-aligned quotas in any IANA timezone so reset windows match user-local days, weeks, or months - Isolate quota namespaces per tenant or product using mounts and scopes without schema conflicts - Refund consumed allowance after failed operations via a privileged mutation, keeping usage counts accurate ## Examples ### how to add daily usage limits with timezone reset in Convex Use @vllnt/convex-quota and call quota.consume(ctx, subjectRef, key, limit, { kind: 'calendar', period: 'day', timeZone: 'America/New_York' }) inside a Convex mutation. The component tracks used and remaining amounts and returns resetsAt so you can display the next reset time. Window math runs server-side, so client clock skew cannot affect the period. ### how to show remaining AI tool quota and reset time in a Convex app Call quota.remaining(ctx, subjectRef, key, limit, window) from a Convex query to get { used, remaining, limit, periodKey, resetsAt }. Expose this through your own host query to the frontend. Note that time passing alone does not invalidate a Convex subscription, so treat resetsAt as an expiry hint and recheck server time on each consume. ### how to cap SaaS feature usage per workspace per month in Convex Pass a workspace identifier as the subjectRef and a feature name as the key to quota.consume, with { kind: 'calendar', period: 'month', timeZone } as the window policy. Use the scope parameter to namespace multiple products within the same mount. Keep the window policy fixed for each (scope, subjectRef, key) triple; changing policy for an existing key throws POLICY_MISMATCH. ### how to refund quota after a failed operation in Convex Call quota.refund(ctx, subjectRef, key, amount, periodKey, scope) inside a privileged Convex mutation after confirming the failure. The refund mutation is not idempotent, so the host must deduplicate refund events in its own transaction using periodKey as a window label. Auth and deduplication are the host's responsibility, not the component's. ## 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 Quotas is not needed ## Troubleshooting **What is the difference between @vllnt/convex-quota and @convex-dev/rate-limiter?** @convex-dev/rate-limiter covers general request throttling with fixed windows, token buckets, readable status, and React hooks. @vllnt/convex-quota focuses on the narrower use case of calendar-aligned, timezone-aware reset windows and a privileged refund surface for adjusting allowances after failed operations. The README explicitly recommends using the official rate-limiter for general throttling. **What window types does @vllnt/convex-quota support?** @vllnt/convex-quota supports three window kinds: calendar windows (day, week, or month aligned to an IANA timezone), rolling windows that start from the first allowed consume, and epoch windows computed as floor(now / durationMs). The window policy for a given (scope, subjectRef, key) combination must remain stable; changing it throws a POLICY_MISMATCH error. **Is consume idempotent in @vllnt/convex-quota?** No. quota.consume is not idempotent. If your mutation retries due to Convex OCC conflicts, each successful execution will consume allowance. The README recommends wrapping retried operations with @vllnt/convex-idempotency to avoid double-counting. Never pass limit or amount values from the end-user; the host must supply them. **How do you isolate quotas for multiple tenants or products in the same Convex app?** @vllnt/convex-quota supports two isolation mechanisms. Multiple mounts (app.use(quota, { name: 'webQuota' })) give each mount its own sandboxed database tables. Within a single mount, the scope parameter namespaces records at runtime, which is useful for separating tenants or product lines without separate deployments. **Does @vllnt/convex-quota handle authentication or billing?** @vllnt/convex-quota is auth-agnostic. The host resolves identity and passes an opaque subjectRef string to the component. The component does not implement billing metering, persistent balances, or purchased reset credits. Any auth checks, purchased allowance systems, or audit logging must be implemented in the host application. ## Resources - [npm package](https://www.npmjs.com/package/%40vllnt%2Fconvex-quota) - [GitHub repository](https://github.com/vllnt/convex-quota) - [Live demo](https://github.com/vllnt/convex-quota/tree/main/example) - [Convex Components Directory](https://www.convex.dev/components/vllnt/convex-quota) - [Convex documentation](https://docs.convex.dev)