@aws-blocks/core 0.1.0

package/dist/scripts/telemetry.test.js

@@ -0,0 +1,203 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync, readFileSync, rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLI_SCRIPT = join(__dirname, 'telemetry-cli.js');
+/** Env overrides that clear CI detection so tests see "default enabled" state. */
+const NO_CI_ENV = {
+    CI: '',
+    CONTINUOUS_INTEGRATION: '',
+    BUILD_NUMBER: '',
+    CODEBUILD_BUILD_ID: '',
+    GITHUB_ACTIONS: '',
+    GITLAB_CI: '',
+    CIRCLECI: '',
+    JENKINS_URL: '',
+    TF_BUILD: '',
+    BITBUCKET_BUILD_NUMBER: '',
+    BUILDKITE: '',
+    AWS_BLOCKS_DISABLE_TELEMETRY: '',
+};
+function createTmpDir() {
+    const dir = join(tmpdir(), `blocks-telemetry-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+function runCli(args, options) {
+    const result = spawnSync('node', [CLI_SCRIPT, ...args], {
+        cwd: options?.cwd ?? process.cwd(),
+        encoding: 'utf-8',
+        env: { ...process.env, ...options?.env },
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return {
+        stdout: result.stdout || '',
+        stderr: result.stderr || '',
+        exitCode: result.status ?? 1,
+    };
+}
+describe('telemetry CLI', () => {
+    let tmpHome;
+    let tmpProject;
+    beforeEach(() => {
+        tmpHome = createTmpDir();
+        tmpProject = createTmpDir();
+    });
+    afterEach(() => {
+        rmSync(tmpHome, { recursive: true, force: true });
+        rmSync(tmpProject, { recursive: true, force: true });
+    });
+    describe('help', () => {
+        it('--help shows usage', () => {
+            const result = runCli(['--help'], { cwd: tmpProject, env: { HOME: tmpHome } });
+            assert.strictEqual(result.exitCode, 0);
+            assert.ok(result.stdout.includes('--enable'));
+            assert.ok(result.stdout.includes('--disable'));
+            assert.ok(result.stdout.includes('--global'));
+        });
+        it('-h shows usage', () => {
+            const result = runCli(['-h'], { cwd: tmpProject, env: { HOME: tmpHome } });
+            assert.strictEqual(result.exitCode, 0);
+            assert.ok(result.stdout.includes('--enable'));
+        });
+    });
+    describe('bare command (shows help)', () => {
+        it('shows usage when invoked with no arguments', () => {
+            const result = runCli([], { cwd: tmpProject, env: { HOME: tmpHome, ...NO_CI_ENV } });
+            assert.strictEqual(result.exitCode, 0);
+            assert.ok(result.stdout.includes('Usage:'));
+            assert.ok(result.stdout.includes('--enable'));
+            assert.ok(result.stdout.includes('--disable'));
+            assert.ok(result.stdout.includes('--status'));
+        });
+    });
+    describe('--enable (project-level default)', () => {
+        it('creates .blocks/config.json with telemetry.enabled=true', () => {
+            const result = runCli(['--enable'], { cwd: tmpProject, env: { HOME: tmpHome } });
+            assert.strictEqual(result.exitCode, 0);
+            assert.ok(result.stdout.includes('enabled for this project'));
+            const configPath = join(tmpProject, '.blocks', 'config.json');
+            assert.ok(existsSync(configPath));
+            const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+            assert.strictEqual(config.telemetry.enabled, true);
+        });
+    });
+    describe('--disable (project-level default)', () => {
+        it('creates .blocks/config.json with telemetry.enabled=false', () => {
+            const result = runCli(['--disable'], { cwd: tmpProject, env: { HOME: tmpHome } });
+            assert.strictEqual(result.exitCode, 0);
+            assert.ok(result.stdout.includes('disabled for this project'));
+            const configPath = join(tmpProject, '.blocks', 'config.json');
+            assert.ok(existsSync(configPath));
+            const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+            assert.strictEqual(config.telemetry.enabled, false);
+        });
+    });
+    describe('--enable --global', () => {
+        it('creates ~/.blocks/config.json with telemetry.enabled=true', () => {
+            const result = runCli(['--enable', '--global'], { cwd: tmpProject, env: { HOME: tmpHome } });
+            assert.strictEqual(result.exitCode, 0);
+            assert.ok(result.stdout.includes('enabled globally'));
+            const configPath = join(tmpHome, '.blocks', 'config.json');
+            assert.ok(existsSync(configPath));
+            const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+            assert.strictEqual(config.telemetry.enabled, true);
+        });
+        it('preserves existing keys in global config', () => {
+            const configDir = join(tmpHome, '.blocks');
+            mkdirSync(configDir, { recursive: true });
+            writeFileSync(join(configDir, 'config.json'), JSON.stringify({ telemetry: { projectId: 'xyz' }, someKey: 'value' }, null, 2));
+            const result = runCli(['--enable', '--global'], { cwd: tmpProject, env: { HOME: tmpHome } });
+            assert.strictEqual(result.exitCode, 0);
+            const config = JSON.parse(readFileSync(join(configDir, 'config.json'), 'utf-8'));
+            assert.strictEqual(config.telemetry.enabled, true);
+            assert.strictEqual(config.telemetry.projectId, 'xyz');
+            assert.strictEqual(config.someKey, 'value');
+        });
+    });
+    describe('--disable --global', () => {
+        it('creates ~/.blocks/config.json with telemetry.enabled=false', () => {
+            const result = runCli(['--disable', '--global'], { cwd: tmpProject, env: { HOME: tmpHome } });
+            assert.strictEqual(result.exitCode, 0);
+            assert.ok(result.stdout.includes('disabled globally'));
+            const configPath = join(tmpHome, '.blocks', 'config.json');
+            assert.ok(existsSync(configPath));
+            const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+            assert.strictEqual(config.telemetry.enabled, false);
+        });
+    });
+    describe('--status (shows status)', () => {
+        it('shows enabled by default when no config exists', () => {
+            const result = runCli(['--status'], { cwd: tmpProject, env: { HOME: tmpHome, ...NO_CI_ENV } });
+            assert.strictEqual(result.exitCode, 0);
+            assert.ok(result.stdout.includes('Telemetry:'));
+            assert.ok(result.stdout.includes('Enabled'));
+        });
+        it('shows disabled when global config disables telemetry', () => {
+            const configDir = join(tmpHome, '.blocks');
+            mkdirSync(configDir, { recursive: true });
+            writeFileSync(join(configDir, 'config.json'), JSON.stringify({ telemetry: { enabled: false } }));
+            const result = runCli(['--status'], { cwd: tmpProject, env: { HOME: tmpHome, ...NO_CI_ENV } });
+            assert.strictEqual(result.exitCode, 0);
+            assert.ok(result.stdout.includes('Disabled'));
+            assert.ok(result.stdout.includes('Global config'));
+        });
+        it('shows disabled when env var is set to 1', () => {
+            const result = runCli(['--status'], { cwd: tmpProject, env: { HOME: tmpHome, ...NO_CI_ENV, AWS_BLOCKS_DISABLE_TELEMETRY: '1' } });
+            assert.strictEqual(result.exitCode, 0);
+            assert.ok(result.stdout.includes('Disabled'));
+            assert.ok(result.stdout.includes('AWS_BLOCKS_DISABLE_TELEMETRY'));
+        });
+        it('any disable wins — project disabled even if global enabled', () => {
+            const globalConfigDir = join(tmpHome, '.blocks');
+            mkdirSync(globalConfigDir, { recursive: true });
+            writeFileSync(join(globalConfigDir, 'config.json'), JSON.stringify({ telemetry: { enabled: true } }));
+            const projectConfigDir = join(tmpProject, '.blocks');
+            mkdirSync(projectConfigDir, { recursive: true });
+            writeFileSync(join(projectConfigDir, 'config.json'), JSON.stringify({ telemetry: { enabled: false } }));
+            const result = runCli(['--status'], { cwd: tmpProject, env: { HOME: tmpHome, ...NO_CI_ENV } });
+            assert.strictEqual(result.exitCode, 0);
+            assert.ok(result.stdout.includes('Disabled'));
+        });
+        it('any disable wins — global disabled even if project enabled', () => {
+            const globalConfigDir = join(tmpHome, '.blocks');
+            mkdirSync(globalConfigDir, { recursive: true });
+            writeFileSync(join(globalConfigDir, 'config.json'), JSON.stringify({ telemetry: { enabled: false } }));
+            const projectConfigDir = join(tmpProject, '.blocks');
+            mkdirSync(projectConfigDir, { recursive: true });
+            writeFileSync(join(projectConfigDir, 'config.json'), JSON.stringify({ telemetry: { enabled: true } }));
+            const result = runCli(['--status'], { cwd: tmpProject, env: { HOME: tmpHome, ...NO_CI_ENV } });
+            assert.strictEqual(result.exitCode, 0);
+            assert.ok(result.stdout.includes('Disabled'));
+        });
+    });
+    describe('error handling', () => {
+        it('--enable and --disable together exits with error', () => {
+            const result = runCli(['--enable', '--disable'], { cwd: tmpProject, env: { HOME: tmpHome } });
+            assert.notStrictEqual(result.exitCode, 0);
+            assert.ok(result.stderr.includes('mutually exclusive'));
+        });
+    });
+    describe('unknown flags', () => {
+        it('warns about unrecognized flags but still exits 0', () => {
+            const result = runCli(['--statu'], { cwd: tmpProject, env: { HOME: tmpHome, ...NO_CI_ENV } });
+            assert.strictEqual(result.exitCode, 0);
+            assert.ok(result.stderr.includes('Unknown option') || result.stdout.includes('Unknown option'));
+            assert.ok(result.stderr.includes('--statu') || result.stdout.includes('--statu'));
+        });
+        it('recognized action still runs when unknown flags are present', () => {
+            const result = runCli(['--enable', '--typo'], { cwd: tmpProject, env: { HOME: tmpHome, ...NO_CI_ENV } });
+            assert.strictEqual(result.exitCode, 0);
+            assert.ok(result.stderr.includes('Unknown option') || result.stdout.includes('Unknown option'));
+            assert.ok(result.stderr.includes('--typo') || result.stdout.includes('--typo'));
+            assert.ok(result.stdout.includes('enabled for this project'));
+        });
+    });
+});

package/dist/scripts/validate-spec.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Validate a generated OpenRPC document for structural conformance.
+ *
+ * Checks:
+ * - Required top-level fields (openrpc, info, methods)
+ * - OpenRPC version format
+ * - Method structure (name, params, result)
+ * - Param structure (name, required, schema)
+ * - Result structure (name, schema)
+ * - All $ref pointers resolve to entries in components.schemas
+ * - No `nullable` field (should use oneOf with null instead)
+ * - Method names are namespace-qualified (contain a dot)
+ * - Result names are descriptive (not just "result")
+ *
+ * Returns an array of error messages. Empty array = valid.
+ */
+export interface SpecValidationError {
+    path: string;
+    message: string;
+}
+export declare function validateSpec(doc: any): SpecValidationError[];
+//# sourceMappingURL=validate-spec.d.ts.map

package/dist/scripts/validate-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-spec.d.ts","sourceRoot":"","sources":["../../src/scripts/validate-spec.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,mBAAmB,EAAE,CA4J5D"}

package/dist/scripts/validate-spec.js

@@ -0,0 +1,159 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+export function validateSpec(doc) {
+    const errors = [];
+    // Top-level required fields
+    if (!doc || typeof doc !== 'object') {
+        return [{ path: '', message: 'Document must be an object' }];
+    }
+    if (typeof doc.openrpc !== 'string') {
+        errors.push({ path: 'openrpc', message: 'Missing or invalid "openrpc" version string' });
+    }
+    else if (!/^\d+\.\d+\.\d+$/.test(doc.openrpc)) {
+        errors.push({ path: 'openrpc', message: `Invalid version format: "${doc.openrpc}"` });
+    }
+    if (!doc.info || typeof doc.info !== 'object') {
+        errors.push({ path: 'info', message: 'Missing "info" object' });
+    }
+    else {
+        if (typeof doc.info.title !== 'string') {
+            errors.push({ path: 'info.title', message: 'Missing "info.title" string' });
+        }
+        if (typeof doc.info.version !== 'string') {
+            errors.push({ path: 'info.version', message: 'Missing "info.version" string' });
+        }
+    }
+    if (!Array.isArray(doc.methods)) {
+        errors.push({ path: 'methods', message: 'Missing "methods" array' });
+        return errors;
+    }
+    // Collect known schema names for $ref resolution
+    const knownSchemas = new Set(Object.keys(doc.components?.schemas || {}));
+    // Scan entire document for $ref pointers and nullable fields
+    const docStr = JSON.stringify(doc);
+    if (docStr.includes('"nullable"')) {
+        errors.push({
+            path: '',
+            message: 'Document contains "nullable" field — use oneOf with { type: "null" } instead',
+        });
+    }
+    // Validate each method
+    for (let i = 0; i < doc.methods.length; i++) {
+        const method = doc.methods[i];
+        const mp = `methods[${i}]`;
+        if (typeof method.name !== 'string') {
+            errors.push({ path: `${mp}.name`, message: 'Missing method name' });
+            continue;
+        }
+        const mpath = `methods["${method.name}"]`;
+        // Namespace-qualified check
+        if (!method.name.includes('.')) {
+            errors.push({ path: `${mpath}.name`, message: `Method name "${method.name}" is not namespace-qualified (expected "namespace.method")` });
+        }
+        // Params
+        if (!Array.isArray(method.params)) {
+            errors.push({ path: `${mpath}.params`, message: 'Missing "params" array' });
+        }
+        else {
+            for (let j = 0; j < method.params.length; j++) {
+                const param = method.params[j];
+                const pp = `${mpath}.params[${j}]`;
+                if (typeof param.name !== 'string') {
+                    errors.push({ path: pp, message: 'Missing param name' });
+                }
+                if (typeof param.required !== 'boolean') {
+                    errors.push({ path: `${pp}.required`, message: 'Missing or non-boolean "required"' });
+                }
+                if (!param.schema || typeof param.schema !== 'object') {
+                    errors.push({ path: `${pp}.schema`, message: 'Missing param schema' });
+                }
+                // Check $ref resolution
+                if (param.schema?.$ref) {
+                    validateRef(param.schema.$ref, `${pp}.schema.$ref`, knownSchemas, errors);
+                }
+            }
+        }
+        // Result
+        if (!method.result || typeof method.result !== 'object') {
+            errors.push({ path: `${mpath}.result`, message: 'Missing "result" object' });
+        }
+        else {
+            if (typeof method.result.name !== 'string') {
+                errors.push({ path: `${mpath}.result.name`, message: 'Missing result name' });
+            }
+            else if (method.result.name === 'result') {
+                errors.push({ path: `${mpath}.result.name`, message: 'Result name should be descriptive, not "result"' });
+            }
+            if (!method.result.schema || typeof method.result.schema !== 'object') {
+                errors.push({ path: `${mpath}.result.schema`, message: 'Missing result schema' });
+            }
+            // Check $ref resolution
+            if (method.result.schema?.$ref) {
+                validateRef(method.result.schema.$ref, `${mpath}.result.schema.$ref`, knownSchemas, errors);
+            }
+            // Check oneOf members for $refs
+            if (Array.isArray(method.result.schema?.oneOf)) {
+                for (let k = 0; k < method.result.schema.oneOf.length; k++) {
+                    const member = method.result.schema.oneOf[k];
+                    if (member.$ref) {
+                        validateRef(member.$ref, `${mpath}.result.schema.oneOf[${k}].$ref`, knownSchemas, errors);
+                    }
+                }
+            }
+            // Validate x-blocks-transferable extension field
+            if ('x-blocks-transferable' in (method.result.schema ?? {})) {
+                const blocksTag = method.result.schema['x-blocks-transferable'];
+                if (typeof blocksTag !== 'string' || blocksTag.length === 0) {
+                    errors.push({
+                        path: `${mpath}.result.schema.x-blocks-transferable`,
+                        message: 'x-blocks-transferable must be a non-empty string',
+                    });
+                }
+            }
+            // Validate x-blocks-type-args extension field
+            if ('x-blocks-type-args' in (method.result.schema ?? {})) {
+                const typeArgs = method.result.schema['x-blocks-type-args'];
+                if (!Array.isArray(typeArgs)) {
+                    errors.push({
+                        path: `${mpath}.result.schema.x-blocks-type-args`,
+                        message: 'x-blocks-type-args must be an array of JSON Schema objects',
+                    });
+                }
+                else {
+                    for (let k = 0; k < typeArgs.length; k++) {
+                        const arg = typeArgs[k];
+                        if (!arg || typeof arg !== 'object' || Array.isArray(arg)) {
+                            errors.push({
+                                path: `${mpath}.result.schema.x-blocks-type-args[${k}]`,
+                                message: 'Each entry in x-blocks-type-args must be a valid JSON Schema object',
+                            });
+                        }
+                        else if (arg.$ref) {
+                            validateRef(arg.$ref, `${mpath}.result.schema.x-blocks-type-args[${k}].$ref`, knownSchemas, errors);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Validate components.schemas entries are well-formed
+    if (doc.components?.schemas) {
+        for (const [name, schema] of Object.entries(doc.components.schemas)) {
+            if (!schema || typeof schema !== 'object') {
+                errors.push({ path: `components.schemas.${name}`, message: 'Schema must be an object' });
+            }
+        }
+    }
+    return errors;
+}
+function validateRef(ref, path, knownSchemas, errors) {
+    const prefix = '#/components/schemas/';
+    if (!ref.startsWith(prefix)) {
+        errors.push({ path, message: `$ref "${ref}" must start with "${prefix}"` });
+        return;
+    }
+    const schemaName = ref.slice(prefix.length);
+    if (!knownSchemas.has(schemaName)) {
+        errors.push({ path, message: `$ref "${ref}" does not resolve — "${schemaName}" not found in components.schemas` });
+    }
+}

package/dist/server/index.d.ts

@@ -0,0 +1,3 @@
+export { withAuth, registerCookieProvider, clearCookieProviders } from './withAuth.js';
+export type { CookieProvider } from './withAuth.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACvF,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/server/index.js

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

package/dist/server/withAuth.d.ts

@@ -0,0 +1,142 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+declare global {
+    var __BLOCKS_REQUEST_COOKIES_STORE__: AsyncLocalStorage<string> | undefined;
+}
+/**
+ * A function that attempts to detect cookies from a specific framework's
+ * request context. Returns the cookie string if available, or `undefined`
+ * if the framework is not active or no cookies are present.
+ */
+export type CookieProvider = () => Promise<string | undefined>;
+/**
+ * Register a framework-specific cookie provider for `withAuth()`.
+ *
+ * Providers are tried in registration order when `withAuth()` is called
+ * without explicit cookies. The first provider that returns a non-undefined
+ * value wins.
+ *
+ * Two providers are registered by default:
+ *
+ * - **Next.js** — reads cookies from `next/headers`. Works out of the box.
+ * - **Nuxt/Nitro** — reads cookies from the active Nitro request event
+ *   (via the `unctx` `'nitro-app'` async context). Requires
+ *   `nitro.experimental.asyncContext: true` in `nuxt.config.ts` so Nitro
+ *   wraps each request in an `AsyncLocalStorage` context. Without that
+ *   flag the provider returns `undefined` and a warning is emitted on
+ *   first miss to point at the missing config (see `withAuth` for the
+ *   no-cookies error path).
+ *
+ * Use this to add support for additional frameworks (SvelteKit, Astro, etc.)
+ * or custom cookie sources.
+ *
+ * @param name - Human-readable provider name (for debugging).
+ * @param detect - Async function that returns a cookie string or `undefined`.
+ *
+ * @example
+ * ```typescript
+ * import { registerCookieProvider } from '@aws-blocks/blocks/server';
+ *
+ * // SvelteKit provider
+ * registerCookieProvider('sveltekit', async () => {
+ *   try {
+ *     const { getRequestEvent } = await import('$app/server');
+ *     const event = getRequestEvent();
+ *     return event?.request.headers.get('cookie') ?? undefined;
+ *   } catch {
+ *     return undefined;
+ *   }
+ * });
+ * ```
+ */
+export declare function registerCookieProvider(name: string, detect: CookieProvider): void;
+/**
+ * Clear all registered cookie providers, including the built-in Next.js one.
+ *
+ * Primarily useful for testing. After calling this, you must re-register any
+ * providers you need (including Next.js if desired).
+ *
+ * @example
+ * ```typescript
+ * import { clearCookieProviders, registerCookieProvider } from '@aws-blocks/blocks/server';
+ *
+ * // In test setup
+ * clearCookieProviders();
+ * registerCookieProvider('test', async () => 'session=test');
+ * ```
+ */
+export declare function clearCookieProviders(): void;
+/** @internal Read-only view of registered providers (for testing). */
+export declare function _getProviders(): ReadonlyArray<{
+    name: string;
+    detect: CookieProvider;
+}>;
+/**
+ * Wraps an async function with authenticated cookie forwarding for SSR.
+ *
+ * In SSR server components, browser cookies aren't automatically forwarded
+ * to API calls. This wrapper reads cookies and makes them available to
+ * all Blocks API calls within the callback via `AsyncLocalStorage`.
+ *
+ * **Resolution order:**
+ * 1. Explicit `cookies` parameter (framework-agnostic)
+ * 2. Existing request context (Lambda handler already set it up)
+ * 3. Registered cookie providers — Next.js and Nuxt are built-in, plus any
+ *    you've added via `registerCookieProvider`
+ * 4. Throws if no cookies found
+ *
+ * **Built-in providers:**
+ *
+ * | Framework | Source | Notes |
+ * |-----------|--------|-------|
+ * | Next.js | `next/headers` | Works out of the box. |
+ * | Nuxt/Nitro | Nitro async context (via `unctx`) | Requires `nitro: { experimental: { asyncContext: true } }` in `nuxt.config.ts`. With the flag off the provider returns `undefined` and emits a one-time warning naming the missing config. |
+ *
+ * @param fn - Async function containing Blocks API calls that need auth.
+ * @param cookies - Optional explicit cookie string. If omitted, auto-detects
+ *   from the request context or registered providers. Pass this for frameworks
+ *   without a registered provider (or use `registerCookieProvider` to add one).
+ * @returns The return value of `fn`.
+ *
+ * @example
+ * ```typescript
+ * // Next.js — auto-detects cookies from next/headers (built-in provider)
+ * import { withAuth } from '@aws-blocks/blocks/server';
+ *
+ * const posts = await withAuth(() => api.listMyPosts());
+ *
+ * // Multiple calls in one scope
+ * const data = await withAuth(async () => {
+ *   const posts = await api.listMyPosts();
+ *   const profile = await api.getProfile();
+ *   return { posts, profile };
+ * });
+ *
+ * // Explicit cookies for any framework
+ * const posts = await withAuth(
+ *   () => api.listMyPosts(),
+ *   request.headers.get('cookie'),
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Nuxt — auto-detects cookies via the active Nitro request event
+ * // (built-in provider). Requires the experimental.asyncContext flag.
+ * //
+ * // nuxt.config.ts
+ * // export default defineNuxtConfig({
+ * //   nitro: { experimental: { asyncContext: true } },
+ * // });
+ * //
+ * // server/api/posts.get.ts
+ * import { withAuth } from '@aws-blocks/blocks/server';
+ *
+ * export default defineEventHandler(async () => {
+ *   return withAuth(() => api.listMyPosts());
+ * });
+ * ```
+ *
+ * @throws {Error} If no cookies are found and no provider detected them.
+ */
+export declare function withAuth<T>(fn: () => Promise<T>, cookies?: string | null): Promise<T>;
+//# sourceMappingURL=withAuth.d.ts.map

package/dist/server/withAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withAuth.d.ts","sourceRoot":"","sources":["../../src/server/withAuth.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAIrD,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,gCAAgC,EAAE,iBAAiB,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;CAC7E;AA+BD;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAI/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAOjF;AA0GD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED,sEAAsE;AACtE,wBAAgB,aAAa,IAAI,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,CAAC,CAEvF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,GACtB,OAAO,CAAC,CAAC,CAAC,CAyBZ"}