@noony-serverless/core 0.3.4 → 0.4.1

package/build/utils/fastify-wrapper.d.ts

@@ -0,0 +1,74 @@
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import { Handler } from '../core/handler';
+/**
+ * Create a Fastify route handler wrapper for a Noony handler
+ *
+ * Wraps a Noony handler into a Fastify route handler for use with Fastify server.
+ * This pattern enables running Noony handlers with Fastify's high-performance HTTP framework.
+ *
+ * @param noonyHandler - The Noony handler to wrap (contains middleware chain and controller)
+ * @param functionName - Name for error logging purposes
+ * @param initializeDependencies - Async function that initializes dependencies (database, services, etc.)
+ *                                  Uses singleton pattern to prevent re-initialization across requests
+ * @returns Fastify route handler: `(req: FastifyRequest, reply: FastifyReply) => Promise<void>`
+ *
+ * @remarks
+ * This wrapper ensures:
+ * - Dependencies are initialized before handler execution (singleton pattern for efficiency)
+ * - Noony handlers work seamlessly with Fastify routing
+ * - Errors are caught and returned as proper HTTP responses
+ * - Response is not sent twice (`reply.sent` check)
+ * - `RESPONSE_SENT` errors are ignored (response already sent by middleware)
+ * - Real errors return 500 with generic message for security
+ *
+ * @example
+ * Creating Fastify app with multiple routes:
+ * ```typescript
+ * import Fastify from 'fastify';
+ * import { createFastifyHandler } from '@noony-serverless/core';
+ * import { loginHandler, getConfigHandler } from './handlers';
+ *
+ * // Initialize dependencies once per app startup
+ * let initialized = false;
+ * async function initializeDependencies(): Promise<void> {
+ *   if (initialized) return;
+ *   const db = await databaseService.connect();
+ *   await initializeServices(db);
+ *   initialized = true;
+ * }
+ *
+ * const server = Fastify({ logger: true });
+ *
+ * // Helper shorthand
+ * const adapt = (handler, name) => createFastifyHandler(handler, name, initializeDependencies);
+ *
+ * // Auth routes
+ * server.post('/api/auth/login', adapt(loginHandler, 'login'));
+ *
+ * // Config routes
+ * server.get('/api/config', adapt(getConfigHandler, 'getConfig'));
+ *
+ * // Start server
+ * server.listen({ port: 3000 }, (err) => {
+ *   if (err) throw err;
+ *   console.log('Server running on port 3000');
+ * });
+ * ```
+ *
+ * @example
+ * Fastify routing with path parameters:
+ * ```typescript
+ * const server = Fastify();
+ *
+ * // Routes with path parameters work seamlessly
+ * server.get('/api/users/:userId', adapt(getUserHandler, 'getUser'));
+ * server.patch('/api/config/sections/:sectionId', adapt(updateSectionHandler, 'updateSection'));
+ *
+ * // Path parameters available in Noony handler via context.req.params
+ * ```
+ *
+ * @see {@link createHttpFunction} for Cloud Functions Framework integration (production deployment)
+ * @see {@link wrapNoonyHandler} for Express integration
+ */
+export declare function createFastifyHandler(noonyHandler: Handler<unknown>, functionName: string, initializeDependencies: () => Promise<void>): (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+//# sourceMappingURL=fastify-wrapper.d.ts.map

package/build/utils/fastify-wrapper.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFastifyHandler = createFastifyHandler;
+const logger_1 = require("../core/logger");
+/**
+ * Adapt Fastify Request to GenericRequest for Noony handlers
+ *
+ * @internal
+ */
+function adaptFastifyRequest(req) {
+    return {
+        method: req.method,
+        url: req.url,
+        path: req.routeOptions?.url || req.url,
+        headers: req.headers,
+        query: (req.query || {}),
+        params: (req.params || {}),
+        body: req.body,
+        // Fastify already parses the body, so set parsedBody for BodyValidationMiddleware
+        parsedBody: req.body,
+        ip: req.ip,
+        userAgent: req.headers['user-agent'],
+    };
+}
+/**
+ * Adapt Fastify Reply to GenericResponse for Noony handlers
+ *
+ * @internal
+ */
+function adaptFastifyResponse(reply) {
+    let statusCode = 200;
+    let headersSent = false;
+    const response = {
+        status(code) {
+            statusCode = code;
+            reply.code(code);
+            return response;
+        },
+        json(data) {
+            headersSent = true;
+            reply.send(data);
+            return response;
+        },
+        send(data) {
+            headersSent = true;
+            reply.send(data);
+            return response;
+        },
+        header(name, value) {
+            reply.header(name, value);
+            return response;
+        },
+        headers(headers) {
+            Object.entries(headers).forEach(([key, value]) => {
+                reply.header(key, value);
+            });
+            return response;
+        },
+        end() {
+            headersSent = true;
+            reply.send();
+        },
+        get statusCode() {
+            return statusCode;
+        },
+        get headersSent() {
+            return headersSent || reply.sent;
+        },
+    };
+    return response;
+}
+/**
+ * Create a Fastify route handler wrapper for a Noony handler
+ *
+ * Wraps a Noony handler into a Fastify route handler for use with Fastify server.
+ * This pattern enables running Noony handlers with Fastify's high-performance HTTP framework.
+ *
+ * @param noonyHandler - The Noony handler to wrap (contains middleware chain and controller)
+ * @param functionName - Name for error logging purposes
+ * @param initializeDependencies - Async function that initializes dependencies (database, services, etc.)
+ *                                  Uses singleton pattern to prevent re-initialization across requests
+ * @returns Fastify route handler: `(req: FastifyRequest, reply: FastifyReply) => Promise<void>`
+ *
+ * @remarks
+ * This wrapper ensures:
+ * - Dependencies are initialized before handler execution (singleton pattern for efficiency)
+ * - Noony handlers work seamlessly with Fastify routing
+ * - Errors are caught and returned as proper HTTP responses
+ * - Response is not sent twice (`reply.sent` check)
+ * - `RESPONSE_SENT` errors are ignored (response already sent by middleware)
+ * - Real errors return 500 with generic message for security
+ *
+ * @example
+ * Creating Fastify app with multiple routes:
+ * ```typescript
+ * import Fastify from 'fastify';
+ * import { createFastifyHandler } from '@noony-serverless/core';
+ * import { loginHandler, getConfigHandler } from './handlers';
+ *
+ * // Initialize dependencies once per app startup
+ * let initialized = false;
+ * async function initializeDependencies(): Promise<void> {
+ *   if (initialized) return;
+ *   const db = await databaseService.connect();
+ *   await initializeServices(db);
+ *   initialized = true;
+ * }
+ *
+ * const server = Fastify({ logger: true });
+ *
+ * // Helper shorthand
+ * const adapt = (handler, name) => createFastifyHandler(handler, name, initializeDependencies);
+ *
+ * // Auth routes
+ * server.post('/api/auth/login', adapt(loginHandler, 'login'));
+ *
+ * // Config routes
+ * server.get('/api/config', adapt(getConfigHandler, 'getConfig'));
+ *
+ * // Start server
+ * server.listen({ port: 3000 }, (err) => {
+ *   if (err) throw err;
+ *   console.log('Server running on port 3000');
+ * });
+ * ```
+ *
+ * @example
+ * Fastify routing with path parameters:
+ * ```typescript
+ * const server = Fastify();
+ *
+ * // Routes with path parameters work seamlessly
+ * server.get('/api/users/:userId', adapt(getUserHandler, 'getUser'));
+ * server.patch('/api/config/sections/:sectionId', adapt(updateSectionHandler, 'updateSection'));
+ *
+ * // Path parameters available in Noony handler via context.req.params
+ * ```
+ *
+ * @see {@link createHttpFunction} for Cloud Functions Framework integration (production deployment)
+ * @see {@link wrapNoonyHandler} for Express integration
+ */
+function createFastifyHandler(noonyHandler, functionName, initializeDependencies) {
+    return async (req, reply) => {
+        try {
+            // Ensure dependencies are initialized
+            await initializeDependencies();
+            // Adapt Fastify req/reply to GenericRequest/GenericResponse
+            const genericReq = adaptFastifyRequest(req);
+            const genericRes = adaptFastifyResponse(reply);
+            // Execute Noony handler with adapted request/response
+            await noonyHandler.executeGeneric(genericReq, genericRes);
+        }
+        catch (error) {
+            // Ignore RESPONSE_SENT markers (response already sent by middleware)
+            if (error instanceof Error && error.message === 'RESPONSE_SENT') {
+                return;
+            }
+            logger_1.logger.error(`${functionName} handler error`, {
+                error: error instanceof Error ? error.message : 'Unknown error',
+                stack: error instanceof Error ? error.stack : undefined,
+            });
+            // Graceful error handling - only send if response not already sent
+            if (!reply.sent) {
+                reply.code(500).send({
+                    success: false,
+                    error: {
+                        code: 'INTERNAL_SERVER_ERROR',
+                        message: 'An unexpected error occurred',
+                    },
+                });
+            }
+        }
+    };
+}
+//# sourceMappingURL=fastify-wrapper.js.map

package/build/utils/index.d.ts

@@ -3,4 +3,8 @@
  */
 export { getService } from './container.utils';
 export { asString, asStringArray, asNumber, asBoolean, } from './query-param.utils';
+export { isPubSubMessage, extractTraceContext, injectTraceContext, createParentContext, type PubSubMessage, type TraceContext, } from './pubsub-trace.utils';
+export { createOTELMixin, getOTELContext, getOTELContextFromSpan, getOTELContextFromContext, formatTraceIdForCloudLogging, createCloudLoggingEntry, isOTELActive, isOTELInstalled, type OTELLogContext, } from './otel.helper';
+export { createHttpFunction, wrapNoonyHandler } from './wrapper-utils';
+export { createFastifyHandler } from './fastify-wrapper';
 //# sourceMappingURL=index.d.ts.map

package/build/utils/index.js

@@ -3,7 +3,7 @@
  * Utility functions for Noony Core
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.asBoolean = exports.asNumber = exports.asStringArray = exports.asString = exports.getService = void 0;
+exports.createFastifyHandler = exports.wrapNoonyHandler = exports.createHttpFunction = exports.isOTELInstalled = exports.isOTELActive = exports.createCloudLoggingEntry = exports.formatTraceIdForCloudLogging = exports.getOTELContextFromContext = exports.getOTELContextFromSpan = exports.getOTELContext = exports.createOTELMixin = exports.createParentContext = exports.injectTraceContext = exports.extractTraceContext = exports.isPubSubMessage = exports.asBoolean = exports.asNumber = exports.asStringArray = exports.asString = exports.getService = void 0;
 // Container utilities
 var container_utils_1 = require("./container.utils");
 Object.defineProperty(exports, "getService", { enumerable: true, get: function () { return container_utils_1.getService; } });
@@ -13,4 +13,26 @@ Object.defineProperty(exports, "asString", { enumerable: true, get: function ()
 Object.defineProperty(exports, "asStringArray", { enumerable: true, get: function () { return query_param_utils_1.asStringArray; } });
 Object.defineProperty(exports, "asNumber", { enumerable: true, get: function () { return query_param_utils_1.asNumber; } });
 Object.defineProperty(exports, "asBoolean", { enumerable: true, get: function () { return query_param_utils_1.asBoolean; } });
+// Pub/Sub trace propagation utilities
+var pubsub_trace_utils_1 = require("./pubsub-trace.utils");
+Object.defineProperty(exports, "isPubSubMessage", { enumerable: true, get: function () { return pubsub_trace_utils_1.isPubSubMessage; } });
+Object.defineProperty(exports, "extractTraceContext", { enumerable: true, get: function () { return pubsub_trace_utils_1.extractTraceContext; } });
+Object.defineProperty(exports, "injectTraceContext", { enumerable: true, get: function () { return pubsub_trace_utils_1.injectTraceContext; } });
+Object.defineProperty(exports, "createParentContext", { enumerable: true, get: function () { return pubsub_trace_utils_1.createParentContext; } });
+// OpenTelemetry logger integration utilities
+var otel_helper_1 = require("./otel.helper");
+Object.defineProperty(exports, "createOTELMixin", { enumerable: true, get: function () { return otel_helper_1.createOTELMixin; } });
+Object.defineProperty(exports, "getOTELContext", { enumerable: true, get: function () { return otel_helper_1.getOTELContext; } });
+Object.defineProperty(exports, "getOTELContextFromSpan", { enumerable: true, get: function () { return otel_helper_1.getOTELContextFromSpan; } });
+Object.defineProperty(exports, "getOTELContextFromContext", { enumerable: true, get: function () { return otel_helper_1.getOTELContextFromContext; } });
+Object.defineProperty(exports, "formatTraceIdForCloudLogging", { enumerable: true, get: function () { return otel_helper_1.formatTraceIdForCloudLogging; } });
+Object.defineProperty(exports, "createCloudLoggingEntry", { enumerable: true, get: function () { return otel_helper_1.createCloudLoggingEntry; } });
+Object.defineProperty(exports, "isOTELActive", { enumerable: true, get: function () { return otel_helper_1.isOTELActive; } });
+Object.defineProperty(exports, "isOTELInstalled", { enumerable: true, get: function () { return otel_helper_1.isOTELInstalled; } });
+// Wrapper utilities for GCP Functions, Express, and Fastify
+var wrapper_utils_1 = require("./wrapper-utils");
+Object.defineProperty(exports, "createHttpFunction", { enumerable: true, get: function () { return wrapper_utils_1.createHttpFunction; } });
+Object.defineProperty(exports, "wrapNoonyHandler", { enumerable: true, get: function () { return wrapper_utils_1.wrapNoonyHandler; } });
+var fastify_wrapper_1 = require("./fastify-wrapper");
+Object.defineProperty(exports, "createFastifyHandler", { enumerable: true, get: function () { return fastify_wrapper_1.createFastifyHandler; } });
 //# sourceMappingURL=index.js.map

package/build/utils/otel.helper.d.ts

@@ -0,0 +1,122 @@
+/**
+ * OpenTelemetry Helper Utilities
+ *
+ * Provides helper functions for integrating OpenTelemetry with logging systems.
+ * These utilities enable automatic trace/span ID injection into log entries for
+ * correlation with distributed traces in Cloud Logging and other observability platforms.
+ *
+ * @module utils/otel.helper
+ */
+import type { Context as OtelContext, Span } from '@opentelemetry/api';
+/**
+ * OTEL context object for logger integration
+ */
+export interface OTELLogContext {
+    traceId?: string;
+    spanId?: string;
+    traceFlags?: number;
+}
+/**
+ * Create Pino mixin for automatic trace/span ID injection
+ *
+ * This function creates a Pino mixin that automatically adds OpenTelemetry
+ * trace and span IDs to every log entry. This enables log-trace correlation
+ * in Cloud Logging and other observability platforms.
+ *
+ * Usage with Pino:
+ * ```typescript
+ * import pino from 'pino';
+ * import { createOTELMixin } from '@noony-serverless/core';
+ *
+ * const logger = pino({
+ *   mixin: createOTELMixin,
+ *   // ... other config
+ * });
+ *
+ * logger.info('User created'); // Automatically includes traceId, spanId, traceFlags
+ * ```
+ *
+ * Log output example:
+ * ```json
+ * {
+ *   "level": 30,
+ *   "time": 1640000000000,
+ *   "msg": "User created",
+ *   "traceId": "13ea7e3c2d3b4547baaa399062df1f2d",
+ *   "spanId": "1234567890123456",
+ *   "traceFlags": 1
+ * }
+ * ```
+ *
+ * @returns Mixin object with trace context or empty object if no active span
+ */
+export declare const createOTELMixin: () => OTELLogContext;
+/**
+ * Extract OTEL context from active span
+ *
+ * Similar to createOTELMixin but returns undefined if no span is active,
+ * making it easier to conditionally add trace context.
+ *
+ * @returns OTEL context or undefined if no active span
+ */
+export declare const getOTELContext: () => OTELLogContext | undefined;
+/**
+ * Extract OTEL context from a specific span
+ *
+ * Useful when you have a reference to a span and want to extract its context
+ * for logging or propagation purposes.
+ *
+ * @param span - The OpenTelemetry span to extract context from
+ * @returns OTEL context from the span
+ */
+export declare const getOTELContextFromSpan: (span: Span) => OTELLogContext;
+/**
+ * Extract OTEL context from an OTEL Context object
+ *
+ * Useful when working with OTEL Context propagation (e.g., in Pub/Sub messages)
+ * and you need to extract the span context for logging.
+ *
+ * @param context - The OpenTelemetry context to extract from
+ * @returns OTEL context from the context or undefined if no span
+ */
+export declare const getOTELContextFromContext: (context: OtelContext) => OTELLogContext | undefined;
+/**
+ * Format trace ID for Cloud Logging
+ *
+ * Cloud Logging expects trace IDs in a specific format:
+ * projects/[PROJECT_ID]/traces/[TRACE_ID]
+ *
+ * This function formats a raw trace ID into the Cloud Logging format.
+ *
+ * @param traceId - Raw trace ID (32-character hex string)
+ * @param projectId - GCP project ID (optional, defaults to GOOGLE_CLOUD_PROJECT env var)
+ * @returns Formatted trace ID for Cloud Logging or undefined if inputs invalid
+ */
+export declare const formatTraceIdForCloudLogging: (traceId?: string, projectId?: string) => string | undefined;
+/**
+ * Create Cloud Logging compatible log entry
+ *
+ * Combines OTEL context with log metadata to create a Cloud Logging compatible
+ * log entry with trace correlation.
+ *
+ * @param message - Log message
+ * @param metadata - Additional log metadata
+ * @param projectId - GCP project ID (optional)
+ * @returns Cloud Logging compatible log entry
+ */
+export declare const createCloudLoggingEntry: (message: string, metadata?: Record<string, any>, projectId?: string) => Record<string, any>;
+/**
+ * Check if OpenTelemetry is available and active
+ *
+ * Useful for conditional OTEL feature usage in libraries and applications.
+ *
+ * @returns true if OTEL is available and there's an active span
+ */
+export declare const isOTELActive: () => boolean;
+/**
+ * Check if OpenTelemetry SDK is installed
+ *
+ * @returns true if @opentelemetry/api is installed
+ */
+export declare const isOTELInstalled: () => boolean;
+//# sourceMappingURL=otel.helper.d.ts.map

package/build/utils/otel.helper.js

@@ -0,0 +1,258 @@
+"use strict";
+/**
+ * OpenTelemetry Helper Utilities
+ *
+ * Provides helper functions for integrating OpenTelemetry with logging systems.
+ * These utilities enable automatic trace/span ID injection into log entries for
+ * correlation with distributed traces in Cloud Logging and other observability platforms.
+ *
+ * @module utils/otel.helper
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isOTELInstalled = exports.isOTELActive = exports.createCloudLoggingEntry = exports.formatTraceIdForCloudLogging = exports.getOTELContextFromContext = exports.getOTELContextFromSpan = exports.getOTELContext = exports.createOTELMixin = void 0;
+// Conditional OpenTelemetry import (optional dependency)
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let trace;
+try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const otelApi = require('@opentelemetry/api');
+    trace = otelApi.trace;
+}
+catch {
+    // OpenTelemetry not installed - helpers will return empty objects
+    trace = null;
+}
+/**
+ * Create Pino mixin for automatic trace/span ID injection
+ *
+ * This function creates a Pino mixin that automatically adds OpenTelemetry
+ * trace and span IDs to every log entry. This enables log-trace correlation
+ * in Cloud Logging and other observability platforms.
+ *
+ * Usage with Pino:
+ * ```typescript
+ * import pino from 'pino';
+ * import { createOTELMixin } from '@noony-serverless/core';
+ *
+ * const logger = pino({
+ *   mixin: createOTELMixin,
+ *   // ... other config
+ * });
+ *
+ * logger.info('User created'); // Automatically includes traceId, spanId, traceFlags
+ * ```
+ *
+ * Log output example:
+ * ```json
+ * {
+ *   "level": 30,
+ *   "time": 1640000000000,
+ *   "msg": "User created",
+ *   "traceId": "13ea7e3c2d3b4547baaa399062df1f2d",
+ *   "spanId": "1234567890123456",
+ *   "traceFlags": 1
+ * }
+ * ```
+ *
+ * @returns Mixin object with trace context or empty object if no active span
+ */
+const createOTELMixin = () => {
+    if (!trace) {
+        return {};
+    }
+    try {
+        const span = trace.getActiveSpan();
+        if (!span) {
+            return {};
+        }
+        const spanContext = span.spanContext();
+        return {
+            traceId: spanContext.traceId,
+            spanId: spanContext.spanId,
+            traceFlags: spanContext.traceFlags,
+        };
+    }
+    catch (error) {
+        // Gracefully handle any errors in trace extraction
+        return {};
+    }
+};
+exports.createOTELMixin = createOTELMixin;
+/**
+ * Extract OTEL context from active span
+ *
+ * Similar to createOTELMixin but returns undefined if no span is active,
+ * making it easier to conditionally add trace context.
+ *
+ * @returns OTEL context or undefined if no active span
+ */
+const getOTELContext = () => {
+    if (!trace) {
+        return undefined;
+    }
+    try {
+        const span = trace.getActiveSpan();
+        if (!span) {
+            return undefined;
+        }
+        const spanContext = span.spanContext();
+        return {
+            traceId: spanContext.traceId,
+            spanId: spanContext.spanId,
+            traceFlags: spanContext.traceFlags,
+        };
+    }
+    catch (error) {
+        return undefined;
+    }
+};
+exports.getOTELContext = getOTELContext;
+/**
+ * Extract OTEL context from a specific span
+ *
+ * Useful when you have a reference to a span and want to extract its context
+ * for logging or propagation purposes.
+ *
+ * @param span - The OpenTelemetry span to extract context from
+ * @returns OTEL context from the span
+ */
+const getOTELContextFromSpan = (span) => {
+    try {
+        const spanContext = span.spanContext();
+        return {
+            traceId: spanContext.traceId,
+            spanId: spanContext.spanId,
+            traceFlags: spanContext.traceFlags,
+        };
+    }
+    catch (error) {
+        return {};
+    }
+};
+exports.getOTELContextFromSpan = getOTELContextFromSpan;
+/**
+ * Extract OTEL context from an OTEL Context object
+ *
+ * Useful when working with OTEL Context propagation (e.g., in Pub/Sub messages)
+ * and you need to extract the span context for logging.
+ *
+ * @param context - The OpenTelemetry context to extract from
+ * @returns OTEL context from the context or undefined if no span
+ */
+const getOTELContextFromContext = (context) => {
+    if (!trace) {
+        return undefined;
+    }
+    try {
+        const span = trace.getSpan(context);
+        if (!span) {
+            return undefined;
+        }
+        const spanContext = span.spanContext();
+        return {
+            traceId: spanContext.traceId,
+            spanId: spanContext.spanId,
+            traceFlags: spanContext.traceFlags,
+        };
+    }
+    catch (error) {
+        return undefined;
+    }
+};
+exports.getOTELContextFromContext = getOTELContextFromContext;
+/**
+ * Format trace ID for Cloud Logging
+ *
+ * Cloud Logging expects trace IDs in a specific format:
+ * projects/[PROJECT_ID]/traces/[TRACE_ID]
+ *
+ * This function formats a raw trace ID into the Cloud Logging format.
+ *
+ * @param traceId - Raw trace ID (32-character hex string)
+ * @param projectId - GCP project ID (optional, defaults to GOOGLE_CLOUD_PROJECT env var)
+ * @returns Formatted trace ID for Cloud Logging or undefined if inputs invalid
+ */
+const formatTraceIdForCloudLogging = (traceId, projectId) => {
+    if (!traceId) {
+        return undefined;
+    }
+    const project = projectId || process.env.GOOGLE_CLOUD_PROJECT || process.env.GCP_PROJECT;
+    if (!project) {
+        return undefined;
+    }
+    return `projects/${project}/traces/${traceId}`;
+};
+exports.formatTraceIdForCloudLogging = formatTraceIdForCloudLogging;
+/**
+ * Create Cloud Logging compatible log entry
+ *
+ * Combines OTEL context with log metadata to create a Cloud Logging compatible
+ * log entry with trace correlation.
+ *
+ * @param message - Log message
+ * @param metadata - Additional log metadata
+ * @param projectId - GCP project ID (optional)
+ * @returns Cloud Logging compatible log entry
+ */
+const createCloudLoggingEntry = (message, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+metadata = {}, projectId
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+) => {
+    const otelContext = (0, exports.getOTELContext)();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const entry = {
+        message,
+        ...metadata,
+    };
+    if (otelContext?.traceId) {
+        entry.traceId = otelContext.traceId;
+        entry.spanId = otelContext.spanId;
+        // Add Cloud Logging trace reference
+        const formattedTrace = (0, exports.formatTraceIdForCloudLogging)(otelContext.traceId, projectId);
+        if (formattedTrace) {
+            entry['logging.googleapis.com/trace'] = formattedTrace;
+        }
+        // Add span ID for Cloud Logging correlation
+        if (otelContext.spanId) {
+            entry['logging.googleapis.com/spanId'] = otelContext.spanId;
+        }
+        // Add trace sampled flag
+        if (otelContext.traceFlags !== undefined) {
+            entry['logging.googleapis.com/trace_sampled'] =
+                (otelContext.traceFlags & 1) === 1;
+        }
+    }
+    return entry;
+};
+exports.createCloudLoggingEntry = createCloudLoggingEntry;
+/**
+ * Check if OpenTelemetry is available and active
+ *
+ * Useful for conditional OTEL feature usage in libraries and applications.
+ *
+ * @returns true if OTEL is available and there's an active span
+ */
+const isOTELActive = () => {
+    if (!trace) {
+        return false;
+    }
+    try {
+        const span = trace.getActiveSpan();
+        return !!span;
+    }
+    catch {
+        return false;
+    }
+};
+exports.isOTELActive = isOTELActive;
+/**
+ * Check if OpenTelemetry SDK is installed
+ *
+ * @returns true if @opentelemetry/api is installed
+ */
+const isOTELInstalled = () => {
+    return !!trace;
+};
+exports.isOTELInstalled = isOTELInstalled;
+//# sourceMappingURL=otel.helper.js.map