README

Usage metering, quotas, and billing for AI applications.

A production-ready Laravel package that automatically tracks AI usage, enforces quotas, and integrates with Stripe for billing. Perfect for SaaS applications that need to meter and bill AI usage.

Features
Why Choose This Package?
Requirements
Quick Start
- Installation
- Usage Example
Documentation
Quick Links
Contributing
License
Support

Features

🎯 Simple Developer Experience - Fluent API for metering AI usage
📊 Usage Tracking - Automatic token and cost tracking
🚦 Quota Management - Configurable limits (tokens, cost, per-plan, per-tenant)
💳 Billing Integration - Stripe/Cashier support with credit-based and subscription modes
🏢 Multi-Tenancy - Works with or without tenancy packages
🔌 Provider Agnostic - Support for OpenAI, Anthropic, and custom providers
⚡ Performance - Caching, queue support, and optimized queries

Why Choose This Package?

Zero Configuration Required - Start tracking usage immediately, no plans or subscriptions needed
Production Ready - Battle-tested with comprehensive test coverage and security features
Automatic Processing - Automatic usage extraction, cost calculation, and billing integration
Flexible Billing - Support for both subscription-based and credit-based billing models
Multi-Tenant Ready - Built-in support for multi-tenant applications without coupling to specific packages
Extensible - Easy to add custom providers, billing drivers, and tenant resolvers
Well Documented - Comprehensive documentation with examples and troubleshooting guides

Requirements

PHP >= 8.1 (PHP >= 8.2 for Laravel 11.x and 12.x)
Laravel 10.x, 11.x, or 12.x
Database (MySQL, PostgreSQL, SQLite, or SQL Server)

Version Compatibility

Laravel Version	PHP Version	Package Version	Status
10.x	>= 8.1	^1.0	✅ Supported
11.x	>= 8.2	^1.0	✅ Supported
12.x	>= 8.2	^1.0	✅ Supported

Optional Dependencies

OpenAI: openai-php/laravel (for OpenAI provider)
Anthropic: anthropic-php/sdk (for Anthropic provider)
Stripe/Cashier: laravel/cashier (for Stripe billing integration)

Quick Start

Note: This package supports Laravel Package Auto-Discovery, so you do not need to manually register the service provider.

Installation

# 1. Install the package
composer require ajooda/laravel-ai-metering

# 2. Publish and run migrations
php artisan vendor:publish --tag=ai-metering-migrations
php artisan migrate

# 3. Verify installation
php artisan ai-metering:validate

Usage Example

Full Example - Complete usage with all options:

use Ajooda\AiMetering\Facades\AiMeter;
use OpenAI\Laravel\Facades\OpenAI;

$response = AiMeter::forUser(auth()->user())
    ->billable(auth()->user())
    ->usingProvider('openai', 'gpt-4o-mini')
    ->feature('chat')
    ->call(function () {
        return OpenAI::chat()->create([
            'model' => 'gpt-4o-mini',
            'messages' => [
                ['role' => 'user', 'content' => 'Hello!'],
            ],
        ]);
    });

// Access the AI response
$aiResponse = $response->getResponse();

// Check usage
$usage = $response->getUsage();
echo "Tokens: {$usage->totalTokens}, Cost: \${$usage->totalCost}";

Minimal Example - Just track usage:

use Ajooda\AiMetering\Facades\AiMeter;

$response = AiMeter::forUser(auth()->user())
    ->billable(auth()->user())
    ->usingProvider('openai', 'gpt-4o-mini')
    ->call(fn() => OpenAI::chat()->create([...]));

$usage = $response->getUsage();

That's it! Usage is automatically tracked. No plans or subscriptions required for basic tracking.

Documentation

Comprehensive documentation is available in the docs/ directory:

Overview - What this package does and when to use it
Installation - Detailed installation and setup guide
Configuration - All configuration options explained
Usage Guide - Common usage flows and examples
Features - Detailed feature documentation
- Plans & Quotas - Setting up usage limits
- Credits - Credit-based billing
- Billing Integration - Stripe/Cashier integration
- Multi-Tenancy - Multi-tenant usage tracking
- Periods - Period configuration
Advanced Topics - Extensibility, customization, events, hooks
API Reference - Complete API documentation
Troubleshooting - Common issues and solutions

Quick Links

Common Tasks

Artisan Commands

# Generate usage report
php artisan ai-metering:report

# Cleanup old usage records
php artisan ai-metering:cleanup

# Sync Stripe overages
php artisan ai-metering:sync-stripe-overages

# Validate configuration
php artisan ai-metering:validate

# Migrate plan
php artisan ai-metering:migrate-plan "App\Models\User" 1 "pro-plan"

# List plans
php artisan ai-metering:sync-plans

See API Reference for complete command documentation.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Quick Start for Contributors

Fork and clone the repository:

git clone https://github.com/ajooda/laravel-ai-metering.git
cd laravel-ai-metering

Install dependencies:
```
composer install
```
Run tests:
```
composer test
```
Run tests with coverage:
```
composer test-coverage
```

See CONTRIBUTING.md for detailed guidelines.

License

The MIT License (MIT). Please see LICENSE for more information.

Support

Getting Help

🐛 Bug Reports: Open an issue
💬 Questions: GitHub Discussions
📖 Documentation: Full Documentation
🔒 Security Issues: Email abdalhadijouda@gmail.com or see SECURITY.md

Maintainers

Primary Maintainer: AbdAlhadi Jouda (abdalhadijouda@gmail.com)

Response Times:

Security vulnerabilities: 48 hours initial response
Bug reports: 3-5 business days
Questions: 5-7 business days
Feature requests: As time permits

ajooda / laravel-ai-metering

Maintainers

Package info

Statistics

Security

README

Table of Contents

Features

Why Choose This Package?

Requirements

Version Compatibility

Optional Dependencies

Quick Start

Installation

Usage Example

Documentation

Quick Links

Common Tasks

Artisan Commands

Contributing

Quick Start for Contributors

License

Support

Getting Help

Maintainers