tapimo 0.0.0 → 0.0.2

package/src/Client.test.ts

@@ -0,0 +1,134 @@
+import * as Client from './Client.js'
+import * as TestApp from '../test/App.js'
+
+test('uses hosted API URL by default', () => {
+  const client = Client.create()
+
+  expect(Client.defaultUrl).toMatchInlineSnapshot(`"https://api.tempo.xyz"`)
+  expect(
+    client.v1.blocks[':block'].$url({ param: { block: 'latest' } }).toString(),
+  ).toMatchInlineSnapshot(`"https://api.tempo.xyz/v1/blocks/latest"`)
+})
+
+test('calls Tempo API app through configured fetch implementation', async () => {
+  const app = TestApp.create()
+  const fetch = (async (input, init) =>
+    app.fetch(new Request(input, init))) satisfies typeof globalThis.fetch
+  const client = Client.create({ fetch, url: 'http://tempo-api.test' })
+
+  const response = await client.v1['verified-tokens'].currencies.$get()
+  const body = await response.json()
+
+  expect(response.status).toMatchInlineSnapshot(`200`)
+  expect(body).toMatchInlineSnapshot(`
+    {
+      "data": [],
+    }
+  `)
+})
+
+test('applies `apiKey` to canonical header over base headers', async () => {
+  const { calls, fetch } = captureFetch()
+  const client = Client.create({
+    apiKey: 'key_option',
+    fetch,
+    headers: {
+      authorization: 'Payment proof',
+      'tempo-api-key': 'key_header',
+      'user-agent': 'tempo-api-test',
+    },
+    url: 'https://api.test',
+  })
+
+  await client.v1.blocks[':block'].$get({ param: { block: 'latest' }, query: {} })
+
+  expect(calls).toMatchInlineSnapshot(`
+      [
+        {
+          "headers": {
+            "authorization": "Payment proof",
+            "tempo-api-key": "key_option",
+            "user-agent": "tempo-api-test",
+          },
+          "url": "https://api.test/v1/blocks/latest?",
+        },
+      ]
+    `)
+})
+
+test('merges `apiKey` with dynamic base headers', async () => {
+  const { calls, fetch } = captureFetch()
+  const client = Client.create({
+    apiKey: 'key_option',
+    fetch,
+    headers: async () => ({ authorization: 'Payment proof' }),
+    url: 'https://api.test',
+  })
+
+  await client.v1.blocks[':block'].$get({ param: { block: 'latest' }, query: {} })
+
+  expect(calls).toMatchInlineSnapshot(`
+      [
+        {
+          "headers": {
+            "authorization": "Payment proof",
+            "tempo-api-key": "key_option",
+          },
+          "url": "https://api.test/v1/blocks/latest?",
+        },
+      ]
+    `)
+})
+
+test('lets per-request headers override base `apiKey`', async () => {
+  const { calls, fetch } = captureFetch()
+  const client = Client.create({ apiKey: 'key_base', fetch, url: 'https://api.test' })
+
+  await client.v1.blocks[':block'].$get(
+    { param: { block: 'latest' }, query: {} },
+    { headers: { 'tempo-api-key': 'key_request' } },
+  )
+
+  expect(calls).toMatchInlineSnapshot(`
+      [
+        {
+          "headers": {
+            "tempo-api-key": "key_request",
+          },
+          "url": "https://api.test/v1/blocks/latest?",
+        },
+      ]
+    `)
+})
+
+test('omits empty API keys', async () => {
+  const { calls, fetch } = captureFetch()
+  const client = Client.create({ apiKey: '', fetch, url: 'https://api.test' })
+
+  await client.v1.blocks[':block'].$get({ param: { block: 'latest' }, query: {} })
+
+  expect(calls).toMatchInlineSnapshot(`
+      [
+        {
+          "headers": {},
+          "url": "https://api.test/v1/blocks/latest?",
+        },
+      ]
+    `)
+})
+
+function captureFetch() {
+  const calls: { headers: Record<string, string>; url: string }[] = []
+  const fetch = (async (input, init) => {
+    calls.push({
+      headers: Object.fromEntries(new Headers(init?.headers).entries()),
+      url: (() => {
+        if (typeof input === 'string') return input
+        if (input instanceof URL) return input.toString()
+        return input.url
+      })(),
+    })
+    return new Response('{}', { headers: { 'content-type': 'application/json' }, status: 200 })
+  }) satisfies typeof globalThis.fetch
+  return { calls, fetch }
+}

