README

Backend SDK for tracking AI usage and blocking AI calls when a Fuseboxie guard rule says no.

Install

composer require fuseboxie/sdk

Usage

Initialize the SDK once in your PHP backend:

<?php

use function Fuseboxie\init;

$fuseboxie = init([
    'projectKey' => getenv('FUSEBOXIE_PROJECT_KEY'),
    'apiUrl' => getenv('FUSEBOXIE_API_URL') ?: 'https://api.fuseboxie.com',
    'guardFailureMode' => 'throw',
]);

On Windows PHP installs that do not have a default CA bundle configured, pass one explicitly:

$fuseboxie = init([
    'projectKey' => getenv('FUSEBOXIE_PROJECT_KEY'),
    'apiUrl' => 'https://api.fuseboxie.com',
    'caBundlePath' => 'C:\\Program Files\\Git\\mingw64\\etc\\ssl\\certs\\ca-bundle.crt',
]);

Guard before the AI provider call:

$decision = $fuseboxie->canUseAI([
    'userId' => 'user_123',
    'customerId' => 'customer_123',
    'role' => 'trial',
    'estimatedTokens' => 2000,
    'estimatedCostUsd' => 0.02,
    'operation' => 'chat.completion',
]);

if (!$decision['allowed']) {
    throw new RuntimeException($decision['reason'] ?? 'AI usage is blocked.');
}

Track after the provider returns:

$response = $openai->chat()->create([...]);

$fuseboxie->trackOpenAI($response, [
    'userId' => 'user_123',
    'customerId' => 'customer_123',
    'role' => 'trial',
    'operation' => 'chat.completion',
]);

Provider helpers:

• trackOpenAI($response, $context) maps usage.prompt_tokens, usage.completion_tokens, usage.total_tokens, and the newer usage.input_tokens / usage.output_tokens shape.
• trackAnthropic($response, $context) maps usage.input_tokens and usage.output_tokens.
• trackGemini($response, $context) maps usageMetadata.promptTokenCount, usageMetadata.candidatesTokenCount, and usageMetadata.totalTokenCount.

You can also call trackUsage() manually when you already have normalized token counts:

$fuseboxie->trackUsage([
    'provider' => 'openai',
    'model' => 'gpt-4.1-mini',
    'inputTokens' => 1200,
    'outputTokens' => 420,
    'userId' => 'user_123',
    'customerId' => 'customer_123',
    'role' => 'trial',
    'operation' => 'chat.completion',
]);

Laravel

The package auto-discovers a Laravel service provider and facade when installed in a Laravel app.

Publish the config file:

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

Set your server-side environment values:

FUSEBOXIE_PROJECT_KEY=pk_live_...
FUSEBOXIE_API_URL=https://api.fuseboxie.com
FUSEBOXIE_GUARD_FAILURE_MODE=throw

Add the middleware to routes that make AI calls. It captures the signed-in Laravel user ID and optional customer/role/request headers, then reuses them for every Fuseboxie call in that request:

use Fuseboxie\Laravel\Middleware\FuseboxieContext;

Route::middleware([FuseboxieContext::class])->post('/chat', ChatController::class);

Use the facade in your controller:

use Fuseboxie\Laravel\Facades\Fuseboxie;

$decision = Fuseboxie::canUseAI([
    'estimatedTokens' => 2000,
    'estimatedCostUsd' => 0.02,
    'operation' => 'chat.completion',
]);

if (!$decision['allowed']) {
    abort(402, $decision['reason'] ?? 'AI usage is blocked.');
}

$response = $openai->chat()->create([...]);

Fuseboxie::trackOpenAI($response, [
    'operation' => 'chat.completion',
]);

If your app stores tenant/customer IDs somewhere else, pass them directly in the guard/tracking arrays or customize the middleware header names in config/fuseboxie.php.

Checks

composer install
composer test

The SDK has no runtime dependencies beyond PHP JSON support. It uses cURL when available and falls back to PHP streams.