@aws-blocks/core 0.1.0

package/dist/common/config.test.js

@@ -0,0 +1,173 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { getConfig, getConfigSync, loadConfigToProcessEnv, preloadConfig, _resetConfigCache, _setS3Fetcher } from './config.js';
+beforeEach(() => {
+    _resetConfigCache();
+    delete process.env.BLOCKS_CONFIG_BUCKET;
+    delete process.env.BLOCKS_CONFIG_KEY;
+});
+afterEach(() => {
+    _resetConfigCache();
+    delete process.env.BLOCKS_CONFIG_BUCKET;
+    delete process.env.BLOCKS_CONFIG_KEY;
+});
+describe('config — no S3 env vars (local dev)', () => {
+    it('getConfig returns empty string when key not in env', async () => {
+        const result = await getConfig('SOME_KEY');
+        assert.strictEqual(result, '');
+    });
+    it('getConfig returns env var value when set', async () => {
+        process.env.MY_KEY = 'my-value';
+        const result = await getConfig('MY_KEY');
+        assert.strictEqual(result, 'my-value');
+        delete process.env.MY_KEY;
+    });
+    it('loadConfigToProcessEnv does not throw when no S3 vars', async () => {
+        await assert.doesNotReject(() => loadConfigToProcessEnv());
+    });
+    it('preloadConfig does not throw when no S3 vars', async () => {
+        await assert.doesNotReject(() => preloadConfig());
+    });
+    it('getConfigSync returns env var value', () => {
+        process.env.SYNC_KEY = 'sync-value';
+        const result = getConfigSync('SYNC_KEY');
+        assert.strictEqual(result, 'sync-value');
+        delete process.env.SYNC_KEY;
+    });
+    it('getConfigSync returns empty string for unknown key', () => {
+        const result = getConfigSync('UNKNOWN');
+        assert.strictEqual(result, '');
+    });
+});
+describe('config — S3 load success', () => {
+    it('loads config from S3 and caches it', async () => {
+        process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+        process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+        let callCount = 0;
+        _setS3Fetcher(async () => {
+            callCount++;
+            return JSON.stringify({ DB_URL: 'postgres://localhost', QUEUE_ARN: 'arn:aws:sqs:us-east-1:123:queue' });
+        });
+        const result = await getConfig('DB_URL');
+        assert.strictEqual(result, 'postgres://localhost');
+        const result2 = await getConfig('QUEUE_ARN');
+        assert.strictEqual(result2, 'arn:aws:sqs:us-east-1:123:queue');
+        assert.strictEqual(callCount, 1, 'S3 should only be called once (cached)');
+    });
+    it('loadConfigToProcessEnv injects values into process.env', async () => {
+        process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+        process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+        _setS3Fetcher(async () => JSON.stringify({ INJECTED_KEY: 'injected-value' }));
+        await loadConfigToProcessEnv();
+        assert.strictEqual(process.env.INJECTED_KEY, 'injected-value');
+        delete process.env.INJECTED_KEY;
+    });
+    it('loadConfigToProcessEnv does not override existing env vars', async () => {
+        process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+        process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+        process.env.EXISTING_KEY = 'original';
+        _setS3Fetcher(async () => JSON.stringify({ EXISTING_KEY: 'from-s3' }));
+        await loadConfigToProcessEnv();
+        assert.strictEqual(process.env.EXISTING_KEY, 'original');
+        delete process.env.EXISTING_KEY;
+    });
+    it('getConfigSync returns cached value after load', async () => {
+        process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+        process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+        _setS3Fetcher(async () => JSON.stringify({ CACHED_KEY: 'cached-value' }));
+        await preloadConfig();
+        const result = getConfigSync('CACHED_KEY');
+        assert.strictEqual(result, 'cached-value');
+    });
+});
+describe('config — S3 errors', () => {
+    it('gracefully handles NoSuchKey (file not yet written)', async () => {
+        process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+        process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+        const noSuchKeyError = new Error('The specified key does not exist.');
+        noSuchKeyError.name = 'NoSuchKey';
+        _setS3Fetcher(async () => { throw noSuchKeyError; });
+        const result = await getConfig('ANY_KEY');
+        assert.strictEqual(result, '', 'Should return empty string (empty config) on NoSuchKey');
+    });
+    it('gracefully handles S3 404 status code', async () => {
+        process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+        process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+        const notFoundError = new Error('Not Found');
+        notFoundError.$metadata = { httpStatusCode: 404 };
+        _setS3Fetcher(async () => { throw notFoundError; });
+        const result = await getConfig('ANY_KEY');
+        assert.strictEqual(result, '', 'Should return empty string (empty config) on 404');
+    });
+    it('throws with clear message on S3 network error', async () => {
+        process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+        process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+        _setS3Fetcher(async () => { throw new Error('Network timeout'); });
+        await assert.rejects(() => getConfig('ANY_KEY'), (err) => {
+            assert.ok(err.message.includes('[Blocks] Failed to load config from S3'));
+            assert.ok(err.message.includes('test-bucket/blocks-config.json'));
+            assert.ok(err.message.includes('Network timeout'));
+            return true;
+        });
+    });
+    it('throws on empty config file', async () => {
+        process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+        process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+        _setS3Fetcher(async () => { throw new Error('Empty config file'); });
+        await assert.rejects(() => getConfig('ANY_KEY'), (err) => {
+            assert.ok(err.message.includes('[Blocks] Failed to load config from S3'));
+            assert.ok(err.message.includes('Empty config file'));
+            return true;
+        });
+    });
+    it('throws on malformed JSON', async () => {
+        process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+        process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+        _setS3Fetcher(async () => 'not valid json {{{');
+        await assert.rejects(() => getConfig('ANY_KEY'), (err) => {
+            assert.ok(err.message.includes('[Blocks] Failed to load config from S3'));
+            return true;
+        });
+    });
+    it('throws when config is an array instead of object', async () => {
+        process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+        process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+        _setS3Fetcher(async () => '["not", "an", "object"]');
+        await assert.rejects(() => getConfig('ANY_KEY'), (err) => {
+            assert.ok(err.message.includes('[Blocks] Config file must be a JSON object'));
+            return true;
+        });
+    });
+    it('throws when config is null', async () => {
+        process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+        process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+        _setS3Fetcher(async () => 'null');
+        await assert.rejects(() => getConfig('ANY_KEY'), (err) => {
+            assert.ok(err.message.includes('[Blocks] Config file must be a JSON object'));
+            return true;
+        });
+    });
+});
+describe('config — concurrent access', () => {
+    it('deduplicates concurrent calls to the same S3 fetch', async () => {
+        process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+        process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+        let callCount = 0;
+        _setS3Fetcher(async () => {
+            callCount++;
+            await new Promise(r => setTimeout(r, 50));
+            return JSON.stringify({ KEY_A: 'value-a' });
+        });
+        const [r1, r2, r3] = await Promise.all([
+            getConfig('KEY_A'),
+            getConfig('KEY_A'),
+            getConfig('KEY_A'),
+        ]);
+        assert.strictEqual(r1, 'value-a');
+        assert.strictEqual(r2, 'value-a');
+        assert.strictEqual(r3, 'value-a');
+        assert.strictEqual(callCount, 1, 'S3 should only be called once even with concurrent access');
+    });
+});

