@aws-blocks/core 0.1.0

package/src/cdk/config-registry.ts

@@ -0,0 +1,106 @@
+// 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 s3 from 'aws-cdk-lib/aws-s3';
+import * as s3deploy from 'aws-cdk-lib/aws-s3-deployment';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import type { Construct } from 'constructs';
+
+const REGISTRY_KEY = Symbol.for('BLOCKS_CONFIG_REGISTRY');
+
+interface ConfigRegistryState {
+	entries: Map<string, unknown>;
+	finalized: boolean;
+}
+
+/**
+ * Get or create the config registry for a given stack.
+ * The registry collects BB config entries (env var key → CDK token value)
+ * and serializes them to an S3 JSON file at synth time.
+ */
+function getRegistry(stack: cdk.Stack): ConfigRegistryState {
+	let state = (stack as any)[REGISTRY_KEY] as ConfigRegistryState | undefined;
+	if (!state) {
+		state = { entries: new Map(), finalized: false };
+		(stack as any)[REGISTRY_KEY] = state;
+	}
+	return state;
+}
+
+/**
+ * Register a config entry for a Building Block. This replaces
+ * `handler.addEnvironment(key, value)` for BB resource mappings.
+ *
+ * The entry will be serialized into a JSON config file in S3, loaded
+ * by the Lambda at cold start. This avoids the 4KB env var limit.
+ *
+ * @param scope - The CDK construct (used to find the parent stack)
+ * @param key - The config key (same string the runtime will use to look it up)
+ * @param value - The config value (can be a CDK token that resolves at deploy time)
+ */
+export function registerConfig(scope: Construct, key: string, value: unknown): void {
+	const stack = cdk.Stack.of(scope);
+	const registry = getRegistry(stack);
+	registry.entries.set(key, value);
+}
+
+/**
+ * Finalize the config registry: create an S3 bucket, upload the config JSON,
+ * set env vars on the handler, and grant read access.
+ *
+ * Must be called after all BBs are constructed (i.e., after the backendCDKPath
+ * import completes in BlocksStack.create() / BlocksBackend.create()).
+ *
+ * @param scope - The CDK construct to create resources under
+ * @param handler - The Lambda function that needs to read the config
+ */
+export function finalizeConfigRegistry(
+	scope: Construct,
+	handler: cdk.aws_lambda.IFunction,
+): void {
+	const stack = cdk.Stack.of(scope);
+	const registry = getRegistry(stack);
+
+	if (registry.finalized) return;
+	registry.finalized = true;
+
+	if (registry.entries.size === 0) return;
+
+	const configBucket = new s3.Bucket(scope, 'BlocksConfigBucket', {
+		removalPolicy: cdk.RemovalPolicy.DESTROY,
+		autoDeleteObjects: true,
+		encryption: s3.BucketEncryption.S3_MANAGED,
+		blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+		lifecycleRules: [
+			{ noncurrentVersionExpiration: cdk.Duration.days(1) },
+		],
+	});
+
+	const configKey = 'blocks-config.json';
+
+	const configObject = cdk.Lazy.any({
+		produce: () => Object.fromEntries(registry.entries),
+	});
+
+	const deployment = new s3deploy.BucketDeployment(scope, 'BlocksConfigDeployment', {
+		sources: [s3deploy.Source.jsonData(configKey, configObject)],
+		destinationBucket: configBucket,
+		prune: false,
+	});
+
+	(handler as cdk.aws_lambda.Function).addEnvironment(
+		'BLOCKS_CONFIG_BUCKET',
+		configBucket.bucketName,
+	);
+	(handler as cdk.aws_lambda.Function).addEnvironment(
+		'BLOCKS_CONFIG_KEY',
+		configKey,
+	);
+
+	// Scope IAM grant to the specific config key
+	(handler as cdk.aws_lambda.Function).addToRolePolicy(new iam.PolicyStatement({
+		actions: ['s3:GetObject'],
+		resources: [`${configBucket.bucketArn}/${configKey}`],
+	}));
+}

package/src/cdk/index.ts

