Entitlement System

The entitlement system controls feature access, usage limits, and billing integration for workspaces and namespaces.

Quick Start

Check Feature Access

use Core\Tenant\Services\EntitlementService;

$entitlements = app(EntitlementService::class);

// Check if workspace can use a feature
$result = $entitlements->can($workspace, 'ai.credits', quantity: 5);

if ($result->isAllowed()) {
    // Perform action
    $entitlements->recordUsage($workspace, 'ai.credits', quantity: 5, user: $user);
} else {
    // Handle denial
    return response()->json([
        'error' => $result->reason,
        'limit' => $result->limit,
        'used' => $result->used,
    ], 403);
}

Via Workspace Model

$result = $workspace->can('social.accounts');

if ($result->isAllowed()) {
    $workspace->recordUsage('social.accounts');
}

Concepts

Features

Features are defined in the entitlement_features table:

Field	Description
code	Unique identifier (e.g., ai.credits, social.accounts)
type	boolean, limit, or unlimited
reset_type	none, monthly, or rolling
rolling_window_days	Days for rolling window
parent_feature_id	For hierarchical features (pool sharing)

Feature Types:

Type	Behaviour
boolean	Binary on/off access
limit	Numeric limit with usage tracking
unlimited	Feature enabled with no limits

Reset Types:

Type	Behaviour
none	Usage accumulates forever
monthly	Resets at billing cycle start
rolling	Rolling window (e.g., last 30 days)

Packages

Packages bundle features with specific limits:

// Example package definition
$package = Package::create([
    'code' => 'creator',
    'name' => 'Creator Plan',
    'is_base_package' => true,
    'monthly_price' => 19.99,
]);

// Attach features
$package->features()->attach($aiCreditsFeature->id, ['limit_value' => 100]);
$package->features()->attach($socialAccountsFeature->id, ['limit_value' => 5]);

Workspace Packages

Packages are provisioned to workspaces:

$workspacePackage = $entitlements->provisionPackage($workspace, 'creator', [
    'source' => EntitlementLog::SOURCE_BLESTA,
    'billing_cycle_anchor' => now(),
    'blesta_service_id' => 'srv_12345',
]);

Statuses:

• active - Package is in use
• suspended - Temporarily disabled (e.g., payment failed)
• cancelled - Permanently ended
• expired - Past expiry date

Boosts

Boosts provide temporary limit increases:

$boost = $entitlements->provisionBoost($workspace, 'ai.credits', [
    'boost_type' => Boost::BOOST_TYPE_ADD_LIMIT,
    'limit_value' => 50,
    'duration_type' => Boost::DURATION_CYCLE_BOUND,
]);

Boost Types:

Type	Effect
add_limit	Adds to package limit
enable	Enables boolean feature
unlimited	Makes feature unlimited

Duration Types:

Type	Expiry
cycle_bound	Expires at billing cycle end
duration	Expires after set expires_at
permanent	Never expires

API Reference

EntitlementService

can()

Check if a workspace can use a feature:

public function can(
    Workspace $workspace,
    string $featureCode,
    int $quantity = 1
): EntitlementResult

Returns EntitlementResult with:

• isAllowed(): bool
• isDenied(): bool
• isUnlimited(): bool
• limit: ?int
• used: int
• remaining: ?int
• reason: ?string
• featureCode: string
• getUsagePercentage(): ?float
• isNearLimit(): bool (>80%)
• isAtLimit(): bool (100%)

canForNamespace()

Check entitlement for a namespace with cascade:

public function canForNamespace(
    Namespace_ $namespace,
    string $featureCode,
    int $quantity = 1
): EntitlementResult

Cascade order:

1. Namespace-level packages
2. Workspace pool (if namespace->workspace_id set)
3. User tier (if namespace owned by user)

recordUsage()

Record feature usage:

public function recordUsage(
    Workspace $workspace,
    string $featureCode,
    int $quantity = 1,
    ?User $user = null,
    ?array $metadata = null
): UsageRecord

provisionPackage()

Assign a package to a workspace:

public function provisionPackage(
    Workspace $workspace,
    string $packageCode,
    array $options = []
): WorkspacePackage

Options:

• source - system, blesta, admin, user
• billing_cycle_anchor - Start of billing cycle
• expires_at - Package expiry date
• blesta_service_id - External billing reference
• metadata - Additional data

provisionBoost()

Add a temporary boost:

public function provisionBoost(
    Workspace $workspace,
    string $featureCode,
    array $options = []
): Boost

Options:

• boost_type - add_limit, enable, unlimited
• duration_type - cycle_bound, duration, permanent
• limit_value - Amount to add (for add_limit)
• expires_at - Expiry date (for duration)

suspendWorkspace() / reactivateWorkspace()

Manage workspace package status:

$entitlements->suspendWorkspace($workspace, 'blesta');
$entitlements->reactivateWorkspace($workspace, 'admin');

getUsageSummary()

Get all feature usage for a workspace:

$summary = $entitlements->getUsageSummary($workspace);

// Returns Collection grouped by category:
// [
//   'ai' => [
//     ['code' => 'ai.credits', 'limit' => 100, 'used' => 50, ...],
//   ],
//   'social' => [
//     ['code' => 'social.accounts', 'limit' => 5, 'used' => 3, ...],
//   ],
// ]

Namespace-Level Entitlements

For products that operate at namespace level:

$result = $entitlements->canForNamespace($namespace, 'bio.pages');

if ($result->isAllowed()) {
    $entitlements->recordNamespaceUsage($namespace, 'bio.pages', user: $user);
}

// Provision namespace-specific package
$entitlements->provisionNamespacePackage($namespace, 'bio-pro');

Usage Alerts

The UsageAlertService monitors usage and sends notifications:

// Check single workspace
$alerts = app(UsageAlertService::class)->checkWorkspace($workspace);

// Check all workspaces (scheduled command)
php artisan tenant:check-usage-alerts

Alert Thresholds:

• 80% - Warning
• 90% - Critical
• 100% - Limit reached

Notification Channels:

• Email to workspace owner
• Webhook events (limit_warning, limit_reached)

Billing Integration

Blesta API

External endpoints for billing system integration:

POST /api/entitlements          - Provision package
POST /api/entitlements/{id}/suspend    - Suspend
POST /api/entitlements/{id}/unsuspend  - Reactivate
POST /api/entitlements/{id}/cancel     - Cancel
POST /api/entitlements/{id}/renew      - Renew
GET  /api/entitlements/{id}     - Get details

Cross-App API

For other Host UK services to check entitlements:

GET  /api/entitlements/check    - Check feature access
POST /api/entitlements/usage    - Record usage
GET  /api/entitlements/summary  - Get usage summary

Webhooks

Subscribe to entitlement events:

$webhookService = app(EntitlementWebhookService::class);

$webhook = $webhookService->register($workspace,
    name: 'Usage Alerts',
    url: 'https://api.example.com/hooks/entitlements',
    events: ['limit_warning', 'limit_reached']
);

Available Events:

• limit_warning - 80%/90% threshold
• limit_reached - 100% threshold
• package_changed - Package add/change/remove
• boost_activated - New boost
• boost_expired - Boost expired

Payload Format:

{
  "event": "limit_warning",
  "data": {
    "workspace_id": 123,
    "feature_code": "ai.credits",
    "threshold": 80,
    "used": 80,
    "limit": 100
  },
  "timestamp": "2026-01-29T12:00:00Z"
}

Verification:

$isValid = $webhookService->verifySignature(
    $payload,
    $request->header('X-Signature'),
    $webhook->secret
);

Best Practices

Check Before Action

Always check entitlements before performing the action:

// Bad: Check after action
$account = SocialAccount::create([...]);
if (!$workspace->can('social.accounts')->isAllowed()) {
    $account->delete();
    throw new \Exception('Limit exceeded');
}

// Good: Check before action
$result = $workspace->can('social.accounts');
if ($result->isDenied()) {
    throw new EntitlementException($result->reason);
}
$account = SocialAccount::create([...]);
$workspace->recordUsage('social.accounts');

Use Transactions

For atomic check-and-record:

DB::transaction(function () use ($workspace, $user) {
    $result = $workspace->can('ai.credits', 10);

    if ($result->isDenied()) {
        throw new EntitlementException($result->reason);
    }

    // Perform AI generation
    $output = $aiService->generate($prompt);

    // Record usage
    $workspace->recordUsage('ai.credits', 10, $user, [
        'model' => 'claude-3',
        'tokens' => 1500,
    ]);

    return $output;
});

Cache Considerations

Entitlement checks are cached for 5 minutes. For real-time accuracy:

// Force cache refresh
$entitlements->invalidateCache($workspace);
$result = $entitlements->can($workspace, 'feature');

Feature Code Conventions

Use dot notation for feature codes:

service.feature
service.feature.subfeature

Examples:

• ai.credits
• social.accounts
• social.posts.scheduled
• bio.pages
• analytics.websites

Hierarchical Features

For shared pools, use parent features:

// Parent feature (pool)
$aiCredits = Feature::create([
    'code' => 'ai.credits',
    'type' => Feature::TYPE_LIMIT,
]);

// Child feature (uses parent pool)
$aiGeneration = Feature::create([
    'code' => 'ai.generation',
    'parent_feature_id' => $aiCredits->id,
]);

// Both check against ai.credits pool
$workspace->can('ai.generation'); // Uses ai.credits limit