package/dist/common/constants.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared constants used across the Blocks framework.
+ *
+ * Centralizes magic strings so directory names and conventions
+ * can be updated in one place.
+ */
+/** Directory where sandbox/deploy config is written (relative to project root). */
+export declare const BLOCKS_SANDBOX_DIR = ".blocks-sandbox";
+/** Default backend entry point directory name. */
+export declare const BLOCKS_BACKEND_DIR = "aws-blocks";
+//# sourceMappingURL=constants.d.ts.map

package/dist/common/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/common/constants.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH,mFAAmF;AACnF,eAAO,MAAM,kBAAkB,oBAAoB,CAAC;AAEpD,kDAAkD;AAClD,eAAO,MAAM,kBAAkB,eAAe,CAAC"}

package/dist/common/constants.js

@@ -0,0 +1,12 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Shared constants used across the Blocks framework.
+ *
+ * Centralizes magic strings so directory names and conventions
+ * can be updated in one place.
+ */
+/** Directory where sandbox/deploy config is written (relative to project root). */
+export const BLOCKS_SANDBOX_DIR = '.blocks-sandbox';
+/** Default backend entry point directory name. */
+export const BLOCKS_BACKEND_DIR = 'aws-blocks';

package/dist/common/crypto.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Compares two strings in constant time to prevent timing side-channel attacks.
+ * Use this for HMAC signature validation — never use === or !== for crypto comparisons.
+ */
+export declare function constantTimeEquals(a: string, b: string): boolean;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/common/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/common/crypto.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAKhE"}

