aws-secrets-manager-env-loader 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 steel8rat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# aws-secrets-manager-env-loader
+
+Load a map of AWS Secrets Manager secrets into `process.env` at boot.
+
+- **Env wins.** An env var already set to a non-empty value is kept, not fetched.
+  Local dev supplies values via the environment and never calls AWS.
+- **Fail fast.** Missing secrets are fetched in parallel; if any fetch or JSON
+  parse fails, the call rejects and `process.env` is left unmodified. No
+  partial-load mode.
+- **JSON blobs.** A value is either a secret ID (whole `SecretString`) or
+  `{ secretId, key }` (one property of a JSON secret). Env vars sharing a
+  `secretId` fetch and parse it once.
+- **Peer dependency.** `@aws-sdk/client-secrets-manager` is not bundled; you
+  choose and upgrade the version. Same convention as
+  [`@aws-lambda-powertools/parameters`][powertools].
+
+[powertools]: https://www.npmjs.com/package/@aws-lambda-powertools/parameters
+
+## Install
+
+```sh
+npm install aws-secrets-manager-env-loader @aws-sdk/client-secrets-manager
+```
+
+The peer dependency (`>=3.0.0`) is only loaded when a fetch actually happens, so
+it can be skipped if every mapped var is always pre-set in the environment.
+
+## Usage
+
+```ts
+import { loadSecrets } from "aws-secrets-manager-env-loader";
+
+await loadSecrets({
+  secrets: {
+    CHAT_BOT_TOKEN: "example/internal/chat/bot-token/sample-service",
+    SERVICE_API_KEY: "example/internal/service/api-key/sample-service",
+  },
+});
+```
+
+Call it once and `await` it before the rest of the app reads those vars.
+
+### Ordering
+
+The loader reads `process.env` only — it does not parse `.env` files. For "env
+wins" to apply locally, the values must be in `process.env` *before* the call.
+Load them first:
+
+```sh
+node --env-file=.env dist/app.js
+```
+
+```ts
+import "dotenv/config"; // before importing anything that calls loadSecrets
+```
+
+Otherwise the var looks missing and the loader tries to fetch it (and throws
+without credentials).
+
+## API
+
+```ts
+function loadSecrets(options: LoadSecretsOptions): Promise<void>;
+
+interface LoadSecretsOptions {
+  secrets: Record<string, SecretSource>;
+  /**
+   * Pre-constructed client, for control over region, credentials, retry, or SDK
+   * version. Default: constructed lazily on first fetch (region from
+   * AWS_REGION, else us-east-1; default credential chain).
+   */
+  client?: SecretsManagerClient | SecretsManagerClientLike;
+  /** Progress messages. Default: console.log. Pass `() => {}` to silence. */
+  onLog?: (message: string) => void;
+}
+
+type SecretSource =
+  | string                              // secret ID; whole SecretString
+  | { secretId: string; key?: string }; // one key of a JSON secret
+```
+
+Supplying a client:
+
+```ts
+import { SecretsManagerClient } from "@aws-sdk/client-secrets-manager";
+
+await loadSecrets({
+  secrets: { SERVICE_API_KEY: "example/internal/service/api-key/sample-service" },
+  client: new SecretsManagerClient({ region: "eu-west-1", maxAttempts: 5 }),
+});
+```
+
+### JSON-blob secrets
+
+For a secret holding a JSON object (the console's key/value editor, RDS-managed
+secrets), point multiple vars at keys of one `secretId`:
+
+```ts
+await loadSecrets({
+  secrets: {
+    DB_USERNAME: { secretId: "example/db/creds", key: "username" },
+    DB_PASSWORD: { secretId: "example/db/creds", key: "password" },
+    DB_PORT:     { secretId: "example/db/creds", key: "port" }, // 5432 -> "5432"
+    SERVICE_API_KEY: "example/internal/service/api-key/sample-service",
+  },
+});
+```
+
+Non-string values are `JSON.stringify`-d before writing.
+
+### Semantics
+
+| Case | Behavior |
+| --- | --- |
+| Env var set to a non-empty value | Kept; not fetched or parsed |
+| Env var unset or empty string | Fetched and written |
+| Several env vars, one `secretId` | Fetched once, parsed once, in parallel with other secrets |
+| Any fetch or JSON parse fails | Call rejects; `process.env` unmodified |
+| Secret has no `SecretString` | `MissingSecretStringError` |
+| Keyed source, key not in the JSON object | `SecretKeyNotFoundError` |
+| Keyed source, `SecretString` not a JSON object | `SecretJsonParseError` |
+| Default client needed, peer dep not installed | `SdkNotInstalledError` |
+| Nothing missing | Returns immediately; SDK not loaded |
+
+Exports: `loadSecrets`, `MissingSecretStringError`, `SecretJsonParseError`,
+`SecretKeyNotFoundError`, `SdkNotInstalledError`, and the types
+`LoadSecretsOptions`, `SecretSource`, `SecretsManagerClientLike`.
+
+## Development
+
+```sh
+npm install
+npm run typecheck
+npm test          # node --test
+npm run build     # tsup -> dist/ (ESM + CJS + .d.ts)
+```
+
+Tests use Node's runner with native type stripping (Node >=22.18 / >=23.6). The
+published package is compiled JavaScript and requires Node >=18.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,197 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MissingSecretStringError: () => MissingSecretStringError,
+  SdkNotInstalledError: () => SdkNotInstalledError,
+  SecretJsonParseError: () => SecretJsonParseError,
+  SecretKeyNotFoundError: () => SecretKeyNotFoundError,
+  loadSecrets: () => loadSecrets
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/sdk.ts
+var SdkNotInstalledError = class extends Error {
+  constructor(cause) {
+    super(
+      `aws-secrets-manager-env-loader: could not load '@aws-sdk/client-secrets-manager'. It is a peer dependency - install it in your app to use the default client, or pass an explicit \`client\`. (If every mapped env var is already set, no fetch happens and the SDK is never needed.) Underlying error: ${cause instanceof Error ? cause.message : String(cause)}`,
+      { cause }
+    );
+    this.name = "SdkNotInstalledError";
+  }
+};
+var realImport = () => import("@aws-sdk/client-secrets-manager");
+var importSdk = realImport;
+var sdkPromise;
+var defaultClientPromise;
+async function loadSdk() {
+  if (!sdkPromise) {
+    sdkPromise = importSdk().catch((err) => {
+      sdkPromise = void 0;
+      throw new SdkNotInstalledError(err);
+    });
+  }
+  return sdkPromise;
+}
+async function getDefaultClient() {
+  if (!defaultClientPromise) {
+    defaultClientPromise = (async () => {
+      const { SecretsManagerClient } = await loadSdk();
+      return new SecretsManagerClient({
+        region: process.env.AWS_REGION ?? "us-east-1"
+      });
+    })().catch((err) => {
+      defaultClientPromise = void 0;
+      throw err;
+    });
+  }
+  return defaultClientPromise;
+}
+
+// src/index.ts
+var MissingSecretStringError = class extends Error {
+  secretId;
+  constructor(secretId) {
+    super(
+      `aws-secrets-manager-env-loader: secret "${secretId}" has no SecretString`
+    );
+    this.name = "MissingSecretStringError";
+    this.secretId = secretId;
+  }
+};
+var SecretJsonParseError = class extends Error {
+  secretId;
+  constructor(secretId, cause) {
+    super(
+      `aws-secrets-manager-env-loader: secret "${secretId}" is not a JSON object`,
+      { cause }
+    );
+    this.name = "SecretJsonParseError";
+    this.secretId = secretId;
+  }
+};
+var SecretKeyNotFoundError = class extends Error {
+  secretId;
+  key;
+  envVar;
+  constructor(secretId, key, envVar) {
+    super(
+      `aws-secrets-manager-env-loader: key "${key}" (for env var ${envVar}) is not present in JSON secret "${secretId}"`
+    );
+    this.name = "SecretKeyNotFoundError";
+    this.secretId = secretId;
+    this.key = key;
+    this.envVar = envVar;
+  }
+};
+async function loadSecrets(options) {
+  const { secrets, onLog = defaultLog } = options;
+  const missing = Object.keys(secrets).filter(
+    (envVar) => !process.env[envVar]
+  );
+  if (missing.length === 0) {
+    onLog("[secrets] all secrets already in env, skipping fetch");
+    return;
+  }
+  onLog(`[secrets] fetching from Secrets Manager: ${missing.join(", ")}`);
+  const { GetSecretValueCommand } = await loadSdk();
+  const client = options.client ?? await getDefaultClient();
+  const sources = new Map(
+    missing.map((envVar) => [envVar, normalize(secrets[envVar])])
+  );
+  const distinctIds = [
+    ...new Set([...sources.values()].map((source) => source.secretId))
+  ];
+  const rawById = /* @__PURE__ */ new Map();
+  await Promise.all(
+    distinctIds.map(async (secretId) => {
+      const res = await client.send(
+        new GetSecretValueCommand({ SecretId: secretId })
+      );
+      if (!res.SecretString) throw new MissingSecretStringError(secretId);
+      rawById.set(secretId, res.SecretString);
+    })
+  );
+  const jsonById = /* @__PURE__ */ new Map();
+  const parseJsonSecret = (secretId) => {
+    const cached = jsonById.get(secretId);
+    if (cached) return cached;
+    let value;
+    try {
+      value = JSON.parse(rawById.get(secretId));
+    } catch (err) {
+      throw new SecretJsonParseError(secretId, err);
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      throw new SecretJsonParseError(
+        secretId,
+        new Error("SecretString is not a JSON object")
+      );
+    }
+    const parsed = value;
+    jsonById.set(secretId, parsed);
+    return parsed;
+  };
+  const resolved = missing.map((envVar) => {
+    const { secretId, key } = sources.get(envVar);
+    if (key === void 0) {
+      return [envVar, rawById.get(secretId)];
+    }
+    const parsed = parseJsonSecret(secretId);
+    if (!(key in parsed)) {
+      throw new SecretKeyNotFoundError(secretId, key, envVar);
+    }
+    const value = parsed[key];
+    return [
+      envVar,
+      typeof value === "string" ? value : JSON.stringify(value)
+    ];
+  });
+  for (const [envVar, value] of resolved) {
+    process.env[envVar] = value;
+  }
+  onLog(`[secrets] provisioned into env: ${missing.join(", ")}`);
+}
+function normalize(source) {
+  return typeof source === "string" ? { secretId: source } : source;
+}
+function defaultLog(message) {
+  console.log(message);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MissingSecretStringError,
+  SdkNotInstalledError,
+  SecretJsonParseError,
+  SecretKeyNotFoundError,
+  loadSecrets
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/sdk.ts"],"sourcesContent":["import type { SecretsManagerClient } from \"@aws-sdk/client-secrets-manager\";\nimport { getDefaultClient, loadSdk, SdkNotInstalledError } from \"./sdk.ts\";\n\nexport { SdkNotInstalledError };\n\n/**\n * The minimal shape this package needs from a Secrets Manager client: a `send`\n * method that resolves a `GetSecretValueCommand` to something carrying a\n * `SecretString`. The real `SecretsManagerClient` satisfies this, and so does\n * any stub with a compatible `send` (handy for tests).\n */\nexport interface SecretsManagerClientLike {\n  send(command: unknown): Promise<{ SecretString?: string }>;\n}\n\n/**\n * How to source one env var's value:\n *\n * - a plain **string** is a Secrets Manager secret ID whose entire\n *   `SecretString` becomes the value;\n * - **`{ secretId, key }`** fetches `secretId`, parses its `SecretString` as a\n *   JSON object, and writes property `key` (non-string values are\n *   `JSON.stringify`-d). Several env vars may read different keys of the same\n *   `secretId` - it is fetched and parsed exactly once.\n */\nexport type SecretSource =\n  | string\n  | {\n      /** Secrets Manager secret ID. */\n      secretId: string;\n      /**\n       * Property to read from the secret's JSON object. Omit to use the whole\n       * `SecretString` verbatim.\n       */\n      key?: string;\n    };\n\nexport interface LoadSecretsOptions {\n  /**\n   * Map of env var name -> where to get its value. See {@link SecretSource}.\n   *\n   * @example\n   * {\n   *   // whole SecretString\n   *   SERVICE_API_KEY: \"example/internal/service/api-key/sample-service\",\n   *   // two keys out of one JSON secret, fetched once\n   *   DB_USERNAME: { secretId: \"example/db/creds\", key: \"username\" },\n   *   DB_PASSWORD: { secretId: \"example/db/creds\", key: \"password\" },\n   * }\n   */\n  secrets: Record<string, SecretSource>;\n  /**\n   * Pre-constructed client. Supply this to control region, credentials,\n   * retry/backoff, or the exact SDK version in play. If omitted, a\n   * `SecretsManagerClient` is constructed lazily on first fetch (region from\n   * `AWS_REGION`, else `us-east-1`; default credential chain).\n   */\n  client?: SecretsManagerClient | SecretsManagerClientLike;\n  /**\n   * Called with human-readable progress messages. Defaults to `console.log`.\n   * Pass `() => {}` to silence, or route through your own logger.\n   */\n  onLog?: (message: string) => void;\n}\n\n/** Thrown when a fetched secret exists but carries no `SecretString`. */\nexport class MissingSecretStringError extends Error {\n  readonly secretId: string;\n  constructor(secretId: string) {\n    super(\n      `aws-secrets-manager-env-loader: secret \"${secretId}\" has no SecretString`,\n    );\n    this.name = \"MissingSecretStringError\";\n    this.secretId = secretId;\n  }\n}\n\n/** Thrown when a keyed source points at a secret whose `SecretString` is not a JSON object. */\nexport class SecretJsonParseError extends Error {\n  readonly secretId: string;\n  constructor(secretId: string, cause: unknown) {\n    super(\n      `aws-secrets-manager-env-loader: secret \"${secretId}\" is not a JSON object`,\n      { cause },\n    );\n    this.name = \"SecretJsonParseError\";\n    this.secretId = secretId;\n  }\n}\n\n/** Thrown when a keyed source names a property missing from the secret's JSON object. */\nexport class SecretKeyNotFoundError extends Error {\n  readonly secretId: string;\n  readonly key: string;\n  readonly envVar: string;\n  constructor(secretId: string, key: string, envVar: string) {\n    super(\n      `aws-secrets-manager-env-loader: key \"${key}\" (for env var ${envVar}) is not present in JSON secret \"${secretId}\"`,\n    );\n    this.name = \"SecretKeyNotFoundError\";\n    this.secretId = secretId;\n    this.key = key;\n    this.envVar = envVar;\n  }\n}\n\n/**\n * Load the mapped secrets into `process.env`.\n *\n * - Env vars already set to a non-empty value are kept and never fetched. Only\n *   `process.env` is consulted; `.env` files must be loaded beforehand.\n * - Each distinct secret ID is fetched once, in parallel, even when several env\n *   vars read different keys from it.\n * - `Promise.all` semantics: any failed fetch or JSON parse rejects the whole\n *   call and leaves `process.env` unmodified. No partial-load mode.\n */\nexport async function loadSecrets(options: LoadSecretsOptions): Promise<void> {\n  const { secrets, onLog = defaultLog } = options;\n\n  const missing = Object.keys(secrets).filter(\n    (envVar) => !process.env[envVar],\n  );\n  if (missing.length === 0) {\n    onLog(\"[secrets] all secrets already in env, skipping fetch\");\n    return;\n  }\n\n  onLog(`[secrets] fetching from Secrets Manager: ${missing.join(\", \")}`);\n\n  const { GetSecretValueCommand } = await loadSdk();\n  const client = options.client ?? (await getDefaultClient());\n\n  const sources = new Map(\n    missing.map((envVar) => [envVar, normalize(secrets[envVar]!)] as const),\n  );\n  const distinctIds = [\n    ...new Set([...sources.values()].map((source) => source.secretId)),\n  ];\n\n  const rawById = new Map<string, string>();\n  await Promise.all(\n    distinctIds.map(async (secretId) => {\n      const res = await client.send(\n        new GetSecretValueCommand({ SecretId: secretId }),\n      );\n      if (!res.SecretString) throw new MissingSecretStringError(secretId);\n      rawById.set(secretId, res.SecretString);\n    }),\n  );\n\n  const jsonById = new Map<string, Record<string, unknown>>();\n  const parseJsonSecret = (secretId: string): Record<string, unknown> => {\n    const cached = jsonById.get(secretId);\n    if (cached) return cached;\n    let value: unknown;\n    try {\n      value = JSON.parse(rawById.get(secretId)!);\n    } catch (err) {\n      throw new SecretJsonParseError(secretId, err);\n    }\n    if (value === null || typeof value !== \"object\" || Array.isArray(value)) {\n      throw new SecretJsonParseError(\n        secretId,\n        new Error(\"SecretString is not a JSON object\"),\n      );\n    }\n    const parsed = value as Record<string, unknown>;\n    jsonById.set(secretId, parsed);\n    return parsed;\n  };\n\n  const resolved = missing.map((envVar) => {\n    const { secretId, key } = sources.get(envVar)!;\n    if (key === undefined) {\n      return [envVar, rawById.get(secretId)!] as const;\n    }\n    const parsed = parseJsonSecret(secretId);\n    if (!(key in parsed)) {\n      throw new SecretKeyNotFoundError(secretId, key, envVar);\n    }\n    const value = parsed[key];\n    return [\n      envVar,\n      typeof value === \"string\" ? value : JSON.stringify(value),\n    ] as const;\n  });\n\n  for (const [envVar, value] of resolved) {\n    process.env[envVar] = value;\n  }\n  onLog(`[secrets] provisioned into env: ${missing.join(\", \")}`);\n}\n\nfunction normalize(source: SecretSource): { secretId: string; key?: string } {\n  return typeof source === \"string\" ? { secretId: source } : source;\n}\n\nfunction defaultLog(message: string): void {\n  console.log(message);\n}\n","import type { SecretsManagerClient } from \"@aws-sdk/client-secrets-manager\";\n\n/** Thrown when the AWS SDK client peer dependency cannot be resolved at runtime. */\nexport class SdkNotInstalledError extends Error {\n  constructor(cause: unknown) {\n    super(\n      \"aws-secrets-manager-env-loader: could not load '@aws-sdk/client-secrets-manager'. \" +\n        \"It is a peer dependency - install it in your app to use the default client, \" +\n        \"or pass an explicit `client`. (If every mapped env var is already set, no fetch \" +\n        \"happens and the SDK is never needed.) \" +\n        `Underlying error: ${cause instanceof Error ? cause.message : String(cause)}`,\n      { cause },\n    );\n    this.name = \"SdkNotInstalledError\";\n  }\n}\n\nexport type SecretsManagerSdk = typeof import(\"@aws-sdk/client-secrets-manager\");\n\nconst realImport = (): Promise<SecretsManagerSdk> =>\n  import(\"@aws-sdk/client-secrets-manager\");\n\nlet importSdk: () => Promise<SecretsManagerSdk> = realImport;\nlet sdkPromise: Promise<SecretsManagerSdk> | undefined;\nlet defaultClientPromise: Promise<SecretsManagerClient> | undefined;\n\n/**\n * Load `@aws-sdk/client-secrets-manager` lazily and only once. Kept out of\n * module scope so that importing this package never requires the peer\n * dependency - only an actual fetch does.\n */\nexport async function loadSdk(): Promise<SecretsManagerSdk> {\n  if (!sdkPromise) {\n    sdkPromise = importSdk().catch((err: unknown) => {\n      sdkPromise = undefined;\n      throw new SdkNotInstalledError(err);\n    });\n  }\n  return sdkPromise;\n}\n\n/**\n * A `SecretsManagerClient` constructed lazily on first use, with its region from\n * `AWS_REGION` (falling back to `us-east-1`) and default-chain credentials.\n */\nexport async function getDefaultClient(): Promise<SecretsManagerClient> {\n  if (!defaultClientPromise) {\n    defaultClientPromise = (async () => {\n      const { SecretsManagerClient } = await loadSdk();\n      return new SecretsManagerClient({\n        region: process.env.AWS_REGION ?? \"us-east-1\",\n      });\n    })().catch((err: unknown) => {\n      defaultClientPromise = undefined;\n      throw err;\n    });\n  }\n  return defaultClientPromise;\n}\n\n/**\n * Test seam. Deliberately NOT re-exported from `index.ts`, so it never reaches\n * the published entry point or type definitions. Swaps how the AWS SDK is\n * imported and clears the memoized SDK + default client. Pass `undefined` to\n * restore the real dynamic import.\n *\n * @internal\n */\nexport function __setSdkImporterForTests(\n  fn: (() => Promise<SecretsManagerSdk>) | undefined,\n): void {\n  importSdk = fn ?? realImport;\n  sdkPromise = undefined;\n  defaultClientPromise = undefined;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,94 @@
+import { SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
+
+/** Thrown when the AWS SDK client peer dependency cannot be resolved at runtime. */
+declare class SdkNotInstalledError extends Error {
+    constructor(cause: unknown);
+}
+
+/**
+ * The minimal shape this package needs from a Secrets Manager client: a `send`
+ * method that resolves a `GetSecretValueCommand` to something carrying a
+ * `SecretString`. The real `SecretsManagerClient` satisfies this, and so does
+ * any stub with a compatible `send` (handy for tests).
+ */
+interface SecretsManagerClientLike {
+    send(command: unknown): Promise<{
+        SecretString?: string;
+    }>;
+}
+/**
+ * How to source one env var's value:
+ *
+ * - a plain **string** is a Secrets Manager secret ID whose entire
+ *   `SecretString` becomes the value;
+ * - **`{ secretId, key }`** fetches `secretId`, parses its `SecretString` as a
+ *   JSON object, and writes property `key` (non-string values are
+ *   `JSON.stringify`-d). Several env vars may read different keys of the same
+ *   `secretId` - it is fetched and parsed exactly once.
+ */
+type SecretSource = string | {
+    /** Secrets Manager secret ID. */
+    secretId: string;
+    /**
+     * Property to read from the secret's JSON object. Omit to use the whole
+     * `SecretString` verbatim.
+     */
+    key?: string;
+};
+interface LoadSecretsOptions {
+    /**
+     * Map of env var name -> where to get its value. See {@link SecretSource}.
+     *
+     * @example
+     * {
+     *   // whole SecretString
+     *   SERVICE_API_KEY: "example/internal/service/api-key/sample-service",
+     *   // two keys out of one JSON secret, fetched once
+     *   DB_USERNAME: { secretId: "example/db/creds", key: "username" },
+     *   DB_PASSWORD: { secretId: "example/db/creds", key: "password" },
+     * }
+     */
+    secrets: Record<string, SecretSource>;
+    /**
+     * Pre-constructed client. Supply this to control region, credentials,
+     * retry/backoff, or the exact SDK version in play. If omitted, a
+     * `SecretsManagerClient` is constructed lazily on first fetch (region from
+     * `AWS_REGION`, else `us-east-1`; default credential chain).
+     */
+    client?: SecretsManagerClient | SecretsManagerClientLike;
+    /**
+     * Called with human-readable progress messages. Defaults to `console.log`.
+     * Pass `() => {}` to silence, or route through your own logger.
+     */
+    onLog?: (message: string) => void;
+}
+/** Thrown when a fetched secret exists but carries no `SecretString`. */
+declare class MissingSecretStringError extends Error {
+    readonly secretId: string;
+    constructor(secretId: string);
+}
+/** Thrown when a keyed source points at a secret whose `SecretString` is not a JSON object. */
+declare class SecretJsonParseError extends Error {
+    readonly secretId: string;
+    constructor(secretId: string, cause: unknown);
+}
+/** Thrown when a keyed source names a property missing from the secret's JSON object. */
+declare class SecretKeyNotFoundError extends Error {
+    readonly secretId: string;
+    readonly key: string;
+    readonly envVar: string;
+    constructor(secretId: string, key: string, envVar: string);
+}
+/**
+ * Load the mapped secrets into `process.env`.
+ *
+ * - Env vars already set to a non-empty value are kept and never fetched. Only
+ *   `process.env` is consulted; `.env` files must be loaded beforehand.
+ * - Each distinct secret ID is fetched once, in parallel, even when several env
+ *   vars read different keys from it.
+ * - `Promise.all` semantics: any failed fetch or JSON parse rejects the whole
+ *   call and leaves `process.env` unmodified. No partial-load mode.
+ */
+declare function loadSecrets(options: LoadSecretsOptions): Promise<void>;
+
+export { type LoadSecretsOptions, MissingSecretStringError, SdkNotInstalledError, SecretJsonParseError, SecretKeyNotFoundError, type SecretSource, type SecretsManagerClientLike, loadSecrets };

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+import { SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
+
+/** Thrown when the AWS SDK client peer dependency cannot be resolved at runtime. */
+declare class SdkNotInstalledError extends Error {
+    constructor(cause: unknown);
+}
+
+/**
+ * The minimal shape this package needs from a Secrets Manager client: a `send`
+ * method that resolves a `GetSecretValueCommand` to something carrying a
+ * `SecretString`. The real `SecretsManagerClient` satisfies this, and so does
+ * any stub with a compatible `send` (handy for tests).
+ */
+interface SecretsManagerClientLike {
+    send(command: unknown): Promise<{
+        SecretString?: string;
+    }>;
+}
+/**
+ * How to source one env var's value:
+ *
+ * - a plain **string** is a Secrets Manager secret ID whose entire
+ *   `SecretString` becomes the value;
+ * - **`{ secretId, key }`** fetches `secretId`, parses its `SecretString` as a
+ *   JSON object, and writes property `key` (non-string values are
+ *   `JSON.stringify`-d). Several env vars may read different keys of the same
+ *   `secretId` - it is fetched and parsed exactly once.
+ */
+type SecretSource = string | {
+    /** Secrets Manager secret ID. */
+    secretId: string;
+    /**
+     * Property to read from the secret's JSON object. Omit to use the whole
+     * `SecretString` verbatim.
+     */
+    key?: string;
+};
+interface LoadSecretsOptions {
+    /**
+     * Map of env var name -> where to get its value. See {@link SecretSource}.
+     *
+     * @example
+     * {
+     *   // whole SecretString
+     *   SERVICE_API_KEY: "example/internal/service/api-key/sample-service",
+     *   // two keys out of one JSON secret, fetched once
+     *   DB_USERNAME: { secretId: "example/db/creds", key: "username" },
+     *   DB_PASSWORD: { secretId: "example/db/creds", key: "password" },
+     * }
+     */
+    secrets: Record<string, SecretSource>;
+    /**
+     * Pre-constructed client. Supply this to control region, credentials,
+     * retry/backoff, or the exact SDK version in play. If omitted, a
+     * `SecretsManagerClient` is constructed lazily on first fetch (region from
+     * `AWS_REGION`, else `us-east-1`; default credential chain).
+     */
+    client?: SecretsManagerClient | SecretsManagerClientLike;
+    /**
+     * Called with human-readable progress messages. Defaults to `console.log`.
+     * Pass `() => {}` to silence, or route through your own logger.
+     */
+    onLog?: (message: string) => void;
+}
+/** Thrown when a fetched secret exists but carries no `SecretString`. */
+declare class MissingSecretStringError extends Error {
+    readonly secretId: string;
+    constructor(secretId: string);
+}
+/** Thrown when a keyed source points at a secret whose `SecretString` is not a JSON object. */
+declare class SecretJsonParseError extends Error {
+    readonly secretId: string;
+    constructor(secretId: string, cause: unknown);
+}
+/** Thrown when a keyed source names a property missing from the secret's JSON object. */
+declare class SecretKeyNotFoundError extends Error {
+    readonly secretId: string;
+    readonly key: string;
+    readonly envVar: string;
+    constructor(secretId: string, key: string, envVar: string);
+}
+/**
+ * Load the mapped secrets into `process.env`.
+ *
+ * - Env vars already set to a non-empty value are kept and never fetched. Only
+ *   `process.env` is consulted; `.env` files must be loaded beforehand.
+ * - Each distinct secret ID is fetched once, in parallel, even when several env
+ *   vars read different keys from it.
+ * - `Promise.all` semantics: any failed fetch or JSON parse rejects the whole
+ *   call and leaves `process.env` unmodified. No partial-load mode.
+ */
+declare function loadSecrets(options: LoadSecretsOptions): Promise<void>;
+
+export { type LoadSecretsOptions, MissingSecretStringError, SdkNotInstalledError, SecretJsonParseError, SecretKeyNotFoundError, type SecretSource, type SecretsManagerClientLike, loadSecrets };

package/dist/index.js

@@ -0,0 +1,156 @@
+// src/sdk.ts
+var SdkNotInstalledError = class extends Error {
+  constructor(cause) {
+    super(
+      `aws-secrets-manager-env-loader: could not load '@aws-sdk/client-secrets-manager'. It is a peer dependency - install it in your app to use the default client, or pass an explicit \`client\`. (If every mapped env var is already set, no fetch happens and the SDK is never needed.) Underlying error: ${cause instanceof Error ? cause.message : String(cause)}`,
+      { cause }
+    );
+    this.name = "SdkNotInstalledError";
+  }
+};
+var realImport = () => import("@aws-sdk/client-secrets-manager");
+var importSdk = realImport;
+var sdkPromise;
+var defaultClientPromise;
+async function loadSdk() {
+  if (!sdkPromise) {
+    sdkPromise = importSdk().catch((err) => {
+      sdkPromise = void 0;
+      throw new SdkNotInstalledError(err);
+    });
+  }
+  return sdkPromise;
+}
+async function getDefaultClient() {
+  if (!defaultClientPromise) {
+    defaultClientPromise = (async () => {
+      const { SecretsManagerClient } = await loadSdk();
+      return new SecretsManagerClient({
+        region: process.env.AWS_REGION ?? "us-east-1"
+      });
+    })().catch((err) => {
+      defaultClientPromise = void 0;
+      throw err;
+    });
+  }
+  return defaultClientPromise;
+}
+
+// src/index.ts
+var MissingSecretStringError = class extends Error {
+  secretId;
+  constructor(secretId) {
+    super(
+      `aws-secrets-manager-env-loader: secret "${secretId}" has no SecretString`
+    );
+    this.name = "MissingSecretStringError";
+    this.secretId = secretId;
+  }
+};
+var SecretJsonParseError = class extends Error {
+  secretId;
+  constructor(secretId, cause) {
+    super(
+      `aws-secrets-manager-env-loader: secret "${secretId}" is not a JSON object`,
+      { cause }
+    );
+    this.name = "SecretJsonParseError";
+    this.secretId = secretId;
+  }
+};
+var SecretKeyNotFoundError = class extends Error {
+  secretId;
+  key;
+  envVar;
+  constructor(secretId, key, envVar) {
+    super(
+      `aws-secrets-manager-env-loader: key "${key}" (for env var ${envVar}) is not present in JSON secret "${secretId}"`
+    );
+    this.name = "SecretKeyNotFoundError";
+    this.secretId = secretId;
+    this.key = key;
+    this.envVar = envVar;
+  }
+};
+async function loadSecrets(options) {
+  const { secrets, onLog = defaultLog } = options;
+  const missing = Object.keys(secrets).filter(
+    (envVar) => !process.env[envVar]
+  );
+  if (missing.length === 0) {
+    onLog("[secrets] all secrets already in env, skipping fetch");
+    return;
+  }
+  onLog(`[secrets] fetching from Secrets Manager: ${missing.join(", ")}`);
+  const { GetSecretValueCommand } = await loadSdk();
+  const client = options.client ?? await getDefaultClient();
+  const sources = new Map(
+    missing.map((envVar) => [envVar, normalize(secrets[envVar])])
+  );
+  const distinctIds = [
+    ...new Set([...sources.values()].map((source) => source.secretId))
+  ];
+  const rawById = /* @__PURE__ */ new Map();
+  await Promise.all(
+    distinctIds.map(async (secretId) => {
+      const res = await client.send(
+        new GetSecretValueCommand({ SecretId: secretId })
+      );
+      if (!res.SecretString) throw new MissingSecretStringError(secretId);
+      rawById.set(secretId, res.SecretString);
+    })
+  );
+  const jsonById = /* @__PURE__ */ new Map();
+  const parseJsonSecret = (secretId) => {
+    const cached = jsonById.get(secretId);
+    if (cached) return cached;
+    let value;
+    try {
+      value = JSON.parse(rawById.get(secretId));
+    } catch (err) {
+      throw new SecretJsonParseError(secretId, err);
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      throw new SecretJsonParseError(
+        secretId,
+        new Error("SecretString is not a JSON object")
+      );
+    }
+    const parsed = value;
+    jsonById.set(secretId, parsed);
+    return parsed;
+  };
+  const resolved = missing.map((envVar) => {
+    const { secretId, key } = sources.get(envVar);
+    if (key === void 0) {
+      return [envVar, rawById.get(secretId)];
+    }
+    const parsed = parseJsonSecret(secretId);
+    if (!(key in parsed)) {
+      throw new SecretKeyNotFoundError(secretId, key, envVar);
+    }
+    const value = parsed[key];
+    return [
+      envVar,
+      typeof value === "string" ? value : JSON.stringify(value)
+    ];
+  });
+  for (const [envVar, value] of resolved) {
+    process.env[envVar] = value;
+  }
+  onLog(`[secrets] provisioned into env: ${missing.join(", ")}`);
+}
+function normalize(source) {
+  return typeof source === "string" ? { secretId: source } : source;
+}
+function defaultLog(message) {
+  console.log(message);
+}
+export {
+  MissingSecretStringError,
+  SdkNotInstalledError,
+  SecretJsonParseError,
+  SecretKeyNotFoundError,
+  loadSecrets
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sdk.ts","../src/index.ts"],"sourcesContent":["import type { SecretsManagerClient } from \"@aws-sdk/client-secrets-manager\";\n\n/** Thrown when the AWS SDK client peer dependency cannot be resolved at runtime. */\nexport class SdkNotInstalledError extends Error {\n  constructor(cause: unknown) {\n    super(\n      \"aws-secrets-manager-env-loader: could not load '@aws-sdk/client-secrets-manager'. \" +\n        \"It is a peer dependency - install it in your app to use the default client, \" +\n        \"or pass an explicit `client`. (If every mapped env var is already set, no fetch \" +\n        \"happens and the SDK is never needed.) \" +\n        `Underlying error: ${cause instanceof Error ? cause.message : String(cause)}`,\n      { cause },\n    );\n    this.name = \"SdkNotInstalledError\";\n  }\n}\n\nexport type SecretsManagerSdk = typeof import(\"@aws-sdk/client-secrets-manager\");\n\nconst realImport = (): Promise<SecretsManagerSdk> =>\n  import(\"@aws-sdk/client-secrets-manager\");\n\nlet importSdk: () => Promise<SecretsManagerSdk> = realImport;\nlet sdkPromise: Promise<SecretsManagerSdk> | undefined;\nlet defaultClientPromise: Promise<SecretsManagerClient> | undefined;\n\n/**\n * Load `@aws-sdk/client-secrets-manager` lazily and only once. Kept out of\n * module scope so that importing this package never requires the peer\n * dependency - only an actual fetch does.\n */\nexport async function loadSdk(): Promise<SecretsManagerSdk> {\n  if (!sdkPromise) {\n    sdkPromise = importSdk().catch((err: unknown) => {\n      sdkPromise = undefined;\n      throw new SdkNotInstalledError(err);\n    });\n  }\n  return sdkPromise;\n}\n\n/**\n * A `SecretsManagerClient` constructed lazily on first use, with its region from\n * `AWS_REGION` (falling back to `us-east-1`) and default-chain credentials.\n */\nexport async function getDefaultClient(): Promise<SecretsManagerClient> {\n  if (!defaultClientPromise) {\n    defaultClientPromise = (async () => {\n      const { SecretsManagerClient } = await loadSdk();\n      return new SecretsManagerClient({\n        region: process.env.AWS_REGION ?? \"us-east-1\",\n      });\n    })().catch((err: unknown) => {\n      defaultClientPromise = undefined;\n      throw err;\n    });\n  }\n  return defaultClientPromise;\n}\n\n/**\n * Test seam. Deliberately NOT re-exported from `index.ts`, so it never reaches\n * the published entry point or type definitions. Swaps how the AWS SDK is\n * imported and clears the memoized SDK + default client. Pass `undefined` to\n * restore the real dynamic import.\n *\n * @internal\n */\nexport function __setSdkImporterForTests(\n  fn: (() => Promise<SecretsManagerSdk>) | undefined,\n): void {\n  importSdk = fn ?? realImport;\n  sdkPromise = undefined;\n  defaultClientPromise = undefined;\n}\n","import type { SecretsManagerClient } from \"@aws-sdk/client-secrets-manager\";\nimport { getDefaultClient, loadSdk, SdkNotInstalledError } from \"./sdk.ts\";\n\nexport { SdkNotInstalledError };\n\n/**\n * The minimal shape this package needs from a Secrets Manager client: a `send`\n * method that resolves a `GetSecretValueCommand` to something carrying a\n * `SecretString`. The real `SecretsManagerClient` satisfies this, and so does\n * any stub with a compatible `send` (handy for tests).\n */\nexport interface SecretsManagerClientLike {\n  send(command: unknown): Promise<{ SecretString?: string }>;\n}\n\n/**\n * How to source one env var's value:\n *\n * - a plain **string** is a Secrets Manager secret ID whose entire\n *   `SecretString` becomes the value;\n * - **`{ secretId, key }`** fetches `secretId`, parses its `SecretString` as a\n *   JSON object, and writes property `key` (non-string values are\n *   `JSON.stringify`-d). Several env vars may read different keys of the same\n *   `secretId` - it is fetched and parsed exactly once.\n */\nexport type SecretSource =\n  | string\n  | {\n      /** Secrets Manager secret ID. */\n      secretId: string;\n      /**\n       * Property to read from the secret's JSON object. Omit to use the whole\n       * `SecretString` verbatim.\n       */\n      key?: string;\n    };\n\nexport interface LoadSecretsOptions {\n  /**\n   * Map of env var name -> where to get its value. See {@link SecretSource}.\n   *\n   * @example\n   * {\n   *   // whole SecretString\n   *   SERVICE_API_KEY: \"example/internal/service/api-key/sample-service\",\n   *   // two keys out of one JSON secret, fetched once\n   *   DB_USERNAME: { secretId: \"example/db/creds\", key: \"username\" },\n   *   DB_PASSWORD: { secretId: \"example/db/creds\", key: \"password\" },\n   * }\n   */\n  secrets: Record<string, SecretSource>;\n  /**\n   * Pre-constructed client. Supply this to control region, credentials,\n   * retry/backoff, or the exact SDK version in play. If omitted, a\n   * `SecretsManagerClient` is constructed lazily on first fetch (region from\n   * `AWS_REGION`, else `us-east-1`; default credential chain).\n   */\n  client?: SecretsManagerClient | SecretsManagerClientLike;\n  /**\n   * Called with human-readable progress messages. Defaults to `console.log`.\n   * Pass `() => {}` to silence, or route through your own logger.\n   */\n  onLog?: (message: string) => void;\n}\n\n/** Thrown when a fetched secret exists but carries no `SecretString`. */\nexport class MissingSecretStringError extends Error {\n  readonly secretId: string;\n  constructor(secretId: string) {\n    super(\n      `aws-secrets-manager-env-loader: secret \"${secretId}\" has no SecretString`,\n    );\n    this.name = \"MissingSecretStringError\";\n    this.secretId = secretId;\n  }\n}\n\n/** Thrown when a keyed source points at a secret whose `SecretString` is not a JSON object. */\nexport class SecretJsonParseError extends Error {\n  readonly secretId: string;\n  constructor(secretId: string, cause: unknown) {\n    super(\n      `aws-secrets-manager-env-loader: secret \"${secretId}\" is not a JSON object`,\n      { cause },\n    );\n    this.name = \"SecretJsonParseError\";\n    this.secretId = secretId;\n  }\n}\n\n/** Thrown when a keyed source names a property missing from the secret's JSON object. */\nexport class SecretKeyNotFoundError extends Error {\n  readonly secretId: string;\n  readonly key: string;\n  readonly envVar: string;\n  constructor(secretId: string, key: string, envVar: string) {\n    super(\n      `aws-secrets-manager-env-loader: key \"${key}\" (for env var ${envVar}) is not present in JSON secret \"${secretId}\"`,\n    );\n    this.name = \"SecretKeyNotFoundError\";\n    this.secretId = secretId;\n    this.key = key;\n    this.envVar = envVar;\n  }\n}\n\n/**\n * Load the mapped secrets into `process.env`.\n *\n * - Env vars already set to a non-empty value are kept and never fetched. Only\n *   `process.env` is consulted; `.env` files must be loaded beforehand.\n * - Each distinct secret ID is fetched once, in parallel, even when several env\n *   vars read different keys from it.\n * - `Promise.all` semantics: any failed fetch or JSON parse rejects the whole\n *   call and leaves `process.env` unmodified. No partial-load mode.\n */\nexport async function loadSecrets(options: LoadSecretsOptions): Promise<void> {\n  const { secrets, onLog = defaultLog } = options;\n\n  const missing = Object.keys(secrets).filter(\n    (envVar) => !process.env[envVar],\n  );\n  if (missing.length === 0) {\n    onLog(\"[secrets] all secrets already in env, skipping fetch\");\n    return;\n  }\n\n  onLog(`[secrets] fetching from Secrets Manager: ${missing.join(\", \")}`);\n\n  const { GetSecretValueCommand } = await loadSdk();\n  const client = options.client ?? (await getDefaultClient());\n\n  const sources = new Map(\n    missing.map((envVar) => [envVar, normalize(secrets[envVar]!)] as const),\n  );\n  const distinctIds = [\n    ...new Set([...sources.values()].map((source) => source.secretId)),\n  ];\n\n  const rawById = new Map<string, string>();\n  await Promise.all(\n    distinctIds.map(async (secretId) => {\n      const res = await client.send(\n        new GetSecretValueCommand({ SecretId: secretId }),\n      );\n      if (!res.SecretString) throw new MissingSecretStringError(secretId);\n      rawById.set(secretId, res.SecretString);\n    }),\n  );\n\n  const jsonById = new Map<string, Record<string, unknown>>();\n  const parseJsonSecret = (secretId: string): Record<string, unknown> => {\n    const cached = jsonById.get(secretId);\n    if (cached) return cached;\n    let value: unknown;\n    try {\n      value = JSON.parse(rawById.get(secretId)!);\n    } catch (err) {\n      throw new SecretJsonParseError(secretId, err);\n    }\n    if (value === null || typeof value !== \"object\" || Array.isArray(value)) {\n      throw new SecretJsonParseError(\n        secretId,\n        new Error(\"SecretString is not a JSON object\"),\n      );\n    }\n    const parsed = value as Record<string, unknown>;\n    jsonById.set(secretId, parsed);\n    return parsed;\n  };\n\n  const resolved = missing.map((envVar) => {\n    const { secretId, key } = sources.get(envVar)!;\n    if (key === undefined) {\n      return [envVar, rawById.get(secretId)!] as const;\n    }\n    const parsed = parseJsonSecret(secretId);\n    if (!(key in parsed)) {\n      throw new SecretKeyNotFoundError(secretId, key, envVar);\n    }\n    const value = parsed[key];\n    return [\n      envVar,\n      typeof value === \"string\" ? value : JSON.stringify(value),\n    ] as const;\n  });\n\n  for (const [envVar, value] of resolved) {\n    process.env[envVar] = value;\n  }\n  onLog(`[secrets] provisioned into env: ${missing.join(\", \")}`);\n}\n\nfunction normalize(source: SecretSource): { secretId: string; key?: string } {\n  return typeof source === \"string\" ? { secretId: source } : source;\n}\n\nfunction defaultLog(message: string): void {\n  console.log(message);\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "aws-secrets-manager-env-loader",
+  "version": "0.1.0",
+  "description": "Load a map of AWS Secrets Manager secrets into process.env at boot. Env vars already set win over the fetch, missing ones are fetched in parallel, and it fails fast. The AWS SDK client is a peer dependency.",
+  "keywords": [
+    "aws",
+    "secrets-manager",
+    "secrets",
+    "env",
+    "environment-variables",
+    "process.env",
+    "dotenv",
+    "bootstrap",
+    "config",
+    "12-factor"
+  ],
+  "license": "MIT",
+  "author": "steel8rat",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/steel8rat/aws-secrets-manager-env-loader.git"
+  },
+  "homepage": "https://github.com/steel8rat/aws-secrets-manager-env-loader#readme",
+  "bugs": {
+    "url": "https://github.com/steel8rat/aws-secrets-manager-env-loader/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test",
+    "test:watch": "node --test --watch",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-secrets-manager": ">=3.0.0"
+  },
+  "overrides": {
+    "esbuild": "^0.28.2"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-secrets-manager": "^3.699.0",
+    "@types/node": "^22.20.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  }
+}