@aws-blocks/core 0.1.0

package/dist/cors.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Parse a comma-separated CORS origin string into anchored RegExp patterns.
+ *
+ * Each entry is treated as a regex pattern:
+ * - If it starts with `^`, it's used as-is (already anchored).
+ * - Otherwise it's wrapped with `^...$` anchors.
+ * - If the resulting regex is invalid, the entry is escaped and matched literally.
+ *
+ * @param raw - Comma-separated CORS patterns (e.g. `"https://example\\.com,^https?://localhost(:\\d+)?$"`)
+ * @returns Array of anchored RegExp patterns
+ */
+export declare function parseCorsPatterns(raw: string): RegExp[];
+/**
+ * Get the lazily-computed CORS patterns from environment variables.
+ *
+ * Merges `CORS_ALLOWED_ORIGINS` and `CORS_HOSTING_ORIGINS` on first call,
+ * then caches the result. Returns `null` if no patterns are configured.
+ */
+export declare function getCorsPatterns(): RegExp[] | null;
+/**
+ * Check whether the given origin is allowed by the configured CORS patterns.
+ *
+ * @param origin - The `Origin` header value from the request
+ * @returns `true` if the origin matches at least one pattern, `false` otherwise
+ */
+export declare function isOriginAllowed(origin: string): boolean;
+/**
+ * Build a 403 Forbidden response for cross-origin requests from disallowed origins.
+ */
+export declare function corsRejection(): {
+    statusCode: number;
+    headers: Record<string, string>;
+    body: string;
+};
+/**
+ * Reset the lazy CORS pattern cache. **For testing only.**
+ */
+export declare function _resetCorsPatterns(): void;
+//# sourceMappingURL=cors.d.ts.map

package/dist/cors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../src/cors.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAYvD;AAcD;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,EAAE,GAAG,IAAI,CAcjD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAIvD;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAMrG;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/cors.js

@@ -0,0 +1,85 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Parse a comma-separated CORS origin string into anchored RegExp patterns.
+ *
+ * Each entry is treated as a regex pattern:
+ * - If it starts with `^`, it's used as-is (already anchored).
+ * - Otherwise it's wrapped with `^...$` anchors.
+ * - If the resulting regex is invalid, the entry is escaped and matched literally.
+ *
+ * @param raw - Comma-separated CORS patterns (e.g. `"https://example\\.com,^https?://localhost(:\\d+)?$"`)
+ * @returns Array of anchored RegExp patterns
+ */
+export function parseCorsPatterns(raw) {
+    return raw.split(',').map(p => p.trim()).filter(Boolean).map(pattern => {
+        try {
+            if (pattern.startsWith('^')) {
+                return new RegExp(pattern);
+            }
+            return new RegExp(`^${pattern}$`);
+        }
+        catch {
+            const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            return new RegExp(`^${escaped}$`);
+        }
+    });
+}
+/**
+ * Lazily-computed regex patterns for CORS origin validation.
+ *
+ * Computed on first access (not at module load) so that S3 config values
+ * injected by `loadConfigToProcessEnv()` are available. Combines:
+ * - `CORS_ALLOWED_ORIGINS` — set as Lambda env var by blocks-backend in sandbox mode
+ * - `CORS_HOSTING_ORIGINS` — set from S3 config by the Hosting construct (CloudFront domain)
+ *
+ * The sentinel value `undefined` means "not yet computed".
+ */
+let _corsPatterns;
+/**
+ * Get the lazily-computed CORS patterns from environment variables.
+ *
+ * Merges `CORS_ALLOWED_ORIGINS` and `CORS_HOSTING_ORIGINS` on first call,
+ * then caches the result. Returns `null` if no patterns are configured.
+ */
+export function getCorsPatterns() {
+    if (_corsPatterns !== undefined)
+        return _corsPatterns;
+    const envOrigins = process.env.CORS_ALLOWED_ORIGINS ?? '';
+    const hostingOrigins = process.env.CORS_HOSTING_ORIGINS ?? '';
+    const combined = [envOrigins, hostingOrigins].filter(Boolean).join(',');
+    if (!combined) {
+        _corsPatterns = null;
+        return null;
+    }
+    _corsPatterns = parseCorsPatterns(combined);
+    return _corsPatterns;
+}
+/**
+ * Check whether the given origin is allowed by the configured CORS patterns.
+ *
+ * @param origin - The `Origin` header value from the request
+ * @returns `true` if the origin matches at least one pattern, `false` otherwise
+ */
+export function isOriginAllowed(origin) {
+    const patterns = getCorsPatterns();
+    if (!origin || !patterns)
+        return false;
+    return patterns.some(re => re.test(origin));
+}
+/**
+ * Build a 403 Forbidden response for cross-origin requests from disallowed origins.
+ */
+export function corsRejection() {
+    return {
+        statusCode: 403,
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ error: 'Forbidden: cross-origin request rejected' }),
+    };
+}
+/**
+ * Reset the lazy CORS pattern cache. **For testing only.**
+ */
+export function _resetCorsPatterns() {
+    _corsPatterns = undefined;
+}

