Xero Laravel Package

Product Decisions This Supports

• Reliability of third-party integrations: the 0.3.23 change makes token-refresh failure an explicit state transition — the connection is marked disabled rather than silently continuing with credentials that will fail. This supports decisions about whether an integration can be trusted as "always working" in customer-facing flows (sync jobs, webhooks, CRM data pulls).
• Build vs. buy for auth/connection lifecycle: token refresh, credential storage, and failure handling are undifferentiated plumbing. Every sprint spent on refresh edge cases is a sprint not spent on the product surface; this package is a candidate to buy (adopt) rather than build.
• Onboarding and recovery UX: because failed refreshes now surface as a disabled connection, product can design a re-authentication prompt ("Reconnect your account") instead of relying on silent degradation, failed jobs, and support tickets.
• Roadmap sequencing for integrations: this package's maturity gates which integrations you can ship confidently. Resilient failure handling is a prerequisite for unattended/background sync features; it is not a blocker for read-only, user-initiated demos.
• Operational load and support cost: disabled-on-failure means failures become observable and countable, enabling alerting and a measurable "connections needing reauth" metric per account — a lever for reducing churn driven by broken integrations.
• Risk posture for enterprise deals: deterministic failure semantics (fail closed, not fail open with stale tokens) is the kind of answer security reviewers and uptime-conscious buyers expect during procurement questionnaires.

When to Consider This Package

Consider adoption when:

• Your Laravel application holds user- or tenant-scoped OAuth credentials to one or more external APIs and refreshes tokens on a schedule or on demand.
• You need background/unattended operation — scheduled syncs, queue workers, webhooks — where a human is not present to notice an expired token.
• You want failure to be explicit and recoverable rather than logged-and-forgotten; the disabled-on-failure behavior in 0.3.23 is a direct fit for building reauth flows and health dashboards.
• You are standardizing multiple integrations on one connection abstraction and want consistent semantics across providers.
• Your team is small relative to the integration surface area, and maintaining refresh logic per provider is a poor use of engineering time.

Look elsewhere or wait when:

• You have exactly one provider with a trivial, long-lived credential (API key, service account). The abstraction may be more machinery than the problem warrants.
• You need provider-specific behaviors (granular scopes, provider-specific refresh race conditions, non-standard token rotation) that a general abstraction cannot express without escaping the package.
• Your failure model requires automatic self-healing — e.g., retry-with-backoff, multi-credential failover, or transparent re-consent. Disabling the connection is a deliberate fail-closed choice; if your product cannot tolerate a disabled state without human action, validate that this is the semantics you want.
• You require production-hardened maturity signals (long release history, broad adopter base, documented upgrade guarantees). A 0.3.x line implies pre-1.0 API churn; assume breaking changes are still permitted.
• You are not on Laravel or are pinned to an unsupported framework/PHP version.

How to Pitch It (Stakeholders)

For executives: This is a small infrastructure dependency that removes a recurring class of customer-visible outages — integrations that quietly stop syncing because a credential expired. The latest release makes those failures visible and actionable instead of silent, which converts a background reliability problem into a simple "reconnect your account" prompt. It is a buy-not-build decision: adopting it avoids owning maintenance of token-refresh logic across every integration we ship, and it lowers the support and engineering cost of each new integration we add. The trade-off is dependency on a pre-1.0 package, so we should treat version pinning and an upgrade budget as part of the decision.

For engineering: The package owns connection lifecycle and token refresh for external providers. Release 0.3.23 changes failure semantics: when a refresh fails, the connection's enabled status is reset, so downstream code sees a disabled connection rather than stale credentials. That means consumers must handle the disabled state explicitly — treat it as a first-class signal, surface reauth to the user, and avoid retry loops that hammer a connection that cannot succeed until reauthorized. This is a behavior change in error paths, not the happy path; audit any code that assumes a connection stays enabled after a failed refresh, and pin the version until that audit is done. Keep an abstraction seam around the package so provider-specific quirks and future breaking changes in the 0.x line don't leak into domain code.