@aws-blocks/core 0.1.0

package/dist/common/index.test.js

@@ -0,0 +1,195 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { test, describe } from 'node:test';
+import assert from 'node:assert';
+import { Scope } from './index.js';
+import { CORE_VERSION } from '../version.js';
+/**
+ * Test subclass that exposes the protected buildUserAgentChain method.
+ */
+class TestBB extends Scope {
+    bbName;
+    bbVersion;
+    constructor(id, opts) {
+        super(id, { parent: opts?.parent });
+        this.bbName = opts?.bbName;
+        this.bbVersion = opts?.bbVersion;
+    }
+    /** Expose protected method for testing */
+    testBuildUserAgentChain() {
+        return this.buildUserAgentChain();
+    }
+}
+// ── buildUserAgentChain: standalone BB (no BB parent) ───────────────────────
+describe('buildUserAgentChain', () => {
+    test('standalone BB returns [aws-blocks, bb] pair', () => {
+        const root = { id: 'my-app' };
+        const bb = new TestBB('store', {
+            parent: root,
+            bbName: 'KVStore',
+            bbVersion: '0.4.0',
+        });
+        const chain = bb.testBuildUserAgentChain();
+        assert.deepStrictEqual(chain, [
+            ['aws-blocks', CORE_VERSION],
+            ['bb', 'KVStore/0.4.0'],
+        ]);
+    });
+    // ── Nested BB (one level) ─────────────────────────────────────────────
+    test('BB nested inside another BB includes parent BB in chain', () => {
+        const root = { id: 'my-app' };
+        const parentBB = new TestBB('auth', {
+            parent: root,
+            bbName: 'AuthBasic',
+            bbVersion: '1.0.1',
+        });
+        const childBB = new TestBB('store', {
+            parent: parentBB,
+            bbName: 'KVStore',
+            bbVersion: '0.4.0',
+        });
+        const chain = childBB.testBuildUserAgentChain();
+        assert.deepStrictEqual(chain, [
+            ['aws-blocks', CORE_VERSION],
+            ['bb', 'AuthBasic/1.0.1'],
+            ['bb', 'KVStore/0.4.0'],
+        ]);
+    });
+    // ── Deeply nested BB (2+ levels) ──────────────────────────────────────
+    test('BB nested 2+ levels deep builds the full chain in root-to-leaf order', () => {
+        const root = { id: 'my-app' };
+        const grandparentBB = new TestBB('dashboard', {
+            parent: root,
+            bbName: 'Dashboard',
+            bbVersion: '2.0.0',
+        });
+        const parentBB = new TestBB('auth', {
+            parent: grandparentBB,
+            bbName: 'AuthBasic',
+            bbVersion: '1.0.1',
+        });
+        const childBB = new TestBB('store', {
+            parent: parentBB,
+            bbName: 'KVStore',
+            bbVersion: '0.4.0',
+        });
+        const chain = childBB.testBuildUserAgentChain();
+        assert.deepStrictEqual(chain, [
+            ['aws-blocks', CORE_VERSION],
+            ['bb', 'Dashboard/2.0.0'],
+            ['bb', 'AuthBasic/1.0.1'],
+            ['bb', 'KVStore/0.4.0'],
+        ]);
+    });
+    // ── Parent without BB metadata (non-BB scope in the chain) ────────────
+    test('parent scope without bbName/bbVersion is skipped in chain', () => {
+        const root = { id: 'my-app' };
+        // A plain Scope (not a BB) in between
+        const middleScope = new TestBB('middleware', {
+            parent: root,
+            // no bbName/bbVersion
+        });
+        const childBB = new TestBB('store', {
+            parent: middleScope,
+            bbName: 'KVStore',
+            bbVersion: '0.4.0',
+        });
+        const chain = childBB.testBuildUserAgentChain();
+        assert.deepStrictEqual(chain, [
+            ['aws-blocks', CORE_VERSION],
+            ['bb', 'KVStore/0.4.0'],
+        ]);
+    });
+    test('non-BB parent between two BBs is skipped', () => {
+        const root = { id: 'my-app' };
+        const parentBB = new TestBB('auth', {
+            parent: root,
+            bbName: 'AuthBasic',
+            bbVersion: '1.0.1',
+        });
+        // Plain scope between parent BB and child BB
+        const middleScope = new TestBB('internal', {
+            parent: parentBB,
+            // no bbName/bbVersion
+        });
+        const childBB = new TestBB('store', {
+            parent: middleScope,
+            bbName: 'KVStore',
+            bbVersion: '0.4.0',
+        });
+        const chain = childBB.testBuildUserAgentChain();
+        assert.deepStrictEqual(chain, [
+            ['aws-blocks', CORE_VERSION],
+            ['bb', 'AuthBasic/1.0.1'],
+            ['bb', 'KVStore/0.4.0'],
+        ]);
+    });
+    // ── Edge case: bbName set but bbVersion missing ───────────────────────
+    test('self not added to chain when bbVersion is missing', () => {
+        const root = { id: 'my-app' };
+        const bb = new TestBB('store', {
+            parent: root,
+            bbName: 'KVStore',
+            // bbVersion missing
+        });
+        const chain = bb.testBuildUserAgentChain();
+        assert.deepStrictEqual(chain, [
+            ['aws-blocks', CORE_VERSION],
+        ]);
+    });
+    // ── Edge case: bbVersion set but bbName missing ───────────────────────
+    test('self not added to chain when bbName is missing', () => {
+        const root = { id: 'my-app' };
+        const bb = new TestBB('store', {
+            parent: root,
+            // bbName missing
+            bbVersion: '0.4.0',
+        });
+        const chain = bb.testBuildUserAgentChain();
+        assert.deepStrictEqual(chain, [
+            ['aws-blocks', CORE_VERSION],
+        ]);
+    });
+    // ── Edge case: neither bbName nor bbVersion set ───────────────────────
+    test('self not added to chain when neither bbName nor bbVersion is set', () => {
+        const root = { id: 'my-app' };
+        const bb = new TestBB('store', {
+            parent: root,
+        });
+        const chain = bb.testBuildUserAgentChain();
+        assert.deepStrictEqual(chain, [
+            ['aws-blocks', CORE_VERSION],
+        ]);
+    });
+    // ── Edge case: parent with only bbName (no bbVersion) is skipped ──────
+    test('parent with bbName but no bbVersion is skipped', () => {
+        const root = { id: 'my-app' };
+        const parentPartial = new TestBB('partial', {
+            parent: root,
+            bbName: 'PartialBB',
+            // bbVersion missing
+        });
+        const childBB = new TestBB('store', {
+            parent: parentPartial,
+            bbName: 'KVStore',
+            bbVersion: '0.4.0',
+        });
+        const chain = childBB.testBuildUserAgentChain();
+        assert.deepStrictEqual(chain, [
+            ['aws-blocks', CORE_VERSION],
+            ['bb', 'KVStore/0.4.0'],
+        ]);
+    });
+    // ── Verifies CORE_VERSION is used as the aws-blocks version ───────────
+    test('CORE_VERSION is used as the aws-blocks version', () => {
+        const root = { id: 'my-app' };
+        const bb = new TestBB('store', {
+            parent: root,
+            bbName: 'KVStore',
+            bbVersion: '1.0.0',
+        });
+        const chain = bb.testBuildUserAgentChain();
+        assert.strictEqual(chain[0][0], 'aws-blocks');
+        assert.strictEqual(chain[0][1], CORE_VERSION);
+    });
+});