package/dist/cors.test.d.ts

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

package/dist/cors.test.d.ts.map

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

package/dist/cors.test.js

@@ -0,0 +1,241 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert';
+import { parseCorsPatterns, _resetCorsPatterns } from './cors.js';
+import { createLambdaHandler } from './lambda-handler.js';
+import { clearRouteRegistry } from './raw-route.js';
+// ── parseCorsPatterns unit tests ────────────────────────────────────────────
+describe('parseCorsPatterns', () => {
+    it('returns anchored patterns from plain strings', () => {
+        const patterns = parseCorsPatterns('https://example\\.com');
+        assert.strictEqual(patterns.length, 1);
+        assert.ok(patterns[0].test('https://example.com'));
+        assert.ok(!patterns[0].test('https://example.com.evil.org'));
+    });
+    it('handles already-anchored patterns (starting with ^)', () => {
+        const patterns = parseCorsPatterns('^https?://(localhost|127\\.0\\.0\\.1)(:\\d+)?$');
+        assert.strictEqual(patterns.length, 1);
+        assert.ok(patterns[0].test('http://localhost:3000'));
+        assert.ok(patterns[0].test('https://127.0.0.1:8080'));
+        assert.ok(!patterns[0].test('https://evil.com'));
+    });
+    it('handles multiple comma-separated patterns', () => {
+        const patterns = parseCorsPatterns('https://a\\.com,https://b\\.com');
+        assert.strictEqual(patterns.length, 2);
+        assert.ok(patterns[0].test('https://a.com'));
+        assert.ok(patterns[1].test('https://b.com'));
+    });
+    it('trims whitespace from patterns', () => {
+        const patterns = parseCorsPatterns(' https://a\\.com , https://b\\.com ');
+        assert.strictEqual(patterns.length, 2);
+        assert.ok(patterns[0].test('https://a.com'));
+        assert.ok(patterns[1].test('https://b.com'));
+    });
+    it('skips empty entries', () => {
+        const patterns = parseCorsPatterns('https://a\\.com,,,,https://b\\.com');
+        assert.strictEqual(patterns.length, 2);
+    });
+    it('handles invalid regex by escaping and matching literally', () => {
+        const patterns = parseCorsPatterns('https://[invalid');
+        assert.strictEqual(patterns.length, 1);
+        assert.ok(patterns[0].test('https://[invalid'));
+        assert.ok(!patterns[0].test('https://valid'));
+    });
+    it('wildcard .* allows all origins', () => {
+        const patterns = parseCorsPatterns('.*');
+        assert.strictEqual(patterns.length, 1);
+        assert.ok(patterns[0].test('https://anything.example.org'));
+        assert.ok(patterns[0].test('http://localhost:9999'));
+    });
+});
+// ── isOriginAllowed + getCorsPatterns integration via handler ────────────────
+// These tests exercise the full CORS flow through createLambdaHandler to
+// verify origin validation, header injection, and rejection work end-to-end.
+describe('createLambdaHandler — CORS origin validation', () => {
+    beforeEach(() => {
+        process.env.CORS_ALLOWED_ORIGINS = [
+            'https://myapp\\.com',
+            '^https?://(localhost|127\\.0\\.0\\.1)(:\\d+)?$',
+        ].join(',');
+        delete process.env.CORS_HOSTING_ORIGINS;
+        _resetCorsPatterns();
+        clearRouteRegistry();
+    });
+    function makeEvent(overrides = {}) {
+        return {
+            httpMethod: 'POST',
+            path: '/aws-blocks/api',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ jsonrpc: '2.0', method: 'api.echo', params: ['hello'], id: 1 }),
+            isBase64Encoded: false,
+            ...overrides,
+        };
+    }
+    async function invoke(backend, event) {
+        const handler = createLambdaHandler(async () => backend);
+        return handler(event);
+    }
+    const echoBackend = {
+        api: (_ctx) => ({
+            async echo(msg) { return { msg }; },
+        }),
+    };
+    it('allows an origin that matches an exact pattern', async () => {
+        const result = await invoke(echoBackend, makeEvent({
+            headers: { 'Content-Type': 'application/json', origin: 'https://myapp.com' },
+        }));
+        assert.strictEqual(result.statusCode, 200);
+        assert.strictEqual(result.headers['access-control-allow-origin'], 'https://myapp.com');
+        assert.strictEqual(result.headers['access-control-allow-credentials'], 'true');
+    });
+    it('allows an origin that matches a regex pattern', async () => {
+        const result = await invoke(echoBackend, makeEvent({
+            headers: { 'Content-Type': 'application/json', origin: 'http://localhost:5173' },
+        }));
+        assert.strictEqual(result.statusCode, 200);
+        assert.strictEqual(result.headers['access-control-allow-origin'], 'http://localhost:5173');
+    });
+    it('rejects an origin that does not match any pattern with 403', async () => {
+        const result = await invoke(echoBackend, makeEvent({
+            headers: { 'Content-Type': 'application/json', origin: 'https://evil.com' },
+        }));
+        assert.strictEqual(result.statusCode, 403);
+        const body = JSON.parse(result.body);
+        assert.strictEqual(body.error, 'Forbidden: cross-origin request rejected');
+    });
+    it('passes through when no origin header is present (same-origin / server-side)', async () => {
+        const result = await invoke(echoBackend, makeEvent({
+            headers: { 'Content-Type': 'application/json' },
+        }));
+        assert.strictEqual(result.statusCode, 200);
+        assert.strictEqual(result.headers['access-control-allow-origin'], undefined);
+    });
+    it('anchored pattern prevents partial-match bypass', async () => {
+        const result = await invoke(echoBackend, makeEvent({
+            headers: { 'Content-Type': 'application/json', origin: 'https://myapp.com.evil.org' },
+        }));
+        assert.strictEqual(result.statusCode, 403);
+    });
+    it('sets ACAO and credentials headers on allowed origin', async () => {
+        const result = await invoke(echoBackend, makeEvent({
+            headers: { 'Content-Type': 'application/json', origin: 'https://myapp.com' },
+        }));
+        assert.strictEqual(result.statusCode, 200);
+        assert.strictEqual(result.headers['access-control-allow-origin'], 'https://myapp.com');
+        assert.strictEqual(result.headers['access-control-allow-credentials'], 'true');
+    });
+    it('OPTIONS preflight with allowed origin returns 200 with CORS headers', async () => {
+        const result = await invoke(echoBackend, makeEvent({
+            httpMethod: 'OPTIONS',
+            path: '/aws-blocks/api',
+            headers: { origin: 'http://localhost:3000' },
+            body: null,
+        }));
+        assert.strictEqual(result.statusCode, 200);
+        assert.strictEqual(result.headers['Access-Control-Allow-Origin'], 'http://localhost:3000');
+        assert.strictEqual(result.headers['Access-Control-Allow-Credentials'], 'true');
+        assert.ok(result.headers['Access-Control-Allow-Methods']);
+        assert.ok(result.headers['Access-Control-Allow-Headers']);
+        assert.strictEqual(result.headers['Access-Control-Max-Age'], '86400');
+    });
+    it('OPTIONS preflight with rejected origin returns 403', async () => {
+        const result = await invoke(echoBackend, makeEvent({
+            httpMethod: 'OPTIONS',
+            path: '/aws-blocks/api',
+            headers: { origin: 'https://evil.com' },
+            body: null,
+        }));
+        assert.strictEqual(result.statusCode, 403);
+    });
+});
+// ── CORS wildcard pattern ───────────────────────────────────────────────────
+describe('createLambdaHandler — CORS wildcard pattern (.*)', () => {
+    beforeEach(() => {
+        process.env.CORS_ALLOWED_ORIGINS = '.*';
+        delete process.env.CORS_HOSTING_ORIGINS;
+        _resetCorsPatterns();
+        clearRouteRegistry();
+    });
+    function makeEvent(overrides = {}) {
+        return {
+            httpMethod: 'POST',
+            path: '/aws-blocks/api',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ jsonrpc: '2.0', method: 'api.echo', params: ['hello'], id: 1 }),
+            isBase64Encoded: false,
+            ...overrides,
+        };
+    }
+    async function invoke(backend, event) {
+        const handler = createLambdaHandler(async () => backend);
+        return handler(event);
+    }
+    const echoBackend = {
+        api: (_ctx) => ({
+            async echo(msg) { return { msg }; },
+        }),
+    };
+    it('allows any origin when pattern is .* (catch-all)', async () => {
+        const result = await invoke(echoBackend, makeEvent({
+            headers: { 'Content-Type': 'application/json', origin: 'https://anything.example.org' },
+        }));
+        assert.strictEqual(result.statusCode, 200);
+        assert.strictEqual(result.headers['access-control-allow-origin'], 'https://anything.example.org');
+    });
+});
+// ── CORS hosting origin merge ───────────────────────────────────────────────
+describe('createLambdaHandler — CORS hosting origin merge', () => {
+    beforeEach(() => {
+        process.env.CORS_ALLOWED_ORIGINS = '^https?://(localhost|127\\.0\\.0\\.1)(:\\d+)?$';
+        process.env.CORS_HOSTING_ORIGINS = 'https://d111111abcdef8\\.cloudfront\\.net';
+        _resetCorsPatterns();
+        clearRouteRegistry();
+    });
+    function makeEvent(overrides = {}) {
+        return {
+            httpMethod: 'POST',
+            path: '/aws-blocks/api',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ jsonrpc: '2.0', method: 'api.echo', params: ['hello'], id: 1 }),
+            isBase64Encoded: false,
+            ...overrides,
+        };
+    }
+    async function invoke(backend, event) {
+        const handler = createLambdaHandler(async () => backend);
+        return handler(event);
+    }
+    const echoBackend = {
+        api: (_ctx) => ({
+            async echo(msg) { return { msg }; },
+        }),
+    };
+    it('allows localhost origin from CORS_ALLOWED_ORIGINS env var', async () => {
+        const result = await invoke(echoBackend, makeEvent({
+            headers: { 'Content-Type': 'application/json', origin: 'http://localhost:5173' },
+        }));
+        assert.strictEqual(result.statusCode, 200);
+        assert.strictEqual(result.headers['access-control-allow-origin'], 'http://localhost:5173');
+    });
+    it('allows CloudFront origin from CORS_HOSTING_ORIGINS (S3 config)', async () => {
+        const result = await invoke(echoBackend, makeEvent({
+            headers: { 'Content-Type': 'application/json', origin: 'https://d111111abcdef8.cloudfront.net' },
+        }));
+        assert.strictEqual(result.statusCode, 200);
+        assert.strictEqual(result.headers['access-control-allow-origin'], 'https://d111111abcdef8.cloudfront.net');
+    });
+    it('rejects origins not matching either source', async () => {
+        const result = await invoke(echoBackend, makeEvent({
+            headers: { 'Content-Type': 'application/json', origin: 'https://evil.com' },
+        }));
+        assert.strictEqual(result.statusCode, 403);
+    });
+    it('allows 127.0.0.1 from the combined patterns', async () => {
+        const result = await invoke(echoBackend, makeEvent({
+            headers: { 'Content-Type': 'application/json', origin: 'http://127.0.0.1:8080' },
+        }));
+        assert.strictEqual(result.statusCode, 200);
+        assert.strictEqual(result.headers['access-control-allow-origin'], 'http://127.0.0.1:8080');
+    });
+});