package/src/Client.ts

@@ -0,0 +1,45 @@
+import { hc, type ClientRequestOptions } from 'hono/client'
+
+import type * as App from './App.js'
+
+/** Default hosted Tempo API URL. */
+export const defaultUrl = 'https://api.tempo.xyz'
+
+/** Creates a typed client for the hosted Tempo API. */
+export function create(options: create.Options = {}): create.ReturnType {
+  const { apiKey, url = defaultUrl, ...client } = options
+  const mergedHeaders = headers(client.headers, apiKey)
+  if (!mergedHeaders) return hc<App.App>(url, client)
+  return hc<App.App>(url, { ...client, headers: mergedHeaders })
+}
+
+/** Typed Hono client for the Tempo API. */
+export type Client = ReturnType<typeof hc<App.App>>
+
+export declare namespace create {
+  /** Typed Hono client returned by {@link create}. */
+  type ReturnType = Client
+
+  /** Options for creating a typed Tempo API client. */
+  type Options = ClientRequestOptions & {
+    /** API key sent on the canonical `tempo-api-key` header. */
+    apiKey?: string | undefined
+    /** Tempo API URL. Defaults to {@link defaultUrl}. */
+    url?: string | undefined
+  }
+}
+
+function headers(
+  base: ClientRequestOptions['headers'],
+  apiKey: string | undefined,
+): ClientRequestOptions['headers'] {
+  if (!apiKey) return base
+  if (typeof base === 'function') return async () => mergeHeaders(await base(), apiKey)
+  return mergeHeaders(base, apiKey)
+}
+
+function mergeHeaders(base: Record<string, string> | undefined, apiKey: string) {
+  const headers = new Headers(base)
+  headers.set('tempo-api-key', apiKey)
+  return Object.fromEntries(headers.entries())
+}

package/src/Metrics.ts

