@aws-blocks/core 0.1.0

package/dist/cdk/index.js

@@ -0,0 +1,90 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import * as cdk from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { computeScopeFullId, } from '../common/index.js';
+import { setupBlocksInfra, BlocksBackend, assertCdkConditionActive } from './blocks-backend.js';
+import { addBlocksStackMetadata } from './stack-metadata.js';
+import { finalizeConfigRegistry } from './config-registry.js';
+export { BlocksBackend } from './blocks-backend.js';
+export { DEFAULT_NODE_RUNTIME } from './node-version.js';
+export { SandboxDisableDeletionProtection } from './mixins.js';
+export { registerConfig, finalizeConfigRegistry } from './config-registry.js';
+export { synthGuard } from './synth-guard.js';
+export { ApiError, isBlocksError } from '../errors.js';
+export class BlocksStack extends cdk.Stack {
+    id;
+    apiUrl;
+    gateway;
+    handler;
+    backendHandlerPath;
+    constructor(scope, id, props) {
+        super(scope, id, props);
+        this.id = id;
+        this.backendHandlerPath = props.backendHandlerPath;
+        // Set globalThis so Building Blocks attach directly to this stack
+        globalThis.CURRENT_BLOCKS_STACK = this;
+        const infra = setupBlocksInfra(this, props, id);
+        this.handler = infra.handler;
+        this.gateway = infra.gateway;
+        this.apiUrl = infra.apiUrl;
+    }
+    static async create(scope, id, props) {
+        assertCdkConditionActive();
+        // Detect ambient pipeline stage scope set by Pipeline appFile imports
+        const pipelineScope = globalThis.__PIPELINE_STAGE_SCOPE__;
+        const actualScope = pipelineScope || scope;
+        const stack = new BlocksStack(actualScope, id, props);
+        // ESM caches modules by URL — append a unique query string so each stage re-executes the module body
+        const mod = await import(`${props.backendCDKPath}?stack=${id}`);
+        if (typeof mod.default === 'function') {
+            try {
+                await mod.default(stack);
+            }
+            catch (error) {
+                throw new Error(`Error executing default export function for stack "${id}": ${error instanceof Error ? error.message : error}`, { cause: error });
+            }
+        }
+        // Finalize BB config → S3 (after all BBs have registered their config)
+        finalizeConfigRegistry(stack, stack.handler);
+        new cdk.CfnOutput(stack, 'ApiUrl', { value: stack.apiUrl });
+        addBlocksStackMetadata(stack);
+        return stack;
+    }
+}
+export class Scope extends Construct {
+    id;
+    parent;
+    bbName;
+    bbVersion;
+    constructor(id, options) {
+        const parent = options?.parent || globalThis.CURRENT_BLOCKS_STACK;
+        super(parent, id);
+        this.id = id;
+        this.parent = parent;
+    }
+    get handler() {
+        // Walk up the construct tree to find the owning BlocksStack/BlocksBackend
+        let current = this;
+        while (current.node.scope) {
+            current = current.node.scope;
+            if (current instanceof BlocksStack || current instanceof BlocksBackend) {
+                return current.handler;
+            }
+        }
+        // Fallback to globalThis for backward compatibility
+        return globalThis.CURRENT_BLOCKS_STACK.handler;
+    }
+    get fullId() {
+        return computeScopeFullId(this);
+    }
+    buildUserAgentChain() {
+        return [];
+    }
+    // Plugin registration — no-ops in CDK context (plugins are only used at dev/build time)
+    registerClientMiddleware(_packageSpecifier) { }
+    registerDevAttachment(_packageSpecifier) { }
+    registerLambdaEventHandler(_eventSource, _identifier, _handler) { }
+    get clientMiddleware() { return []; }
+    get devAttachments() { return []; }
+}

package/dist/cdk/mixins.d.ts

