autotel-aws 0.2.0

package/dist/sns.d.ts

@@ -0,0 +1,256 @@
+import { TraceContext } from 'autotel';
+
+/**
+ * SNS-specific instrumentation
+ *
+ * Provides semantic helpers for tracing SNS operations with proper OpenTelemetry
+ * messaging semantic conventions. Automatically sets `messaging.*` attributes.
+ *
+ * @example Publish to topic
+ * ```typescript
+ * import { traceSNS } from 'autotel-aws/sns';
+ * import { SNSClient, PublishCommand } from '@aws-sdk/client-sns';
+ *
+ * const sns = new SNSClient({});
+ *
+ * export const publishNotification = traceSNS({
+ *   topicArn: 'arn:aws:sns:us-east-1:123456789:notifications'
+ * })(ctx => async (message: string, subject?: string) => {
+ *   const result = await sns.send(new PublishCommand({
+ *     TopicArn: 'arn:aws:sns:us-east-1:123456789:notifications',
+ *     Message: message,
+ *     Subject: subject
+ *   }));
+ *
+ *   if (result.MessageId) {
+ *     ctx.setAttribute('messaging.message.id', result.MessageId);
+ *   }
+ *
+ *   return result;
+ * });
+ *
+ * // Usage: await publishNotification('User signed up', 'New User');
+ * ```
+ *
+ * @example Publish to mobile endpoint
+ * ```typescript
+ * export const sendPushNotification = traceSNS({
+ *   operation: 'publish',
+ *   topicArn: 'arn:aws:sns:us-east-1:123456789:app/APNS/my-app'
+ * })(ctx => async (endpointArn: string, payload: object) => {
+ *   ctx.setAttribute('aws.sns.target_arn', endpointArn);
+ *   return await sns.send(new PublishCommand({
+ *     TargetArn: endpointArn,
+ *     Message: JSON.stringify(payload),
+ *     MessageStructure: 'json'
+ *   }));
+ * });
+ * ```
+ */
+
+/**
+ * SNS operation configuration
+ */
+interface TraceSNSConfig {
+    /**
+     * SNS topic ARN
+     * Sets `messaging.destination.name` attribute.
+     */
+    topicArn: string;
+    /**
+     * Operation type (defaults to 'publish')
+     */
+    operation?: 'publish' | 'subscribe' | 'unsubscribe';
+}
+/**
+ * Trace SNS operations with semantic attributes
+ *
+ * Creates a traced function that automatically sets SNS messaging semantic attributes
+ * following OpenTelemetry conventions.
+ *
+ * @param config - SNS operation configuration
+ * @returns A higher-order function that wraps your SNS operation with tracing
+ *
+ * @remarks
+ * Semantic attributes set automatically:
+ * - `messaging.system` - 'aws_sns'
+ * - `messaging.destination.name` - Topic ARN
+ * - `messaging.operation` - 'publish'
+ *
+ * Additional attributes you should set in your handler:
+ * - `messaging.message.id` - Message ID from response
+ * - `aws.sns.target_arn` - Target ARN for direct publishing
+ *
+ * @see https://opentelemetry.io/docs/specs/semconv/messaging/aws-sns/
+ */
+declare function traceSNS(config: TraceSNSConfig): <TArgs extends unknown[], TReturn>(fn: (ctx: TraceContext) => (...args: TArgs) => Promise<TReturn>) => (...args: TArgs) => Promise<TReturn>;
+/**
+ * Configuration for SNS Publisher
+ */
+interface SNSPublisherConfig {
+    /**
+     * SNS Topic ARN
+     */
+    topicArn: string;
+    /**
+     * Inject W3C Trace Context into message attributes
+     * Enables distributed tracing to SNS subscribers (e.g., Lambda, SQS)
+     * @default true
+     */
+    injectTraceContext?: boolean;
+    /**
+     * Optional service name for tracing
+     */
+    service?: string;
+}
+/**
+ * Message to publish via SNS Publisher
+ */
+interface SNSPublishMessage {
+    /**
+     * Message body (string or JSON for message structure)
+     */
+    message: string;
+    /**
+     * Optional subject (for email/SMS subscriptions)
+     */
+    subject?: string;
+    /**
+     * Optional message attributes
+     */
+    attributes?: Record<string, {
+        StringValue: string;
+        DataType: string;
+    }>;
+    /**
+     * Optional target ARN for direct endpoint publishing
+     */
+    targetArn?: string;
+    /**
+     * Optional phone number for SMS
+     */
+    phoneNumber?: string;
+    /**
+     * Optional message structure ('json' for platform-specific messages)
+     */
+    messageStructure?: 'json';
+    /**
+     * Optional message group ID (for FIFO topics)
+     */
+    messageGroupId?: string;
+    /**
+     * Optional deduplication ID (for FIFO topics)
+     */
+    messageDeduplicationId?: string;
+}
+/**
+ * SNS Publisher with automatic trace context injection
+ *
+ * Wraps an SNS client to automatically:
+ * - Create spans for publish operations
+ * - Inject W3C Trace Context into message attributes
+ * - Set proper semantic attributes
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { SNSPublisher } from 'autotel-aws/sns';
+ * import { SNSClient } from '@aws-sdk/client-sns';
+ *
+ * const sns = new SNSClient({ region: 'us-east-1' });
+ * const publisher = new SNSPublisher(sns, {
+ *   topicArn: 'arn:aws:sns:us-east-1:123456789:my-topic'
+ * });
+ *
+ * // Publish with automatic trace context
+ * const result = await publisher.publish({
+ *   message: 'Order completed',
+ *   subject: 'Order #12345'
+ * });
+ * console.log('Message ID:', result.messageId);
+ * ```
+ *
+ * @example With custom attributes
+ * ```typescript
+ * await publisher.publish({
+ *   message: JSON.stringify({ orderId: '12345', status: 'completed' }),
+ *   attributes: {
+ *     'eventType': { StringValue: 'ORDER_COMPLETED', DataType: 'String' },
+ *     'priority': { StringValue: 'high', DataType: 'String' }
+ *   }
+ * });
+ * ```
+ *
+ * @example Batch publish
+ * ```typescript
+ * const results = await publisher.publishBatch([
+ *   { message: 'Event 1' },
+ *   { message: 'Event 2' },
+ *   { message: 'Event 3' }
+ * ]);
+ * console.log(`Published ${results.successful.length} messages`);
+ * ```
+ *
+ * @example Direct endpoint publish
+ * ```typescript
+ * await publisher.publishToEndpoint({
+ *   targetArn: 'arn:aws:sns:us-east-1:123456789:endpoint/APNS/my-app/device-token',
+ *   message: JSON.stringify({
+ *     APNS: JSON.stringify({ aps: { alert: 'Hello!' } })
+ *   }),
+ *   messageStructure: 'json'
+ * });
+ * ```
+ */
+declare class SNSPublisher<TClient extends {
+    send: (command: any) => Promise<any>;
+} = any> {
+    private client;
+    private config;
+    private topicName;
+    constructor(client: TClient, config: SNSPublisherConfig);
+    /**
+     * Inject trace context into message attributes
+     */
+    private injectContext;
+    /**
+     * Publish a message to the topic
+     *
+     * @param message - Message to publish
+     * @returns Promise with message ID and sequence number
+     */
+    publish(message: SNSPublishMessage): Promise<{
+        messageId?: string;
+        sequenceNumber?: string;
+    }>;
+    /**
+     * Publish multiple messages in a batch
+     *
+     * @param messages - Array of messages to publish (max 10)
+     * @returns Promise with successful and failed message results
+     */
+    publishBatch(messages: SNSPublishMessage[]): Promise<{
+        successful: Array<{
+            id: string;
+            messageId?: string;
+            sequenceNumber?: string;
+        }>;
+        failed: Array<{
+            id: string;
+            code?: string;
+            message?: string;
+        }>;
+    }>;
+    /**
+     * Publish to a specific endpoint (mobile push, etc.)
+     *
+     * @param message - Message with targetArn set
+     * @returns Promise with message ID
+     */
+    publishToEndpoint(message: Omit<SNSPublishMessage, 'targetArn'> & {
+        targetArn: string;
+    }): Promise<{
+        messageId?: string;
+    }>;
+}
+
+export { type SNSPublishMessage, SNSPublisher, type SNSPublisherConfig, type TraceSNSConfig, traceSNS };

