@aws-blocks/core 0.1.0

package/dist/telemetry/trackCommand.d.ts

@@ -0,0 +1,32 @@
+import type { CommandName, TrackCommandOptions } from './types.js';
+/**
+ * Classify a caught error into a telemetry-safe error code.
+ * Only inspects the error message for known patterns — never transmits raw messages.
+ */
+export declare function classifyError(error: unknown): {
+    code: string;
+    phase: string;
+};
+/**
+ * Wrap a CLI command function with telemetry tracking.
+ *
+ * Measures wall-clock duration, classifies errors, and sends a single telemetry event
+ * after the command completes (success or failure). The telemetry send is fire-and-forget
+ * and bounded by a 5s timeout — it will never delay the command or affect its exit code.
+ *
+ * If telemetry is disabled (via env var or config), the function is executed directly
+ * with zero overhead.
+ *
+ * @param commandName - The command being tracked
+ * @param fn - The async function to execute
+ * @param options - Optional metadata (template, framework, etc.)
+ *
+ * @example
+ * ```ts
+ * await trackCommand('sandbox', async () => {
+ *   await startSandbox({ backendPath: '...' });
+ * });
+ * ```
+ */
+export declare function trackCommand(commandName: CommandName, fn: () => Promise<void>, options?: TrackCommandOptions): Promise<void>;
+//# sourceMappingURL=trackCommand.d.ts.map

package/dist/telemetry/trackCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trackCommand.d.ts","sourceRoot":"","sources":["../../src/telemetry/trackCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAgB,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAIjF;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAuC7E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,WAAW,EACxB,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EACvB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAmCf"}

package/dist/telemetry/trackCommand.js

@@ -0,0 +1,102 @@
+import { isTelemetryEnabled } from './consent.js';
+import { buildAndSendEvent } from './client.js';
+/**
+ * Classify a caught error into a telemetry-safe error code.
+ * Only inspects the error message for known patterns — never transmits raw messages.
+ */
+export function classifyError(error) {
+    if (!(error instanceof Error))
+        return { code: 'UNKNOWN', phase: 'unknown' };
+    const msg = error.message.toLowerCase();
+    if (msg.includes('eaddrinuse') || (msg.includes('port') && msg.includes('in use'))) {
+        return { code: 'PORT_IN_USE', phase: 'startup' };
+    }
+    if (msg.includes('access denied') || msg.includes('not authorized') || msg.includes('forbidden')) {
+        return { code: 'PERMISSION_DENIED', phase: 'auth' };
+    }
+    if (msg.includes('credentials') || msg.includes('no credentials') || msg.includes('security token')) {
+        return { code: 'CREDENTIALS_FAILED', phase: 'auth' };
+    }
+    if (msg.includes('cdk synth') || msg.includes('synthesis')) {
+        return { code: 'CDK_SYNTH_FAILED', phase: 'synth' };
+    }
+    if (msg.includes('cdk deploy') || msg.includes('deployment failed')) {
+        return { code: 'CDK_DEPLOY_FAILED', phase: 'deploy' };
+    }
+    if (msg.includes('cdk destroy') || msg.includes('destroy failed')) {
+        return { code: 'CDK_DESTROY_FAILED', phase: 'destroy' };
+    }
+    if (msg.includes('npm install') || msg.includes('npm err')) {
+        return { code: 'NPM_INSTALL_FAILED', phase: 'install' };
+    }
+    if (msg.includes('codegen') || msg.includes('generate client')) {
+        return { code: 'CODEGEN_FAILED', phase: 'codegen' };
+    }
+    if (msg.includes('vite') || msg.includes('next build') || msg.includes('frontend build')) {
+        return { code: 'FRONTEND_BUILD_FAILED', phase: 'build' };
+    }
+    if (msg.includes('template') && msg.includes('copy')) {
+        return { code: 'TEMPLATE_COPY_FAILED', phase: 'init' };
+    }
+    if (msg.includes('argument') || msg.includes('parse')) {
+        return { code: 'ARG_PARSE_FAILED', phase: 'init' };
+    }
+    return { code: 'UNKNOWN', phase: 'unknown' };
+}
+/**
+ * Wrap a CLI command function with telemetry tracking.
+ *
+ * Measures wall-clock duration, classifies errors, and sends a single telemetry event
+ * after the command completes (success or failure). The telemetry send is fire-and-forget
+ * and bounded by a 5s timeout — it will never delay the command or affect its exit code.
+ *
+ * If telemetry is disabled (via env var or config), the function is executed directly
+ * with zero overhead.
+ *
+ * @param commandName - The command being tracked
+ * @param fn - The async function to execute
+ * @param options - Optional metadata (template, framework, etc.)
+ *
+ * @example
+ * ```ts
+ * await trackCommand('sandbox', async () => {
+ *   await startSandbox({ backendPath: '...' });
+ * });
+ * ```
+ */
+export async function trackCommand(commandName, fn, options) {
+    if (!isTelemetryEnabled()) {
+        return fn();
+    }
+    const startTime = Date.now();
+    let state = 'SUCCESS';
+    let errorInfo;
+    try {
+        await fn();
+    }
+    catch (error) {
+        state = 'FAIL';
+        errorInfo = classifyError(error);
+        throw error;
+    }
+    finally {
+        const duration = Date.now() - startTime;
+        buildAndSendEvent({
+            command: commandName,
+            state,
+            duration,
+            ...(errorInfo && { error: errorInfo }),
+            ...(options && {
+                product: {
+                    ...(options.cdkVersion && { cdkVersion: options.cdkVersion }),
+                    ...(options.framework && { framework: options.framework }),
+                    ...(options.template && { template: options.template }),
+                    ...(options.templateVersion && { templateVersion: options.templateVersion }),
+                },
+            }),
+            ...(options?.blocksCount !== undefined && {
+                counters: { blocksCount: options.blocksCount },
+            }),
+        });
+    }
+}