package/dist/common/mock-data.d.ts

@@ -0,0 +1,40 @@
+import type { Scope } from './index.js';
+/**
+ * Options for {@link getMockDataDir}.
+ */
+export interface MockDataDirOptions {
+    /**
+     * When true, returns the root `.bb-data/` directory without appending
+     * the scope's fullId. Use this to consolidate all data from a single resource
+     * type into a single file or folder. E.g., `settings.json`.
+     */
+    root?: boolean;
+}
+/**
+ * Returns the mock data directory for a Building Block instance, creating it
+ * if it doesn't already exist.
+ *
+ * Resolves to `<cwd>/.bb-data/{scope.fullId}/` by default. The BB owns this
+ * folder and can store whatever files it needs inside it.
+ *
+ * If `root: true` are specified, returns `<cwd>/.bb-data/`. The BB must then
+ * take responsibility not to conflict with other files and folders.
+ *
+ * @param scope - The Building Block's Scope instance.
+ * @param options - Optional configuration.
+ * @returns Absolute path to the BB's data directory (guaranteed to exist).
+ *
+ * @example
+ * ```typescript
+ * const dir = getMockDataDir(this);
+ * const filePath = join(dir, 'store.json');
+ * ```
+ *
+ * @example Root directory for shared files
+ * ```typescript
+ * const dir = getMockDataDir(this, { root: true });
+ * const settingsPath = join(dir, 'settings.json');
+ * ```
+ */
+export declare function getMockDataDir(scope: Scope, options?: MockDataDirOptions): string;
+//# sourceMappingURL=mock-data.d.ts.map

