/**
 * Trace context helpers - Core primitives for trace correlation
 *
 * These are the building blocks that allow users to bring their own logger
 * (bunyan, log4js, custom, etc.) and add trace correlation.
 *
 * @example Using with bunyan
 * ```typescript
 * import bunyan from 'bunyan';
 * import { enrichWithTraceContext } from 'autotel/trace-helpers';
 *
 * const bunyanLogger = bunyan.createLogger({ name: 'myapp' });
 *
 * const logger = {
 *   info: (msg: string, extra?: object) => {
 *     bunyanLogger.info(enrichWithTraceContext(extra || {}), msg);
 *   }
 * };
 * ```
 *
 * @example Using with log4js
 * ```typescript
 * import log4js from 'log4js';
 * import { getTraceContext } from 'autotel/trace-helpers';
 *
 * const log4jsLogger = log4js.getLogger();
 *
 * function logWithTrace(level: string, msg: string, extra?: object) {
 *   const context = getTraceContext();
 *   log4jsLogger[level](msg, { ...extra, ...context });
 * }
 * ```
 */

import { trace, context, SpanStatusCode } from '@opentelemetry/api';
import type { Span, Tracer, Context } from '@opentelemetry/api';
import { requireModule } from './node-require';

/**
 * WeakMap to store span names for active spans
 * This allows us to retrieve the span name even though OpenTelemetry
 * doesn't expose it through the public API
 */
const spanNameMap = new WeakMap<Span, string>();

/**
 * Store span name for a given span
 * Called internally when spans are created
 */
export function setSpanName(span: Span, name: string): void {
  spanNameMap.set(span, name);
}

/**
 * Trace context extracted from active span
 */
export interface TraceContext {
  /** Full 32-character hex trace ID */
  traceId: string;
  /** 16-character hex span ID */
  spanId: string;
  /** First 16 characters of trace ID (for log grouping/correlation) */
  correlationId: string;
  /** Function/operation name (OpenTelemetry semantic convention: code.function) */
  'code.function'?: string;
  /** Datadog trace ID in decimal format (lower 64 bits) for log-trace correlation */
  'dd.trace_id'?: string;
  /** Datadog span ID in decimal format for log-trace correlation */
  'dd.span_id'?: string;
}

/**
 * Convert hex string to decimal string representation
 * Handles 64-bit unsigned integers for Datadog correlation
 *
 * @param hex - Hex string (up to 16 characters for 64-bit)
 * @returns Decimal string representation
 */
function hexToDecimal(hex: string): string {
  // For 64-bit values, use BigInt to avoid precision loss
  return BigInt('0x' + hex).toString(10);
}

/**
 * Get current trace context from active span
 *
 * Returns null if no span is active (e.g., outside of trace operation)
 *
 * Includes both OpenTelemetry standard fields (hex) and Datadog-specific
 * fields (decimal) for maximum compatibility.
 *
 * @returns Trace context with traceId, spanId, correlationId, and Datadog decimal IDs, or null
 *
 * @example
 * ```typescript
 * import { getTraceContext } from 'autotel/trace-helpers';
 *
 * const context = getTraceContext();
 * if (context) {
 *   console.log('Current trace:', context.traceId);
 *   // Current trace: 4bf92f3577b34da6a3ce929d0e0e4736
 *   console.log('Datadog trace ID:', context['dd.trace_id']);
 *   // Datadog trace ID: 12007117331170166582 (decimal for log correlation)
 * }
 * ```
 */
export function getTraceContext(): TraceContext | null {
  const span = trace.getActiveSpan();
  if (!span) return null;

  const spanContext = span.spanContext();
  const traceId = spanContext.traceId;
  const spanId = spanContext.spanId;

  // Get span name from WeakMap (set when span is created)
  // Map to OpenTelemetry semantic convention: code.function
  const spanName = spanNameMap.get(span);

  // Datadog uses the lower 64 bits of the 128-bit OpenTelemetry trace ID
  // Convert from hex to decimal for Datadog's log-trace correlation
  const traceIdLower64 = traceId.slice(-16); // Last 16 hex chars = lower 64 bits
  const ddTraceId = hexToDecimal(traceIdLower64);
  const ddSpanId = hexToDecimal(spanId);

  return {
    traceId,
    spanId,
    correlationId: traceId.slice(0, 16),
    ...(spanName && { 'code.function': spanName }),
    // Datadog-specific fields for log-trace correlation
    'dd.trace_id': ddTraceId,
    'dd.span_id': ddSpanId,
  };
}

