Refinder Laravel SDK

REFINDER_API_KEY=rfnd_your_api_key_here
REFINDER_BASE_URL=https://api.refinder.ai/api/v1
REFINDER_TIMEOUT=120
REFINDER_RETRIES=2
REFINDER_CACHE_ENABLED=false
REFINDER_CACHE_TTL=60
REFINDER_EVENTS=true

// Basic analysis
$result = Refinder::seo()->basic($content, 'en');

// Advanced analysis (default)
$result = Refinder::seo()->advanced($content, 'en');

// Full technical analysis
$result = Refinder::seo()->technical($content, 'en');

return [
    'api_key'       => env('REFINDER_API_KEY'),
    'base_url'      => env('REFINDER_BASE_URL', 'https://api.refinder.ai/api/v1'),
    'timeout'       => env('REFINDER_TIMEOUT', 120),
    'retries'       => env('REFINDER_RETRIES', 2),
    'retry_delay_ms' => env('REFINDER_RETRY_DELAY', 1000),
    'cache' => [
        'enabled' => env('REFINDER_CACHE_ENABLED', false),
        'ttl'     => env('REFINDER_CACHE_TTL', 60),
        'prefix'  => 'refinder_',
    ],
    'events'      => env('REFINDER_EVENTS', true),
    'log_channel' => env('REFINDER_LOG_CHANNEL', null),
];

use Refinder\LaravelSdk\DTOs\SeoInput;

$input = new SeoInput(
    content:        $article->body,
    url:            route('articles.show', $article),
    contentType:    'article',
    language:       'en',
    depth:          'advanced',
    targetKeywords: ['AI tools', 'machine learning'],
    brandName:      'MyBrand',
    industry:       'Technology',
);

$result = Refinder::seo()->execute($input);

$result = Refinder::seo()->execute(['content' => $text]);
$seo = $result->output;

// Meta tags
$seo->metaTitle;            // string (50-60 chars)
$seo->metaDescription;      // string (150-160 chars)

// Keywords
$seo->keywords->primary;     // ['keyword1', 'keyword2']
$seo->keywords->secondary;   // ['keyword3', 'keyword4']
$seo->keywords->longTail;    // ['long tail phrase']
$seo->keywords->all();        // All keywords merged

// Content Analysis
$seo->contentAnalysis->readabilityScore;    // 'excellent', 'good', 'needs_improvement'
$seo->contentAnalysis->contentQuality;      // 'high', 'medium', 'low'

// SEO Score (0-100)
$seo->seoScore->overall;     // 75
$seo->seoScore->content;     // 70
$seo->seoScore->keywords;    // 80
$seo->seoScore->structure;   // 75
$seo->seoScore->isPassing(); // true (>= 60)

// Optimization Suggestions
foreach ($seo->optimizationSuggestions as $suggestion) {
    $suggestion->category;     // 'content', 'technical', 'structure'
    $suggestion->priority;     // 'high', 'medium', 'low'
    $suggestion->suggestion;   // "Add structured data..."
    $suggestion->isHighPriority(); // bool
}

// Heading Structure
$seo->headingStructure->suggestedH1;  // string
$seo->headingStructure->suggestedH2s; // array

// Execution metadata
$result->id;                       // UUID
$result->usage->totalTokens;       // 1276
$result->model->provider;         // 'alibaba'

$platform = Refinder::me();

$platform->id;           // 1
$platform->name;         // "My Platform"
$platform->slug;         // "my-platform"
$platform->website;      // "https://example.com"
$platform->isActive;     // true

$sub = Refinder::subscription();

$sub->plan->name;                // "Pro"
$sub->plan->maxRequestsPerMonth; // 1000
$sub->plan->maxRequestsPerDay;   // 100
$sub->plan->features;             // ['advanced_seo', ...]
$sub->isActive();                // true

$usage = Refinder::usage();
// Or with date range:
$usage = Refinder::usage('2026-01-01', '2026-01-31');

$usage->totalRequests; // 47
$usage->totalTokens;   // 62340
$usage->totalCost;     // 0.12468

foreach ($usage->daily as $day) {
    $day->date;           // "2026-02-08"
    $day->requestsCount;  // 12
    $day->tokensUsed;     // 15600
}

$executions = Refinder::executions(perPage: 10, page: 1);

$executions->total;        // 47
$executions->hasMorePages(); // true

foreach ($executions->items as $exec) {
    $exec->id;     // UUID
    $exec->tool;   // "seo"
    $exec->status; // "completed"
}

// Get a specific execution
$exec = Refinder::execution('uuid-here');
if ($exec->isCompleted()) {
    echo $exec->output->metaTitle;
}

use Refinder\LaravelSdk\Exceptions\AuthenticationException;
use Refinder\LaravelSdk\Exceptions\RateLimitException;
use Refinder\LaravelSdk\Exceptions\SubscriptionException;
use Refinder\LaravelSdk\Exceptions\ToolException;
use Refinder\LaravelSdk\Exceptions\ValidationException;

try {
    $result = Refinder::seo()->execute(['content' => $text]);
} catch (ValidationException $e) {
    // 422 — Input validation failed
    return response()->json(['error' => $e->errors], 422);
} catch (RateLimitException $e) {
    // 429 — $e->limit, $e->current
} catch (SubscriptionException $e) {
    // 403 — Subscription issue
} catch (AuthenticationException $e) {
    // 401 — Invalid API key
} catch (ToolException $e) {
    // 500/502 — $e->executionId for debugging
}

$usage = Refinder::usage();
$sub   = Refinder::subscription();

$used      = $usage->totalRequests;
$limit     = $sub->plan->maxRequestsPerMonth;
$remaining = $limit - $used;

echo "Used {$used}/{$limit} this month. {$remaining} remaining.";

use Refinder\LaravelSdk\Facades\Refinder;

public function test_seo_analysis()
{
    Refinder::fake();

    $result = Refinder::seo()->execute(['content' => 'Test content']);

    $this->assertEquals('completed', $result->status);
    $this->assertNotNull($result->output->metaTitle);
    $this->assertTrue($result->output->seoScore->isPassing());

    // Assertions
    Refinder::assertToolExecuted('seo');
    Refinder::assertToolExecutedCount('seo', 1);
}

class AnalyzeArticleSeo implements ShouldQueue
{
    public int $tries = 3;
    public int $backoff = 60;

    public function handle(): void
    {
        try {
            $result = Refinder::seo()->execute([
                'content' => $this->article->body,
                'depth'   => 'advanced',
            ]);

            $this->article->update([
                'seo_score' => $result->output->seoScore->overall,
            ]);
        } catch (RateLimitException $e) {
            $this->release(300); // retry in 5 minutes
        }
    }
}