@aws-blocks/bb-app-setting 0.1.0

package/dist/index.cdk.js

@@ -0,0 +1,242 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import * as cdk from 'aws-cdk-lib';
+import * as ssm from 'aws-cdk-lib/aws-ssm';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+import * as cr from 'aws-cdk-lib/custom-resources';
+import { Scope, registerConfig, DEFAULT_NODE_RUNTIME } from '@aws-blocks/core/cdk';
+import { AppSettingErrors } from './errors.js';
+export { AppSettingErrors } from './errors.js';
+/**
+ * CDK construct for AppSetting. Creates a single SSM parameter (String or
+ * SecureString) and grants the shared Lambda handler read/write permissions.
+ *
+ * - String parameters use `aws-cdk-lib/aws-ssm.StringParameter` directly.
+ * - SecureString parameters use a Custom Resource Lambda because
+ *   CloudFormation cannot natively create SecureString parameters.
+ * - SecureString parameters are encrypted with the default `aws/ssm` KMS key.
+ */
+export class AppSetting extends Scope {
+    /**
+     * Reference an SSM parameter that is created and owned **outside this stack**
+     * (e.g. a connection string seeded by `ensureSecrets` before deploy). The
+     * construct does not create, seed, tag, or delete it — it only grants the app
+     * **read-only** access (`ssm:GetParameter`, plus `kms:Decrypt` when `secret`)
+     * and registers the name for config resolution.
+     *
+     * The parameter MUST already exist at deploy time, otherwise the app fails at
+     * runtime with `ParameterNotFound`.
+     *
+     * @example
+     * const dbUrl = AppSetting.fromExisting(scope, 'db-url', { name: dbParameterName, secret: true });
+     */
+    static fromExisting(scope, id, options) {
+        const opts = { ...options, external: true };
+        return new AppSetting(scope, id, opts);
+    }
+    constructor(scope, id, options) {
+        super(id, { parent: scope });
+        // `external` is package-internal (set only by fromExisting), not on the
+        // public AppSettingOptions — read it via the internal options type.
+        const external = options.external ?? false;
+        // ── Validation ──────────────────────────────────────────────────────
+        if (options.secret && options.schema) {
+            const err = new Error(`AppSetting '${id}': 'secret' and 'schema' cannot be used together. ` +
+                `Secrets are always plain strings. Remove the schema or the secret flag.`);
+            err.name = AppSettingErrors.ValidationFailed;
+            throw err;
+        }
+        if (options.schema && options.value === undefined) {
+            const err = new Error(`AppSetting '${id}': a schema is provided but no value. ` +
+                `Provide a value that conforms to the schema so the SSM parameter is valid on first deploy.`);
+            err.name = AppSettingErrors.ValidationFailed;
+            throw err;
+        }
+        if (options.secret && options.value !== undefined) {
+            const err = new Error(`AppSetting '${id}': secrets should not have a value in source code. ` +
+                `Remove the value — a random secret will be generated on first deploy. ` +
+                `Set the real value at runtime via AppSetting.put().`);
+            err.name = AppSettingErrors.ValidationFailed;
+            throw err;
+        }
+        if (external && options.value !== undefined) {
+            const err = new Error(`AppSetting '${id}': 'external' settings are owned elsewhere and must not have a value. ` +
+                `Remove the value — the parameter is created and seeded outside this stack.`);
+            err.name = AppSettingErrors.ValidationFailed;
+            throw err;
+        }
+        if (external && !options.name) {
+            const err = new Error(`AppSetting '${id}': 'external' requires an explicit 'name' referencing the existing parameter.`);
+            err.name = AppSettingErrors.ValidationFailed;
+            throw err;
+        }
+        if (!options.secret && !external && options.value === undefined) {
+            const err = new Error(`AppSetting '${id}': non-secret settings require a value. ` +
+                `Provide an initial value for the SSM parameter.`);
+            err.name = AppSettingErrors.ValidationFailed;
+            throw err;
+        }
+        const parameterName = options.name ?? `/${this.fullId}`;
+        // Always JSON.stringify
+        // For secrets without a value, the Custom Resource Lambda generates a random string
+        const initialValue = options.value !== undefined
+            ? JSON.stringify(options.value)
+            : undefined;
+        const parameterArn = cdk.Stack.of(this).formatArn({
+            service: 'ssm',
+            resource: 'parameter',
+            resourceName: parameterName.replace(/^\//, ''),
+        });
+        if (options.secret) {
+            // ── SecureString ────────────────────────────────────────────────
+            // Externally-owned secrets (e.g. the connection string seeded by
+            // ensureSecrets) are NOT enrolled in the bulk-init: it would
+            // PutParameter a random placeholder over a parameter we don't own and
+            // then fail tagging it (AddTagsToResource needs ssm:GetParameters).
+            // We only need runtime read access, granted below.
+            if (!external) {
+                registerSecret(cdk.Stack.of(this), parameterName);
+            }
+            // Grant handler KMS access for the default aws/ssm key. External secrets
+            // are read-only (Decrypt only); stack-managed secrets also need Encrypt
+            // so the app can write the value via put().
+            this.handler.addToRolePolicy(new iam.PolicyStatement({
+                actions: external ? ['kms:Decrypt'] : ['kms:Decrypt', 'kms:Encrypt'],
+                resources: ['*'],
+                conditions: {
+                    StringEquals: {
+                        'kms:ViaService': `ssm.${cdk.Stack.of(this).region}.amazonaws.com`,
+                    },
+                },
+            }));
+        }
+        else if (!external) {
+            // ── String parameter via CDK construct ──────────────────────────
+            const param = new ssm.StringParameter(this, 'Param', {
+                parameterName,
+                stringValue: initialValue ?? '',
+            });
+            let tagStack = cdk.Stack.of(this);
+            while (tagStack.nestedStackParent)
+                tagStack = tagStack.nestedStackParent;
+            cdk.Tags.of(param).add('aws-blocks-stack', tagStack.stackName);
+        }
+        // (external non-secret: parameter exists already; nothing to create.)
+        // Grant handler SSM access on this parameter. External parameters are owned
+        // elsewhere, so the app only reads them (no ssm:PutParameter).
+        this.handler.addToRolePolicy(new iam.PolicyStatement({
+            actions: external ? ['ssm:GetParameter'] : ['ssm:GetParameter', 'ssm:PutParameter'],
+            resources: [parameterArn],
+        }));
+        // Pass the parameter name to the runtime via config registry
+        const envKey = `BLOCKS_SSM_PARAM_${id.toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
+        registerConfig(this, envKey, parameterName);
+    }
+}
+// ── Bulk Secret Initialization (one CustomResource per stack) ───────────────
+const SECRET_BULK_KEY = Symbol.for('BLOCKS_SECRET_BULK_INIT');
+/**
+ * Register a secret parameter name. On first call, creates the shared Lambda,
+ * Provider, and a single CustomResource. All subsequent calls just append to
+ * the parameter list (resolved lazily at synth time).
+ */
+function registerSecret(stack, parameterName) {
+    let state = stack[SECRET_BULK_KEY];
+    if (state) {
+        state.parameterNames.push(parameterName);
+        return;
+    }
+    // First secret in this stack — create all shared infrastructure
+    state = { parameterNames: [parameterName] };
+    stack[SECRET_BULK_KEY] = state;
+    const secretInitFn = new lambda.Function(stack, 'KitSecretInitFn', {
+        runtime: DEFAULT_NODE_RUNTIME,
+        handler: 'index.handler',
+        code: lambda.Code.fromInline(`
+			const { SSMClient, PutParameterCommand, DeleteParameterCommand, AddTagsToResourceCommand } = require('@aws-sdk/client-ssm');
+			const crypto = require('crypto');
+			const client = new SSMClient({});
+			exports.handler = async (event) => {
+				const names = event.ResourceProperties.ParameterNames || [];
+				const stackName = event.ResourceProperties.StackName || '';
+				const tags = stackName ? [{ Key: 'aws-blocks-stack', Value: stackName }] : [];
+				const oldNames = (event.OldResourceProperties || {}).ParameterNames || [];
+				if (event.RequestType === 'Delete') {
+					for (const name of names) {
+						try { await client.send(new DeleteParameterCommand({ Name: name })); } catch {}
+					}
+					return { PhysicalResourceId: 'bb-secrets-bulk' };
+				}
+				if (event.RequestType === 'Create') {
+					for (const name of names) {
+						const secret = crypto.randomBytes(32).toString('base64url');
+						try {
+							await client.send(new PutParameterCommand({
+								Name: name, Value: secret, Type: 'SecureString', Overwrite: false, Tags: tags,
+							}));
+						} catch (e) {
+							if (e.name !== 'ParameterAlreadyExists') throw e;
+							if (tags.length) {
+								await client.send(new AddTagsToResourceCommand({ ResourceType: 'Parameter', ResourceId: name, Tags: tags }));
+							}
+						}
+					}
+					return { PhysicalResourceId: 'bb-secrets-bulk' };
+				}
+				if (event.RequestType === 'Update') {
+					const added = names.filter(n => !oldNames.includes(n));
+					const removed = oldNames.filter(n => !names.includes(n));
+					for (const name of added) {
+						const secret = crypto.randomBytes(32).toString('base64url');
+						try {
+							await client.send(new PutParameterCommand({
+								Name: name, Value: secret, Type: 'SecureString', Overwrite: false, Tags: tags,
+							}));
+						} catch (e) {
+							if (e.name !== 'ParameterAlreadyExists') throw e;
+							if (tags.length) {
+								await client.send(new AddTagsToResourceCommand({ ResourceType: 'Parameter', ResourceId: name, Tags: tags }));
+							}
+						}
+					}
+					for (const name of removed) {
+						try { await client.send(new DeleteParameterCommand({ Name: name })); } catch {}
+					}
+					return { PhysicalResourceId: 'bb-secrets-bulk' };
+				}
+				return { PhysicalResourceId: 'bb-secrets-bulk' };
+			};
+		`),
+    });
+    secretInitFn.addToRolePolicy(new iam.PolicyStatement({
+        actions: ['ssm:PutParameter', 'ssm:DeleteParameter', 'ssm:AddTagsToResource'],
+        resources: cdk.Lazy.list({
+            produce: () => state.parameterNames.map(name => stack.formatArn({
+                service: 'ssm',
+                resource: 'parameter',
+                resourceName: name.replace(/^\//, ''),
+            })),
+        }),
+    }));
+    secretInitFn.addToRolePolicy(new iam.PolicyStatement({
+        actions: ['kms:Encrypt'],
+        resources: ['*'],
+        conditions: {
+            StringEquals: {
+                'kms:ViaService': `ssm.${stack.region}.amazonaws.com`,
+            },
+        },
+    }));
+    const provider = new cr.Provider(stack, 'KitSecretProvider', {
+        onEventHandler: secretInitFn,
+    });
+    new cdk.CustomResource(stack, 'KitSecretsBulk', {
+        serviceToken: provider.serviceToken,
+        properties: {
+            ParameterNames: cdk.Lazy.list({ produce: () => state.parameterNames }),
+            StackName: (() => { let s = stack; while (s.nestedStackParent)
+                s = s.nestedStackParent; return s.stackName; })(),
+        },
+    });
+}

package/dist/index.cdk.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.cdk.test.d.ts.map

package/dist/index.cdk.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cdk.test.d.ts","sourceRoot":"","sources":["../src/index.cdk.test.ts"],"names":[],"mappings":""}

package/dist/index.cdk.test.js

@@ -0,0 +1,187 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CDK-side tests for AppSetting.
+ *
+ * Verifies that the Custom Resource Lambda's IAM policy is scoped to specific
+ * parameter ARNs (not a wildcard) — regression test for #598.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert';
+import * as cdk from 'aws-cdk-lib';
+import { Template, Match } from 'aws-cdk-lib/assertions';
+import { Scope, DEFAULT_NODE_RUNTIME } from '@aws-blocks/core/cdk';
+import { AppSetting } from './index.cdk.js';
+class StubBlocksStack extends cdk.Stack {
+    handler;
+    id;
+    constructor(scope, id) {
+        super(scope, id);
+        this.id = id;
+        globalThis.CURRENT_BLOCKS_STACK = this;
+        this.handler = new cdk.aws_lambda.Function(this, 'StubHandler', {
+            runtime: DEFAULT_NODE_RUNTIME,
+            handler: 'index.handler',
+            code: cdk.aws_lambda.Code.fromInline('exports.handler = async () => {};'),
+        });
+    }
+}
+function setup() {
+    const app = new cdk.App();
+    const stack = new StubBlocksStack(app, 'TestStack');
+    const parent = new Scope('app');
+    return { stack, parent };
+}
+test('CDK: secret AppSetting SSM policy is scoped to specific parameter ARN (not wildcard)', () => {
+    const { stack, parent } = setup();
+    new AppSetting(parent, 'my-secret', { secret: true, name: '/myapp/secret-key' });
+    const template = Template.fromStack(stack);
+    // The KitSecretInitFn should have an IAM policy for ssm:PutParameter/DeleteParameter
+    // scoped to the specific parameter, NOT a wildcard
+    const policies = template.findResources('AWS::IAM::Policy');
+    const policyLogicalIds = Object.keys(policies);
+    let foundSsmPolicy = false;
+    for (const logicalId of policyLogicalIds) {
+        const statements = policies[logicalId]?.Properties?.PolicyDocument?.Statement;
+        if (!Array.isArray(statements))
+            continue;
+        for (const stmt of statements) {
+            const actions = stmt.Action;
+            if (!Array.isArray(actions))
+                continue;
+            if (!actions.includes('ssm:PutParameter') || !actions.includes('ssm:DeleteParameter'))
+                continue;
+            foundSsmPolicy = true;
+            // Resource must NOT be a wildcard — it should be a specific ARN
+            const resources = stmt.Resource;
+            if (Array.isArray(resources)) {
+                for (const res of resources) {
+                    const arnStr = typeof res === 'string' ? res : JSON.stringify(res);
+                    assert.ok(!arnStr.includes('"*"') && arnStr !== '*', `SSM policy resource must not be a wildcard, got: ${arnStr}`);
+                }
+            }
+            else {
+                const arnStr = typeof resources === 'string' ? resources : JSON.stringify(resources);
+                assert.notStrictEqual(arnStr, '*', 'SSM policy resource must not be a wildcard');
+            }
+        }
+    }
+    assert.ok(foundSsmPolicy, 'Expected to find an IAM policy with ssm:PutParameter/DeleteParameter');
+});
+test('CDK: secret AppSetting SSM policy contains the correct parameter name', () => {
+    const { stack, parent } = setup();
+    new AppSetting(parent, 'db-password', { secret: true, name: '/myapp/db-password' });
+    const template = Template.fromStack(stack);
+    // Verify the policy resource ARN references the parameter name
+    const templateJson = JSON.stringify(template.toJSON());
+    assert.ok(templateJson.includes('myapp/db-password'), 'Expected the synthesized template to contain the specific parameter name "myapp/db-password"');
+});
+test('CDK: multiple secret AppSettings produce scoped policy with all parameter ARNs', () => {
+    const { stack, parent } = setup();
+    new AppSetting(parent, 'secret-a', { secret: true, name: '/app/secret-a' });
+    new AppSetting(parent, 'secret-b', { secret: true, name: '/app/secret-b' });
+    const template = Template.fromStack(stack);
+    const templateJson = JSON.stringify(template.toJSON());
+    assert.ok(templateJson.includes('app/secret-a'), 'Expected template to reference parameter "app/secret-a"');
+    assert.ok(templateJson.includes('app/secret-b'), 'Expected template to reference parameter "app/secret-b"');
+});
+test('CDK: non-secret AppSetting creates SSM StringParameter', () => {
+    const { stack, parent } = setup();
+    new AppSetting(parent, 'config', { value: 'hello', name: '/app/config' });
+    const template = Template.fromStack(stack);
+    template.resourceCountIs('AWS::SSM::Parameter', 1);
+});
+test('CDK: non-secret AppSetting grants handler scoped SSM access', () => {
+    const { stack, parent } = setup();
+    new AppSetting(parent, 'config', { value: 'hello', name: '/app/config' });
+    const template = Template.fromStack(stack);
+    // Should have a policy statement for ssm:GetParameter, ssm:PutParameter
+    // scoped to the specific parameter ARN
+    template.hasResourceProperties('AWS::IAM::Policy', {
+        PolicyDocument: {
+            Statement: Match.arrayWith([
+                Match.objectLike({
+                    Action: ['ssm:GetParameter', 'ssm:PutParameter'],
+                    Resource: Match.objectLike({
+                        'Fn::Join': Match.anyValue(),
+                    }),
+                }),
+            ]),
+        },
+    });
+});
+test('CDK: external secret is NOT enrolled in bulk-init (no KitSecretsBulk / KitSecretInitFn)', () => {
+    const { stack, parent } = setup();
+    AppSetting.fromExisting(parent, 'db-url', { name: '/blocks/sandbox/db-abc-connection-string', secret: true });
+    const template = Template.fromStack(stack);
+    // No secret bulk-init custom resource and no init Lambda should be synthesized:
+    // an externally-owned parameter must not be created, tagged, or deleted by us.
+    template.resourceCountIs('AWS::CloudFormation::CustomResource', 0);
+    const lambdas = template.findResources('AWS::Lambda::Function');
+    for (const id of Object.keys(lambdas)) {
+        const code = JSON.stringify(lambdas[id]?.Properties?.Code ?? {});
+        assert.ok(!code.includes('AddTagsToResourceCommand'), `Lambda ${id} should not be the secret-init function`);
+    }
+});
+test('CDK: external secret grants READ-ONLY runtime access (GetParameter + Decrypt, scoped, no write)', () => {
+    const { stack, parent } = setup();
+    AppSetting.fromExisting(parent, 'db-url', { name: '/blocks/sandbox/db-abc-connection-string', secret: true });
+    const template = Template.fromStack(stack);
+    // ssm:GetParameter, scoped to the specific parameter ARN (not a wildcard).
+    template.hasResourceProperties('AWS::IAM::Policy', {
+        PolicyDocument: {
+            Statement: Match.arrayWith([
+                Match.objectLike({
+                    Action: 'ssm:GetParameter',
+                    Resource: Match.objectLike({ 'Fn::Join': Match.anyValue() }),
+                }),
+            ]),
+        },
+    });
+    // kms:Decrypt for reading the SecureString.
+    template.hasResourceProperties('AWS::IAM::Policy', {
+        PolicyDocument: { Statement: Match.arrayWith([Match.objectLike({ Action: 'kms:Decrypt' })]) },
+    });
+    // Must NOT grant write to an externally-owned secret.
+    const policiesJson = JSON.stringify(template.findResources('AWS::IAM::Policy'));
+    assert.ok(!policiesJson.includes('ssm:PutParameter'), 'external secret must not grant ssm:PutParameter');
+    assert.ok(!policiesJson.includes('kms:Encrypt'), 'external secret must not grant kms:Encrypt');
+});
+test('CDK: external non-secret creates no SSM parameter and grants read-only access', () => {
+    const { stack, parent } = setup();
+    AppSetting.fromExisting(parent, 'shared-config', { name: '/some/external/config' });
+    const template = Template.fromStack(stack);
+    // The construct does not create the parameter — it's owned externally.
+    template.resourceCountIs('AWS::SSM::Parameter', 0);
+    template.hasResourceProperties('AWS::IAM::Policy', {
+        PolicyDocument: {
+            Statement: Match.arrayWith([
+                Match.objectLike({
+                    Action: 'ssm:GetParameter',
+                    Resource: Match.objectLike({ 'Fn::Join': Match.anyValue() }),
+                }),
+            ]),
+        },
+    });
+    assert.ok(!JSON.stringify(template.findResources('AWS::IAM::Policy')).includes('ssm:PutParameter'), 'external non-secret must not grant write');
+});
+test('CDK: the internal external guard requires a name and forbids a value', () => {
+    // fromExisting() is the public API and makes `name` required at the type level;
+    // these assertions cover the runtime guard on the underlying `external` option
+    // (defense for JS callers / direct construction).
+    const { parent } = setup();
+    assert.throws(() => new AppSetting(parent, 'ext-no-name', { secret: true, external: true }), /requires an explicit 'name'/);
+    assert.throws(() => new AppSetting(parent, 'ext-with-value', { external: true, name: '/x', value: 'v' }), /must not have a value/);
+});
+test('CDK: fromExisting still registers the runtime config key (BLOCKS_SSM_PARAM_*)', () => {
+    // BLOCKS_SSM_PARAM_DB_URL is the ONLY link between db-pull's runtime resolveConnString()
+    // and the deployed parameter name. If config registration ever moved inside the
+    // non-external branch, every external setting would fail at runtime with
+    // ParameterNotFound — and nothing else would catch it. This pins the contract.
+    const { stack, parent } = setup();
+    AppSetting.fromExisting(parent, 'db-url', { name: '/blocks/sandbox/db-abc-connection-string', secret: true });
+    const registry = stack[Symbol.for('BLOCKS_CONFIG_REGISTRY')];
+    assert.ok(registry, 'config registry exists on the stack');
+    assert.ok(registry.entries.has('BLOCKS_SSM_PARAM_DB_URL'), 'external setting must register BLOCKS_SSM_PARAM_DB_URL so the runtime can resolve the parameter');
+    assert.equal(registry.entries.get('BLOCKS_SSM_PARAM_DB_URL'), '/blocks/sandbox/db-abc-connection-string');
+});

package/dist/index.hooks.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.hooks.d.ts.map

package/dist/index.hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.hooks.d.ts","sourceRoot":"","sources":["../src/index.hooks.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC"}

package/dist/index.hooks.js

@@ -0,0 +1,3 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+export {};

package/dist/index.mock.d.ts

@@ -0,0 +1,77 @@
+import { Scope } from '@aws-blocks/core';
+import type { ScopeParent } from '@aws-blocks/core';
+import type { AppSettingOptions } from './types.js';
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+export { AppSettingErrors } from './errors.js';
+export type { AppSettingOptions } from './types.js';
+/**
+ * A single application configuration value backed by SSM Parameter Store.
+ *
+ * **When to use:** You need to store and retrieve a non-secret configuration
+ * value at runtime — a feature flag, API URL, threshold, or structured config
+ * object. For sensitive values, set `secret: true` to use SSM SecureString.
+ *
+ * **When NOT to use:** If you need structured key-value data with conditional
+ * writes and queries, use `KVStore` or `DistributedTable`.
+ *
+ * **Best practices:**
+ * - One AppSetting per logical configuration value
+ * - Use a schema for structured objects to get type safety and runtime validation
+ * - Use `secret: true` for API keys, tokens, and passwords
+ *
+ * **Scaling:** Standard-tier SSM parameters. 40 TPS default for GetParameter
+ * (can be increased). No cost for standard parameters.
+ */
+export declare class AppSetting<T = string> extends Scope {
+    /**
+     * Reference an SSM parameter created and owned outside this stack — the local
+     * dev mirror of the CDK `fromExisting`. In the mock there is no IAM or
+     * bulk-init, so it behaves like a normal setting keyed by its `fullId`; the
+     * factory exists so app code uses the same API in dev and deploy.
+     *
+     * Note: like any mock secret with no value, `get()` returns a random placeholder
+     * unless `.bb-data/settings.json` was already seeded for this `fullId` (e.g. by
+     * `db pull`). Local dev still depends on whatever seeds that value.
+     */
+    static fromExisting<T = string>(scope: ScopeParent, id: string, options: {
+        name: string;
+        secret?: boolean;
+    }): AppSetting<T>;
+    private parameterName;
+    private initialValue;
+    private schema?;
+    private isSecret;
+    /** @internal Logger for internal operations. Defaults to error-level when not provided. */
+    protected log: ChildLogger;
+    constructor(scope: ScopeParent, id: string, options: AppSettingOptions<T>);
+    /**
+     * Retrieve the current value.
+     *
+     * Returns the stored value from `.bb-data/settings.json`.
+     *
+     * @returns The current value.
+     *
+     * @example
+     * ```typescript
+     * const retries = await maxRetries.get();
+     * ```
+     */
+    get(): Promise<T>;
+    /**
+     * Update the value at runtime.
+     *
+     * Writes the new value to `.bb-data/settings.json`. When a schema is
+     * configured, the value is validated before writing.
+     *
+     * @param value - The new value to store.
+     * @throws {AppSettingErrors.ValidationFailed} If schema validation fails or value exceeds 4 KB.
+     *
+     * @example
+     * ```typescript
+     * await maxRetries.put('5');
+     * await config.put({ maxRetries: 5, timeout: 10000 });
+     * ```
+     */
+    put(value: T): Promise<void>;
+}
+//# sourceMappingURL=index.mock.d.ts.map

package/dist/index.mock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mock.d.ts","sourceRoot":"","sources":["../src/index.mock.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAA0B,MAAM,kBAAkB,CAAC;AAEjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAMpD,OAAO,KAAK,EAAE,iBAAiB,EAA6B,MAAM,YAAY,CAAC;AAE/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAIzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAsCpD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,UAAU,CAAC,CAAC,GAAG,MAAM,CAAE,SAAQ,KAAK;IAChD;;;;;;;;;OASG;IACH,MAAM,CAAC,YAAY,CAAC,CAAC,GAAG,MAAM,EAC7B,KAAK,EAAE,WAAW,EAClB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GACzC,UAAU,CAAC,CAAC,CAAC;IAKhB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,YAAY,CAAI;IACxB,OAAO,CAAC,MAAM,CAAC,CAAsB;IACrC,OAAO,CAAC,QAAQ,CAAU;IAE1B,2FAA2F;IAC3F,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC;gBAEf,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAyBzE;;;;;;;;;;;OAWG;IACG,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC;IAWvB;;;;;;;;;;;;;;OAcG;IACG,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAelC"}