package/dist/sns.js

@@ -0,0 +1,6 @@
+export { SNSPublisher, traceSNS } from './chunk-CIGXV6HA.js';
+import './chunk-YG56NRIO.js';
+import './chunk-I4CKQ4RD.js';
+import './chunk-DGUM43GV.js';
+//# sourceMappingURL=sns.js.map
+//# sourceMappingURL=sns.js.map

package/dist/sns.js.map

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

package/dist/sqs.cjs

@@ -0,0 +1,23 @@
+'use strict';
+
+var chunkOB4XTAVK_cjs = require('./chunk-OB4XTAVK.cjs');
+require('./chunk-UZEJV2YD.cjs');
+require('./chunk-Q3DMMQ7K.cjs');
+require('./chunk-JEQ2X3Z6.cjs');
+
+
+
+Object.defineProperty(exports, "SQSConsumer", {
+  enumerable: true,
+  get: function () { return chunkOB4XTAVK_cjs.SQSConsumer; }
+});
+Object.defineProperty(exports, "SQSProducer", {
+  enumerable: true,
+  get: function () { return chunkOB4XTAVK_cjs.SQSProducer; }
+});
+Object.defineProperty(exports, "traceSQS", {
+  enumerable: true,
+  get: function () { return chunkOB4XTAVK_cjs.traceSQS; }
+});
+//# sourceMappingURL=sqs.cjs.map
+//# sourceMappingURL=sqs.cjs.map

package/dist/sqs.cjs.map

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

package/dist/sqs.d.cts

@@ -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 };