@aws-blocks/core 0.1.3 → 0.1.4

package/dist/constants.d.ts

@@ -24,4 +24,16 @@ export declare const BLOCKS_RPC_PREFIX = "/aws-blocks/api";
  * prefix; CloudFront forwards the subtree and the Lambda dispatches by path.
  */
 export declare const BLOCKS_AUTH_PREFIX = "/aws-blocks/auth";
+/**
+ * Reserved path for the client runtime config (`config.json`).
+ *
+ * In production CloudFront serves `${BLOCKS_SANDBOX_PREFIX}/*` from S3 as
+ * static assets (see hosting.ts) so the browser client can resolve its API
+ * URL. The local dev server mirrors this by serving the config from the front
+ * door itself, instead of proxying the request to the framework dev server —
+ * which only serves its own static dir (Next.js `public/`, etc.) and would 404
+ * on a project-root file. Keeping this symmetric with production is what makes
+ * the browser client work the same in `dev`, `sandbox`, and deployed.
+ */
+export declare const BLOCKS_SANDBOX_PREFIX = "/.blocks-sandbox";
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

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

package/dist/constants.js

@@ -26,3 +26,15 @@ export const BLOCKS_RPC_PREFIX = '/aws-blocks/api';
  * prefix; CloudFront forwards the subtree and the Lambda dispatches by path.
  */
 export const BLOCKS_AUTH_PREFIX = '/aws-blocks/auth';
+/**
+ * Reserved path for the client runtime config (`config.json`).
+ *
+ * In production CloudFront serves `${BLOCKS_SANDBOX_PREFIX}/*` from S3 as
+ * static assets (see hosting.ts) so the browser client can resolve its API
+ * URL. The local dev server mirrors this by serving the config from the front
+ * door itself, instead of proxying the request to the framework dev server —
+ * which only serves its own static dir (Next.js `public/`, etc.) and would 404
+ * on a project-root file. Keeping this symmetric with production is what makes
+ * the browser client work the same in `dev`, `sandbox`, and deployed.
+ */
+export const BLOCKS_SANDBOX_PREFIX = '/.blocks-sandbox';

package/dist/scripts/dev-server-config.test.d.ts

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

package/dist/scripts/dev-server-config.test.d.ts.map

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

package/dist/scripts/dev-server-config.test.js

@@ -0,0 +1,37 @@
+// 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 { buildBlocksConfig, isBlocksConfigRequest } from './dev-server.js';
+describe('buildBlocksConfig — client runtime config', () => {
+    it('points the browser at the localhost front door RPC endpoint', () => {
+        assert.deepStrictEqual(buildBlocksConfig(3000, false), {
+            apiUrl: 'http://localhost:3000/aws-blocks/api',
+            environment: 'local',
+        });
+    });
+    it('honors a custom port', () => {
+        assert.strictEqual(buildBlocksConfig(4000, false).apiUrl, 'http://localhost:4000/aws-blocks/api');
+    });
+    it('marks the environment as sandbox but keeps the localhost front door', () => {
+        assert.deepStrictEqual(buildBlocksConfig(3000, true), {
+            apiUrl: 'http://localhost:3000/aws-blocks/api',
+            environment: 'sandbox',
+        });
+    });
+});
+describe('isBlocksConfigRequest — reserved runtime-config path', () => {
+    it('matches GET /.blocks-sandbox/config.json', () => {
+        assert.strictEqual(isBlocksConfigRequest('GET', '/.blocks-sandbox/config.json'), true);
+    });
+    it('ignores non-GET methods (only the static-style read is reserved)', () => {
+        assert.strictEqual(isBlocksConfigRequest('POST', '/.blocks-sandbox/config.json'), false);
+        assert.strictEqual(isBlocksConfigRequest('HEAD', '/.blocks-sandbox/config.json'), false);
+    });
+    it('does not match other paths (frontend/app routes pass through to the proxy)', () => {
+        assert.strictEqual(isBlocksConfigRequest('GET', '/'), false);
+        assert.strictEqual(isBlocksConfigRequest('GET', '/api/chat'), false);
+        assert.strictEqual(isBlocksConfigRequest('GET', '/.blocks-sandbox/other.json'), false);
+        assert.strictEqual(isBlocksConfigRequest('GET', '/aws-blocks/api'), false);
+    });
+});

package/dist/scripts/dev-server.d.ts

@@ -4,6 +4,25 @@ export declare const LOCALHOST_PATTERN: RegExp;
  * Reflects back origins matching localhost/127.0.0.1; otherwise returns the fallback.
  */
 export declare function resolveDevCorsOrigin(origin: string): string;
