Document and test expanded Fleet resource APIs

[roncodes]

Summary

Documents and asserts the public Fleet, Vehicle and Driver contracts as
implemented in fleetbase/fleetops#311.

This revision corrects the relationship design from the first one. The earlier
commit documented and asserted a public ID under the object key, which would
have made a property an object on one call and a string on another. The SDK
stores what the API returns verbatim, so every consumer that dereferences such a
property breaks — Navigator interpolates driver.user straight into a socket
channel name, where an object becomes user.[object Object].

Implementation PR: fleetbase/fleetops#311

Type of Change

• Feature
• Documentation
• Test

Implementation Notes

Relationships are two keys

<name>_id is the public identifier and is always present. <name> is the
nested object, returned only when it was asked for through ?with=, and never a
string. Object definitions, examples and assertions all say so, and an automated
sweep confirms no Fleet, Vehicle or Driver response example renders a
relationship key as a string.

• Vehicle gains driver_id, vendor_id, category_id, warranty_id,
  photo_id, and fuel_card_number — which the object definition never carried
  even though the API returned it. photo_id is documented as the file
  reference, with photo_url as the convenience URL and avatar_url called out
  separately as a display asset.
• Fleet gains service_area_id, zone_id, vendor_id, parent_fleet_id,
  photo_id.
• Driver keeps user, company, company_name, vehicle, vendor and
  current_job in every example, alongside vehicle_id, vendor_id and
  job_id. user is documented as a string that is never expanded, with the
  reason.

Expansion

?with=vendor, ?with[]=vendor, ?with=vendor,driver and the expand alias
are documented, and two new requests prove the array and scalar spellings
equivalent rather than assuming it:

Request	Order	Asserts
Expand a Vehicle	3100	with[]=vendor adds the object, vendor_id unchanged and equal to vendor.id, an unsupported name is ignored
Expand a Vehicle Scalar	3200	with=vendor produces the identical result

Identifier lookup

internal_id and public_id are documented as exact on the public API,
with the console's partial search called out as internal-only — an importer that
keys on VEH-10 must not match VEH-100.

Assertions

Vehicle create and Driver update now drive their assertions off the request
body, so a field cannot be added to a request without an assertion following it.
Specifically asserted: purchased_at, the coordinates-to-location
canonicalisation, vehicle status normalisation, driver email, phone and the
new timezone, relationship public-ID prefixes, and the object/identifier
invariants under expansion. The uuid-leak checks became a sweep over every
response key rather than a fixed list.

Response shapes are the real ones — bare objects and bare arrays, no invented
{data: ...} wrapper. 200/201 are accepted only where the implementation
permits either.

Validation

• Lint

$ npm run postman:lint
Validated 5 Postman Native Git collections and 3 environments.
Linting Fleetbase API...            No issues found. Scanned: 214 | Errors: 0 | Warnings: 0
Linting Fleetbase Core API...       No issues found. Scanned: 24  | Errors: 0 | Warnings: 0
Linting Fleetbase Integrated Vendor Flow... No issues found. Scanned: 7 | Errors: 0 | Warnings: 0
Linting Fleetbase Ledger API...     No issues found. Scanned: 8   | Errors: 0 | Warnings: 0
Linting Fleetbase Storefront API... No issues found. Scanned: 62  | Errors: 0 | Warnings: 0

Both scripts/validate-collections.js and the Postman Native Git schema lint ran
(Postman CLI 1.46.0).

Live run — passed. fleetbase/fleetops#311 temporarily pinned its contract job
to this branch's commit so the two were validated together. Run
33953882575,
fleetops a249e7df × postman 91e72fe, against a booted stack carrying the
Fleet-Ops branch:

requests      237 executed, 0 failed
test-scripts   83 executed, 0 failed
assertions    314 executed, 0 failed

The pin has been reverted on that PR. Running this collection against a
deployment that does not carry #311 will fail, because the endpoints it asserts
do not exist there.

The first pinned run failed and was worth running: it caught a 500 on
GET /v1/vehicles/{id}?with[]=… in the implementation, and two assertions here
that compared the response against pm.request.body.raw — which re-resolves
{{$randomEmail}} every time it is read, so they could only ever fail. Both are
fixed.

Documentation Impact

• Documentation needed but not included

API Reference Impact

• Updated fleetbase/postman

If the fleetbase.io API reference is generated from this repository it needs
regeneration once both PRs land. No change was made to fleetbase/fleetbase.io.

Risk

Specification and tests only. The Fleets folder creates and deletes its own
vehicle and driver because the Vehicles and Drivers folders delete theirs before
it runs. The driver authentication and password requests are untouched:
driver_identity, driver_password and driver_phone are still not written by
anything here.

Confirmation

No credentials, API keys, tokens or customer data. All identifiers in examples
are illustrative. Not merged.