Create Evlog Adapter

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 11 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.

Step 4: Unit Tests

Create packages/evlog/test/adapters/{name}.test.ts. Read references/test-template.md for the full annotated template, and packages/evlog/test/README.md for the repo-wide conventions.

Non-negotiables from the test README:

• Use mockFetch() / getFetchCall / getFetchJson / getFetchHeaders from test/helpers/fetch.ts, never hand-roll vi.spyOn(globalThis, 'fetch') boilerplate.
• Clean up any env vars the adapter reads in afterEach.
• Test the exported pure helpers (to{Name}Event, build{Name}Payload, URL resolvers) directly, one describe per helper.

Required test categories:

1. URL construction (default + custom endpoint, trailing-slash tolerance)
2. Headers (auth, content-type, service-specific)
3. Request body format (JSON structure matches service API)
4. Skip behavior when apiKey (or required field) is missing
5. Batch operations (multiple events in one request, empty batch skips fetch)
6. Deprecated alias still works (when applicable)
7. Add the adapter to test/adapters/encode-parity.test.ts

Step 5: E2E Test + Sandbox

Create packages/evlog/test/e2e/{name}.e2e.ts, gated on the adapter's env vars (skipped when absent). Run with pnpm test:e2e.

If the service is self-hostable, extend the local sandbox so the adapter can be exercised without cloud credentials:

• packages/evlog/test/e2e/docker-compose.yml: add the service
• packages/evlog/test/e2e/seed.mjs: fan the seeder out to the new backend
• packages/evlog/test/e2e/README.md: document it
• Root package.json sandbox:e2e script: add the local env var if needed