package/dist/common/mock-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-data.d.ts","sourceRoot":"","sources":["../../src/common/mock-data.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAMjF"}

package/dist/common/mock-data.js

@@ -0,0 +1,39 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { join } from 'node:path';
+import { existsSync, mkdirSync } from 'node:fs';
+/**
+ * Returns the mock data directory for a Building Block instance, creating it
+ * if it doesn't already exist.
+ *
+ * Resolves to `<cwd>/.bb-data/{scope.fullId}/` by default. The BB owns this
+ * folder and can store whatever files it needs inside it.
+ *
+ * If `root: true` are specified, returns `<cwd>/.bb-data/`. The BB must then
+ * take responsibility not to conflict with other files and folders.
+ *
+ * @param scope - The Building Block's Scope instance.
+ * @param options - Optional configuration.
+ * @returns Absolute path to the BB's data directory (guaranteed to exist).
+ *
+ * @example
+ * ```typescript
+ * const dir = getMockDataDir(this);
+ * const filePath = join(dir, 'store.json');
+ * ```
+ *
+ * @example Root directory for shared files
+ * ```typescript
+ * const dir = getMockDataDir(this, { root: true });
+ * const settingsPath = join(dir, 'settings.json');
+ * ```
+ */
+export function getMockDataDir(scope, options) {
+    const segments = [process.cwd(), '.bb-data'];
+    if (!options?.root)
+        segments.push(scope.fullId);
+    const dir = join(...segments);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    return dir;
+}

package/dist/common/official-bb-names.generated.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Set of official Building Block display names recognized by telemetry.
+ * Any BB whose `bbName` matches one of these entries is reported in the
+ * `product.buildingBlocks` array; others still contribute to `totalCount`.
+ */
+export declare const OFFICIAL_BB_NAMES: ReadonlySet<string>;
+//# sourceMappingURL=official-bb-names.generated.d.ts.map

package/dist/common/official-bb-names.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"official-bb-names.generated.d.ts","sourceRoot":"","sources":["../../src/common/official-bb-names.generated.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAoBhD,CAAC"}

package/dist/common/official-bb-names.generated.js

@@ -0,0 +1,28 @@
+// DO NOT EDIT — auto-generated by scripts/generate-bb-names.mjs
+// Source: packages/blocks/package.json → aws-blocks.vendorize
+/**
+ * Set of official Building Block display names recognized by telemetry.
+ * Any BB whose `bbName` matches one of these entries is reported in the
+ * `product.buildingBlocks` array; others still contribute to `totalCount`.
+ */
+export const OFFICIAL_BB_NAMES = new Set([
+    'Agent',
+    'AppSetting',
+    'AsyncJob',
+    'AuthBasic',
+    'AuthCognito',
+    'AuthOidc',
+    'CronJob',
+    'Dashboard',
+    'Database',
+    'DistributedDatabase',
+    'DistributedTable',
+    'EmailClient',
+    'FileBucket',
+    'KVStore',
+    'KnowledgeBase',
+    'Logger',
+    'Metrics',
+    'Realtime',
+    'Tracer',
+]);

package/dist/common/sdk-registry.d.ts

