@geekmidas/events 0.0.1

package/src/sqs/SQSSubscriber.ts

@@ -0,0 +1,189 @@
+import {
+  DeleteMessageCommand,
+  type Message,
+  ReceiveMessageCommand,
+} from '@aws-sdk/client-sqs';
+import type { EventSubscriber, PublishableMessage } from '../types';
+import type { SQSConnection } from './SQSConnection';
+
+export interface SQSSubscriberOptions {
+  waitTimeSeconds?: number; // SQS long polling (default: 20)
+  maxMessages?: number; // Max messages per poll (default: 10)
+  expectedTopicArn?: string; // Optional: verify messages are from specific SNS topic
+}
+
+/**
+ * SQS Subscriber - receives messages from an SQS queue
+ *
+ * This subscriber can receive:
+ * 1. Direct SQS messages
+ * 2. SNS messages that were pushed to the queue (SNS → SQS pattern)
+ *
+ * When receiving SNS messages, it:
+ * - Automatically detects and parses the SNS wrapper format
+ * - Filters by TopicArn (if expectedTopicArn is provided)
+ * - Filters by message type
+ * - Processes the actual message payload
+ */
+export class SQSSubscriber<TMessage extends PublishableMessage<string, any>>
+  implements EventSubscriber<TMessage>
+{
+  private polling = false;
+  private messageTypes: Set<TMessage['type']> = new Set();
+  private listener?: (payload: TMessage) => Promise<void>;
+  private options: Required<SQSSubscriberOptions>;
+
+  constructor(
+    private connection: SQSConnection,
+    options: SQSSubscriberOptions = {},
+  ) {
+    this.options = {
+      waitTimeSeconds: options.waitTimeSeconds ?? 20,
+      maxMessages: options.maxMessages ?? 10,
+      expectedTopicArn: options.expectedTopicArn ?? '',
+    };
+  }
+
+  async subscribe(
+    messages: TMessage['type'][],
+    listener: (payload: TMessage) => Promise<void>,
+  ): Promise<void> {
+    this.messageTypes = new Set(messages);
+    this.listener = listener;
+
+    if (!this.connection.isConnected()) {
+      await this.connection.connect();
+    }
+
+    this.polling = true;
+    this.poll();
+  }
+
+  stop(): void {
+    this.polling = false;
+  }
+
+  private async poll(): Promise<void> {
+    while (this.polling) {
+      try {
+        const command = new ReceiveMessageCommand({
+          QueueUrl: this.connection.queueUrl,
+          MaxNumberOfMessages: this.options.maxMessages,
+          WaitTimeSeconds: this.options.waitTimeSeconds,
+          MessageAttributeNames: ['All'],
+        });
+
+        const response = await this.connection.sqsClient.send(command);
+
+        if (response.Messages && response.Messages.length > 0) {
+          await this.processMessages(response.Messages);
+        }
+      } catch (error) {
+        console.error('Error receiving messages from SQS:', error);
+        await this.sleep(1000);
+      }
+    }
+  }
+
+  private async processMessages(messages: Message[]): Promise<void> {
+    for (const message of messages) {
+      try {
+        if (!message.Body) continue;
+
+        // Try to parse as SNS message first
+        const parsedMessage = this.parseMessage(message.Body);
+
+        if (!parsedMessage) {
+          // Not a valid message format
+          await this.deleteMessage(message.ReceiptHandle!);
+          continue;
+        }
+
+        const { payload, messageType, topicArn } = parsedMessage;
+
+        // If expectedTopicArn is set, verify the message is from that topic
+        if (this.options.expectedTopicArn && topicArn) {
+          if (topicArn !== this.options.expectedTopicArn) {
+            console.warn(
+              `Received message from unexpected topic: ${topicArn}, expected: ${this.options.expectedTopicArn}`,
+            );
+            await this.deleteMessage(message.ReceiptHandle!);
+            continue;
+          }
+        }
+
+        // Check if we're subscribed to this message type
+        if (
+          messageType &&
+          this.messageTypes.has(messageType as TMessage['type'])
+        ) {
+          // Call listener
+          if (this.listener) {
+            await this.listener(payload as TMessage);
+          }
+
+          // Delete message after successful processing
+          await this.deleteMessage(message.ReceiptHandle!);
+        } else {
+          // Delete messages we're not subscribed to
+          await this.deleteMessage(message.ReceiptHandle!);
+        }
+      } catch (error) {
+        console.error('Error processing message:', error);
+        // Message will become visible again
+      }
+    }
+  }
+
+  /**
+   * Parse message body - handles both direct SQS messages and SNS-wrapped messages
+   */
+  private parseMessage(body: string): {
+    payload: unknown;
+    messageType: string | undefined;
+    topicArn?: string;
+  } | null {
+    try {
+      const parsed = JSON.parse(body);
+
+      // Check if this is an SNS notification wrapper
+      if (parsed.Type === 'Notification' && parsed.Message) {
+        // This is an SNS message
+        const snsMessage = JSON.parse(parsed.Message);
+        const messageType =
+          parsed.MessageAttributes?.type?.Value || snsMessage.type;
+
+        return {
+          payload: snsMessage,
+          messageType,
+          topicArn: parsed.TopicArn,
+        };
+      }
+
+      // This is a direct SQS message
+      return {
+        payload: parsed,
+        messageType: parsed.type,
+      };
+    } catch (error) {
+      console.error('Failed to parse message:', error);
+      return null;
+    }
+  }
+
+  private async deleteMessage(receiptHandle: string): Promise<void> {
+    try {
+      const command = new DeleteMessageCommand({
+        QueueUrl: this.connection.queueUrl,
+        ReceiptHandle: receiptHandle,
+      });
+      await this.connection.sqsClient.send(command);
+    } catch (error) {
+      console.error('Error deleting message:', error);
+    }
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

package/src/sqs/__tests__/SQSPublisher.spec.ts

@@ -0,0 +1,189 @@
+import { describe, expect, it } from 'vitest';
+import type { PublishableMessage } from '../../types';
+import { SQSConnection } from '../SQSConnection';
+import { SQSPublisher } from '../SQSPublisher';
+
+type TestMessage = PublishableMessage<'user.created' | 'user.updated', any>;
+
+const TEST_QUEUE_URL =
+  'https://sqs.us-east-1.amazonaws.com/123456789012/test-queue';
+
+describe('SQSPublisher', () => {
+  describe('constructor', () => {
+    it('should create instance with queue URL', () => {
+      const connection = new SQSConnection({
+        queueUrl: TEST_QUEUE_URL,
+      });
+      const publisher = new SQSPublisher<TestMessage>(connection);
+
+      expect(publisher).toBeDefined();
+    });
+
+    it('should create instance with region', () => {
+      const connection = new SQSConnection({
+        queueUrl: TEST_QUEUE_URL,
+        region: 'us-east-1',
+      });
+      const publisher = new SQSPublisher<TestMessage>(connection);
+
+      expect(publisher).toBeDefined();
+    });
+
+    it('should create instance with credentials', () => {
+      const connection = new SQSConnection({
+        queueUrl: TEST_QUEUE_URL,
+        region: 'us-east-1',
+        credentials: {
+          accessKeyId: 'test-key',
+          secretAccessKey: 'test-secret',
+        },
+      });
+      const publisher = new SQSPublisher<TestMessage>(connection);
+
+      expect(publisher).toBeDefined();
+    });
+
+    it('should create instance with custom batch size', () => {
+      const connection = new SQSConnection({
+        queueUrl: TEST_QUEUE_URL,
+      });
+      const publisher = new SQSPublisher<TestMessage>(connection, {
+        maxBatchSize: 5,
+      });
+
+      expect(publisher).toBeDefined();
+    });
+
+    it('should create instance with custom endpoint', () => {
+      const connection = new SQSConnection({
+        queueUrl: TEST_QUEUE_URL,
+        endpoint: 'http://localhost:4566',
+      });
+      const publisher = new SQSPublisher<TestMessage>(connection);
+
+      expect(publisher).toBeDefined();
+    });
+
+    it('should default maxBatchSize to 10', () => {
+      const connection = new SQSConnection({
+        queueUrl: TEST_QUEUE_URL,
+      });
+      const publisher = new SQSPublisher<TestMessage>(connection);
+
+      // Access private options through any to test default
+      expect(publisher.options.maxBatchSize).toBe(10);
+    });
+  });
+
+  describe('fromConnectionString', () => {
+    it('should parse basic connection string', async () => {
+      const publisher = await SQSPublisher.fromConnectionString<TestMessage>(
+        `sqs://?queueUrl=${encodeURIComponent(TEST_QUEUE_URL)}`,
+      );
+
+      expect(publisher).toBeDefined();
+    });
+
+    it('should parse connection string with region', async () => {
+      const publisher = await SQSPublisher.fromConnectionString<TestMessage>(
+        `sqs://?queueUrl=${encodeURIComponent(TEST_QUEUE_URL)}&region=us-west-2`,
+      );
+
+      expect(publisher).toBeDefined();
+      expect(publisher.connection.config.region).toBe('us-west-2');
+    });
+
+    it('should parse connection string with credentials', async () => {
+      const publisher = await SQSPublisher.fromConnectionString<TestMessage>(
+        `sqs://?queueUrl=${encodeURIComponent(TEST_QUEUE_URL)}&accessKeyId=test-key&secretAccessKey=test-secret`,
+      );
+
+      expect(publisher).toBeDefined();
+      expect(publisher.connection.config.credentials).toEqual({
+        accessKeyId: 'test-key',
+        secretAccessKey: 'test-secret',
+        sessionToken: undefined,
+      });
+    });
+
+    it('should parse connection string with session token', async () => {
+      const publisher = await SQSPublisher.fromConnectionString<TestMessage>(
+        `sqs://?queueUrl=${encodeURIComponent(TEST_QUEUE_URL)}&accessKeyId=test-key&secretAccessKey=test-secret&sessionToken=test-token`,
+      );
+
+      expect(publisher).toBeDefined();
+      expect(publisher.connection.config.credentials).toEqual({
+        accessKeyId: 'test-key',
+        secretAccessKey: 'test-secret',
+        sessionToken: 'test-token',
+      });
+    });
+
+    it('should parse connection string with maxBatchSize', async () => {
+      const publisher = await SQSPublisher.fromConnectionString<TestMessage>(
+        `sqs://?queueUrl=${encodeURIComponent(TEST_QUEUE_URL)}&maxBatchSize=5`,
+      );
+
+      expect(publisher).toBeDefined();
+      expect(publisher.options.maxBatchSize).toBe(5);
+    });
+
+    it('should parse connection string with endpoint', async () => {
+      const publisher = await SQSPublisher.fromConnectionString<TestMessage>(
+        `sqs://?queueUrl=${encodeURIComponent(TEST_QUEUE_URL)}&endpoint=${encodeURIComponent('http://localhost:4566')}`,
+      );
+
+      expect(publisher).toBeDefined();
+      expect(publisher.connection.config.endpoint).toBe(
+        'http://localhost:4566',
+      );
+    });
+
+    it('should parse connection string with all parameters', async () => {
+      const publisher = await SQSPublisher.fromConnectionString<TestMessage>(
+        `sqs://?queueUrl=${encodeURIComponent(TEST_QUEUE_URL)}&region=us-west-2&endpoint=${encodeURIComponent('http://localhost:4566')}&maxBatchSize=5&accessKeyId=test&secretAccessKey=secret`,
+      );
+
+      expect(publisher).toBeDefined();
+      expect(publisher.connection.config.region).toBe('us-west-2');
+      expect(publisher.connection.config.endpoint).toBe(
+        'http://localhost:4566',
+      );
+      expect(publisher.options.maxBatchSize).toBe(5);
+      expect(publisher.connection.config.credentials).toEqual({
+        accessKeyId: 'test',
+        secretAccessKey: 'secret',
+        sessionToken: undefined,
+      });
+    });
+
+    it('should throw error if queueUrl is missing', async () => {
+      await expect(
+        SQSPublisher.fromConnectionString<TestMessage>(
+          'sqs://?region=us-east-1',
+        ),
+      ).rejects.toThrow('queueUrl parameter is required');
+    });
+  });
+
+  describe('close', () => {
+    it('should close without error', async () => {
+      const connection = new SQSConnection({
+        queueUrl: TEST_QUEUE_URL,
+      });
+      const publisher = new SQSPublisher<TestMessage>(connection);
+
+      await expect(publisher.close()).resolves.toBeUndefined();
+    });
+
+    it('should allow multiple close calls', async () => {
+      const connection = new SQSConnection({
+        queueUrl: TEST_QUEUE_URL,
+      });
+      const publisher = new SQSPublisher<TestMessage>(connection);
+
+      await publisher.close();
+      await expect(publisher.close()).resolves.toBeUndefined();
+    });
+  });
+});

package/src/sqs/index.ts

@@ -0,0 +1,6 @@
+export { SQSConnection } from './SQSConnection';
+export type { SQSConnectionConfig } from './SQSConnection';
+export { SQSPublisher } from './SQSPublisher';
+export type { SQSPublisherOptions } from './SQSPublisher';
+export { SQSSubscriber } from './SQSSubscriber';
+export type { SQSSubscriberOptions } from './SQSSubscriber';

package/src/types.ts

@@ -0,0 +1,76 @@
+import type { InferStandardSchema } from '@geekmidas/schema';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+
+/**
+ * Represents a publishable event message with a type and payload.
+ *
+ * @template TType - The event type/name (e.g., 'user.created')
+ * @template TPayload - The event payload data
+ */
+export type PublishableMessage<TType extends string, TPayload> = {
+  type: TType;
+  payload: TPayload;
+};
+
+/**
+ * Event publisher/subscriber types
+ */
+export enum EventPublisherType {
+  Basic = 'basic',
+  EventBridge = 'eventbridge',
+  SQS = 'sqs',
+  SNS = 'sns',
+  Kafka = 'kafka',
+  RabbitMQ = 'rabbitmq',
+}
+
+/**
+ * Base interface for event connections
+ * Connections manage the underlying transport (RabbitMQ channel, SQS client, etc.)
+ */
+export interface EventConnection {
+  readonly type: EventPublisherType;
+  connect(): Promise<void>;
+  close(): Promise<void>;
+  isConnected(): boolean;
+}
+
+/**
+ * Interface for event publishers that handle the actual publishing of events.
+ * Implementations can send to EventBridge, SQS, Kafka, or any other event system.
+ *
+ * @template TMessage - The union type of all publishable messages
+ */
+export type EventPublisher<TMessage extends PublishableMessage<string, any>> = {
+  publish: (message: TMessage[]) => Promise<void>;
+};
+
+/**
+ * Interface for event subscribers that handle receiving and processing events.
+ *
+ * @template TMessage - The union type of all publishable messages
+ */
+export type EventSubscriber<TMessage extends PublishableMessage<string, any>> =
+  {
+    subscribe: (
+      messages: TMessage['type'][],
+      listener: (payload: TMessage) => Promise<void>,
+    ) => Promise<void>;
+  };
+/**
+ * Utility type to extract the message from EventPublisher
+ */
+export type ExtractPublisherMessage<T> = T extends EventPublisher<infer M>
+  ? M
+  : never;
+
+export type MappedEvent<
+  T extends EventPublisher<any> | undefined,
+  OutSchema extends StandardSchemaV1 | undefined = undefined,
+> = {
+  type: ExtractPublisherMessage<T>['type'];
+  payload: (
+    ctx: InferStandardSchema<OutSchema>,
+  ) => ExtractPublisherMessage<T>['payload'];
+  when?: (ctx: InferStandardSchema<OutSchema>) => boolean;
+};

package/tsdown.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  external: ['amqplib', '@aws-sdk/client-sqs', '@aws-sdk/client-sns'],
+});