@aws-blocks/core 0.1.0

package/dist/server/withAuth.js

@@ -0,0 +1,261 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { ApiError } from '../errors.js';
+function getSsrCookies() {
+    const store = globalThis.__BLOCKS_REQUEST_COOKIES_STORE__;
+    if (!store || typeof store.getStore !== 'function')
+        return undefined;
+    return store.getStore();
+}
+/**
+ * Get or lazily create the request cookie AsyncLocalStorage.
+ *
+ * In the API Lambda, `lambda-handler.ts` creates the store and registers it
+ * on `globalThis.__BLOCKS_REQUEST_COOKIES_STORE__`. In the SSR Lambda (a separate
+ * process), the store may not exist yet — this function creates it on demand.
+ *
+ * This module is server-only (never bundled for the browser), so direct
+ * `node:async_hooks` import is safe — no `webpackIgnore` needed.
+ */
+function getRequestCookieStore() {
+    const existing = globalThis.__BLOCKS_REQUEST_COOKIES_STORE__;
+    if (existing)
+        return existing;
+    const store = new AsyncLocalStorage();
+    globalThis.__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+    return store;
+}
+const providers = [];
+/**
+ * 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 function registerCookieProvider(name, detect) {
+    const existingIdx = providers.findIndex(p => p.name === name);
+    if (existingIdx >= 0) {
+        providers[existingIdx] = { name, detect };
+    }
+    else {
+        providers.push({ name, detect });
+    }
+}
+// Built-in Next.js provider — registered by default
+registerCookieProvider('nextjs', async () => {
+    try {
+        const mod = await import('next/headers');
+        const store = await mod.cookies();
+        const all = store.getAll();
+        if (all.length === 0)
+            return undefined;
+        return all.map((c) => `${c.name}=${c.value}`).join('; ');
+    }
+    catch {
+        return undefined;
+    }
+});
+let nuxtAsyncContextWarned = false;
+registerCookieProvider('nuxt', async () => {
+    let getContext;
+    try {
+        ({ getContext } = await import('unctx'));
+    }
+    catch {
+        return undefined; // unctx not installed → not a Nuxt/Nitro app
+    }
+    // `getContext('nitro-app')` itself never throws — it lazily creates the
+    // context registry. `.use()` is what throws when no instance is bound.
+    const nitroAsyncContext = getContext('nitro-app');
+    let bound;
+    try {
+        // `.use()` returns the bound NitroApp or throws.
+        //
+        // TODO(nitro-v3 / nuxt-5): Nitro v3 swaps h3 for srvx, so the bound
+        // context shape changes from `{ event }` (h3 `H3Event`, read below via
+        // `event.node.req.headers.cookie`) to `{ request }` (a standard Web
+        // `Request`, read via `request.headers.get('cookie')`). We read both
+        // shapes below so the provider keeps working across the cutover; revisit
+        // and drop the h3 branch once Nuxt 5 / Nitro v3 is the floor.
+        bound = nitroAsyncContext.use();
+    }
+    catch {
+        // In a Nitro runtime but no context bound for this call — almost
+        // always `experimental.asyncContext: true` missing from the config.
+        // Surface a hint exactly once per process so the developer sees the
+        // root cause, not a downstream generic "no cookies" 401. Suppressible
+        // via env var for tests / intentional setups.
+        if (!nuxtAsyncContextWarned &&
+            process.env.BLOCKS_SUPPRESS_NUXT_ASYNC_CONTEXT_WARN !== '1') {
+            nuxtAsyncContextWarned = true;
+            // eslint-disable-next-line no-console
+            console.warn('[@aws-blocks/core] withAuth: Nuxt/Nitro detected but the request context is not available. ' +
+                "Add `nitro: { experimental: { asyncContext: true } }` to nuxt.config.ts so withAuth() can read cookies from the active request. " +
+                'See https://nuxt.com/docs/guide/going-further/experimental-features#asynccontext');
+        }
+        return undefined;
+    }
+    // h3 (Nitro v2): cookie lives on the Node request headers.
+    // srvx (Nitro v3): cookie lives on the Web `Request` headers. See the
+    // TODO above — the `request` branch future-proofs this for Nuxt 5.
+    const cookie = bound?.event?.node?.req?.headers?.cookie ??
+        bound?.request?.headers?.get('cookie') ??
+        undefined;
+    return typeof cookie === 'string' && cookie.length > 0 ? cookie : undefined;
+});
+/**
+ * Try each registered provider in order; return the first non-undefined result.
+ */
+async function detectFrameworkCookies() {
+    for (const provider of providers) {
+        const result = await provider.detect();
+        if (result)
+            return result;
+    }
+    return undefined;
+}
+/**
+ * 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 function clearCookieProviders() {
+    providers.length = 0;
+}
+/** @internal Read-only view of registered providers (for testing). */
+export function _getProviders() {
+    return providers;
+}
+/**
+ * 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 async function withAuth(fn, cookies) {
+    if (cookies != null && cookies.trim()) {
+        const store = getRequestCookieStore();
+        return store.run(cookies, fn);
+    }
+    const existing = getSsrCookies();
+    if (existing) {
+        return fn();
+    }
+    const detected = await detectFrameworkCookies();
+    if (detected) {
+        const store = getRequestCookieStore();
+        return store.run(detected, fn);
+    }
+    const providerNames = providers.map(p => p.name).join(', ');
+    throw new ApiError(`withAuth: No authentication cookies found. ` +
+        `Tried providers: [${providerNames || 'none registered'}]. ` +
+        `Ensure the user is logged in and cookies are being forwarded, ` +
+        `or pass cookies explicitly as the second argument.`, 401);
+}

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

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

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

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

package/dist/server/withAuth.test.js

@@ -0,0 +1,278 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { getContext } from 'unctx';
+import { withAuth, registerCookieProvider, clearCookieProviders } from './index.js';
+import { _getProviders } from './withAuth.js';
+import { ApiError } from '../errors.js';
+// Seed the `nitro-app` unctx context with `asyncContext: true` at module load,
+// mirroring Nitro's `experimental.asyncContext: true`. unctx caches the context
+// instance on first `getContext()` call (first-write-wins), so this MUST run
+// before any test triggers the provider — otherwise a non-async instance gets
+// cached and `.use()` cannot survive the provider's internal `await import`.
+getContext('nitro-app', { asyncContext: true, AsyncLocalStorage });
+describe('withAuth', () => {
+    let originalStore;
+    beforeEach(() => {
+        originalStore = globalThis.__BLOCKS_REQUEST_COOKIES_STORE__;
+    });
+    afterEach(() => {
+        if (originalStore === undefined) {
+            delete globalThis.__BLOCKS_REQUEST_COOKIES_STORE__;
+        }
+        else {
+            globalThis.__BLOCKS_REQUEST_COOKIES_STORE__ = originalStore;
+        }
+    });
+    test('forwards explicit cookies via AsyncLocalStorage', async () => {
+        const store = new AsyncLocalStorage();
+        globalThis.__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+        let captured;
+        await withAuth(async () => {
+            captured = store.getStore();
+            return 'result';
+        }, 'session=abc123; token=xyz');
+        assert.strictEqual(captured, 'session=abc123; token=xyz');
+    });
+    test('returns the value from fn when explicit cookies provided', async () => {
+        const store = new AsyncLocalStorage();
+        globalThis.__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+        const result = await withAuth(async () => {
+            return { data: 42 };
+        }, 'session=abc');
+        assert.deepStrictEqual(result, { data: 42 });
+    });
+    test('uses existing AsyncLocalStorage context when already set', async () => {
+        const store = new AsyncLocalStorage();
+        globalThis.__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+        let innerCookies;
+        await store.run('existing-cookies', async () => {
+            const result = await withAuth(async () => {
+                innerCookies = store.getStore();
+                return 'ok';
+            });
+            assert.strictEqual(result, 'ok');
+        });
+        assert.strictEqual(innerCookies, 'existing-cookies');
+    });
+    test('throws when no cookies found and no framework detected', async () => {
+        const store = new AsyncLocalStorage();
+        globalThis.__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+        const saved = _getProviders().slice();
+        clearCookieProviders();
+        try {
+            await assert.rejects(() => withAuth(async () => 'should not reach'), (err) => {
+                assert.ok(err instanceof ApiError);
+                assert.ok(err.message.includes('withAuth: No authentication cookies found'));
+                assert.strictEqual(err.status, 401);
+                return true;
+            });
+        }
+        finally {
+            for (const p of saved)
+                registerCookieProvider(p.name, p.detect);
+        }
+    });
+    test('creates AsyncLocalStorage lazily if globalThis store is missing', async () => {
+        delete globalThis.__BLOCKS_REQUEST_COOKIES_STORE__;
+        let storeExistedDuringCall = false;
+        const result = await withAuth(async () => {
+            storeExistedDuringCall = !!globalThis.__BLOCKS_REQUEST_COOKIES_STORE__;
+            return 'created';
+        }, 'lazy-cookies');
+        assert.strictEqual(result, 'created');
+        assert.ok(storeExistedDuringCall, 'Store should be created lazily');
+        assert.ok(globalThis.__BLOCKS_REQUEST_COOKIES_STORE__, 'Store should persist on globalThis');
+    });
+    test('propagates errors from fn', async () => {
+        const store = new AsyncLocalStorage();
+        globalThis.__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+        await assert.rejects(() => withAuth(async () => {
+            throw new Error('inner error');
+        }, 'some-cookies'), { message: 'inner error' });
+    });
+    test('multiple nested API calls share the same cookie context', async () => {
+        const store = new AsyncLocalStorage();
+        globalThis.__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+        const captured = [];
+        await withAuth(async () => {
+            captured.push(store.getStore() ?? 'none');
+            await Promise.resolve();
+            captured.push(store.getStore() ?? 'none');
+            return captured;
+        }, 'shared-session=1');
+        assert.deepStrictEqual(captured, ['shared-session=1', 'shared-session=1']);
+    });
+});
+describe('Cookie Provider Registry', () => {
+    let originalStore;
+    let savedProviders;
+    beforeEach(() => {
+        originalStore = globalThis.__BLOCKS_REQUEST_COOKIES_STORE__;
+        savedProviders = _getProviders().slice();
+        clearCookieProviders();
+    });
+    afterEach(() => {
+        clearCookieProviders();
+        for (const p of savedProviders)
+            registerCookieProvider(p.name, p.detect);
+        if (originalStore === undefined) {
+            delete globalThis.__BLOCKS_REQUEST_COOKIES_STORE__;
+        }
+        else {
+            globalThis.__BLOCKS_REQUEST_COOKIES_STORE__ = originalStore;
+        }
+    });
+    test('default Next.js provider is registered on module load', () => {
+        const providers = savedProviders;
+        const nextProvider = providers.find(p => p.name === 'nextjs');
+        assert.ok(nextProvider, 'Next.js provider should be registered by default');
+    });
+    test('Next.js provider returns undefined when next/headers is not available', async () => {
+        const nextProvider = savedProviders.find(p => p.name === 'nextjs');
+        assert.ok(nextProvider);
+        const result = await nextProvider.detect();
+        assert.strictEqual(result, undefined);
+    });
+    test('default Nuxt provider is registered on module load', () => {
+        const providers = savedProviders;
+        const nuxtProvider = providers.find(p => p.name === 'nuxt');
+        assert.ok(nuxtProvider, 'Nuxt provider should be registered by default');
+    });
+    test('Nuxt provider returns undefined cleanly when no Nitro context is bound', async () => {
+        // When the test runs in a plain node env (no Nitro), either `unctx`
+        // isn't installed (import fails) or it is, but `getContext('nitro-app').use()`
+        // throws because no async context is bound. Both paths must return
+        // undefined, and neither should leak the underlying error to the caller.
+        const nuxtProvider = savedProviders.find(p => p.name === 'nuxt');
+        assert.ok(nuxtProvider);
+        // Suppress the one-time console.warn on the asyncContext-disabled path so
+        // it doesn't contaminate test output.
+        process.env.BLOCKS_SUPPRESS_NUXT_ASYNC_CONTEXT_WARN = '1';
+        try {
+            const result = await nuxtProvider.detect();
+            assert.strictEqual(result, undefined);
+        }
+        finally {
+            delete process.env.BLOCKS_SUPPRESS_NUXT_ASYNC_CONTEXT_WARN;
+        }
+    });
+    test('Nuxt provider reads cookie from the h3 `{ event }` shape (Nitro v2)', async () => {
+        const nuxtProvider = savedProviders.find(p => p.name === 'nuxt');
+        assert.ok(nuxtProvider);
+        // The `nitro-app` context is seeded with asyncContext at module load, so
+        // the binding survives the provider's internal `await import('unctx')`.
+        // Nitro v2 (h3): `{ event }` carrying the cookie on the Node request headers.
+        const bound = { event: { node: { req: { headers: { cookie: 'session=h3' } } } } };
+        const result = await getContext('nitro-app').callAsync(bound, () => nuxtProvider.detect());
+        assert.strictEqual(result, 'session=h3');
+    });
+    test('Nuxt provider reads cookie from the srvx `{ request }` shape (Nitro v3 / Nuxt 5)', async () => {
+        const nuxtProvider = savedProviders.find(p => p.name === 'nuxt');
+        assert.ok(nuxtProvider);
+        // Nitro v3 (srvx): `{ request }` carrying the cookie on a standard Web
+        // `Request`. This is the forward-compat path guarded by the TODO in
+        // withAuth.ts.
+        const bound = { request: new Request('https://example.com', { headers: { cookie: 'session=srvx' } }) };
+        const result = await getContext('nitro-app').callAsync(bound, () => nuxtProvider.detect());
+        assert.strictEqual(result, 'session=srvx');
+    });
+    test('custom provider registration works', async () => {
+        const store = new AsyncLocalStorage();
+        globalThis.__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+        registerCookieProvider('custom', async () => 'custom-cookie=hello');
+        let captured;
+        await withAuth(async () => {
+            captured = store.getStore();
+            return 'ok';
+        });
+        assert.strictEqual(captured, 'custom-cookie=hello');
+    });
+    test('multiple providers tried in registration order — first match wins', async () => {
+        const store = new AsyncLocalStorage();
+        globalThis.__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+        const callOrder = [];
+        registerCookieProvider('first', async () => {
+            callOrder.push('first');
+            return undefined;
+        });
+        registerCookieProvider('second', async () => {
+            callOrder.push('second');
+            return 'winner=second';
+        });
+        registerCookieProvider('third', async () => {
+            callOrder.push('third');
+            return 'should-not-reach=true';
+        });
+        let captured;
+        await withAuth(async () => {
+            captured = store.getStore();
+            return 'ok';
+        });
+        assert.strictEqual(captured, 'winner=second');
+        assert.deepStrictEqual(callOrder, ['first', 'second']);
+    });
+    test('explicit cookies take priority over providers', async () => {
+        const store = new AsyncLocalStorage();
+        globalThis.__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+        let providerCalled = false;
+        registerCookieProvider('should-not-run', async () => {
+            providerCalled = true;
+            return 'provider-cookie=value';
+        });
+        let captured;
+        await withAuth(async () => {
+            captured = store.getStore();
+            return 'ok';
+        }, 'explicit-cookie=priority');
+        assert.strictEqual(captured, 'explicit-cookie=priority');
+        assert.strictEqual(providerCalled, false, 'Provider should not be called when explicit cookies given');
+    });
+    test('existing ALS context takes priority over providers', async () => {
+        const store = new AsyncLocalStorage();
+        globalThis.__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+        let providerCalled = false;
+        registerCookieProvider('should-not-run', async () => {
+            providerCalled = true;
+            return 'provider-cookie=value';
+        });
+        let captured;
+        await store.run('als-cookies', async () => {
+            await withAuth(async () => {
+                captured = store.getStore();
+                return 'ok';
+            });
+        });
+        assert.strictEqual(captured, 'als-cookies');
+        assert.strictEqual(providerCalled, false, 'Provider should not be called when ALS context exists');
+    });
+    test('throws when all providers return undefined', async () => {
+        const store = new AsyncLocalStorage();
+        globalThis.__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+        registerCookieProvider('nope1', async () => undefined);
+        registerCookieProvider('nope2', async () => undefined);
+        await assert.rejects(() => withAuth(async () => 'should not reach'), (err) => {
+            assert.ok(err instanceof ApiError);
+            assert.ok(err.message.includes('withAuth: No authentication cookies found'));
+            assert.strictEqual(err.status, 401);
+            return true;
+        });
+    });
+    test('registerCookieProvider appends to existing providers', () => {
+        registerCookieProvider('a', async () => undefined);
+        registerCookieProvider('b', async () => undefined);
+        const providers = _getProviders();
+        assert.strictEqual(providers.length, 2);
+        assert.strictEqual(providers[0].name, 'a');
+        assert.strictEqual(providers[1].name, 'b');
+    });
+    test('clearCookieProviders removes all registered providers', () => {
+        registerCookieProvider('a', async () => undefined);
+        registerCookieProvider('b', async () => undefined);
+        assert.strictEqual(_getProviders().length, 2);
+        clearCookieProviders();
+        assert.strictEqual(_getProviders().length, 0);
+    });
+});

package/dist/telemetry/client.d.ts

@@ -0,0 +1,59 @@
+import type { BlocksTelemetryEvent, BuildAndSendEventOptions } from './types.js';
+/**
+ * Parse `--telemetry-file=/path/to/file.json` from process.argv.
+ *
+ * Supports both `--telemetry-file=path` and `--telemetry-file path` forms.
+ *
+ * @returns The file path if the flag is present, undefined otherwise.
+ *
+ * @example
+ * // Capture telemetry to file (also sends HTTP when enabled):
+ * // npx tsx aws-blocks/scripts/server.ts --telemetry-file=/tmp/events.json
+ *
+ * // Capture WITHOUT sending (disable HTTP, file still writes):
+ * // AWS_BLOCKS_DISABLE_TELEMETRY=1 npx tsx aws-blocks/scripts/server.ts --telemetry-file=/tmp/events.json
+ */
+export declare function getTelemetryFilePath(): string | undefined;
+/**
+ * Constructs a telemetry event without sending it.
+ * Useful for testing event structure without I/O side effects.
+ * @internal
+ */
+export declare function buildEvent(opts: BuildAndSendEventOptions): BlocksTelemetryEvent;
+/**
+ * Build a complete telemetry event and send it to the collection endpoint.
+ *
+ * This is the single entry point for all telemetry emission. It handles:
+ * 1. Early exit — if telemetry is disabled AND no `--telemetry-file` is set,
+ *    returns immediately with no side effects (no IDs persisted, no notice)
+ * 2. Full payload construction (identifiers, environment, product info)
+ * 3. File sink — writes to the file specified by `--telemetry-file` (if set),
+ *    regardless of opt-out status (inspired by CDK CLI's --telemetry-file)
+ * 4. Privacy filtering — custom BB names are NEVER sent, only counted
+ * 5. HTTP sink — fire-and-forget POST (only when telemetry is enabled)
+ *
+ * The file sink fires unconditionally when `--telemetry-file` is set.
+ * The HTTP sink only fires when telemetry is enabled. Callers never need to
+ * import consent, identifier, or environment utilities directly.
+ *
+ * @param opts - Event metadata (command, state, duration, optional error/product/counters)
+ *
+ * @example
+ * ```ts
+ * buildAndSendEvent({
+ *   command: 'deploy',
+ *   state: 'SUCCESS',
+ *   duration: 4500,
+ *   product: { cdkVersion: '2.150.0' },
+ * });
+ * ```
+ */
+export declare function buildAndSendEvent(opts: BuildAndSendEventOptions): void;
+/**
+ * Send a pre-built telemetry event to the collection endpoint.
+ *
+ * Fire-and-forget: no retry, 500ms timeout, all errors silently swallowed.
+ * Debug output available via `NODE_DEBUG=blocks-telemetry`.
+ */
+export declare function sendEvent(event: BlocksTelemetryEvent): void;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/telemetry/client.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAajF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,SAAS,CAWzD;AAwBD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,wBAAwB,GAAG,oBAAoB,CAwD/E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,IAAI,CAatE;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,oBAAoB,GAAG,IAAI,CAyC3D"}