package/dist/common/crypto.js

@@ -0,0 +1,14 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { timingSafeEqual } from 'node:crypto';
+/**
+ * Compares two strings in constant time to prevent timing side-channel attacks.
+ * Use this for HMAC signature validation — never use === or !== for crypto comparisons.
+ */
+export function constantTimeEquals(a, b) {
+    const ab = Buffer.from(a, 'utf8');
+    const bb = Buffer.from(b, 'utf8');
+    if (ab.length !== bb.length)
+        return false;
+    return timingSafeEqual(ab, bb);
+}

package/dist/common/index.d.ts

@@ -0,0 +1,220 @@
+import type { StackProps } from 'aws-cdk-lib';
+import type { Construct } from 'constructs';
+export { OFFICIAL_BB_NAMES } from './official-bb-names.generated.js';
+export interface ScopeOptions {
+    parent?: ScopeParent;
+    bbName?: string;
+    bbVersion?: string;
+}
+export type ScopeParent = Scope | {
+    id: string;
+};
+/**
+ * Scope defines a logical boundary for your backend resources.
+ *
+ * Building Blocks are instantiated within a scope. The scope provides namespacing and resource organization.
+ *
+ * ## Usage
+ *
+ * Create a scope at the top of your backend file:
+ *
+ * ```typescript
+ * import { Scope } from '@aws-blocks/core';
+ *
+ * const scope = new Scope('my-app');
+ * ```
+ *
+ * Then instantiate Building Blocks within that scope:
+ *
+ * ```typescript
+ * import { KVStore } from '@aws-blocks/bb-kv-store';
+ *
+ * const store = new KVStore(scope, 'user-prefs', {});
+ * ```
+ *
+ * ## Available Building Blocks
+ *
+ * **IMPORTANT: Always use Blocks Building Blocks instead of creating your own storage, data structures, or AWS SDK calls.**
+ *
+ * Building Blocks provide:
+ * - **Local mocking** - Run in-process during development (`npm run dev`) with no AWS resources
+ * - **Production deployment** - Automatically provision and configure AWS resources (`npm run sandbox` or `npm run deploy`)
+ * - **Same code, both environments** - Your application logic works identically in local and production
+ *
+ * Each Building Block has comprehensive docstrings with use-cases, scaling characteristics, performance metrics, and best practices. Import and explore:
+ *
+ * - **`ApiNamespace`** from `@aws-blocks/core` - Define type-safe APIs with automatic frontend/backend integration
+ * - **`KVStore`** from `@aws-blocks/bb-kv-store` - Simple key-value storage (DynamoDB)
+ * - **`DistributedTable`** from `@aws-blocks/bb-distributed-table` - Type-safe tables with Zod schemas, indexes, and queries (DynamoDB)
+ * - **`AuthBasic`** from `@aws-blocks/bb-auth-basic` - Username/password authentication with JWT tokens and built-in UI components
+ * - **`Database`** from `@aws-blocks/bb-data` - SQL database with Kysely query builder (Aurora Serverless)
+ *
+ * Read each Building Block's class and method docstrings for detailed documentation.
+ *
+ * ## Choosing the Right Building Block
+ *
+ * **For authentication:**
+ * - Use `AuthBasic` for username/password auth (includes built-in UI component)
+ * - Provides JWT tokens, password hashing, and session management
+ *
+ * **For data storage, choose based on your access patterns:**
+ *
+ * - **`KVStore`** - Simple key-value lookups (user preferences, feature flags, session data)
+ *   - Get/set by key only
+ *   - No queries or indexes
+ *   - Simplest option
+ *
+ * - **`DistributedTable`** - Structured data with queries and indexes
+ *   - Query by partition key with optional filtering
+ *   - Secondary indexes for alternate access patterns
+ *   - Supports filtering, sorting, pagination
+ *   - Use Zod schemas for type safety
+ *   - **Zero cost to start, highly scalable**
+ *   - **Default choice for most application data**
+ *
+ * - **`Database`** - SQL database with full relational features
+ *   - Use when you need: complex multi-table JOINs, SQL transactions across tables, foreign key constraints
+ *   - Avoid when: DynamoDB limitations are acceptable (no ad-hoc queries, eventual consistency on indexes, 400KB item limit)
+ *   - Requires migrations folder with .sql files
+ *   - Local dev requires manual schema setup (see Database README)
+ *   - Higher baseline cost than DistributedTable
+ *
+ * **Rule of thumb:** Use DistributedTable unless you specifically need SQL JOINs or transactions.
+ *
+ * ## Data Modeling
+ *
+ * - **For DistributedTable**: Use Zod schemas for runtime validation and type inference. Install: `npm install zod`
+ *   - For flexible key-value fields: `z.record(z.string(), z.any())`
+ * - **For Database**: Define TypeScript interfaces and create migrations folder with .sql files
+ * - **For KVStore**: Store strings only (serialize objects as JSON)
+ *
+ * ## Local Development
+ *
+ * In local dev mode (`npm run dev`), Building Blocks run in-process with mock implementations.
+ * No AWS resources are created. State is ephemeral.
+ *
+ * ## Deployed to AWS
+ *
+ * When deployed (`npm run sandbox` or `npm run deploy`), Blocks provisions real AWS resources:
+ * - Lambda functions for your APIs
+ * - DynamoDB tables for KVStore and DistributedTable
+ * - Aurora Serverless for Database
+ * - S3 buckets for file storage
+ * - IAM roles and policies
+ *
+ * Infrastructure is **inferred from your code**. You write application logic; Blocks determines
+ * what AWS resources are needed and provisions them automatically.
+ *
+ * ## Best Practices
+ *
+ * - Use one scope per application or major feature boundary
+ * - Give scopes descriptive IDs (e.g., 'user-service', 'orders')
+ * - Nest scopes for complex applications using the `parent` option
+ * - Always use Building Blocks for storage - never create your own in-memory Maps or custom storage
+ */
+/**
+ * Metadata identifying a Building Block for user-agent attribution.
+ * BBs that want to participate in user-agent chains must set these on their class.
+ */
+export interface BuildingBlockMeta {
+    /** Short BB name used in user-agent strings, e.g. "KVStore", "AuthCognito" */
+    readonly bbName: string;
+    /** Package version from the BB's own package.json (build-time generated) */
+    readonly bbVersion: string;
+}
+export declare class Scope {
+    readonly id: string;
+    readonly parent: ScopeParent;
+    /** Short BB name used in user-agent strings. Set by subclass BBs. */
+    readonly bbName?: string;
+    /** Package version from the BB's own package.json. Set by subclass BBs. */
+    readonly bbVersion?: string;
+    /** Static registry — collects BB names as they're instantiated */
+    private static _bbRegistry;
+    constructor(id: string, options?: ScopeOptions);
+    /**
+     * Get registered BBs filtered for telemetry privacy.
+     *
+     * Only official BB names (in OFFICIAL_BB_NAMES) are returned in `blocks`.
+     * Custom BBs are counted in `customBlocksCount` but their names are never exposed.
+     *
+     * @returns Official blocks, total instance count, and total number of custom BB instances.
+     * @internal
+     */
+    static getRegisteredBlocks(): {
+        blocks: Array<{
+            name: string;
+            version: string;
+        }>;
+        totalCount: number;
+        customBlocksCount: number;
+    };
+    /** Reset registry (useful for testing). */
+    static _resetRegistry(): void;
+    get fullId(): string;
+    /**
+     * Register a Lambda event handler for non-HTTP events (e.g., SQS, WebSocket).
+     * The handler receives the raw Lambda event record and processes it.
+     * Used by Building Blocks that consume event sources (e.g., AsyncJob → SQS,
+     * Realtime → API Gateway WebSocket).
+     *
+     * @param eventSource - Event source prefix (e.g., 'blocks.asyncjob', 'blocks.websocket').
+     * @param identifier - Building Block's fullId (scope-qualified ID, e.g., 'myapp-rt').
+     *                     Combined with eventSource to form the registry key '{eventSource}:{identifier}'.
+     * @param handler - Async function that processes the raw Lambda event.
+     */
+    registerLambdaEventHandler(eventSource: string, identifier: string, handler: (record: any) => Promise<void>): void;
+    /**
+     * Register a client middleware package to be imported in the generated browser client.
+     * Used by Building Blocks that need browser-side protocol support (e.g., Realtime WebSocket).
+     * Only has effect during codegen — pushes to a global collector if one is active.
+     */
+    registerClientMiddleware(packageSpecifier: string): void;
+    /**
+     * Register a dev server attachment package to be attached to the local HTTP server.
+     * Used by Building Blocks that need special local dev protocols (e.g., WebSocket server).
+     * Only has effect during dev server startup — pushes to a global collector if one is active.
+     *
+     * Dev attachments use an **explicit registration** pattern: the dev server imports
+     * the module and calls its exported `attach(server)` function, passing the HTTP
+     * server instance. This differs intentionally from client middleware, which uses
+     * self-registering side-effect imports — dev attachments need the server instance
+     * at registration time, which isn't available during a bare import.
+     */
+    registerDevAttachment(packageSpecifier: string): void;
+    /**
+     * Build the customUserAgent chain by walking the scope tree.
+     *
+     * Produces an array of `[key, value]` pairs suitable for passing directly
+     * to any AWS SDK v3 client's `customUserAgent` configuration option.
+     *
+     * The chain encodes the nesting hierarchy:
+     * - `['aws-blocks', coreVersion]` — always first
+     * - `['bb', 'ParentBB/parentVersion']` — if this BB is nested inside another BB
+     * - `['bb', 'SelfBB/selfVersion']` — the current BB
+     *
+     * @param coreVersion - The version of @aws-blocks/core
+     * @returns Array of [key, value] pairs for customUserAgent
+     *
+     * @example
+     * ```typescript
+     * const client = new DynamoDBClient({
+     *   customUserAgent: this.buildUserAgentChain(),
+     * });
+     * ```
+     */
+    protected buildUserAgentChain(): [string, string][];
+}
+export declare function computeScopeFullId(scope: {
+    id: string;
+    parent?: any;
+}): string;
+export interface BlocksStackProps extends StackProps {
+    backendHandlerPath: string;
+    backendCDKPath: string;
+}
+export declare class BlocksStack {
+    readonly id: string;
+    constructor(scope: Construct, id: string, props: BlocksStackProps);
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/common/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAErE,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsGG;AAEH;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,KAAK;IAChB,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,MAAM,EAAE,WAAW,CAAC;IAEpC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,kEAAkE;IAClE,OAAO,CAAC,MAAM,CAAC,WAAW,CAA8D;gBAE5E,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;IAiB9C;;;;;;;;OAQG;IACH,MAAM,CAAC,mBAAmB,IAAI;QAAE,MAAM,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE;IAejI,2CAA2C;IAC3C,MAAM,CAAC,cAAc,IAAI,IAAI;IAI7B,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;;;;;;;;OAUG;IACH,0BAA0B,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAOlH;;;;OAIG;IACH,wBAAwB,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAIxD;;;;;;;;;;OAUG;IACH,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAIrD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,CAAC,mBAAmB,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE;CAapD;AA0CD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,GAAG,CAAA;CAAE,UAUrE;AAED,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,WAAW;IACvB,SAAgB,EAAE,EAAE,MAAM,CAAC;gBACf,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB;CAGjE"}

package/dist/common/index.js

@@ -0,0 +1,180 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { CORE_VERSION } from '../version.js';
+import { OFFICIAL_BB_NAMES } from './official-bb-names.generated.js';
+export { OFFICIAL_BB_NAMES } from './official-bb-names.generated.js';
+export class Scope {
+    id;
+    parent;
+    /** Short BB name used in user-agent strings. Set by subclass BBs. */
+    bbName;
+    /** Package version from the BB's own package.json. Set by subclass BBs. */
+    bbVersion;
+    /** Static registry — collects BB names as they're instantiated */
+    static _bbRegistry = new Map();
+    constructor(id, options) {
+        this.id = id;
+        this.parent = options?.parent || globalThis.CURRENT_BLOCKS_STACK || {
+            id: typeof process !== 'undefined' ? process.env?.BLOCKS_STACK_NAME : undefined
+        };
+        if (options?.bbName) {
+            this.bbName = options.bbName;
+            this.bbVersion = options.bbVersion;
+            const existing = Scope._bbRegistry.get(options.bbName);
+            Scope._bbRegistry.set(options.bbName, {
+                version: options.bbVersion || 'unknown',
+                count: (existing?.count || 0) + 1,
+            });
+        }
+    }
+    /**
+     * Get registered BBs filtered for telemetry privacy.
+     *
+     * Only official BB names (in OFFICIAL_BB_NAMES) are returned in `blocks`.
+     * Custom BBs are counted in `customBlocksCount` but their names are never exposed.
+     *
+     * @returns Official blocks, total instance count, and total number of custom BB instances.
+     * @internal
+     */
+    static getRegisteredBlocks() {
+        const blocks = [];
+        let totalCount = 0;
+        let customBlocksCount = 0;
+        for (const [name, { version, count }] of Scope._bbRegistry.entries()) {
+            totalCount += count;
+            if (OFFICIAL_BB_NAMES.has(name)) {
+                blocks.push({ name, version });
+            }
+            else {
+                customBlocksCount += count;
+            }
+        }
+        return { blocks, totalCount, customBlocksCount };
+    }
+    /** Reset registry (useful for testing). */
+    static _resetRegistry() {
+        Scope._bbRegistry.clear();
+    }
+    get fullId() {
+        return computeScopeFullId(this);
+    }
+    /**
+     * Register a Lambda event handler for non-HTTP events (e.g., SQS, WebSocket).
+     * The handler receives the raw Lambda event record and processes it.
+     * Used by Building Blocks that consume event sources (e.g., AsyncJob → SQS,
+     * Realtime → API Gateway WebSocket).
+     *
+     * @param eventSource - Event source prefix (e.g., 'blocks.asyncjob', 'blocks.websocket').
+     * @param identifier - Building Block's fullId (scope-qualified ID, e.g., 'myapp-rt').
+     *                     Combined with eventSource to form the registry key '{eventSource}:{identifier}'.
+     * @param handler - Async function that processes the raw Lambda event.
+     */
+    registerLambdaEventHandler(eventSource, identifier, handler) {
+        if (!globalThis.__BLOCKS_LAMBDA_EVENT_HANDLERS__) {
+            globalThis.__BLOCKS_LAMBDA_EVENT_HANDLERS__ = new Map();
+        }
+        globalThis.__BLOCKS_LAMBDA_EVENT_HANDLERS__.set(`${eventSource}:${identifier}`, handler);
+    }
+    /**
+     * Register a client middleware package to be imported in the generated browser client.
+     * Used by Building Blocks that need browser-side protocol support (e.g., Realtime WebSocket).
+     * Only has effect during codegen — pushes to a global collector if one is active.
+     */
+    registerClientMiddleware(packageSpecifier) {
+        globalThis.__BLOCKS_CLIENT_MIDDLEWARE__?.push(packageSpecifier);
+    }
+    /**
+     * Register a dev server attachment package to be attached to the local HTTP server.
+     * Used by Building Blocks that need special local dev protocols (e.g., WebSocket server).
+     * Only has effect during dev server startup — pushes to a global collector if one is active.
+     *
+     * Dev attachments use an **explicit registration** pattern: the dev server imports
+     * the module and calls its exported `attach(server)` function, passing the HTTP
+     * server instance. This differs intentionally from client middleware, which uses
+     * self-registering side-effect imports — dev attachments need the server instance
+     * at registration time, which isn't available during a bare import.
+     */
+    registerDevAttachment(packageSpecifier) {
+        globalThis.__BLOCKS_DEV_ATTACHMENTS__?.push(packageSpecifier);
+    }
+    /**
+     * Build the customUserAgent chain by walking the scope tree.
+     *
+     * Produces an array of `[key, value]` pairs suitable for passing directly
+     * to any AWS SDK v3 client's `customUserAgent` configuration option.
+     *
+     * The chain encodes the nesting hierarchy:
+     * - `['aws-blocks', coreVersion]` — always first
+     * - `['bb', 'ParentBB/parentVersion']` — if this BB is nested inside another BB
+     * - `['bb', 'SelfBB/selfVersion']` — the current BB
+     *
+     * @param coreVersion - The version of @aws-blocks/core
+     * @returns Array of [key, value] pairs for customUserAgent
+     *
+     * @example
+     * ```typescript
+     * const client = new DynamoDBClient({
+     *   customUserAgent: this.buildUserAgentChain(),
+     * });
+     * ```
+     */
+    buildUserAgentChain() {
+        const chain = [['aws-blocks', CORE_VERSION]];
+        const parents = collectBBParents(this.parent);
+        for (const parent of parents) {
+            chain.push(['bb', `${parent.bbName}/${parent.bbVersion}`]);
+        }
+        if (this.bbName && this.bbVersion && OFFICIAL_BB_NAMES.has(this.bbName)) {
+            chain.push(['bb', `${this.bbName}/${this.bbVersion}`]);
+        }
+        return chain;
+    }
+}
+/**
+ * Walk up the scope tree collecting any parent that has BuildingBlockMeta.
+ * Returns them in root-to-leaf order (outermost parent first).
+ */
+function collectBBParents(parent) {
+    const result = [];
+    let current = parent;
+    while (current) {
+        if (isOfficialBuildingBlock(current)) {
+            result.unshift(current);
+        }
+        current = 'parent' in current ? current.parent : undefined;
+    }
+    return result;
+}
+function isBuildingBlock(obj) {
+    return (obj !== null &&
+        typeof obj === 'object' &&
+        'bbName' in obj &&
+        'bbVersion' in obj &&
+        typeof obj.bbName === 'string' &&
+        typeof obj.bbVersion === 'string');
+}
+/**
+ * Returns true if the object is a Building Block with an official AWS name.
+ * Custom BBs (with names not in the allowlist) return false, ensuring
+ * customer-chosen names never appear in user-agent telemetry.
+ */
+function isOfficialBuildingBlock(obj) {
+    return isBuildingBlock(obj) && OFFICIAL_BB_NAMES.has(obj.bbName);
+}
+export function computeScopeFullId(scope) {
+    if (scope.parent) {
+        if ('fullId' in scope.parent && scope.parent.fullId) {
+            return `${scope.parent.fullId}-${scope.id}`;
+        }
+        if ('id' in scope.parent && scope.parent.id) {
+            return `${scope.parent.id}-${scope.id}`;
+        }
+    }
+    return scope.id;
+}
+export class BlocksStack {
+    id;
+    constructor(scope, id, props) {
+        this.id = id;
+    }
+}

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

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

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

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