AWS SDK Integration

/**
 * Add the Powertools for AWS Lambda user agent middleware to an AWS SDK v3 client.
 * This middleware appends the feature name and Powertools version to the user agent string
 * for usage tracking. The middleware is used to secure continued investment in the project.
 *
 * The middleware will append information in the format: "PT/<feature>/<version> PTEnv/<environment>"
 * Example: "PT/Tracer/2.29.0 PTEnv/nodejs20.x"
 *
 * @param client - The AWS SDK v3 client to add the middleware to
 * @param feature - The feature name to be added to the user agent (e.g., 'Tracer', 'Logger', 'Metrics')
 * @throws Error if the client does not match the expected AWS SDK v3 interface
 */
function addUserAgentMiddleware(client: unknown, feature: string): void;

/**
 * Type guard to check if the client provided is a valid AWS SDK v3 client.
 * Validates that the client has the required methods and properties for middleware integration.
 *
 * @param client - The client to check
 * @returns Type guard indicating if client is a valid SdkClient
 */
function isSdkClient(client: unknown): client is SdkClient;

/**
 * Interface representing a valid AWS SDK v3 client.
 */
interface SdkClient {
  /** Method to send commands to AWS services */
  send: Function;
  /** Client configuration object */
  config: object;
  /** Middleware stack for request/response processing */
  middlewareStack: {
    /** Get list of middleware names */
    identify: () => string[];
    /** Add middleware relative to another middleware */
    addRelativeTo: (middleware: Function, options: object) => void;
  };
}

import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { addUserAgentMiddleware } from '@aws-lambda-powertools/commons';

// Create AWS SDK v3 client
const dynamoDBClient = new DynamoDBClient({});

// Add Powertools user agent middleware
addUserAgentMiddleware(dynamoDBClient, 'MyFeature');

// Now all requests will include Powertools user agent information
// The user agent will include: "PT/MyFeature/2.29.0 PTEnv/nodejs20.x"

import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { S3Client } from '@aws-sdk/client-s3';
import { SQSClient } from '@aws-sdk/client-sqs';
import { addUserAgentMiddleware } from '@aws-lambda-powertools/commons';

const dynamoDBClient = new DynamoDBClient({});
const s3Client = new S3Client({});
const sqsClient = new SQSClient({});

// Add middleware to all clients
addUserAgentMiddleware(dynamoDBClient, 'Logger');
addUserAgentMiddleware(s3Client, 'Logger');
addUserAgentMiddleware(sqsClient, 'Logger');

import { isSdkClient } from '@aws-lambda-powertools/commons';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';

function processClient(client: unknown) {
  if (isSdkClient(client)) {
    // TypeScript knows client is SdkClient here
    console.log('Valid AWS SDK v3 client');
    // Can safely access client.send, client.config, etc.
  } else {
    console.log('Not a valid AWS SDK v3 client');
  }
}

const dynamoDBClient = new DynamoDBClient({});
processClient(dynamoDBClient); // Valid AWS SDK v3 client
processClient({}); // Not a valid AWS SDK v3 client

import { addUserAgentMiddleware, isSdkClient } from '@aws-lambda-powertools/commons';

class MyCustomUtility {
  private client: unknown;

  constructor(client: unknown) {
    if (!isSdkClient(client)) {
      throw new Error('Invalid AWS SDK client provided');
    }

    this.client = client;

    // Add user agent middleware for tracking
    addUserAgentMiddleware(client, 'CustomUtility');
  }

  // ... rest of utility implementation
}

import { addUserAgentMiddleware } from '@aws-lambda-powertools/commons';

// The function will warn but not throw on invalid clients
const invalidClient = { notAnSdkClient: true };

// This will log a warning to console but not throw
addUserAgentMiddleware(invalidClient, 'MyFeature');
// Console output: "Failed to add user agent middleware [Error: ...]"