feat: Configure AI usage counter

[kofimokome]

Fixes #7

Depends on #10

[sourceant]

Code Review Summary

The PR introduces AI usage tracking and plan entitlements. However, the implementation has critical logic errors in how features are authorized and identified, rendering the entitlement system largely ineffective in its current state.

🚀 Key Improvements

• Configurable AI token allowances across all plan types using environment variables.
• Integration with a central Entitlements contract via a new Service Provider singleton.

💡 Minor Suggestions

• Use Laravel string helpers for more robust parsing.
• Refine the usage reset logic to align with actual billing cycles.

🚨 Critical Issues

• The allows method is a no-op that always permits access, bypassing plan limits.
• The check method incorrectly compares programmatic feature keys against human-readable display strings.

[sourceant]

Review complete. See the overview comment for a summary.

[sourceant]

Review complete. See the overview comment for a summary.

[sourceant]

Review complete. See the overview comment for a summary.

[sourceant]

Review complete. See the overview comment for a summary.

[nfebe]

This looks good but since we have multiple projects that the question of tokens will come up. I built and publish a package that will simplify things there is already a task to implement it in the core and it may remove the need for one table you have here.

See: https://github.com/whilesmartphp/eloquent-agent-metrics

[kofimokome]

@nfebe what's the issue number on trakli core? I can't find it

[nfebe]

I already implemented it so its closed

[sourceant]

Review complete. See the overview comment for a summary.

[nfebe]

There is already a way to measure the usage in core

[nfebe]

Could you add this to the webservice and see how we can eliminate this table?

https://github.com/whilesmartphp/eloquent-agent-metrics

Was this solved?

[kofimokome]

I'm still working on this and the other open pr.

[nfebe]

So I already integrated the metrics tracking in the core : https://github.com/trakli/webservice/blob/dev/composer.json#L26

So you just need to used it and remove the custom tracking tables

[nfebe]

This doesn't load against current dev:

Error: Interface "App\Contracts\Entitlements" not found

Dropping the counter table is addressed, and tokensUsed($periodStart) is the right call on the trait. The rest went stale while the branch was open:

Issue	Where
App\Contracts\Entitlements no longer exists; core gates through Whilesmart\Entitlements\Contracts\Entitlements	removed in trakli/webservice#302
getPlanCode() queries BillingCustomer, which is gone	deleted when #10 merged
Nothing binds CloudEntitlements, so it never runs	binding was in #12
remaining() returns INF on the free plan, so free users get unlimited AI despite CLOUD_PLAN_FREE_TOKEN_ALLOWANCE defaulting to 0	CloudEntitlements::remaining()

Cache and DB are unused imports, and allows() / limit() return allow-all, which would switch the plan gating back off if this bound.

This should be a UsageMeter, not an Entitlements. The allowance belongs to the plan and the meter only counts against it, so the plan lookup, the Cashier query and the freemode branch all move out:

class TokenMeterUsage implements UsageMeter
{
    public function remaining(?Model $owner, string $meter, int|float $allowance): int|float
    {
        if ($meter !== 'ai_tokens' || $owner === null || is_infinite($allowance)) {
            return INF;
        }

        return max(0, $allowance - $owner->tokensUsed(now()->startOfMonth()));
    }

    public function consume(?Model $owner, string $meter, int $amount): void
    {
        // core already records through TokenMeter
    }
}

That needs plans carrying meters.ai_tokens, which is in feat/entitlement-rewired. Rebase onto that once it merges and this is the class above plus a binding.

[kofimokome]

@nfebe are we taking away the cloudplans.php config?

I see that most of the information in the config is in the Eloquent Entitlements plans table

[sourceant]

Review complete. See the overview comment for a summary.

[sourceant]

The allows method is currently hardcoded to return true, which bypasses all plan-based feature restrictions. This should delegate to the check method to ensure that entitlements are properly enforced across the application.

Suggested change

	public function allows(?Model $owner, string $feature): bool
	public function allows(?Model $owner, string $feature): bool
	{
	return $this->check($owner, $feature)->allowed();
	}

[sourceant]

The features array in config/cloudplans.php contains human-readable strings for the UI (e.g., 'Up to 3 wallets'). Checking for a programmatic feature key (like 'ai_chat') against this array will always fail. You should introduce a machine-readable permissions array in the config or map feature keys to these strings.

Suggested change

	// Check if the feature is listed in the plan's features or permissions
	// Suggested: Use a dedicated permissions array for programmatic keys
	$permissions = $plan['permissions'] ?? [];
	if ($plan && in_array($feature, $permissions, true)) {
	return AccessResult::allow($feature);
	}

[sourceant]

Determining the plan code by splitting the key string is brittle. If a plan key doesn't follow the exact prefix-suffix format (e.g., a three-part key), this logic might return an incorrect value. Consider using a more robust mapping or Laravel's Str::before helper.

Suggested change

	return explode('-', $subscription->plan->key)[0]; // gets monthly from monthly-eu
	return (string) \Illuminate\Support\Str::before($subscription->plan->key, '-');