npm package: @origins-digital/nestjs-aws-ssm
Description: Origins Digital NestJS AWS SSM Module
Author: Origins Digital
Latest version: 2.1.4

# @origins-digital/nestjs-aws-ssm

A NestJS package for interacting with AWS Systems Manager Parameter Store, providing secure parameter storage and retrieval capabilities.

## Installation

```bash
npm install @origins-digital/nestjs-aws-ssm
```

## Features

- AWS Systems Manager Parameter Store integration
- Secure parameter storage and retrieval with automatic decryption
- Automatic JSON parsing/stringifying
- Type-safe parameter management
- Comprehensive error handling
- Support for parameter versions and metadata

## Usage

### Basic Setup

```typescript
import { Module } from '@nestjs/common';
import { AWSSystemManagerModule } from '@origins-digital/nestjs-aws-ssm';

@Module({
  imports: [AWSSystemManagerModule],
})
export class AppModule {}
```

### Using the Service

```typescript
import { Injectable } from '@nestjs/common';
import { AWSSystemManagerService } from '@origins-digital/nestjs-aws-ssm';

@Injectable()
export class YourService {
  constructor(private readonly ssmService: AWSSystemManagerService) {}

  async getConfig() {
    // Get a parameter value
    const value = await this.ssmService.getParameterValue(
      'your-parameter-name',
    );

    // Get a secure parameter with decryption
    const secureValue = await this.ssmService.getParameterValue(
      'secure-param',
      {
        withDecryption: true,
      },
    );

    // Get full parameter details
    const parameter = await this.ssmService.getParameter('full-param');

    // Set a parameter
    await this.ssmService.setParameter('new-param', {
      some: 'data',
    });

    // Set a secure parameter
    await this.ssmService.setParameter('secure-param', 'sensitive-data', {
      secured: true,
    });

    // Delete a single parameter
    await this.ssmService.deleteParameter('old-param');

    // Delete multiple parameters
    await this.ssmService.deleteParameters(['param1', 'param2']);
  }
}
```

### Service Methods

#### `getParameterValue(name: string, options?: { withDecryption?: boolean })`

Retrieves the value of a parameter, optionally with decryption for secure parameters.

#### `getParameter(name: string)`

Retrieves the full parameter object including metadata, type, and version information.

#### `setParameter(name: string, value: any, options?: ParameterOptions)`

Sets a parameter value with optional configuration like security, type, and description.

#### `deleteParameter(name: string)`

Deletes a single parameter.

#### `deleteParameters(names: string[])`

Deletes multiple parameters in a single operation.

### Parameter Store Features

- **Get Parameters**: Retrieve parameters with optional decryption
- **Get Full Parameters**: Access complete parameter metadata
- **Set Parameters**: Store parameters with configurable options
- **Delete Parameters**: Remove single or multiple parameters
- **Automatic JSON Handling**: Values are automatically parsed/stringified
- **Version Support**: Access specific versions of parameters
- **Secure Parameters**: Handle encrypted parameters with automatic decryption

## Configuration

The service uses AWS SDK v3 and inherits configuration from your AWS environment:

- **Environment Variables**: `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
- **AWS Profiles**: Uses default profile or specified profile
- **IAM Roles**: Supports EC2 instance roles and ECS task roles

## Error Handling

The service includes comprehensive error handling for AWS operations:

- Returns `null` for non-existent parameters instead of throwing errors
- Provides detailed error information for AWS operation failures
- Handles network timeouts and retries gracefully

## Dependencies

- `@nestjs/common`: NestJS framework
- `@aws-sdk/client-ssm`: AWS SDK v3 for Systems Manager
- `@aws-sdk/client-secrets-manager`: AWS SDK v3 for Secrets Manager

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see the [LICENSE](../../../LICENSE) file for details.