Core Api Laravel Package

Product Decisions This Supports

• Whether to accelerate this upgrade as a data-exposure fix, not a routine bump. v1.6.71 fixes two defects with customer-visible data-integrity consequences:
  • Find::httpFilterForModel() cached its answer per model class for the life of the process, so under Octane the first controller to list a model set the filter for everyone. Concretely: Fleet-Ops' order filter was applied to Storefront's order lists, so a network's orders page listed every order in the company. If you run console + Storefront/Fleet-Ops together on Octane, this is a live cross-tenant visibility bug — treat it as an incident-review item (scope of exposure, whether customer notification is warranted), not just a dependency chore.
  • Live and test-mode data shared API cache entries because console sessions carry no API credential to distinguish them. A test-mode console could be served the cached live response for the same query, and the reverse. If sandbox/test mode is used for demos, partner onboarding, QA, or training, that is a correctness and trust problem.
• Realtime channel auth becomes an operational decision, not an env-file decision. Admins can now read/write the socket switch, mode (off, log, enforce), token TTL, allowed origins and publisher origin via int/v1/settings/socket, with fallback to environment when unset and every save written to the activity log. This is what makes a staged rollout decision practical: turn on log mode to measure impact without rejecting connections, then move to enforce — no restart, no redeploy, no engineer in the loop. The SOCKETCLUSTER_AUTH_KEY remains env-only and is never stored or returned, and enabling the switch without a key is refused, so the security-critical secret does not leak into the admin surface.
• Integration roadmap for realtime consumers. Driver-assigned order events now publish on driver.{public_id} and driver.{uuid}, matching the {type}.{id} convention clients actually subscribe to. driverAssigned.* still publishes but is deprecated. Any driver-facing app, partner integration, or webhook subscriber built on driverAssigned.* needs a migration item on the roadmap; the deprecation is your notice window, not a break.
• Console feature enablement via parent_uuid on internal Category responses. A flat category list can now build a tree client-side, which is the enabler for Storefront's nested product categories. Cheap, additive unblock for a merchandising/catalogue roadmap item.
• Carry-forward: phone-change verification. From v1.6.70, VerificationCode::generateSmsVerificationFor() accepts a phone option so a code is sent to the number being verified, with the SMS guard counting and tracing the send against it. This remains a hard dependency for the Storefront phone-change endpoint (fleetbase/storefront v0.4.25 requires fleetbase/core-api ^1.6.70), and it closed a silent failure where a subject with no phone got a success response and no text.
• Build vs buy: the socket settings endpoint is a strong argument for buy/consume — realtime auth config, audit logging and runtime propagation are exactly the plumbing you do not want to rebuild per app. Likewise the verification primitive: narrow and well-scoped, cheaper to extend than to duplicate.

When to Consider This Package

Adopt (and in the two fixes below, prioritise) when:

• You run console alongside Storefront and/or Fleet-Ops on Octane. The per-class filter cache bug is a cross-tenant visibility risk; upgrading is risk reduction, not feature work.
• You operate a sandbox or test mode for demos, partner/merchant onboarding, QA or training, and cannot tolerate live data appearing in test responses or vice versa.
• You need realtime channel authentication you can tune without redeploying: staged log → enforce rollout, per-environment origins, and an audit trail of who changed what.
• You have driver-facing clients on the {type}.{id} channel convention that were missing driver-assigned events — and subscribers still on driverAssigned.* that need a deprecation migration.
• You are building a nested category tree in a console or storefront catalogue and want it from the existing flat internal endpoint rather than a new one.
• You are shipping a phone-change or contact-verification flow (carried forward from v1.6.70) or need the Storefront phone-change endpoint.
• You value a no-migration upgrade path: no upgrade steps required, environment values stay the defaults for socket settings, and stale cache entries expire on their own TTL (5 minutes for lists, 1 hour for models) with deploy.sh already running cache:clear.

Look elsewhere or scope carefully when:

• You run a single-tenant deployment with one app and no Storefront/Fleet-Ops pairing and no sandbox users — the headline fixes are real but lower-impact; fold them into a routine dependency pass rather than a dedicated initiative.
• You need multi-channel verification (email, voice, push) with a unified template/consent layer — the verification work here is SMS-specific.
• You require provider-agnostic delivery with SLAs, delivery receipts and fallback routing — that belongs to a dedicated OTP vendor; this package sits behind it at best.
• You need verification for a number not attributable to a subject record — the API is oriented around a subject plus an optional target phone.
• You are pinned below fleetbase/core-api 1.6.70 and cannot upgrade — the Storefront phone-change endpoint will not work.
• Your socket server is older than fleetbase/fleetbase v0.7.70 — it will keep reading its own environment and simply won't pick up console-managed settings; the admin UI would then be misleading, so upgrade both or neither.

How to Pitch It (Stakeholders)

For executives: v1.6.71 is a low-cost, no-migration upgrade that closes two real data-integrity defects. First, an order-list filter was being cached per model and leaking across apps under Octane — a network's orders page could list every order in the company. Second, live and test-mode data were sharing API cache entries, so a test-mode console could be served live data. Both are trust-and-compliance issues with a straightforward remedy: upgrade on the next dependency pass, and review exposure scope given the first one. Alongside the fixes, realtime channel authentication moves into the admin console (switch, mode, token TTL, allowed origins) with an activity-log audit trail and no restart required, which lets us stage realtime enforcement safely instead of flipping it in an env file. One deprecation to note: driverAssigned.* events are superseded by driver.{id}, so any partner or in-house client on the old channel needs a scheduled migration.

For engineering: Upgrade is additive — no upgrade steps. Five changes to know:

1. Find::httpFilterForModel() and Find::httpRequestForModel() are now keyed by the model's own filter/request class, and convention-discovered filters are picked per request audience. Fixes the Fleet-Ops filter bleeding into Storefront order lists under Octane (#315).
2. API cache keys now carry the database connection ({api_query}:mysql:… / {api_query}:sandbox:…), isolating live from sandbox list, model and relationship caches (#312). Old entries keep old keys and expire within TTL; deploy.sh already clears cache.
3. New GET/POST int/v1/settings/socket and signed GET int/v1/socket/config (#314). Values fall back to environment when unset; SOCKETCLUSTER_AUTH_KEY stays env-only and enabling the switch without it is refused; saves are activity-logged. Requires socket server fleetbase/fleetbase v0.7.70+ to consume the signed config at runtime.
4. Driver-assigned order events now also publish on driver.{public_id} and driver.{uuid}; driverAssigned.* still publishes but is deprecated (#311). Update client subscriptions and add a deprecation note to any integration docs.
5. Internal Category resource includes parent_uuid (#316) — additive, no client breakage.

Recommended actions: upgrade in the next routine pass but flag #315 for a security/exposure review first; add regression coverage for cross-app filter resolution under Octane and for live-vs-sandbox cache key separation; and carry forward the outstanding v1.6.70 test gap on the "subject has no phone" verification path, which previously reported success without delivering a code.