@@ -0,0 +1,154 @@
+import type * as Log from './internal/Log.js'
+
+/** Tag values a metric backend accepts. */
+export type Tags = Record<string, string | number | boolean | undefined | null>
+
+/**
+ * The bounded StatsD-style surface the built-in metric sinks emit to, plus an
+ * optional high-cardinality {@link Metrics.analytics} hook. Apps supply a
+ * concrete backend — e.g. {@link cloudflare} — so core carries no metrics-vendor
+ * dependency. Pass it as `metrics` to `App.create` and the webhook poller/queue
+ * handlers.
+ */
+export type Metrics = {
+  /**
+   * Optional per-request analytics sink, called once with the request-log entry
+   * for every response. Unlike the StatsD `count`/`gauge`/`histogram` surface
+   * (which stays low-cardinality), this hook carries the full entry — caller
+   * ids, org ids, route, status — for a wide-event store (e.g. ClickHouse).
+   * Attach it via {@link cloudflare}'s `analytics` option (or {@link from} for a
+   * custom backend); omit it to drop analytics. May be async; `App.create` does
+   * not await it.
+   */
+  analytics?: ((entry: Log.Entry) => Promise<void> | void) | undefined
+  /** Increments a counter; same name+tags are summed. */
+  count(name: string, value: number, tags?: Tags): void
+  /** Ships accumulated metrics. */
+  flush(): void
+  /** Sets a gauge; last write wins for the same name+tags. */
+  gauge(name: string, value: number, tags?: Tags): void
+  /** Records a histogram observation. */
+  histogram(name: string, value: number, tags?: Tags): void
+}
+
+/**
+ * Creates a {@link Metrics} from a value, type-checking it against the contract.
+ * The escape hatch for bringing your own backend (Datadog, Prometheus, …):
+ * author the implementation inline and have it validated against {@link Metrics}.
+ */
+export function from<const metrics extends Metrics>(metrics: metrics): metrics {
+  return metrics
+}
+
+/** Options for the {@link cloudflare} preset and its backend. */
+export declare namespace cloudflare {
+  /** Shared context handed to the {@link Options.analytics} factory. */
+  type Context = {
+    /** Resolved `enabled` flag; the analytics sink should drop events when false. */
+    enabled: boolean
+    /** Deployment environment, also added as the `environment` global tag. */
+    environment?: string | undefined
+    /** Service name, also added as the `service` global tag. */
+    service?: string | undefined
+  }
+  type Options = {
+    /**
+     * Builds the per-request {@link Metrics.analytics} hook from the shared
+     * {@link Context}, so the sink reuses `enabled`/`environment`/`service`
+     * instead of repeating them. Omit to drop analytics.
+     */
+    analytics?: ((context: Context) => Metrics['analytics']) | undefined
+    /** Set false (e.g. in local `wrangler dev`) to drop every metric and analytics event. Default true. */
+    enabled?: boolean | undefined
+    /** Deployment environment, added as the `environment` global tag and shared with {@link Options.analytics}. */
+    environment?: string | undefined
+    /** Service name, added as the `service` global tag and shared with {@link Options.analytics}. */
+    service?: string | undefined
+  }
+}
+
+/**
+ * A Cloudflare Workers {@link Metrics} — pass it as `metrics` to `App.create`
+ * and the webhook poller/queue handlers. It buffers metrics and emits them on
+ * `flush()` as `cwm-`-prefixed `console.log` lines (one per ≤250 KiB batch) for
+ * a Workers Logs → metrics pipeline to scrape; no external dependency.
+ */
+export function cloudflare(options: cloudflare.Options = {}): Metrics {
+  type Entry = { n: string; t: 'c' | 'g' | 'h'; tags: Tags; ts: number; v: number }
+
+  const enabled = options.enabled !== false
+
+  const analytics = options.analytics?.({
+    enabled,
+    environment: options.environment,
+    service: options.service,
+  })
+
+  if (!enabled) return { analytics, count() {}, flush() {}, gauge() {}, histogram() {} }
+
+  const globalTags: Tags = {
+    ...(options.environment === undefined ? {} : { environment: options.environment }),
+    ...(options.service === undefined ? {} : { service: options.service }),
+  }
+
+  const counts = new Map<string, Entry>()
+  const gauges = new Map<string, Entry>()
+  const histograms: Entry[] = []
+
+  const key = (name: string, tags: Tags) => {
+    let s = name
+    for (const k of Object.keys(tags).sort()) s += `\0${k}\0${tags[k]}`
+    return s
+  }
+  const withGlobal = (tags?: Tags): Tags => ({ ...globalTags, ...tags })
+
+  return {
+    analytics,
+    count(name, value, tags) {
+      const merged = withGlobal(tags)
+      const k = key(name, merged)
+      const existing = counts.get(k)
+      if (existing) existing.v += value
+      else counts.set(k, { n: name, t: 'c', tags: merged, ts: 0, v: value })
+    },
+    flush() {
+      const ts = Date.now()
+      const entries: Entry[] = []
+      for (const e of counts.values()) entries.push({ ...e, ts })
+      for (const e of gauges.values()) entries.push({ ...e, ts })
+      entries.push(...histograms)
+      counts.clear()
+      gauges.clear()
+      histograms.length = 0
+      if (!entries.length) return
+
+      // Emit as `cwm-[…]` lines, splitting batches over the size cap. Serialize
+      // with the field order the Workers Logs pipeline emits (`t,n,v,tags,ts`).
+      const parts = entries.map((e) =>
+        JSON.stringify({ t: e.t, n: e.n, v: e.v, tags: e.tags, ts: e.ts }),
+      )
+      let buf: string[] = []
+      let bufLen = 0
+      for (const part of parts) {
+        // 5 bytes for the `cwm-[` / `]` frame, plus one comma per joined part.
+        const wouldBe = 5 + (buf.length + 1) + bufLen + part.length
+        // 250 KiB: the largest `console.log` payload Workers Logs keeps untruncated.
+        if (buf.length > 0 && wouldBe > 250 * 1024) {
+          console.log(`cwm-[${buf.join(',')}]`)
+          buf = []
+          bufLen = 0
+        }
+        buf.push(part)
+        bufLen += part.length
+      }
+      if (buf.length) console.log(`cwm-[${buf.join(',')}]`)
+    },
+    gauge(name, value, tags) {
+      const merged = withGlobal(tags)
+      gauges.set(key(name, merged), { n: name, t: 'g', tags: merged, ts: 0, v: value })
+    },
+    histogram(name, value, tags) {
+      histograms.push({ n: name, t: 'h', tags: withGlobal(tags), ts: Date.now(), v: value })
+    },
+  }
+}

