Wapi Gateway Laravel Package

Product Decisions This Supports

• Billing reconciliation and revenue-leak detection. The root problem behind the 0.22.7 fix was a paid WhatsApp instance that is billed but never successfully cancelled — a silent, recurring cost with no failure signal. With unsubscribe() now writing to device_logs in parity with logout(), we can answer "did the cancellation actually land at Z-API?" from data rather than from support tickets. This directly supports decisions about refunds, churn credits, and vendor cost exposure. That capability remains the primary reason this package carries product weight for us.
• Correctness of customer-facing message content. The 0.23.3 fix stops a duplicated country code from being emitted in shared-contact vCards. This matters because a vCard defect is not cosmetic: it produces a dialable-looking number that is wrong, propagates into the recipient's address book, and surfaces as a customer complaint rather than an error. Decisions affected: how much we trust outbound message composition to the package versus validating it ourselves, and whether contact-sharing is safe to ship broadly on this channel.
• Operational trust in the WhatsApp channel. Any decision to expand usage of the channel (more instances, more accounts, higher tiers) depends on being able to audit lifecycle events. Disconnect and cancel are the two highest-risk lifecycle transitions because they touch money; contact composition is high-risk because it touches the customer. Both classes of defect are now addressed in recent releases, which is what makes further expansion defensible.
• Incident forensics and support deflection. Failed unsubscribes are now queryable records rather than escalations, and vCard formatting defects now have a fix we can point to instead of an open "wrong number" mystery. Both reduce the volume of issues that arrive without a diagnostic path.
• Vendor dependency management (build vs buy). This remains a thin Laravel wrapper over a single gateway (Z-API). Its iteration cadence is informative: it is shipping small, focused patches across both billing lifecycle and message composition, which is a reasonable signal that staying on the wrapper is cheaper than a deeper integration — for now. A provider abstraction layer is still the fallback if we ever need to switch gateways.
• Upgrade-path decision, now overdue for a revisit. The 0.22.7 assessment recommended bumping accounts off ^0.22.4. The package has since moved to 0.23.3. We are now crossing from 0.22.x into 0.23.x, which under the package's own 0.x versioning can carry behavioral change that a patch note does not reveal. The decision is no longer "take a free patch" but "review the 0.23.x line deliberately and land it as a scoped change."
• Roadmap input on observability and correctness parity. That the unsubscribe logging gap survived to 0.22.7, and a formatting defect survived to 0.23.3, both point the same direction: client methods are added without a consistent acceptance bar. A reasonable follow-up is to mandate parity tests — logRequest() coverage for anything that mutates billing state, and vCard/phone-format assertions for anything that composes message content.

When to Consider This Package

Adopt or continue with it when:

• You run WhatsApp messaging or instance management through Z-API specifically, inside a Laravel/PHP codebase, and want an idiomatic client (ZApiClient, inherited by ZApiLite) rather than hand-rolled HTTP calls.
• You manage paid instance lifecycle — subscription, disconnect, integrator cancel — and need an audit trail for billing disputes and churn accounting.
• You send shared contacts / vCards, where the 0.23.3 country-code deduplication fix is a direct customer-facing correctness win. If you do not use contact sharing, this release is effectively inert for you.
• You need credential-safe logging. sanitizeUrl() masks the /token/<token>/ segment on unsubscribe URLs, so adopting this logging does not create a new secret-in-logs exposure. This is a genuine adoption enabler for teams with log-retention or compliance constraints.
• You want a low-risk, additive upgrade within the current minor line. Both recent releases are bug fixes with no method signature or response-shape changes.

Look elsewhere or defer when:

• You are not on Z-API, or you want a provider-agnostic messaging abstraction that lets you switch gateways. This package is coupled to one vendor's semantics (integrator cancel, disconnect, token-in-URL).
• You require semantic-versioning stability guarantees. At 0.x, minor bumps can still carry behavioral change. The jump from 0.22.x to 0.23.x should be treated as a reviewed upgrade, not an automatic one — read the full 0.23.0 changelog, not just 0.23.3. Plan for a 1.0 conversation if this becomes load-bearing for billing.
• You need observability beyond local device_logs — metrics, alerting, or a dead-letter path for failed cancellations. The package writes the record; it does not alert on it. Alerting on method=unsubscribe failures is our responsibility.
• You have already built your own vCard/phone normalization upstream. The 0.23.3 fix may then be redundant or, worse, duplicative — verify your normalization does not also strip or prepend country codes, or you risk reintroducing the same defect from the other side.
• Your logging pipeline is the audit system of record and you would rather emit domain events than rely on database rows in a package-owned table.

How to Pitch It (Stakeholders)

For executives: Two small, low-risk releases close two different gaps. The first closed a revenue blind spot: if a paid WhatsApp instance failed to cancel at the provider, nothing was recorded and we kept getting billed with no signal. Every unsubscribe attempt now leaves an auditable, credential-masked trace, so we can detect and recover instances that are billed but never cancelled. The second closes a customer-facing defect: shared-contact vCards could go out with a duplicated country code, meaning recipients saved a wrong phone number and had no way to tell. That is now fixed. Neither release carries a schema break, an API break, or a persisted secret. The main open item is sequencing: our accounts service is still on the 0.22 line, and the package is now at 0.23.3, so this is no longer a trivial patch bump — it should be a scoped upgrade with a changelog review, not an automatic one. Recommended action: schedule the 0.23.x upgrade for accounts in the next release cycle and stop treating it as a background dependency refresh.

For engineering: Two independent fixes. (1) ZApiClient::unsubscribe() was the only client method bypassing logRequest(), so failed disconnects and integrator cancels produced no device_logs entry; both now log in parity with logout(), with step (disconnect | cancel) disambiguating them under method=unsubscribe, and URLs passed through sanitizeUrl() so no token reaches the log. (2) PR #68 fixes duplicated country-code prefixing when composing shared-contact vCards. No signature changes, no response changes, ZApiLite inherits both behaviors. The caveat is version distance: we have visibility into the 0.23.2→0.23.3 diff only, and we are moving from 0.22.x to 0.23.x — review the 0.23.0 release before bumping the constraint. Two follow-ups worth discussing: a parity test asserting logRequest() coverage for every method that mutates billing state, and a formatting assertion for every method that composes outbound message content, so neither class of gap reappears.