/**
 * Enrich object with trace context (traceId, spanId, correlationId, and Datadog fields)
 *
 * If no span is active, returns the object unchanged.
 * This prevents "undefined" or "null" values in logs.
 *
 * Automatically adds both OpenTelemetry standard fields (hex) and Datadog-specific
 * fields (decimal) for maximum compatibility with observability backends.
 *
 * @param obj - Object to enrich (e.g., log metadata)
 * @returns Object with trace context merged in, or unchanged if no active span
 *
 * @example
 * ```typescript
 * import { enrichWithTraceContext } from 'autotel/trace-helpers';
 *
 * // Inside a trace operation:
 * const enriched = enrichWithTraceContext({ userId: '123' });
 * // {
 * //   userId: '123',
 * //   traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
 * //   spanId: '00f067aa0ba902b7',
 * //   correlationId: '4bf92f3577b34da6',
 * //   'dd.trace_id': '12007117331170166582',  // Datadog decimal format
 * //   'dd.span_id': '67667974448284583'       // Datadog decimal format
 * // }
 *
 * // Outside trace operation:
 * const unchanged = enrichWithTraceContext({ userId: '123' });
 * // { userId: '123' } - no trace fields added
 * ```
 */
export function enrichWithTraceContext<T extends Record<string, unknown>>(
  obj: T,
): T {
  const context = getTraceContext();
  return context ? ({ ...obj, ...context } as T) : obj;
}

/**
 * Check if currently in a trace context
 *
 * Useful for conditional logic based on trace presence
 *
 * @returns true if active span exists, false otherwise
 *
 * @example
 * ```typescript
 * import { isTracing } from 'autotel/trace-helpers';
 *
 * if (isTracing()) {
 *   // Add expensive debug metadata only when tracing
 *   logger.debug('Detailed context', expensiveDebugData());
 * }
 * ```
 */
export function isTracing(): boolean {
  return trace.getActiveSpan() !== undefined;
}

/**
 * Get a tracer instance for creating custom spans
 *
 * Use this when you need low-level control over span lifecycle.
 * For most use cases, prefer trace(), span(), or instrument() instead.
 *
 * @param name - Tracer name (usually your service or module name)
 * @param version - Optional version string
 * @returns OpenTelemetry Tracer instance
 *
 * @example Basic usage
 * ```typescript
 * import { getTracer } from 'autotel';
 *
 * const tracer = getTracer('my-service');
 * const span = tracer.startSpan('custom.operation');
 * try {
 *   // Your logic
 *   span.setAttribute('key', 'value');
 * } finally {
 *   span.end();
 * }
 * ```
 *
 * @example With AI SDK
 * ```typescript
 * import { getTracer } from 'autotel';
 * import { generateText } from 'ai';
 *
 * const tracer = getTracer('ai-agent');
 * const result = await generateText({
 *   model: myModel,
 *   prompt: 'Hello',
 *   experimental_telemetry: {
 *     isEnabled: true,
 *     tracer,
 *   },
 * });
 * ```
 */
export function getTracer(name: string, version?: string): Tracer {
  return trace.getTracer(name, version);
}

/**
 * Get the currently active span
 *
 * Returns undefined if no span is currently active.
 * Useful for adding attributes to the current span.
 *
 * @returns Active span or undefined
 *
 * @example Adding attributes to active span
 * ```typescript
 * import { getActiveSpan } from 'autotel';
 *
 * const span = getActiveSpan();
 * if (span) {
 *   span.setAttribute('user.id', userId);
 *   span.setAttribute('user.action', 'click');
 * }
 * ```
 *
 * @example Checking span status
 * ```typescript
 * import { getActiveSpan, SpanStatusCode } from 'autotel';
 *
 * const span = getActiveSpan();
 * if (span?.isRecording()) {
 *   span.setStatus({ code: SpanStatusCode.OK });
 * }
 * ```
 */
export function getActiveSpan(): Span | undefined {
  return trace.getActiveSpan();
}

/**
 * Get the currently active OpenTelemetry context
 *
 * The context contains the active span and any baggage.
 * Useful for context propagation and custom instrumentation.
 *
 * @returns Current active context
 *
 * @example Propagating context
 * ```typescript
 * import { getActiveContext } from 'autotel';
 *
 * const currentContext = getActiveContext();
 * // Pass context to another function or service
 * ```
 *
 * @example With context injection
 * ```typescript
 * import { getActiveContext, injectTraceContext } from 'autotel';
 *
 * const headers = {};
 * injectTraceContext(headers);
 * // Headers now contain trace propagation data
 * ```
 */
