@aws-blocks/core 0.1.0

package/dist/client/index.js

@@ -0,0 +1,238 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { encodeRpcRequest, decodeRpcResponse } from '../rpc.js';
+const IS_SSR = typeof window === 'undefined';
+// SSR cookie forwarding: reads from a global AsyncLocalStorage that SSR
+// frameworks populate with the inbound request's cookies. The store is
+// accessed via a well-known global key so the client bundle never imports
+// node:async_hooks (which would break browser/webpack builds).
+function getSsrCookies() {
+    if (!IS_SSR)
+        return undefined;
+    if (typeof globalThis === 'undefined')
+        return undefined;
+    const store = globalThis.__BLOCKS_REQUEST_COOKIES_STORE__;
+    if (!store || typeof store.getStore !== 'function')
+        return undefined;
+    return store.getStore();
+}
+let API_URL = null;
+let apiUrlPromise = null;
+async function getApiUrl() {
+    if (API_URL)
+        return API_URL;
+    if (apiUrlPromise)
+        return apiUrlPromise;
+    apiUrlPromise = resolveApiUrl().catch((err) => {
+        // Don't cache failures — config.json may not exist yet during startup
+        apiUrlPromise = null;
+        throw err;
+    });
+    return apiUrlPromise;
+}
+async function resolveApiUrl() {
+    if (API_URL)
+        return API_URL;
+    function isInvalidUrl(url) {
+        if (!url || typeof url !== 'string' || !url.trim())
+            return true;
+        if (url === 'undefined' || url.startsWith('undefined'))
+            return true;
+        // Relative URLs (e.g. '/aws-blocks/api') are valid for browser fetch
+        if (url.startsWith('/'))
+            return false;
+        try {
+            const parsed = new URL(url);
+            return parsed.hostname === 'undefined' ||
+                parsed.pathname === '/undefined' ||
+                parsed.pathname.startsWith('/undefined/');
+        }
+        catch {
+            return true;
+        }
+    }
+    function validateAndCache(url, source) {
+        if (!url || typeof url !== 'string' || isInvalidUrl(url)) {
+            throw new Error(`Blocks API URL is not configured (source: ${source}). Ensure BLOCKS_API_URL environment variable is set ` +
+                'or config.json is deployed. Run with --conditions=cdk during CDK synthesis.');
+        }
+        API_URL = url;
+        return url;
+    }
+    // 1. SSR Lambda: env vars injected by Hosting construct
+    if (typeof process !== 'undefined' && process.env?.BLOCKS_API_URL) {
+        const url = process.env.BLOCKS_API_URL;
+        // CDK tokens (e.g. ${Token[TOKEN.1228]}) are present at build time but
+        // only resolve at CloudFormation deploy time.  If we detect them, the
+        // build is running inside `cdk synth` and the URL is not usable yet.
+        if (/\$\{Token\[/.test(url)) {
+            throw new Error('Blocks API URL contains unresolved CDK tokens. This usually means a ' +
+                'Server Component is being statically prerendered during `next build` ' +
+                'inside `cdk deploy`.\n' +
+                'Fix: add `export const dynamic = \'force-dynamic\';` to any page ' +
+                'that calls the Blocks API so Next.js skips prerendering it.');
+        }
+        const validated = validateAndCache(url, 'env BLOCKS_API_URL');
+        console.log('[Blocks] Using API (env BLOCKS_API_URL):', validated);
+        return validated;
+    }
+    // 2. SSR Lambda: full config as JSON env var
+    if (typeof process !== 'undefined' && process.env?.BLOCKS_CONFIG) {
+        try {
+            const config = JSON.parse(process.env.BLOCKS_CONFIG);
+            const validated = validateAndCache(config.apiUrl, 'env BLOCKS_CONFIG');
+            console.log('[Blocks] Using API (env BLOCKS_CONFIG):', validated);
+            return validated;
+        }
+        catch {
+            // Malformed BLOCKS_CONFIG — fall through
+        }
+    }
+    // 3. Node.js: read config file from filesystem
+    if (typeof process !== 'undefined' && process.versions?.node) {
+        try {
+            const fs = await import(/* webpackIgnore: true */ 'node:fs');
+            const config = JSON.parse(fs.readFileSync('.blocks-sandbox/config.json', 'utf-8'));
+            const validated = validateAndCache(config.apiUrl, 'config.json file');
+            console.log('[Blocks] Using API (config.json file):', validated);
+            return validated;
+        }
+        catch {
+            // Config doesn't exist or not in Node.js
+        }
+    }
+    // 4. Browser: fetch config.json from hosting origin
+    try {
+        const response = await fetch('/.blocks-sandbox/config.json');
+        if (response.ok) {
+            const config = await response.json();
+            const validated = validateAndCache(config.apiUrl, 'config.json fetch');
+            console.log('[Blocks] Using API (config.json fetch):', validated);
+            return validated;
+        }
+    }
+    catch {
+        // Config doesn't exist
+    }
+    // Fallback — no config found
+    throw new Error('Blocks API URL not configured. Ensure:\n' +
+        '1. You ran `npm run deploy` (deploys config.json)\n' +
+        '2. SSR Lambda has BLOCKS_API_URL env var, OR\n' +
+        '3. config.json exists at /.blocks-sandbox/config.json');
+}
+const middlewares = [];
+/**
+ * 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 function registerMiddleware(middleware) {
+    middlewares.push(middleware);
+}
+async function processRequest(request) {
+    for (const mw of middlewares) {
+        if (mw.onRequest) {
+            const result = await mw.onRequest(request);
+            if (result)
+                request = result;
+        }
+    }
+    return request;
+}
+function processResponse(data) {
+    for (const mw of middlewares) {
+        if (mw.onResponse) {
+            data = mw.onResponse(data);
+        }
+    }
+    return data;
+}
+/**
+ * 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 function ApiNamespaceClient(name, options) {
+    const urlOverride = options?.url;
+    return new Proxy({}, {
+        get(target, method) {
+            if (typeof method === 'symbol')
+                return undefined;
+            return async (...args) => {
+                const apiUrl = urlOverride ?? await getApiUrl();
+                let request = {
+                    apiNamespace: name,
+                    method,
+                    args,
+                    headers: { 'Content-Type': 'application/json' },
+                };
+                request = await processRequest(request);
+                // SSR cookie forwarding: when running server-side, forward the
+                // inbound request cookies so auth sessions propagate to API calls.
+                // Deduplicates by cookie name — existing cookies (from middleware)
+                // take precedence over SSR-forwarded ones.
+                const ssrCookies = getSsrCookies();
+                if (ssrCookies) {
+                    const existingKey = 'Cookie' in request.headers ? 'Cookie' : 'cookie' in request.headers ? 'cookie' : null;
+                    const existing = existingKey ? request.headers[existingKey] : undefined;
+                    if (existingKey && existingKey !== 'Cookie') {
+                        delete request.headers[existingKey];
+                    }
+                    if (existing) {
+                        const existingNames = new Set(existing.split(';').filter(Boolean).map((c) => c.trim().split('=')[0]));
+                        const newCookies = ssrCookies
+                            .split(';')
+                            .filter(Boolean)
+                            .filter((c) => !existingNames.has(c.trim().split('=')[0]))
+                            .join('; ');
+                        request.headers['Cookie'] = newCookies
+                            ? `${existing}; ${newCookies}`
+                            : existing;
+                    }
+                    else {
+                        request.headers['Cookie'] = ssrCookies;
+                    }
+                }
+                const response = await fetch(apiUrl, {
+                    method: 'POST',
+                    headers: request.headers,
+                    credentials: 'include',
+                    body: encodeRpcRequest(request.apiNamespace, request.method, request.args),
+                });
+                const rpcBody = await response.json();
+                const result = decodeRpcResponse(rpcBody); // throws ApiError on RPC error
+                return processResponse(result);
+            };
+        }
+    });
+}
+export { ApiError, isBlocksError } from '../errors.js';
+export { Scope } from '../common/index.js';

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

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

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

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

package/dist/client/index.test.js

@@ -0,0 +1,113 @@
+// 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, env) {
+    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}`);
+    });
+});

package/dist/common/config.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Get a config value by key.
+ *
+ * Checks `process.env[key]` first (local dev where env vars are set directly).
+ * If not found, reads from the cached S3 config file.
+ *
+ * @param key - The config key (e.g., `BLOCKS_AUTH_COGNITO_MYAPP_AUTHC_USER_POOL_ID`)
+ * @returns The config value, or empty string if not found anywhere
+ */
+export declare function getConfig(key: string): Promise<string>;
+/**
+ * Synchronous config access — returns the value if already cached, otherwise
+ * returns the process.env fallback. Use this only when you're certain the
+ * config has already been loaded (e.g., after an initial await getConfig() call).
+ *
+ * @param key - The config key
+ * @returns The config value, or empty string if not found
+ */
+export declare function getConfigSync(key: string): string;
+/**
+ * Preload the S3 config. Call this early in Lambda cold start to ensure
+ * the config is cached before any BB constructors need it.
+ *
+ * This is a no-op if the config is already loaded or if S3 env vars aren't set.
+ */
+export declare function preloadConfig(): Promise<void>;
+/**
+ * Load S3 config and inject all values into `process.env`.
+ *
+ * This enables the lazy-init handler pattern: the handler loads config into
+ * process.env BEFORE importing the backend module, so BB constructors can
+ * read their config via `process.env[key]` as before — no BB code changes needed.
+ *
+ * Only sets env vars that aren't already set (won't override explicit env vars).
+ */
+export declare function loadConfigToProcessEnv(): Promise<void>;
+/**
+ * Reset the config cache. **For testing only.**
+ */
+export declare function _resetConfigCache(): void;
+/**
+ * Override the S3 fetcher function. **For testing only.**
+ */
+export declare function _setS3Fetcher(fetcher: ((bucket: string, key: string) => Promise<string>) | null): void;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/common/config.ts"],"names":[],"mappings":"AA4FA;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM5D;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOjD;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAEnD;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAO5D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAIxC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAEtG"}

package/dist/common/config.js

@@ -0,0 +1,154 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Runtime config loader for Building Blocks.
+ *
+ * At deploy time, BB resource mappings (ARNs, URLs, paths) are stored in an
+ * S3 JSON file instead of Lambda environment variables (which have a 4KB limit).
+ * This module loads that config file once at cold start and caches it.
+ *
+ * Lookup order for each key:
+ * 1. `process.env[key]` — local dev where env vars are set directly
+ * 2. Cached S3 config — loaded once per cold start
+ *
+ * @module
+ */
+let configCache = null;
+let configLoadPromise = null;
+let s3FetcherOverride = null;
+async function defaultS3Fetcher(bucket, key) {
+    const { S3Client, GetObjectCommand } = await import('@aws-sdk/client-s3');
+    const client = new S3Client({
+        region: process.env.AWS_REGION,
+        requestHandler: { requestTimeout: 5000 },
+        maxAttempts: 3,
+    });
+    const response = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+    const body = await response.Body?.transformToString('utf-8');
+    if (!body)
+        throw new Error('Empty config file');
+    return body;
+}
+/**
+ * Load the config JSON from S3. Fetches once and caches forever (Lambda lifetime).
+ * Skips S3 entirely if BLOCKS_CONFIG_BUCKET/BLOCKS_CONFIG_KEY are not set (local dev).
+ * Throws if the env vars ARE set but the S3 fetch fails.
+ */
+async function loadConfigFromS3() {
+    if (configCache)
+        return configCache;
+    const bucket = process.env.BLOCKS_CONFIG_BUCKET;
+    const key = process.env.BLOCKS_CONFIG_KEY;
+    if (!bucket || !key) {
+        configCache = {};
+        return configCache;
+    }
+    const fetcher = s3FetcherOverride ?? defaultS3Fetcher;
+    try {
+        const body = await fetcher(bucket, key);
+        configCache = JSON.parse(body);
+    }
+    catch (error) {
+        const isNotFound = error?.name === 'NoSuchKey'
+            || error?.Code === 'NoSuchKey'
+            || error?.$metadata?.httpStatusCode === 404;
+        if (isNotFound) {
+            console.warn(`[Blocks] Config file not found in S3 (${bucket}/${key}), proceeding with empty config`);
+            configCache = {};
+            return configCache;
+        }
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new Error(`[Blocks] Failed to load config from S3 (${bucket}/${key}): ${msg}`);
+    }
+    if (typeof configCache !== 'object' || configCache === null || Array.isArray(configCache)) {
+        throw new Error('[Blocks] Config file must be a JSON object');
+    }
+    console.log(`[Blocks] Config loaded: ${Object.keys(configCache).length} keys`);
+    return configCache;
+}
+/**
+ * Ensure only one S3 fetch is in flight at a time.
+ * Multiple BB constructors calling getConfig() concurrently will share the same promise.
+ */
+function ensureConfigLoaded() {
+    if (configCache)
+        return Promise.resolve(configCache);
+    if (!configLoadPromise) {
+        configLoadPromise = loadConfigFromS3().finally(() => {
+            configLoadPromise = null;
+        });
+    }
+    return configLoadPromise;
+}
+/**
+ * Get a config value by key.
+ *
+ * Checks `process.env[key]` first (local dev where env vars are set directly).
+ * If not found, reads from the cached S3 config file.
+ *
+ * @param key - The config key (e.g., `BLOCKS_AUTH_COGNITO_MYAPP_AUTHC_USER_POOL_ID`)
+ * @returns The config value, or empty string if not found anywhere
+ */
+export async function getConfig(key) {
+    const envValue = process.env[key];
+    if (envValue !== undefined)
+        return envValue;
+    const config = await ensureConfigLoaded();
+    return config[key] ?? '';
+}
+/**
+ * Synchronous config access — returns the value if already cached, otherwise
+ * returns the process.env fallback. Use this only when you're certain the
+ * config has already been loaded (e.g., after an initial await getConfig() call).
+ *
+ * @param key - The config key
+ * @returns The config value, or empty string if not found
+ */
+export function getConfigSync(key) {
+    const envValue = process.env[key];
+    if (envValue !== undefined)
+        return envValue;
+    if (configCache)
+        return configCache[key] ?? '';
+    return '';
+}
+/**
+ * Preload the S3 config. Call this early in Lambda cold start to ensure
+ * the config is cached before any BB constructors need it.
+ *
+ * This is a no-op if the config is already loaded or if S3 env vars aren't set.
+ */
+export async function preloadConfig() {
+    await ensureConfigLoaded();
+}
+/**
+ * Load S3 config and inject all values into `process.env`.
+ *
+ * This enables the lazy-init handler pattern: the handler loads config into
+ * process.env BEFORE importing the backend module, so BB constructors can
+ * read their config via `process.env[key]` as before — no BB code changes needed.
+ *
+ * Only sets env vars that aren't already set (won't override explicit env vars).
+ */
+export async function loadConfigToProcessEnv() {
+    const config = await ensureConfigLoaded();
+    for (const [key, value] of Object.entries(config)) {
+        if (process.env[key] === undefined) {
+            process.env[key] = value;
+        }
+    }
+}
+/**
+ * Reset the config cache. **For testing only.**
+ */
+export function _resetConfigCache() {
+    configCache = null;
+    configLoadPromise = null;
+    s3FetcherOverride = null;
+}
+/**
+ * Override the S3 fetcher function. **For testing only.**
+ */
+export function _setS3Fetcher(fetcher) {
+    s3FetcherOverride = fetcher;
+}

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

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

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

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