@@ -0,0 +1,136 @@
+/**
+ * SDK Identifier Registry — centralized map of Building Block AWS resource identifiers.
+ *
+ * Each Building Block registers its AWS resource identifiers (table names, bucket names,
+ * queue URLs, etc.) upon construction. Application code retrieves these identifiers via
+ * {@link getSdkIdentifiers} to interact with BB-managed resources using the raw AWS SDK.
+ *
+ * This module serves a complementary role to `mock-data.ts`:
+ * - `mock-data.ts` → provides local file paths for mock persistence (`.bb-data/`)
+ * - `sdk-registry.ts` → provides AWS resource identifiers for SDK access
+ *
+ * Together, these two modules form the runtime discovery layer — `mock-data.ts` for
+ * local development, and `sdk-registry.ts` for deployed AWS environments.
+ *
+ * @see {@link docs/guides/extending-with-existing-aws-resources.md} — "SDK Identifiers" section
+ * @module
+ */
+type ResourceEntry = Record<string, string>;
+/**
+ * Register SDK identifiers for a Building Block instance.
+ *
+ * Called internally by Building Blocks during construction — **not intended for
+ * application code**. Each BB registers its resolved AWS resource identifiers
+ * (e.g., DynamoDB table name, S3 bucket name) so they can be retrieved later
+ * via {@link getSdkIdentifiers}.
+ *
+ * If the same `fullId` is registered multiple times (e.g., a BB that manages
+ * multiple resources), entries are merged — later calls augment rather than
+ * replace earlier ones.
+ *
+ * @param fullId - The Building Block's fully-qualified scope ID (e.g., `"myapp-users"`).
+ * @param identifiers - Key-value map of resource identifiers to register.
+ *
+ * @example
+ * ```typescript
+ * // Inside a Building Block constructor (internal use only):
+ * registerSdkIdentifiers(this.fullId, { tableName: 'myapp-users' });
+ * ```
+ */
+export declare function registerSdkIdentifiers(fullId: string, identifiers: ResourceEntry): void;
+/**
+ * Retrieve the SDK identifiers for a specific Building Block instance.
+ *
+ * This is the base (untyped) version that returns `Record<string, string>`.
+ * For full type safety with per-BB return types, import the overloaded
+ * `getSdkIdentifiers` from `@aws-blocks/blocks` instead.
+ *
+ * @param bb - Any object with a `fullId` property (typically a Building Block instance).
+ * @returns A record of the BB's registered resource identifiers.
+ *
+ * @example
+ * ```typescript
+ * import { getSdkIdentifiers } from '@aws-blocks/blocks';
+ * import { KVStore } from '@aws-blocks/bb-kv-store';
+ * import { DynamoDBClient, QueryCommand } from '@aws-sdk/client-dynamodb';
+ *
+ * const store = new KVStore(scope, 'users', {});
+ *
+ * // Retrieve the underlying DynamoDB table name (typed via overloads)
+ * const { tableName } = getSdkIdentifiers(store);
+ *
+ * // Use it with the raw AWS SDK for advanced operations
+ * const client = new DynamoDBClient({});
+ * const result = await client.send(new QueryCommand({
+ *   TableName: tableName,
+ *   KeyConditionExpression: 'pk = :pk',
+ *   ExpressionAttributeValues: { ':pk': { S: 'user#123' } },
+ * }));
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { getSdkIdentifiers } from '@aws-blocks/blocks';
+ * import { FileBucket } from '@aws-blocks/bb-file-bucket';
+ * import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3';
+ * import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+ *
+ * const bucket = new FileBucket(scope, 'uploads', {});
+ * const { bucketName } = getSdkIdentifiers(bucket);
+ *
+ * // Generate a presigned download URL
+ * const url = await getSignedUrl(
+ *   new S3Client({}),
+ *   new GetObjectCommand({ Bucket: bucketName, Key: 'report.pdf' }),
+ *   { expiresIn: 3600 },
+ * );
+ * ```
+ */
+export declare function getSdkIdentifiers(bb: {
+    fullId: string;
+}): Record<string, string>;
+/**
+ * Return a read-only snapshot of all registered SDK identifiers.
+ *
+ * Primarily useful for debugging, tooling, and diagnostics — lists every
+ * Building Block that has registered identifiers in the current process.
+ * The returned map is keyed by `fullId` with each value being the identifier
+ * record for that BB.
+ *
+ * @returns A read-only `Map<fullId, identifiers>` of all registered entries.
+ *
+ * @example
+ * ```typescript
+ * import { getAllSdkIdentifiers } from '@aws-blocks/core';
+ *
+ * // Log all registered identifiers for debugging
+ * for (const [fullId, ids] of getAllSdkIdentifiers()) {
+ *   console.log(`${fullId}:`, ids);
+ * }
+ * // Output:
+ * //   myapp-users: { tableName: 'myapp-users' }
+ * //   myapp-uploads: { bucketName: 'myapp-uploads' }
+ * //   myapp-auth: { userPoolId: 'us-east-1_abc', clientId: '123abc' }
+ * ```
+ */
+export declare function getAllSdkIdentifiers(): ReadonlyMap<string, ResourceEntry>;
+/**
+ * Clear the SDK identifier registry. **For test cleanup only.**
+ *
+ * Resets the global registry to an empty state. Use this in test teardown
+ * (`afterEach`) to prevent state leakage between test cases that construct
+ * Building Blocks.
+ *
+ * @example
+ * ```typescript
+ * import { _resetSdkRegistry } from '@aws-blocks/core';
+ * import { afterEach } from 'node:test';
+ *
+ * afterEach(() => {
+ *   _resetSdkRegistry();
+ * });
+ * ```
+ */
+export declare function _resetSdkRegistry(): void;
+export {};
+//# sourceMappingURL=sdk-registry.d.ts.map

