@usehaia/trace-circle

npm install @usehaia/trace-circle

import { mkdirSync } from "node:fs";
import { createVerifier, createWebhookHandler } from "@usehaia/trace-circle";
import { createFileEventWriter } from "@usehaia/trace-core/file";

mkdirSync(".trace/events", { recursive: true });

const handler = createWebhookHandler({
  verifier: createVerifier({
    // The publicKey endpoint needs your Circle API credentials, so the fetch is
    // injected rather than built in. The verifier caches each key id.
    resolveKey: async (keyId) => {
      const res = await fetch(
        `https://api.circle.com/v2/notifications/publicKey/${keyId}`,
        { headers: { Authorization: `Bearer ${process.env.CIRCLE_API_KEY}` } },
      );
      if (res.status === 404) return null; // unknown key id → verification fails
      if (!res.ok) throw new Error(`publicKey ${keyId}: HTTP ${res.status}`);
      const { data } = (await res.json()) as { data: { publicKey: string } };
      return data.publicKey; // base64 SPKI, exactly as returned
    },
  }),
  // A refused event is reported by returning false, and the handler answers
  // 500 so Circle retries. Core's file sink already does this.
  write: createFileEventWriter(".trace/events/webhooks.ndjson").write,
});

// Any framework: `headers` may be a fetch `Headers` or a Node header record,
// read case-insensitively either way.
export async function POST(request: Request): Promise<Response> {
  // The body exactly as received — the signature covers these bytes, and
  // re-serializing parsed JSON can change them.
  const rawBody = await request.text();
  const result = await handler.handle(rawBody, request.headers);
  return new Response(null, { status: result.status });
}

createWebhookHandler({
  // Required. Verifies X-Circle-Signature against the raw body.
  verifier: createVerifier({ resolveKey }),

  // Required. Persists one stamped event. Return false (or throw) to refuse.
  write: createFileEventWriter(path).write,

  // Envelope → event inputs. Default: the circle.* vocabulary above.
  // Return [] to acknowledge a notification type without recording anything.
  normalize: (envelope) => [{ event_type: "my.event", payload: {} }],

  // Deduplication backing. Default: createMemoryDedupeStore().
  dedupe: myDurableStore,

  // Injectable clock and id source, for deterministic tests.
  now: () => "2026-07-28T12:00:00.000Z",
  newId: () => "evt-1",
});

haia-trace build --template escrow-arc