+ Step-by-step for the operator who needs to turn this on in production, verify it's working, and respond to + the cards that show up in the channel. Read top to bottom for first-time setup; jump to + troubleshooting when something looks off. +
+ ++ Once enabled, every successful hourly Anthropic cost sync posts up to three kinds of Adaptive Cards into one + Microsoft Teams channel: +
+ ++ A fourth card — stale-data warning — replaces the digest when the cost sync hasn't completed + in over 70 minutes, so silent ingestion outages don't look like "everything's fine." +
+ ++ See the mockup for the exact visual layout of each card type. +
+ + +Before you start, confirm:
+ +/claude and confirm the "Synced N minutes ago" pill in the header isn't showing a stale-data warning.+ Microsoft retired the legacy O365 Connector incoming webhooks in May 2026. The replacement is the + Workflows app (Power Automate template). The URL you provision below is an HMAC-signed Logic + Apps trigger — treat it like a secret. +
+ +In Microsoft Teams, navigate to the team and channel that should receive the alerts (e.g., + "Unic · FinOps for AI > Claude Spend Alerts").
+Click the ⋯ menu next to the channel name → Workflows. (If you don't see
+ Workflows, search the app store and add it to the team.)
Search for "Post to a channel when a webhook request is received" (also listed as + "Send webhook alerts to a channel"). Select it.
+The dialog asks who the workflow runs as. Pick a generic service account if your team has one — if not, + a personal account is fine, but be aware: when that person leaves, the workflow stops working until + re-provisioned.
+Auto-populated if launched from the channel. Click Add workflow / Save.
+The URL looks like:
+https://prod-XX.<region>.logic.azure.com:443/workflows/<workflow-id>/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=<SIGNATURE>+
The sig= query parameter is the HMAC. Anyone with this URL can post to the channel.
+ Do not paste it into Slack, email, or commit it.
Vercel dashboard → AI Developer Hub project → Settings → Environment Variables.
+TEAMS_WEBHOOK_URL
+
+ Name: TEAMS_WEBHOOK_URL
+ Value: the Workflows URL you copied above
+ Environments: Production (and optionally Preview if you have a
+ separate staging Teams channel)
+
TEAMS_DASHBOARD_BASE_URL (optional)
+
+ Used to build the "Open dashboard" / "Open workspace" link buttons inside each card. Defaults to
+ NEXTAUTH_URL if unset, so you only need this if your card-target host differs (e.g., a
+ custom domain). Example: https://hub.unic.com.
+
Vercel doesn't hot-load env changes for the running production deployment. Trigger a redeploy:
+vercel redeploy --prod+
Or push a no-op commit. The next cron run after deploy picks up the new env.
+If you want to test cards while developing, add to .env.local in your worktree:
# .env.local +TEAMS_WEBHOOK_URL="https://prod-XX.region.logic.azure.com/workflows/.../invoke?...&sig=..." +TEAMS_DASHBOARD_BASE_URL="http://localhost:3000"+ +
Restart the dev server (env is read at boot). Then trigger a sync manually:
+ +curl -X GET http://localhost:3000/api/sync/anthropic-api-costs \
+ -H "Authorization: Bearer $CRON_SECRET"
+
+ .env.local is gitignored, but it's worth checking once: git check-ignore .env.local
+ should print the path. If TEAMS_WEBHOOK_URL ever ends up in git status, treat the
+ URL as compromised and rotate it (delete + recreate the workflow).
+ + The cron runs every hour, so the quickest way to confirm wiring is to trigger it manually. From a machine + with the cron secret (or via the Vercel dashboard's Cron Jobs > "Run now"): +
+ +curl -X GET https://hub.unic.com/api/sync/anthropic-api-costs \
+ -H "Authorization: Bearer $CRON_SECRET"
+
+ Expected response within ~10 seconds:
+ +{"ok": true, "eventId": 2827}
+
+ Within seconds of that, your Teams channel should see at least the hourly digest card.
+ +| You see | What it means |
|---|---|
| Just the digest card | +Healthy. No threshold breaches and no forecast-at-risk transitions this run. | +
| Digest + one or more breach/forecast cards | +First time the alert state for those workspaces was evaluated against the current month. Subsequent runs won't re-fire the same thresholds. | +
| Only a yellow "stale-data" card | +The cost sync is more than 70 minutes behind. The evaluator suppressed the digest and other cards to avoid posting stale numbers. Fix the sync first. | +
| Nothing in the channel | +See Troubleshooting § "No cards appearing". | +
The cron handler logs a one-line summary every run. In Vercel logs (Runtime → Filter by route
+ /api/sync/anthropic-api-costs), look for:
[anthropic-api-costs] teams alerts posted=4 skipped=-+ +
The numbers tell you what happened — posted=N is the total cards POSTed this run,
+ skipped=... is any kill-switch / stale-data reason. posted=0 skipped=webhook_disabled
+ means the env var isn't set on this environment yet.
+ The Anthropic cost sync runs hourly. That means up to 24 digest cards per day in your + channel, plus breach and forecast cards when state changes. For a typical month most days have only the + digest; breaches concentrate near the end of the month and when a new project ramps up. +
+ +Best case (steady state): 1 card (digest).
+ Worst case (first sync after enabling on a noisy environment): 1 digest + 1 card per
+ (workspace × newly-crossed-threshold) + 1 card per workspace newly flipped to at-risk.
For 11 workspaces with two over-budget and three at-risk, that's 1 + 2 + 3 = 6 cards. Posted serially over + roughly 1–3 seconds.
+ + +In order of likelihood:
+vercel env ls or the dashboard. Look for the cron log line posted=0 skipped=webhook_disabled — that's the smoking gun.vercel redeploy --prod.Most likely the URL was rotated by someone else, or Workflows hit a quota limit. Check the cron logs for a non-2xx HTTP status:
+[anthropic-api-costs] teams alert evaluation failed (non-fatal): Teams webhook returned 401+
401 / 403: URL is stale — re-provision and update the env var.
+ 429: You're hitting the 4 req/sec or 1800/hour-per-channel rate limit. Unlikely under
+ normal cadence; if you see this routinely, something is running the cron more often than hourly.
+ 413: Payload over 28 KB. The digest caps at top-5 workspaces; if the channel grew to
+ hundreds, file a follow-up to chunk the digest.
The cost sync hasn't completed in 70+ minutes. The evaluator deliberately suppresses the digest and + alert cards to avoid posting numbers nobody trusts. Fix the sync first:
+/settings/sync in the app — look at the "Anthropic API costs" row for the last
+ outcome and error message./api/sync/anthropic-api-costs. Common causes: Anthropic Admin
+ API key expired, Anthropic API outage (check status.claude.com),
+ Neon DB connectivity.By design, the entire card batch is all-or-nothing: if any single POST fails mid-batch, the next sync + re-evaluates and re-posts. Operators will see cards 1–2 duplicated and cards 3–5 appear fresh. This is + the cost of at-least-once delivery — preferred over partial state loss.
+If duplicates persist across many runs, one specific card is consistently failing — most often a + 413 (oversized) or 400 (schema rejected). Check the cron logs; the error message names the failing card + type.
+Cards use the workspace name from anthropic_workspaces.name, which mirrors what Anthropic
+ returns from its workspaces API. If a workspace was renamed in the Anthropic console, run the workspace
+ sync manually to refresh local names:
curl -X POST https://hub.unic.com/api/sync/anthropic-api-costs \
+ -H "Authorization: Bearer $CRON_SECRET"
+ Provision a second Workflows webhook in a private channel (e.g., "Claude Alerts · Staging"), set
+ TEAMS_WEBHOOK_URL on the Vercel Preview environment only, and trigger the
+ cron against a preview deployment. The production channel stays clean.
The idempotency ledger is in the anthropic_alert_state table. To re-arm threshold cards for
+ a workspace in the current month, run against your staging Neon branch (never production):
DELETE FROM anthropic_alert_state WHERE billing_month = '2026-05';
+ Next sync will fire fresh threshold and forecast cards for any workspaces whose state should be active.
+Don't do this in production unless you genuinely want the channel to see a re-fire of + every existing alert.
+The feature ships with sensible defaults. If you need to change them, here's where they live:
+ +| Behavior | Where | Default |
|---|---|---|
| Threshold levels | +src/lib/teams/evaluator.ts · computeAlertDiff |
+ 80%, 100%, 120% | +
| Top-N workspaces in digest | +src/lib/teams/evaluator.ts · DIGEST_TOP_N |
+ 5 | +
| Forecast lookback window | +src/lib/teams/evaluator.ts · FORECAST_LOOKBACK_DAYS |
+ 30 | +
| Forecast trailing-rate window | +src/lib/anthropic/forecast-workspace.ts · hard-coded 7-day slice | +7 days | +
| Stale-data threshold | +src/lib/anthropic/queries.ts · STALE_MINUTES |
+ 70 minutes | +
| Sync cadence | +vercel.json · cron schedule for /api/sync/anthropic-api-costs |
+ hourly | +
| Webhook retry | +src/lib/teams/webhook.ts · MAX_ATTEMPTS, BASE_DELAY_MS |
+ 3 attempts, 2 → 20 s backoff | +
Two ways, both safe and reversible:
+ +Unset TEAMS_WEBHOOK_URL on Vercel Production. The evaluator no-ops on its first line; sync continues to run; no cards post; no code rollback needed. To re-enable, put the env var back.
From the Workflows app, turn off the flow (toggle "On" → "Off"). The webhook URL returns a 4xx; the evaluator logs the error and moves on. Use this when you can't reach the Vercel dashboard.
+ +anthropic_alert_state table is small and harmless when the feature is off. Deleting it via
+ migration is not necessary and complicates re-enabling.
+ Not in v1. The plan calls out a future TEAMS_WEBHOOK_URL_ALERTS variant for splitting noisy
+ digest from high-priority alerts — but it's deferred. File a request if you want it prioritized.
Adaptive Cards posted via Workflows webhooks do not support mention entities — that's a
+ Bot Framework feature. For pings, the right path is a Microsoft Graph Activity Feed notification (also
+ deferred; see plan.html Phase 3).
No. Cards are visible to all members of the Teams channel, same as a regular chat message. The + "Open dashboard" / "Open workspace" buttons take them to the in-app dashboard, which still + enforces admin-only access.
+Anthropic invoices in USD; the cards mirror the source-of-truth currency to avoid implying a conversion + we don't apply to the underlying numbers. Multi-currency display is a future enhancement (deferred + per spec Q4).
+v1 doesn't correlate against status.claude.com. If an incident + causes spend to spike (rare) or the sync to fail (more common), you may see false-positive alerts or the + stale-data warning. Status-page correlation is on the Phase 3 backlog.
+All data is already in the Neon Postgres database — anthropic_workspace_costs,
+ anthropic_workspace_limits, anthropic_sync_status. The only new table is
+ anthropic_alert_state (the idempotency ledger). No Anthropic data is sent to Microsoft
+ beyond what's rendered in the card.
Not directly — the evaluator runs as a whole batch from the sync. The closest equivalent is the + curl-based cron trigger above. For testing, point at a staging channel.
+Running log of design decisions, deviations, tradeoffs, and open questions while implementing spec 030 (Claude Spend → Microsoft Teams).
+ +2026-05-21 · Task 1
+
+ The worktree didn't have its own .env.local (gitignored). Copied from main repo, then branched
+ Neon project ai-developer-hub off main into wt/ms-teams-report via the
+ neon-worktree-branch skill. DATABASE_URL and DATABASE_URL_UNPOOLED now point
+ at the branch. Verified host differs from main's host. Production data is untouched by anything done in this
+ worktree.
+
workspace_id with two partial unique indexes — not "__default__" coalesce2026-05-21 · Task 2
+
+ The plan specified workspaceId: varchar(64).notNull() and coalescing the Anthropic default workspace's
+ null to a sentinel string "__default__". While reading the existing schema I found that
+ anthropic_workspace_costs and anthropic_workspace_limits already solve this with
+ varchar(100) nullable + two partial unique indexes (WHERE workspace_id IS NOT NULL and
+ WHERE workspace_id IS NULL). I matched that pattern in anthropic_alert_state.
+
+ Why: consistency across the whole Anthropic sub-schema. The coalesce approach would have required + a thin translation layer at every read/write site. The partial-index approach is invisible at the application + layer — Drizzle just sees a nullable column. +
+
+ Tradeoff: the queries module now has to be careful to compare workspace_id IS NULL
+ rather than = '__default__'. Documented as a contract comment on the queries module.
+
billing_month2026-05-21 · Task 2
+
+ Added CHECK (billing_month ~ '^[0-9]{4}-(0[1-9]|1[0-2])$') so a malformed value (e.g.
+ '2026-13' or 'May') can't reach the table even if a future caller forgets to
+ validate. Cheap belt-and-braces — TS types are not enforced at the DB layer, and the value is small enough that the
+ regex won't show up in EXPLAIN plans.
+
2026-05-21 · Task 4
+
+ The spec said "refactor the server actions to delegate" — taken literally that meant moving every _get*
+ private function out of anthropic-global.ts (16 of them). I only moved the three the evaluator
+ actually needs (loadSyncStatus, loadDashboardKpis, loadWorkspaceList) and
+ left the other 13 private functions in place. The rest can migrate later if a second consumer emerges.
+
Why: minimum diff, zero behavior change for any of the other 13 dashboard panels. Typecheck passes.
+
+ Mitigations from the plan all applied: import "server-only" at top, contract comment naming the
+ only two allowed callers, load* naming convention.
+
limitCents parameter2026-05-21 · Task 5
+
+ Plan signature was forecastWorkspaceMonth(workspaceId, month, today) but its return shape includes
+ crossesCapOn and status: "at_risk" | "on_track" — both of which require the cap.
+ Added a 4th param limitCents: number | null. Caller already has it on WorkspaceListItem.
+
2026-05-21 · Task 5
++ Considered: weighted exponential moving average, OLS on day-of-month progression, or two-line piecewise to detect + inflection. Picked plain 7-day trailing because: (1) the forecast card already shows a 7-day rate as a fact, so the + projection "7-day rate × days remaining" is internally consistent with what the operator sees, (2) Anthropic spend + has strong weekly seasonality (weekday spikes, weekend dips), and a 7-day window naturally averages over that, (3) + EWMA would chase noise from a single backfill spike. +
++ Downside: a single "experiment Friday" spike pulls the 7-day rate up for a week. Acceptable — the next 7 days will + smooth it back out. +
+insufficient_data when < 3 distinct billed days this month2026-05-21 · Task 5
++ Plan didn't specify the data-sufficiency threshold. Picked 3 distinct billed days inside the current billing + month. Fewer than that and the projection is dominated by noise — no card fires, evaluator ignores the workspace + for forecast purposes. Threshold breaches still fire normally; they don't depend on the forecast. +
+crossesCapOn = null, not today's date2026-05-21 · Task 5
+
+ The forecast card shows "Crosses 100% on YYYY-MM-DD". If a workspace is already over, the threshold breach card
+ has already signaled that — the forecast doesn't need to also say "crosses today". Returning null
+ here lets the renderer omit the field instead of showing a confusing date.
+
webhook.ts instead of retryWithBackoff()2026-05-21 · Task 6
+
+ The plan said "reuse retryWithBackoff() from src/lib/sync/framework.ts". Reading the
+ existing helper showed it retries on every error and ignores HTTP Retry-After. Microsoft's rate-limit
+ docs say to honor Retry-After on 429 and to retry only specific statuses (412/429/502/504), not
+ everything. Wrote a small Teams-specific retry that does both.
+
+ Tradeoff: < 60 lines of duplicated structural code vs. forking the shared helper. Picked + duplication because the Teams retry has different semantics than the data-sync retry (status-specific, header-honoring) + and tangling them would make the data-sync retry harder to reason about. +
+/claude/workspaces/[id], not /anthropic/workspaces/[id]2026-05-21 · Task 6
+
+ Plan's example payloads used https://hub.unic.com/anthropic/workspaces/research-claude. The actual
+ route in this codebase is /claude/workspaces/[workspaceId]. Used that. encodeURIComponent
+ on the id for safety.
+
"__default__" for in-memory state only2026-05-21 · Task 6
+
+ The DB stores workspace_id IS NULL for the default workspace (matching existing tables — see entry
+ under Schema). But the evaluator's state-machine maps need a non-null key for Map<string, ...>.
+ Coined a single helper keyFor() that maps null → "__default__" for in-memory keys only;
+ everything that hits the DB still passes the original string | null. Avoids the "__default__" leak
+ that I rejected at the schema layer.
+
2026-05-21 · Task 6
++ Two options: persist after each card (so a mid-batch failure doesn't lose progress), or persist after all cards + succeed (so a mid-batch failure causes the next sync to re-post the cards that did make it). Picked the second + because: (a) re-posting an identical card to a Teams channel within the hour is benign (operator just sees a + duplicate), (b) the alternative leaves a half-fired state where some cards were "announced" but no operator knows + the others didn't make it. At-least-once delivery, idempotent on the receiver. +
+computeAlertDiff() exported as a pure function2026-05-21 · Task 6
+
+ The evaluator's state-machine logic is pure (no DB, no side effects). Split it out as
+ computeAlertDiff() and exported it so unit tests can hammer the threshold/forecast invariants without
+ needing a database. Plan didn't spell this out; this is a structural improvement.
+
2026-05-21 · Task 7 → revisited in Code Review
+
+ First pass used a dynamic await import() to keep the "server-only" chain out of the
+ sync source's static graph. Quality review flagged it as a smell. With the tests/shims/server-only.ts
+ alias already in both vitest configs, static import works fine in tests too. Switched back to static import.
+
server-only shim — not in plan2026-05-21 · Task 8
+
+ Both unit and integration test configs now alias the server-only package to an empty shim at
+ tests/shims/server-only.ts. Required because the plan's "import "server-only"
+ at the top of queries.ts" mitigation breaks vitest unless aliased — the package only exists at
+ runtime under Next.js. Net effect on production: zero. Tests now run; production builds still enforce the
+ server-only invariant.
+
.env.local2026-05-21 · Task 8
+
+ Existing integration tests (e.g. invoice-sync.test.ts) silently rely on the caller exporting
+ DATABASE_URL before running pnpm test:integration. Added an explicit
+ dotenv.config({ path: ".env.local" }) at the top of vitest.config.integration.mts. Also
+ bumped hookTimeout from 10s to 30s to tolerate Neon cold starts on first connection.
+
2026-05-21 · Task 8
++ Initial expectations assumed seed covered last 14 days ending yesterday. The function fills missing days with 0 + (correct behavior — missing means "not synced yet," treat conservatively). Updated seeds to include today's + row, which is more realistic anyway since the hourly cron writes a partial today row on every run. +
+2026-05-21 · Task 8
+
+ Existing anthropic-workspace backfill tests passed unchanged. They now emit
+ [anthropic-api-costs] teams alerts posted=0 skipped=webhook_disabled in their logs — confirming the
+ kill-switch behavior works correctly when TEAMS_WEBHOOK_URL is unset.
+
2026-05-21 · Task 9
+
+ Navigated http://localhost:3001/claude in Chrome via the chrome-devtools MCP. Page renders with real
+ Neon-branch data — $2,438.76 MTD, 11 workspaces, KPIs, daily breakdown, historical trend, all 13 workspace budget
+ cards. Single console error is a static-asset 404 unrelated to this change. Server-action refactor is transparent.
+ Screenshot saved at specs/030-claude-spend-teams-alerts/verification-dashboard.png.
+
2026-05-21 · Task 9
+
+ Hit /api/sync/anthropic-api-costs via curl with the cron Bearer token in four
+ configurations:
+
| Run | +TEAMS_WEBHOOK_URL | +posted= | +Confirms | +
|---|---|---|---|
| 1 | unset | 0 | Kill switch |
| 2 | set (httpbin echo) | 4 | Digest + 3 forecast edges (first run) |
| 3 | set | 1 | Idempotency — forecast cards suppressed |
| 4 | set | 1 | State stable across runs |
+ SELECT * FROM anthropic_alert_state after run 2 shows three rows with forecast_at_risk=true
+ on the workspaces the dashboard's "on pace 102%/103%/97%" cards flagged. Threshold timestamps remain NULL because
+ no workspace is currently over 80%.
+
2026-05-21 · Task 9
+
+ The plan's rollout step list assumes the operator has a real Workflows webhook URL to test against. For our
+ verification I used httpbin.org/anything as a wire test. Before production rollout, the operator should: (a)
+ provision a real Workflows webhook in a Teams channel, (b) replace TEAMS_WEBHOOK_URL in Vercel, (c)
+ seed a synthetic over-limit workspace in staging to test the threshold path (didn't exist in current data).
+
2026-05-21 · /simplify
++ Three xhigh-effort review agents ran in parallel (reuse, quality, efficiency). High-value fixes applied: +
+fmtMoneyPrecise (duplicated formatCurrency from src/lib/utils.ts). Switched fmtAgo to wrap date-fns formatDistanceToNow (8+ existing call sites). Deleted unused fmtDate.ALL_THRESHOLDS export. Extracted projectedEomLabel() from a nested ternary in cards.ts. Trimmed the contract comment in queries.ts from 18 → 4 lines. Replaced linear workspaces.find() with a workspacesByKey Map. Fixed the misleading "at-least-once delivery" comment to honestly describe all-or-nothing batch semantics. Hoisted the dynamic import to static.forecastWorkspaceMonth is now a pure function; loadCostHistory() in queries.ts fetches all workspaces' daily costs in one SQL query and the evaluator fans out in JS. ~11 queries → 1. State upsert batched into a single INSERT...VALUES...ON CONFLICT instead of N round trips; redundant per-row transaction dropped (caller has withSyncLock).+ Smoke-tested against the Neon branch after the refactor: clean state → posted=4 (digest + 3 forecast cards) → re-run → posted=1 (digest only, idempotent). Same behavior as pre-refactor, fewer queries. +
+
+ Deferred (out of scope for spec 030): the "__default__" magic string appears in 13 sites across the
+ codebase — extracting a shared DEFAULT_WORKSPACE_KEY constant is a cross-cutting cleanup, separate
+ ticket. Loading loadDashboardKpis as one query instead of two is a pre-existing pattern lifted
+ unchanged — also separate.
+
__dirname with ESM-safe derivation in .mts config2026-05-21 · PR #97 review
+
+ Copilot reviewer flagged that vitest.config.integration.mts uses __dirname, which is
+ technically undefined in Node ESM. It worked in practice (Vitest's esbuild transform polyfilled it), but the
+ spec is clear and the defensive fix is cheap. Switched to
+ path.dirname(fileURLToPath(import.meta.url)). Also rebased loadEnv() to use that
+ derived path so it works regardless of CWD. vitest.config.ts stays as-is — it's .ts
+ not .mts and resolved as CJS in this CJS project.
+
2026-05-21 · PR #97 review
+
+ Reviewer flagged that the silent fallback to "http://localhost:3000" for the dashboard base URL
+ would produce embarrassingly broken deep links if a production deployment lacked both
+ TEAMS_DASHBOARD_BASE_URL and NEXTAUTH_URL. Added a guard: when
+ VERCEL_ENV indicates a production-like environment and neither base URL is set, the evaluator
+ returns posted: 0, skipped: ["dashboard_base_url_missing"]. Local dev still falls back to localhost
+ so the kill switch can be tested without extra env wiring.
+
(entries added as work progresses)
+ ++ Option 1 mockup — Adaptive Cards posted into a Teams channel by the existing hourly Anthropic sync cron via an + incoming Workflows webhook (replacement for retired O365 Connectors). Three card variants are shown + in chronological order as they would appear in a real Teams channel: hourly digest, threshold-breach alert, and + forecast-at-risk alert. +
+14:01 CET · data is 1 min old
+ 13:58 CET · first breach this month
+ + Spend accelerated after a backfill job started at 11:20. The OLS forecast on the last + 14 days now exceeds the ceiling by $3,940. Recommended actions: raise the cap, + pause the workspace, or open the run-rate breakdown. +
+anthropic_workspace_limits.monthly_cap since the previous sync. Idempotency on (workspace_id, threshold, billing_month).
+ at_risk
+ forecastBudget() in src/lib/forecast.ts returns status: at_risk on this sync but was on_track on the previous sync. Edge-triggered, not level-triggered.
+ + All three cards are static Adaptive Card v1.5 JSON payloads POSTed to a per-channel Workflows webhook URL. No bot, + no Entra app, no manifest — fire-and-forget HTTP from the existing hourly cron. Each post is a new message + (Workflows webhooks cannot edit in place). +
+ +
+ Posted once per successful sync. Pulls getDashboardKpis() + the top 5 entries from
+ getWorkspaceList() sorted by utilizationPct. Skipped if
+ getSyncStatus().isStale is true; a stale-data warning posts instead.
+
+ Fired once per workspace per threshold (80, 100, 120%) per billing month. Idempotency stored in a new
+ anthropic_alert_state table to survive cron restarts and re-runs.
+
+ Fired when forecastBudget() flips from on_track → at_risk, and
+ again when it flips back. Single source-of-truth: the same forecast already shown in the in-app dashboard.
+
https://prod-XX.westeurope.logic.azure.com/workflows/…
+ + Post Adaptive Cards into a Microsoft Teams channel from the existing hourly Anthropic sync via an + incoming Workflows webhook. Three card types: hourly digest, threshold-breach alert, forecast-at-risk + alert. No bot, no Teams app manifest, no Entra registration. +
+ + +src/lib/anthropic/queries.ts.forecastBudget() is for annual budgets, not workspace-monthly caps. Several card fields had no source. New forecastWorkspaceMonth() + "Top model" deferred to Phase 1.5.[80,100)/[100,120)/[≥120) ranges with an active boolean produced confusing semantics. Replaced with one row per workspace per month + three nullable "first-fired-at" timestamps. Each threshold fires exactly once per workspace per billing month./api/sync/anthropic-api-costs).on_track → at_risk or back).anthropic_alert_state for idempotency — alerts are edge-triggered, not level-triggered.refresh / auto-refreshing cards.specs/030-claude-spend-teams-alerts/mockup.html for the visual contract and the "explore additional information" thread for backlog items.The integration is an additive post-step on the existing sync. No new cron, no new route, no new auth.
+ +try/catch; a failure logs but does not flip the sync to partial/failed. The sync's job is data integrity; alerts are a side effect.Action.Execute, Action.Submit, and refresh all require a bot. We use Action.OpenUrl exclusively.One new table. No new enums (the original tier enum was dropped — see rev 2 below). No changes to existing tables.
+ +anthropic_alert_state rev 2
+ One row per (workspace_id, billing_month) — the idempotency ledger. Each threshold has a nullable
+ *_fired_at timestamp: NULL means "never fired this month", non-NULL means "already fired, don't
+ fire again". Forecast tracking is stored as a boolean + timestamp pair on the same row (it's edge-triggered;
+ thresholds are not).
+
src/lib/db/schema.ts (edit)// No new enum — the previous threshold enum is replaced by three nullable timestamp columns. + +export const anthropicAlertState = pgTable("anthropic_alert_state", { + id: serial("id").primaryKey(), + + // workspaceId is varchar(64) NOT NULL. For the special "default" workspace + // (where Anthropic returns workspace_id = null), we coalesce to "__default__" + // before insert — see queries.ts. This sidesteps Postgres's NULL-is-not-equal-NULL + // gotcha on the unique index. + workspaceId: varchar("workspace_id", { length: 64 }).notNull(), + billingMonth: varchar("billing_month", { length: 7 }).notNull(), // YYYY-MM + + // Threshold alerts: fire-once-per-month, never re-fire. + threshold80FiredAt: timestamp("threshold_80_fired_at"), + threshold100FiredAt: timestamp("threshold_100_fired_at"), + threshold120FiredAt: timestamp("threshold_120_fired_at"), + + // Forecast: edge-triggered. Fires when forecastAtRisk transitions false → true. + forecastAtRisk: boolean("forecast_at_risk").notNull().default(false), + forecastChangedAt: timestamp("forecast_changed_at"), + + createdAt: timestamp("created_at").notNull().defaultNow(), + updatedAt: timestamp("updated_at").notNull().defaultNow(), +}, (t) => [ + uniqueIndex("alert_state_workspace_month_idx").on(t.workspaceId, t.billingMonth), +]);+ +
| Column | Purpose |
|---|---|
threshold_80_fired_at / _100_ / _120_ | NULL until that threshold first crosses this month. Once set, never re-fires for the same (workspace, month). |
forecast_at_risk | Current state of the forecast. Used to detect false → true edges (and optionally back). |
forecast_changed_at | Timestamp of the last state flip. Lets the card show "status changed N minutes ago". |
| composite unique | (workspace_id, billing_month) — exactly one row per workspace per month. |
pnpm db:generate # produces .migrations/XXXX_*.sql +pnpm db:migrate # applies to DATABASE_URL+ +
+ Two new namespaces — src/lib/anthropic/ for the auth-free data layer
+ (used by both the existing server actions and the new evaluator) and src/lib/teams/ for the
+ Teams-specific code — plus one schema edit and one source-handler edit.
+ rev 2
+
src/ +├── actions/ +│ └── anthropic-global.ts refactor: actions delegate to queries.ts (no behavior change for UI) +├── lib/ +│ ├── db/ +│ │ └── schema.ts + anthropicAlertState (rev 2 shape) +│ ├── env.ts + TEAMS_WEBHOOK_URL, TEAMS_DASHBOARD_BASE_URL +│ ├── sync/ +│ │ └── sources/ +│ │ └── anthropic-workspace.ts + call evaluateAndPostTeamsAlerts() on success +│ ├── anthropic/ NEW namespace — auth-free data layer +│ │ ├── queries.ts loadSyncStatus(), loadDashboardKpis(month), loadWorkspaceList() +│ │ └── forecast-workspace.ts forecastWorkspaceMonth(ws, month, today) — trailing-rate, not OLS +│ └── teams/ +│ ├── webhook.ts postCard() — fetch wrapper w/ retry +│ ├── cards.ts renderDigestCard(), renderBreachCard(), renderForecastCard(), renderStaleCard() +│ ├── evaluator.ts evaluateAndPostTeamsAlerts() — pure orchestration +│ ├── state.ts readAlertState(month), upsertAlertState(diff) +│ ├── format.ts tiny helpers: $, %, ago() +│ └── types.ts card-input types, AlertEvaluation, CardEnvelope + +tests/ +├── unit/ +│ └── teams/ +│ ├── cards.test.ts snapshot tests for each card variant +│ └── format.test.ts $, %, ago() +└── integration/ + ├── anthropic/ + │ └── forecast-workspace.test.ts trailing-rate math against seeded daily costs + └── teams/ + ├── evaluator.test.ts fire-once-per-month invariants + forecast edges + └── webhook.test.ts postCard against a mocked fetch+ +
+ The existing getSyncStatus(), getDashboardKpis(), getWorkspaceList()
+ keep their signatures and their requireAdmin() + unstable_cache() wrappers. Their
+ bodies shrink to a single call into src/lib/anthropic/queries.ts. The DB queries
+ themselves move into the queries module. Both surfaces (UI server actions and the cron-time evaluator) read from
+ the same source — actions enforce the admin gate, the evaluator skips it because it runs under
+ CRON_SECRET.
+
+ Hoisting org-financial queries above the auth boundary creates a footgun: a future route handler that imports a
+ load* function and forgets to gate would publicly expose spend KPIs. The mitigations below make
+ misuse hard to commit and easy to catch in review.
+
import "server-only" at the top of src/lib/anthropic/queries.ts. Next.js throws a build error if any client-side code tries to import the module, preventing accidental browser bundling.load*() (not get*()) to flag "auth-free, caller's responsibility" distinct from action-style getters.nextauth-security-reviewer sub-agent before merge — explicitly added to the rollout step list.middleware.ts or any edge runtime path.+ Residual risk after mitigations: a hand-written new route that explicitly imports a load function and skips auth. + That requires an intentional act and is the kind of regression code review catches. Net assessment: small + incremental risk vs. the original "auth at the boundary" pattern, materially lower than the cost of leaving the + cron caller broken. +
+ +CRON_SECRET previously gave an attacker the ability to trigger syncs. After this change it
+ also gives them the ability to fire Teams posts to whatever channel TEAMS_WEBHOOK_URL points at. No
+ data exfil (the attacker would need both secrets to read responses), low real value, but worth noting.
+ forecastBudget()
+ src/lib/forecast.ts's forecastBudget() is designed for the annual budget tracker
+ (input: MonthlySpend[] over many months; output: annual projection via OLS). The Teams use case
+ needs monthly projection from daily data over a partial month. Different domain.
+ forecastWorkspaceMonth() uses a 7-day trailing rate scaled to days-remaining-in-month — well-suited
+ for a 30-day cycle and produces the "Crosses 100% on YYYY-MM-DD" date the forecast card needs.
+
+ A thin wrapper around fetch that POSTs an Adaptive Card envelope, honors 429 Retry-After,
+ and retries on 412/502/504 per Microsoft's guidance. Reuses retryWithBackoff() from
+ src/lib/sync/framework.ts.
+
src/lib/teams/webhook.ts (new)import { env } from "@/lib/env"; +import { retryWithBackoff } from "@/lib/sync/framework"; +import type { CardEnvelope } from "./types"; + +const RETRIABLE = new Set([412, 429, 502, 504]); + +export async function postCard(webhookUrl: string, envelope: CardEnvelope): Promise<void> { + await retryWithBackoff(async () => { + const res = await fetch(webhookUrl, { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify(envelope), + }); + if (res.ok) return; + + if (RETRIABLE.has(res.status)) { + const retryAfter = Number(res.headers.get("retry-after") ?? 0); + throw new RetriableError(`Teams webhook ${res.status}`, retryAfter * 1000); + } + const body = await res.text(); + throw new Error(`Teams webhook ${res.status}: ${body.slice(0, 500)}`); + }, { maxAttempts: 3, baseDelayMs: 2000, maxDelayMs: 20000, jitterPct: 0.2 }); +}+ +
+ Pure functions: (input) => CardEnvelope. No DB access, no side effects, no clock reads — the caller
+ passes in now. This makes snapshot tests trivial and makes the cards reproducible.
+
src/lib/teams/cards.ts (new)export function renderDigestCard(input: DigestInput): CardEnvelope; +export function renderBreachCard(input: BreachInput): CardEnvelope; +export function renderForecastCard(input: ForecastInput): CardEnvelope; +export function renderStaleCard(input: StaleInput): CardEnvelope;+ +
src/lib/teams/types.ts (new)export type DigestInput = { + kpis: DashboardKpis; // from getDashboardKpis() + topWorkspaces: WorkspaceListItem[]; // top 5 by utilization, from getWorkspaceList() + sync: SyncStatus; // from getSyncStatus() + month: string; // "2026-05" + dashboardUrl: string; +}; + +export type BreachInput = { + workspace: WorkspaceListItem; + threshold: "threshold_80" | "threshold_100" | "threshold_120"; + projectedMonthEndCents: number; + topModel: { name: string; sharePct: number } | null; + workspaceUrl: string; + raiseLimitUrl: string; +}; + +export type ForecastInput = { + workspace: WorkspaceListItem; + forecast: BudgetForecast; // from forecastBudget() + crossesCapOn: Date | null; + runRate7dCents: number; + runRateWoWPct: number; + workspaceUrl: string; +}; + +export type CardEnvelope = { + type: "message"; + attachments: [{ + contentType: "application/vnd.microsoft.card.adaptive"; + contentUrl: null; + content: AdaptiveCard; + }]; +};+ +
+ Cards must match the mockup at specs/030-claude-spend-teams-alerts/mockup.html. Notable rendering
+ constraints from the Teams contract investigation:
+
version: "1.4" for mobile rendering compatibility (1.5 is desktop-only).Action.OpenUrl is supported via Workflows webhook. No Submit/Execute, no refresh.Image. Render utilization bars as nested ColumnSet with weighted widths and tinted Container.style (default / good / warning / attention).Action.OpenUrl deep-links into the in-app dashboard. The button label stays the same; the click flow is "open the page where you can do it".sig= in the query string authenticates anyone holding it.
+ Never log the URL, never echo it back in error messages, never include it in sync_events.errorMessage.
+ + The orchestration layer. Pulls data via the auth-free queries module, diffs against the alert-state ledger, + emits zero or more cards, persists the new state. + rev 2 +
+ +src/lib/teams/evaluator.ts (new)import { loadSyncStatus, loadDashboardKpis, loadWorkspaceList } from "@/lib/anthropic/queries"; +import { forecastWorkspaceMonth } from "@/lib/anthropic/forecast-workspace"; +import { readAlertState, upsertAlertState } from "./state"; +import { postCard } from "./webhook"; +import { env } from "@/lib/env"; + +export async function evaluateAndPostTeamsAlerts(opts?: { + now?: Date; +}): Promise<{ posted: number; skipped: string[] }> { + if (!env.TEAMS_WEBHOOK_URL) return { posted: 0, skipped: ["webhook_disabled"] }; + + const now = opts?.now ?? new Date(); + const month = getCurrentMonth(now); + const sync = await loadSyncStatus(); + + // Stale guard — short-circuit before doing any other work. + if (sync.isStale) { + await postCard(env.TEAMS_WEBHOOK_URL, renderStaleCard({ sync, month })); + return { posted: 1, skipped: ["digest_skipped_stale"] }; + } + + const [kpis, workspaces, state] = await Promise.all([ + loadDashboardKpis(month), + loadWorkspaceList(), + readAlertState(month), + ]); + + // Per-workspace forecasts run in parallel; the call is cheap (single SQL aggregation). + const forecasts = await Promise.all( + workspaces.filter(w => w.workspaceId !== null && w.limitCents !== null).map(w => + forecastWorkspaceMonth(w.workspaceId!, month, now).then(f => ({ workspace: w, forecast: f })) + ), + ); + + const diff = computeAlertDiff({ workspaces, forecasts, state, now }); + const envelopes: CardEnvelope[] = []; + + // 1) Hourly digest — always (unless stale). + envelopes.push(renderDigestCard({ kpis, topWorkspaces: top5(workspaces), sync, month, dashboardUrl: dashUrl() })); + + // 2) Threshold breaches — only thresholds with no firedAt timestamp yet this month. + for (const b of diff.thresholdsToFire) { + envelopes.push(renderBreachCard(toBreachInput(b))); + } + + // 3) Forecast edges — false → true (and optionally true → false). + for (const f of diff.forecastEdges) { + envelopes.push(renderForecastCard(toForecastInput(f))); + } + + // Post serially to stay under 4 req/sec. + for (const envelope of envelopes) { + await postCard(env.TEAMS_WEBHOOK_URL, envelope); + } + + // Persist new state only after all cards have posted successfully. + await upsertAlertState(diff, now); + return { posted: envelopes.length, skipped: [] }; +}+ +
For each (workspaceId, billingMonth) row, the evaluator decides per-column:
| Column | Condition | Action | Card? |
|---|---|---|---|
threshold_80_fired_at | NULL AND pct ≥ 80 | set to now | yes |
threshold_80_fired_at | non-NULL (any pct) | no-op | — |
threshold_100_fired_at | NULL AND pct ≥ 100 | set to now | yes |
threshold_120_fired_at | NULL AND pct ≥ 120 | set to now | yes |
forecast_at_risk | was false, now true | flip + stamp forecast_changed_at | yes |
forecast_at_risk | was true, now false | flip + stamp forecast_changed_at | see Q1 |
threshold_80 and threshold_100 in the same evaluation — two cards.limitCents === null are skipped for thresholds. Forecast still runs (no cap = no overshoot, but the run-rate / projection is still computed).
+ The only change to the existing cron path is a single try-wrapped call at the end of run(), after the
+ sync-status sentinel is stamped.
+
counts.errorCount === 0 — partial-failure syncs don't post (data may be incomplete).try/catch — Teams posting can never fail the sync.console per house convention. No new logging infrastructure.makeCronSyncRoute, withSyncLock, or sync_events.
+ A dev or admin can re-fire the evaluator without re-running the upstream sync by calling
+ evaluateAndPostTeamsAlerts() from a one-off script (e.g., scripts/teams-test.ts). This is
+ not exposed as an API route in v1.
+
| Name | Type | Required | Purpose |
|---|---|---|---|
TEAMS_WEBHOOK_URL |
+ URL | +No | +If unset, the evaluator no-ops. This is the kill switch. | +
TEAMS_DASHBOARD_BASE_URL |
+ URL | +No (defaults to NEXTAUTH_URL) |
+ Base URL used to build deep links in card buttons. | +
src/lib/env.tssrc/lib/env.ts (edit)const envSchema = z.object({ + /* ...existing... */ + TEAMS_WEBHOOK_URL: z.string().url().optional(), + TEAMS_DASHBOARD_BASE_URL: z.string().url().optional(), +});+ +
TEAMS_WEBHOOK_URL in Vercel Project Settings → Environment Variables, scoped to Production only
+ at first. vercel env pull on local will pick it up. Treat the URL as a secret — it's an HMAC-signed
+ Logic Apps trigger and is auth by possession.
+ + Three Adaptive Card v1.4 payloads, wrapped in the Workflows envelope. These are the contract — the renderer must + produce JSON that matches this shape. +
+ +$TEAMS_WEBHOOK_URL — digest payload{
+ "type": "message",
+ "attachments": [
+ {
+ "contentType": "application/vnd.microsoft.card.adaptive",
+ "contentUrl": null,
+ "content": {
+ "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
+ "type": "AdaptiveCard",
+ "version": "1.4",
+ "body": [
+ { "type": "TextBlock", "text": "Claude API spend · hourly digest", "weight": "Bolder", "size": "Large", "wrap": true },
+ { "type": "TextBlock", "text": "May 2026 MTD · synced 14:01 CET · 1 min old", "isSubtle": true, "spacing": "None", "wrap": true },
+ { "type": "ColumnSet", "spacing": "Medium", "columns": [
+ { "type": "Column", "width": "stretch", "items": [
+ { "type": "TextBlock", "text": "MTD spend", "isSubtle": true, "size": "Small" },
+ { "type": "TextBlock", "text": "$18,420", "weight": "Bolder", "size": "ExtraLarge", "spacing": "None" },
+ { "type": "TextBlock", "text": "▲ 12% vs same day last month", "color": "Attention", "size": "Small", "spacing": "None" }
+ ]},
+ { "type": "Column", "width": "stretch", "items": [
+ { "type": "TextBlock", "text": "Workspaces > 80%", "isSubtle": true, "size": "Small" },
+ { "type": "TextBlock", "text": "3 of 11", "weight": "Bolder", "size": "ExtraLarge", "spacing": "None" }
+ ]},
+ { "type": "Column", "width": "stretch", "items": [
+ { "type": "TextBlock", "text": "Forecast", "isSubtle": true, "size": "Small" },
+ { "type": "TextBlock", "text": "At risk", "weight": "Bolder", "size": "ExtraLarge", "color": "Attention", "spacing": "None" }
+ ]}
+ ]},
+ { "type": "TextBlock", "text": "Top utilization", "weight": "Bolder", "spacing": "Medium" },
+
+ /* repeat per workspace: name+pct, then a two-column "bar" */
+ { "type": "TextBlock", "text": "research-claude · 102% · $5,120 / $5,000", "spacing": "Small", "wrap": true },
+ { "type": "ColumnSet", "spacing": "None", "columns": [
+ { "type": "Column", "width": 100, "items": [{ "type": "Container", "style": "attention", "minHeight": "6px", "items": [{ "type": "TextBlock", "text": " " }]}]}
+ ]}
+ /* ...repeat for the remaining 4 workspaces... */
+ ],
+ "actions": [
+ { "type": "Action.OpenUrl", "title": "Open dashboard", "url": "https://hub.unic.com/anthropic" },
+ { "type": "Action.OpenUrl", "title": "View all workspaces", "url": "https://hub.unic.com/anthropic/workspaces" }
+ ]
+ }
+ }
+ ]
+}
+ $TEAMS_WEBHOOK_URL — breach payload (truncated for brevity){
+ "type": "message",
+ "attachments": [{
+ "contentType": "application/vnd.microsoft.card.adaptive",
+ "contentUrl": null,
+ "content": {
+ "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
+ "type": "AdaptiveCard",
+ "version": "1.4",
+ "body": [
+ { "type": "Container", "style": "attention", "bleed": true, "items": [
+ { "type": "TextBlock", "text": "⚠ Workspace over budget · research-claude", "weight": "Bolder", "size": "Large", "color": "Attention", "wrap": true },
+ { "type": "TextBlock", "text": "Crossed 100% at 13:58 CET · first breach this month", "isSubtle": true, "spacing": "None", "wrap": true }
+ ]},
+ { "type": "FactSet", "facts": [
+ { "title": "Workspace", "value": "research-claude" },
+ { "title": "Monthly limit", "value": "$5,000.00" },
+ { "title": "Spend MTD", "value": "$5,120.40 · 102%" },
+ { "title": "7-day run rate", "value": "$612/day · 3.4× the 30-day avg" },
+ { "title": "Projected EOM", "value": "$8,940 · +$3,940 over" }
+ /* "Top model" intentionally omitted in v1 — no per-workspace × model join
+ available. Deferred to Phase 1.5 once we wire anthropic_usage_metrics
+ into a workspace-attributed aggregation. */
+ ]}
+ ],
+ "actions": [
+ { "type": "Action.OpenUrl", "title": "Open workspace", "url": "https://hub.unic.com/anthropic/workspaces/research-claude" },
+ { "type": "Action.OpenUrl", "title": "Adjust limit", "url": "https://hub.unic.com/anthropic/workspaces/research-claude/limit" }
+ ]
+ }
+ }]
+}
+ $TEAMS_WEBHOOK_URL — forecast payload (truncated){
+ "type": "message",
+ "attachments": [{
+ "contentType": "application/vnd.microsoft.card.adaptive",
+ "contentUrl": null,
+ "content": {
+ "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
+ "type": "AdaptiveCard",
+ "version": "1.4",
+ "body": [
+ { "type": "Container", "style": "warning", "bleed": true, "items": [
+ { "type": "TextBlock", "text": "Forecast: product-ai projected to overshoot", "weight": "Bolder", "size": "Medium", "color": "Warning", "wrap": true },
+ { "type": "TextBlock", "text": "OLS on last 14 days · status flipped to at_risk", "isSubtle": true, "spacing": "None" }
+ ]},
+ { "type": "FactSet", "facts": [
+ { "title": "Spend MTD", "value": "$4,200 · 84%" },
+ { "title": "7-day run rate", "value": "$210/day · ▲ 28% WoW" },
+ { "title": "Projected EOM", "value": "$5,890 · +$890 over" },
+ { "title": "Crosses 100% on", "value": "28 May 2026 · in 7 days" }
+ ]}
+ ],
+ "actions": [
+ { "type": "Action.OpenUrl", "title": "Open forecast", "url": "https://hub.unic.com/anthropic/workspaces/product-ai/forecast" }
+ ]
+ }
+ }]
+}
+ | Scenario | Behavior |
|---|---|
| Webhook returns 429 | +retryWithBackoff honors Retry-After, up to 3 attempts, max 20s delay. |
+
| Webhook returns 4xx (non-429) | +No retry. Log error (without URL). Sync still marked success — alerts are best-effort. | +
| Workflow URL revoked / O365 connector retired | +All POSTs fail. Operator removes TEAMS_WEBHOOK_URL until a new Workflows URL is provisioned. |
+
| Sync stale (> 70 min) | +Digest skipped. Stale-data card posted instead. Breach/forecast cards skipped entirely. | +
| Anthropic workspace removed upstream | +Workspace drops out of getWorkspaceList(). Its alert-state row goes dormant (active=false next eval). |
+
| New billing month | +Eval queries WHERE billing_month = '2026-06'. No rows exist; everything is treated as fresh. May → June rollover emits a fresh set of breach cards if conditions persist. |
+
| Limit increased mid-month (utilization drops below threshold) | +Row flips active=false. Next time utilization crosses again, a new card fires. No spam. |
+
| Limit removed entirely | +Workspace has no limitCents. Excluded from threshold evaluation. Forecast still runs if monthly history is sufficient. |
+
| Card > 28 KB | +Renderer caps the digest at top-5 workspaces; theoretical max is well under 6 KB. If somehow exceeded, the POST fails with 413 and the operator sees the error in cron logs. | +
| Concurrent sync runs | +withSyncLock prevents concurrency. Evaluator runs only after the lock releases. |
+
| Partial sync (errorCount > 0) | +Evaluator skipped. Sync data may be incomplete; better silence than misleading alerts. | +
tests/unit/teams/cards.test.ts — one snapshot per card variant. Catches accidental schema breakage.tests/unit/teams/format.test.ts — money/percent/relative-time helpers.tests/integration/teams/evaluator.test.ts rev 2:
+ threshold_80_fired_at is set.threshold_100 card; threshold_100_fired_at set.threshold_80_fired_at already non-NULL, so no re-fire.on_track → at_risk → forecast card posted; forecast_at_risk = true, forecast_changed_at stamped.at_risk → on_track → optional recovery card per Q1 default (no card).limitCents = null → thresholds skipped, forecast still computed.workspaceId = null) → coalesced to "__default__" in the ledger, unique index satisfied.tests/integration/anthropic/forecast-workspace.test.ts new — seed 14 days of anthropic_workspace_costs, assert: 7-day run rate, week-over-week %, projected EOM cents, crosses-cap date (or NULL when on-track).tests/integration/teams/webhook.test.ts — mock fetch to assert: envelope shape, retry on 429 with Retry-After, no retry on 400, never logs the URL.pnpm tsx scripts/teams-test.ts → digest + breach card appear in the channel within seconds.curl -H "Authorization: Bearer $CRON_SECRET" .../api/sync/anthropic-api-costs.anthropic_alert_type enum + anthropic_alert_state table. Generate, review with drizzle-migration-reviewer, apply.
+ src/actions/anthropic-global.ts into new src/lib/anthropic/queries.ts. Server actions stay as thin admin-gated + cached wrappers. UI behavior unchanged; verify by running the existing dashboard against staging.
+ forecastWorkspaceMonth() in src/lib/anthropic/forecast-workspace.ts with an integration test.
+ types.ts → format.ts → cards.ts → webhook.ts → state.ts → evaluator.ts. Each lands with unit tests.
+ src/lib/sync/sources/anthropic-workspace.ts with the try-wrapped call.
+ TEAMS_WEBHOOK_URL on the preview only.
+ nextauth-security-reviewer sub-agent against the diff. Focus on src/lib/anthropic/queries.ts (server-only marker, no client imports), the cron handler, and any newly-touched session-handling code.
+ main.
+ TEAMS_WEBHOOK_URL to Vercel Production.
+ specs/030-claude-spend-teams-alerts/README.html (to be added later).
+
+ Remove or unset TEAMS_WEBHOOK_URL in Vercel. No code rollback needed — the evaluator early-returns when the var is missing.
+ Schema migration is additive (a new table) and safe to keep even when the feature is off.
+
| # | Question | Default if no answer |
|---|---|---|
| Q1 | +Post a recovery card when forecast flips at_risk → on_track? (Thresholds are fire-once-per-month by design and don't apply.) |
+ No in v1 — reduces noise. The flip is recorded in the ledger and visible in the next digest. Reconsider after a month of real usage. | +
| Q2 | +One channel for everything, or split "digest" vs "alerts"? | +One channel (TEAMS_WEBHOOK_URL). Add a second var (TEAMS_WEBHOOK_URL_ALERTS) later if signal-to-noise becomes an issue. |
+
| Q3 | +Should the digest post even when nothing has changed? | +Yes — the digest is the heartbeat. If it disappears, ops knows the sync is broken. | +
| Q4 | +Currency and time-zone formatting — USD + CET, or per-tenant config? | +USD + CET hard-coded in v1; pull from a settings module when there's more than one tenant. | +
| Q5 | +Hourly cadence too noisy? | +Keep hourly. The digest is one message; only edge-triggered breach/forecast cards add extra posts, and they're by definition uncommon. | +
| Q6 | +Where do the deep-link buttons point? Are there per-workspace pages today (/anthropic/workspaces/:id)? |
+ Confirm against the routing under src/app/(authed)/anthropic/ during implementation. If the per-workspace page doesn't exist, link to the global dashboard with an anchor. |
+