Skip to content

feat(fleetbase-api): driver manifests and driver password endpoints - #53

Merged
roncodes merged 2 commits into
mainfrom
feat/driver-manifests-and-password-endpoints
Aug 31, 2026
Merged

feat(fleetbase-api): driver manifests and driver password endpoints#53
roncodes merged 2 commits into
mainfrom
feat/driver-manifests-and-password-endpoints

Conversation

@roncodes

@roncodes roncodes commented Aug 23, 2026

Copy link
Copy Markdown
Member

Documents the consumable endpoints added in
fleetops#304 and
fleetops#305.

Drivers — password management

Request Endpoint
Change Driver Password POST /drivers/:id/change-password
Request Driver Password Reset POST /drivers/forgot-password
Reset Driver Password POST /drivers/reset-password

A password change is an authorisation decision rather than an attribute update,
which is why it is not part of PUT /drivers/:idthat endpoint no longer
accepts a password at all
, which is the security fix in fleetops#304.

The descriptions carry the two properties a caller needs to know and cannot
discover by trying:

  • the reset request answers identically whether or not the identity exists,
    so it cannot be used to enumerate an organization's drivers
  • a wrong code, an expired code and an unknown identity all return the same
    error
    , so reset is not an oracle either

Manifests — a new folder

Request Endpoint
List Driver Manifests GET /drivers/:id/manifests
Retrieve a Manifest GET /manifests/:id
Update a Manifest Stop PATCH /manifest-stops/:id
Optimize a Manifest POST /manifests/:id/optimize

A manifest is a driver's route: an order-agnostic sequence of stops which may
span several orders, or none the driver has seen as an order. Retrieve returns
the stops in sequence with their places inline, so a route of twenty stops is
one request rather than twenty-one.

The optimize description says plainly what it is — a nearest-neighbour walk
over road distances
, usually a large improvement on an arbitrary order and not
guaranteed optimal. It reorders the stops of one assigned manifest rather than
allocating work across a fleet, which is what the orchestrator does. Completed
and skipped stops keep their place.

Creating, cancelling and deleting a manifest are dispatch operations and are
deliberately absent — they are not part of the consumable API.

Listing a driver's manifests sits with the other driver-scoped requests rather
than in the new folder, next to List Driver Organizations.

Validation

npm run postman:lint
Linting Fleetbase API...  No issues found.
Scanned: 196 | Errors: 0 | Warnings: 0

Not included: response examples

The endpoints are still in review on the fleetops release branch. An example
recorded against an unmerged branch would be a guess rather than verified
behaviour, and this repo's own rules ask for spec updates backed by verified
API behaviour. Happy to add them in a follow-up once fleetops#304 and #305 merge
— say the word and I will capture real responses against dev-v0.6.61.


Merge order

  1. ci: seed the driver password-reset code the contract run needs fleetbase#636 — seeds the driver_password_reset code this collection needs.
  2. This PR.

fleetbase/fleetops#304 and #305 are already merged to dev-v0.6.61, so the endpoints themselves exist.

Running unattended

The collection asserts that every request returns 2xx, so a request that cannot succeed on its own
reads as a broken endpoint rather than as an untestable one.

  • Create a Driver seeds a password and captures the generated email and phone under
    created_driver_*. It deliberately does not write driver_identity, driver_password or
    driver_phone: those name the driver a contract run seeds and injects, and Login Driver, Request
    Driver Login SMS and Verify Driver Login Code authenticate as it. Writing the throwaway driver's
    details there signed all three in as an account deleted a few requests earlier.
  • Ordering. The password requests run before Delete a Driver rather than after it.
  • The Manifests folder is ordered after Orchestrator, because POST /orchestrator/commit is what
    creates a manifest — it returns the ids it created, and that is where the folder gets one. Retrieve
    a Manifest then passes a stop id to Update a Manifest Stop.
  • Reset Driver Password asks for a code issued for a password reset, not a login code — the
    endpoint matches on purpose as well as on value — and sets the password back to the one already in
    force, so the run stays repeatable and the login requests below still authenticate.
  • Request Driver Password Reset addresses a reserved address (RFC 2606) that belongs to nobody.
    The endpoint answers identically for an unknown identity — deliberately, so it cannot enumerate
    drivers — so it is still exercised and no stranger receives a reset code.

pm.execution.skipRequest() is not a skip

An earlier revision guarded the requests that need a fixture with pm.execution.skipRequest(). The
Postman CLI reports that as "Request could not be completed" — a run error, which fails the
contract exactly as a bad response would. Every guard is gone; each request now has something real to
address instead.

Verified

npm run postman:lint is clean (196 requests, 0 errors, 0 warnings). POST /drivers/{id}/change-password
and GET /drivers/{id}/manifests were both confirmed 200 against a live instance running the merged
dev-v0.6.61.

Response examples still to add.

Documents the consumable endpoints added in fleetops#304 and fleetops#305.

Drivers gains three password requests. A password change is an authorisation
decision rather than an attribute update, which is why it is not part of
PUT /drivers/:id — that endpoint no longer accepts a password at all. The
descriptions carry the two properties a caller needs to know about and cannot
discover by trying: the reset request answers identically whether or not the
identity exists, so it cannot be used to enumerate an organization's drivers,
and a wrong code, an expired code and an unknown identity all return the same
error.

A new Manifests folder covers the route a driver actually drives — a manifest is
an order-agnostic sequence of stops which may span several orders, or none the
driver has seen as an order. Retrieve returns the stops in sequence with their
places inline, so a route of twenty stops is one request rather than twenty-one.

The optimize description says plainly what it is: a nearest-neighbour walk over
road distances, usually a large improvement on an arbitrary order and not
guaranteed optimal, which reorders the stops of one assigned manifest rather
than allocating work across a fleet the way the orchestrator does. Completed and
skipped stops keep their place.

Listing a driver's manifests sits with the other driver-scoped requests rather
than in the new folder, next to List Driver Organizations.

No response examples yet: the endpoints are still in review on the fleetops
release branch, and an example recorded against an unmerged branch would be a
guess rather than verified behaviour. Happy to add them once merged.

npm run postman:lint — 196 requests scanned in Fleetbase API, 0 errors,
0 warnings.
The collection asserts every request returns 2xx, so a request that
cannot succeed unattended reads as a broken endpoint.

- Create a Driver seeds a known password and captures the generated
  email and phone. They are generated inline, so the response is the
  only place to read them back, and without them the password requests
  had no identity and no current password to prove.
- The password and manifest requests run before Delete a Driver rather
  than after it. At 13000 they addressed a driver deleted at 5000.
- Reset Driver Password skips itself: its code arrives by email or SMS,
  which an automated run cannot read.
- Request Driver Password Reset addresses a reserved address that
  belongs to nobody. The endpoint answers identically for an unknown
  identity, so it is still exercised and no stranger is sent a code.
- The manifest requests skip themselves when the run found no manifest.
@roncodes
roncodes merged commit 656d608 into main Aug 31, 2026
1 check passed
@roncodes
roncodes deleted the feat/driver-manifests-and-password-endpoints branch August 31, 2026 04:12
@roncodes

Copy link
Copy Markdown
Member Author

The follow-up for the FleetOps contract failures this introduced is #57 — this branch's later pushes landed after the merge, so they were not part of what shipped here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant