webhook / rules

---
description: TypeScript and Cloudflare Workers conventions, error handling, and testing expectations.
globs: **/*.ts
alwaysApply: false
---

# Engineering conventions (TypeScript / Workers)

## Language & types

- TypeScript everywhere, `strict` on. No `any` unless justified with a comment; prefer `unknown` +
  narrowing. Validate all external input (webhook bodies, API params) at the boundary with a schema.
- Keep `shared/` the home for cross-surface types. The same operation across CLI / API / web / MCP
  should share types — don't redefine payloads per surface.
- **Node↔Workers tsconfig boundary.** Packages export source for live cross-package types, but a
  Node-typed package (`types: ["node"]`) and a Workers-typed one (`types: ["@cloudflare/workers-types"]`)
  must never recompile each other's source — the lib worlds disagree (e.g. `@types/node`'s
  `Uint8Array<ArrayBufferLike>` vs the DOM `BufferSource` for WebCrypto). So an internal dependency
  edge that **crosses** that boundary resolves to the dep's built `dist/*.d.ts` via tsconfig `paths`,
  not its source; same-world edges stay on source. Use the `@webhook-co/*` → `dist` wildcard when
  **every** internal dep crosses (db); use an exact `@webhook-co/<pkg>` redirect when only some do
  (api/mcp → db). The `tsconfig-boundary` guard (`scripts/tsconfig-boundary.mjs`, wired into `lint`
  and CI) fails the build if a cross-boundary edge isn't redirected.

## Workers / Durable Objects

- Workers handlers stay thin: validate → delegate → respond. ACK ingestion fast; do delivery work
  off the request hot path (via the DO + alarms), not inline.
- One Durable Object **per endpoint** is the ordering/isolation primitive — preserve FIFO semantics
  and never share a DO across endpoints.
- Schedule retries/backoff with **DO Alarms**, not hot-path queues. Make delivery idempotent and
  dedup by event id.
- Never block on long outbound work in a Worker; route heavy/blocking delivery through the
  container-delivery **seam** (don't bypass the interface).
- Use bindings (KV, R2, Hyperdrive, DO) — never hardcode endpoints or credentials.

## Error handling

- Fail loud internally, fail safe externally. Return Standard-Webhooks-correct status codes; don't
  leak internal errors, stack traces, secrets, or tenant data to responses or logs.
- Errors are typed and actionable; wrap with context rather than swallowing. Retryable vs terminal
  failures must be distinguishable so the retry scheduler does the right thing.

## Testing

- Unit-test signing/verification, dedup/idempotency, and retry/backoff logic — these are
  correctness-critical.
- Cover edge cases: malformed/oversized payloads, duplicate deliveries, clock skew, partial
  failures, replay. Add a regression test with every bug fix.
- Prefer `vitest` with the Workers pool for DO/Workers code so tests run against the real runtime.
- Enforce an invariant in a **test**, not a tautological runtime guard. A `throw` whose condition can
  never be true (e.g. guarding `A < B` where `A` is defined as `B`) is dead code — assert the
  invariant in a test instead, where it actually runs.
- Extract magic values that are **coupled to a schema, migration, or config** into a named constant
  with a comment pointing at the authoritative source, so the two can't silently drift.