package/dist/db-naming.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Single source of truth for the SSM parameter name that stores an external
+ * database connection string, and for the project ref derived from a Postgres
+ * connection string.
+ *
+ * Both the deploy-time provisioner (`ensure-secrets`) and the `db pull`
+ * generated code derive this name from the stage alone. Keep this the only
+ * place the name is constructed.
+ */
+/**
+ * Extract a stable identifier from a Postgres connection string.
+ *
+ * Maps the Supabase pooler form (`postgres.{ref}@`) and the direct form
+ * (`db.{ref}.supabase.co`) to the same `{ref}`, so a project's connection string
+ * yields one identifier regardless of which form the customer pastes. Falls back
+ * to a sanitized hostname for non-Supabase hosts.
+ */
+export declare function extractDbRef(connectionString: string): string;
+/** SSM parameter name storing the connection string for a given stage. */
+export declare function dbConnectionParameterName(stage: string): string;
+//# sourceMappingURL=db-naming.d.ts.map

package/dist/db-naming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-naming.d.ts","sourceRoot":"","sources":["../src/db-naming.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAc7D;AAED,0EAA0E;AAC1E,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/D"}

package/dist/db-naming.js

@@ -0,0 +1,38 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Single source of truth for the SSM parameter name that stores an external
+ * database connection string, and for the project ref derived from a Postgres
+ * connection string.
+ *
+ * Both the deploy-time provisioner (`ensure-secrets`) and the `db pull`
+ * generated code derive this name from the stage alone. Keep this the only
+ * place the name is constructed.
+ */
+/**
+ * Extract a stable identifier from a Postgres connection string.
+ *
+ * Maps the Supabase pooler form (`postgres.{ref}@`) and the direct form
+ * (`db.{ref}.supabase.co`) to the same `{ref}`, so a project's connection string
+ * yields one identifier regardless of which form the customer pastes. Falls back
+ * to a sanitized hostname for non-Supabase hosts.
+ */
+export function extractDbRef(connectionString) {
+    // Supabase pooler: postgres.{ref}:pass@... or postgres.{ref}@...
+    const pooler = connectionString.match(/postgres\.([a-z0-9]+)[:@]/i);
+    if (pooler)
+        return pooler[1];
+    // Supabase direct: @db.{ref}.supabase.co
+    const direct = connectionString.match(/@db\.([a-z0-9]+)\.supabase\.co/i);
+    if (direct)
+        return direct[1];
+    // Generic host fallback
+    const host = connectionString.match(/@([^:/?]+)/);
+    if (host)
+        return host[1].replace(/\./g, '-');
+    throw new Error('Cannot extract database identifier from connection string.');
+}
+/** SSM parameter name storing the connection string for a given stage. */
+export function dbConnectionParameterName(stage) {
+    return `/blocks/${stage}/db-connection-string`;
+}

