feat(subscriptions): add get, update, pause and resume (#78)

[karlwaldman]

Closes #78

What /v1/subscriptions is (established before any live call)

On oilpriceapi-api origin/main, /v1/subscriptions is V1::SubscriptionsController over the Watch model: agent "watches" that snapshot a set of commodity codes on an interval. It is deliberately separate from Billing::Subscription.

• pause calls @watch.paused!, resume calls @watch.active! plus arm_now!, and update accepts name, interval_seconds, deliver_webhook, status, codes. None of them touches Stripe or billing.
• Quota: WatchEvaluatorWorker dispatches due watches to WatchSnapshotWorker, which writes a WatchEvent and advances next_run_at. It records no api_requests row, so a live watch consumes no request quota between calls. CRUD calls count as normal requests, and events is excluded from quota (skip_after_action :track_request).
• Limits: WatchLimitPolicy#can_create? compares the count of active watches with ApiLimits::WATCH_LIMITS (free 1 … enterprise 1,000). A paused watch does not count. Watch#interval_at_or_above_tier_floor enforces MIN_INTERVAL_SECONDS (free 3,600s … 60s). An over-limit create returns 402 with an upgrade block; an update below the floor returns 422 VALIDATION_ERROR.

No member action changes what a customer is billed, so the live smoke was run.

Observed wire shapes (live, 2026-09-13, test key's own account)

Call	HTTP	Body
POST /v1/subscriptions	200	{status:"success", data:{subscription:{id, name, codes, interval_seconds, status:"active", deliver_webhook, source, tool_name, last_evaluated_at:null, next_run_at, created_at}}}
POST /v1/subscriptions/:id/pause	200	same envelope, status:"paused"
GET /v1/subscriptions/:id	200	same envelope
PATCH /v1/subscriptions/:id {name}	200	same envelope, renamed
PATCH … {interval_seconds:1}	422	{status:"fail", data:{error:"VALIDATION_ERROR", message:"Interval seconds is below your plan minimum of 60 seconds", details:{interval_seconds:[…]}}}
PATCH … {codes:["NOPE_NOT_A_CODE"]}	422	{status:"fail", data:{error:"VALIDATION_ERROR", message:"Codes contains invalid commodity codes: NOPE_NOT_A_CODE", details:{codes:[…]}}}
PATCH … {status:"sleeping"}	500	{error:{code:"INTERNAL_SERVER_ERROR", …}} (already tracked as OilpriceAPI/oilpriceapi-api#8471)
POST …/resume	200	same envelope, status:"active", next_run_at re-armed to now
DELETE /v1/subscriptions/:id	204	empty
GET after delete, unknown id	404	{error:{code:"NOT_FOUND", message:"Subscription not found", request_id, docs}}
GET /v1/subscriptions	200	{status:"success", data:{subscriptions:[…]}}

The raw probe created watch c27641db-012d-4a22-8939-e77fe05d7eb4, paused it immediately, and deleted it in finally (DELETE 204, then GET 404). Fixtures in tests/fixtures/subscriptions/ are those bodies byte for byte.

What changed

• get(id), update(id, params), pause(id), resume(id), each returning Subscription.
• UpdateSubscriptionParams { name?, codes?, interval?, deliverWebhook?, status? }. interval uses the same friendly mapping as create ("1h" → interval_seconds: 3600).
• Validation before sending: empty or non-string id, no fields, empty codes or a non-string code, an invalid interval, and a status other than active / paused (the API 500s on it).
• Ids are path-encoded ([P1][bug] 53 resource paths interpolate ids without encoding — webhooks.delete('../data-sources/x') sends DELETE to the wrong resource #92). PATCH stays non-replayable (fix(retry): never replay a non-idempotent write; bound every retry signal (#82) #88): a timed-out update throws with ambiguousWrite: true after exactly one attempt.
• 402 and 422 recovery details stay on rawBody (upgrade_trigger, limit, upgrade.next_tier; details.<field>).
• list() no longer returns [] when subscriptions is missing. It raises unexpected_response_shape; [] now means the API sent an empty list. create() and the new methods likewise raise on an envelope they cannot map instead of returning it as-is.
• README: a short "Watches" section covering the lifecycle, limits and the ambiguous-PATCH rule.

Breaking changes (for the 2.0.0 notes)

• subscriptions.list() throws unexpected_response_shape instead of resolving [] for a body without a subscriptions array, and no longer accepts a bare array (production never sends one).
• subscriptions.create() throws unexpected_response_shape instead of returning an unrecognised body typed as Subscription.

No version bump in any of the four places.

Red first

tests/resources/subscriptions.test.ts now drives the real client through a fetch mock (the old suite spied on the private request). tests/subscriptions-lifecycle.test-d.ts is new, in the typecheck project. Against unmodified src/:

⎯⎯⎯⎯⎯⎯ Failed Tests 42 ⎯⎯⎯⎯⎯⎯⎯
 Test Files  2 failed (2)
      Tests  42 failed | 15 passed (57)
Type Errors  4 failed
   1 AssertionError: expected [] to be an instance of OilPriceAPIError
   1 AssertionError: expected { …(2) } to be an instance of OilPriceAPIError
   1 AssertionError: expected { status: 'active' } to be an instance of OilPriceAPIError
   1 AssertionError: expected undefined to be 'unexpected_response_shape' // Object.is equality
   2 TypeCheckError: Property 'get' does not exist on type 'SubscriptionsResource'.
   2 TypeCheckError: Property 'pause' does not exist on type 'SubscriptionsResource'.
   2 TypeCheckError: Property 'resume' does not exist on type 'SubscriptionsResource'.
   3 TypeCheckError: Property 'update' does not exist on type 'SubscriptionsResource'.
   2 TypeCheckError: Unused '@ts-expect-error' directive.
   1 TypeError: c.subscriptions.get is not a function
   8 TypeError: client(...).subscriptions.update is not a function

expected [] to be an instance of OilPriceAPIError is the fabricated-default list() failing its new test.

Green

 Test Files  2 passed (2)
      Tests  57 passed (57)
Type Errors  no errors

Full suite and checks on the branch (baseline on main: 50 files, 703 passed / 1 skipped):

 Test Files  51 passed (51)
      Tests  742 passed | 1 skipped (743)
Type Errors  no errors
vitest=0 tsc=0 typecheck=0 lint=0 build=0 storefront=0 secrets=0

Live lifecycle smoke: ran, passed

tests/live/subscriptions.test.ts adds create → pause (immediately) → get → update → resume → pause → delete in finally, then asserts get raises NotFoundError. Run against production with the test key:

 Test Files  1 passed (1)
      Tests  3 passed (3)
   Duration  13.07s

Afterwards the account held only one watch, b84b24a0… mcp-live-contract-1788524538194 (active). That watch was leaked by the mcp-server live contract on 2026-09-04 and is filed as OilpriceAPI/mcp-server#126. It was not touched here.

Error messages in this PR's 404 test come from the canonical {error:{…}} envelope, which main already parses. The 422 test asserts rawBody only; message and code for fail-envelope bodies arrive with #114 (#111). Both PRs are green in either merge order.

Merge order

This PR, #113 (#108) and the #79 PR all add exports to src/index.ts in different blocks. Git should merge them cleanly in any order; if one conflicts, it will be adjacent export lines only.

🤖 Generated with Claude Code

https://claude.ai/code/session_015ao5paex73xXvuM424Libo

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: c6913125-c4c2-400d-9615-ecfbba5f04ce

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}