@@ -0,0 +1,28 @@
+import { Mixin } from 'aws-cdk-lib';
+import type { IConstruct } from 'constructs';
+import type { IMixin } from 'constructs';
+/**
+ * Disables deletion protection on any construct that has a `deletionProtection`
+ * property (e.g. RDS clusters, RDS instances). Uses duck-typing so it
+ * automatically covers current and future resource types.
+ *
+ * Intended for sandbox teardown — use in the CDK layer alongside
+ * `RemovalPolicies.of(stack).destroy()` to ensure `sandbox:destroy` can
+ * delete the entire stack without manual cleanup.
+ *
+ * @example
+ * ```ts
+ * import { RemovalPolicies, Mixins } from 'aws-cdk-lib';
+ * import { SandboxDisableDeletionProtection } from '@aws-blocks/blocks/cdk';
+ *
+ * if (sandboxMode) {
+ *   RemovalPolicies.of(stack).destroy();
+ *   Mixins.of(stack).apply(new SandboxDisableDeletionProtection());
+ * }
+ * ```
+ */
+export declare class SandboxDisableDeletionProtection extends Mixin implements IMixin {
+    supports(construct: any): boolean;
+    applyTo(node: IConstruct): void;
+}
+//# sourceMappingURL=mixins.d.ts.map

package/dist/cdk/mixins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mixins.d.ts","sourceRoot":"","sources":["../../src/cdk/mixins.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,gCAAiC,SAAQ,KAAM,YAAW,MAAM;IAC3E,QAAQ,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO;IAGjC,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;CAShC"}

package/dist/cdk/mixins.js

@@ -0,0 +1,37 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Mixin } from 'aws-cdk-lib';
+/**
+ * Disables deletion protection on any construct that has a `deletionProtection`
+ * property (e.g. RDS clusters, RDS instances). Uses duck-typing so it
+ * automatically covers current and future resource types.
+ *
+ * Intended for sandbox teardown — use in the CDK layer alongside
+ * `RemovalPolicies.of(stack).destroy()` to ensure `sandbox:destroy` can
+ * delete the entire stack without manual cleanup.
+ *
+ * @example
+ * ```ts
+ * import { RemovalPolicies, Mixins } from 'aws-cdk-lib';
+ * import { SandboxDisableDeletionProtection } from '@aws-blocks/blocks/cdk';
+ *
+ * if (sandboxMode) {
+ *   RemovalPolicies.of(stack).destroy();
+ *   Mixins.of(stack).apply(new SandboxDisableDeletionProtection());
+ * }
+ * ```
+ */
+export class SandboxDisableDeletionProtection extends Mixin {
+    supports(construct) {
+        return 'deletionProtection' in construct;
+    }
+    applyTo(node) {
+        // Only flip explicitly-enabled protection. When undefined (the default),
+        // deletion protection is already off — setting it to false would emit the
+        // property in the CloudFormation template, which breaks Aurora DB instances
+        // (RDS rejects DeletionProtection on cluster members).
+        if (node.deletionProtection === true) {
+            node.deletionProtection = false;
+        }
+    }
+}

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

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

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

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

package/dist/cdk/mixins.test.js