package/dist/db-naming.test.d.ts

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

package/dist/db-naming.test.d.ts.map

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

package/dist/db-naming.test.js

@@ -0,0 +1,29 @@
+// 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 { extractDbRef, dbConnectionParameterName } from './db-naming.js';
+describe('extractDbRef', () => {
+    test('pooler form (postgres.{ref}@) yields ref', () => {
+        assert.strictEqual(extractDbRef('postgresql://postgres.abcdef:pw@aws-0-us-east-1.pooler.supabase.com:6543/postgres'), 'abcdef');
+    });
+    test('direct form (db.{ref}.supabase.co) yields the same ref', () => {
+        assert.strictEqual(extractDbRef('postgresql://postgres:pw@db.abcdef.supabase.co:5432/postgres'), 'abcdef');
+    });
+    test('pooler and direct forms of one project agree', () => {
+        const pooler = extractDbRef('postgresql://postgres.proj123:pw@aws-0-eu-west-2.pooler.supabase.com:5432/postgres');
+        const direct = extractDbRef('postgresql://postgres:pw@db.proj123.supabase.co:5432/postgres');
+        assert.strictEqual(pooler, direct);
+    });
+    test('non-Supabase host falls back to sanitized hostname', () => {
+        assert.strictEqual(extractDbRef('postgresql://user:pw@my.db.example.com:5432/app'), 'my-db-example-com');
+    });
+    test('throws when no host is present', () => {
+        assert.throws(() => extractDbRef('not-a-connection-string'));
+    });
+});
+describe('dbConnectionParameterName', () => {
+    test('composes the stage into the SSM name', () => {
+        assert.strictEqual(dbConnectionParameterName('production'), '/blocks/production/db-connection-string');
+    });
+});

