feat(billing): add useQuota composable for plan-based feature gating

[PierreBrisorgueil]

Summary

• Add fetchUsage() store action calling GET /billing/usage and storing quota data (plan, period, usage, limits)
• Create useQuota composable with canDo(resource, action) and usagePercent(resource, action) helpers for plan-based feature gating
• Add 20 unit tests covering store action, canDo logic (under/at/over limit, Infinity, undefined, null), usagePercent (correct %, cap at 100, edge cases), refresh, and computed defaults

Test plan

• npx eslint passes on all changed files
• All 20 new unit tests pass
• Full test suite (675 tests) passes with no regressions

Closes #3739

Summary by CodeRabbit

• New Features

  • Added quota management functionality to check if users can perform actions based on their billing limits.
  • Added usage tracking that displays resource consumption as a percentage of allocated limits.
  • Added ability to refresh quota and usage information on-demand.

• Tests

  • Added comprehensive unit tests for quota management features.

[coderabbitai]

Warning

Rate limit exceeded

@PierreBrisorgueil has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 20 minutes and 2 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 3a0d3820-a067-4644-ae1a-7a1dbace5d67

📥 Commits

Reviewing files that changed from the base of the PR and between 952c270 and 3777dc0.

📒 Files selected for processing (2)

• src/modules/billing/composables/billing.useQuota.js
• src/modules/billing/tests/billing.useQuota.unit.tests.js

Walkthrough

Added a new Vue composable useQuota that provides quota checking and usage percentage computation for billing-based feature gating. The composable integrates with the billing store, which now includes a new quota state property and a fetchUsage() action that fetches quota data from the billing usage endpoint.

Changes

Cohort / File(s)	Summary
Billing Quota Composable & Store src/modules/billing/composables/billing.useQuota.js, src/modules/billing/stores/billing.store.js	New composable exports reactive plan, period, usage, limits computed properties; canDo(resource, action) method returns true when limit is missing, null, or Infinity; usagePercent(resource, action) computes 0–100 percentage with clamping; refresh() triggers fetchUsage(). Store now includes quota state and async fetchUsage() action that GET-requests /api/billing/usage endpoint.
Billing Quota Tests src/modules/billing/tests/billing.useQuota.unit.tests.js	Comprehensive unit tests validating fetchUsage() endpoint behavior, quota data persistence, error handling with loading state reset, canDo() logic across under/at/over-limit states, usagePercent() percentage computation with edge cases (Infinity, null, undefined), integer rounding, and computed property defaults when quota is null.

Sequence Diagram

sequenceDiagram
    actor User
    participant Component as Vue Component
    participant Composable as useQuota()
    participant Store as useBillingStore
    participant API as Billing API

    User->>Component: Use composable to check quota
    Component->>Composable: Call refresh()
    Composable->>Store: Call fetchUsage()
    Store->>Store: Set loading = true
    Store->>API: GET /api/billing/usage
    API-->>Store: Return quota data
    Store->>Store: Store quota in state
    Store->>Store: Set loading = false
    Store-->>Composable: Return quota
    Composable-->>Component: Update computed values
    Component->>Composable: Call canDo(resource, action)
    Composable-->>Component: Return boolean (based on limits vs usage)
    Component->>Composable: Call usagePercent(resource, action)
    Composable-->>Component: Return 0–100 percentage

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• #3740 — Dependent feature for displaying billing usage bars and upgrade prompts relies on the quota data and helper functions introduced in this PR.

Possibly related PRs

• #3723 — Introduces the initial billing store scaffold that this PR extends with quota state and fetchUsage() action.

Suggested labels

billing

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding a useQuota composable for plan-based feature gating, which is the primary objective of this pull request.
Description check	✅ Passed	The description covers the main changes, includes a test plan with verification checkmarks, and references the closed issue. However, it deviates from the template by omitting several required sections like Scope, Validation checklist, and Guardrails.
Linked Issues check	✅ Passed	The PR successfully implements all requirements from issue #3739: adds fetchUsage() action, useQuota composable with canDo() and usagePercent(), exposes usage/limits/plan/period, and includes 20 unit tests covering all specified scenarios.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing the useQuota composable and supporting infrastructure (store action and unit tests). No unrelated modifications are present.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/billing-use-quota

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.19%. Comparing base (8203f2c) to head (3777dc0).
⚠️ Report is 3 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #3743   +/-   ##
=======================================
  Coverage   99.18%   99.19%           
=======================================
  Files          26       26           
  Lines         863      873   +10     
  Branches      223      223           
=======================================
+ Hits          856      866   +10     
  Misses          7        7           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

Adds quota/usage support to the billing module so downstream projects can gate UI features based on plan limits via a dedicated composable backed by a store action.

Changes:

• Added fetchUsage() action to the billing Pinia store to fetch and cache quota usage/limits data from the billing API.
• Introduced useQuota() composable to expose plan, period, usage, limits, plus canDo() and usagePercent() helpers and a refresh() method.
• Added unit tests covering the store fetch and composable quota calculations/defaults.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
src/modules/billing/stores/billing.store.js	Adds quota state and fetchUsage() action to retrieve and store usage/limits data.
src/modules/billing/composables/billing.useQuota.js	New composable providing quota gating helpers and accessors backed by the billing store.
src/modules/billing/tests/billing.useQuota.unit.tests.js	New unit tests for fetchUsage, canDo, usagePercent, refresh, and computed defaults.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/modules/billing/composables/billing.useQuota.js`:
- Around line 43-45: The usagePercent() function treats falsy limits the same as
"no limit", so a limit of 0 incorrectly returns 0% while canDo() treats 0 as
blocking; update usagePercent() to explicitly handle limit === 0 by returning
100 (or another value consistent with canDo's semantics) before the no-limit
check (i.e., check if limit === 0 first), then keep the existing branch for
limit === Infinity or undefined; reference the usagePercent() function, the
limit variable, usage.value[key], and canDo() to ensure consistent behavior
across both functions.

In `@src/modules/billing/tests/billing.useQuota.unit.tests.js`:
- Around line 121-176: Add a regression test to the existing
describe('usagePercent') block to cover the case when a resource limit equals 0:
set store.quota with usage e.g. { 'documents.create': 1 } and limits {
'documents.create': 0 }, call usagePercent('documents', 'create') and assert it
returns 0; place the new it(...) alongside the other tests so usagePercent is
exercised for the zero-limit edge case.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: f496d4c8-1ef5-447e-9f9d-ff627ff6ea21

📥 Commits

Reviewing files that changed from the base of the PR and between d591112 and 952c270.

📒 Files selected for processing (3)

• src/modules/billing/composables/billing.useQuota.js
• src/modules/billing/stores/billing.store.js
• src/modules/billing/tests/billing.useQuota.unit.tests.js