@@ -0,0 +1,108 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { test, describe } from 'node:test';
+import * as cdk from 'aws-cdk-lib';
+import { Template, Match } from 'aws-cdk-lib/assertions';
+import { Table, AttributeType, BillingMode } from 'aws-cdk-lib/aws-dynamodb';
+import * as rds from 'aws-cdk-lib/aws-rds';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import { RemovalPolicies, Mixins } from 'aws-cdk-lib';
+import { SandboxDisableDeletionProtection } from './mixins.js';
+describe('sandbox removal policy', () => {
+    test('sandbox mode: DeletionPolicy is Delete on all resources', () => {
+        const app = new cdk.App({ context: { sandboxMode: 'true' } });
+        const stack = new cdk.Stack(app, 'TestStack');
+        new Table(stack, 'MyTable', {
+            partitionKey: { name: 'pk', type: AttributeType.STRING },
+            billingMode: BillingMode.PAY_PER_REQUEST,
+        });
+        RemovalPolicies.of(stack).destroy();
+        const template = Template.fromStack(stack);
+        template.hasResource('AWS::DynamoDB::Table', {
+            DeletionPolicy: 'Delete',
+        });
+    });
+    test('sandbox mode: deletionProtection disabled on RDS cluster', () => {
+        const app = new cdk.App({ context: { sandboxMode: 'true' } });
+        const stack = new cdk.Stack(app, 'TestStack');
+        const vpc = new ec2.Vpc(stack, 'Vpc', {
+            maxAzs: 2,
+            natGateways: 0,
+            subnetConfiguration: [
+                { name: 'isolated', subnetType: ec2.SubnetType.PRIVATE_ISOLATED },
+            ],
+        });
+        new rds.DatabaseCluster(stack, 'Cluster', {
+            engine: rds.DatabaseClusterEngine.auroraPostgres({
+                version: rds.AuroraPostgresEngineVersion.VER_16_4,
+            }),
+            writer: rds.ClusterInstance.serverlessV2('Writer'),
+            vpc,
+            vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_ISOLATED },
+            deletionProtection: true,
+        });
+        RemovalPolicies.of(stack).destroy();
+        Mixins.of(stack).apply(new SandboxDisableDeletionProtection());
+        const template = Template.fromStack(stack);
+        template.hasResourceProperties('AWS::RDS::DBCluster', {
+            DeletionProtection: false,
+        });
+        template.hasResource('AWS::RDS::DBCluster', {
+            DeletionPolicy: 'Delete',
+        });
+    });
+    test('production mode: default DeletionPolicy is Retain (CDK default, no explicit call needed)', () => {
+        const app = new cdk.App();
+        const stack = new cdk.Stack(app, 'TestStack');
+        new Table(stack, 'MyTable', {
+            partitionKey: { name: 'pk', type: AttributeType.STRING },
+            billingMode: BillingMode.PAY_PER_REQUEST,
+        });
+        // No removal policy call — CDK defaults to RETAIN
+        const template = Template.fromStack(stack);
+        template.hasResource('AWS::DynamoDB::Table', {
+            DeletionPolicy: 'Retain',
+        });
+    });
+    test('SandboxDisableDeletionProtection mixin: does not set deletionProtection on Aurora instances', () => {
+        const app = new cdk.App();
+        const stack = new cdk.Stack(app, 'TestStack');
+        const vpc = new ec2.Vpc(stack, 'Vpc', {
+            maxAzs: 2,
+            natGateways: 0,
+            subnetConfiguration: [
+                { name: 'isolated', subnetType: ec2.SubnetType.PRIVATE_ISOLATED },
+            ],
+        });
+        new rds.DatabaseCluster(stack, 'Cluster', {
+            engine: rds.DatabaseClusterEngine.auroraPostgres({
+                version: rds.AuroraPostgresEngineVersion.VER_16_4,
+            }),
+            writer: rds.ClusterInstance.serverlessV2('Writer'),
+            vpc,
+            vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_ISOLATED },
+            removalPolicy: cdk.RemovalPolicy.DESTROY,
+        });
+        RemovalPolicies.of(stack).destroy();
+        Mixins.of(stack).apply(new SandboxDisableDeletionProtection());
+        const template = Template.fromStack(stack);
+        // Aurora DB instance should NOT have DeletionProtection set at all
+        // (RDS rejects it for cluster members)
+        template.hasResourceProperties('AWS::RDS::DBInstance', {
+            DeletionProtection: Match.absent(),
+        });
+    });
+    test('SandboxDisableDeletionProtection mixin: skips constructs without deletionProtection', () => {
+        const app = new cdk.App();
+        const stack = new cdk.Stack(app, 'TestStack');
+        new Table(stack, 'MyTable', {
+            partitionKey: { name: 'pk', type: AttributeType.STRING },
+            billingMode: BillingMode.PAY_PER_REQUEST,
+        });
+        // Should not throw — DynamoDB Table has no deletionProtection property
+        Mixins.of(stack).apply(new SandboxDisableDeletionProtection());
+        const template = Template.fromStack(stack);
+        // Table should still synthesize normally
+        template.resourceCountIs('AWS::DynamoDB::Table', 1);
+    });
+});

package/dist/cdk/node-version.d.ts

@@ -0,0 +1,14 @@
+import { Runtime } from 'aws-cdk-lib/aws-lambda';
+/**
+ * The single source of truth for the Node.js Lambda runtime used by Blocks's
+ * own Lambda functions and every Building Block. Set every
+ * `aws_lambda.Function` / `NodejsFunction` runtime to this constant rather
+ * than hardcoding `Runtime.NODEJS_*_X`, so the whole framework moves in
+ * lockstep when the runtime is bumped.
+ *
+ * Currently the latest Active LTS. This controls only the AWS-managed
+ * runtime that executes deployed handlers; it is independent of the Node
+ * version a consumer runs the CLI / CDK synth on.
+ */
+export declare const DEFAULT_NODE_RUNTIME: Runtime;
+//# sourceMappingURL=node-version.d.ts.map

package/dist/cdk/node-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-version.d.ts","sourceRoot":"","sources":["../../src/cdk/node-version.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,SAAsB,CAAC"}

package/dist/cdk/node-version.js

