Core Api Laravel Package

Getting Started

• Require fleetbase/core-api ^1.6.71. Both 1.6.70 and 1.6.71 are additive patch-level bumps — no upgrade steps beyond bumping the constraint. If you run fleetbase/storefront v0.4.25, ^1.6.70 is a hard requirement for its phone change endpoint; 1.6.71 satisfies it.
• Run php artisan cache:clear on deploy (your deploy.sh already does). Cache keys changed shape in 1.6.71, so stale entries from before the bump will simply expire within their TTL (5 min lists, 1 hour models) but clearing is cleaner.
• Two seams to know first, depending on what you're doing:
  • SMS/verification: VerificationCode::generateSmsVerificationFor() — creates/saves the code, hands it to the SMS guard, and the guard does the send, counting, and tracing.
  • Realtime auth: the console socket settings endpoints — GET/POST int/v1/settings/socket (read/save) and signed GET int/v1/socket/config (what the socket server polls).
• First use case (phone change): call generateSmsVerificationFor($subject, ['phone' => $newNumber]) so the code goes to the number being verified rather than the one on file.
• First use case (realtime): confirm your socket server is on fleetbase/fleetbase v0.7.70 or newer, then start moving socket auth config out of env and into the console settings.

Implementation Patterns

Default verification behaviour (unchanged): omit the option and the code is texted to the subject's own phone. Keep this for login, signup confirmation, and any flow where the number on file is the number being proven.

Phone change flow: pass the destination explicitly.

$code = VerificationCode::generateSmsVerificationFor($customer, [
    'phone' => $request->input('phone'),
]);

The code is texted to that number, and the SMS guard counts and traces the send against it — not against the subject's stored phone. That matters for rate limiting and audit trails: the trace reflects the number that actually received the message.

Customer with no number on file: the case 1.6.70 fixed. Previously the request reported success while nothing was sent. With phone, the code goes to the supplied number. Use for onboarding flows where the first number is being captured rather than replaced.

Post-verification persistence: the option only affects delivery and accounting. Persisting the new number onto the subject is your code's job, after the code checks out. Treat generate → verify → persist as three distinct steps.

Socket settings from the console: administrators manage the switch, mode (off, log, enforce), token TTL, allowed origins, and publisher origin via POST int/v1/settings/socket. Each value falls back to the environment when unset — nothing changes until someone saves. Your socket server polls the signed GET int/v1/socket/config and applies changes at runtime (no restart). SOCKETCLUSTER_AUTH_KEY stays in env, is never stored or returned, and enabling the switch without a key is refused.

Category trees: the internal Category resource now includes parent_uuid, so a console can build a tree from a flat list (e.g. Storefront's nested product categories) without a second round trip.

Event subscriptions: driver-assigned order events now publish on driver.{public_id} and driver.{uuid} as well as driverAssigned.*. Subscribe to the {type}.{id} channels — that's the convention clients follow, and driverAssigned.* is now deprecated.

Cache isolation: list/model/relationship cache keys now carry the connection ({api_query}:mysql:… / {api_query}:sandbox:…). Live and test-mode responses are kept apart automatically. No action needed unless you've written custom caching keyed on the raw api_query string.

Storefront integration: if you're wiring the phone change endpoint through fleetbase/storefront v0.4.25, the ^1.6.70 constraint is already declared — just don't hold core-api back with a tighter pin elsewhere in the dependency graph.

Gotchas and Tips

• Silent no-send. Without the phone option, a subject with no phone still gets a saved code and no text, and the call can still look successful. Anywhere you generate a code for a number the subject doesn't own yet, pass phone explicitly.
• Counting moves with the number. The guard counts against the passed phone, so rate limits key off the destination, not the subject. Correct for a phone change, but consider your own per-subject throttle if abuse is a concern.
• phone is a delivery target, not an assignment. Passing it does not attach the number to the subject. Skip the persistence step and the code is valid but the account never changes.
• Verification must match the destination. Verify against the same number you sent to. "Sent to new number, verified against stored phone" is the easy mistake.
• Debugging a missing SMS: start from the send trace the guard writes and confirm which phone it was recorded against. Trace shows the stored number → you forgot phone. No trace at all → the flow short-circuited before the guard.
• driverAssigned.* is deprecated but still published. Existing listeners won't break, but migrate to driver.{public_id} / driver.{uuid} now — that's where the {type}.{id} convention clients actually subscribe.
• Octane filter bleed is fixed. Under Octane, Find::httpFilterForModel() previously cached the filter per model class for the life of the process, so the first controller to list a model decided the filter for every other app (the reported symptom: a network's orders page listing every order in the company). The cache is now keyed by the model's own filter and request class. If you were seeing cross-app filter leakage, confirm you're on 1.6.71 and your controller's $filter is actually set.
• Cache keys changed shape. Live and test responses no longer share entries (that's the fix, not a bug). If you had tooling that parsed cache keys, update it. Old keys expire naturally within TTL.
• Socket server version matters. An older socket server (< fleetbase/fleetbase v0.7.70) keeps reading its own environment and ignores console-saved settings entirely — no error, just no effect.
• Socket saves are audited. Every save is written to the activity log, so config changes are traceable; account for that in log-retention and compliance workflows.
• Category parent_uuid is on the internal resource only. Don't expect it on public API Category responses.
• Upgrade risk is low. All changes are additive or bug fixes, the no-option verification path is unchanged, and nothing changes until an administrator saves socket settings. Safe patch-level bump — but do bump.