fix(order-sync): Stop retrying after a terminal 401/403, back off on 429, and tell the merchant

[ackm04]

Summary

One store's API key lacked the orders:write scope. The plugin sent POST /v1/integrations/woocommerce/order-sync about every 3 seconds: 444 refusals (HTTP 403) in 50 minutes, and the merchant was never told.

Nothing in the plugin looped. Action Scheduler does not re-run a callback that returns. Every order trigger (creation, each status change, each admin save) pushed again with a key that could never succeed, because a refusal was treated like a timeout.

New Tack_Sync_Gate applies the temporary/terminal split the TackQuote API uses:

• Terminal: a 401 or 403 carrying TackQuote's own JSON error body. That means statusCode equal to the HTTP status and a non-empty code (insufficient_scope, SUBSCRIPTION_INACTIVE, an invalid or revoked key).
  • Pushes stop, and a wp-admin notice-error names the missing scope or the billing step (Profile > Billing & Plan).
  • Sync re-probes at most once an hour; saving a different key lifts the block at once.
  • A 429 that carries the scope refusal stays terminal, held until max(Retry-After, 1 h), so the notice does not flicker.
• Throttled: any other 429 waits for Retry-After (seconds or an HTTP-date), capped at one hour.
• Temporary: everything else, including a 403 whose body is HTML or a proxy's JSON (a firewall or challenge page).
• When a block lifts, orders modified since it began are re-queued through the normal worker. This is bounded to 200 orders and 30 days, logs when it truncates, and the sync key skips anything already accepted.
• Only a 16-character sha256 prefix of the key is stored. uninstall.php removes the new option.

No wire-contract change. The plugin reads fields the API already sends. The server half (scope 403, then 429 with Retry-After, then a daily seller notice) is already live on api.tackquote.com.

Vendor sources:

• Action Scheduler retry semantics and as_enqueue_async_action (Context7 /woocommerce/action-scheduler);
• the wc_get_orders date_modified => '>' . ts form (Context7 /woocommerce/woocommerce, docs/features/orders/wc-get-orders.md);
• WP_Error data and wp_remote_retrieve_header (developer.wordpress.org).

The readme has an Unreleased changelog entry. The version bump and tag are left to the owner.

Gates (php:8.2-cli via docker run --rm, through ~/bin/tack-heavy)

Gate	Exit
php -l on every PHP file	0
php tests/run.php on this branch	0 (All checks passed)
Red-first: today's tests against pre-fix api client + order sync	255 (RED: classification and data checks fail)
Red-first: today's tests against pre-fix includes/ entirely	255 (RED)
Mutant: terminal no longer requires statusCode === status	1 (killed)
Mutant: 429 scope refusal treated as a plain throttle	1 (killed)
Mutant: lift() stops announcing the unblock	1 (killed)
Mutant: TERMINAL_REPROBE 3600 -> 3	1 (killed)
Mutant: run_sync no longer consults the gate	1 (killed)
Mutant: key-change hook not registered	1 (killed)

One equivalent mutant was omitted: dropping the json term cannot change an outcome, because statusCode is only non-zero when the body parsed as JSON.

🤖 Generated with Claude Code