@@ -0,0 +1,15 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Runtime } from 'aws-cdk-lib/aws-lambda';
+/**
+ * The single source of truth for the Node.js Lambda runtime used by Blocks's
+ * own Lambda functions and every Building Block. Set every
+ * `aws_lambda.Function` / `NodejsFunction` runtime to this constant rather
+ * than hardcoding `Runtime.NODEJS_*_X`, so the whole framework moves in
+ * lockstep when the runtime is bumped.
+ *
+ * Currently the latest Active LTS. This controls only the AWS-managed
+ * runtime that executes deployed handlers; it is independent of the Node
+ * version a consumer runs the CLI / CDK synth on.
+ */
+export const DEFAULT_NODE_RUNTIME = Runtime.NODEJS_24_X;

package/dist/cdk/stack-metadata.d.ts

@@ -0,0 +1,12 @@
+import * as cdk from 'aws-cdk-lib';
+/**
+ * Adds AWS Blocks identification metadata and a deployment-type tag to a CloudFormation stack.
+ *
+ * Sets `AWS::Blocks::Platform` template metadata with the current core version
+ * and applies a `blocks:deployment-type` tag (`sandbox` or `production`) based on
+ * the CDK context key `sandboxMode`.
+ *
+ * @param stack - The CDK stack to annotate.
+ */
+export declare function addBlocksStackMetadata(stack: cdk.Stack): void;
+//# sourceMappingURL=stack-metadata.d.ts.map

package/dist/cdk/stack-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-metadata.d.ts","sourceRoot":"","sources":["../../src/cdk/stack-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AAGnC;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,GAAG,IAAI,CAgB7D"}

package/dist/cdk/stack-metadata.js

@@ -0,0 +1,22 @@
+import * as cdk from 'aws-cdk-lib';
+import { CORE_VERSION } from '../version.js';
+/**
+ * Adds AWS Blocks identification metadata and a deployment-type tag to a CloudFormation stack.
+ *
+ * Sets `AWS::Blocks::Platform` template metadata with the current core version
+ * and applies a `blocks:deployment-type` tag (`sandbox` or `production`) based on
+ * the CDK context key `sandboxMode`.
+ *
+ * @param stack - The CDK stack to annotate.
+ */
+export function addBlocksStackMetadata(stack) {
+    stack.templateOptions.metadata = {
+        ...stack.templateOptions.metadata,
+        'AWS::Blocks::Platform': {
+            version: CORE_VERSION,
+        },
+    };
+    const isSandbox = stack.node.tryGetContext('sandboxMode') === 'true' ||
+        stack.node.tryGetContext('sandboxMode') === true;
+    cdk.Tags.of(stack).add('blocks:deployment-type', isSandbox ? 'sandbox' : 'production');
+}

package/dist/cdk/stack-metadata.test.d.ts

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

package/dist/cdk/stack-metadata.test.d.ts.map

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

package/dist/cdk/stack-metadata.test.js

@@ -0,0 +1,56 @@
+import { test, describe } from 'node:test';
+import assert from 'node:assert';
+import * as cdk from 'aws-cdk-lib';
+import { Template } from 'aws-cdk-lib/assertions';
+import { addBlocksStackMetadata } from './stack-metadata.js';
+import { CORE_VERSION } from '../version.js';
+describe('addBlocksStackMetadata', () => {
+    test('adds AWS::Blocks::Platform metadata with correct version', () => {
+        const app = new cdk.App();
+        const stack = new cdk.Stack(app, 'TestStack');
+        addBlocksStackMetadata(stack);
+        const template = Template.fromStack(stack);
+        const metadata = template.toJSON().Metadata;
+        assert.deepStrictEqual(metadata['AWS::Blocks::Platform'], {
+            version: CORE_VERSION,
+        });
+    });
+    test('preserves existing template metadata', () => {
+        const app = new cdk.App();
+        const stack = new cdk.Stack(app, 'ExistingMetaStack');
+        stack.templateOptions.metadata = {
+            'Custom::Existing': { key: 'value' },
+        };
+        addBlocksStackMetadata(stack);
+        const template = Template.fromStack(stack);
+        const metadata = template.toJSON().Metadata;
+        assert.deepStrictEqual(metadata['Custom::Existing'], { key: 'value' });
+        assert.deepStrictEqual(metadata['AWS::Blocks::Platform'], {
+            version: CORE_VERSION,
+        });
+    });
+    test('tags deployment-type as production when sandboxMode context is absent', () => {
+        const app = new cdk.App();
+        const stack = new cdk.Stack(app, 'ProdStack');
+        addBlocksStackMetadata(stack);
+        const assembly = app.synth();
+        const stackArtifact = assembly.getStackByName(stack.stackName);
+        assert.strictEqual(stackArtifact.tags['blocks:deployment-type'], 'production');
+    });
+    test('tags deployment-type as sandbox when sandboxMode context is boolean true', () => {
+        const app = new cdk.App({ context: { sandboxMode: true } });
+        const stack = new cdk.Stack(app, 'SandboxBoolStack');
+        addBlocksStackMetadata(stack);
+        const assembly = app.synth();
+        const stackArtifact = assembly.getStackByName(stack.stackName);
+        assert.strictEqual(stackArtifact.tags['blocks:deployment-type'], 'sandbox');
+    });
+    test('tags deployment-type as sandbox when sandboxMode context is string "true"', () => {
+        const app = new cdk.App({ context: { sandboxMode: 'true' } });
+        const stack = new cdk.Stack(app, 'SandboxStringStack');
+        addBlocksStackMetadata(stack);
+        const assembly = app.synth();
+        const stackArtifact = assembly.getStackByName(stack.stackName);
+        assert.strictEqual(stackArtifact.tags['blocks:deployment-type'], 'sandbox');
+    });
+});