package/src/Scope.ts

@@ -0,0 +1,50 @@
+/**
+ * The issuable API-key scope vocabulary: the single source of truth for the
+ * `/scopes` catalog, for key minting (`ApiKeySource.Source.mint`), and for the scopes
+ * required by route policies (`Auth.policy`). Exposing it publicly lets operator
+ * tooling (e.g. the provisioning CLI) validate scopes against the same list the
+ * server enforces.
+ */
+
+/**
+ * Wildcard scope. A key whose `scopes` contains this value satisfies every
+ * required scope, so it never needs re-provisioning when new scopes are added.
+ * Use sparingly — it grants full access.
+ */
+export const wildcard = '*'
+
+/** Catalog entry describing an issuable API-key scope. */
+type Entry = {
+  /** Human-readable explanation of what the scope grants. */
+  description: string
+  /** Scope identifier used in a key's `scopes` and in route policies. */
+  scope: string
+}
+
+/**
+ * The issuable API-key scope vocabulary — the single source of truth for the
+ * `/scopes` catalog and for key minting. Route policies require values from this
+ * set; {@link wildcard} (`'*'`) is an implicit grant-all and is intentionally
+ * not listed as an issuable scope.
+ */
+export const catalog = [
+  {
+    description: 'Read public chain data: tokens, transactions, transfers, blocks, and receipts.',
+    scope: 'data:read',
+  },
+  {
+    description: 'Run ad-hoc queries against the raw indexer passthrough.',
+    scope: 'indexer:query',
+  },
+  {
+    description: 'Read webhook subscriptions.',
+    scope: 'webhooks:read',
+  },
+  {
+    description: 'Create, update, and delete webhook subscriptions.',
+    scope: 'webhooks:write',
+  },
+] as const satisfies readonly Entry[]
+
+/** Issuable API-key scope identifier — the union of every {@link catalog} entry. */
+export type Id = (typeof catalog)[number]['scope']

package/src/Webhooks.test.ts