export function getActiveContext(): Context {
  // Check stored context first (from baggage setters), then fall back to active context
  // This ensures ctx.setBaggage() changes are visible to OpenTelemetry operations
  try {
    const { getActiveContextWithBaggage } = requireModule<{
      getActiveContextWithBaggage: () => Context;
    }>('./trace-context');
    return getActiveContextWithBaggage();
  } catch {
    // Fallback if trace-context isn't available
    return context.active();
  }
}

/**
 * Run a function with a specific span set as active
 *
 * This is a convenience wrapper around the two-step process of
 * setting a span in context and running code within that context.
 *
 * @param span - The span to set as active
 * @param fn - Function to execute with the span active
 * @returns The return value of the function
 *
 * @example Running code with a custom span
 * ```typescript
 * import { getTracer, runWithSpan } from 'autotel';
 *
 * const tracer = getTracer('my-service');
 * const span = tracer.startSpan('background.job');
 *
 * try {
 *   const result = await runWithSpan(span, async () => {
 *     // Any spans created here will be children of 'background.job'
 *     await processData();
 *     return { success: true };
 *   });
 *   console.log(result);
 * } finally {
 *   span.end();
 * }
 * ```
 *
 * @example Testing with custom spans
 * ```typescript
 * import { runWithSpan, otelTrace } from 'autotel';
 *
 * const tracer = otelTrace.getTracer('test');
 * const span = tracer.startSpan('test.operation');
 *
 * const result = runWithSpan(span, () => {
 *   // Code under test runs with this span as active
 *   return myFunction();
 * });
 *
 * span.end();
 * ```
 */
export function runWithSpan<T>(span: Span, fn: () => T): T {
  const ctx = trace.setSpan(context.active(), span);
  return context.with(ctx, fn);
}

/**
 * Finalize a span with appropriate status and optional error recording
 *
 * This is a convenience function that:
 * - Records exceptions if an error is provided
 * - Sets span status to ERROR if error exists, OK otherwise
 * - Ends the span
 *
 * @param span - The span to finalize
 * @param error - Optional error to record
 *
 * @example Without error (success case)
 * ```typescript
 * import { getTracer, finalizeSpan } from 'autotel';
 *
 * const tracer = getTracer('my-service');
 * const span = tracer.startSpan('operation');
 *
 * try {
 *   await doWork();
 *   finalizeSpan(span);
 * } catch (error) {
 *   finalizeSpan(span, error);
 *   throw error;
 * }
 * ```
 *
 * @example With error
 * ```typescript
 * import { getTracer, finalizeSpan } from 'autotel';
 *
 * const tracer = getTracer('my-service');
 * const span = tracer.startSpan('operation');
 *
 * try {
 *   await riskyOperation();
 *   finalizeSpan(span);
 * } catch (error) {
 *   finalizeSpan(span, error); // Records exception and sets ERROR status
 *   throw error;
 * }
 * ```
 *
 * @example In instrumentation
 * ```typescript
 * import { getTracer, runWithSpan, finalizeSpan } from 'autotel';
 *
 * function instrumentedQuery(query: string) {
 *   const tracer = getTracer('db');
 *   const span = tracer.startSpan('db.query');
 *
 *   return runWithSpan(span, () => {
 *     try {
 *       const result = executeQuery(query);
 *       finalizeSpan(span);
 *       return result;
 *     } catch (error) {
 *       finalizeSpan(span, error);
 *       throw error;
 *     }
 *   });
 * }
 * ```
 */
export function finalizeSpan(span: Span, error?: unknown): void {
  if (error) {
    if (error instanceof Error) {
      span.recordException(error);
    } else {
      span.recordException(new Error(String(error)));
    }
    span.setStatus({ code: SpanStatusCode.ERROR });
  } else {
    span.setStatus({ code: SpanStatusCode.OK });
  }
  span.end();
}