@@ -0,0 +1,115 @@
+// 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 {
+  type BlocksStackProps,
+  type BlocksStack as BaseBlocksStack,
+  type ScopeParent,
+  type ScopeOptions,
+  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, type BlocksBackendProps } 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 type { ScopeOptions } from '../index.js';
+export { ApiError, isBlocksError } from '../errors.js';
+
+export class BlocksStack extends cdk.Stack implements BaseBlocksStack {
+  public readonly id: string;
+  public readonly apiUrl: string;
+  public readonly gateway: cdk.aws_apigateway.RestApi;
+  public readonly handler: cdk.aws_lambda_nodejs.NodejsFunction;
+  public readonly backendHandlerPath: string;
+
+  private constructor(scope: Construct, id: string, props: BlocksStackProps) {
+    super(scope, id, props);
+    this.id = id;
+    this.backendHandlerPath = props.backendHandlerPath;
+
+    // Set globalThis so Building Blocks attach directly to this stack
+    (globalThis as any).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: Construct, id: string, props: BlocksStackProps) {
+    assertCdkConditionActive();
+
+    // Detect ambient pipeline stage scope set by Pipeline appFile imports
+    const pipelineScope = (globalThis as any).__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 {
+  public readonly id: string;
+  public readonly parent: ScopeParent;
+
+  readonly bbName?: string;
+  readonly bbVersion?: string;
+
+  constructor(id: string, options?: ScopeOptions) {
+    const parent = options?.parent || (globalThis as any).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: Construct = this;
+    while (current.node.scope) {
+        current = current.node.scope as Construct;
+        if (current instanceof BlocksStack || current instanceof BlocksBackend) {
+            return current.handler;
+        }
+    }
+    // Fallback to globalThis for backward compatibility
+    return ((globalThis as any).CURRENT_BLOCKS_STACK as { handler: cdk.aws_lambda_nodejs.NodejsFunction }).handler;
+  }
+
+  get fullId(): string {
+    return computeScopeFullId(this);
+  }
+
+  protected buildUserAgentChain(): [string, string][] {
+    return [];
+  }
+
+  // Plugin registration — no-ops in CDK context (plugins are only used at dev/build time)
+  registerClientMiddleware(_packageSpecifier: string): void {}
+  registerDevAttachment(_packageSpecifier: string): void {}
+  registerLambdaEventHandler(_eventSource: string, _identifier: string, _handler: (record: any) => Promise<void>): void {}
+  get clientMiddleware(): readonly string[] { return []; }
+  get devAttachments(): readonly string[] { return []; }
+}

package/src/cdk/mixins.test.ts

@@ -0,0 +1,129 @@
+// 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 * 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/src/cdk/mixins.ts

@@ -0,0 +1,41 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+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 class SandboxDisableDeletionProtection extends Mixin implements IMixin {
+  supports(construct: any): boolean {
+    return 'deletionProtection' in construct;
+  }
+  applyTo(node: IConstruct): void {
+    // 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 as any).deletionProtection === true) {
+      (node as any).deletionProtection = false;
+    }
+  }
+}

package/src/cdk/node-version.ts

@@ -0,0 +1,17 @@
+// 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/src/cdk/stack-metadata.test.ts

@@ -0,0 +1,71 @@
+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/src/cdk/stack-metadata.ts

@@ -0,0 +1,29 @@
+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: cdk.Stack): void {
+  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/src/cdk/synth-guard.test.ts

@@ -0,0 +1,21 @@
+// 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: Error) => {
+			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/src/cdk/synth-guard.ts

@@ -0,0 +1,23 @@
+// 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: string, method: string): never {
+	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/src/client/index.test.ts

@@ -0,0 +1,118 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { execSync } from 'node:child_process';
+import { writeFileSync, unlinkSync, mkdtempSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+/**
+ * Tests for the client's URL resolution defensive guard (issue #730).
+ *
+ * The client module caches API_URL globally, so each test spawns a
+ * subprocess with appropriate env vars to get a fresh module instance.
+ */
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLIENT_MODULE = join(__dirname, '..', 'client', 'index.js');
+
+function runScript(scriptBody: string, env: Record<string, string>): string {
+  const tmp = mkdtempSync(join(tmpdir(), 'blocks-client-test-'));
+  const scriptPath = join(tmp, 'test.mjs');
+  // Use absolute path to import the client module
+  const importPath = `file://${CLIENT_MODULE}`;
+  const fullScript = `import { ApiNamespaceClient } from '${importPath}';\n${scriptBody}`;
+  writeFileSync(scriptPath, fullScript);
+  try {
+    return execSync(`node ${scriptPath}`, {
+      encoding: 'utf-8',
+      env: { PATH: process.env.PATH, HOME: process.env.HOME, ...env },
+      timeout: 10000,
+    }).trim();
+  } finally {
+    try { unlinkSync(scriptPath); } catch {}
+  }
+}
+
+describe('Client URL validation (issue #730)', () => {
+  it('ApiNamespaceClient with explicit url option containing "undefined" does NOT throw on creation', async () => {
+    const { ApiNamespaceClient } = await import('./index.js');
+    const client = ApiNamespaceClient('test', { url: 'https://undefined.example.com' });
+    assert.ok(client, 'Should create client proxy');
+  });
+
+  it('resolveApiUrl rejects when BLOCKS_API_URL contains "undefined"', () => {
+    const result = runScript(`
+const api = ApiNamespaceClient('test');
+try {
+  await api.hello();
+  console.log('FAIL:no_error');
+} catch (e) {
+  if (e.message.includes('Blocks API URL is not configured')) {
+    console.log('PASS');
+  } else {
+    console.log('FAIL:' + e.message);
+  }
+}
+`, { BLOCKS_API_URL: 'https://undefined/api' });
+    assert.ok(result.includes('PASS'), `Expected PASS, got: ${result}`);
+  });
+
+  it('resolveApiUrl rejects when BLOCKS_CONFIG has missing apiUrl', () => {
+    const result = runScript(`
+const api = ApiNamespaceClient('test');
+try {
+  await api.hello();
+  console.log('FAIL:no_error');
+} catch (e) {
+  if (e.message.includes('Blocks API URL is not configured') || e.message.includes('Blocks API URL not configured')) {
+    console.log('PASS');
+  } else {
+    console.log('FAIL:' + e.message);
+  }
+}
+`, { BLOCKS_CONFIG: JSON.stringify({ region: 'us-east-1' }) });
+    assert.ok(result.includes('PASS'), `Expected PASS, got: ${result}`);
+  });
+
+  it('resolveApiUrl succeeds with valid BLOCKS_API_URL', () => {
+    const result = runScript(`
+const api = ApiNamespaceClient('test');
+try {
+  await api.hello();
+  console.log('FAIL:no_error');
+} catch (e) {
+  if (e.message.includes('fetch') || e.message.includes('ENOTFOUND') || e.message.includes('getaddrinfo')) {
+    console.log('PASS:url_resolved_fetch_failed');
+  } else if (e.message.includes('Blocks API URL')) {
+    console.log('FAIL:url_rejected_valid');
+  } else {
+    console.log('PASS:other');
+  }
+}
+`, { BLOCKS_API_URL: 'https://abc123.execute-api.us-east-1.amazonaws.com/prod/aws-blocks' });
+    assert.ok(result.includes('PASS'), `Expected PASS, got: ${result}`);
+  });
+
+  it('resolveApiUrl accepts relative URLs (e.g. /aws-blocks/api for SPA hosting)', () => {
+    const result = runScript(`
+const api = ApiNamespaceClient('test');
+try {
+  await api.hello();
+  console.log('FAIL:no_error');
+} catch (e) {
+  if (e.message.includes('fetch') || e.message.includes('ENOTFOUND') || e.message.includes('getaddrinfo') || e.message.includes('Invalid URL')) {
+    console.log('PASS:url_resolved_fetch_failed');
+  } else if (e.message.includes('Blocks API URL')) {
+    console.log('FAIL:url_rejected_relative');
+  } else {
+    console.log('PASS:other');
+  }
+}
+`, { BLOCKS_API_URL: '/aws-blocks/api' });
+    assert.ok(result.includes('PASS'), `Expected PASS, got: ${result}`);
+  });
+});