@cross-deck/node 0.1.0 → 1.1.0

package/dist/auto-events/index.d.mts

@@ -0,0 +1,316 @@
+import { p as CrossdeckServer } from '../crossdeck-server-BXQaFjVx.mjs';
+import 'node:events';
+
+/**
+ * Express auto-events — `request.handled` middleware + uncaught-route
+ * error capture.
+ *
+ * Two middleware factories, registered separately because Express
+ * differentiates them by arity:
+ *
+ *   import { crossdeckExpress, crossdeckExpressErrorHandler } from
+ *     "@cross-deck/node/auto-events";
+ *
+ *   app.use(crossdeckExpress(server));        // request middleware
+ *   app.use(routes);                          // your routes
+ *   app.use(crossdeckExpressErrorHandler(server)); // LAST — error middleware
+ *
+ * `crossdeckExpress` emits `request.handled` on response 'finish'
+ * with the matched route pattern (not the full URL — high-cardinality
+ * URL paths kill dashboards), method, statusCode, and durationMs.
+ *
+ * `crossdeckExpressErrorHandler` catches errors thrown in route
+ * handlers (sync OR async — Express 5 supports async handlers
+ * natively; Express 4 needs the caller to forward via `next(err)`).
+ * The error is shipped with request context (url, method, matched
+ * route) attached so the dashboard can group by route.
+ *
+ * Compatible with both Express 4 and Express 5. The middleware
+ * signatures are stable across both versions.
+ *
+ * No `import` from `express`. The adapter speaks shape-only against
+ * Express's request / response objects — customers don't pay a
+ * forced dependency on Express just to install the Crossdeck SDK.
+ * If `express` is missing at install, this module still compiles.
+ */
+
+/**
+ * Shape of an Express request object — enough fields for the
+ * middleware to do its job without depending on Express's types.
+ */
+interface ExpressRequestLike {
+    method: string;
+    url: string;
+    path?: string;
+    route?: {
+        path?: string | RegExp | Array<string | RegExp>;
+    };
+    originalUrl?: string;
+    headers?: Record<string, string | string[] | undefined>;
+}
+/** Shape of an Express response object. */
+interface ExpressResponseLike {
+    statusCode: number;
+    once(event: "finish" | "close", listener: () => void): unknown;
+    /**
+     * Optional — Express's response exposes this for reading headers
+     * the framework / middleware chain set. Used by the middleware to
+     * surface `responseBytes` on the `request.handled` event. If your
+     * adapter doesn't have it, the field is simply omitted.
+     */
+    getHeader?(name: string): string | string[] | number | undefined;
+}
+type ExpressNext = (err?: unknown) => void;
+interface CrossdeckExpressOptions {
+    /**
+     * Routes to skip. Tested against `req.route?.path` if available, else
+     * `req.path` / `req.url`. Defaults to a single self-skip for
+     * `/crossdeck/*` so the SDK doesn't emit telemetry about its own
+     * health endpoints.
+     */
+    skipPaths?: Array<string | RegExp>;
+    /**
+     * Optional identity extractor — runs once per request. Whatever it
+     * returns is attached to the `request.handled` event so the
+     * dashboard can pivot by user. Typical implementation: read
+     * `req.user.id` populated by your auth middleware.
+     *
+     *   crossdeckExpress(server, {
+     *     getIdentity: (req) => ({ developerUserId: req.user?.id }),
+     *   })
+     */
+    getIdentity?: (req: ExpressRequestLike) => {
+        developerUserId?: string;
+        anonymousId?: string;
+        crossdeckCustomerId?: string;
+    } | null | undefined;
+    /**
+     * Attach `{ url, method, route }` as `context.request` on captured
+     * errors. Default `true`. Set `false` if you have a separate
+     * mechanism for capturing request context (Pino bindings, etc).
+     */
+    captureErrorsWithRequestContext?: boolean;
+}
+/**
+ * Express middleware that emits `request.handled` per request.
+ * Register BEFORE your routes:
+ *
+ *   app.use(crossdeckExpress(server));
+ *
+ * Behaviour:
+ *   - Listens on `res.once('finish')` so we capture the FINAL
+ *     statusCode after any post-route middleware (compression, etc).
+ *     Also listens on `res.once('close')` to cover client-aborted
+ *     requests where 'finish' never fires.
+ *   - Idempotent per request: dispatches once regardless of which
+ *     terminal event fires first.
+ *   - `route` property is the matched route PATTERN (`/users/:id`),
+ *     not the full URL — keeps dashboard cardinality manageable. Falls
+ *     back to `req.path` when no route matched (404s).
+ *   - Errors thrown by `getIdentity` are swallowed and the event still
+ *     ships without identity — telemetry must NEVER break the request
+ *     pipeline.
+ */
+declare function crossdeckExpress(server: CrossdeckServer, options?: CrossdeckExpressOptions): (req: ExpressRequestLike, res: ExpressResponseLike, next: ExpressNext) => void;
+/**
+ * Express error middleware (4-arg signature). Register LAST, after
+ * all routes + after the request middleware:
+ *
+ *   app.use(crossdeckExpressErrorHandler(server));
+ *
+ * Captures the error with request context, then forwards to the next
+ * error handler — Crossdeck observes, the framework still produces the
+ * normal 500 response.
+ *
+ * In Express 5 (async handlers natively forward errors), this middleware
+ * sees errors from any handler. In Express 4, customers must wrap async
+ * route handlers in a `next(err)` adapter — that's not a Crossdeck
+ * limitation; it's how Express 4 works.
+ */
+declare function crossdeckExpressErrorHandler(server: CrossdeckServer, options?: CrossdeckExpressOptions): (err: unknown, req: ExpressRequestLike, _res: ExpressResponseLike, next: ExpressNext) => void;
+declare function shouldSkipRequest(req: ExpressRequestLike, skipPaths: Array<string | RegExp>): boolean;
+declare function extractRoutePattern(req: ExpressRequestLike): string;
+
+/**
+ * AWS Lambda handler wrapper — emits `function.invoked` /
+ * `function.completed` / `function.failed` with Lambda lifecycle
+ * metadata, and (crucially) `await server.flush()` BEFORE the handler
+ * returns.
+ *
+ * Why flush-before-return is non-optional on Lambda: the runtime
+ * freezes the process between invocations. Any event queued but not
+ * sent over the wire vanishes — silently — when the function returns.
+ * `flush-on-exit` doesn't fire because the process isn't exiting;
+ * it's hibernating. Without the wrapper's explicit flush, you'd lose
+ * the very telemetry you installed the SDK for.
+ *
+ *   import { wrapLambdaHandler } from "@cross-deck/node/auto-events";
+ *
+ *   export const handler = wrapLambdaHandler(server, async (event, ctx) => {
+ *     // your handler
+ *   });
+ *
+ * The wrapper preserves the handler's TypeScript signature via
+ * generic parameters so the wrapped handler is type-equivalent to
+ * the original.
+ *
+ * Cold-start detection is per-module-instance: the first invocation
+ * gets `coldStart: true`, subsequent invocations of the SAME warm
+ * container get `coldStart: false`. AWS spawns multiple containers
+ * for concurrent invocations — each container's first invocation is
+ * a cold start, so this is a per-container signal, not per-account.
+ */
+
+/**
+ * Minimal shape of the AWS Lambda invocation context. We don't pull
+ * `@types/aws-lambda` as a dependency — that would force every
+ * non-Lambda caller to install Lambda types just to import the SDK.
+ * The fields we read are the stable subset every Lambda runtime
+ * provides.
+ */
+interface LambdaContextLike {
+    awsRequestId?: string;
+    functionName?: string;
+    functionVersion?: string;
+    invokedFunctionArn?: string;
+    memoryLimitInMB?: number | string;
+    logGroupName?: string;
+    logStreamName?: string;
+    /** Time remaining in the invocation, in ms. Useful for context. */
+    getRemainingTimeInMillis?: () => number;
+}
+type LambdaHandlerLike<TEvent, TResult> = (event: TEvent, context: LambdaContextLike) => Promise<TResult> | TResult;
+interface WrapLambdaOptions {
+    /**
+     * Override the per-container cold-start flag. Module-level
+     * detection is sufficient for production; tests use this to
+     * deterministically reset cold-start across runs.
+     */
+    resetColdStart?: boolean;
+    /**
+     * Optional identity extractor — read auth context from `event`
+     * (e.g. `event.requestContext?.authorizer?.principalId` on an API
+     * Gateway invocation) and attach to the emitted events.
+     */
+    getIdentity?: (event: unknown, context: LambdaContextLike) => {
+        developerUserId?: string;
+        anonymousId?: string;
+        crossdeckCustomerId?: string;
+    } | null | undefined;
+}
+/**
+ * Wrap a Lambda handler. Returns a handler with the same signature.
+ *
+ * Lifecycle emitted:
+ *   - `function.invoked` on entry  — requestId, functionName, coldStart
+ *   - `function.completed` on success — durationMs, memoryUsedMb, statusCode
+ *   - `function.failed` on throw — errorType, errorMessage, durationMs
+ *
+ * Failures also call `server.captureError(err)` so the error pipeline
+ * sees it with `error.handled` shape (frames + fingerprint +
+ * breadcrumbs). The thrown error is re-thrown after capture so Lambda
+ * itself still sees the failure and reports it to CloudWatch.
+ *
+ * `await server.flush()` runs in the `finally` block of every
+ * invocation — bounded best-effort, so a transient backend outage
+ * doesn't keep the function alive past the platform's SIGKILL.
+ */
+declare function wrapLambdaHandler<TEvent, TResult>(server: CrossdeckServer, handler: LambdaHandlerLike<TEvent, TResult>, options?: WrapLambdaOptions): LambdaHandlerLike<TEvent, TResult>;
+
+/**
+ * Firebase Cloud Functions wrapper — generic across v1 + v2, also
+ * usable for Google Cloud Run Functions and Cloud Run services
+ * (anything that exposes a Node handler and freezes / tears down
+ * between invocations).
+ *
+ * Why generic: Firebase has many handler signatures across v1 and v2:
+ *   v1 https.onRequest:  (req, res) => void
+ *   v1 https.onCall:     (data, context) => Promise<result>
+ *   v1 firestore.onWrite: (snapshot, context) => Promise<void>
+ *   v1 pubsub.onPublish: (message, context) => Promise<void>
+ *   v2 onRequest:        (req, res) => Promise<void>
+ *   v2 onCall:           (request) => Promise<result>
+ *   v2 onDocumentWritten: (event) => Promise<void>
+ *
+ * Rather than ship one wrapper per signature (which would force a
+ * dependency on `firebase-functions` types and break when Google
+ * adds new triggers), this wrapper is **shape-preserving** — it
+ * accepts ANY function and returns one with the same signature.
+ * Lifecycle telemetry is emitted around the call; metadata extraction
+ * is plug-in via `getMetadata`.
+ *
+ *   import { wrapFunction } from "@cross-deck/node/auto-events";
+ *   import { onRequest } from "firebase-functions/v2/https";
+ *
+ *   export const myFunction = onRequest(wrapFunction(server, async (req, res) => {
+ *     // your handler
+ *   }));
+ *
+ * Cold-start detection: same per-container logic as Lambda. The
+ * first invocation of a fresh container is a cold start; subsequent
+ * invocations of the same warm container are not.
+ *
+ * Flush-before-return: same critical contract as Lambda. Firebase
+ * tears down idle containers; queued events vanish if the SDK doesn't
+ * flush before the handler returns.
+ */
+
+interface WrapFunctionOptions {
+    /**
+     * Override the per-container cold-start flag. Module-level
+     * detection is sufficient for production; tests use this to
+     * deterministically reset cold-start across runs.
+     */
+    resetColdStart?: boolean;
+    /**
+     * Optional metadata extractor — read trigger-specific fields off
+     * the handler arguments and attach them to the emitted events.
+     * Default: no extra metadata.
+     *
+     * Return `{ identity, properties }` so identity hints route onto
+     * the event envelope (for dashboard pivot) and properties merge
+     * into the event's `properties` bag:
+     *
+     *   wrapFunction(server, handler, {
+     *     getMetadata: (args) => ({
+     *       identity: { developerUserId: args[0].auth?.uid },
+     *       properties: { docPath: args[0].ref?.path, region: "us-central1" },
+     *     }),
+     *   })
+     */
+    getMetadata?: (args: unknown[]) => WrapFunctionMetadata | null | undefined;
+    /**
+     * Label for the `runtime` event property. Defaults to
+     * `"firebase-functions"`. Override to distinguish triggers in
+     * dashboards (e.g. `"firebase-https"` vs `"firebase-firestore"`).
+     */
+    runtime?: string;
+}
+interface WrapFunctionMetadata {
+    /** Identity hint attached to the event envelope (developerUserId / anonymousId / crossdeckCustomerId). */
+    identity?: {
+        developerUserId?: string;
+        anonymousId?: string;
+        crossdeckCustomerId?: string;
+    };
+    /** Additional properties merged into emitted event properties. */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Shape-preserving wrap for a Firebase / Cloud Run handler. Returns
+ * a function with the SAME signature as the input.
+ *
+ * Lifecycle emitted:
+ *   - `function.invoked` on entry — runtime, coldStart, ...metadata
+ *   - `function.completed` on success — durationMs, memoryUsedMb
+ *   - `function.failed` on throw — errorType, errorMessage, durationMs
+ *
+ * Failures also call `server.captureError(err)`. Errors are re-thrown
+ * so Firebase still sees the failure and reports it to Cloud Logging.
+ *
+ * `await server.flush()` runs in `finally` — same as Lambda. Firebase
+ * containers freeze / tear down between invocations.
+ */
+declare function wrapFunction<TArgs extends unknown[], TResult>(server: CrossdeckServer, handler: (...args: TArgs) => Promise<TResult> | TResult, options?: WrapFunctionOptions): (...args: TArgs) => Promise<TResult>;
+
+export { type CrossdeckExpressOptions, type ExpressNext, type ExpressRequestLike, type ExpressResponseLike, type LambdaContextLike, type LambdaHandlerLike, type WrapFunctionMetadata, type WrapFunctionOptions, type WrapLambdaOptions, crossdeckExpress, crossdeckExpressErrorHandler, extractRoutePattern, shouldSkipRequest, wrapFunction, wrapLambdaHandler };

package/dist/auto-events/index.d.ts

@@ -0,0 +1,316 @@
+import { p as CrossdeckServer } from '../crossdeck-server-BXQaFjVx.js';
+import 'node:events';
+
+/**
+ * Express auto-events — `request.handled` middleware + uncaught-route
+ * error capture.
+ *
+ * Two middleware factories, registered separately because Express
+ * differentiates them by arity:
+ *
+ *   import { crossdeckExpress, crossdeckExpressErrorHandler } from
+ *     "@cross-deck/node/auto-events";
+ *
+ *   app.use(crossdeckExpress(server));        // request middleware
+ *   app.use(routes);                          // your routes
+ *   app.use(crossdeckExpressErrorHandler(server)); // LAST — error middleware
+ *
+ * `crossdeckExpress` emits `request.handled` on response 'finish'
+ * with the matched route pattern (not the full URL — high-cardinality
+ * URL paths kill dashboards), method, statusCode, and durationMs.
+ *
+ * `crossdeckExpressErrorHandler` catches errors thrown in route
+ * handlers (sync OR async — Express 5 supports async handlers
+ * natively; Express 4 needs the caller to forward via `next(err)`).
+ * The error is shipped with request context (url, method, matched
+ * route) attached so the dashboard can group by route.
+ *
+ * Compatible with both Express 4 and Express 5. The middleware
+ * signatures are stable across both versions.
+ *
+ * No `import` from `express`. The adapter speaks shape-only against
+ * Express's request / response objects — customers don't pay a
+ * forced dependency on Express just to install the Crossdeck SDK.
+ * If `express` is missing at install, this module still compiles.
+ */
+
+/**
+ * Shape of an Express request object — enough fields for the
+ * middleware to do its job without depending on Express's types.
+ */
+interface ExpressRequestLike {
+    method: string;
+    url: string;
+    path?: string;
+    route?: {
+        path?: string | RegExp | Array<string | RegExp>;
+    };
+    originalUrl?: string;
+    headers?: Record<string, string | string[] | undefined>;
+}
+/** Shape of an Express response object. */
+interface ExpressResponseLike {
+    statusCode: number;
+    once(event: "finish" | "close", listener: () => void): unknown;
+    /**
+     * Optional — Express's response exposes this for reading headers
+     * the framework / middleware chain set. Used by the middleware to
+     * surface `responseBytes` on the `request.handled` event. If your
+     * adapter doesn't have it, the field is simply omitted.
+     */
+    getHeader?(name: string): string | string[] | number | undefined;
+}
+type ExpressNext = (err?: unknown) => void;
+interface CrossdeckExpressOptions {
+    /**
+     * Routes to skip. Tested against `req.route?.path` if available, else
+     * `req.path` / `req.url`. Defaults to a single self-skip for
+     * `/crossdeck/*` so the SDK doesn't emit telemetry about its own
+     * health endpoints.
+     */
+    skipPaths?: Array<string | RegExp>;
+    /**
+     * Optional identity extractor — runs once per request. Whatever it
+     * returns is attached to the `request.handled` event so the
+     * dashboard can pivot by user. Typical implementation: read
+     * `req.user.id` populated by your auth middleware.
+     *
+     *   crossdeckExpress(server, {
+     *     getIdentity: (req) => ({ developerUserId: req.user?.id }),
+     *   })
+     */
+    getIdentity?: (req: ExpressRequestLike) => {
+        developerUserId?: string;
+        anonymousId?: string;
+        crossdeckCustomerId?: string;
+    } | null | undefined;
+    /**
+     * Attach `{ url, method, route }` as `context.request` on captured
+     * errors. Default `true`. Set `false` if you have a separate
+     * mechanism for capturing request context (Pino bindings, etc).
+     */
+    captureErrorsWithRequestContext?: boolean;
+}
+/**
+ * Express middleware that emits `request.handled` per request.
+ * Register BEFORE your routes:
+ *
+ *   app.use(crossdeckExpress(server));
+ *
+ * Behaviour:
+ *   - Listens on `res.once('finish')` so we capture the FINAL
+ *     statusCode after any post-route middleware (compression, etc).
+ *     Also listens on `res.once('close')` to cover client-aborted
+ *     requests where 'finish' never fires.
+ *   - Idempotent per request: dispatches once regardless of which
+ *     terminal event fires first.
+ *   - `route` property is the matched route PATTERN (`/users/:id`),
+ *     not the full URL — keeps dashboard cardinality manageable. Falls
+ *     back to `req.path` when no route matched (404s).
+ *   - Errors thrown by `getIdentity` are swallowed and the event still
+ *     ships without identity — telemetry must NEVER break the request
+ *     pipeline.
+ */
+declare function crossdeckExpress(server: CrossdeckServer, options?: CrossdeckExpressOptions): (req: ExpressRequestLike, res: ExpressResponseLike, next: ExpressNext) => void;
+/**
+ * Express error middleware (4-arg signature). Register LAST, after
+ * all routes + after the request middleware:
+ *
+ *   app.use(crossdeckExpressErrorHandler(server));
+ *
+ * Captures the error with request context, then forwards to the next
+ * error handler — Crossdeck observes, the framework still produces the
+ * normal 500 response.
+ *
+ * In Express 5 (async handlers natively forward errors), this middleware
+ * sees errors from any handler. In Express 4, customers must wrap async
+ * route handlers in a `next(err)` adapter — that's not a Crossdeck
+ * limitation; it's how Express 4 works.
+ */
+declare function crossdeckExpressErrorHandler(server: CrossdeckServer, options?: CrossdeckExpressOptions): (err: unknown, req: ExpressRequestLike, _res: ExpressResponseLike, next: ExpressNext) => void;
+declare function shouldSkipRequest(req: ExpressRequestLike, skipPaths: Array<string | RegExp>): boolean;
+declare function extractRoutePattern(req: ExpressRequestLike): string;
+
+/**
+ * AWS Lambda handler wrapper — emits `function.invoked` /
+ * `function.completed` / `function.failed` with Lambda lifecycle
+ * metadata, and (crucially) `await server.flush()` BEFORE the handler
+ * returns.
+ *
+ * Why flush-before-return is non-optional on Lambda: the runtime
+ * freezes the process between invocations. Any event queued but not
+ * sent over the wire vanishes — silently — when the function returns.
+ * `flush-on-exit` doesn't fire because the process isn't exiting;
+ * it's hibernating. Without the wrapper's explicit flush, you'd lose
+ * the very telemetry you installed the SDK for.
+ *
+ *   import { wrapLambdaHandler } from "@cross-deck/node/auto-events";
+ *
+ *   export const handler = wrapLambdaHandler(server, async (event, ctx) => {
+ *     // your handler
+ *   });
+ *
+ * The wrapper preserves the handler's TypeScript signature via
+ * generic parameters so the wrapped handler is type-equivalent to
+ * the original.
+ *
+ * Cold-start detection is per-module-instance: the first invocation
+ * gets `coldStart: true`, subsequent invocations of the SAME warm
+ * container get `coldStart: false`. AWS spawns multiple containers
+ * for concurrent invocations — each container's first invocation is
+ * a cold start, so this is a per-container signal, not per-account.
+ */
+
+/**
+ * Minimal shape of the AWS Lambda invocation context. We don't pull
+ * `@types/aws-lambda` as a dependency — that would force every
+ * non-Lambda caller to install Lambda types just to import the SDK.
+ * The fields we read are the stable subset every Lambda runtime
+ * provides.
+ */
+interface LambdaContextLike {
+    awsRequestId?: string;
+    functionName?: string;
+    functionVersion?: string;
+    invokedFunctionArn?: string;
+    memoryLimitInMB?: number | string;
+    logGroupName?: string;
+    logStreamName?: string;
+    /** Time remaining in the invocation, in ms. Useful for context. */
+    getRemainingTimeInMillis?: () => number;
+}
+type LambdaHandlerLike<TEvent, TResult> = (event: TEvent, context: LambdaContextLike) => Promise<TResult> | TResult;
+interface WrapLambdaOptions {
+    /**
+     * Override the per-container cold-start flag. Module-level
+     * detection is sufficient for production; tests use this to
+     * deterministically reset cold-start across runs.
+     */
+    resetColdStart?: boolean;
+    /**
+     * Optional identity extractor — read auth context from `event`
+     * (e.g. `event.requestContext?.authorizer?.principalId` on an API
+     * Gateway invocation) and attach to the emitted events.
+     */
+    getIdentity?: (event: unknown, context: LambdaContextLike) => {
+        developerUserId?: string;
+        anonymousId?: string;
+        crossdeckCustomerId?: string;
+    } | null | undefined;
+}
+/**
+ * Wrap a Lambda handler. Returns a handler with the same signature.
+ *
+ * Lifecycle emitted:
+ *   - `function.invoked` on entry  — requestId, functionName, coldStart
+ *   - `function.completed` on success — durationMs, memoryUsedMb, statusCode
+ *   - `function.failed` on throw — errorType, errorMessage, durationMs
+ *
+ * Failures also call `server.captureError(err)` so the error pipeline
+ * sees it with `error.handled` shape (frames + fingerprint +
+ * breadcrumbs). The thrown error is re-thrown after capture so Lambda
+ * itself still sees the failure and reports it to CloudWatch.
+ *
+ * `await server.flush()` runs in the `finally` block of every
+ * invocation — bounded best-effort, so a transient backend outage
+ * doesn't keep the function alive past the platform's SIGKILL.
+ */
+declare function wrapLambdaHandler<TEvent, TResult>(server: CrossdeckServer, handler: LambdaHandlerLike<TEvent, TResult>, options?: WrapLambdaOptions): LambdaHandlerLike<TEvent, TResult>;
+
+/**
+ * Firebase Cloud Functions wrapper — generic across v1 + v2, also
+ * usable for Google Cloud Run Functions and Cloud Run services
+ * (anything that exposes a Node handler and freezes / tears down
+ * between invocations).
+ *
+ * Why generic: Firebase has many handler signatures across v1 and v2:
+ *   v1 https.onRequest:  (req, res) => void
+ *   v1 https.onCall:     (data, context) => Promise<result>
+ *   v1 firestore.onWrite: (snapshot, context) => Promise<void>
+ *   v1 pubsub.onPublish: (message, context) => Promise<void>
+ *   v2 onRequest:        (req, res) => Promise<void>
+ *   v2 onCall:           (request) => Promise<result>
+ *   v2 onDocumentWritten: (event) => Promise<void>
+ *
+ * Rather than ship one wrapper per signature (which would force a
+ * dependency on `firebase-functions` types and break when Google
+ * adds new triggers), this wrapper is **shape-preserving** — it
+ * accepts ANY function and returns one with the same signature.
+ * Lifecycle telemetry is emitted around the call; metadata extraction
+ * is plug-in via `getMetadata`.
+ *
+ *   import { wrapFunction } from "@cross-deck/node/auto-events";
+ *   import { onRequest } from "firebase-functions/v2/https";
+ *
+ *   export const myFunction = onRequest(wrapFunction(server, async (req, res) => {
+ *     // your handler
+ *   }));
+ *
+ * Cold-start detection: same per-container logic as Lambda. The
+ * first invocation of a fresh container is a cold start; subsequent
+ * invocations of the same warm container are not.
+ *
+ * Flush-before-return: same critical contract as Lambda. Firebase
+ * tears down idle containers; queued events vanish if the SDK doesn't
+ * flush before the handler returns.
+ */
+
+interface WrapFunctionOptions {
+    /**
+     * Override the per-container cold-start flag. Module-level
+     * detection is sufficient for production; tests use this to
+     * deterministically reset cold-start across runs.
+     */
+    resetColdStart?: boolean;
+    /**
+     * Optional metadata extractor — read trigger-specific fields off
+     * the handler arguments and attach them to the emitted events.
+     * Default: no extra metadata.
+     *
+     * Return `{ identity, properties }` so identity hints route onto
+     * the event envelope (for dashboard pivot) and properties merge
+     * into the event's `properties` bag:
+     *
+     *   wrapFunction(server, handler, {
+     *     getMetadata: (args) => ({
+     *       identity: { developerUserId: args[0].auth?.uid },
+     *       properties: { docPath: args[0].ref?.path, region: "us-central1" },
+     *     }),
+     *   })
+     */
+    getMetadata?: (args: unknown[]) => WrapFunctionMetadata | null | undefined;
+    /**
+     * Label for the `runtime` event property. Defaults to
+     * `"firebase-functions"`. Override to distinguish triggers in
+     * dashboards (e.g. `"firebase-https"` vs `"firebase-firestore"`).
+     */
+    runtime?: string;
+}
+interface WrapFunctionMetadata {
+    /** Identity hint attached to the event envelope (developerUserId / anonymousId / crossdeckCustomerId). */
+    identity?: {
+        developerUserId?: string;
+        anonymousId?: string;
+        crossdeckCustomerId?: string;
+    };
+    /** Additional properties merged into emitted event properties. */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Shape-preserving wrap for a Firebase / Cloud Run handler. Returns
+ * a function with the SAME signature as the input.
+ *
+ * Lifecycle emitted:
+ *   - `function.invoked` on entry — runtime, coldStart, ...metadata
+ *   - `function.completed` on success — durationMs, memoryUsedMb
+ *   - `function.failed` on throw — errorType, errorMessage, durationMs
+ *
+ * Failures also call `server.captureError(err)`. Errors are re-thrown
+ * so Firebase still sees the failure and reports it to Cloud Logging.
+ *
+ * `await server.flush()` runs in `finally` — same as Lambda. Firebase
+ * containers freeze / tear down between invocations.
+ */
+declare function wrapFunction<TArgs extends unknown[], TResult>(server: CrossdeckServer, handler: (...args: TArgs) => Promise<TResult> | TResult, options?: WrapFunctionOptions): (...args: TArgs) => Promise<TResult>;
+
+export { type CrossdeckExpressOptions, type ExpressNext, type ExpressRequestLike, type ExpressResponseLike, type LambdaContextLike, type LambdaHandlerLike, type WrapFunctionMetadata, type WrapFunctionOptions, type WrapLambdaOptions, crossdeckExpress, crossdeckExpressErrorHandler, extractRoutePattern, shouldSkipRequest, wrapFunction, wrapLambdaHandler };