Document and test expanded Fleet resource APIs

[roncodes]

Summary

Brings the Fleetbase API collection in line with the expanded public Fleet,
Vehicle and Driver contracts, and adds request-specific response assertions so a
collection run proves the documented behaviour rather than only that a 2xx came
back.

Implementation PR: fleetbase/fleetops#311 — this PR documents and
tests that one.

Type of Change

• Feature
• Documentation
• Test

Implementation Notes

Fleets

Request/response contracts:

• Create a Fleet and Update a Fleet now document and send name,
  color, task, status, and the service_area, zone, vendor and
  parent_fleet relationships. Relationships are public IDs
  (service_area_..., zone_..., vendor_..., fleet_...) resolved inside
  the authenticated organization; a cross-company ID is answered exactly as a
  missing one is. null clears an assignment.
• Fleet status is documented as a short string rather than a closed enum: the
  console offers active/disabled/decommissioned, but the column is not
  constrained and existing integrations write other values.

New requests:

Request	Order	Covers
Create a Fleet	1000	Root fleet; seeds fleet_id and parent_fleet_id
Create a Subfleet	1100	parent_fleet hierarchy; seeds subfleet_id
Create a Fleet Vehicle	1200	Membership fixture
Create a Fleet Driver	1300	Membership fixture
Assign a Vehicle to a Fleet	3100	assigned: true
Reassign a Vehicle to a Fleet	3150	Idempotency
Assign a Driver to a Fleet	3200	assigned: true
Reassign a Driver to a Fleet	3250	Idempotency
Remove a Vehicle from a Fleet	4100	assigned: false
Remove a Vehicle from a Fleet Again	4150	Safe no-op
Remove a Driver from a Fleet	4200	assigned: false
Remove a Driver from a Fleet Again	4250	Safe no-op
Delete a Fleet Vehicle	4700	Cleanup
Delete a Fleet Driver	4800	Cleanup
Delete a Subfleet	4900	Child before parent

Assignments run before removals, memberships are removed before the resources
are deleted, and the subfleet is deleted before its parent.

Why the membership requests create their own vehicle and driver. The
Vehicles folder (order 6000) and the Drivers folder (7000) both delete their own
resource before the Fleets folder (9000) runs, so {{vehicle_id}} and
{{driver_id}} no longer resolve by then. Rather than let the membership
assertions fail on a stale id, the folder creates — and cleans up — a vehicle
and a driver of its own. {{vendor_id}} and {{service_area_id}} are still
reused, since those folders' resources are created earlier and are still live.

New collection variables, all narrowly named: parent_fleet_id, subfleet_id,
fleet_vehicle_id, fleet_driver_id, operational_driver_id.

Vehicles

• Create a Vehicle and Update a Vehicle document every safe business
  field the vehicle record holds: identity and description, odometer and
  measurement, body, capacity and dimensions, lifecycle and financing,
  regulatory and engine specifications, structured specs/details/meta,
  orchestrator constraints, and the vendor, driver, category and
  warranty relationships.
• The status enum is reconciled with the implementation. The collection
  documented three values (operational, maintenance, decommissioned) while
  the API accepts nineteen. All nineteen are now listed, with a note that
  active is stored as available.
• Query parameters documented, including internal_id — the lookup an importer
  keys on before deciding whether to create — plus plate_number, vin,
  public_id, vendor, driver and fleet.

Drivers

• email and phone are documented as optional, validated and unique when
  supplied.
• New Create an Operational Driver request for a driver with neither, plus
  Delete an Operational Driver to clean it up. Its description states
  plainly that such a driver cannot sign in to Navigator until credentials are
  supplied.
• Identity (internal_id, drivers_license_number, license_expiry,
  photo), operational (country, currency, city, online,
  current_status, status, location and telemetry), structured meta and
  orchestrator fields are all documented.
• password removed from the update contract — the API does not accept it
  there, and the dedicated password endpoints are referenced instead.
• Query parameters documented, including internal_id, drivers_license_number,
  phone, vehicle, vendor and fleet.

Response assertions

Every new and updated request carries its own afterResponse block rather than
relying on the collection-wide "2xx and JSON" test. Between them they assert:

• The expected success status, accepting 200/201 only where the contract
  genuinely permits either.
• The response is an object, or an array where the endpoint returns a bare
  array. No {data: ...} wrapper is assumed — none of these endpoints uses one.
• A public ID is present and carries the right prefix.
• Every submitted writable field comes back with the value that was sent —
  including the ones that used to be silently discarded: the vehicle odometer,
  and driver meta and internal_id.
• parent_fleet resolves to the parent's public ID, and a fleet is never its
  own parent.
• service_area, vendor and zone resolve to public IDs.
• Membership responses carry the expected fleet and resource IDs, assigned is
  true after an assignment and false after a removal, a repeated assignment
  stays successful and produces no duplicate logical membership, and a repeated
  removal is a successful no-op.
• A partial vehicle update leaves untouched fields alone — online in
  particular, which a partial update used to reset.
• No internal uuid column (uuid, company_uuid, *_uuid, auth_token,
  signup_token_used, _key) appears anywhere the public contract should
  expose a public ID.

Error examples were added for validation and cross-company behaviour:
422 for a self-parented fleet and for invalid vehicle input, 404 for a
cross-company parent_fleet, vendor, or membership resource, and 422 for a
malformed or duplicate driver contact detail.

Object definitions and examples

Fleets/, Vehicles/ and Drivers/ .resources/object.yaml were updated to
match the responses the API now returns, and the <string> placeholder examples
were replaced with realistic bodies. The Drivers examples previously documented
signup_token_used, phone_number and phone_country_code, none of which the
resource returns.

The Fleets folder description carries the membership endpoint contract and the
shared response shape.

Validation

• Lint

$ npm run postman:lint

Validated 5 Postman Native Git collections and 3 environments.
Linting Fleetbase API...          No issues found. Scanned: 212 | 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

This ran both scripts/validate-collections.js and the Postman Native Git
schema lint (Postman CLI 1.46.0 was available).

Live collection run: pending. npm run postman:run:fleetbase has not
been executed — no Fleetbase deployment carrying the Fleet-Ops branch was
available, and the new membership endpoints and expanded fields do not exist on
any currently deployed build, so a run would fail for the absence of the
implementation rather than for anything in this PR. The response assertions
above are therefore not claimed to have passed live. Once
fleetbase/fleetops#311 is deployed to a test environment:

npm run postman:run:fleetbase --  --env-var base_url=<test-api-url> --env-var api_key=<test-key>

Nothing here was run against production.

Documentation Impact

• Documentation needed but not included

API Reference Impact

• Updated fleetbase/postman

API reference notes: if the fleetbase.io API reference is generated from this
repository, it needs regeneration once this PR and
fleetbase/fleetops#311 land. No change was made to
fleetbase/fleetbase.io.

Risk

The changes are specification and test only. The one behavioural risk in a
contract run is ordering: the Fleets folder now creates two resources of its own
and deletes them at the end of the folder, and the driver-authentication and
password requests are untouched — driver_identity, driver_password and
driver_phone are still not written by any request here.

Confirmation

No credentials, real API keys, tokens, or customer data were committed. All
identifiers in examples are illustrative.