Wapi Gateway Laravel Package

Getting Started

• Require the package (composer require) and confirm which line you are on: ^0.22.4 remains the entry point for consumers such as accounts; 0.23.3 is the current patch. If you are jumping from 0.22.x, review the full changelog for 0.23.0–0.23.3 before bumping — the provided 0.23.3 note only lists the vCard fix.
• Publish and run the migrations first — the package persists an audit trail in device_logs. Without that table the client still works, but you lose the observability that the 0.22.7 unsubscribe fix exists to provide.
• Look at three places before writing code: the ZApiClient class (public methods such as unsubscribe(), logout(), logRequest(), sanitizeUrl()), ZApiLite (the thin variant that inherits the same behaviour), and your device_logs rows after issuing a single call.
• If you expose shared contacts, also locate the vCard generation path. 0.23.3 fixes duplicated country codes in shared-contact vCards, so this is the second surface to validate after upgrading.
• First use case: exercise the disconnect path once in a non-production instance, then confirm two device_logs rows exist with method=unsubscribe — one with step=disconnect, one with step=cancel. That single check validates credentials, migration, logging parity and URL masking in one pass. If you use shared contacts, generate a vCard for a contact with an international number and confirm the country code appears once.

Implementation Patterns

• Treat device_logs as the source of truth for lifecycle state. The 0.22.7 change makes unsubscribe() log in parity with logout(), so cancellation is auditable end to end. Build any "is this instance really cancelled?" check against the log table rather than trusting the HTTP response you got back at call time.
• Model an unsubscribe as two steps, not one operation. step distinguishes disconnect from cancel under the shared method=unsubscribe. Deduplicate on (instance_id, method, step) when counting cancellations, otherwise a single unsubscribe inflates your metrics by two.
• Alert on the "billed but never cancelled" signature — the failure mode the 0.22.7 release was cut for. A paid instance with no successful method=unsubscribe row (both steps present) is the queue you want surfaced in a scheduled command or a Laravel notification, not a spreadsheet.
• Follow the logRequest() convention in your own wrappers. If you extend or decorate the client with custom endpoints, call logRequest() explicitly; the bug fixed in 0.22.7 was precisely a method that skipped it. Any new call site that omits it becomes invisible in the same way.
• Run unsubscribe from a queued job with retries and failed() handling. Since both HTTP calls now log, a retried job leaves a readable trail of attempts; without the fix you would have had a silent gap.
• Prefer injecting the client over resolving it statically in application code, and type-hint ZApiLite only where you deliberately want the reduced surface. Anything you write against ZApiClient should keep working through the inheritance path.
• Pin explicitly. Bumping from 0.22.x to 0.23.3 picks up both the unsubscribe logging fix and the shared-contact vCard fix, but a 0.22→0.23 minor jump in 0.x semver can carry more than a patch. Read the changelog and run an upgrade pass rather than treating it as a blind patch bump.
• Add a vCard regression check if shared contacts are part of your product. Generate a vCard for a contact with an already-prefixed international number and assert the country code is not duplicated; do the same for a local number. Keep this in the same test suite as your unsubscribe logging checks so both release-critical behaviours stay covered.

Gotchas and Tips

• Old failures are unrecoverable. The 0.22.7 logging fix is forward-looking only — unsubscribes that failed before it left no device_logs trace and cannot be backfilled. Run a one-off reconciliation against your payment provider for historical periods rather than querying logs.
• URLs are masked by design. Both unsubscribe URLs carry /token/<token>/ and sanitizeUrl() redacts it, so never expect to recover an instance token or identify an instance from the logged URL. Key off whatever instance/device identifier column you store alongside the log entry.
• step values are lowercase literals (disconnect, cancel). Compare exactly and avoid case-insensitive matching that could hide a future value.
• Absence of a log row is not proof the call was never made on versions below 0.22.7; on 0.22.7 and above it is. Make sure any alerting you build knows which version produced the data it is reading.
• A failed disconnect may still be followed by an attempted cancel (or vice versa). Don't assume the two rows are written atomically or that one implies the other succeeded — check each step independently.
• Debugging order: confirm the device_logs migration ran, confirm the row is written (proves logRequest() was reached), then inspect the sanitized URL and response payload. If no row appears at all, you are on an older version or a custom wrapper that bypasses logging.
• Extension point: logRequest() and sanitizeUrl() are the natural seams — override or hook them centrally (events, a decorator, or a base class) to add correlation IDs or extra redaction, rather than sprinkling logging through call sites.
• Keep ZApiLite and ZApiClient in lockstep in your own abstractions. Behaviour added to the base client is inherited, so a wrapper that special-cases only ZApiClient will quietly diverge from lite consumers.
• The vCard country-code bug is a formatting defect, not a transport failure. It will not show up in device_logs or HTTP status. If shared contacts render malformed phone numbers, check the package version first; 0.23.3 prevents duplicated country codes, but it does not rewrite vCards that were already generated — regenerate them.
• Do not infer the whole 0.23.x line from the 0.23.3 note. The release note lists only the shared-contact vCard fix. If you are upgrading from 0.22.x, validate both your unsubscribe logging path and your vCard path in a staging environment before rolling out.