Wavespeed Ai Bundle Laravel Package

Getting Started

v0.1.0 is the initial release, so treat this as an early-stage integration. The release notes only link to the changelog, so start source-first: read the README, CHANGELOG.md, composer.json, service provider, config file, routes, and tests before designing around it.

Minimal setup:

1. Require the package: composer require errogaht/wavespeed-ai-bundle.
2. Check for Laravel auto-discovery in composer.json; if not present, register the service provider manually.
3. Publish any package config if supported, e.g. php artisan vendor:publish --tag=wavespeed-config.
4. Add credentials to .env, typically a WaveSpeed API key, and confirm the expected env names in the package config.
5. Resolve the package client through the container or facade rather than instantiating it directly.

First use case: submit a single WaveSpeed generation request from a queued Laravel job, store the provider request/job ID, then complete the result via polling or webhook/callback if supported. Keep controllers thin; put provider interaction behind an application service or action.

Implementation Patterns

• Wrap the package behind your own service/action. Create something like GenerateWaveSpeedAsset so controllers and jobs depend on your domain API, not the package’s raw arrays or response objects.
• Use dependency injection. Bind the package client or an interface in a service provider, then inject it into actions/jobs. This makes testing and future package replacement easier.
• Queue long-running work. Image/video generation is usually asynchronous and slow. Use ShouldQueue, explicit $timeout, $tries, backoff(), and avoid doing generation inline in HTTP requests.
• Separate submit, poll, and complete. Persist provider IDs and statuses in your own table/model. This avoids relying on in-memory state and supports retries, observability, and user dashboards.
• Store outputs on a Laravel disk. Download or copy provider result URLs to storage or S3 promptly; provider URLs may expire.
• Model webhooks carefully if supported. Verify signatures, reject replays, persist the raw payload, then dispatch a queued job to process it idempotently.
• Use Laravel HTTP fakes in tests. If the package uses Laravel’s HTTP client, fake provider responses and assert your job/action behavior rather than hitting the real API.
• Emit domain events. For example, WaveSpeedGenerationCompleted and WaveSpeedGenerationFailed, then attach notifications, billing, or UI updates as listeners.
• Centralize config. Read timeouts, disks, queue names, model defaults, and API base URLs from config, not scattered constants.

Typical day-to-day flow:

GenerateWaveSpeedAsset::dispatch($generation->id);

// In the job:
$response = $client->submit($payload);
$generation->update([
    'provider_job_id' => $response->id(),
    'status' => 'processing',
]);

Exact method names will depend on the package surface; verify against source before committing to an integration shape.

Gotchas and Tips

• v0.1.0 is early. Pin the version and read the changelog before upgrading. Expect API changes, limited documentation, and possible gaps in Laravel-specific conventions.
• Release notes are thin. The only v0.1.0 note is a changelog link; do not assume features from the package name alone. Inspect the actual public API and tests.
• Keep API keys server-side. Never expose WaveSpeed credentials through frontend config or Inertia props. Use config:cache in deployment and confirm env/config names match.
• Do not run generation synchronously in a request. Provider latency and timeouts will cause failed requests and duplicate jobs. Prefer queues with idempotency keys where possible.
• Handle provider failures distinctly. Separate validation errors, auth failures, rate limits, provider-side errors, and transport timeouts so retries do not repeat non-retryable failures.
• Watch rate limits and cost. Add queue throttling and per-user/account quotas. Log estimated or actual cost if the provider exposes it.
• Webhook security matters. Verify signatures, reject stale timestamps, store event IDs, and process events asynchronously after verification.
• Be careful with temporary URLs. Persist generated files to your own disk before showing them to users or storing them long term.
• Debug with correlation IDs. Log your internal generation ID, provider job/request ID, status transitions, and sanitized error payloads. Use Laravel Telescope or structured logs.
• Extension points to check first: container bindings, config publishing, facade accessors, events, custom HTTP client injection, and response DTOs. If these are missing in v0.1.0, keep the package isolated behind your own adapter.