Skip to content

fix(maintenance)!: move warranties off the removed /preview paths and sync spec 2445b573294b - #17

Open
eastagiletracker wants to merge 1 commit into
TheEightBot:mainfrom
eastagiletracker:agile-board/graduate-maintenance-warranties
Open

eastagiletracker wants to merge 1 commit into
TheEightBot:mainfrom
eastagiletracker:agile-board/graduate-maintenance-warranties

Conversation

@eastagiletracker

Copy link
Copy Markdown

This PR proposes moving the warranty methods off the /preview/maintenance/* paths Samsara removed, and syncing the SDK to spec content 2445b573294b (Closes #16). We include this PR work along with a full history of your repo at https://eastagiletracker.com/projects/970. You can sign in with your GitHub ID to claim ownership of the project.

What was broken

Samsara deleted the nine warranty operations under /preview/maintenance/ and republished them, schema-identical, under /maintenance/* (tag Maintenance). Every IPreviewApisClient warranty method still calls the old paths, so they fail against the live API today. Reproduced on main at 2a3dbe7:

$ curl -s -o /dev/null -w '%{http_code}' https://api.samsara.com/preview/maintenance/warranties
404
$ curl -s -o /dev/null -w '%{http_code}' https://api.samsara.com/maintenance/warranties
401
$ python3 tools/check-sdk-sync.py --spec-file live-spec.json --fail-on-mismatch
  MISMATCHED:           9
Spec ops not implemented: 25
  GET     /preview/maintenance/warranties             PreviewApisClient.cs::ListWarrantiesAsync
  ...

(The unauthenticated probe is enough to tell the two apart: the removed route 404s before auth, the live one asks for a token.)

What changed

Following the steps in the issue: check-api-sync.py --update-baseline (the baseline diff is the reviewable spec change), then everything in its section 2, then check-sdk-fabrication.py --update-tags, the status block, the checklist docs and a CHANGELOG.md entry.

  • Warranties graduate to IMaintenanceClient, same signatures as before, plus the new ListWarrantyAssetAssignmentsAsync. The nine IPreviewApisClient members become [Obsolete] forwarders, the same pattern you used for CreateTachographFileUploadAsync. One difference: they delegate to MaintenanceClient instead of repeating the path, so there is a single implementation and no ALLOW_DUPLICATE / ALLOW_TAG_DRIFT entries are needed. The warranty records stay in Samsara.Sdk.Models.Preview so nobody's using breaks.
  • The other 16 new operations: vendor create/update/delete, vendor groups, technician shifts (the ID filters are explode=true, so they go out as repeated keys), maintenance sites, POST /maintenance/work-orders/attachments, and POST /fleet/asset-sharing/agreements/assets/cancel/batch (a bare { requestId, responses } body with per-asset status, read with PostAsync<T> rather than the data unwrap).
  • All 33 MEDIUM model findings (parts, purchase-order tax, work-order assignees and historical times, Trip.finalDistanceMeters/tripPurpose, the new MaintenanceVendor members), plus ListVendorsAsync's new externalIds/includeResolvedSettings filters so resolvedSettings can actually be requested.
  • UpdateDriverVehicleAssignmentRequest no longer requires driverId/vehicleId/startTime, since the spec now accepts metadata.sourceName instead. That brings the LOW count back from 7 to 4.

Compatibility: existing warranty callers keep compiling and start working again. They see CS0618 instead of the SAMSARA001 opt-in. The one source break is ListVendorsAsync: the two new filters sit before cancellationToken, so a caller passing the token positionally has to name it. That is why the commit is marked !.

Verification

Before and after, on this tree: dotnet build -c Release has 0 warnings. dotnet test tests/Samsara.Sdk.Tests -c Release went from 1341 passed to 1403 passed, with 0 failing before or after. The four checkers from the issue are green against the refreshed baseline: 396/396 ops, 0 mismatched, 0 tag drift, 0 CRITICAL/HIGH/MEDIUM. check-sdk-sync also passes against the live spec. render-sync-status.py --check passes. It was already stale on main, still showing hash ddbd93d89c05.

The new contract tests are WarrantyGraduationContractTests, MaintenanceSpecDriftContractTests and SpecDriftModelContractTests. They pin the verb, path and query placement of every new call, the request body names, and response binding. The shim test drives all nine IPreviewApisClient members and asserts that none of them touch /preview/. To confirm the tests catch the regression, I pointed MaintenanceClient's two warranty path constants back at preview/...: 9 of the 10 warranty tests went red. The tenth checks the [Obsolete] attributes.

Left alone on purpose:

  • The optional parameters Samsara added to four changed operations: DELETE /places externalId, GET /places hubIds, GET /assets/depreciation queryByTimeField, and GET /functions-storage/ls prefix/groupByFolder. None of the checkers report them, and surfacing folders from functions-storage/ls would change ListStorageFilesAsync's return type, which is your call.
  • [Experimental] on parts, preventive maintenance and preferred stations. Samsara moved those out of Beta APIs, and the --update-tags diff shows that, but whether to drop the opt-in is a policy decision for you.

How this was managed

We imported your issues and pull requests into a board and used it to manage this work. This change is tracked as https://eastagiletracker.com/projects/970/stories/1122535 on https://eastagiletracker.com/projects/970.

board

If you'd rather not receive contributions like this, reply no-more-prs on this pull request and we won't open any further ones on your repositories.


Lawrence W. Sinclair
CEO / East Agile
linkedin.com/in/lwsinclair/
eastagile.com

…nc spec 2445b573294b

Samsara removed the nine /preview/maintenance/warranties* and
/preview/maintenance/warranty-claims operations and republished them,
schema-identical, under /maintenance/* (tag Maintenance). The
IPreviewApisClient members kept calling the old paths, which now return
404 from the live API.

- IMaintenanceClient gains the ten graduated warranty/claim operations,
  including the new GET /maintenance/warranties/assets. The preview
  members become [Obsolete] forwarders, so existing callers keep
  compiling and start working again.
- Implement the rest of the drift: vendor writes and list filters,
  vendor groups, technician shifts, maintenance sites, work-order
  attachments and shared-asset batch cancellation.
- Add the new members on Part, PartInventoryLocation, PurchaseOrder,
  WorkOrder, ServiceTaskInstance, the work-order requests and Trip; relax
  UpdateDriverVehicleAssignmentRequest's composite key, which the spec no
  longer requires.
- Refresh the baseline with check-api-sync --update-baseline, the
  client-tag map with --update-tags, the status block and the docs.

All four checkers pass against the refreshed baseline (396/396 ops,
0 mismatched, 0 tag drift, 0 MEDIUM+), and against the live spec.

BREAKING CHANGE: ListVendorsAsync inserts two optional filters before
cancellationToken, so positional token callers must pass it by name.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

[api-sync] Samsara spec drift (2025-10-23, content 94654d38db61 → 6fe410fad840)

1 participant