README

The official Laravel SDK for Volta — AI billing, handled.

Requirements

• PHP 8.2+
• Laravel 10, 11, or 12

Installation

composer require darknautica/volta-php

Publish the config:

php artisan vendor:publish --tag=volta-config

Add to your .env:

VOLTA_APP_KEY=your-app-key-here
VOLTA_BASE_URL=https://volta.test

Quick Start

Three lines to add billing to any AI endpoint:

use DarkNautica\Volta\Facades\Volta;

// Check before calling AI
if (!Volta::hasAccess($user->id)) {
    return response()->json(['error' => 'Insufficient credits'], 402);
}

// Make your AI call here...

// Deduct after success
Volta::charge($user->id, 1);

Middleware

Protect entire routes automatically:

// Requires 1 credit (default)
Route::post('/generate', [AIController::class, 'generate'])
    ->middleware('volta.gate');

// Requires 3 credits, specific model
Route::post('/analyze', [AIController::class, 'analyze'])
    ->middleware('volta.gate:3,gpt-4');

The middleware resolves the user automatically:

1. $request->volta_user_id if set explicitly
2. $request->user()->id if authenticated
3. Falls back to request IP for anonymous users

Blade Directives

{{-- Show balance --}}
<span>@voltaBalance($user->id) credits remaining</span>

{{-- Conditional content --}}
@voltaHasAccess($user->id, 1)
    <button>Generate</button>
@endvoltaHasAccess

@voltaNoAccess($user->id, 1)
    <a href="/billing">Buy more credits</a>
@endvoltaNoAccess

{{-- Embed billing portal --}}
<iframe src="@voltaPortalUrl($user->id)" width="100%" height="600"></iframe>

Available Methods

Testing Connection

php artisan volta:test

This will verify your API key, test connectivity, and display account info.

Error Handling

use DarkNautica\Volta\Exceptions\InsufficientCreditsException;
use DarkNautica\Volta\Exceptions\RateLimitExceededException;

try {
    Volta::charge($user->id, 1);
} catch (InsufficientCreditsException $e) {
    return response()->json(['error' => 'Not enough credits'], 402);
} catch (RateLimitExceededException $e) {
    return response()->json(['error' => 'Slow down', 'retry_after' => $e->retryAfter], 429);
}

Fail Silently Mode

Set VOLTA_FAIL_SILENTLY=true in .env to prevent Volta errors from crashing your app. When enabled:

• hasAccess() returns false
• balance() returns 0
• charge() returns false

This is useful for apps that should degrade gracefully if Volta is unreachable.

Configuration

License

MIT