{"_id":"@appinventiv/aws-secret-manager","_rev":"4-c1429a1af9ee6a276e0f597c7fa18a40","name":"@appinventiv/aws-secret-manager","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@appinventiv/aws-secret-manager","version":"1.0.0","keywords":[],"author":"","license":"ISC","_id":"@appinventiv/aws-secret-manager@1.0.0","maintainers":[{"name":"abhishek.tyagi1","email":"abhishek.tyagi1@appinventiv.com"}],"dist":{"shasum":"24cac5785d60d454b0fb35d10b9e52aaba801e1a","tarball":"https://registry.npmjs.org/@appinventiv/aws-secret-manager/-/aws-secret-manager-1.0.0.tgz","fileCount":12,"integrity":"sha512-5vE0O37UfyN7gLBsPn/kHKgekcM+bYk2ublTUDxqXtxVjuQZDm/BVQP8qEiGVsW9s+afO7by2yTlptl/o1cjKg==","signatures":[{"sig":"MEYCIQC/iSllKUaG6W/ntf+2WJdFqy5fd5jEihlBpm1AmXzWWQIhAKpEX0VqYyEOxhc1b9BJDctP+kEH3tRmpWC288EumY+N","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":127807},"main":"dist/index.js","types":"dist/index.d.ts","scripts":{"test":"echo \"Error: no test specified\" && exit 1","build":"tsc"},"_npmUser":{"name":"abhishek.tyagi1","email":"abhishek.tyagi1@appinventiv.com"},"_npmVersion":"10.9.3","description":"AWS Secrets Manager client package for Node.js applications. Provides an easy-to-use interface for retrieving secrets from AWS Secrets Manager.","directories":{},"_nodeVersion":"22.19.0","dependencies":{"@aws-sdk/client-secrets-manager":"^3.972.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.3","@types/node":"^25.0.9"},"_npmOperationalInternal":{"tmp":"tmp/aws-secret-manager_1.0.0_1769313971144_0.7819204143039158","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@appinventiv/aws-secret-manager","version":"1.0.1","keywords":[],"author":"","license":"ISC","_id":"@appinventiv/aws-secret-manager@1.0.1","maintainers":[{"name":"developer-at","email":"abhishektyagi199816@gmail.com"},{"name":"abhishek.tyagi1","email":"abhishek.tyagi1@appinventiv.com"}],"dist":{"shasum":"48870311709fe25a253e0689043b757ee3b1c4db","tarball":"https://registry.npmjs.org/@appinventiv/aws-secret-manager/-/aws-secret-manager-1.0.1.tgz","fileCount":13,"integrity":"sha512-XmZ352cDia1kWNaioLav45MdSGvgvuz/rkAAhoTFKpA9/JavKCvr0SJFI9iqrDigkdCo9JxUkLvKdDwBHQfAUw==","signatures":[{"sig":"MEYCIQDVNxTERfeNG51Oc1fS3b3EWcAcvxk6f8UIARilXBK0JwIhAOBUkr9STE2//hncRs+nF4rbaqJv7UbGZlfwcq177daA","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":139498},"main":"dist/index.js","types":"dist/index.d.ts","scripts":{"test":"echo \"Error: no test specified\" && exit 1","build":"tsc"},"_npmUser":{"name":"abhishek.tyagi1","email":"abhishek.tyagi1@appinventiv.com"},"_npmVersion":"10.9.3","description":"AWS Secrets Manager client package for Node.js applications. Provides an easy-to-use interface for retrieving secrets from AWS Secrets Manager.","directories":{},"_nodeVersion":"22.19.0","dependencies":{"@aws-sdk/client-secrets-manager":"^3.972.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.3","@types/node":"^25.0.9"},"_npmOperationalInternal":{"tmp":"tmp/aws-secret-manager_1.0.1_1769577063586_0.6112446732788808","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@appinventiv/aws-secret-manager","version":"1.0.2","description":"AWS Secrets Manager client package for Node.js applications. Provides an easy-to-use interface for retrieving secrets from AWS Secrets Manager.","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","test":"echo \"Error: no test specified\" && exit 1"},"keywords":[],"author":"","license":"ISC","devDependencies":{"@types/node":"^25.0.9","typescript":"^5.9.3"},"dependencies":{"@aws-sdk/client-secrets-manager":"^3.972.0"},"_id":"@appinventiv/aws-secret-manager@1.0.2","_nodeVersion":"22.19.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-jAsBOqKfXAk5dHU4qUJB/WiOj2Ao9aUvfvJk4v8bM+ETRxen7qUhd9BqwfnDEK7RCFikgFirxWzVIQV+08rv3g==","shasum":"03a74bb3c96f976ad76204d2a57534f5d37bb01c","tarball":"https://registry.npmjs.org/@appinventiv/aws-secret-manager/-/aws-secret-manager-1.0.2.tgz","fileCount":16,"unpackedSize":166455,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHpKw5E+C8GWtPOcls7RXgQ2UpRekoqxi2Z/5uzmk7TIAiEA09jhin6wIqrKTlxJo5Lo380R42DqSdXIPGItfDMhzMQ="}]},"_npmUser":{"name":"abhishek.tyagi1","email":"abhishek.tyagi1@appinventiv.com"},"directories":{},"maintainers":[{"name":"developer-at","email":"abhishektyagi199816@gmail.com"},{"name":"abhishek.tyagi1","email":"abhishek.tyagi1@appinventiv.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/aws-secret-manager_1.0.2_1778743020355_0.560230387381901"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-25T04:06:11.033Z","modified":"2026-05-14T07:17:00.663Z","1.0.0":"2026-01-25T04:06:11.327Z","1.0.1":"2026-01-28T05:11:03.755Z","1.0.2":"2026-05-14T07:17:00.505Z"},"license":"ISC","keywords":[],"description":"AWS Secrets Manager client package for Node.js applications. Provides an easy-to-use interface for retrieving secrets from AWS Secrets Manager.","maintainers":[{"name":"developer-at","email":"abhishektyagi199816@gmail.com"},{"name":"abhishek.tyagi1","email":"abhishek.tyagi1@appinventiv.com"}],"readme":"# @developer-at/aws-secret-manager\n\nAWS Secrets Manager client package for Node.js applications. Provides an easy-to-use interface for retrieving secrets from AWS Secrets Manager.\n\n## Installation\n\n```bash\nnpm install @developer-at/aws-secret-manager\n```\n\n## Features\n\n- Simple API for loading and retrieving secrets\n- Automatic AWS SDK client initialization\n- **Fallback:** `setSecretsFromJson()` to load secrets from a local JSON object or string (dev / offline / backup)\n- TypeScript support\n- Error handling\n\n## Prerequisites\n\n- AWS account with Secrets Manager access\n- AWS credentials configured (via environment variables, IAM role, or AWS credentials file)\n- `AWS_REGION` environment variable set\n\n## AWS Setup\n\n1. Create a secret in AWS Secrets Manager\n2. Ensure your AWS credentials have permissions to access Secrets Manager\n3. Set the `AWS_REGION` environment variable\n\n### Required IAM Permissions\n\n```json\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\n        \"secretsmanager:GetSecretValue\",\n        \"secretsmanager:DescribeSecret\"\n      ],\n      \"Resource\": \"arn:aws:secretsmanager:*:*:secret:*\"\n    }\n  ]\n}\n```\n\n## Usage\n\n### Basic Setup\n\n```typescript\nimport { secret } from '@developer-at/aws-secret-manager';\n\n// Set AWS region (required)\nprocess.env.AWS_REGION = 'us-east-1';\n\n// Load secrets from AWS Secrets Manager\nawait secret.loadCreds('my-secret-name');\n\n// Retrieve a secret value\nconst dbPassword = secret.get('dbPassword');\nconst apiKey = secret.get('apiKey');\n\nconsole.log('Database Password:', dbPassword);\nconsole.log('API Key:', apiKey);\n```\n\n### Fallback: local JSON (`setSecretsFromJson`)\n\nWhen AWS is unavailable, for local development, or as a backup after `loadCreds` fails, you can assign the same key/value shape as your secret JSON **without** calling AWS:\n\n**From an object:**\n\n```typescript\nimport { secret } from '@developer-at/aws-secret-manager';\n\nsecret.setSecretsFromJson({\n  DB_HOST: 'localhost',\n  DB_PASSWORD: 'dev-only',\n  API_KEY: 'local-key'\n});\n\nconst host = secret.get('DB_HOST');\n```\n\n**From a JSON string:**\n\n```typescript\nsecret.setSecretsFromJson('{\"JWT_SECRET\":\"dev-secret\",\"API_KEY\":\"local\"}');\n```\n\n**Try AWS first, then fallback:**\n\n```typescript\ntry {\n  await secret.loadCreds('my-application-secrets');\n} catch {\n  secret.setSecretsFromJson({\n    DB_HOST: process.env.DB_HOST || 'localhost',\n    DB_PASSWORD: process.env.DB_PASSWORD || ''\n  });\n}\n```\n\nNotes:\n\n- Calling `setSecretsFromJson` **replaces** `this.secrets` for that singleton instance. If you later call `loadCreds` successfully, AWS values replace the fallback.\n- Invalid JSON string throws the same structured `SecretsManagerException` pattern as other operations (see Error Handling).\n- Non-object JSON (e.g. array or bare string) is rejected with a clear error.\n\n### Complete Example\n\n```typescript\nimport { secret } from '@developer-at/aws-secret-manager';\n\nasync function initializeApp() {\n  try {\n    // Load secrets from AWS\n    await secret.loadCreds('my-application-secrets');\n    \n    // Retrieve configuration values\n    const config = {\n      database: {\n        host: secret.get('DB_HOST'),\n        port: secret.get('DB_PORT'),\n        username: secret.get('DB_USERNAME'),\n        password: secret.get('DB_PASSWORD'),\n        name: secret.get('DB_NAME')\n      },\n      api: {\n        key: secret.get('API_KEY'),\n        secret: secret.get('API_SECRET')\n      },\n      jwt: {\n        secret: secret.get('JWT_SECRET')\n      }\n    };\n    \n    // Use configuration\n    console.log('Application configured successfully');\n    return config;\n    \n  } catch (error) {\n    console.error('Failed to load secrets:', error);\n    throw error;\n  }\n}\n\n// Initialize on application startup\ninitializeApp()\n  .then(() => {\n    console.log('App started');\n  })\n  .catch((error) => {\n    console.error('Failed to start app:', error);\n    process.exit(1);\n  });\n```\n\n### Express.js Integration Example\n\n```typescript\nimport express from 'express';\nimport { secret } from '@developer-at/aws-secret-manager';\n\nconst app = express();\n\n// Load secrets on startup\nasync function loadSecrets() {\n  try {\n    await secret.loadCreds(process.env.SECRET_NAME || 'my-app-secrets');\n    \n    // Access secrets throughout the application\n    const jwtSecret = secret.get('JWT_SECRET');\n    const dbConfig = {\n      host: secret.get('DB_HOST'),\n      password: secret.get('DB_PASSWORD')\n    };\n    \n    console.log('Secrets loaded successfully');\n  } catch (error) {\n    console.error('Failed to load secrets:', error);\n    process.exit(1);\n  }\n}\n\n// Initialize before starting server\nloadSecrets().then(() => {\n  app.listen(3000, () => {\n    console.log('Server started on port 3000');\n  });\n});\n```\n\n### Using AWSSecretManagerProvider Class Directly\n\n```typescript\nimport { AWSSecretManagerProvider } from '@developer-at/aws-secret-manager';\n\n// Create a custom instance\nconst customSecret = new AWSSecretManagerProvider();\n\n// Load and use secrets\nawait customSecret.loadCreds('my-custom-secret');\nconst value = customSecret.get('myKey');\n```\n\n## API Reference\n\n### `secret` (Singleton Instance)\n\nPre-configured secret manager instance ready to use.\n\n### `AWSSecretManagerProvider` Class\n\nMain secret manager provider class.\n\n#### `constructor()`\n\nInitializes a new AWS Secrets Manager provider instance. Automatically initializes the AWS SDK client.\n\n#### `initializeSecretManager()`\n\nInitializes the AWS Secrets Manager client. Called automatically in the constructor.\n\n#### `loadCreds(secretName: string)`\n\nLoads secrets from AWS Secrets Manager.\n\n**Parameters:**\n- `secretName` (string): Name or ARN of the secret in AWS Secrets Manager\n\n**Returns:**\n- `Promise<void>`\n\n**Throws:**\n- Error if secret cannot be loaded or parsed\n\n**Example:**\n```typescript\nawait secret.loadCreds('production/database/credentials');\n```\n\n#### `setSecretsFromJson(payload: Record<string, unknown> | string)`\n\nAssigns secrets from a plain object or a JSON string (fallback / local / offline). Same usage as `get()` after `loadCreds`.\n\n**Parameters:**\n\n- `payload` — Object of key/value pairs, or a JSON string that parses to a **non-null object** (not an array).\n\n**Returns:**\n\n- `void`\n\n**Throws:**\n\n- Structured error if the string is not valid JSON or does not parse to an object.\n\n**Example:**\n\n```typescript\nsecret.setSecretsFromJson({ API_KEY: 'local' });\n// or\nsecret.setSecretsFromJson('{\"API_KEY\":\"local\"}');\n```\n\n#### `get(key: string)`\n\nRetrieves a secret value by key.\n\n**Parameters:**\n- `key` (string): Key name in the secret JSON\n\n**Returns:**\n- `any`: Secret value or undefined if key not found\n\n**Example:**\n```typescript\nconst password = secret.get('password');\nconst config = secret.get('database');\n```\n\n## Secret Format\n\nSecrets in AWS Secrets Manager should be stored as JSON strings. For example:\n\n```json\n{\n  \"DB_HOST\": \"database.example.com\",\n  \"DB_PORT\": \"5432\",\n  \"DB_USERNAME\": \"admin\",\n  \"DB_PASSWORD\": \"secure-password\",\n  \"API_KEY\": \"api-key-12345\",\n  \"JWT_SECRET\": \"jwt-secret-key\"\n}\n```\n\n## Environment Variables\n\n- `AWS_REGION` (required): AWS region where your secrets are stored (e.g., `us-east-1`)\n\n## Error Handling\n\nThe package includes structured error handling with `SecretsManagerException` class. All errors are automatically categorized and returned in a consistent format:\n\n```typescript\nimport { secret, SecretsManagerException } from '@developer-at/aws-secret-manager';\n\ntry {\n    await secret.loadCreds('my-secret-name');\n} catch (error) {\n    if (error instanceof SecretsManagerException) {\n        const errorResponse = error.getError();\n        // Returns: { status: 404, data: { message, type, originalError, context, ... } }\n    }\n}\n```\n\nError types include: Connection, Authentication, Not Found, Validation, Timeout, Server, and Operation errors.\n\n## TypeScript Support\n\nThe package includes full TypeScript definitions and is written in TypeScript.\n\n## Dependencies\n\n- `@aws-sdk/client-secrets-manager`: ^3.972.0\n\n## Security Best Practices\n\n1. **Never commit secrets to version control**\n2. **Use IAM roles** when running on AWS infrastructure (EC2, ECS, Lambda)\n3. **Rotate secrets regularly** in AWS Secrets Manager\n4. **Use least privilege IAM policies** for Secrets Manager access\n5. **Load secrets at application startup** rather than on-demand\n6. **Don't log secret values** in your application logs\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"Unable to Connect Error\"**\n   - Verify AWS credentials are configured\n   - Check AWS_REGION environment variable is set\n   - Ensure IAM permissions are correct\n\n2. **\"Unable to Load credentials AWS Error\"**\n   - Verify secret name/ARN is correct\n   - Check secret exists in the specified region\n   - Ensure IAM user/role has `secretsmanager:GetSecretValue` permission\n\n3. **\"undefined\" when calling `get()`**\n   - Ensure `loadCreds()` or `setSecretsFromJson()` ran successfully\n   - Verify the key exists in the secret JSON\n   - Check key name spelling\n\n## License\n\nISC\n","readmeFilename":"README.md"}