sp-api-drift

Amazon's Selling Partner API ships weekly model updates with no semantic changelog, and its flat-file reports (GET_MERCHANT_LISTINGS_ALL_DATA, GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE_V2, GET_FBA_INVENTORY_PLANNING_DATA, ...) have no OpenAPI schema at all — so a spec differ like oasdiff can't see a report column disappear. sp-api-drift locks the column set, order, type, and whitespace fingerprint of a report you already pull, and fails on the next run if any of it silently changed.

It doesn't touch your Amazon credentials. Point it at report files you've already downloaded.

Install

npm install -g sp-api-drift

Use

sp-api-drift init --report-type GET_MERCHANT_LISTINGS_ALL_DATA --file ./reports/listings.tsv
sp-api-drift check --report-type GET_MERCHANT_LISTINGS_ALL_DATA --file ./reports/listings.tsv

init writes .sp-api-drift.lock.json — commit it. check diffs a fresh pull against the lockfile and exits 1 on breaking drift (column removed, type changed, delimiter changed), so it works as a CI step or pre-sync guard:

[BREAKING] column-removed: column "Status" is present in the lockfile but missing from the current report
[warning] whitespace-changed: column "Merchant Shipping Group" whitespace fingerprint changed from clean to present

1 breaking, 1 warning finding(s) for GET_MERCHANT_LISTINGS_ALL_DATA

That's the actual shape of drift Amazon has shipped in production — see amzn/selling-partner-api-models#5131 (buyerEmail dropped from the Orders API, open six months, no release-note entry) and the report-column removals tracked in the same repo's issues.

Telemetry (opt-in, off by default)

--telemetry-url <url> (or SP_API_DRIFT_TELEMETRY_URL) POSTs a fingerprint of the current schema — column names, order, inferred types, a hash — never row data. This is the client side of a hosted cross-tenant drift feed ("this column vanished for 41% of observed accounts starting Tuesday") that doesn't exist yet. The flag ships now so nobody has to retrofit it later.

What this isn't

It doesn't diff the OpenAPI spec — oasdiff already does that well and for free against amzn/selling-partner-api-models. sp-api-drift covers the surfaces that have no spec to diff: flat-file report columns and whatever undocumented shape changes show up in data you already have.

Built autonomously by an AI agent (fernforge).