package/dist/telemetry/types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Command names tracked by the Blocks CLI telemetry system.
+ */
+export type CommandName = 'create-blocks-app' | 'dev' | 'sandbox' | 'sandbox:destroy' | 'deploy' | 'destroy' | 'cleanup' | 'console' | 'vendorize';
+/**
+ * Terminal state of a command execution.
+ */
+export type CommandState = 'SUCCESS' | 'FAIL' | 'ABORTED';
+/**
+ * The telemetry event payload sent to the endpoint.
+ *
+ * Matches the server schema exactly (additionalProperties: false).
+ * All fields are anonymized — no PII, no customer content, no account IDs.
+ */
+export interface BlocksTelemetryEvent {
+    telemetryVersion: string;
+    identifiers: {
+        installationId: string;
+        projectId: string;
+        eventId: string;
+        timestamp: string;
+    };
+    event: {
+        command: CommandName;
+        state: CommandState;
+        duration: number;
+        error?: {
+            code: string;
+            phase: string;
+        };
+    };
+    environment: {
+        os: 'linux' | 'darwin' | 'win32';
+        nodeVersion: string;
+        ci: boolean;
+        packageManager?: string;
+        agent?: string;
+    };
+    product?: {
+        blocksVersion: string;
+        cdkVersion?: string;
+        framework?: 'nextjs' | 'spa' | 'static';
+        template?: {
+            name: string;
+            version?: string;
+        };
+        buildingBlocks?: Array<{
+            name: string;
+            version: string;
+        }>;
+    };
+    counters?: {
+        blocksCount: number;
+        customBuildingBlocks?: number;
+    };
+}
+/**
+ * Options for the `trackCommand` utility.
+ */
+export interface TrackCommandOptions {
+    template?: string;
+    templateVersion?: string;
+    framework?: 'nextjs' | 'spa' | 'static';
+    cdkVersion?: string;
+    blocksCount?: number;
+}
+/**
+ * Options accepted by `buildAndSendEvent()`.
+ *
+ * Callers provide minimal metadata; the function resolves identifiers,
+ * environment, and consent internally.
+ */
+export interface BuildAndSendEventOptions {
+    command: CommandName;
+    state: CommandState;
+    duration: number;
+    error?: {
+        code: string;
+        phase: string;
+    };
+    product?: {
+        cdkVersion?: string;
+        framework?: 'nextjs' | 'spa' | 'static';
+        template?: string;
+        templateVersion?: string;
+    };
+    counters?: {
+        blocksCount: number;
+        customBuildingBlocks?: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/telemetry/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/telemetry/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,WAAW,GACnB,mBAAmB,GACnB,KAAK,GACL,SAAS,GACT,iBAAiB,GACjB,QAAQ,GACR,SAAS,GACT,SAAS,GACT,SAAS,GACT,WAAW,CAAC;AAEhB;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE;QACX,cAAc,EAAE,MAAM,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,KAAK,EAAE;QACL,OAAO,EAAE,WAAW,CAAC;QACrB,KAAK,EAAE,YAAY,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE;YACN,IAAI,EAAE,MAAM,CAAC;YACb,KAAK,EAAE,MAAM,CAAC;SACf,CAAC;KACH,CAAC;IACF,WAAW,EAAE;QACX,EAAE,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;QACjC,WAAW,EAAE,MAAM,CAAC;QACpB,EAAE,EAAE,OAAO,CAAC;QACZ,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,OAAO,CAAC,EAAE;QACR,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,CAAC;QACxC,QAAQ,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAC9C,cAAc,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC3D,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,WAAW,EAAE,MAAM,CAAC;QACpB,oBAAoB,CAAC,EAAE,MAAM,CAAC;KAC/B,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,WAAW,CAAC;IACrB,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,CAAC;QACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,QAAQ,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE"}

package/dist/telemetry/types.js

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -0,0 +1,24 @@
+import type { Construct } from 'constructs';
+/**
+ * Infrastructure layer function signature.
+ * Exported from `infra.ts` in a Building Block.
+ */
+export type MaterializeFn<TOptions = any> = (scope: Construct, name: string, options: TOptions) => void | Record<string, any>;
+/**
+ * Building Block metadata discovered by Blocks.
+ */
+export interface BuildingBlockMetadata {
+    name: string;
+    runtimePath?: string;
+    infraPath?: string;
+    mockPath?: string;
+    clientHookPath?: string;
+}
+/**
+ * Client-side protocol extension hook.
+ */
+export interface ClientSideAPIHook {
+    onResponse?(response: Response): Promise<void>;
+    onRequest?(request: Request): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;GAGG;AACH,MAAM,MAAM,aAAa,CAAC,QAAQ,GAAG,GAAG,IAAI,CAC1C,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,KACd,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEhC;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,SAAS,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C"}

package/dist/types.js

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

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const CORE_VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,YAAY,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,2 @@
+// Auto-generated by scripts/generate-version.mjs — do not edit manually
+export const CORE_VERSION = '0.1.0';

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@aws-blocks/core",
+  "version": "0.1.0",
+  "author": "Amazon Web Services",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": [
+    "./dist/server/withAuth.js"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "src",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "browser": "./dist/client/index.js",
+      "cdk": "./dist/index.cdk.js",
+      "default": "./dist/index.js"
+    },
+    "./cdk": {
+      "types": "./dist/index.cdk.js",
+      "default": "./dist/index.cdk.js"
+    },
+    "./client": "./dist/client/index.js",
+    "./lambda-handler": "./dist/lambda-handler.js",
+    "./bb-utils": {
+      "types": "./dist/bb-utils.d.ts",
+      "default": "./dist/bb-utils.js"
+    },
+    "./version": {
+      "types": "./dist/version.d.ts",
+      "default": "./dist/version.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js",
+      "require": "./dist/server/index.js"
+    },
+    "./scripts": "./dist/scripts/index.js",
+    "./db-naming": {
+      "types": "./dist/db-naming.d.ts",
+      "default": "./dist/db-naming.js"
+    }
+  },
+  "scripts": {
+    "prebuild": "node ../../scripts/generate-version.mjs --core && node ../../scripts/generate-bb-names.mjs",
+    "build": "tsc --build",
+    "test": "node --test dist/*.test.js dist/**/*.test.js",
+    "dev": "tsc --build --watch"
+  },
+  "bin": {
+    "blocks-generate-spec": "./dist/scripts/generate-spec-cli.js",
+    "blocks-telemetry": "./dist/scripts/telemetry-cli.js"
+  },
+  "devDependencies": {
+    "@types/http-proxy": "^1.17.16",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0",
+    "unctx": "^2.0.0"
+  },
+  "dependencies": {
+    "@aws-blocks/hosting": "*",
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@aws-sdk/client-ssm": "^3.700.0",
+    "http-proxy": "^1.18.1"
+  },
+  "peerDependencies": {
+    "aws-cdk-lib": "^2.257.0",
+    "constructs": "^10.6.0",
+    "next": ">=13.0.0",
+    "unctx": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "unctx": {
+      "optional": true
+    }
+  }
+}