+/** Shape of the client runtime config the browser fetches to discover the API URL. */
+export interface BlocksRuntimeConfig {
+    apiUrl: string;
+    environment: 'local' | 'sandbox';
+}
+/**
+ * Build the runtime config the browser fetches at `${BLOCKS_SANDBOX_PREFIX}/config.json`.
+ * In sandbox mode the browser still targets the localhost front door (the dev
+ * server proxies `/aws-blocks/api` to the deployed API), so the shape is the
+ * same in both modes — only `environment` differs.
+ */
+export declare function buildBlocksConfig(port: number, isSandbox: boolean): BlocksRuntimeConfig;
+/**
+ * True for the reserved runtime-config request the dev server answers itself
+ * (mirroring production, where CloudFront serves `${BLOCKS_SANDBOX_PREFIX}/*`
+ * statically) instead of proxying it to the framework dev server — which only
+ * serves its own static dir (Next.js `public/`, etc.) and would 404.
+ */
+export declare function isBlocksConfigRequest(method: string, pathname: string): boolean;
 export interface DevServerOptions {
     /** Customer-facing port. Default: 3000. */
     port?: number;

package/dist/scripts/dev-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev-server.d.ts","sourceRoot":"","sources":["../../src/scripts/dev-server.ts"],"names":[],"mappings":"AAmCA,eAAO,MAAM,iBAAiB,QAAiD,CAAC;AAEhF;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAmCD,wBAAsB,cAAc,CAAC,OAAO,EAAE,gBAAgB,iBAiP7D"}
+{"version":3,"file":"dev-server.d.ts","sourceRoot":"","sources":["../../src/scripts/dev-server.ts"],"names":[],"mappings":"AAmCA,eAAO,MAAM,iBAAiB,QAAiD,CAAC;AAEhF;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,sFAAsF;AACtF,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,OAAO,GAAG,SAAS,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,mBAAmB,CAKvF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE/E;AAED,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAmCD,wBAAsB,cAAc,CAAC,OAAO,EAAE,gBAAgB,iBA8P7D"}

package/dist/scripts/dev-server.js

@@ -9,7 +9,7 @@ import { createConnection } from 'node:net';
 import httpProxy from 'http-proxy';
 import { writeClientCode } from './generate-client.js';
 import { ApiError } from '../errors.js';
-import { BLOCKS_RPC_PREFIX } from '../constants.js';
+import { BLOCKS_RPC_PREFIX, BLOCKS_SANDBOX_PREFIX } from '../constants.js';
 import { matchRoute, lockRouteRegistry } from '../raw-route.js';
 import { registerBuiltinRoutes } from '../builtin-routes.js';
 import { parseRpcRequest, successResponse, errorResponseFromCatch, methodNotFoundResponse, } from '../rpc.js';
@@ -34,6 +34,27 @@ export const LOCALHOST_PATTERN = /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/;
 export function resolveDevCorsOrigin(origin) {
     return LOCALHOST_PATTERN.test(origin) ? origin : 'http://localhost:3000';
 }
+/**
+ * Build the runtime config the browser fetches at `${BLOCKS_SANDBOX_PREFIX}/config.json`.
+ * In sandbox mode the browser still targets the localhost front door (the dev
+ * server proxies `/aws-blocks/api` to the deployed API), so the shape is the
+ * same in both modes — only `environment` differs.
+ */
+export function buildBlocksConfig(port, isSandbox) {
+    return {
+        apiUrl: `http://localhost:${port}${BLOCKS_RPC_PREFIX}`,
+        environment: isSandbox ? 'sandbox' : 'local',
+    };
+}
+/**
+ * True for the reserved runtime-config request the dev server answers itself
+ * (mirroring production, where CloudFront serves `${BLOCKS_SANDBOX_PREFIX}/*`
+ * statically) instead of proxying it to the framework dev server — which only
+ * serves its own static dir (Next.js `public/`, etc.) and would 404.
+ */
+export function isBlocksConfigRequest(method, pathname) {
+    return method === 'GET' && pathname === `${BLOCKS_SANDBOX_PREFIX}/config.json`;
+}
 /**
  * Initialize all building blocks that have an initialize() method.
  * This is the "local deploy" phase - mirrors CDK deploy.
@@ -95,11 +116,9 @@ export async function startDevServer(options) {
     // BLOCKS_API_URL server-side, so the request still reaches the deployed Lambda.
     // This makes sandbox single-origin, matching `npm run dev` and the prod
     // CloudFront proxy; `crossDomain` stays unnecessary.
+    const blocksConfig = buildBlocksConfig(port, isSandbox);
     mkdirSync('.blocks-sandbox', { recursive: true });
-    writeFileSync('.blocks-sandbox/config.json', JSON.stringify({
-        apiUrl: `http://localhost:${port}${BLOCKS_RPC_PREFIX}`,
-        environment: isSandbox ? 'sandbox' : 'local',
-    }, null, 2));
+    writeFileSync('.blocks-sandbox/config.json', JSON.stringify(blocksConfig, null, 2));
     // 1. Set up global collectors for plugin discovery
     globalThis.__BLOCKS_CLIENT_MIDDLEWARE__ = [];
     globalThis.__BLOCKS_DEV_ATTACHMENTS__ = [];
@@ -181,6 +200,20 @@ export async function startDevServer(options) {
             res.end();
             return;
         }
+        // ── Blocks runtime config ──────────────────────────────────────────
+        // Reserved path: serve it from the front door so it works for every
+        // framework (Next/Nuxt/Astro/SPA all proxy through this :3000 server),
+        // mirroring production where CloudFront serves `${BLOCKS_SANDBOX_PREFIX}/*`
+        // statically. Otherwise the request is proxied to the framework dev
+        // server, which can't serve this project-root file and 404s.
+        if (isBlocksConfigRequest(method, url.pathname)) {
+            res.writeHead(200, {
+                'Content-Type': 'application/json',
+                'Cache-Control': 'no-store',
+            });
+            res.end(JSON.stringify(blocksConfig));
+            return;
+        }
         // ── API/RawRoute requests ──────────────────────────────────────────
         if (isApiRequest(method, url.pathname)) {
             if (isSandbox && apiProxy) {

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-blocks/core",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "author": "Amazon Web Services",
   "license": "Apache-2.0",
   "type": "module",

package/src/constants.ts

@@ -29,3 +29,16 @@ export const BLOCKS_RPC_PREFIX = '/aws-blocks/api';
  * prefix; CloudFront forwards the subtree and the Lambda dispatches by path.
  */
 export const BLOCKS_AUTH_PREFIX = '/aws-blocks/auth';
+
+/**
+ * Reserved path for the client runtime config (`config.json`).
+ *
+ * In production CloudFront serves `${BLOCKS_SANDBOX_PREFIX}/*` from S3 as
+ * static assets (see hosting.ts) so the browser client can resolve its API
+ * URL. The local dev server mirrors this by serving the config from the front
+ * door itself, instead of proxying the request to the framework dev server —
+ * which only serves its own static dir (Next.js `public/`, etc.) and would 404
+ * on a project-root file. Keeping this symmetric with production is what makes
+ * the browser client work the same in `dev`, `sandbox`, and deployed.
+ */
+export const BLOCKS_SANDBOX_PREFIX = '/.blocks-sandbox';

package/src/scripts/dev-server-config.test.ts

@@ -0,0 +1,43 @@
+// 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 { buildBlocksConfig, isBlocksConfigRequest } from './dev-server.js';
+
+describe('buildBlocksConfig — client runtime config', () => {
+  it('points the browser at the localhost front door RPC endpoint', () => {
+    assert.deepStrictEqual(buildBlocksConfig(3000, false), {
+      apiUrl: 'http://localhost:3000/aws-blocks/api',
+      environment: 'local',
+    });
+  });
+
+  it('honors a custom port', () => {
+    assert.strictEqual(buildBlocksConfig(4000, false).apiUrl, 'http://localhost:4000/aws-blocks/api');
+  });
+
+  it('marks the environment as sandbox but keeps the localhost front door', () => {
+    assert.deepStrictEqual(buildBlocksConfig(3000, true), {
+      apiUrl: 'http://localhost:3000/aws-blocks/api',
+      environment: 'sandbox',
+    });
+  });
+});
+
+describe('isBlocksConfigRequest — reserved runtime-config path', () => {
+  it('matches GET /.blocks-sandbox/config.json', () => {
+    assert.strictEqual(isBlocksConfigRequest('GET', '/.blocks-sandbox/config.json'), true);
+  });
+
+  it('ignores non-GET methods (only the static-style read is reserved)', () => {
+    assert.strictEqual(isBlocksConfigRequest('POST', '/.blocks-sandbox/config.json'), false);
+    assert.strictEqual(isBlocksConfigRequest('HEAD', '/.blocks-sandbox/config.json'), false);
+  });
+
+  it('does not match other paths (frontend/app routes pass through to the proxy)', () => {
+    assert.strictEqual(isBlocksConfigRequest('GET', '/'), false);
+    assert.strictEqual(isBlocksConfigRequest('GET', '/api/chat'), false);
+    assert.strictEqual(isBlocksConfigRequest('GET', '/.blocks-sandbox/other.json'), false);
+    assert.strictEqual(isBlocksConfigRequest('GET', '/aws-blocks/api'), false);
+  });
+});

package/src/scripts/dev-server.ts

@@ -4,13 +4,13 @@
 import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
 import { pathToFileURL, URL } from 'node:url';
 import { resolve, dirname, join } from 'node:path';
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { writeFileSync, mkdirSync } from 'node:fs';
 import { spawn, type ChildProcess } from 'node:child_process';
 import { createConnection } from 'node:net';
 import httpProxy from 'http-proxy';
 import { writeClientCode } from './generate-client.js';
 import { ApiError } from '../errors.js';
-import { BLOCKS_RPC_PREFIX } from '../constants.js';
+import { BLOCKS_RPC_PREFIX, BLOCKS_SANDBOX_PREFIX } from '../constants.js';
 import { matchRoute, lockRouteRegistry } from '../raw-route.js';
 import { registerBuiltinRoutes } from '../builtin-routes.js';
 import {
@@ -43,6 +43,35 @@ export function resolveDevCorsOrigin(origin: string): string {
   return LOCALHOST_PATTERN.test(origin) ? origin : 'http://localhost:3000';
 }
 
+/** Shape of the client runtime config the browser fetches to discover the API URL. */
+export interface BlocksRuntimeConfig {
+  apiUrl: string;
+  environment: 'local' | 'sandbox';
+}
+
+/**
+ * Build the runtime config the browser fetches at `${BLOCKS_SANDBOX_PREFIX}/config.json`.
+ * In sandbox mode the browser still targets the localhost front door (the dev
+ * server proxies `/aws-blocks/api` to the deployed API), so the shape is the
+ * same in both modes — only `environment` differs.
+ */
+export function buildBlocksConfig(port: number, isSandbox: boolean): BlocksRuntimeConfig {
+  return {
+    apiUrl: `http://localhost:${port}${BLOCKS_RPC_PREFIX}`,
+    environment: isSandbox ? 'sandbox' : 'local',
+  };
+}
+
+/**
+ * True for the reserved runtime-config request the dev server answers itself
+ * (mirroring production, where CloudFront serves `${BLOCKS_SANDBOX_PREFIX}/*`
+ * statically) instead of proxying it to the framework dev server — which only
+ * serves its own static dir (Next.js `public/`, etc.) and would 404.
+ */
+export function isBlocksConfigRequest(method: string, pathname: string): boolean {
+  return method === 'GET' && pathname === `${BLOCKS_SANDBOX_PREFIX}/config.json`;
+}
+
 export interface DevServerOptions {
   /** Customer-facing port. Default: 3000. */
   port?: number;
@@ -125,11 +154,9 @@ export async function startDevServer(options: DevServerOptions) {
   // BLOCKS_API_URL server-side, so the request still reaches the deployed Lambda.
   // This makes sandbox single-origin, matching `npm run dev` and the prod
   // CloudFront proxy; `crossDomain` stays unnecessary.
+  const blocksConfig = buildBlocksConfig(port, isSandbox);
   mkdirSync('.blocks-sandbox', { recursive: true });
-  writeFileSync('.blocks-sandbox/config.json', JSON.stringify({
-    apiUrl: `http://localhost:${port}${BLOCKS_RPC_PREFIX}`,
-    environment: isSandbox ? 'sandbox' : 'local',
-  }, null, 2));
+  writeFileSync('.blocks-sandbox/config.json', JSON.stringify(blocksConfig, null, 2));
 
   // 1. Set up global collectors for plugin discovery
   (globalThis as any).__BLOCKS_CLIENT_MIDDLEWARE__ = [];
@@ -221,6 +248,21 @@ export async function startDevServer(options: DevServerOptions) {
       return;
     }
 
+    // ── Blocks runtime config ──────────────────────────────────────────
+    // Reserved path: serve it from the front door so it works for every
+    // framework (Next/Nuxt/Astro/SPA all proxy through this :3000 server),
+    // mirroring production where CloudFront serves `${BLOCKS_SANDBOX_PREFIX}/*`
+    // statically. Otherwise the request is proxied to the framework dev
+    // server, which can't serve this project-root file and 404s.
+    if (isBlocksConfigRequest(method, url.pathname)) {
+      res.writeHead(200, {
+        'Content-Type': 'application/json',
+        'Cache-Control': 'no-store',
+      });
+      res.end(JSON.stringify(blocksConfig));
+      return;
+    }
+
     // ── API/RawRoute requests ──────────────────────────────────────────
     if (isApiRequest(method, url.pathname)) {
       if (isSandbox && apiProxy) {

package/src/version.ts

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