package/dist/cdk/synth-guard.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Throws an actionable error when a runtime-only method is called during CDK synth.
+ *
+ * Under `--conditions=cdk` Building Block modules resolve to their CDK construct,
+ * which only provisions infrastructure. Data/runtime methods live in the runtime
+ * build. Calling them at module top-level (which runs during synth) would otherwise
+ * fail with a cryptic `X is not a function` TypeError; this utility turns that into
+ * an actionable message directing the user to the correct execution context.
+ *
+ * @param className - The Building Block class name (e.g. "KVStore", "DistributedTable")
+ * @param method - The method that was called (e.g. "get", "put")
+ */
+export declare function synthGuard(className: string, method: string): never;
+//# sourceMappingURL=synth-guard.d.ts.map

package/dist/cdk/synth-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synth-guard.d.ts","sourceRoot":"","sources":["../../src/cdk/synth-guard.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAOnE"}

package/dist/cdk/synth-guard.js

@@ -0,0 +1,20 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Throws an actionable error when a runtime-only method is called during CDK synth.
+ *
+ * Under `--conditions=cdk` Building Block modules resolve to their CDK construct,
+ * which only provisions infrastructure. Data/runtime methods live in the runtime
+ * build. Calling them at module top-level (which runs during synth) would otherwise
+ * fail with a cryptic `X is not a function` TypeError; this utility turns that into
+ * an actionable message directing the user to the correct execution context.
+ *
+ * @param className - The Building Block class name (e.g. "KVStore", "DistributedTable")
+ * @param method - The method that was called (e.g. "get", "put")
+ */
+export function synthGuard(className, method) {
+    throw new Error(`${className}.${method}() cannot be called during CDK synth. ` +
+        `Data methods run at request time — call them inside an ApiNamespace method, ` +
+        `RawRoute handler, job handler, or a runtime script (run with --conditions=aws-runtime), ` +
+        `not at the top level of your backend module.`);
+}

package/dist/cdk/synth-guard.test.d.ts

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

package/dist/cdk/synth-guard.test.d.ts.map

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

package/dist/cdk/synth-guard.test.js

@@ -0,0 +1,15 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { test } from 'node:test';
+import assert from 'node:assert';
+import { synthGuard } from './synth-guard.js';
+test('synthGuard throws an error mentioning the class and method name', () => {
+    assert.throws(() => synthGuard('MyBlock', 'doThing'), (err) => {
+        assert.match(err.message, /MyBlock\.doThing\(\) cannot be called during CDK synth/);
+        assert.match(err.message, /--conditions=aws-runtime/);
+        return true;
+    });
+});
+test('synthGuard always throws (return type is never)', () => {
+    assert.throws(() => synthGuard('X', 'y'));
+});

package/dist/client/index.d.ts

