autotel-aws 0.2.0

package/dist/sqs.d.ts

@@ -0,0 +1,384 @@
+import { TraceContext } from 'autotel';
+
+/**
+ * SQS-specific instrumentation
+ *
+ * Provides semantic helpers for tracing SQS operations with proper OpenTelemetry
+ * messaging semantic conventions. Automatically sets `messaging.*` and `aws.sqs.*` attributes.
+ *
+ * @example Send message
+ * ```typescript
+ * import { traceSQS } from 'autotel-aws/sqs';
+ * import { SQSClient, SendMessageCommand } from '@aws-sdk/client-sqs';
+ *
+ * const sqs = new SQSClient({});
+ *
+ * export const sendMessage = traceSQS({
+ *   operation: 'send',
+ *   queueName: 'my-queue',
+ *   queueUrl: 'https://sqs.us-east-1.amazonaws.com/123456789/my-queue'
+ * })(ctx => async (body: string, attributes?: Record<string, string>) => {
+ *   const result = await sqs.send(new SendMessageCommand({
+ *     QueueUrl: 'https://sqs.us-east-1.amazonaws.com/123456789/my-queue',
+ *     MessageBody: body,
+ *     MessageAttributes: attributes
+ *   }));
+ *
+ *   if (result.MessageId) {
+ *     ctx.setAttribute('messaging.message.id', result.MessageId);
+ *   }
+ *
+ *   return result;
+ * });
+ *
+ * // Usage: await sendMessage('Hello!', { correlationId: { StringValue: '123', DataType: 'String' } });
+ * ```
+ *
+ * @example Receive and process messages
+ * ```typescript
+ * export const receiveMessages = traceSQS({
+ *   operation: 'receive',
+ *   queueName: 'my-queue'
+ * })(ctx => async (maxMessages: number) => {
+ *   const result = await sqs.send(new ReceiveMessageCommand({
+ *     QueueUrl: 'https://sqs.../my-queue',
+ *     MaxNumberOfMessages: maxMessages
+ *   }));
+ *
+ *   ctx.setAttribute('messaging.batch.message_count', result.Messages?.length ?? 0);
+ *   return result.Messages;
+ * });
+ * ```
+ */
+
+/**
+ * SQS operation configuration
+ */
+interface TraceSQSConfig {
+    /**
+     * SQS operation type
+     * - 'send' - SendMessage, SendMessageBatch
+     * - 'receive' - ReceiveMessage
+     */
+    operation: 'send' | 'receive';
+    /**
+     * Queue name (last segment of queue URL)
+     * Sets `messaging.destination.name` attribute.
+     */
+    queueName: string;
+    /**
+     * Full queue URL
+     * Sets `aws.sqs.queue_url` attribute.
+     */
+    queueUrl?: string;
+}
+/**
+ * Trace SQS operations with semantic attributes
+ *
+ * Creates a traced function that automatically sets SQS messaging semantic attributes
+ * following OpenTelemetry conventions.
+ *
+ * @param config - SQS operation configuration
+ * @returns A higher-order function that wraps your SQS operation with tracing
+ *
+ * @remarks
+ * Semantic attributes set automatically:
+ * - `messaging.system` - 'aws_sqs'
+ * - `messaging.destination.name` - Queue name
+ * - `messaging.operation` - 'send' or 'receive'
+ * - `aws.sqs.queue_url` - Full queue URL (if provided)
+ *
+ * Additional attributes you should set in your handler:
+ * - `messaging.message.id` - Message ID from response
+ * - `messaging.batch.message_count` - Number of messages in batch
+ *
+ * @see https://opentelemetry.io/docs/specs/semconv/messaging/aws-sqs/
+ */
+declare function traceSQS(config: TraceSQSConfig): <TArgs extends unknown[], TReturn>(fn: (ctx: TraceContext) => (...args: TArgs) => Promise<TReturn>) => (...args: TArgs) => Promise<TReturn>;
+/**
+ * Configuration for SQS Producer
+ */
+interface SQSProducerConfig {
+    /**
+     * Full SQS queue URL
+     */
+    queueUrl: string;
+    /**
+     * Inject W3C Trace Context into message attributes
+     * Enables distributed tracing across producer/consumer
+     * @default true
+     */
+    injectTraceContext?: boolean;
+    /**
+     * Optional service name for tracing
+     */
+    service?: string;
+}
+/**
+ * Message to send via SQS Producer
+ */
+interface SQSMessage {
+    /**
+     * Message body (string)
+     */
+    body: string;
+    /**
+     * Optional message attributes
+     */
+    attributes?: Record<string, {
+        StringValue: string;
+        DataType: string;
+    }>;
+    /**
+     * Optional message group ID (for FIFO queues)
+     */
+    messageGroupId?: string;
+    /**
+     * Optional deduplication ID (for FIFO queues)
+     */
+    messageDeduplicationId?: string;
+    /**
+     * Optional delay in seconds (0-900)
+     */
+    delaySeconds?: number;
+}
+/**
+ * SQS Producer with automatic trace context injection
+ *
+ * Wraps an SQS client to automatically:
+ * - Create spans for send operations
+ * - Inject W3C Trace Context into message attributes
+ * - Set proper semantic attributes
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { SQSProducer } from 'autotel-aws/sqs';
+ * import { SQSClient } from '@aws-sdk/client-sqs';
+ *
+ * const sqs = new SQSClient({ region: 'us-east-1' });
+ * const producer = new SQSProducer(sqs, {
+ *   queueUrl: 'https://sqs.us-east-1.amazonaws.com/123456789/my-queue'
+ * });
+ *
+ * // Send with automatic trace context
+ * const result = await producer.send({ body: 'Hello!' });
+ * console.log('Message ID:', result.messageId);
+ * ```
+ *
+ * @example With custom attributes
+ * ```typescript
+ * await producer.send({
+ *   body: JSON.stringify({ orderId: '12345' }),
+ *   attributes: {
+ *     'correlationId': { StringValue: 'abc-123', DataType: 'String' },
+ *     'eventType': { StringValue: 'ORDER_CREATED', DataType: 'String' }
+ *   }
+ * });
+ * ```
+ *
+ * @example Batch send
+ * ```typescript
+ * const results = await producer.sendBatch([
+ *   { body: 'Message 1' },
+ *   { body: 'Message 2' },
+ *   { body: 'Message 3' }
+ * ]);
+ * console.log(`Sent ${results.successful.length} messages`);
+ * ```
+ */
+declare class SQSProducer<TClient extends {
+    send: (command: any) => Promise<any>;
+} = any> {
+    private client;
+    private config;
+    private queueName;
+    constructor(client: TClient, config: SQSProducerConfig);
+    /**
+     * Inject trace context into message attributes
+     */
+    private injectContext;
+    /**
+     * Send a single message to the queue
+     *
+     * @param message - Message to send
+     * @returns Promise with message ID and other metadata
+     */
+    send(message: SQSMessage): Promise<{
+        messageId?: string;
+        sequenceNumber?: string;
+        md5OfMessageBody?: string;
+    }>;
+    /**
+     * Send multiple messages in a batch
+     *
+     * @param messages - Array of messages to send (max 10)
+     * @returns Promise with successful and failed message results
+     */
+    sendBatch(messages: SQSMessage[]): Promise<{
+        successful: Array<{
+            id: string;
+            messageId?: string;
+            sequenceNumber?: string;
+        }>;
+        failed: Array<{
+            id: string;
+            code?: string;
+            message?: string;
+        }>;
+    }>;
+}
+/**
+ * Configuration for SQS Consumer
+ */
+interface SQSConsumerConfig {
+    /**
+     * Full SQS queue URL
+     */
+    queueUrl: string;
+    /**
+     * Extract W3C Trace Context from message attributes
+     * Creates child spans linked to the producer
+     * @default true
+     */
+    extractTraceContext?: boolean;
+    /**
+     * Maximum number of messages to receive per poll
+     * @default 10
+     */
+    maxMessages?: number;
+    /**
+     * Visibility timeout in seconds
+     * @default 30
+     */
+    visibilityTimeout?: number;
+    /**
+     * Wait time for long polling in seconds (0-20)
+     * @default 20
+     */
+    waitTimeSeconds?: number;
+    /**
+     * Optional service name for tracing
+     */
+    service?: string;
+}
+/**
+ * Received SQS message with parsed attributes
+ */
+interface ReceivedSQSMessage {
+    /**
+     * Message ID
+     */
+    messageId: string;
+    /**
+     * Receipt handle for deletion
+     */
+    receiptHandle: string;
+    /**
+     * Message body (string)
+     */
+    body: string;
+    /**
+     * Parsed message attributes
+     */
+    attributes: Record<string, string>;
+    /**
+     * System attributes (ApproximateReceiveCount, etc.)
+     */
+    systemAttributes: Record<string, string>;
+    /**
+     * Original AWS SDK message object
+     */
+    raw: any;
+}
+/**
+ * Message processor function type
+ */
+type MessageProcessor = (message: ReceivedSQSMessage, ctx: TraceContext) => Promise<void>;
+/**
+ * SQS Consumer with automatic trace context extraction
+ *
+ * Wraps an SQS client to automatically:
+ * - Create spans for receive/process operations
+ * - Extract W3C Trace Context from message attributes
+ * - Link consumer spans to producer spans
+ * - Delete messages after successful processing
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { SQSConsumer } from 'autotel-aws/sqs';
+ * import { SQSClient } from '@aws-sdk/client-sqs';
+ *
+ * const sqs = new SQSClient({ region: 'us-east-1' });
+ * const consumer = new SQSConsumer(sqs, {
+ *   queueUrl: 'https://sqs.us-east-1.amazonaws.com/123456789/my-queue'
+ * });
+ *
+ * // Process messages with automatic tracing
+ * await consumer.processMessages(async (message, ctx) => {
+ *   ctx.setAttribute('order.id', JSON.parse(message.body).orderId);
+ *   await handleOrder(message.body);
+ * });
+ * ```
+ *
+ * @example With polling loop
+ * ```typescript
+ * // Start continuous polling
+ * const controller = new AbortController();
+ *
+ * consumer.poll(async (message, ctx) => {
+ *   await processMessage(message);
+ * }, { signal: controller.signal });
+ *
+ * // Stop polling gracefully
+ * controller.abort();
+ * ```
+ */
+declare class SQSConsumer<TClient extends {
+    send: (command: any) => Promise<any>;
+} = any> {
+    private client;
+    private config;
+    private queueName;
+    constructor(client: TClient, config: SQSConsumerConfig);
+    /**
+     * Extract trace context from message attributes
+     */
+    private extractContext;
+    /**
+     * Parse AWS SDK message into our format
+     */
+    private parseMessage;
+    /**
+     * Receive messages from the queue
+     *
+     * @returns Array of received messages
+     */
+    receive(): Promise<ReceivedSQSMessage[]>;
+    /**
+     * Delete a message from the queue
+     *
+     * @param receiptHandle - Receipt handle of the message to delete
+     */
+    delete(receiptHandle: string): Promise<void>;
+    /**
+     * Process messages with automatic trace context extraction
+     *
+     * Receives messages, processes each with the provided handler,
+     * and deletes successfully processed messages.
+     *
+     * @param processor - Function to process each message
+     * @returns Number of messages processed
+     */
+    processMessages(processor: MessageProcessor): Promise<number>;
+    /**
+     * Start continuous polling loop
+     *
+     * @param processor - Function to process each message
+     * @param options - Polling options including abort signal
+     */
+    poll(processor: MessageProcessor, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+
+export { type MessageProcessor, type ReceivedSQSMessage, SQSConsumer, type SQSConsumerConfig, type SQSMessage, SQSProducer, type SQSProducerConfig, type TraceSQSConfig, traceSQS };

package/dist/sqs.js

@@ -0,0 +1,6 @@
+export { SQSConsumer, SQSProducer, traceSQS } from './chunk-OHFR7WX5.js';
+import './chunk-YG56NRIO.js';
+import './chunk-I4CKQ4RD.js';
+import './chunk-DGUM43GV.js';
+//# sourceMappingURL=sqs.js.map
+//# sourceMappingURL=sqs.js.map

package/dist/sqs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"sqs.js"}

package/dist/step-functions.cjs

@@ -0,0 +1,35 @@
+'use strict';
+
+var chunkKUIOI74B_cjs = require('./chunk-KUIOI74B.cjs');
+require('./chunk-UZEJV2YD.cjs');
+require('./chunk-Q3DMMQ7K.cjs');
+require('./chunk-JEQ2X3Z6.cjs');
+
+
+
+Object.defineProperty(exports, "StepFunctionsActivityWorker", {
+  enumerable: true,
+  get: function () { return chunkKUIOI74B_cjs.StepFunctionsActivityWorker; }
+});
+Object.defineProperty(exports, "StepFunctionsExecutor", {
+  enumerable: true,
+  get: function () { return chunkKUIOI74B_cjs.StepFunctionsExecutor; }
+});
+Object.defineProperty(exports, "extractStepFunctionsContext", {
+  enumerable: true,
+  get: function () { return chunkKUIOI74B_cjs.extractStepFunctionsContext; }
+});
+Object.defineProperty(exports, "injectTraceContext", {
+  enumerable: true,
+  get: function () { return chunkKUIOI74B_cjs.injectTraceContext; }
+});
+Object.defineProperty(exports, "stripTraceContext", {
+  enumerable: true,
+  get: function () { return chunkKUIOI74B_cjs.stripTraceContext; }
+});
+Object.defineProperty(exports, "traceStepFunction", {
+  enumerable: true,
+  get: function () { return chunkKUIOI74B_cjs.traceStepFunction; }
+});
+//# sourceMappingURL=step-functions.cjs.map
+//# sourceMappingURL=step-functions.cjs.map

package/dist/step-functions.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"step-functions.cjs"}