@@ -0,0 +1,49 @@
+import { Store, Webhooks } from 'cadent'
+
+describe('createPoller', () => {
+  /** Decodes the opaque `(block, index)` keyset cursor the poller stores. */
+  function decodeCursor(token: string | null): [number, number] | null {
+    if (!token) return null
+    const json = atob(token.replaceAll('-', '+').replaceAll('_', '/'))
+    return JSON.parse(json) as [number, number]
+  }
+
+  test('binds a state store and runs a tick at an injected head', async () => {
+    const store = Store.memory()
+    const subscription = await Webhooks.createSubscription(store, {
+      chainId: 42431,
+      destination: { type: 'url', url: 'https://hooks.example.com/x' },
+      eventType: 'token:transfer',
+      owner: { orgId: 'org_test', type: 'api_key' },
+    })
+
+    const poller = Webhooks.createPoller({
+      defaultChainId: 42431,
+      webhook: { store },
+    })
+
+    // A brand-new subscription anchors at the confirmed head on its first tick
+    // (no backfill), so this exercises the createPoller → poll wiring (store
+    // binding, default chain id, injected head, result shape) without touching
+    // TIDX. Detailed poll/getIndexedHead behavior lives in
+    // src/apps/webhooks.test.ts.
+    const result = await poller.tick({ headBlockNumber: 200 })
+
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "chainId": 42431,
+        "dispatched": 0,
+        "failed": 0,
+        "safeBlock": 198,
+        "scanned": 0,
+        "subscriptions": 1,
+      }
+    `)
+    expect(decodeCursor(await Webhooks.getCursor(store, subscription.id))).toMatchInlineSnapshot(`
+      [
+        198,
+        2147483647,
+      ]
+    `)
+  })
+})

package/src/Webhooks.ts

@@ -0,0 +1,172 @@
+import * as AppWebhooks from './apps/webhooks.js'
+import * as MetricSink from './internal/MetricSink.js'
+import type * as Store from './internal/Store.js'
+import type * as Metrics from './Metrics.js'
+import * as Tidx from './internal/Tidx.js'
+import * as Viem from './internal/Viem.js'
+
+// Re-export the runtime-agnostic primitives (subscriptions, signing, delivery,
+// `deliverAndRecord`, cursors, …) so consumers reach everything through one
+// `Webhooks` namespace. The apps-layer poller stays private behind
+// `createPoller` below.
+export * from './internal/Webhooks.js'
+
+// Re-export the webhook resource's zod schemas so consumers can validate and
+// type delivery bodies: `Webhooks.schema.Envelope` (a discriminated union on
+// `type`), plus the per-event `TransferEvent` / `TransactionEvent` / `PingEvent`
+// payloads. Infer a type with `z.infer<typeof Webhooks.schema.Envelope>`.
+export { eventTypes, schema } from './apps/webhooks.js'
+
+/**
+ * Builds a scheduled webhook poller bound to a state store and chain config.
+ *
+ * This is the entry point a host runtime drives on a timer (a Cloudflare
+ * `scheduled` cron handler, a self-host `setInterval`, …). Each {@link
+ * Poller.tick} scans active subscriptions from their cursors up to `head -
+ * confirmations` and dispatches matching events.
+ *
+ * The monitoring event types (`log:emitted`, `block:created`,
+ * `transaction:included`) scan a confirmed window directly over JSON-RPC, so the
+ * poller builds memoized viem clients (via {@link Viem.getClient}); the legacy
+ * `token:transfer` type still reads from TIDX, so it
+ * also builds memoized TIDX clients (via {@link Tidx.createGetClient}) when a
+ * `tidx` config is supplied. The poller keeps `App.create` a pure Hono app: it
+ * constructs its own clients instead of reaching into app internals, and owns no
+ * request state.
+ */
+export function createPoller(options: createPoller.Options): createPoller.Poller {
+  const { store } = options.webhook
+  const getTidx = options.tidx
+    ? Tidx.createGetClient({ defaultChainId: options.defaultChainId, tidx: options.tidx })
+    : undefined
+  const clients = new Map<number, Viem.getClient.ReturnType>()
+  const getClient = (chainId: Viem.ChainId) => {
+    let client = clients.get(chainId)
+    if (!client) {
+      client = Viem.getClient({ chainId, rpc: options.rpc })
+      clients.set(chainId, client)
+    }
+    return client
+  }
+
+  const metrics = options.metrics ? MetricSink.webhooks(options.metrics) : undefined
+
+  return {
+    async tick(input = {}) {
+      const chainId = input.chainId ?? options.defaultChainId ?? Viem.defaultChainId
+
+      // Wrap the transport so each enqueue (or inline delivery) emits a timed
+      // `webhook:enqueue` metric. The wrapper preserves the dispatch contract: it
+      // returns the underlying result unchanged and is a no-op when no metrics
+      // backend is configured.
+      const inner = input.dispatch ?? options.dispatch
+      const dispatch =
+        metrics && inner
+          ? async (dispatchable: AppWebhooks.poll.Dispatchable) => {
+              const start = Date.now()
+              const result = await inner(dispatchable)
+              metrics.record({
+                chainId: dispatchable.envelope.chainId,
+                durationMs: Date.now() - start,
+                eventType: dispatchable.envelope.type,
+                ok: result.ok,
+                type: 'webhook:enqueue',
+              })
+              return result
+            }
+          : inner
+
+      const start = Date.now()
+      try {
+        const result = await AppWebhooks.poll({
+          batchSize: input.batchSize ?? options.batchSize,
+          chainId,
+          client: getClient(chainId),
+          confirmations: input.confirmations ?? options.confirmations,
+          dispatch,
+          eventTypes: input.eventTypes ?? options.eventTypes,
+          ...(input.headBlockNumber === undefined
+            ? {}
+            : { headBlockNumber: input.headBlockNumber }),
+          maxBlocks: input.maxBlocks ?? options.maxBlocks,
+          now: input.now ?? options.now,
+          store,
+          ...(getTidx ? { tidx: getTidx(chainId) } : {}),
+        })
+        metrics?.record({
+          meta: { durationMs: Date.now() - start, outcome: 'ok' },
+          result,
+          type: 'webhook:tick',
+        })
+        return result
+      } catch (error) {
+        metrics?.record({
+          meta: { chainId, durationMs: Date.now() - start, outcome: 'error' },
+          result: undefined,
+          type: 'webhook:tick',
+        })
+        throw error
+      } finally {
+        metrics?.flush()
+      }
+    },
+  }
+}
+
+export declare namespace createPoller {
+  /** A row to dispatch, paired with its owning subscription. */
+  type Dispatchable = AppWebhooks.poll.Dispatchable
+
+  /** Delivery transport: hands a matched event to a queue or delivers inline. */
+  type Dispatch = NonNullable<AppWebhooks.poll.Options['dispatch']>
+
+  /** Summary counters returned by {@link Poller.tick}. */
+  type Result = AppWebhooks.poll.Result
+
+  /** Knobs shared by every {@link Poller.tick}; each is overridable per tick. */
+  type Defaults = {
+    /** Max matching rows scanned per subscription per tick (default 100). */
+    batchSize?: number | undefined
+    /** Reorg-safety window: only emit blocks this far behind head (default 2). */
+    confirmations?: number | undefined
+    /**
+     * Delivery transport. Defaults to inline `deliverAndRecord` (self-host); on
+     * Cloudflare pass a Queue producer so retry/backoff/DLQ are native.
+     */
+    dispatch?: Dispatch | undefined
+    /** Event types to poll (default all). */
+    eventTypes?: AppWebhooks.poll.Options['eventTypes']
+    /** Backfill cap: most blocks an RPC scanner inspects per tick (default 1000). */
+    maxBlocks?: number | undefined
+    /** Clock for envelope timestamps; injectable for tests. */
+    now?: (() => Date) | undefined
+  }
+
+  /** Options for {@link createPoller}. */
+  type Options = Defaults & {
+    /** Tempo chain id polled when a tick omits one. */
+    defaultChainId?: Viem.ChainId | undefined
+    /** Metrics backend; emits `webhook:tick` per tick and `webhook:enqueue` per dispatch. */
+    metrics?: Metrics.Metrics | undefined
+    /** RPC options for the viem clients the monitoring scanners read from. */
+    rpc?: Viem.getClient.Rpc | undefined
+    /** TIDX query client options for the legacy `token:transfer` type. */
+    tidx?: Tidx.getClient.Tidx | undefined
+    /** Webhook state store (subscriptions + cursors). */
+    webhook: { store: Store.State }
+  }
+
+  /** Per-tick overrides; falls back to the {@link Options} defaults. */
+  type TickOptions = Defaults & {
+    /** Chain to poll this tick (default `options.defaultChainId`). */
+    chainId?: Viem.ChainId | undefined
+    /** Chain head to work back from; resolved from RPC when omitted. */
+    headBlockNumber?: bigint | number | undefined
+  }
+
+  /** A scheduled webhook poller. */
+  type Poller = {
+    /** Runs one poll tick, resolving the indexed head when not supplied. */
+    tick(options?: TickOptions): Promise<Result>
+  }
+}