package/dist/common/sdk-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-registry.d.ts","sourceRoot":"","sources":["../../src/common/sdk-registry.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AAEH,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAI5C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,GAAG,IAAI,CAEvF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEhF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,IAAI,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAEzE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}

package/dist/common/sdk-registry.js

@@ -0,0 +1,125 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+const registry = new Map();
+/**
+ * Register SDK identifiers for a Building Block instance.
+ *
+ * Called internally by Building Blocks during construction — **not intended for
+ * application code**. Each BB registers its resolved AWS resource identifiers
+ * (e.g., DynamoDB table name, S3 bucket name) so they can be retrieved later
+ * via {@link getSdkIdentifiers}.
+ *
+ * If the same `fullId` is registered multiple times (e.g., a BB that manages
+ * multiple resources), entries are merged — later calls augment rather than
+ * replace earlier ones.
+ *
+ * @param fullId - The Building Block's fully-qualified scope ID (e.g., `"myapp-users"`).
+ * @param identifiers - Key-value map of resource identifiers to register.
+ *
+ * @example
+ * ```typescript
+ * // Inside a Building Block constructor (internal use only):
+ * registerSdkIdentifiers(this.fullId, { tableName: 'myapp-users' });
+ * ```
+ */
+export function registerSdkIdentifiers(fullId, identifiers) {
+    registry.set(fullId, { ...registry.get(fullId), ...identifiers });
+}
+/**
+ * Retrieve the SDK identifiers for a specific Building Block instance.
+ *
+ * This is the base (untyped) version that returns `Record<string, string>`.
+ * For full type safety with per-BB return types, import the overloaded
+ * `getSdkIdentifiers` from `@aws-blocks/blocks` instead.
+ *
+ * @param bb - Any object with a `fullId` property (typically a Building Block instance).
+ * @returns A record of the BB's registered resource identifiers.
+ *
+ * @example
+ * ```typescript
+ * import { getSdkIdentifiers } from '@aws-blocks/blocks';
+ * import { KVStore } from '@aws-blocks/bb-kv-store';
+ * import { DynamoDBClient, QueryCommand } from '@aws-sdk/client-dynamodb';
+ *
+ * const store = new KVStore(scope, 'users', {});
+ *
+ * // Retrieve the underlying DynamoDB table name (typed via overloads)
+ * const { tableName } = getSdkIdentifiers(store);
+ *
+ * // Use it with the raw AWS SDK for advanced operations
+ * const client = new DynamoDBClient({});
+ * const result = await client.send(new QueryCommand({
+ *   TableName: tableName,
+ *   KeyConditionExpression: 'pk = :pk',
+ *   ExpressionAttributeValues: { ':pk': { S: 'user#123' } },
+ * }));
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { getSdkIdentifiers } from '@aws-blocks/blocks';
+ * import { FileBucket } from '@aws-blocks/bb-file-bucket';
+ * import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3';
+ * import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+ *
+ * const bucket = new FileBucket(scope, 'uploads', {});
+ * const { bucketName } = getSdkIdentifiers(bucket);
+ *
+ * // Generate a presigned download URL
+ * const url = await getSignedUrl(
+ *   new S3Client({}),
+ *   new GetObjectCommand({ Bucket: bucketName, Key: 'report.pdf' }),
+ *   { expiresIn: 3600 },
+ * );
+ * ```
+ */
+export function getSdkIdentifiers(bb) {
+    return registry.get(bb.fullId) ?? {};
+}
+/**
+ * Return a read-only snapshot of all registered SDK identifiers.
+ *
+ * Primarily useful for debugging, tooling, and diagnostics — lists every
+ * Building Block that has registered identifiers in the current process.
+ * The returned map is keyed by `fullId` with each value being the identifier
+ * record for that BB.
+ *
+ * @returns A read-only `Map<fullId, identifiers>` of all registered entries.
+ *
+ * @example
+ * ```typescript
+ * import { getAllSdkIdentifiers } from '@aws-blocks/core';
+ *
+ * // Log all registered identifiers for debugging
+ * for (const [fullId, ids] of getAllSdkIdentifiers()) {
+ *   console.log(`${fullId}:`, ids);
+ * }
+ * // Output:
+ * //   myapp-users: { tableName: 'myapp-users' }
+ * //   myapp-uploads: { bucketName: 'myapp-uploads' }
+ * //   myapp-auth: { userPoolId: 'us-east-1_abc', clientId: '123abc' }
+ * ```
+ */
+export function getAllSdkIdentifiers() {
+    return new Map(registry);
+}
+/**
+ * Clear the SDK identifier registry. **For test cleanup only.**
+ *
+ * Resets the global registry to an empty state. Use this in test teardown
+ * (`afterEach`) to prevent state leakage between test cases that construct
+ * Building Blocks.
+ *
+ * @example
+ * ```typescript
+ * import { _resetSdkRegistry } from '@aws-blocks/core';
+ * import { afterEach } from 'node:test';
+ *
+ * afterEach(() => {
+ *   _resetSdkRegistry();
+ * });
+ * ```
+ */
+export function _resetSdkRegistry() {
+    registry.clear();
+}

