@onivoro/server-aws-kinesis 24.39.0 → 25.0.2

package/README.md

@@ -1,277 +1,119 @@
 # @onivoro/server-aws-kinesis
 
-AWS Kinesis Data Streams integration for NestJS applications.
+AWS Kinesis Data Streams integration for NestJS applications: publish JSON records to a stream.
 
 ## Installation
 
 ```bash
-npm install @onivoro/server-aws-kinesis
+npm install @onivoro/server-aws-kinesis @aws-sdk/client-kinesis @nestjs/common
 ```
 
-## Overview
-
-This library provides a simple AWS Kinesis Data Streams integration for NestJS applications, allowing you to publish data to Kinesis streams.
+`@aws-sdk/client-kinesis` and `@nestjs/common` are peer dependencies.
 
 ## Module Setup
 
+`ServerAwsKinesisModule.configure(config)` takes the configuration object directly; the module does not read environment variables itself.
+
 ```typescript
 import { Module } from '@nestjs/common';
 import { ServerAwsKinesisModule } from '@onivoro/server-aws-kinesis';
 
 @Module({
   imports: [
-    ServerAwsKinesisModule.configure()
-  ]
+    ServerAwsKinesisModule.configure({
+      AWS_REGION: process.env.AWS_REGION!,
+      AWS_KINESIS_NAME: process.env.AWS_KINESIS_NAME!,
+      AWS_PROFILE: process.env.AWS_PROFILE, // optional
+    }),
+  ],
 })
 export class AppModule {}
 ```
 
-## Configuration
+The module is not global. It provides and exports `KinesisService`, `ServerAwsKinesisConfig`, a `KinesisClient` instance, and the `AwsCredentials` provider from `@onivoro/server-aws-credential-providers`.
 
-The module uses environment-based configuration:
+## Configuration
 
 ```typescript
 export class ServerAwsKinesisConfig {
+  AWS_KINESIS_NAME: string; // stream that publish writes to
+  AWS_PROFILE?: string; // optional named profile from ~/.aws
   AWS_REGION: string;
-  AWS_PROFILE?: string;  // Optional AWS profile
 }
 ```
 
-## Service
-
-### KinesisService
-
-The main service for publishing data to Kinesis streams:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { KinesisService } from '@onivoro/server-aws-kinesis';
-
-@Injectable()
-export class EventPublisherService {
-  constructor(private readonly kinesisService: KinesisService) {}
+### AWS Credentials
 
-  async publishEvent(streamName: string, eventData: any) {
-    const result = await this.kinesisService.publish({
-      streamName,
-      data: eventData,
-      partitionKey: eventData.id || 'default'
-    });
-    
-    return result;
-  }
+Credentials are resolved by [`@onivoro/server-aws-credential-providers`](../aws-credential-providers/):
 
-  async publishUserActivity(userId: string, activity: any) {
-    const streamName = 'user-activity-stream';
-    const data = {
-      userId,
-      activity,
-      timestamp: new Date().toISOString()
-    };
-    
-    return await this.kinesisService.publish({
-      streamName,
-      data,
-      partitionKey: userId  // Use userId as partition key for ordering
-    });
-  }
-}
-```
+- If `AWS_PROFILE` is set, credentials are loaded from that profile in the shared credentials file. If that fails, `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` (or their lowercase forms) from the environment are used.
+- If `AWS_PROFILE` is not set, the client uses the AWS SDK's default credential provider chain.
 
-## Method Details
+## KinesisService
 
-### publish(params)
+### `publish<TData>(event: TData, PartitionKey: string): Promise<void>`
 
-The `publish` method accepts an object with the following properties:
+Sends a `PutRecordCommand` to the `AWS_KINESIS_NAME` stream with `Data` set to `JSON.stringify(event)` and the given partition key. The stream name always comes from config.
 
-- **streamName** (string, required): The name of the Kinesis stream
-- **data** (any, required): The data to publish (will be JSON stringified)
-- **partitionKey** (string, required): Used to determine which shard to send the record to
-
-## Direct Client Access
-
-The service exposes the underlying Kinesis client for advanced operations:
+Errors are caught and logged with `console.error`; `publish` never rejects and does not return the `PutRecord` response (shard ID / sequence number).
 
 ```typescript
