|
| 1 | +# Adapter Source Template |
| 2 | + |
| 3 | +Complete TypeScript template for `packages/evlog/src/adapters/{name}.ts`. |
| 4 | + |
| 5 | +Replace `{Name}`, `{name}`, and `{NAME}` with the actual service name. |
| 6 | + |
| 7 | +```typescript |
| 8 | +import type { DrainContext, WideEvent } from '../types' |
| 9 | +import { getRuntimeConfig } from './_utils' |
| 10 | + |
| 11 | +// --- 1. Config Interface --- |
| 12 | +// Define all service-specific configuration fields. |
| 13 | +// Always include optional `timeout`. |
| 14 | +export interface {Name}Config { |
| 15 | + /** {Name} API key / token */ |
| 16 | + apiKey: string |
| 17 | + /** {Name} API endpoint. Default: https://api.{name}.com */ |
| 18 | + endpoint?: string |
| 19 | + /** Request timeout in milliseconds. Default: 5000 */ |
| 20 | + timeout?: number |
| 21 | + // Add service-specific fields here (dataset, project, region, etc.) |
| 22 | +} |
| 23 | + |
| 24 | +// --- 2. Event Transformation (optional) --- |
| 25 | +// Export a converter if the service needs a specific format. |
| 26 | +// This makes the transformation testable independently. |
| 27 | + |
| 28 | +/** {Name} event structure */ |
| 29 | +export interface {Name}Event { |
| 30 | + // Define the target service's event shape |
| 31 | + timestamp: string |
| 32 | + level: string |
| 33 | + data: Record<string, unknown> |
| 34 | +} |
| 35 | + |
| 36 | +/** |
| 37 | + * Convert a WideEvent to {Name}'s event format. |
| 38 | + */ |
| 39 | +export function to{Name}Event(event: WideEvent): {Name}Event { |
| 40 | + const { timestamp, level, ...rest } = event |
| 41 | + |
| 42 | + return { |
| 43 | + timestamp, |
| 44 | + level, |
| 45 | + data: rest, |
| 46 | + } |
| 47 | +} |
| 48 | + |
| 49 | +// --- 3. Factory Function --- |
| 50 | +// Returns a drain function that resolves config at call time. |
| 51 | +// Config priority: overrides > runtimeConfig.evlog.{name} > runtimeConfig.{name} > env vars |
| 52 | + |
| 53 | +/** |
| 54 | + * Create a drain function for sending logs to {Name}. |
| 55 | + * |
| 56 | + * Configuration priority (highest to lowest): |
| 57 | + * 1. Overrides passed to create{Name}Drain() |
| 58 | + * 2. runtimeConfig.evlog.{name} |
| 59 | + * 3. runtimeConfig.{name} |
| 60 | + * 4. Environment variables: NUXT_{NAME}_*, {NAME}_* |
| 61 | + * |
| 62 | + * @example |
| 63 | + * ```ts |
| 64 | + * // Zero config - set NUXT_{NAME}_API_KEY env var |
| 65 | + * nitroApp.hooks.hook('evlog:drain', create{Name}Drain()) |
| 66 | + * |
| 67 | + * // With overrides |
| 68 | + * nitroApp.hooks.hook('evlog:drain', create{Name}Drain({ |
| 69 | + * apiKey: 'my-key', |
| 70 | + * })) |
| 71 | + * ``` |
| 72 | + */ |
| 73 | +export function create{Name}Drain(overrides?: Partial<{Name}Config>): (ctx: DrainContext) => Promise<void> { |
| 74 | + return async (ctx: DrainContext) => { |
| 75 | + const runtimeConfig = getRuntimeConfig() |
| 76 | + const evlogConfig = runtimeConfig?.evlog?.{name} |
| 77 | + const rootConfig = runtimeConfig?.{name} |
| 78 | + |
| 79 | + // Build config with fallbacks |
| 80 | + const config: Partial<{Name}Config> = { |
| 81 | + apiKey: overrides?.apiKey ?? evlogConfig?.apiKey ?? rootConfig?.apiKey |
| 82 | + ?? process.env.NUXT_{NAME}_API_KEY ?? process.env.{NAME}_API_KEY, |
| 83 | + endpoint: overrides?.endpoint ?? evlogConfig?.endpoint ?? rootConfig?.endpoint |
| 84 | + ?? process.env.NUXT_{NAME}_ENDPOINT ?? process.env.{NAME}_ENDPOINT, |
| 85 | + timeout: overrides?.timeout ?? evlogConfig?.timeout ?? rootConfig?.timeout, |
| 86 | + } |
| 87 | + |
| 88 | + // Validate required fields |
| 89 | + if (!config.apiKey) { |
| 90 | + console.error('[evlog/{name}] Missing apiKey. Set NUXT_{NAME}_API_KEY env var or pass to create{Name}Drain()') |
| 91 | + return |
| 92 | + } |
| 93 | + |
| 94 | + try { |
| 95 | + await sendTo{Name}(ctx.event, config as {Name}Config) |
| 96 | + } catch (error) { |
| 97 | + console.error('[evlog/{name}] Failed to send event:', error) |
| 98 | + } |
| 99 | + } |
| 100 | +} |
| 101 | + |
| 102 | +// --- 5. Send Functions --- |
| 103 | +// Exported for direct use and testability. |
| 104 | +// sendTo{Name} wraps sendBatchTo{Name} for single events. |
| 105 | + |
| 106 | +/** |
| 107 | + * Send a single event to {Name}. |
| 108 | + */ |
| 109 | +export async function sendTo{Name}(event: WideEvent, config: {Name}Config): Promise<void> { |
| 110 | + await sendBatchTo{Name}([event], config) |
| 111 | +} |
| 112 | + |
| 113 | +/** |
| 114 | + * Send a batch of events to {Name}. |
| 115 | + */ |
| 116 | +export async function sendBatchTo{Name}(events: WideEvent[], config: {Name}Config): Promise<void> { |
| 117 | + if (events.length === 0) return |
| 118 | + |
| 119 | + const endpoint = (config.endpoint ?? 'https://api.{name}.com').replace(/\/$/, '') |
| 120 | + const timeout = config.timeout ?? 5000 |
| 121 | + // Construct the full URL for the service's ingest API |
| 122 | + const url = `${endpoint}/v1/ingest` |
| 123 | +
|
| 124 | + const headers: Record<string, string> = { |
| 125 | + 'Content-Type': 'application/json', |
| 126 | + 'Authorization': `Bearer ${config.apiKey}`, |
| 127 | + // Add service-specific headers here |
| 128 | + } |
| 129 | +
|
| 130 | + // Transform events if the service needs a specific format |
| 131 | + const payload = events.map(to{Name}Event) |
| 132 | + // Or send raw: JSON.stringify(events) |
| 133 | +
|
| 134 | + const controller = new AbortController() |
| 135 | + const timeoutId = setTimeout(() => controller.abort(), timeout) |
| 136 | +
|
| 137 | + try { |
| 138 | + const response = await fetch(url, { |
| 139 | + method: 'POST', |
| 140 | + headers, |
| 141 | + body: JSON.stringify(payload), |
| 142 | + signal: controller.signal, |
| 143 | + }) |
| 144 | +
|
| 145 | + if (!response.ok) { |
| 146 | + const text = await response.text().catch(() => 'Unknown error') |
| 147 | + const safeText = text.length > 200 ? `${text.slice(0, 200)}...[truncated]` : text |
| 148 | + throw new Error(`{Name} API error: ${response.status} ${response.statusText} - ${safeText}`) |
| 149 | + } |
| 150 | + } finally { |
| 151 | + clearTimeout(timeoutId) |
| 152 | + } |
| 153 | +} |
| 154 | +``` |
| 155 | + |
| 156 | +## Customization Notes |
| 157 | + |
| 158 | +- **Auth style**: Some services use `Authorization: Bearer`, others use a custom header like `X-API-Key`. Adjust the headers accordingly. |
| 159 | +- **Payload format**: Some services accept raw JSON arrays (Axiom), others need a wrapper object (PostHog `{ api_key, batch }`), others need a protocol-specific structure (OTLP). Adapt `sendBatchTo{Name}` to match. |
| 160 | +- **Event transformation**: If the service expects a specific schema, implement `to{Name}Event()`. If the service accepts arbitrary JSON, you can skip it and send `ctx.event` directly. |
| 161 | +- **URL construction**: Match the service's API endpoint pattern. Some use path-based routing (`/v1/datasets/{id}/ingest`), others use a flat endpoint (`/batch/`). |
| 162 | +- **Extra config fields**: Add service-specific fields to the config interface (e.g., `dataset` for Axiom, `orgId` for org-scoped APIs, `host` for region selection). |
0 commit comments