package/dist/constants.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Reserved namespace for AWS-managed framework features.
+ * No user routes can be registered under this path.
+ */
+export declare const BLOCKS_NAMESPACE = "/aws-blocks";
+/**
+ * URL path prefix for the Blocks RPC endpoint.
+ *
+ * CloudFront behaviors route this path (and children) to the API Gateway
+ * origin. Namespaced under `/aws-blocks/api` so it doesn't shadow
+ * framework-conventional `/api/*` SSR routes (Next.js `pages/api/*`,
+ * `app/api/*`, Nuxt `server/api/*`) on CloudFront's first-match-wins
+ * behavior resolution.
+ */
+export declare const BLOCKS_RPC_PREFIX = "/aws-blocks/api";
+/**
+ * Reserved subtree for the auth Building Block's HTTP routes.
+ *
+ * Like {@link BLOCKS_RPC_PREFIX}, this lives under the reserved `/aws-blocks`
+ * namespace so Hosting can proxy the whole auth flow (callback, sign-in,
+ * exchange, authorize-params, the stub IdP, …) to the API Gateway origin with a
+ * single CloudFront behavior — and so it never collides with a customer's own
+ * `/auth/*` frontend routes. The auth BB mounts every route it owns under this
+ * prefix; CloudFront forwards the subtree and the Lambda dispatches by path.
+ */
+export declare const BLOCKS_AUTH_PREFIX = "/aws-blocks/auth";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,eAAO,MAAM,gBAAgB,gBAAgB,CAAC;AAE9C;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AAEnD;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,qBAAqB,CAAC"}

package/dist/constants.js

@@ -0,0 +1,28 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Reserved namespace for AWS-managed framework features.
+ * No user routes can be registered under this path.
+ */
+export const BLOCKS_NAMESPACE = '/aws-blocks';
+/**
+ * URL path prefix for the Blocks RPC endpoint.
+ *
+ * CloudFront behaviors route this path (and children) to the API Gateway
+ * origin. Namespaced under `/aws-blocks/api` so it doesn't shadow
+ * framework-conventional `/api/*` SSR routes (Next.js `pages/api/*`,
+ * `app/api/*`, Nuxt `server/api/*`) on CloudFront's first-match-wins
+ * behavior resolution.
+ */
+export const BLOCKS_RPC_PREFIX = '/aws-blocks/api';
+/**
+ * Reserved subtree for the auth Building Block's HTTP routes.
+ *
+ * Like {@link BLOCKS_RPC_PREFIX}, this lives under the reserved `/aws-blocks`
+ * namespace so Hosting can proxy the whole auth flow (callback, sign-in,
+ * exchange, authorize-params, the stub IdP, …) to the API Gateway origin with a
+ * single CloudFront behavior — and so it never collides with a customer's own
+ * `/auth/*` frontend routes. The auth BB mounts every route it owns under this
+ * prefix; CloudFront forwards the subtree and the Lambda dispatches by path.
+ */
+export const BLOCKS_AUTH_PREFIX = '/aws-blocks/auth';