feat(worker): premium webhook watches (price + status, signed POST delivery)

Agents can now register watches that fire HMAC-signed webhooks when a
model price crosses a threshold or a provider's status changes. Phase 1
of the recurring/event-driven billing path.

Endpoints (under /api/premium/watches):
  POST    register a watch (1 credit). Body: { spec, callback_url, secret?, fire_cap? }
  GET     list watches owned by the bearer token (free)
  GET     /{id}  read one watch + fire metadata (free, owner-only)
  DELETE  /{id}  remove a watch (free, owner-only)

Watch types in v1:
  price   { model, field: inputPrice|outputPrice|blended, op: lt|gt|changes, threshold? }
  status  { provider, op: becomes|changes, value? }

Predicates fire only on edge transitions (debounced) so a watch on
"Opus 4.7 inputPrice < $10" fires once when the price crosses, not on
every poll while the price stays below. Watches live 90 days, fire up
to fire_cap times (default 100), capped at 25 active watches per token.

Delivery: signed POST to callback_url with X-TensorFeed-Signature
(HMAC-SHA256 over the body using the watch's secret) and
X-TensorFeed-Watch-Id headers. Fire-and-forget with 8-second timeout.
Basic SSRF guard rejects http://, localhost, RFC1918, link-local, and
loopback addresses.

Cron integration:
  - Status dispatch hooks into pollStatusPages (every 5 min) using the
    same transition detection the incident detector already runs on.
  - Price dispatch runs daily after updateCatalog via runPriceWatchCycle,
    diffing the freshly-merged pricing payload against a watch-owned
    previous snapshot at watch:prev:pricing.

Storage layout (TENSORFEED_CACHE):
  watch:{id}              full Watch record (90-day TTL)
  watch:index:price       string[] of watch IDs (single-key lookup per cron)
  watch:index:status      string[]
  watch:byToken:{token}   string[] for owner listing
  watch:prev:pricing      last seen pricing payload for diff baseline

Tests: 30 new vitest cases covering URL validation (SSRF), spec
validation, predicate edge transitions, transition computation,
HMAC determinism, CRUD lifecycle, ownership enforcement, and
end-to-end dispatch with stubbed fetch. Total worker tests: 63.

Updated /api/meta, public/llms.txt, /developers/agent-payments,
and CLAUDE.md to advertise the new endpoints.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: RipperMercs

CLAUDE.md

@@ -38,6 +38,9 @@ tensorfeed/
       routing.ts      Tier 2 routing recommendation engine + free preview rate limiter
       routing.test.ts Vitest unit tests for the routing engine (pure-logic, no chain)
       payments.ts     Payment middleware: credits + x402 fallback, USDC on Base verification, daily rollup analytics
+      history-series.ts  Premium history series: pricing/benchmark series, status uptime, snapshot diff
+      watches.ts      Premium webhook watches: register, predicate eval, HMAC-signed POST delivery, cron-driven dispatch
+      watches.test.ts Vitest coverage for predicate edge transitions, SSRF guard, dispatch end-to-end
       podcasts.ts     Podcast feed polling
       trending.ts     Trending GitHub repos
       twitter.ts      X/Twitter auto-posting
@@ -195,6 +198,9 @@ All mounted under `https://tensorfeed.ai/api/*` via the Worker.
 - `/api/premium/history/benchmarks/series?model=&benchmark=&from=&to=`: Tier 1, 1 credit. Score evolution for a single benchmark on one model. Returns delta in percentage points.
 - `/api/premium/history/status/uptime?provider=&from=&to=`: Tier 1, 1 credit. Daily uptime % for one provider (degraded counts as half) with incident-day list. Missing-data days excluded from denominator.
 - `/api/premium/history/compare?from=&to=&type=pricing|benchmarks`: Tier 1, 1 credit. Diff two daily snapshots: added, removed, changed entries with deltas.
+- `/api/premium/watches` (POST): Tier 1, 1 credit per registration. Body `{ spec, callback_url, secret?, fire_cap? }`. Spec is `{ type: "price"|"status", ... }`. Watch lives 90 days, default fire cap 100. Fires deliver HMAC-signed POST to callback URL.
+- `/api/premium/watches` (GET): List watches owned by the bearer token. Free.
+- `/api/premium/watches/{id}` (GET|DELETE): Read or remove an owned watch. Free.
 
 **Admin (auth-gated via `?key=ENVIRONMENT`):**
 - `/api/admin/usage?date=YYYY-MM-DD`: Daily revenue + usage rollup
@@ -308,6 +314,8 @@ Key modules:
 - `worker/src/payments.ts`: middleware (`requirePayment`), USDC verification, quote/confirm/balance, daily rollup analytics
 - `worker/src/routing.ts`: routing engine + free preview rate limiter
 - `worker/src/history.ts`: daily snapshot capture (the data moat)
+- `worker/src/history-series.ts`: premium aggregated views (series, uptime, compare) over the daily snapshots
+- `worker/src/watches.ts`: premium webhook watches; status dispatch hooks into `pollStatusPages` (every 5 min), price dispatch runs daily after `updateCatalog`
 
 SDKs:
 - Python: `sdk/python/` (1.2.0). `pip install tensorfeed[web3]` enables `tf.purchase_credits()` for one-call sign-and-send. See `sdk/python/PUBLISHING.md` for the PyPI release flow.

public/llms.txt

@@ -53,6 +53,7 @@ TensorFeed accepts USDC on Base as the sole payment method for premium endpoints
 - [Premium Benchmark Series](https://tensorfeed.ai/api/premium/history/benchmarks/series): Tier 1, 1 credit per call. Score evolution for a single benchmark (e.g. swe_bench, mmlu_pro, gpqa_diamond, math, human_eval) on one model. Params: `?model=&benchmark=&from=&to=`. Range capped at 90 days.
 - [Premium Status Uptime](https://tensorfeed.ai/api/premium/history/status/uptime): Tier 1, 1 credit per call. Daily status rollup for one provider with operational/degraded/down day counts, uptime % (degraded counts as half), and incident-day list. Params: `?provider=&from=&to=`.
 - [Premium History Compare](https://tensorfeed.ai/api/premium/history/compare): Tier 1, 1 credit per call. Diff between two daily snapshots: added, removed, and changed entries with deltas. Params: `?from=YYYY-MM-DD&to=YYYY-MM-DD&type=pricing|benchmarks`.
+- [Premium Watches](https://tensorfeed.ai/api/premium/watches): Tier 1, 1 credit per registration. Webhook alerts for price changes (`{ type: "price", model, field: "inputPrice"|"outputPrice"|"blended", op: "lt"|"gt"|"changes", threshold? }`) or service status transitions (`{ type: "status", provider, op: "becomes"|"changes", value? }`). POST `{ spec, callback_url, secret? }` to register, GET to list, GET/DELETE on `/api/premium/watches/{id}` for individual control. Each watch lives 90 days, fires up to 100 times by default, delivers a signed POST to the callback URL with `X-TensorFeed-Signature: sha256=<hex>` and an `X-TensorFeed-Watch-Id` header. Listing and per-watch read/delete require the bearer token but cost no credits.
 
 **Recommended flow:** POST `/api/payment/buy-credits`, send USDC, POST `/api/payment/confirm`, then use the returned token for all premium calls. **Fallback (x402):** call any `/api/premium/*` endpoint without auth to receive a 402 response with payment instructions; send USDC and retry with `X-Payment-Tx: <txHash>` header.
 

src/app/developers/agent-payments/page.tsx

@@ -226,6 +226,32 @@ const ENDPOINTS: PremiumEndpoint[] = [
     { "model": "GPT-5.5", "field": "inputPrice", "from": 12, "to": 10, "delta_pct": -16.67 }
   ],
   "unchanged_count": 8
+}`,
+  },
+  {
+    method: 'POST',
+    path: '/api/premium/watches',
+    description:
+      'Register a webhook watch on a price change or service status transition. Each watch lives 90 days and fires up to 100 times by default. Deliveries POST to your callback URL with an HMAC-SHA256 signature header (X-TensorFeed-Signature: sha256=...). Per-token cap of 25 active watches. Listing and per-watch read/delete are free for the owning bearer token.',
+    cost: '1 credit per registration',
+    example: `// Body: { spec, callback_url, secret?, fire_cap? }
+// Spec types:
+//   { type: "price", model, field: "inputPrice"|"outputPrice"|"blended",
+//     op: "lt"|"gt"|"changes", threshold? }
+//   { type: "status", provider, op: "becomes"|"changes",
+//     value?: "operational"|"degraded"|"down" }
+{
+  "ok": true,
+  "watch": {
+    "id": "wat_a1b2c3d4e5f60718a9b0c1d2",
+    "spec": { "type": "price", "model": "Claude Opus 4.7",
+              "field": "blended", "op": "lt", "threshold": 30 },
+    "callback_url": "https://agent.example.com/hook",
+    "created": "2026-04-27T18:00:00Z",
+    "expires_at": "2026-07-26T18:00:00Z",
+    "fire_count": 0, "fire_cap": 100, "status": "active"
+  },
+  "billing": { "credits_charged": 1, "credits_remaining": 49 }
 }`,
   },
 ];

worker/src/index.ts

@@ -17,6 +17,13 @@ import {
   MAX_RANGE_DAYS,
   DEFAULT_RANGE_DAYS,
 } from './history-series';
+import {
+  createWatch,
+  getWatch,
+  listWatchesForToken,
+  deleteWatch,
+  runPriceWatchCycle,
+} from './watches';
 import { computeRouting, checkRoutingPreviewRateLimit, hoursUntilUTCRollover, RoutingTask } from './routing';
 import {
   requirePayment,
@@ -471,6 +478,9 @@ export default {
           premiumBenchmarkSeries: '/api/premium/history/benchmarks/series?model=&benchmark=&from=&to=',
           premiumStatusUptime: '/api/premium/history/status/uptime?provider=&from=&to=',
           premiumHistoryCompare: '/api/premium/history/compare?from=&to=&type=pricing|benchmarks',
+          premiumWatchesCreate: 'POST /api/premium/watches (1 credit per registration)',
+          premiumWatchesList: 'GET /api/premium/watches',
+          premiumWatchesItem: 'GET|DELETE /api/premium/watches/{id}',
           paymentInfo: '/api/payment/info',
           paymentBuyCredits: '/api/payment/buy-credits',
           paymentConfirm: '/api/payment/confirm',
@@ -856,6 +866,80 @@ export default {
       return premiumResponse(result, payment, 1);
     }
 
+    // === PAID PREMIUM: WATCHES (webhook alerts) ===
+    // Registration costs 1 credit. Read/list/delete are free for the
+    // bearer token that owns the watch (no charge, but token required).
+
+    if (path === '/api/premium/watches' && request.method === 'POST') {
+      const payment = await requirePayment(request, env, 1);
+      if (!payment.paid) return payment.response!;
+      if (!payment.token) {
+        return jsonResponse(
+          { ok: false, error: 'token_required', message: 'Watch creation requires a bearer token (use /api/payment/buy-credits).' },
+          401,
+        );
+      }
+      let body: { spec?: unknown; callback_url?: string; secret?: string; fire_cap?: number };
+      try {
+        body = await request.json();
+      } catch {
+        return jsonResponse({ ok: false, error: 'invalid_json' }, 400);
+      }
+      if (typeof body.callback_url !== 'string') {
+        return jsonResponse({ ok: false, error: 'callback_url_required' }, 400);
+      }
+      const result = await createWatch(env, payment.token, {
+        spec: body.spec as never,
+        callback_url: body.callback_url,
+        ...(typeof body.secret === 'string' ? { secret: body.secret } : {}),
+        ...(typeof body.fire_cap === 'number' ? { fire_cap: body.fire_cap } : {}),
+      });
+      if (!result.ok) {
+        return jsonResponse(result, 400);
+      }
+      ctx.waitUntil(
+        logPremiumUsage(env, '/api/premium/watches', request.headers.get('User-Agent') || 'unknown', 1),
+      );
+      return premiumResponse(result, payment, 1);
+    }
+
+    if (path === '/api/premium/watches' && request.method === 'GET') {
+      // Listing requires a bearer token but no credits.
+      const authHeader = request.headers.get('Authorization');
+      const token = authHeader?.startsWith('Bearer ') ? authHeader.slice(7).trim() : '';
+      if (!token || !token.startsWith('tf_live_')) {
+        return jsonResponse({ ok: false, error: 'token_required' }, 401);
+      }
+      const watches = await listWatchesForToken(env, token);
+      return jsonResponse({ ok: true, count: watches.length, watches }, 200, 0);
+    }
+
+    const watchMatch = path.match(/^\/api\/premium\/watches\/(wat_[a-f0-9]{24})$/);
+    if (watchMatch) {
+      const id = watchMatch[1];
+      const authHeader = request.headers.get('Authorization');
+      const token = authHeader?.startsWith('Bearer ') ? authHeader.slice(7).trim() : '';
+      if (!token || !token.startsWith('tf_live_')) {
+        return jsonResponse({ ok: false, error: 'token_required' }, 401);
+      }
+      if (request.method === 'GET') {
+        const watch = await getWatch(env, id);
+        if (!watch) return jsonResponse({ ok: false, error: 'watch_not_found' }, 404);
+        if (watch.token !== token) return jsonResponse({ ok: false, error: 'forbidden' }, 403);
+        return jsonResponse({ ok: true, watch }, 200, 0);
+      }
+      if (request.method === 'DELETE') {
+        const result = await deleteWatch(env, id, token);
+        if (!result.ok) {
+          return jsonResponse(
+            result,
+            result.error === 'watch_not_found' ? 404 : result.error === 'forbidden' ? 403 : 400,
+          );
+        }
+        return jsonResponse({ ok: true }, 200, 0);
+      }
+    }
+
     // === ADMIN: usage and revenue rollup (auth-gated) ===
     // Same key pattern as /api/refresh: ?key=<ENVIRONMENT>. At MVP scale
     // this is sufficient; if/when revenue is real, swap to a dedicated
@@ -1029,6 +1113,9 @@ export default {
       // pricing, models, benchmarks, status, agent activity. Runs after
       // updateDailyData so the snapshot reflects freshly-updated data.
       await run('captureHistory', () => captureHistory(env));
+      // Premium webhook watches: fire price-change webhooks based on the
+      // diff between the last seen pricing and the freshly-updated payload.
+      await run('runPriceWatchCycle', () => runPriceWatchCycle(env));
     // X/Twitter: 1 post/day, re-enabled 2026-04-12 after spam flag on 2026-04-04.
     // Hold at 1/day until 2026-05-04; do not increase cadence without 30 clean days.
     } else if (cron === '30 14 * * *') {

worker/src/status.ts

@@ -1,5 +1,6 @@
 import { Env, ServiceStatus, StatusPageResponse } from './types';
 import { STATUS_PAGES } from './sources';
+import { dispatchStatusWatches, StatusTransition } from './watches';
 
 function normalizeStatus(indicator: string): 'operational' | 'degraded' | 'down' | 'unknown' {
   switch (indicator?.toLowerCase()) {
@@ -142,6 +143,7 @@ export async function pollStatusPages(env: Env): Promise<void> {
   const previousRaw = await env.TENSORFEED_STATUS.get('previous-status', 'json') as
     { name: string; status: string; provider: string }[] | null;
 
+  const watchTransitions: StatusTransition[] = [];
   if (previousRaw) {
     const prevMap = new Map(previousRaw.map(s => [s.name, s]));
     const incidentsRaw = await env.TENSORFEED_STATUS.get('incidents', 'json') as Incident[] | null;
@@ -158,6 +160,15 @@ export async function pollStatusPages(env: Env): Promise<void> {
       if (prevStatus === curStatus) continue;
       if (curStatus === 'unknown' || prevStatus === 'unknown') continue;
 
+      // Collect for premium watch dispatch (fires only on real transitions,
+      // matching the same edge filter the incident detector uses).
+      watchTransitions.push({
+        provider: current.provider,
+        name: current.name,
+        from: prevStatus as StatusTransition['from'],
+        to: curStatus as StatusTransition['to'],
+      });
+
       // Service went from operational to degraded/down
       if (prevStatus === 'operational' && (curStatus === 'degraded' || curStatus === 'down')) {
         const incident: Incident = {
@@ -203,6 +214,20 @@ export async function pollStatusPages(env: Env): Promise<void> {
   const down = statuses.filter(s => s.status === 'down').length;
 
   console.log(`Status poll complete - ${operational} operational, ${degraded} degraded, ${down} down`);
+
+  // Premium watch dispatch (no-op when no watches are subscribed)
+  if (watchTransitions.length > 0) {
+    try {
+      const summary = await dispatchStatusWatches(env, watchTransitions);
+      if (summary.watches_fired > 0) {
+        console.log(
+          `status watches fired: ${summary.watches_fired} of ${summary.watches_evaluated} (failures: ${summary.delivery_failures})`,
+        );
+      }
+    } catch (e) {
+      console.error('dispatchStatusWatches failed:', e instanceof Error ? e.message : e);
+    }
+  }
 }
 
 export interface Incident {