evlog Adapter Creator

Create evlog Adapter

Add a new built-in adapter to evlog. Every adapter follows the same architecture and is built on the public toolkit primitives in evlog/toolkit, so a community adapter has the same shape as a built-in one.

PR Title

feat({name}): add the {Name} drain adapter

Recent examples: feat(loki): add the Grafana Loki drain adapter, feat(clickhouse): add the ClickHouse drain adapter. Use the adapter name as the conventional-commit scope, and register that scope (see touchpoint 11).

Scope timing caveat: the semantic PR check reads its scope list from the base branch, so a brand-new scope can't validate the very PR that introduces it. Either register the scope in a small preceding PR (the Loki/ClickHouse pattern), or use an unscoped title (feat: add the {Name} drain adapter) on the introducing PR.

Touchpoints Checklist

Important: Do NOT consider the task complete until all 12 touchpoints have been addressed.

Naming Conventions

Use these placeholders consistently:

Standard option naming (use these exact names):

If a service historically used a different name (token, sourceToken, …) keep it as a deprecated alias via applyDeprecatedAlias. See Axiom and Better Stack for the pattern.

Step 1: Adapter Source: built on defineHttpDrain

Create packages/evlog/src/adapters/{name}.ts. Read references/adapter-template.md for the full annotated template. loki.ts and clickhouse.ts are the most recent reference implementations.

The contract is defineHttpDrain<TConfig>({ name, label, resolve, encode }). You only ship two pieces of logic:

1. resolve(): produce a fully-resolved config or null to skip. Use resolveAdapterConfig for the standard precedence (overrides → runtimeConfig.evlog.{name} → runtimeConfig.{name} → env vars). List NUXT_{NAME}_* before {NAME}_* in ConfigField.env for silent Nuxt compat; show only {NAME}_* in user-facing messages via formatPublicEnvKeys.
2. encode(events, config): a private encode{Name}Request(events, config): HttpDrainRequest returning { url, headers, body } for a batch. HTTP transport, identity headers, retries, timeout, and error logging are handled by defineHttpDrain (via httpPost).

Key rules:

• Single factory. Export one create{Name}Drain(overrides?: Partial<{Name}Config>). No dual-API factories: if a service has multiple ingest modes (logs vs events), expose them via a mode option (see PostHog).
• No HTTP code in the adapter. Never call fetch directly. If the service truly needs custom transport (binary envelopes, non-HTTP), use defineDrain from ../shared/drain instead, see fs.ts and memory.ts.
• Encode parity. The standalone sendTo{Name} / sendBatchTo{Name} helpers must reuse the same private encode{Name}Request() and go through sendEncodedDrainRequest(request, { label, source, timeout, retries }), never a separate fetch path. test/adapters/encode-parity.test.ts pins this for a subset of adapters; add the new one to it (not every existing adapter is registered there yet, and that is a gap, not a license to skip).
• No bespoke config resolution. Always go through resolveAdapterConfig. Deprecated aliases (token → apiKey) go through applyDeprecatedAlias.
• Exported converters. If the service needs a specific event shape, export to{Name}Event() / build{Name}Payload() helpers so they're testable independently.
• Edge-safe. Adapters run on Cloudflare Workers: no Buffer (use TextEncoder + btoa, see loki.ts), no Node-only APIs. fs.ts shows the isEdgeRuntime() guard pattern when a runtime genuinely can't be supported.

Step 2: Build Config

Add a build entry in packages/evlog/tsdown.config.ts alongside the existing adapters:

'adapters/{name}': 'src/adapters/{name}.ts',

Follow the existing ordering in that file.

Step 3: Package Exports

In packages/evlog/package.json, add two entries (after the last adapter, and check the current list rather than assuming):

In exports:

"./{name}": {
  "types": "./dist/adapters/{name}.d.mts",
  "import": "./dist/adapters/{name}.mjs"
}

In typesVersions["*"]:

"{name}": [
  "./dist/adapters/{name}.d.mts"
]

Any export added to package.json without a matching tsdown.config.ts entry (and vice versa) fails test/toolkit/api-surface.test.ts, which is touchpoint 6.