Documentation Index
Fetch the complete documentation index at: https://grantmaster.dev/llms.txt
Use this file to discover all available pages before exploring further.
Quota Service Reference
Source: src/shared/billing/QuotaService.ts
Enforces seat-based and feature-based quotas at the data layer. Prevents quota bypass by validating all create operations before writes.
Architecture:
- Called automatically by
BaseService.validateQuota() before create operations
- Emits
QUOTA_EXCEEDED events for analytics and notification workflows
- Emits
QUOTA_WARNING events at 80% and 90% thresholds
- Provides upgrade suggestions when quotas are exceeded
- Tracks usage metrics in real-time
Quick Example
import { quotaService } from '@/shared/billing/QuotaService';
const quotaCheck = await quotaService.checkQuota({
organizationId: 'org-123',
resourceType: 'users',
action: 'create',
additionalCount: 1,
});
if (!quotaCheck.allowed) {
// quotaCheck.reason contains user-friendly message
// quotaCheck.suggestedTier contains next tier recommendation
throw new BusinessLogicError(quotaCheck.reason);
}
Types
ResourceType
Billable resource categories tracked by the quota system. Each value maps to a corresponding field in Organization.usageMetrics and a limit defined per SubscriptionTier in TIER_LIMITS.
type ResourceType =
| 'users' // Team member seats
| 'projects' // Active projects
| 'storage' // Storage in GB
| 'ai_generations' // Gemini AI generations per month
| 'agent_credits' // Agent credits per month
| 'agent_runs'; // Agent runs per month
QuotaCheckRequest
Input for quotaService.checkQuota().
| Field | Type | Required | Description |
|---|
organizationId | string | Yes | Tenant isolation key |
resourceType | ResourceType | Yes | The billable resource to check |
action | 'create' | 'update' | Yes | 'create' enforces limit; 'update' always passes |
additionalCount | number | No | How many new resources are being created (default: 1) |
QuotaCheckResponse
Result returned by quotaService.checkQuota().
| Field | Type | Description |
|---|
allowed | boolean | true if the requested action is within quota |
reason | string? | Human-readable explanation when allowed is false |
limit | number | Maximum allowed for this resource (or -1 for unlimited) |
current | number | Current usage count before the requested action |
available | number | Remaining capacity after the requested action (or -1 for unlimited) |
requiresUpgrade | boolean? | true when the only way to proceed is to upgrade the subscription |
suggestedTier | SubscriptionTier? | Next tier that would accommodate the request, if applicable |
percentageUsed | number | Usage as a percentage of the limit (0-100) |
Methods
checkQuota()
Check if an organization can perform an action based on subscription quotas.
checkQuota(request: QuotaCheckRequest): Promise<QuotaCheckResponse>
- Fetches the organization document with subscription details
- Determines the resource limit from
subscription.features or TIER_LIMITS
- Calculates available capacity
- For
'create' actions: validates additionalCount <= available
- For
'update' actions: always returns allowed: true
- Emits
QUOTA_EXCEEDED event if denied
- Checks warning thresholds (80%, 90%) and emits
QUOTA_WARNING if crossed
Throws: NotFoundError — If organization not found.
Resource limit sources:
| Resource | Limit Source | Usage Source |
|---|
users | subscription.seats.total (or features.maxUsers) | usageMetrics.activeUsers |
projects | features.maxProjects | usageMetrics.totalProjects |
storage | features.storageGB | usageMetrics.storageUsedGB |
ai_generations | features.aiGenerationsPerMonth | usageMetrics.aiGenerationsThisMonth |
agent_credits | features.agentCreditsPerMonth | usageMetrics.agentCreditsUsedThisMonth |
agent_runs | TIER_LIMITS[tier].maxAgentRunsPerMonth | usageMetrics.agentRunsThisMonth |
incrementUsage()
Increment usage counter after a successful operation. Non-blocking — failures are logged to Sentry but don’t break the operation.
incrementUsage(
organizationId: string,
resourceType: ResourceType,
amount?: number
): Promise<void>
| Param | Type | Description |
|---|
organizationId | string | Organization ID |
resourceType | ResourceType | Type of resource |
amount | number | Amount to increment (default: 1) |
decrementUsage()
Decrement usage counter (for deletions/deactivations). Non-blocking — failures are logged to Sentry but don’t break the operation.
decrementUsage(
organizationId: string,
resourceType: ResourceType,
amount?: number
): Promise<void>
| Param | Type | Description |
|---|
organizationId | string | Organization ID |
resourceType | ResourceType | Type of resource |
amount | number | Amount to decrement (default: 1) |
Warning Thresholds
The service emits QUOTA_WARNING events when usage crosses 80% or 90% of a resource limit. Warnings are emitted only once per threshold crossing (i.e., going from 79% to 80% triggers a warning, but 80% to 81% does not).
Tier progression for upgrade suggestions:
POTENTIAL -> PROFESSIONALPROFESSIONAL -> ULTIMATEULTIMATE -> undefined (contact support for enterprise)
Singleton Export
import { quotaService } from '@/shared/billing/QuotaService';
QuotaService singleton using default logger, EventBus, and time provider.