package/src/api.test.ts

@@ -0,0 +1,25 @@
+// 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 { ApiNamespace, API_NAMESPACE_MARKER } from './api.js';
+import { Scope } from './common/index.js';
+
+const scope = new Scope('test');
+
+test('ApiNamespace stores name via marker symbol', () => {
+  const api1 = new ApiNamespace(scope, 'myapi', (ctx) => ({
+    test: () => 'hello'
+  }));
+  
+  assert.strictEqual((api1 as any)[API_NAMESPACE_MARKER], 'myapi');
+});
+
+test('Different ApiNamespace names should not collide', () => {
+  const api1 = new ApiNamespace(scope, 'api1', (ctx) => ({ test: () => 'a' }));
+  const api2 = new ApiNamespace(scope, 'api2', (ctx) => ({ test: () => 'b' }));
+  
+  assert.strictEqual((api1 as any)[API_NAMESPACE_MARKER], 'api1');
+  assert.strictEqual((api2 as any)[API_NAMESPACE_MARKER], 'api2');
+});

package/src/api.ts

@@ -0,0 +1,163 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export type BlocksContext = {
+  request: {
+    headers: Headers;
+    body: ReadableStream<Uint8Array> | null;
+    json: () => Promise<any>;
+    text: () => Promise<string>;
+    /**
+     * Absolute URL of the incoming request. Built from the request's `host`
+     * header plus the path + query string. Useful for RawRoute handlers
+     * that need query-string parsing or must echo the request URL back
+     * (e.g., building OIDC redirect URIs).
+     *
+     * In dev: derived from `req.url` and `req.headers.host`.
+     * In AWS: derived from `event.path`, `event.queryStringParameters`,
+     * and `event.headers.host`. May include a trusted `x-forwarded-proto`
+     * to pick http vs https.
+     */
+    url: URL;
+    /**
+     * Path parameters extracted from RawRoute patterns.
+     * Example: route `/users/{id}` with request `/users/123` → `{ id: '123' }`.
+     *
+     * Only populated for RawRoute handlers. Always `{}` for RPC API methods.
+     */
+    params: Record<string, string>;
+    /**
+     * Abort signal tied to the HTTP deadline guard.
+     *
+     * Fires when the Lambda is about to return a 504 timeout response.
+     * Pass this to `fetch()`, AWS SDK calls, or any cancellable I/O so
+     * in-flight work is cancelled rather than continuing to run (and bill)
+     * after the client has already received a timeout.
+     *
+     * `undefined` in local dev or when no deadline is configured.
+     */
+    signal?: AbortSignal;
+  };
+  response: {
+    headers: Headers;
+    status: number;
+    send: (body: any) => void;
+  };
+};
+
+export type ApiHandler<T extends Record<string, (...args: any[]) => any>> = (context: BlocksContext) => T;
+
+// Map all methods to return Promises
+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;
+};
+
+/** Marker symbol to identify ApiNamespace instances during discovery. */
+export const API_NAMESPACE_MARKER = Symbol.for('blocks:ApiNamespace');
+
+import type { ScopeParent } from './common/index.js';
+
+/**
+ * Define a type-safe API namespace that works seamlessly between frontend and backend.
+ * 
+ * ## Usage
+ * 
+ * Define your API in the backend (`aws-blocks/index.ts`):
+ * 
+ * ```typescript
+ * const scope = new Scope('my-app');
+ * 
+ * export const api = new ApiNamespace(scope, 'api', (context) => ({
+ *   async greet(name: string) {
+ *     return { message: `Hello, ${name}!` };
+ *   },
+ *   
+ *   async deleteAccount(id: string) {
+ *     // Gated: throws 401 if the caller has no valid session.
+ *     await auth.requireAuth(context);
+ *     return db.users.delete(id);
+ *   }
+ * }));
+ * ```
+ * 
+ * Import and call from the frontend with full type safety:
+ * 
+ * ```typescript
+ * import { api } from 'aws-blocks';
+ * 
+ * const result = await api.greet('World'); // Fully typed
+ * ```
+ * 
+ * ## Authentication — every method is a public endpoint
+ * 
+ * Each method becomes a public, internet-reachable RPC endpoint with **no
+ * authentication by default**. Gating is opt-in per method by calling an auth
+ * Building Block at the top of the handler:
+ * 
+ * ```typescript
+ * export const api = new ApiNamespace(scope, 'api', (context) => ({
+ *   // No requireAuth call → callable by anyone.
+ *   async listPublicPosts() {
+ *     return db.posts.findPublished();
+ *   },
+ * 
+ *   async createPost(input: NewPost) {
+ *     const user = await auth.requireAuth(context);
+ *     return db.posts.create({ ...input, authorId: user.userId });
+ *   },
+ * 
+ *   async deletePost(id: string) {
+ *     await auth.requireRole(context, 'admins');
+ *     return db.posts.delete(id);
+ *   },
+ * }));
+ * ```
+ * 
+ * The local mock applies no auth either, so an ungated method passes every
+ * local check and still ships callable by anyone. See your auth block's README
+ * (e.g. `@aws-blocks/bb-auth-cognito`) for `requireAuth` / `requireRole`.
+ * 
+ * ## Context
+ * 
+ * The `context` parameter provides access to:
+ * - `context.request.headers` - Incoming request headers
+ * - `context.request.json()` - Parse request body as JSON
+ * - `context.response.headers` - Set response headers (e.g., cookies)
+ * - `context.response.status` - Set HTTP status code
+ * 
+ * ## Local vs Deployed
+ * 
+ * - **Local**: APIs run in-process. Calls are direct function invocations.
+ * - **Deployed**: APIs run in Lambda. Calls go through API Gateway over HTTPS.
+ * 
+ * The same code works in both environments without changes.
+ * 
+ * ## Scaling Characteristics (AWS)
+ * 
+ * - Serverless: Auto-scales from 0 to thousands of concurrent requests
+ * - Cold starts: ~100-500ms for first request after idle period
+ * - Warm requests: Single-digit millisecond overhead
+ * - Cost: Pay per request (free tier: 1M requests/month)
+ * 
+ * ## Best Practices
+ * 
+ * - No auth by default — gate methods with `requireAuth`/`requireRole` (see above)
+ * - Keep API methods focused and single-purpose
+ * - Use async/await for all I/O operations
+ * - Return serializable data (JSON-compatible types)
+ * - Handle errors explicitly - they'll be sent to the client
+ * - Use Building Blocks (KVStore, DistributedTable) for state
+ */
+export interface ApiNamespaceConstructor {
+  new <T extends Record<string, (...args: any[]) => any>>(scope: ScopeParent, name: string, handler: ApiHandler<T>): AsyncAPI<T>;
+}
+
+export const ApiNamespace: ApiNamespaceConstructor = class ApiNamespace {
+  constructor(scope: ScopeParent, name: string, handler: any) {
+    handler[API_NAMESPACE_MARKER] = name;
+    return handler;
+  }
+} as any;
+