-import { 
-  DescribeStreamCommand,
-  ListStreamsCommand,
-  GetRecordsCommand,
-  GetShardIteratorCommand,
-  CreateStreamCommand
-} from '@aws-sdk/client-kinesis';
-
-@Injectable()
-export class AdvancedKinesisService {
-  constructor(private readonly kinesisService: KinesisService) {}
-
-  // List all Kinesis streams
-  async listStreams() {
-    const command = new ListStreamsCommand({});
-    return await this.kinesisService.kinesisClient.send(command);
-  }
-
-  // Describe stream details
-  async describeStream(streamName: string) {
-    const command = new DescribeStreamCommand({
-      StreamName: streamName
-    });
-    return await this.kinesisService.kinesisClient.send(command);
-  }
+import { Injectable } from '@nestjs/common';
+import { KinesisService } from '@onivoro/server-aws-kinesis';
 
-  // Create a new stream
-  async createStream(streamName: string, shardCount: number = 1) {
-    const command = new CreateStreamCommand({
-      StreamName: streamName,
-      ShardCount: shardCount
-    });
-    return await this.kinesisService.kinesisClient.send(command);
-  }
+interface OrderEvent {
+  orderId: string;
+  type: 'ORDER_CREATED' | 'ORDER_SHIPPED';
+  timestamp: string;
 }
-```
-
-## Complete Example
-
-```typescript
-import { Module, Injectable } from '@nestjs/common';
-import { ServerAwsKinesisModule, KinesisService } from '@onivoro/server-aws-kinesis';
-
-@Module({
-  imports: [ServerAwsKinesisModule.configure()],
-  providers: [OrderEventService],
-  exports: [OrderEventService]
-})
-export class OrderModule {}
 
 @Injectable()
-export class OrderEventService {
+export class OrderEventPublisher {
   constructor(private readonly kinesisService: KinesisService) {}
 
-  async publishOrderEvent(orderId: string, eventType: string, eventData: any) {
-    const streamName = 'order-events-stream';
-    
-    const event = {
-      orderId,
-      eventType,
-      eventData,
-      timestamp: new Date().toISOString(),
-      version: '1.0'
-    };
-
-    try {
-      const result = await this.kinesisService.publish({
-        streamName,
-        data: event,
-        partitionKey: orderId
-      });
-
-      console.log(`Published ${eventType} event for order ${orderId}:`, {
-        shardId: result.ShardId,
-        sequenceNumber: result.SequenceNumber
-      });
-
-      return result;
-    } catch (error) {
-      console.error(`Failed to publish event for order ${orderId}:`, error);
-      throw error;
-    }
-  }
-
-  // Publish different order events
-  async orderCreated(order: any) {
-    return this.publishOrderEvent(order.id, 'ORDER_CREATED', order);
-  }
-
-  async orderUpdated(orderId: string, updates: any) {
-    return this.publishOrderEvent(orderId, 'ORDER_UPDATED', updates);
-  }
-
-  async orderShipped(orderId: string, trackingInfo: any) {
-    return this.publishOrderEvent(orderId, 'ORDER_SHIPPED', trackingInfo);
-  }
-
-  async orderDelivered(orderId: string, deliveryInfo: any) {
-    return this.publishOrderEvent(orderId, 'ORDER_DELIVERED', deliveryInfo);
+  async orderCreated(orderId: string) {
+    // Using orderId as the partition key keeps an order's events on one shard, in order.
+    await this.kinesisService.publish<OrderEvent>({ orderId, type: 'ORDER_CREATED', timestamp: new Date().toISOString() }, orderId);
   }
 }
 ```
 
-## Batch Publishing Example
+## Direct Client Access
 
-For better performance with multiple records:
+The service keeps its client private, but the module exports the `KinesisClient` provider. Inject it for anything `publish` doesn't cover, such as batching or when you need errors to propagate:
 
 ```typescript
-@Injectable()
-export class BatchEventService {
-  constructor(private readonly kinesisService: KinesisService) {}
-
-  async publishBatch(streamName: string, events: any[]) {
-    // Use the exposed client for batch operations
-    const records = events.map(event => ({
-      Data: Buffer.from(JSON.stringify(event.data)),
-      PartitionKey: event.partitionKey
-    }));
-
-    const command = new PutRecordsCommand({
-      StreamName: streamName,
-      Records: records
-    });
-
-    return await this.kinesisService.kinesisClient.send(command);
-  }
-}
-```
-
-## Environment Variables
-
-```bash
-# Required: AWS region
-AWS_REGION=us-east-1
-
-# Optional: AWS profile
-AWS_PROFILE=my-profile
-```
-
-## AWS Credentials
-
-The module uses the standard AWS SDK credential chain:
-1. Environment variables
-2. Shared credentials file
-3. IAM roles (for EC2/ECS/Lambda)
-
-## Error Handling
+import { Injectable } from '@nestjs/common';
+import { KinesisClient, PutRecordsCommand } from '@aws-sdk/client-kinesis';
+import { ServerAwsKinesisConfig } from '@onivoro/server-aws-kinesis';
 
-```typescript
-try {
-  await kinesisService.publish({
-    streamName: 'my-stream',
-    data: eventData,
-    partitionKey: 'key'
-  });
-} catch (error) {
-  if (error.name === 'ResourceNotFoundException') {
-    console.error('Kinesis stream does not exist');
-  } else if (error.name === 'ProvisionedThroughputExceededException') {
-    console.error('Rate limit exceeded, implement retry logic');
+@Injectable()
+export class BatchEventPublisher {
+  constructor(
+    private readonly kinesis: KinesisClient,
+    private readonly config: ServerAwsKinesisConfig,
+  ) {}
+
+  publishBatch(events: { partitionKey: string; data: unknown }[]) {
+    return this.kinesis.send(
+      new PutRecordsCommand({
+        StreamName: this.config.AWS_KINESIS_NAME,
+        Records: events.map((e) => ({
+          Data: Buffer.from(JSON.stringify(e.data)),
+          PartitionKey: e.partitionKey,
+        })),
+      }),
+    );
   }
 }
 ```
 
-## Limitations
-
-- This library only provides a single `publish` method
-- No built-in support for batch publishing or consumer operations
-- For advanced Kinesis operations, use the exposed `kinesisClient` directly
-- No automatic retry logic for throughput exceptions
-
-## Best Practices
+## Exports
 
-1. **Partition Key Selection**: Choose partition keys that evenly distribute data across shards
-2. **Data Size**: Keep record size under 1 MB (Kinesis limit)
-3. **Error Handling**: Implement retry logic for transient errors
-4. **Monitoring**: Use CloudWatch metrics to monitor stream performance
-5. **Scaling**: Monitor shard metrics and scale as needed
+- `ServerAwsKinesisModule` - dynamic module with `configure(config)`
+- `ServerAwsKinesisConfig` - configuration class (also injectable)
+- `KinesisService` - `publish(event, partitionKey)`
 
 ## License
 
-MIT
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onivoro/server-aws-kinesis",
-  "version": "24.39.0",
+  "version": "25.0.2",
   "license": "MIT",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -10,8 +10,8 @@
     "url": "https://github.com/onivoro/monorepo.git"
   },
   "dependencies": {
-    "@onivoro/server-aws-credential-providers": "24.39.0",
-    "@onivoro/server-common": "24.39.0",
+    "@onivoro/server-aws-credential-providers": "25.0.2",
+    "@onivoro/server-common": "25.0.2",
     "tslib": "^2.3.0"
   },
   "peerDependencies": {