Entitlements & Usage Service

System Overview

The Entitlements service acts as the central brain for your application's monetization. It decouples feature availability from your business logic, allowing product managers to update plans and limits in YAML without code redeploys.

Getting Started & Local Dev

# 1. Start Infrastructure (PostgreSQL + Redis + NATS)
docker-compose up -d

# 2. Sync Policies & Run Server
make run

Feature Catalog (features.yaml)

The Feature Dictionary defines the global schema. It describes what a feature is, but not its specific limit (which happens in plans).

version: 1

features:
  - key: "automation.runs"
    namespace: "automations"
    type: "INT"           # Supported: TOGGLE, INT, DECIMAL, STRING, JSON
    scope: "COMPANY"      # COMPANY, TEAM, USER, GLOBAL
    default_aggregation_period: "MONTH"
    display_name: "Monthly Automation Runs"
    metadata:
      unit: "runs"
      ui_group: "Usage Metrics"

  - key: "ai.advanced_model"
    type: "TOGGLE"
    scope: "USER"
    display_name: "Access to Claude 3.5 / GPT-4o"

Plan Definitions (plans.yaml)

Plans bundle features from the catalog and assign Monetization Bounds specifically given to specific tiers.

plans:
  - id: "pro-monthly"
    code: "pro"
    name: "Professional"
    default_billing_period: "MONTHLY"
    metadata:
      price_monthly: 29.00
      marketing_label: "Most Popular"

    features:
      - feature_key: "automation.runs"
        value: { int_value: 5000 }
        is_hard_limit: true
        enforcement: "BLOCK"

      - feature_key: "storage.gb"
        value: { decimal_value: 50.0 }
        is_hard_limit: true
        enforcement: "BLOCK"

      - feature_key: "ai.advanced_model"
        value: { bool_value: true }

Frontend Integration

Use the generated ConnectRPC clients to drive your UI logic based on entitlements.

Fetching Effective Features

Load all permitted capabilities for a company on application boot.

const response = await subClient.getEffectiveFeaturesForSubject({
  subject: { type: SubjectType.COMPANY, id: companyId }
});

// Convert to a lookup map for easy UX logic
const featureMap = new Map(response.features.map(f => [f.featureKey, f]));

Usage & Limit Checks

Perform a dry-run limit check before allowing users to perform costly actions.

const res = await usageClient.checkLimit({
  subject: { type: SubjectType.COMPANY, id: companyId },
  featureKey: "storage.gb_used",
  delta: 1n // Check if can add 1 more unit
});

if (!res.allowed) {
  showUpgradeModal();
}

Building Limit-Aware UI

Avoid "Post-mortems": Never let an API request fail due to a limit before you've warned the user. Use isHardLimit to drive button states and progress bars.