@karmaniverous/aws-secrets-manager-tools 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,250 @@
+import { SecretsManagerClient, SecretsManagerClientConfig } from '@aws-sdk/client-secrets-manager';
+import * as _karmaniverous_get_dotenv_cliHost from '@karmaniverous/get-dotenv/cliHost';
+
+/**
+ * Requirements addressed:
+ * - Secret values are always a JSON object map of env vars.
+ */
+/**
+ * Canonical “env secret” shape stored in AWS Secrets Manager.
+ *
+ * `undefined` values are not representable in JSON; readers should treat `null`
+ * values as `undefined` when decoding.
+ */
+type EnvSecretMap = Record<string, string | undefined>;
+
+/**
+ * Requirements addressed:
+ * - Provide a public tools-style wrapper `AwsSecretsManagerTools`.
+ * - Package consumers should not need to construct SecretsManagerClient; they
+ *   should use `AwsSecretsManagerTools.init(...)` and optionally import AWS SDK
+ *   Commands for advanced operations.
+ * - Expose the fully configured SDK client via `tools.client`.
+ * - Support optional AWS X-Ray capture:
+ *   - Default “auto”: enable only when AWS_XRAY_DAEMON_ADDRESS is set.
+ *   - In “auto”, if the daemon address is set but aws-xray-sdk is missing,
+ *     throw with a clear message.
+ * - Enforce a minimal logger contract (debug/info/warn/error); do not attempt
+ *   to polyfill or proxy unknown loggers.
+ * - Secret values are JSON object maps of env vars.
+ */
+
+/**
+ * Console-like logger contract used by AwsSecretsManagerTools.
+ *
+ * If you pass a custom logger via `clientConfig.logger`, it must implement
+ * these methods (no internal polyfills are applied).
+ */
+type AwsSecretsManagerToolsLogger = Pick<Console, 'debug' | 'error' | 'info' | 'warn'>;
+/** X-Ray capture mode for {@link AwsSecretsManagerTools.init}. */
+type AwsSecretsManagerToolsXrayMode = 'auto' | 'on' | 'off';
+/**
+ * Materialized X-Ray state for diagnostics and DX.
+ *
+ * Note: `enabled` reflects the effective runtime decision after applying the
+ * configured `mode` and checking daemon configuration.
+ */
+type XrayState = {
+    /** Capture mode configured for initialization. */
+    mode: AwsSecretsManagerToolsXrayMode;
+    /** Whether capture is enabled for the effective client instance. */
+    enabled: boolean;
+    /** Daemon address used when capture is enabled (if available). */
+    daemonAddress?: string;
+};
+/** Options for {@link AwsSecretsManagerTools.init}. */
+type AwsSecretsManagerToolsInitOptions = {
+    /**
+     * AWS SDK v3 Secrets Manager client config.
+     *
+     * Include advanced settings here (region, credentials, retry config, custom
+     * endpoint, etc.). If a logger is provided, it must implement
+     * debug/info/warn/error.
+     */
+    clientConfig?: SecretsManagerClientConfig;
+    /**
+     * AWS X-Ray capture mode.
+     *
+     * - `auto` (default): enable only when `AWS_XRAY_DAEMON_ADDRESS` is set.
+     * - `on`: force enable (throws if daemon address is missing).
+     * - `off`: disable.
+     */
+    xray?: AwsSecretsManagerToolsXrayMode;
+};
+/**
+ * Tools-style AWS Secrets Manager wrapper for env-map secrets.
+ *
+ * The secret payload is always a JSON object map of environment variables:
+ * `Record<string, string | undefined>`.
+ *
+ * Consumers should typically use the convenience methods on this class, and
+ * use {@link AwsSecretsManagerTools.client} as an escape hatch when they need
+ * AWS SDK operations not wrapped here.
+ */
+declare class AwsSecretsManagerTools {
+    /**
+     * The effective SDK client (captured when X-Ray is enabled).
+     *
+     * Import AWS SDK `*Command` classes as needed and call `tools.client.send(...)`.
+     */
+    readonly client: SecretsManagerClient;
+    /**
+     * The effective client config used to construct the base client.
+     *
+     * Note: this may contain functions/providers (e.g., credential providers).
+     */
+    readonly clientConfig: SecretsManagerClientConfig;
+    /** The logger used by this wrapper and (when applicable) by the AWS client. */
+    readonly logger: AwsSecretsManagerToolsLogger;
+    /** Materialized X-Ray state (mode + enabled + daemonAddress when relevant). */
+    readonly xray: XrayState;
+    private constructor();
+    /**
+     * Initialize an `AwsSecretsManagerTools` instance.
+     *
+     * This factory owns all setup (including optional X-Ray capture) so consumers
+     * do not need to construct a base Secrets Manager client themselves.
+     *
+     * @throws If `clientConfig.logger` is provided but does not implement
+     * `debug`, `info`, `warn`, and `error`.
+     * @throws If X-Ray capture is enabled (via `xray: 'on'` or `xray: 'auto'`
+     * with `AWS_XRAY_DAEMON_ADDRESS` set) but `aws-xray-sdk` is not installed.
+     * @throws If X-Ray capture is requested but `AWS_XRAY_DAEMON_ADDRESS` is not set.
+     */
+    static init({ clientConfig, xray: xrayMode, }?: AwsSecretsManagerToolsInitOptions): Promise<AwsSecretsManagerTools>;
+    /**
+     * Read a Secrets Manager secret and parse it as an env-map secret.
+     *
+     * @param opts - Options:
+     *   - `secretId`: Secret name or ARN.
+     *   - `versionId`: Optional version id to read.
+     *
+     * @throws If the secret is missing, binary, invalid JSON, or not an object map.
+     */
+    readEnvSecret(opts: {
+        secretId: string;
+        versionId?: string;
+    }): Promise<EnvSecretMap>;
+    /**
+     * Write a new version value for an existing secret.
+     *
+     * This does not create the secret if it does not exist.
+     *
+     * @param opts - Options:
+     *   - `secretId`: Secret name or ARN.
+     *   - `value`: Env-map payload to store (JSON object map).
+     *   - `versionId`: Optional client request token (idempotency).
+     */
+    updateEnvSecret(opts: {
+        secretId: string;
+        value: EnvSecretMap;
+        versionId?: string;
+    }): Promise<void>;
+    /**
+     * Create a new secret containing an env-map.
+     *
+     * @param opts - Options:
+     *   - `secretId`: Secret name (or ARN in some contexts).
+     *   - `value`: Env-map payload to store (JSON object map).
+     *   - `description`: Optional AWS secret description.
+     *   - `forceOverwriteReplicaSecret`: See AWS CreateSecret behavior for replicas.
+     *   - `versionId`: Optional client request token (idempotency).
+     */
+    createEnvSecret(opts: {
+        secretId: string;
+        value: EnvSecretMap;
+        description?: string;
+        forceOverwriteReplicaSecret?: boolean;
+        versionId?: string;
+    }): Promise<void>;
+    /**
+     * Put a secret value, creating the secret only when it does not exist.
+     *
+     * This creates only when the update fails with `ResourceNotFoundException`;
+     * other errors are re-thrown.
+     *
+     * @returns `'updated'` if updated; `'created'` if the secret was created.
+     * @throws Re-throws any non-ResourceNotFound AWS errors.
+     */
+    upsertEnvSecret({ secretId, value, }: {
+        secretId: string;
+        value: EnvSecretMap;
+    }): Promise<'updated' | 'created'>;
+    /**
+     * Delete a secret.
+     *
+     * By default, deletion is recoverable (AWS default recovery window) unless
+     * `forceDeleteWithoutRecovery` is set.
+     *
+     * @param opts - Options:
+     *   - `secretId`: Secret name or ARN.
+     *   - `recoveryWindowInDays`: Explicit recovery window to use.
+     *   - `forceDeleteWithoutRecovery`: Dangerous: delete without recovery.
+     *
+     * @throws If both `recoveryWindowInDays` and `forceDeleteWithoutRecovery` are provided.
+     */
+    deleteSecret(opts: {
+        secretId: string;
+        recoveryWindowInDays?: number;
+        forceDeleteWithoutRecovery?: boolean;
+    }): Promise<void>;
+}
+
+/**
+ * Requirements addressed:
+ * - Provide get-dotenv plugin mounted as `aws secrets` with commands:
+ *   - `aws secrets pull`
+ *   - `aws secrets push`
+ *   - `aws secrets delete`
+ * - Keep the plugin adapter thin: command registration is decomposed into
+ *   dedicated modules; core behavior lives outside this file.
+ * - For config-backed plugin options, register dynamic options on the command
+ *   so help reflects composed defaults and option parsing is typed.
+ */
+/**
+ * get-dotenv plugin that provides `aws secrets pull|push|delete`.
+ *
+ * Intended usage: mount under `awsPlugin().use(secretsPlugin())`.
+ */
+declare const secretsPlugin: () => _karmaniverous_get_dotenv_cliHost.PluginWithInstanceHelpers<Omit<{
+    logger: unknown;
+    defaultEnv?: string | undefined;
+    dotenvToken?: string | undefined;
+    dynamicPath?: string | undefined;
+    dynamic?: Record<string, unknown> | undefined;
+    env?: string | undefined;
+    excludeDynamic?: boolean | undefined;
+    excludeEnv?: boolean | undefined;
+    excludeGlobal?: boolean | undefined;
+    excludePrivate?: boolean | undefined;
+    excludePublic?: boolean | undefined;
+    loadProcess?: boolean | undefined;
+    log?: boolean | undefined;
+    outputPath?: string | undefined;
+    paths?: string[] | undefined;
+    privateToken?: string | undefined;
+    vars?: Record<string, string | undefined> | undefined;
+}, "dynamic" | "logger"> & {
+    logger: Record<string, (...args: unknown[]) => void> | Console;
+    dynamic?: {
+        [x: string]: string | ((vars: {
+            [x: string]: string | undefined;
+        }, env: string | undefined) => string | undefined) | undefined;
+    };
+}, {
+    secretName?: string | undefined;
+    templateExtension?: string | undefined;
+    push?: {
+        from?: string[] | undefined;
+        include?: string[] | undefined;
+        exclude?: string[] | undefined;
+    } | undefined;
+    pull?: {
+        to?: string | undefined;
+        include?: string[] | undefined;
+        exclude?: string[] | undefined;
+    } | undefined;
+}, [], {}, {}>;
+
+export { AwsSecretsManagerTools, secretsPlugin };
+export type { AwsSecretsManagerToolsInitOptions, AwsSecretsManagerToolsLogger, AwsSecretsManagerToolsXrayMode, EnvSecretMap, XrayState };