/**
 * Creates a deterministic trace ID from a seed string.
 *
 * Generates a consistent 128-bit trace ID (32 hex characters) from an input seed
 * using SHA-256 hashing. Useful for correlating external system IDs (request IDs,
 * order IDs, session IDs) with OpenTelemetry trace IDs.
 *
 * **Use Cases:**
 * - Correlate external request IDs with traces
 * - Link customer support tickets to trace data
 * - Associate business entities (orders, sessions) with observability data
 * - Debug specific user flows by deterministic trace lookup
 *
 * **Important:** Only use this when you need deterministic trace IDs for correlation.
 * For normal tracing, let OpenTelemetry generate random trace IDs automatically.
 *
 * **Runtime Support:**
 * - Node.js 15+ (native crypto.subtle)
 * - All modern browsers
 * - Edge runtimes (Cloudflare Workers, Deno, etc.)
 *
 * @param seed - Input string to generate trace ID from (e.g., request ID, order ID)
 * @returns Promise resolving to a 32-character hex trace ID (128 bits)
 *
 * @example Correlate external request ID with trace
 * ```typescript
 * import { createDeterministicTraceId } from 'autotel/trace-helpers'
 * import { trace, context } from '@opentelemetry/api'
 *
 * // In middleware or request handler
 * const requestId = req.headers['x-request-id']
 * const traceId = await createDeterministicTraceId(requestId)
 *
 * // Use with manual span creation (advanced - not needed with trace/span functions)
 * const tracer = trace.getTracer('my-service')
 * const spanContext = {
 *   traceId,
 *   spanId: '0123456789abcdef', // Still random
 *   traceFlags: 1
 * }
 * ```
 *
 * @example Link customer support tickets to traces
 * ```typescript
 * import { createDeterministicTraceId } from 'autotel/trace-helpers'
 *
 * // Support dashboard integration
 * const ticketId = 'TICKET-12345'
 * const traceId = await createDeterministicTraceId(ticketId)
 *
 * // Generate direct link to traces in observability backend
 * const traceUrl = `https://your-otel-backend.com/traces/${traceId}`
 * console.log(`View related traces: ${traceUrl}`)
 * ```
 *
 * @example Session-based correlation
 * ```typescript
 * import { createDeterministicTraceId } from 'autotel/trace-helpers'
 *
 * // Track all operations for a user session
 * const sessionId = req.session.id
 * const traceId = await createDeterministicTraceId(sessionId)
 *
 * // All operations in this session share the same trace ID
 * // Makes it easy to find all activity for a specific session
 * ```
 *
 * @public
 */
export async function createDeterministicTraceId(
  seed: string,
): Promise<string> {
  // Encode seed string to bytes
  const encoder = new TextEncoder();
  const data = encoder.encode(seed);

  // Generate SHA-256 hash (256 bits)
  const hashBuffer = await crypto.subtle.digest('SHA-256', data);

  // Convert to hex string and truncate to 32 characters (128 bits)
  // OpenTelemetry trace IDs are 128 bits (16 bytes, 32 hex characters)
  const hashArray = new Uint8Array(hashBuffer);
  return [...hashArray]
    .map((byte) => byte.toString(16).padStart(2, '0'))
    .join('')
    .slice(0, 32);
}