package/dist/errors.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Error subclass for errors that cross the wire between server and client.
+ *
+ * Carries a `status` (HTTP status code) and sets `name` to the BB-level
+ * error name (e.g., `'ConditionalCheckFailedException'`). Both are
+ * serialized to the client. `cause` stays server-side.
+ *
+ * @example
+ * ```typescript
+ * // Backend: catch a BB error and re-throw with status
+ * try {
+ *   await store.put(key, value, { ifNotExists: true });
+ * } catch (e: unknown) {
+ *   if (isBlocksError(e, KVStoreErrors.ConditionalCheckFailed)) {
+ *     throw new ApiError('Username already taken', 409, { name: e.name, cause: e });
+ *   }
+ *   throw e;
+ * }
+ *
+ * // Frontend: same isBlocksError works
+ * try {
+ *   await api.createUser('alice', 'pass');
+ * } catch (e: unknown) {
+ *   if (isBlocksError(e, KVStoreErrors.ConditionalCheckFailed)) {
+ *     showMessage('Username already taken');
+ *   }
+ * }
+ * ```
+ */
+export declare class ApiError extends Error {
+    /** HTTP status code. */
+    readonly status: number;
+    /**
+     * Whether the caller can retry the same action without restarting the
+     * broader flow. Semantically meaningful for multi-step state machines
+     * like auth challenges: the same session token / envelope can be reused
+     * with a corrected input (wrong MFA code, wrong password on re-prompt)
+     * when `retriable === true`; non-retriable errors (expired session,
+     * tampered envelope, too-many-attempts lockouts) require restarting the
+     * flow. Defaults to `false` when unspecified.
+     */
+    readonly retriable: boolean;
+    constructor(message: string, status: number, options?: {
+        name?: string;
+        cause?: unknown;
+        retriable?: boolean;
+    });
+}
+/**
+ * Type guard for narrowing `unknown` catch variables against BB error constants.
+ *
+ * Checks `error.name` — works identically on both server and client because
+ * `ApiError` reconstructed from the wire preserves the error name.
+ *
+ * @example
+ * ```typescript
+ * catch (e: unknown) {
+ *   if (isBlocksError(e, KVStoreErrors.ConditionalCheckFailed)) {
+ *     // e is narrowed to Error & { name: 'ConditionalCheckFailedException' }
+ *   }
+ * }
+ * ```
+ */
+export declare function isBlocksError<N extends string>(e: unknown, name: N): e is Error & {
+    name: N;
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAClC,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE;CAM9G;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,GAAG;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CAE7F"}

package/dist/errors.js

@@ -0,0 +1,69 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Error subclass for errors that cross the wire between server and client.
+ *
+ * Carries a `status` (HTTP status code) and sets `name` to the BB-level
+ * error name (e.g., `'ConditionalCheckFailedException'`). Both are
+ * serialized to the client. `cause` stays server-side.
+ *
+ * @example
+ * ```typescript
+ * // Backend: catch a BB error and re-throw with status
+ * try {
+ *   await store.put(key, value, { ifNotExists: true });
+ * } catch (e: unknown) {
+ *   if (isBlocksError(e, KVStoreErrors.ConditionalCheckFailed)) {
+ *     throw new ApiError('Username already taken', 409, { name: e.name, cause: e });
+ *   }
+ *   throw e;
+ * }
+ *
+ * // Frontend: same isBlocksError works
+ * try {
+ *   await api.createUser('alice', 'pass');
+ * } catch (e: unknown) {
+ *   if (isBlocksError(e, KVStoreErrors.ConditionalCheckFailed)) {
+ *     showMessage('Username already taken');
+ *   }
+ * }
+ * ```
+ */
+export class ApiError extends Error {
+    /** HTTP status code. */
+    status;
+    /**
+     * Whether the caller can retry the same action without restarting the
+     * broader flow. Semantically meaningful for multi-step state machines
+     * like auth challenges: the same session token / envelope can be reused
+     * with a corrected input (wrong MFA code, wrong password on re-prompt)
+     * when `retriable === true`; non-retriable errors (expired session,
+     * tampered envelope, too-many-attempts lockouts) require restarting the
+     * flow. Defaults to `false` when unspecified.
+     */
+    retriable;
+    constructor(message, status, options) {
+        super(message, options?.cause ? { cause: options.cause } : undefined);
+        this.name = options?.name ?? 'ApiError';
+        this.status = status;
+        this.retriable = options?.retriable ?? false;
+    }
+}
+/**
+ * Type guard for narrowing `unknown` catch variables against BB error constants.
+ *
+ * Checks `error.name` — works identically on both server and client because
+ * `ApiError` reconstructed from the wire preserves the error name.
+ *
+ * @example
+ * ```typescript
+ * catch (e: unknown) {
+ *   if (isBlocksError(e, KVStoreErrors.ConditionalCheckFailed)) {
+ *     // e is narrowed to Error & { name: 'ConditionalCheckFailedException' }
+ *   }
+ * }
+ * ```
+ */
+export function isBlocksError(e, name) {
+    return e instanceof Error && e.name === name;
+}