@leanstacks/lambda-utils 0.3.0 → 0.4.0

package/README.md

@@ -94,7 +94,7 @@ export const handler = async (event: APIGatewayProxyEvent) => {
 - **📝 Structured Logging** – Pino logger pre-configured for Lambda with automatic AWS request context enrichment
 - **📤 API Response Helpers** – Standard response formatting for API Gateway with proper HTTP status codes
 - **⚙️ Configuration Validation** – Environment variable validation with Zod schema support
-- **🔌 AWS SDK Clients** – Pre-configured AWS SDK v3 clients including DynamoDB with document client support
+- **🔌 AWS SDK Clients** – Pre-configured AWS SDK v3 clients including DynamoDB, Lambda, SNS, and SQS with singleton patterns
 - **🔒 Full TypeScript Support** – Complete type definitions and IDE autocomplete
 - **⚡ Lambda Optimized** – Designed for performance in serverless environments
 
@@ -107,7 +107,10 @@ Comprehensive guides and examples are available in the `docs` directory:
 | **[Configuration Guide](./docs/CONFIGURATION.md)**           | Validate environment variables with Zod schemas and type safety        |
 | **[Logging Guide](./docs/LOGGING.md)**                       | Configure and use structured logging with automatic AWS Lambda context |
 | **[API Gateway Responses](./docs/API_GATEWAY_RESPONSES.md)** | Format responses for API Gateway with standard HTTP patterns           |
-| **[DynamoDB Client](./docs/DYNAMODB_CLIENT.md)**             | Use pre-configured AWS SDK v3 clients in your handlers                 |
+| **[DynamoDB Client](./docs/DYNAMODB_CLIENT.md)**             | Use pre-configured DynamoDB clients with singleton pattern             |
+| **[Lambda Client](./docs/LAMBDA_CLIENT.md)**                 | Invoke other Lambda functions synchronously or asynchronously          |
+| **[SNS Client](./docs/SNS_CLIENT.md)**                       | Publish messages to SNS topics with message attributes                 |
+| **[SQS Client](./docs/SQS_CLIENT.md)**                       | Send messages to SQS queues with message attributes                    |
 
 ## Usage
 
@@ -195,11 +198,89 @@ export const handler = async (event: any, context: any) => {
 
 **→ See [DynamoDB Client Guide](./docs/DYNAMODB_CLIENT.md) for detailed configuration and examples**
 
-Additional AWS Clients are coming soon.
+#### Lambda Client
+
+Invoke other Lambda functions synchronously or asynchronously:
+
+```typescript
+import { invokeLambdaSync, invokeLambdaAsync } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  // Synchronous invocation - wait for response
+  const response = await invokeLambdaSync('my-function-name', {
+    key: 'value',
+    data: { nested: true },
+  });
+
+  // Asynchronous invocation - fire and forget
+  await invokeLambdaAsync('my-async-function', {
+    eventType: 'process',
+    data: [1, 2, 3],
+  });
+
+  return { statusCode: 200, body: JSON.stringify(response) };
+};
+```
+
+**→ See [Lambda Client Guide](./docs/LAMBDA_CLIENT.md) for detailed configuration and examples**
+
+#### SNS Client
+
+Publish messages to SNS topics with optional message attributes:
+
+```typescript
+import { publishToTopic, SNSMessageAttributes } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  const attributes: SNSMessageAttributes = {
+    priority: {
+      DataType: 'String',
+      StringValue: 'high',
+    },
+  };
+
+  const messageId = await publishToTopic(
+    'arn:aws:sns:us-east-1:123456789012:MyTopic',
+    { orderId: '12345', status: 'completed' },
+    attributes,
+  );
+
+  return { statusCode: 200, body: JSON.stringify({ messageId }) };
+};
+```
+
+**→ See [SNS Client Guide](./docs/SNS_CLIENT.md) for detailed configuration and examples**
+
+#### SQS Client
+
+Send messages to SQS queues with optional message attributes:
+
+```typescript
+import { sendToQueue, SQSMessageAttributes } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  const attributes: SQSMessageAttributes = {
+    priority: {
+      DataType: 'String',
+      StringValue: 'high',
+    },
+  };
+
+  const messageId = await sendToQueue(
+    'https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue',
+    { orderId: '12345', status: 'completed' },
+    attributes,
+  );
+
+  return { statusCode: 200, body: JSON.stringify({ messageId }) };
+};
+```
+
+**→ See [SQS Client Guide](./docs/SQS_CLIENT.md) for detailed configuration and examples**
 
 ## Examples
 
-Example Lambda functions using Lambda Utilities are available in the repository:
+To see an example Lambda microservice using the Lambda Utilities, see the LeanStacks [`lambda-starter`](https://github.com/leanstacks/lambda-starter) :octocat: GitHub repository.
 
 - API Gateway with logging and response formatting
 - Configuration validation and DynamoDB integration

package/dist/clients/lambda-client.d.ts

@@ -0,0 +1,78 @@
+import { LambdaClient, LambdaClientConfig } from '@aws-sdk/client-lambda';
+/**
+ * Initializes the Lambda client with the provided configuration.
+ * If the client is already initialized, this will replace it with a new instance.
+ *
+ * @param config - Lambda client configuration
+ * @returns The Lambda client instance
+ *
+ * @example
+ * ```typescript
+ * // Initialize with default configuration
+ * initializeLambdaClient();
+ *
+ * // Initialize with custom configuration
+ * initializeLambdaClient({ region: 'us-east-1' });
+ * ```
+ */
+export declare const initializeLambdaClient: (config?: LambdaClientConfig) => LambdaClient;
+/**
+ * Returns the singleton Lambda client instance.
+ * If the client has not been initialized, creates one with default configuration.
+ *
+ * @returns The Lambda client instance
+ *
+ * @example
+ * ```typescript
+ * const client = getLambdaClient();
+ * ```
+ */
+export declare const getLambdaClient: () => LambdaClient;
+/**
+ * Resets the Lambda client instance.
+ * Useful for testing or when you need to reinitialize the client with a different configuration.
+ */
+export declare const resetLambdaClient: () => void;
+/**
+ * Invokes a Lambda function synchronously (RequestResponse).
+ * The function waits for the response and returns the payload.
+ *
+ * @param functionName - The name or ARN of the Lambda function to invoke
+ * @param payload - The JSON payload to pass to the Lambda function
+ * @returns Promise that resolves to the response payload from the Lambda function
+ * @throws Error if the Lambda invocation fails or returns a function error
+ *
+ * @example
+ * ```typescript
+ * interface MyResponse {
+ *   result: string;
+ *   statusCode: number;
+ * }
+ *
+ * const response = await invokeLambdaSync<MyResponse>(
+ *   'my-function-name',
+ *   { key: 'value', data: { nested: true } }
+ * );
+ * console.log(response.result);
+ * ```
+ */
+export declare const invokeLambdaSync: <T = unknown>(functionName: string, payload: unknown) => Promise<T>;
+/**
+ * Invokes a Lambda function asynchronously (Event).
+ * The function returns immediately without waiting for the Lambda execution to complete.
+ *
+ * @param functionName - The name or ARN of the Lambda function to invoke
+ * @param payload - The JSON payload to pass to the Lambda function
+ * @returns Promise that resolves when the invocation request is accepted
+ * @throws Error if the Lambda invocation request fails
+ *
+ * @example
+ * ```typescript
+ * // Fire and forget invocation
+ * await invokeLambdaAsync(
+ *   'my-async-function',
+ *   { eventType: 'process', data: [1, 2, 3] }
+ * );
+ * ```
+ */
+export declare const invokeLambdaAsync: (functionName: string, payload: unknown) => Promise<void>;

package/dist/clients/sns-client.d.ts

@@ -0,0 +1,75 @@
+import { SNSClient, SNSClientConfig } from '@aws-sdk/client-sns';
+/**
+ * Interface for SNS message attributes.
+ * Supports the AWS SNS data types: String, String.Array, Number, and Binary.
+ * Note: String.Array is the only array type supported by AWS SNS.
+ */
+export interface SNSMessageAttributes {
+    [key: string]: {
+        DataType: 'String' | 'String.Array' | 'Number' | 'Binary';
+        StringValue?: string;
+        BinaryValue?: Uint8Array;
+    };
+}
+/**
+ * Initializes the SNS client with the provided configuration.
+ * If the client is already initialized, this will replace it with a new instance.
+ *
+ * @param config - SNS client configuration
+ * @returns The SNS client instance
+ *
+ * @example
+ * ```typescript
+ * // Initialize with default configuration
+ * initializeSNSClient();
+ *
+ * // Initialize with custom configuration
+ * initializeSNSClient({ region: 'us-east-1' });
+ * ```
+ */
+export declare const initializeSNSClient: (config?: SNSClientConfig) => SNSClient;
+/**
+ * Returns the singleton SNS client instance.
+ * If the client has not been initialized, creates one with default configuration.
+ *
+ * @returns The SNS client instance
+ *
+ * @example
+ * ```typescript
+ * const client = getSNSClient();
+ * ```
+ */
+export declare const getSNSClient: () => SNSClient;
+/**
+ * Resets the SNS client instance.
+ * Useful for testing or when you need to reinitialize the client with a different configuration.
+ */
+export declare const resetSNSClient: () => void;
+/**
+ * Publishes a message to an SNS topic.
+ *
+ * @param topicArn - The ARN of the SNS topic to publish to
+ * @param message - The message content (will be converted to JSON string)
+ * @param attributes - Optional message attributes for filtering
+ * @returns Promise that resolves to the message ID
+ * @throws Error if the SNS publish operation fails
+ *
+ * @example
+ * ```typescript
+ * const messageId = await publishToTopic(
+ *   'arn:aws:sns:us-east-1:123456789012:MyTopic',
+ *   { orderId: '12345', status: 'completed' },
+ *   {
+ *     priority: {
+ *       DataType: 'String',
+ *       StringValue: 'high'
+ *     },
+ *     categories: {
+ *       DataType: 'String.Array',
+ *       StringValue: JSON.stringify(['urgent', 'vip', 'customer-request'])
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export declare const publishToTopic: (topicArn: string, message: Record<string, unknown>, attributes?: SNSMessageAttributes) => Promise<string>;

package/dist/clients/sqs-client.d.ts

@@ -0,0 +1,74 @@
+import { SQSClient, SQSClientConfig } from '@aws-sdk/client-sqs';
+/**
+ * Interface for SQS message attributes.
+ * Supports the AWS SQS data types: String, Number, and Binary.
+ */
+export interface SQSMessageAttributes {
+    [key: string]: {
+        DataType: 'String' | 'Number' | 'Binary';
+        StringValue?: string;
+        BinaryValue?: Uint8Array;
+    };
+}
+/**
+ * Initializes the SQS client with the provided configuration.
+ * If the client is already initialized, this will replace it with a new instance.
+ *
+ * @param config - SQS client configuration
+ * @returns The SQS client instance
+ *
+ * @example
+ * ```typescript
+ * // Initialize with default configuration
+ * initializeSQSClient();
+ *
+ * // Initialize with custom configuration
+ * initializeSQSClient({ region: 'us-east-1' });
+ * ```
+ */
+export declare const initializeSQSClient: (config?: SQSClientConfig) => SQSClient;
+/**
+ * Returns the singleton SQS client instance.
+ * If the client has not been initialized, creates one with default configuration.
+ *
+ * @returns The SQS client instance
+ *
+ * @example
+ * ```typescript
+ * const client = getSQSClient();
+ * ```
+ */
+export declare const getSQSClient: () => SQSClient;
+/**
+ * Resets the SQS client instance.
+ * Useful for testing or when you need to reinitialize the client with a different configuration.
+ */
+export declare const resetSQSClient: () => void;
+/**
+ * Sends a message to an SQS queue.
+ *
+ * @param queueUrl - The URL of the SQS queue to send to
+ * @param message - The message content (will be converted to JSON string)
+ * @param attributes - Optional message attributes for filtering
+ * @returns Promise that resolves to the message ID
+ * @throws Error if the SQS send operation fails
+ *
+ * @example
+ * ```typescript
+ * const messageId = await sendToQueue(
+ *   'https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue',
+ *   { orderId: '12345', status: 'completed' },
+ *   {
+ *     priority: {
+ *       DataType: 'String',
+ *       StringValue: 'high'
+ *     },
+ *     attempts: {
+ *       DataType: 'Number',
+ *       StringValue: '1'
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export declare const sendToQueue: (queueUrl: string, message: Record<string, unknown>, attributes?: SQSMessageAttributes) => Promise<string>;

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 export { Logger, LoggerConfig, withRequestTracking } from './logging/logger';
 export { createResponse, ok, created, noContent, badRequest, notFound, internalServerError, httpHeaders, Headers, } from './utils/apigateway-response';
 export { getDynamoDBClient, getDynamoDBDocumentClient, initializeDynamoDBClients, resetDynamoDBClients, } from './clients/dynamodb-client';
+export { getSNSClient, initializeSNSClient, SNSMessageAttributes, publishToTopic, resetSNSClient, } from './clients/sns-client';
+export { getLambdaClient, initializeLambdaClient, invokeLambdaAsync, invokeLambdaSync, resetLambdaClient, } from './clients/lambda-client';
+export { getSQSClient, initializeSQSClient, SQSMessageAttributes, sendToQueue, resetSQSClient, } from './clients/sqs-client';
 export { createConfigManager, ConfigManager } from './validation/config';

package/dist/index.esm.js

@@ -1,2 +1,2 @@
-import n from"pino";import{lambdaRequestTracker as e,StructuredLogFormatter as t,CloudwatchLogFormatter as o,pinoLambdaDestination as r}from"pino-lambda";import{DynamoDBClient as i}from"@aws-sdk/client-dynamodb";import{DynamoDBDocumentClient as s}from"@aws-sdk/lib-dynamodb";import{z as l}from"zod";const a=e();class c{constructor(e){this._loggerConfig={enabled:!0,level:"info",format:"json"},this._instance=null,this._createLogger=()=>{const e="json"===this._loggerConfig.format?new t:new o,i=r({formatter:e});return n({enabled:this._loggerConfig.enabled,level:this._loggerConfig.level},i)},e&&(this._loggerConfig={enabled:e.enabled??!0,level:e.level??"info",format:e.format??"json"})}get instance(){return null===this._instance&&(this._instance=this._createLogger()),this._instance}}const m={contentType:n=>({"Content-Type":n}),json:{"Content-Type":"application/json"},cors:(n="*")=>({"Access-Control-Allow-Origin":n})},f=(n,e,t={})=>({statusCode:n,headers:{...t},body:JSON.stringify(e)}),g=(n,e={})=>f(200,n,e),d=(n,e={})=>f(201,n,e),u=(n={})=>f(204,{},n),h=(n="Bad Request",e={})=>f(400,{message:n},e),p=(n="Not Found",e={})=>f(404,{message:n},e),C=(n="Internal Server Error",e={})=>f(500,{message:n},e);let w=null,y=null;const _=(n,e,t)=>{w=new i(n||{});const o={marshallOptions:e||{},unmarshallOptions:t||{}};return y=s.from(w,o),{client:w,documentClient:y}},b=()=>{if(!w)throw new Error("DynamoDB client not initialized. Call initializeDynamoDBClients() first.");return w},D=()=>{if(!y)throw new Error("DynamoDB Document client not initialized. Call initializeDynamoDBClients() first.");return y},v=()=>{w=null,y=null},j=n=>{let e=null;const t=()=>{try{return n.parse(process.env)}catch(n){if(n instanceof l.ZodError){const e=n.issues.map(n=>`${n.path.join(".")}: ${n.message}`).join(", ");throw new Error(`Configuration validation failed: ${e}`)}throw n}};return{get:()=>(e||(e=t()),e),refresh:()=>(e=t(),e)}};export{c as Logger,h as badRequest,j as createConfigManager,f as createResponse,d as created,b as getDynamoDBClient,D as getDynamoDBDocumentClient,m as httpHeaders,_ as initializeDynamoDBClients,C as internalServerError,u as noContent,p as notFound,g as ok,v as resetDynamoDBClients,a as withRequestTracking};
+import n from"pino";import{lambdaRequestTracker as e,StructuredLogFormatter as t,CloudwatchLogFormatter as o,pinoLambdaDestination as r}from"pino-lambda";import{DynamoDBClient as s}from"@aws-sdk/client-dynamodb";import{DynamoDBDocumentClient as i}from"@aws-sdk/lib-dynamodb";import{SNSClient as a,PublishCommand as l}from"@aws-sdk/client-sns";import{LambdaClient as c,InvokeCommand as u}from"@aws-sdk/client-lambda";import{SQSClient as d,SendMessageCommand as m}from"@aws-sdk/client-sqs";import{z as f}from"zod";const g=e();class w{constructor(e){this._loggerConfig={enabled:!0,level:"info",format:"json"},this._instance=null,this._createLogger=()=>{const e="json"===this._loggerConfig.format?new t:new o,s=r({formatter:e});return n({enabled:this._loggerConfig.enabled,level:this._loggerConfig.level},s)},e&&(this._loggerConfig={enabled:e.enabled??!0,level:e.level??"info",format:e.format??"json"})}get instance(){return null===this._instance&&(this._instance=this._createLogger()),this._instance}}const p={contentType:n=>({"Content-Type":n}),json:{"Content-Type":"application/json"},cors:(n="*")=>({"Access-Control-Allow-Origin":n})},y=(n,e,t={})=>({statusCode:n,headers:{...t},body:JSON.stringify(e)}),h=(n,e={})=>y(200,n,e),b=(n,e={})=>y(201,n,e),C=(n={})=>y(204,{},n),E=(n="Bad Request",e={})=>y(400,{message:n},e),v=(n="Not Found",e={})=>y(404,{message:n},e),_=(n="Internal Server Error",e={})=>y(500,{message:n},e);let D=null,N=null;const O=(n,e,t)=>{D=new s(n||{});const o={marshallOptions:e||{},unmarshallOptions:t||{}};return N=i.from(D,o),{client:D,documentClient:N}},j=()=>{if(!D)throw new Error("DynamoDB client not initialized. Call initializeDynamoDBClients() first.");return D},F=()=>{if(!N)throw new Error("DynamoDB Document client not initialized. Call initializeDynamoDBClients() first.");return N},S=()=>{D=null,N=null};let T=null;const B=n=>(T=new a(n||{}),T),J=()=>(T||(T=new a({})),T),M=()=>{T=null},k=async(n,e,t)=>{const o=J(),r=new l({TopicArn:n,Message:JSON.stringify(e),MessageAttributes:t});return(await o.send(r)).MessageId??""};let z=null;const A=n=>(z=new c(n||{}),z),I=()=>(z||(z=new c({})),z),$=()=>{z=null},L=async(n,e)=>{const t=I(),o=new u({FunctionName:n,InvocationType:"RequestResponse",Payload:JSON.stringify(e)}),r=await t.send(o);if(r.FunctionError)throw new Error(`Lambda function error: ${r.FunctionError}`);return r.Payload?JSON.parse((new TextDecoder).decode(r.Payload)):null},P=async(n,e)=>{const t=I(),o=new u({FunctionName:n,InvocationType:"Event",Payload:JSON.stringify(e)}),r=await t.send(o);if(r.FunctionError)throw new Error(`Lambda function error: ${r.FunctionError}`)};let q=null;const R=n=>(q=new d(n||{}),q),x=()=>(q||(q=new d({})),q),Q=()=>{q=null},U=async(n,e,t)=>{const o=x(),r=new m({QueueUrl:n,MessageBody:JSON.stringify(e),MessageAttributes:t});return(await o.send(r)).MessageId??""},Z=n=>{let e=null;const t=()=>{try{return n.parse(process.env)}catch(n){if(n instanceof f.ZodError){const e=n.issues.map(n=>`${n.path.join(".")}: ${n.message}`).join(", ");throw new Error(`Configuration validation failed: ${e}`)}throw n}};return{get:()=>(e||(e=t()),e),refresh:()=>(e=t(),e)}};export{w as Logger,E as badRequest,Z as createConfigManager,y as createResponse,b as created,j as getDynamoDBClient,F as getDynamoDBDocumentClient,I as getLambdaClient,J as getSNSClient,x as getSQSClient,p as httpHeaders,O as initializeDynamoDBClients,A as initializeLambdaClient,B as initializeSNSClient,R as initializeSQSClient,_ as internalServerError,P as invokeLambdaAsync,L as invokeLambdaSync,C as noContent,v as notFound,h as ok,k as publishToTopic,S as resetDynamoDBClients,$ as resetLambdaClient,M as resetSNSClient,Q as resetSQSClient,U as sendToQueue,g as withRequestTracking};
 //# sourceMappingURL=index.esm.js.map

package/dist/index.js

@@ -1,2 +1,2 @@
-"use strict";var e=require("pino"),t=require("pino-lambda"),n=require("@aws-sdk/client-dynamodb"),r=require("@aws-sdk/lib-dynamodb"),o=require("zod");const i=t.lambdaRequestTracker();const s=(e,t,n={})=>({statusCode:e,headers:{...n},body:JSON.stringify(t)});let a=null,l=null;exports.Logger=class{constructor(n){this._loggerConfig={enabled:!0,level:"info",format:"json"},this._instance=null,this._createLogger=()=>{const n="json"===this._loggerConfig.format?new t.StructuredLogFormatter:new t.CloudwatchLogFormatter,r=t.pinoLambdaDestination({formatter:n});return e({enabled:this._loggerConfig.enabled,level:this._loggerConfig.level},r)},n&&(this._loggerConfig={enabled:n.enabled??!0,level:n.level??"info",format:n.format??"json"})}get instance(){return null===this._instance&&(this._instance=this._createLogger()),this._instance}},exports.badRequest=(e="Bad Request",t={})=>s(400,{message:e},t),exports.createConfigManager=e=>{let t=null;const n=()=>{try{return e.parse(process.env)}catch(e){if(e instanceof o.z.ZodError){const t=e.issues.map(e=>`${e.path.join(".")}: ${e.message}`).join(", ");throw new Error(`Configuration validation failed: ${t}`)}throw e}};return{get:()=>(t||(t=n()),t),refresh:()=>(t=n(),t)}},exports.createResponse=s,exports.created=(e,t={})=>s(201,e,t),exports.getDynamoDBClient=()=>{if(!a)throw new Error("DynamoDB client not initialized. Call initializeDynamoDBClients() first.");return a},exports.getDynamoDBDocumentClient=()=>{if(!l)throw new Error("DynamoDB Document client not initialized. Call initializeDynamoDBClients() first.");return l},exports.httpHeaders={contentType:e=>({"Content-Type":e}),json:{"Content-Type":"application/json"},cors:(e="*")=>({"Access-Control-Allow-Origin":e})},exports.initializeDynamoDBClients=(e,t,o)=>{a=new n.DynamoDBClient(e||{});const i={marshallOptions:t||{},unmarshallOptions:o||{}};return l=r.DynamoDBDocumentClient.from(a,i),{client:a,documentClient:l}},exports.internalServerError=(e="Internal Server Error",t={})=>s(500,{message:e},t),exports.noContent=(e={})=>s(204,{},e),exports.notFound=(e="Not Found",t={})=>s(404,{message:e},t),exports.ok=(e,t={})=>s(200,e,t),exports.resetDynamoDBClients=()=>{a=null,l=null},exports.withRequestTracking=i;
+"use strict";var e=require("pino"),n=require("pino-lambda"),t=require("@aws-sdk/client-dynamodb"),r=require("@aws-sdk/lib-dynamodb"),o=require("@aws-sdk/client-sns"),s=require("@aws-sdk/client-lambda"),i=require("@aws-sdk/client-sqs"),a=require("zod");const l=n.lambdaRequestTracker();const c=(e,n,t={})=>({statusCode:e,headers:{...t},body:JSON.stringify(n)});let u=null,d=null;let m=null;const g=()=>(m||(m=new o.SNSClient({})),m);let p=null;const C=()=>(p||(p=new s.LambdaClient({})),p);let w=null;const y=()=>(w||(w=new i.SQSClient({})),w);exports.Logger=class{constructor(t){this._loggerConfig={enabled:!0,level:"info",format:"json"},this._instance=null,this._createLogger=()=>{const t="json"===this._loggerConfig.format?new n.StructuredLogFormatter:new n.CloudwatchLogFormatter,r=n.pinoLambdaDestination({formatter:t});return e({enabled:this._loggerConfig.enabled,level:this._loggerConfig.level},r)},t&&(this._loggerConfig={enabled:t.enabled??!0,level:t.level??"info",format:t.format??"json"})}get instance(){return null===this._instance&&(this._instance=this._createLogger()),this._instance}},exports.badRequest=(e="Bad Request",n={})=>c(400,{message:e},n),exports.createConfigManager=e=>{let n=null;const t=()=>{try{return e.parse(process.env)}catch(e){if(e instanceof a.z.ZodError){const n=e.issues.map(e=>`${e.path.join(".")}: ${e.message}`).join(", ");throw new Error(`Configuration validation failed: ${n}`)}throw e}};return{get:()=>(n||(n=t()),n),refresh:()=>(n=t(),n)}},exports.createResponse=c,exports.created=(e,n={})=>c(201,e,n),exports.getDynamoDBClient=()=>{if(!u)throw new Error("DynamoDB client not initialized. Call initializeDynamoDBClients() first.");return u},exports.getDynamoDBDocumentClient=()=>{if(!d)throw new Error("DynamoDB Document client not initialized. Call initializeDynamoDBClients() first.");return d},exports.getLambdaClient=C,exports.getSNSClient=g,exports.getSQSClient=y,exports.httpHeaders={contentType:e=>({"Content-Type":e}),json:{"Content-Type":"application/json"},cors:(e="*")=>({"Access-Control-Allow-Origin":e})},exports.initializeDynamoDBClients=(e,n,o)=>{u=new t.DynamoDBClient(e||{});const s={marshallOptions:n||{},unmarshallOptions:o||{}};return d=r.DynamoDBDocumentClient.from(u,s),{client:u,documentClient:d}},exports.initializeLambdaClient=e=>(p=new s.LambdaClient(e||{}),p),exports.initializeSNSClient=e=>(m=new o.SNSClient(e||{}),m),exports.initializeSQSClient=e=>(w=new i.SQSClient(e||{}),w),exports.internalServerError=(e="Internal Server Error",n={})=>c(500,{message:e},n),exports.invokeLambdaAsync=async(e,n)=>{const t=C(),r=new s.InvokeCommand({FunctionName:e,InvocationType:"Event",Payload:JSON.stringify(n)}),o=await t.send(r);if(o.FunctionError)throw new Error(`Lambda function error: ${o.FunctionError}`)},exports.invokeLambdaSync=async(e,n)=>{const t=C(),r=new s.InvokeCommand({FunctionName:e,InvocationType:"RequestResponse",Payload:JSON.stringify(n)}),o=await t.send(r);if(o.FunctionError)throw new Error(`Lambda function error: ${o.FunctionError}`);return o.Payload?JSON.parse((new TextDecoder).decode(o.Payload)):null},exports.noContent=(e={})=>c(204,{},e),exports.notFound=(e="Not Found",n={})=>c(404,{message:e},n),exports.ok=(e,n={})=>c(200,e,n),exports.publishToTopic=async(e,n,t)=>{const r=g(),s=new o.PublishCommand({TopicArn:e,Message:JSON.stringify(n),MessageAttributes:t});return(await r.send(s)).MessageId??""},exports.resetDynamoDBClients=()=>{u=null,d=null},exports.resetLambdaClient=()=>{p=null},exports.resetSNSClient=()=>{m=null},exports.resetSQSClient=()=>{w=null},exports.sendToQueue=async(e,n,t)=>{const r=y(),o=new i.SendMessageCommand({QueueUrl:e,MessageBody:JSON.stringify(n),MessageAttributes:t});return(await r.send(o)).MessageId??""},exports.withRequestTracking=l;
 //# sourceMappingURL=index.js.map

package/docs/LAMBDA_CLIENT.md

@@ -0,0 +1,292 @@
+# Lambda Client Utilities
+
+The Lambda client utilities provide a reusable singleton instance of `LambdaClient` for use in AWS Lambda functions. These utilities enable you to configure the client once and reuse it across invocations, following AWS best practices for Lambda performance optimization.
+
+## Overview
+
+The utility exports the following functions:
+
+- `initializeLambdaClient()` - Initialize the Lambda client with optional configuration
+- `getLambdaClient()` - Get the singleton Lambda client instance
+- `invokeLambdaSync()` - Invoke a Lambda function synchronously (RequestResponse)
+- `invokeLambdaAsync()` - Invoke a Lambda function asynchronously (Event)
+- `resetLambdaClient()` - Reset the client instance (useful for testing)
+
+## Usage
+
+### Synchronous Invocation (RequestResponse)
+
+Use synchronous invocation when you need to wait for the Lambda function to complete and return a response:
+
+```typescript
+import { invokeLambdaSync } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  // Invoke a Lambda function and wait for the response
+  const response = await invokeLambdaSync('my-function-name', {
+    key: 'value',
+    data: { nested: true },
+  });
+
+  return {
+    statusCode: 200,
+    body: JSON.stringify(response),
+  };
+};
+```
+
+### Synchronous Invocation with Typed Response
+
+For better type safety, you can specify the expected response type:
+
+```typescript
+import { invokeLambdaSync } from '@leanstacks/lambda-utils';
+
+interface MyFunctionResponse {
+  result: string;
+  statusCode: number;
+  data: Record<string, unknown>;
+}
+
+export const handler = async (event: any) => {
+  const response = await invokeLambdaSync<MyFunctionResponse>('my-function-name', {
+    operation: 'getData',
+    id: '12345',
+  });
+
+  console.log(`Function returned: ${response.result}`);
+
+  return {
+    statusCode: response.statusCode,
+    body: JSON.stringify(response.data),
+  };
+};
+```
+
+### Asynchronous Invocation (Event)
+
+Use asynchronous invocation for fire-and-forget scenarios where you don't need to wait for the Lambda function to complete:
+
+```typescript
+import { invokeLambdaAsync } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  // Invoke a Lambda function asynchronously (fire and forget)
+  await invokeLambdaAsync('my-async-function', {
+    eventType: 'process',
+    data: [1, 2, 3],
+  });
+
+  // Returns immediately without waiting for the function to complete
+  return {
+    statusCode: 202,
+    body: JSON.stringify({ message: 'Processing initiated' }),
+  };
+};
+```
+
+### Using Function ARN
+
+You can invoke Lambda functions by name or ARN:
+
+```typescript
+import { invokeLambdaSync } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  // Using function ARN
+  const response = await invokeLambdaSync('arn:aws:lambda:us-east-1:123456789012:function:my-function', {
+    key: 'value',
+  });
+
+  return {
+    statusCode: 200,
+    body: JSON.stringify(response),
+  };
+};
+```
+
+### Using the Lambda Client Directly
+
+For advanced use cases, you can access the underlying Lambda client:
+
+```typescript
+import { getLambdaClient } from '@leanstacks/lambda-utils';
+import { ListFunctionsCommand } from '@aws-sdk/client-lambda';
+
+export const handler = async (event: any) => {
+  const client = getLambdaClient();
+
+  const response = await client.send(new ListFunctionsCommand({}));
+
+  return {
+    statusCode: 200,
+    body: JSON.stringify(response.Functions),
+  };
+};
+```
+
+### Custom Configuration
+
+Initialize the Lambda client with custom configuration at the start of your Lambda handler:
+
+```typescript
+import { initializeLambdaClient, invokeLambdaSync } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  // Initialize with custom configuration (only needs to be done once)
+  initializeLambdaClient({
+    region: 'us-west-2',
+    maxAttempts: 3,
+  });
+
+  const response = await invokeLambdaSync('my-function', { key: 'value' });
+
+  return {
+    statusCode: 200,
+    body: JSON.stringify(response),
+  };
+};
+```
+
+## API Reference
+
+### initializeLambdaClient(config?)
+
+Initializes the Lambda client with the provided configuration. If the client is already initialized, this will replace it with a new instance.
+
+**Parameters:**
+
+- `config` (optional): `LambdaClientConfig` - AWS SDK Lambda client configuration
+
+**Returns:** `LambdaClient` - The Lambda client instance
+
+### getLambdaClient()
+
+Returns the singleton Lambda client instance. If the client has not been initialized, creates one with default configuration.
+
+**Returns:** `LambdaClient` - The Lambda client instance
+
+### invokeLambdaSync<T>(functionName, payload)
+
+Invokes a Lambda function synchronously (RequestResponse). The function waits for the response and returns the payload.
+
+**Parameters:**
+
+- `functionName`: `string` - The name or ARN of the Lambda function to invoke
+- `payload`: `unknown` - The JSON payload to pass to the Lambda function
+
+**Returns:** `Promise<T>` - Promise that resolves to the response payload from the Lambda function
+
+**Throws:** `Error` - If the Lambda invocation fails or returns a function error
+
+### invokeLambdaAsync(functionName, payload)
+
+Invokes a Lambda function asynchronously (Event). The function returns immediately without waiting for the Lambda execution to complete.
+
+**Parameters:**
+
+- `functionName`: `string` - The name or ARN of the Lambda function to invoke
+- `payload`: `unknown` - The JSON payload to pass to the Lambda function
+
+**Returns:** `Promise<void>` - Promise that resolves when the invocation request is accepted
+
+**Throws:** `Error` - If the Lambda invocation request fails
+
+### resetLambdaClient()
+
+Resets the Lambda client instance. Useful for testing or when you need to reinitialize the client with a different configuration.
+
+**Returns:** `void`
+
+## Error Handling
+
+Both `invokeLambdaSync` and `invokeLambdaAsync` throw errors in the following cases:
+
+1. **Function Errors**: When the invoked Lambda function returns an error (e.g., unhandled exceptions)
+2. **AWS SDK Errors**: When the AWS SDK encounters an error (e.g., network issues, permission errors)
+
+```typescript
+import { invokeLambdaSync } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  try {
+    const response = await invokeLambdaSync('my-function', { key: 'value' });
+    return {
+      statusCode: 200,
+      body: JSON.stringify(response),
+    };
+  } catch (error) {
+    console.error('Lambda invocation failed:', error);
+    return {
+      statusCode: 500,
+      body: JSON.stringify({ error: 'Failed to invoke Lambda function' }),
+    };
+  }
+};
+```
+
+## Testing
+
+The utility provides a `resetLambdaClient()` function for testing purposes:
+
+```typescript
+import { resetLambdaClient, initializeLambdaClient } from '@leanstacks/lambda-utils';
+import { mockClient } from 'aws-sdk-client-mock';
+import { LambdaClient, InvokeCommand } from '@aws-sdk/client-lambda';
+
+describe('My Lambda Tests', () => {
+  const lambdaClientMock = mockClient(LambdaClient);
+
+  beforeEach(() => {
+    resetLambdaClient();
+    lambdaClientMock.reset();
+  });
+
+  it('should invoke Lambda function successfully', async () => {
+    // Mock the Lambda client response
+    const responsePayload = { result: 'success' };
+    const encoder = new TextEncoder();
+    const responseBytes = encoder.encode(JSON.stringify(responsePayload));
+
+    lambdaClientMock.on(InvokeCommand).resolves({
+      StatusCode: 200,
+      Payload: responseBytes,
+    });
+
+    // Test your code that uses invokeLambdaSync or invokeLambdaAsync
+    // ...
+  });
+});
+```
+
+## Best Practices
+
+1. **Singleton Pattern**: The Lambda client is created once and reused across invocations, improving performance by reducing initialization overhead.
+
+2. **Error Handling**: Always wrap Lambda invocations in try-catch blocks to handle potential errors gracefully.
+
+3. **Type Safety**: Use TypeScript generics to specify the expected response type for synchronous invocations:
+
+   ```typescript
+   const response = await invokeLambdaSync<MyResponseType>('my-function', payload);
+   ```
+
+4. **Async vs Sync**: Choose the appropriate invocation type:
+   - Use `invokeLambdaSync` when you need to wait for and process the response
+   - Use `invokeLambdaAsync` for fire-and-forget scenarios to improve performance
+
+5. **IAM Permissions**: Ensure your Lambda function has the necessary IAM permissions to invoke other Lambda functions:
+   ```json
+   {
+     "Effect": "Allow",
+     "Action": ["lambda:InvokeFunction"],
+     "Resource": "arn:aws:lambda:region:account-id:function:function-name"
+   }
+   ```
+
+## See Also
+
+- [AWS SDK for JavaScript - Lambda Client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-lambda/)
+- [AWS Lambda Developer Guide - Invoking Functions](https://docs.aws.amazon.com/lambda/latest/dg/lambda-invocation.html)
+- [DynamoDB Client Documentation](./DYNAMODB_CLIENT.md)
+- [SNS Client Documentation](./SNS_CLIENT.md)