package/src/bb-utils.ts

@@ -0,0 +1,13 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Utilities for Building Block authors.
+ *
+ * Used by standard BBs and available to customers writing custom Building Blocks.
+ * Not part of the main '.' export — import from '@aws-blocks/core/bb-utils'.
+ */
+export { getMockDataDir } from './common/mock-data.js';
+export { API_NAMESPACE_MARKER } from './api.js';
+export { EventSourceMapping } from './lambda-handler.js';
+export { constantTimeEquals } from './common/crypto.js';

package/src/builtin-routes.ts

@@ -0,0 +1,62 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { getRegisteredRoutes, registerRoute } from './raw-route.js';
+import { exec } from 'node:child_process';
+import { join } from 'node:path';
+import type { BlocksContext } from './api.js';
+
+function openInEditor(filePath: string): void {
+	const platform = process.platform;
+	const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'start ""' : 'xdg-open';
+	exec(`${cmd} "${filePath}"`);
+}
+
+/**
+ * Register built-in /aws-blocks/resources and /aws-blocks/settings routes.
+ * Skips if already registered (safe to call from both CDK and dev server).
+ */
+export function registerBuiltinRoutes(): void {
+	const routes: Array<{ method: 'GET' | 'POST'; path: string; handler: (ctx: BlocksContext) => Promise<void> }> = [
+		{
+			method: 'GET',
+			path: '/aws-blocks/resources',
+			handler: async (ctx: BlocksContext) => {
+				const url = process.env.BB_RESOURCES_GROUP_URL;
+				if (!url) {
+					ctx.response.status = 200;
+					ctx.response.headers.set('Content-Type', 'text/html');
+					ctx.response.send(`<!DOCTYPE html><html><head><title>Resources</title><style>body{font-family:system-ui,sans-serif;max-width:640px;margin:4rem auto;padding:0 1rem;color:#1a1a1a}h1{font-size:1.5rem}p{line-height:1.6}code{background:#f3f4f6;padding:2px 6px;border-radius:4px;font-size:0.9em}</style></head><body><h1>Resources</h1><p>Locally, each Building Block persists data to <code>.bb-data/</code> in your project root. Tables, buckets, queues, and other state live under <code>.bb-data/{id}/</code>.</p><p>For deployed apps, this page automatically redirects to the Resources group in the AWS console.</p></body></html>`);
+					return;
+				}
+				ctx.response.status = 302;
+				ctx.response.headers.set('Location', url);
+				ctx.response.send('');
+			},
+		},
+		{
+			method: 'GET',
+			path: '/aws-blocks/settings',
+			handler: async (ctx: BlocksContext) => {
+				const url = process.env.BB_SETTINGS_GROUP_URL;
+				if (!url) {
+					const settingsPath = join(process.cwd(), '.bb-data', 'settings.json');
+					openInEditor(settingsPath);
+					ctx.response.status = 200;
+					ctx.response.headers.set('Content-Type', 'text/html');
+					ctx.response.send(`<!DOCTYPE html><html><head><title>Settings</title><style>body{font-family:system-ui,sans-serif;max-width:640px;margin:4rem auto;padding:0 1rem;color:#1a1a1a}h1{font-size:1.5rem}p{line-height:1.6}code{background:#f3f4f6;padding:2px 6px;border-radius:4px;font-size:0.9em}a{color:#0066cc}</style></head><body><h1>Settings</h1><p>Opening <code>.bb-data/settings.json</code> in your default editor.</p><p>All AppSetting values are stored as <code>{ "fullId": value }</code> entries. Edit and save -- changes take effect on the next <code>get()</code> call.</p><p>File location: <code>${settingsPath}</code></p></body></html>`);
+					return;
+				}
+				ctx.response.status = 302;
+				ctx.response.headers.set('Location', url);
+				ctx.response.send('');
+			},
+		},
+	];
+
+	for (const route of routes) {
+		if (!getRegisteredRoutes().some(r => r.method === route.method && r.path === route.path)) {
+			registerRoute(route);
+		}
+	}
+}

package/src/cdk/__fixtures__/factory-backend.ts

@@ -0,0 +1,8 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Construct } from 'constructs';
+
+export default function (scope: Construct) {
+  new Construct(scope, 'FactoryMarker');
+}