@@ -0,0 +1,97 @@
+export type BlocksContext = any;
+export type ApiHandler<T extends Record<string, (...args: any[]) => any>> = any;
+type AsyncAPI<T extends Record<string, (...args: any[]) => any>> = {
+    [K in keyof T]: T[K] extends (...args: infer Args) => infer R ? (...args: Args) => Promise<Awaited<R>> : never;
+};
+/**
+ * A Blocks request object passed through middleware before being sent.
+ * Middleware can inspect or modify any of these properties before the
+ * request is dispatched to the server.
+ */
+export interface KitRequest {
+    /** The namespace name this call targets (e.g., 'api', 'auth'). Corresponds to the second argument of `new ApiNamespace(scope, name, handler)` in the backend. */
+    apiNamespace: string;
+    /** The method being called on the namespace (e.g., 'getUser', 'kvSet'). */
+    method: string;
+    /** The arguments passed to the method call. */
+    args: any[];
+    /** HTTP headers that will be sent with the request. Middleware can add or modify headers (e.g., inject auth tokens). */
+    headers: Record<string, string>;
+}
+/**
+ * Client middleware that can process requests before they are sent
+ * and/or responses after they are received. Both hooks are optional.
+ *
+ * ```typescript
+ * // Request middleware — inject auth token
+ * registerMiddleware({
+ *   onRequest(req) {
+ *     req.headers['authorization'] = `Bearer ${getToken()}`;
+ *   }
+ * });
+ *
+ * // Response middleware — hydrate transferable descriptors
+ * registerMiddleware({
+ *   onResponse(data) {
+ *     if (isMyDescriptor(data)) return hydrate(data);
+ *     return data;
+ *   }
+ * });
+ * ```
+ */
+export interface KitMiddleware {
+    /** Transform the request before it's sent. Modify the request in place or return a new one. Can be async. */
+    onRequest?: (request: KitRequest) => KitRequest | void | Promise<KitRequest | void>;
+    /** Transform the response data after it's received. Used to hydrate __blocks descriptors. */
+    onResponse?: (data: unknown) => unknown;
+}
+/**
+ * Register client middleware for request/response processing.
+ *
+ * Building Block middleware packages call this on import to register
+ * hooks that run on every API call. Request hooks can inject headers
+ * (e.g., auth tokens). Response hooks hydrate `{ __blocks: '...' }`
+ * descriptors into live client-side objects (e.g., WebSocket channels).
+ *
+ * Client middleware uses a **self-registering** pattern: the middleware
+ * module imports this function and calls it as a side effect of being
+ * imported. The generated `client.js` simply includes
+ * `import 'bb-realtime/mock-middleware'` — no explicit registration
+ * code is needed. This is idiomatic for browser/bundler contexts where
+ * side-effect imports are standard (similar to CSS imports or polyfills).
+ *
+ * This differs intentionally from **dev server attachments**, which use
+ * an explicit `attach(server)` pattern because they need the HTTP server
+ * instance passed to them — something unavailable at import time.
+ */
+export declare function registerMiddleware(middleware: KitMiddleware): void;
+/**
+ * Options for `ApiNamespaceClient`.
+ */
+export interface ApiNamespaceClientOptions {
+    /** Explicit API URL. When provided, skips automatic config.json discovery. */
+    url?: string;
+}
+/**
+ * Client-side API proxy. Creates a typed proxy that sends method calls
+ * to the backend API over HTTP and hydrates Transferable descriptors
+ * in responses via registered middleware.
+ *
+ * This is the browser counterpart of the server-side `ApiNamespace` in
+ * `core/api.ts`. The generated `client.js` emits one of these per
+ * API namespace exported from the backend.
+ *
+ * ```typescript
+ * // Generated client.js
+ * import { ApiNamespaceClient } from '@aws-blocks/core/client';
+ * export const api = ApiNamespaceClient('api');
+ *
+ * // Frontend usage — fully typed via the 'aws-blocks' types export
+ * import { api } from 'aws-blocks';
+ * const user = await api.getUser('123');
+ * ```
+ */
+export declare function ApiNamespaceClient<T extends Record<string, (...args: any[]) => any>>(name: string, options?: ApiNamespaceClientOptions): AsyncAPI<T>;
+export { ApiError, isBlocksError } from '../errors.js';
+export { Scope, type ScopeOptions } from '../common/index.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC;AAChC,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI,GAAG,CAAC;AAiBhF,KAAK,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI;KAChE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,MAAM,CAAC,GACzD,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GACtC,KAAK;CACV,CAAC;AAoHF;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,iKAAiK;IACjK,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,wHAAwH;IACxH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,aAAa;IAC5B,6GAA6G;IAC7G,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACpF,6FAA6F;IAC7F,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;CACzC;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,aAAa,GAAG,IAAI,CAElE;AAqBD;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAClF,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,yBAAyB,GAClC,QAAQ,CAAC,CAAC,CAAC,CAyDb;AAED,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC"}