add-usage-tracking documents an `idempotency_key` parameter that the SDK does not have

[advaitpaliwal]

--- body below this line ---

Three corrections from integrating autumn-js@1.2.51 against these skills. All were verified against the published SDK's own dist, and the first one is a factual error rather than an omission.

1. idempotency_key is not a parameter. autumn/add-usage-tracking/SKILL.md says, under Gotchas:

4. Idempotency - Use idempotency_key to prevent double-counting

There is no such member in TrackParams, and the string idempotency does not appear anywhere in the shipped dist. Idempotency is an HTTP request header, Idempotency-Key, supplied through the per-call request options — RequestOptions extends Omit<RequestInit, ...>, so headers set there reach the wire:

await autumn.track(
  { customer_id, feature_id: "api_calls", value: 1 },
  { headers: { "Idempotency-Key": sourceEventId } },
);

Worth stating alongside it that the window is 24 hours and that a repeat within it returns 409, not a silent no-op — a caller that treats 409 as a failure to retry will loop, and one that treats it as an error will double-count on the compensating path. Docs that get this right: https://docs.useautumn.com/documentation/customers/edge-cases and https://docs.useautumn.com/api-reference/core/track

2. The client fails open by default, and no skill mentions it. new Autumn({...}) installs a fail-open hook unless you pass failOpen: false. It swaps in a fetcher that turns connection failures into a synthetic HTTP 555, then rewrites any response with status >= 500 for check, track, getOrCreateCustomer and getEntity into an HTTP 200 with a fabricated body — track yields {customer_id: null, value: 0, balance: null}, and getOrCreateCustomer yields a customer with subscriptions: []. See the FailOpenHook registration and FAIL_OPEN_BODIES in dist/backend/chunk-IVZOKPTN.mjs (around line 26406 in 1.2.51).

For a gate this is a reasonable availability default. For a meter it is silent revenue loss: during a provider outage track returns a success receipt while nothing is recorded, so any queue that dequeues on success discards billable usage, and a retry branch written for 5xx becomes unreachable. The fabricated zero-subscription customer is worse if it is cached, because it reads as "this customer pays for nothing".

Suggestion: say so in best-practices, and in add-usage-tracking recommend failOpen: false for metering specifically.

3. The retry default is one hour. retryConfig: { strategy: "backoff" } without an explicit backoff object retries until maxElapsedTime, whose default is 3,600,000 ms (same file, around line 26648). Fail-open hides this, because the rewritten 200 ends the loop on the first failure; turning fail-open off exposes it. Anyone following advice to enable backoff and to stop failing open gets both at once, so the two belong in the same paragraph.

Happy to send a PR for any or all of these if that is easier than patching it yourselves.