| 1 | # Adapter Source Template |
| 2 | |
| 3 | Complete TypeScript template for `packages/evlog/src/adapters/{name}.ts`. |
| 4 | |
| 5 | Replace `{Name}`, `{name}`, and ` |
| 6 | |
| 7 | ```typescript |
| 8 | import type { DrainContext, |
| 9 | import { getRuntimeConfig } |
| 10 | |
| 11 | // --- 1. Config Interface --- |
| 12 | // Define all service-specific configuration fields. |
| 13 | // Always include optional `timeout`. |
| 14 | export interface {Name} |
| 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} |
| 30 | // Define the target service's event shape |
| 31 | timestamp: string |
| 32 | level: string |
| 33 | data: Record<string |
| 34 | } |
| 35 | |
| 36 | /** |
| 37 | * Convert a WideEvent to {Name}'s event format. |
| 38 | */ |
| 39 | export function to{Name |
| 40 | const { timestamp, |
| 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 |
| 74 | return async (ctx: |
| 75 | const runtimeConfig |
| 76 | const evlogConfig |
| 77 | const rootConfig |
| 78 | |
| 79 | // Build config with fallbacks |
| 80 | const config |
| 81 | apiKey: overrides |
| 82 | ?? process.env |
| 83 | endpoint: overrides |
| 84 | ?? process.env |
| 85 | timeout: overrides |
| 86 | } |
| 87 | |
| 88 | // Validate required fields |
| 89 | if (!config.apiKey |
| 90 | console.error( |
| 91 | return |
| 92 | } |
| 93 | |
| 94 | try { |
| 95 | await sendTo |
| 96 | } catch (error) { |
| 97 | console.error('[evlog/{name}] Failed to send event: |
| 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 |
| 110 | await sendBatchTo{Name}([event |
| 111 | } |
| 112 | |
| 113 | /** |
| 114 | * Send a batch of events to {Name}. |
| 115 | */ |
| 116 | export async function sendBatchTo{Name}(events: WideEvent[], config |
| 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. |
| 149 | } |
| 150 | } finally { |
| 151 | clearTimeout(timeoutId) |
| 152 | } |
| 153 | } |
| 154 | ``` |
| 155 | |
| 156 | ## Customization Notes |
| 157 | |
| 158 | - **Auth style**: Some services use |
| 159 | - **Payload format**: Some services accept raw JSON arrays (Axiom), others need a wrapper object (PostHog |
| 160 | - **Event transformation**: If the service expects a specific schema, implement |
| 161 | - **URL construction**: Match the service's API endpoint pattern. Some use path-based routing ( |
| 162 | - **Extra config fields**: Add service-specific fields to the config interface (e.g., |