Laravel Switchbot Frame Laravel Package

Product Decisions This Supports

• Feature bets on ambient/physical surfaces. This package is the delivery leg for a prompt → AI image → SwitchBot Frame pipeline (prompt improvement, generation, ready-state, per-image bookkeeping). It supports product bets like daily AI art, family/photo rotation, dashboards-as-art, or personalized e-ink displays without building device plumbing in-house.
• Build vs buy on the integration layer. Adopt the package for the SwitchBot Frame API and job/pipeline semantics; spend engineering effort on prompt quality, content selection, and user-facing experiences rather than on device transport, retries, and state tracking.
• Dependency strategy for laravel/ai. 1.4.0 supports both ^0.11 and ^1.0 (token shapes: promptTokens/completionTokens vs inputTokens/outputTokens, plus ImageUsage). That buys you the option to defer a forced major upgrade and to migrate on your own schedule — a roadmap input, not just a technical detail.
• Reliability vs telemetry tradeoff (explicit product call). Bookkeeping failures (token usage, model name, cost estimation) are now rescued and unreported, so a generated image still reaches "ready" and prompt improvement still applies. This is the right default for user-facing reliability, but it means cost/usage data is now best-effort. If cost attribution feeds billing, budgets, or unit economics, pair this with spaanproductions/laravel-ai-usage (explicitly suggested in this release) or your own instrumentation.
• Observability as a separate concern. The maintainer's suggestion of a companion usage/cost dashboard package signals the intended split: this package owns delivery, a sibling owns cost visibility. That supports a "buy the dashboard, don't build it" decision for internal spend tracking.
• Sizing and scope signal. A narrow, single-vendor integration with job-state semantics is low-cost to trial behind a flag or in an internal tool, making it a low-commitment way to validate demand for physical AI-generated displays before investing in a broader abstraction.

When to Consider This Package

Consider it when:

• You are on Laravel and already use (or plan to use) laravel/ai for image generation, and you want results rendered on SwitchBot Frame hardware.
• You want the pipeline semantics — improved prompt applied, image generated, asset marked ready — handled for you rather than hand-rolled in jobs and listeners.
• You need to stay on laravel/ai ^0.11 for now, or you are mid-migration to ^1.0; 1.4.0 and its CI matrix cover both, so you are not blocked by the upgrade.
• You accept best-effort usage/cost bookkeeping, or you are willing to add explicit monitoring (companion package, logs, or alerts) because failures are now silent.
• The value is in getting a working end-to-end demo or internal feature quickly, with a single device vendor.

Look elsewhere or plan extra work when:

• You need multi-vendor display support (multiple frame brands, screens, or e-ink devices) — this is SwitchBot Frame-specific.
• Cost and token accounting must be authoritative (billing, per-tenant quotas, strict budgets) — the 1.4.0 behavior deliberately makes this non-blocking and non-reported, so you need a separate, verified accounting path.
• You are not using laravel/ai, or you need a provider-agnostic generation layer.
• You require hard guarantees that every generation is cost-attributed; silent rescue trades that guarantee for uptime.
• You need vendor-backed SLAs or long-term support commitments — this is a small, single-maintainer package and should be treated as such (pin versions, watch releases, keep an abstraction seam around the delivery call).

How to Pitch It (Stakeholders)

For executives (one paragraph): This package lets our Laravel app push AI-generated images to SwitchBot Frame displays with very little custom code — prompt improvement, generation, and delivery are already handled. The 1.4.0 release is low-risk: it supports both the current and next major version of our AI library, so we are not forced into an upgrade, and it makes sure a display still updates even if our cost-tracking step breaks. That is the right priority for a customer-facing feature, but it means spend numbers are now best-effort — we should add a small cost dashboard (the maintainer points to a companion package) if we intend to use these numbers for budgeting. Overall: a cheap way to test whether physical, AI-generated displays are worth investing in, with a clear seam to walk away if not.

For engineering: 1.4.0 adds laravel/ai ^1.0 support alongside ^0.11, reading token usage from either promptTokens/completionTokens (0.x) or inputTokens/outputTokens (1.x, including ImageUsage); CI now runs the matrix against both majors, so an upgrade is a version bump rather than a rewrite. The behavioral change to note: bookkeeping (usage, model name, cost estimate) is now rescued and not reported, so failures no longer block a generated image from being marked ready or an improved prompt from being applied. That is a deliberate decoupling of telemetry from the critical path — if cost data matters, add explicit logging and alerting around it, or wire in spaanproductions/laravel-ai-usage. No breaking changes are called out; the main risks are the silent-failure behavior and reliance on a pre-1.0-adjacent dependency, so pin versions and keep the delivery call behind a thin internal interface.