autotel-aws 0.2.0

package/dist/eventbridge.d.cts

@@ -0,0 +1,360 @@
+import { TraceContext } from 'autotel';
+import { SpanContext } from '@opentelemetry/api';
+
+/**
+ * EventBridge instrumentation
+ *
+ * Provides helpers for tracing Amazon EventBridge operations with
+ * automatic W3C Trace Context propagation for distributed tracing.
+ *
+ * @example Publish events with trace context
+ * ```typescript
+ * import { EventBridgePublisher } from 'autotel-aws/eventbridge';
+ * import { EventBridgeClient } from '@aws-sdk/client-eventbridge';
+ *
+ * const client = new EventBridgeClient({ region: 'us-east-1' });
+ * const publisher = new EventBridgePublisher(client, {
+ *   eventBusName: 'my-event-bus',
+ *   source: 'com.myapp.orders'
+ * });
+ *
+ * // Publish with automatic trace context injection
+ * await publisher.putEvent({
+ *   detailType: 'OrderCreated',
+ *   detail: { orderId: '123', customerId: 'abc' }
+ * });
+ * ```
+ *
+ * @example Extract context in Lambda triggered by EventBridge
+ * ```typescript
+ * import { extractEventBridgeContext } from 'autotel-aws/eventbridge';
+ * import { wrapHandler } from 'autotel-aws/lambda';
+ *
+ * export const handler = wrapHandler(async (event) => {
+ *   // Extract trace context from EventBridge event detail
+ *   const parentContext = extractEventBridgeContext(event);
+ *
+ *   // Process the event
+ *   const { orderId, customerId } = event.detail;
+ *   await processOrder(orderId, customerId);
+ *
+ *   return { statusCode: 200 };
+ * });
+ * ```
+ *
+ * @example Trace EventBridge operations with helper
+ * ```typescript
+ * import { traceEventBridge } from 'autotel-aws/eventbridge';
+ *
+ * export const publishOrderEvent = traceEventBridge({
+ *   eventBus: 'orders-bus',
+ *   source: 'order-service',
+ *   detailType: 'OrderCreated'
+ * })(ctx => async (order: Order) => {
+ *   ctx.setAttribute('order.id', order.id);
+ *   await eventBridge.send(new PutEventsCommand({
+ *     Entries: [{
+ *       EventBusName: 'orders-bus',
+ *       Source: 'order-service',
+ *       DetailType: 'OrderCreated',
+ *       Detail: JSON.stringify(injectEventBridgeContext(order))
+ *     }]
+ *   }));
+ * });
+ * ```
+ */
+
+/**
+ * EventBridge operation configuration for traceEventBridge helper
+ */
+interface TraceEventBridgeConfig {
+    /**
+     * Event bus name or ARN
+     */
+    eventBus: string;
+    /**
+     * Event source (e.g., 'com.myapp.orders')
+     */
+    source: string;
+    /**
+     * Event detail type (e.g., 'OrderCreated')
+     */
+    detailType: string;
+}
+/**
+ * Configuration for EventBridgePublisher
+ */
+interface EventBridgePublisherConfig {
+    /**
+     * Event bus name or ARN
+     * @default 'default' (the account's default event bus)
+     */
+    eventBusName?: string;
+    /**
+     * Event source (e.g., 'com.myapp.orders')
+     */
+    source: string;
+    /**
+     * Inject W3C Trace Context into event detail
+     * @default true
+     */
+    injectTraceContext?: boolean;
+    /**
+     * Optional service name for tracing
+     */
+    service?: string;
+}
+/**
+ * Event to publish via EventBridgePublisher
+ */
+interface EventBridgeEvent<T = Record<string, unknown>> {
+    /**
+     * Event detail type (e.g., 'OrderCreated', 'UserSignedUp')
+     */
+    detailType: string;
+    /**
+     * Event detail (the actual payload)
+     */
+    detail: T;
+    /**
+     * Optional resources ARNs associated with the event
+     */
+    resources?: string[];
+    /**
+     * Optional time for the event (defaults to current time)
+     */
+    time?: Date;
+    /**
+     * Optional trace header (for X-Ray integration)
+     */
+    traceHeader?: string;
+}
+/**
+ * Trace context fields injected into EventBridge detail
+ */
+interface TraceContextFields {
+    _traceContext?: {
+        traceparent: string;
+        tracestate?: string;
+        baggage?: string;
+    };
+}
+/**
+ * EventBridge event structure (Lambda event format)
+ */
+interface EventBridgeLambdaEvent {
+    version?: string;
+    id?: string;
+    'detail-type'?: string;
+    source?: string;
+    account?: string;
+    time?: string;
+    region?: string;
+    resources?: string[];
+    detail?: Record<string, unknown> & TraceContextFields;
+}
+/**
+ * Inject W3C Trace Context into EventBridge event detail
+ *
+ * Adds `_traceContext` field with traceparent, tracestate, and baggage.
+ * This enables distributed tracing from the publisher to all event consumers.
+ *
+ * @param detail - The event detail object
+ * @returns Detail with trace context injected
+ *
+ * @example
+ * ```typescript
+ * const detail = { orderId: '123', status: 'created' };
+ * const detailWithContext = injectEventBridgeContext(detail);
+ * // { orderId: '123', status: 'created', _traceContext: { traceparent: '...' } }
+ *
+ * await eventBridge.send(new PutEventsCommand({
+ *   Entries: [{
+ *     EventBusName: 'my-bus',
+ *     Source: 'my-app',
+ *     DetailType: 'OrderCreated',
+ *     Detail: JSON.stringify(detailWithContext)
+ *   }]
+ * }));
+ * ```
+ */
+declare function injectEventBridgeContext<T extends Record<string, unknown>>(detail: T): T & TraceContextFields;
+/**
+ * Extract W3C Trace Context from EventBridge Lambda event
+ *
+ * Extracts the `_traceContext` field from the event detail.
+ * Works with the Lambda event format from EventBridge rules.
+ *
+ * @param event - EventBridge Lambda event
+ * @returns SpanContext if trace context was found, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * // In a Lambda triggered by EventBridge
+ * export const handler = async (event: EventBridgeLambdaEvent) => {
+ *   const parentContext = extractEventBridgeContext(event);
+ *   // Use parentContext to link traces...
+ *
+ *   // Access detail without trace context
+ *   const cleanDetail = stripEventBridgeContext(event.detail);
+ * };
+ * ```
+ */
+declare function extractEventBridgeContext(event: EventBridgeLambdaEvent): SpanContext | undefined;
+/**
+ * Strip trace context fields from EventBridge event detail
+ *
+ * Returns the detail without `_traceContext` field for cleaner processing.
+ *
+ * @param detail - EventBridge event detail with optional trace context
+ * @returns Detail without trace context fields
+ *
+ * @example
+ * ```typescript
+ * const detail = { orderId: '123', _traceContext: { ... } };
+ * const cleanDetail = stripEventBridgeContext(detail);
+ * // { orderId: '123' }
+ * ```
+ */
+declare function stripEventBridgeContext<T extends Record<string, unknown>>(detail: T): Omit<T, '_traceContext'>;
+/**
+ * Trace EventBridge operations with semantic attributes
+ *
+ * Creates a traced function that automatically sets EventBridge attributes.
+ *
+ * @param config - EventBridge operation configuration
+ * @returns A higher-order function that wraps your EventBridge operation with tracing
+ *
+ * @remarks
+ * Semantic attributes set automatically:
+ * - `aws.eventbridge.event_bus` - Event bus name
+ * - `aws.eventbridge.source` - Event source
+ * - `aws.eventbridge.detail_type` - Event detail type
+ *
+ * @example
+ * ```typescript
+ * export const publishOrderEvent = traceEventBridge({
+ *   eventBus: 'orders-bus',
+ *   source: 'order-service',
+ *   detailType: 'OrderCreated'
+ * })(ctx => async (order: Order) => {
+ *   ctx.setAttribute('order.id', order.id);
+ *
+ *   const detail = injectEventBridgeContext(order);
+ *   await eventBridge.send(new PutEventsCommand({
+ *     Entries: [{
+ *       EventBusName: 'orders-bus',
+ *       Source: 'order-service',
+ *       DetailType: 'OrderCreated',
+ *       Detail: JSON.stringify(detail)
+ *     }]
+ *   }));
+ * });
+ * ```
+ */
+declare function traceEventBridge(config: TraceEventBridgeConfig): <TArgs extends unknown[], TReturn>(fn: (ctx: TraceContext) => (...args: TArgs) => Promise<TReturn>) => (...args: TArgs) => Promise<TReturn>;
+/**
+ * EventBridge Publisher with automatic trace context injection
+ *
+ * Wraps an EventBridge client to automatically:
+ * - Create spans for PutEvents operations
+ * - Inject W3C Trace Context into event detail
+ * - Set proper semantic attributes
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { EventBridgePublisher } from 'autotel-aws/eventbridge';
+ * import { EventBridgeClient } from '@aws-sdk/client-eventbridge';
+ *
+ * const client = new EventBridgeClient({ region: 'us-east-1' });
+ * const publisher = new EventBridgePublisher(client, {
+ *   eventBusName: 'my-event-bus',
+ *   source: 'com.myapp.orders'
+ * });
+ *
+ * // Publish single event
+ * const result = await publisher.putEvent({
+ *   detailType: 'OrderCreated',
+ *   detail: { orderId: '123', customerId: 'abc' }
+ * });
+ * console.log('Event ID:', result.eventId);
+ * ```
+ *
+ * @example Batch publish multiple events
+ * ```typescript
+ * const results = await publisher.putEvents([
+ *   { detailType: 'OrderCreated', detail: { orderId: '1' } },
+ *   { detailType: 'OrderCreated', detail: { orderId: '2' } },
+ *   { detailType: 'OrderCreated', detail: { orderId: '3' } }
+ * ]);
+ *
+ * console.log(`Published ${results.successful.length} events`);
+ * console.log(`Failed ${results.failed.length} events`);
+ * ```
+ *
+ * @example Multiple sources
+ * ```typescript
+ * // Create publishers for different event sources
+ * const ordersPublisher = new EventBridgePublisher(client, {
+ *   source: 'com.myapp.orders'
+ * });
+ *
+ * const usersPublisher = new EventBridgePublisher(client, {
+ *   source: 'com.myapp.users'
+ * });
+ *
+ * await ordersPublisher.putEvent({ detailType: 'OrderCreated', detail: {...} });
+ * await usersPublisher.putEvent({ detailType: 'UserSignedUp', detail: {...} });
+ * ```
+ */
+declare class EventBridgePublisher<TClient extends {
+    send: (command: any) => Promise<any>;
+} = any> {
+    private client;
+    private config;
+    constructor(client: TClient, config: EventBridgePublisherConfig);
+    /**
+     * Publish a single event to EventBridge
+     *
+     * @param event - Event to publish
+     * @returns Promise with event ID (if successful)
+     */
+    putEvent<T extends Record<string, unknown>>(event: EventBridgeEvent<T>): Promise<{
+        eventId?: string;
+        failedEntryCount?: number;
+    }>;
+    /**
+     * Publish multiple events in a batch
+     *
+     * @param events - Array of events to publish (max 10 per API call)
+     * @returns Promise with successful and failed event results
+     */
+    putEvents<T extends Record<string, unknown>>(events: EventBridgeEvent<T>[]): Promise<{
+        successful: Array<{
+            eventId?: string;
+            detailType: string;
+        }>;
+        failed: Array<{
+            errorCode?: string;
+            errorMessage?: string;
+            detailType: string;
+        }>;
+        failedEntryCount: number;
+    }>;
+    /**
+     * Publish event with override source
+     *
+     * Use when you need to publish to a different source than the default.
+     *
+     * @param event - Event with source override
+     * @returns Promise with event ID
+     */
+    putEventWithSource<T extends Record<string, unknown>>(event: EventBridgeEvent<T> & {
+        source: string;
+    }): Promise<{
+        eventId?: string;
+        failedEntryCount?: number;
+    }>;
+}
+
+export { type EventBridgeEvent, type EventBridgeLambdaEvent, EventBridgePublisher, type EventBridgePublisherConfig, type TraceEventBridgeConfig, extractEventBridgeContext, injectEventBridgeContext, stripEventBridgeContext, traceEventBridge };