/**
 * Flattens nested metadata objects into dot-notation span attributes.
 *
 * Converts complex nested objects into flat key-value pairs suitable for
 * OpenTelemetry span attributes. Non-string values are JSON serialized.
 * Handles serialization failures gracefully with a fallback value.
 *
 * **Use Cases:**
 * - Structured metadata with nested objects
 * - User context with multiple properties
 * - Request/response metadata
 * - Business entity attributes
 *
 * **Note:** Filters out null/undefined values automatically to keep spans clean.
 *
 * @param metadata - Nested metadata object to flatten
 * @param prefix - Prefix for all attribute keys (default: 'metadata')
 * @returns Flattened attributes as { [key: string]: string }
 *
 * @example Basic metadata flattening
 * ```typescript
 * import { flattenMetadata } from 'autotel/trace-helpers'
 * import { trace } from 'autotel'
 *
 * export const processOrder = trace(ctx => async (orderId: string) => {
 *   const order = await getOrder(orderId)
 *
 *   // Flatten complex order metadata
 *   const flattened = flattenMetadata({
 *     user: { id: order.userId, tier: 'premium' },
 *     payment: { method: 'card', processor: 'stripe' },
 *     items: order.items.length
 *   })
 *
 *   ctx.setAttributes(flattened)
 *   // Results in:
 *   // {
 *   //   'metadata.user.id': 'user-123',
 *   //   'metadata.user.tier': 'premium',
 *   //   'metadata.payment.method': 'card',
 *   //   'metadata.payment.processor': 'stripe',
 *   //   'metadata.items': '5'
 *   // }
 * })
 * ```
 *
 * @example Custom prefix for semantic conventions
 * ```typescript
 * import { flattenMetadata } from 'autotel/trace-helpers'
 * import { trace } from 'autotel'
 *
 * export const fetchUser = trace(ctx => async (userId: string) => {
 *   const user = await db.users.findOne({ id: userId })
 *
 *   // Use semantic convention prefix
 *   const userAttrs = flattenMetadata(
 *     {
 *       id: user.id,
 *       email: user.email,
 *       plan: user.subscription.plan
 *     },
 *     'user'  // Custom prefix
 *   )
 *
 *   ctx.setAttributes(userAttrs)
 *   // Results in:
 *   // {
 *   //   'user.id': 'user-123',
 *   //   'user.email': 'user@example.com',
 *   //   'user.plan': 'enterprise'
 *   // }
 * })
 * ```
 *
 * @example With complex objects (auto-serialized)
 * ```typescript
 * import { flattenMetadata } from 'autotel/trace-helpers'
 * import { trace } from 'autotel'
 *
 * export const analyzeRequest = trace(ctx => async (req: Request) => {
 *   const metadata = flattenMetadata({
 *     headers: req.headers,  // Object - will be JSON serialized
 *     query: req.query,       // Object - will be JSON serialized
 *     timestamp: new Date()   // Non-string - will be JSON serialized
 *   })
 *
 *   ctx.setAttributes(metadata)
 *   // Results in:
 *   // {
 *   //   'metadata.headers': '{"accept":"application/json",...}',
 *   //   'metadata.query': '{"page":"1","limit":"10"}',
 *   //   'metadata.timestamp': '"2024-01-15T12:00:00.000Z"'
 *   // }
 * })
 * ```
 *
 * @example Error handling
 * ```typescript
 * import { flattenMetadata } from 'autotel/trace-helpers'
 *
 * // Objects with circular references are handled gracefully
 * const circular: any = { a: 1 }
 * circular.self = circular
 *
 * const flattened = flattenMetadata({ data: circular })
 * // Results in:
 * // { 'metadata.data': '<serialization-failed>' }
 * ```
 *
 * @public
 */
/**
 * Resolve a trace URL from a template string and trace ID.
 *
 * Templates use `{traceId}` as placeholder. Falls back to `OTEL_TRACE_URL_TEMPLATE` env var.
 *
 * @example
 * resolveTraceUrl('https://grafana.example.com/explore?traceId={traceId}', 'abc123')
 * // => 'https://grafana.example.com/explore?traceId=abc123'
 */
export function resolveTraceUrl(
  template: string | undefined,
  traceId: string,
): string | undefined {
  const t = template ?? process.env.OTEL_TRACE_URL_TEMPLATE;
  if (!t) return undefined;
  return t.replace(/\{traceId\}/g, traceId);
}

export function flattenMetadata(
  metadata: Record<string, unknown>,
  prefix = 'metadata',
): Record<string, string> {
  const flattened: Record<string, string> = {};
  const seen = new WeakSet<object>(); // Track visited objects to detect cycles

  function flatten(obj: Record<string, unknown>, currentPrefix: string): void {
    for (const [key, value] of Object.entries(obj)) {
      // Skip null/undefined values
      if (value == null) continue;

      const attributeKey = `${currentPrefix}.${key}`;

      // Handle primitives directly (string, number, boolean)
      if (typeof value === 'string') {
        flattened[attributeKey] = value;
        continue;
      }
      if (typeof value === 'number' || typeof value === 'boolean') {
        flattened[attributeKey] = String(value);
        continue;
      }

      // Recursively flatten plain objects (with cycle detection)
      if (
        typeof value === 'object' &&
        value !== null &&
        value.constructor === Object
      ) {
        // Detect circular references
        if (seen.has(value)) {
          flattened[attributeKey] = '<circular-reference>';
          continue;
        }

        // Mark as visited and recursively flatten
        seen.add(value);
        flatten(value as Record<string, unknown>, attributeKey);
        continue;
      }

      // Serialize arrays and other non-plain objects to JSON
      try {
        flattened[attributeKey] = JSON.stringify(value);
      } catch {
        // Handle circular references or non-serializable objects
        flattened[attributeKey] = '<serialization-failed>';
      }
    }
  }

  flatten(metadata, prefix);
  return flattened;
}