@pingops/core 0.1.0 → 0.1.2

package/dist/index.d.mts

@@ -0,0 +1,306 @@
+import { Context } from "@opentelemetry/api";
+import { ReadableSpan } from "@opentelemetry/sdk-trace-base";
+
+//#region src/types.d.ts
+/**
+ * Shared type definitions for PingOps SDK
+ */
+interface DomainRule {
+  domain: string;
+  paths?: string[];
+  headersAllowList?: string[];
+  headersDenyList?: string[];
+  captureRequestBody?: boolean;
+  captureResponseBody?: boolean;
+}
+interface SpanPayload {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+  name: string;
+  kind: string;
+  startTime: string;
+  endTime: string;
+  duration: number;
+  attributes: Record<string, unknown>;
+  status: {
+    code: string;
+    message?: string;
+  };
+}
+/**
+ * Attributes to propagate to HTTP spans
+ */
+interface WrapHttpAttributes {
+  userId?: string;
+  sessionId?: string;
+  tags?: string[];
+  metadata?: Record<string, string>;
+  /**
+   * Whether to capture request body for HTTP spans in this context.
+   * Takes precedence over domain-specific rules and global config.
+   */
+  captureRequestBody?: boolean;
+  /**
+   * Whether to capture response body for HTTP spans in this context.
+   * Takes precedence over domain-specific rules and global config.
+   */
+  captureResponseBody?: boolean;
+}
+//#endregion
+//#region src/filtering/span-filter.d.ts
+/**
+ * Checks if a span is eligible for capture based on span kind and attributes.
+ * A span is eligible if:
+ * 1. span.kind === SpanKind.CLIENT
+ * 2. AND has HTTP attributes (http.method, http.url, or server.address)
+ *    OR has GenAI attributes (gen_ai.system, gen_ai.operation.name)
+ */
+declare function isSpanEligible(span: ReadableSpan): boolean;
+//#endregion
+//#region src/filtering/domain-filter.d.ts
+/**
+ * Determines if a span should be captured based on domain rules
+ */
+declare function shouldCaptureSpan(url: string, domainAllowList?: DomainRule[], domainDenyList?: DomainRule[]): boolean;
+//#endregion
+//#region src/filtering/sensitive-headers.d.ts
+/**
+ * Sensitive header patterns and redaction configuration
+ */
+/**
+ * Default patterns for sensitive headers that should be redacted
+ * These are matched case-insensitively
+ */
+declare const DEFAULT_SENSITIVE_HEADER_PATTERNS: readonly ["authorization", "www-authenticate", "proxy-authenticate", "proxy-authorization", "x-auth-token", "x-api-key", "x-api-token", "x-access-token", "x-auth-user", "x-auth-password", "x-csrf-token", "x-xsrf-token", "api-key", "apikey", "api_key", "access-key", "accesskey", "access_key", "secret-key", "secretkey", "secret_key", "private-key", "privatekey", "private_key", "cookie", "set-cookie", "session-id", "sessionid", "session_id", "session-token", "sessiontoken", "session_token", "oauth-token", "oauth_token", "oauth2-token", "oauth2_token", "bearer", "x-amz-security-token", "x-amz-signature", "x-aws-access-key", "x-aws-secret-key", "x-aws-session-token", "x-password", "x-secret", "x-token", "x-jwt", "x-jwt-token", "x-refresh-token", "x-client-secret", "x-client-id", "x-user-token", "x-service-key"];
+/**
+ * Redaction strategies for sensitive header values
+ */
+declare enum HeaderRedactionStrategy {
+  /**
+   * Replace the entire value with a fixed redaction string
+   */
+  REPLACE = "replace",
+  /**
+   * Show only the first N characters, redact the rest
+   */
+  PARTIAL = "partial",
+  /**
+   * Show only the last N characters, redact the rest
+   */
+  PARTIAL_END = "partial_end",
+  /**
+   * Remove the header entirely (same as deny list)
+   */
+  REMOVE = "remove",
+}
+/**
+ * Configuration for header redaction
+ */
+interface HeaderRedactionConfig {
+  /**
+   * Patterns to match sensitive headers (case-insensitive)
+   * Defaults to DEFAULT_SENSITIVE_HEADER_PATTERNS if not provided
+   */
+  sensitivePatterns?: readonly string[];
+  /**
+   * Redaction strategy to use
+   * @default HeaderRedactionStrategy.REPLACE
+   */
+  strategy?: HeaderRedactionStrategy;
+  /**
+   * Redaction string used when strategy is REPLACE
+   * @default "[REDACTED]"
+   */
+  redactionString?: string;
+  /**
+   * Number of characters to show when strategy is PARTIAL or PARTIAL_END
+   * @default 4
+   */
+  visibleChars?: number;
+  /**
+   * Whether to enable redaction
+   * @default true
+   */
+  enabled?: boolean;
+}
+/**
+ * Default redaction configuration
+ */
+declare const DEFAULT_REDACTION_CONFIG: Required<HeaderRedactionConfig>;
+/**
+ * Checks if a header name matches any sensitive pattern
+ * Uses case-insensitive matching with exact match, prefix/suffix, and substring matching
+ *
+ * @param headerName - The header name to check
+ * @param patterns - Array of patterns to match against (defaults to DEFAULT_SENSITIVE_HEADER_PATTERNS)
+ * @returns true if the header matches any sensitive pattern
+ */
+declare function isSensitiveHeader(headerName: string, patterns?: readonly string[]): boolean;
+/**
+ * Redacts a header value based on the configuration
+ */
+declare function redactHeaderValue(value: string | string[] | undefined, config: Required<HeaderRedactionConfig>): string | string[] | undefined;
+//#endregion
+//#region src/filtering/header-filter.d.ts
+/**
+ * Filters headers based on allow/deny lists and applies redaction to sensitive headers
+ * - Deny list always wins (if header is in deny list, exclude it)
+ * - Allow list filters included headers (if specified, only include these)
+ * - Sensitive headers are redacted after filtering (if redaction is enabled)
+ * - Case-insensitive matching
+ *
+ * @param headers - Headers to filter
+ * @param headersAllowList - Optional allow list of header names to include
+ * @param headersDenyList - Optional deny list of header names to exclude
+ * @param redactionConfig - Optional configuration for header value redaction
+ * @returns Filtered and redacted headers
+ */
+declare function filterHeaders(headers: Record<string, string | string[] | undefined>, headersAllowList?: string[], headersDenyList?: string[], redactionConfig?: HeaderRedactionConfig): Record<string, string | string[] | undefined>;
+/**
+ * Extracts and normalizes headers from OpenTelemetry span attributes
+ *
+ * Handles flat array format headers (e.g., 'http.request.header.0', 'http.request.header.1')
+ * and converts them to proper key-value objects.
+ *
+ * Some OpenTelemetry instrumentations store headers as flat arrays:
+ * - 'http.request.header.0': 'Content-Type'
+ * - 'http.request.header.1': 'application/json'
+ * - 'http.request.header.2': 'Authorization'
+ * - 'http.request.header.3': 'Bearer token'
+ *
+ * This function converts them to:
+ * - { 'Content-Type': 'application/json', 'Authorization': 'Bearer token' }
+ */
+declare function extractHeadersFromAttributes(attributes: Record<string, unknown>, headerPrefix: "http.request.header" | "http.response.header"): Record<string, string | string[] | undefined> | null;
+/**
+ * Normalizes headers from various sources into a proper key-value object
+ */
+declare function normalizeHeaders(headers: unknown): Record<string, string | string[] | undefined>;
+//#endregion
+//#region src/utils/span-extractor.d.ts
+/**
+ * Extracts structured payload from a span
+ */
+declare function extractSpanPayload(span: ReadableSpan, domainAllowList?: DomainRule[], globalHeadersAllowList?: string[], globalHeadersDenyList?: string[], globalCaptureRequestBody?: boolean, globalCaptureResponseBody?: boolean, headerRedaction?: HeaderRedactionConfig): SpanPayload | null;
+//#endregion
+//#region src/utils/context-extractor.d.ts
+/**
+ * Extracts propagated attributes from the given context and returns them
+ * as span attributes that can be set on a span.
+ *
+ * @param parentContext - The OpenTelemetry context to extract attributes from
+ * @returns Record of attribute key-value pairs to set on spans
+ */
+declare function getPropagatedAttributesFromContext(parentContext: Context): Record<string, string | string[]>;
+//#endregion
+//#region src/logger.d.ts
+/**
+ * Global logger utility for PingOps Core
+ *
+ * Provides consistent logging across all core components with support for
+ * different log levels and debug mode control via PINGOPS_DEBUG environment variable.
+ */
+type LogLevel = "debug" | "info" | "warn" | "error";
+interface Logger {
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Creates a logger instance with a specific prefix
+ *
+ * @param prefix - Prefix to add to all log messages (e.g., '[PingOps Filter]')
+ * @returns Logger instance
+ */
+declare function createLogger(prefix: string): Logger;
+//#endregion
+//#region src/context-keys.d.ts
+/**
+ * OpenTelemetry context keys for PingOps
+ */
+/**
+ * Context key for enabling HTTP instrumentation.
+ * When set to true, HTTP requests will be automatically instrumented.
+ * This allows wrapHttp to control which HTTP calls are captured.
+ */
+declare const PINGOPS_HTTP_ENABLED: symbol;
+/**
+ * Context key for user ID attribute.
+ * Used to propagate user identifier to all spans in the context.
+ */
+declare const PINGOPS_USER_ID: symbol;
+/**
+ * Context key for session ID attribute.
+ * Used to propagate session identifier to all spans in the context.
+ */
+declare const PINGOPS_SESSION_ID: symbol;
+/**
+ * Context key for tags attribute.
+ * Used to propagate tags array to all spans in the context.
+ */
+declare const PINGOPS_TAGS: symbol;
+/**
+ * Context key for metadata attribute.
+ * Used to propagate metadata object to all spans in the context.
+ */
+declare const PINGOPS_METADATA: symbol;
+/**
+ * Context key for capturing request body.
+ * When set, controls whether request bodies should be captured for HTTP spans.
+ * This allows wrapHttp to control body capture per-request.
+ */
+declare const PINGOPS_CAPTURE_REQUEST_BODY: symbol;
+/**
+ * Context key for capturing response body.
+ * When set, controls whether response bodies should be captured for HTTP spans.
+ * This allows wrapHttp to control body capture per-request.
+ */
+declare const PINGOPS_CAPTURE_RESPONSE_BODY: symbol;
+//#endregion
+//#region src/wrap-http.d.ts
+/**
+ * Options for wrapHttp function
+ */
+interface WrapHttpOptions {
+  attributes?: WrapHttpAttributes;
+  /**
+   * Callback to check if SDK is initialized.
+   * Required to determine if global instrumentation is enabled.
+   */
+  checkInitialized: () => boolean;
+  /**
+   * Callback to check if global instrumentation is enabled.
+   * Required to determine instrumentation behavior.
+   */
+  isGlobalInstrumentationEnabled: () => boolean;
+  /**
+   * Optional callback to ensure SDK is initialized (auto-initialization).
+   * If not provided, wrapHttp will try to auto-initialize from environment variables.
+   */
+  ensureInitialized?: () => Promise<void>;
+}
+/**
+ * Wraps a function to set attributes on HTTP spans created within the wrapped block.
+ *
+ * This function sets attributes (userId, sessionId, tags, metadata) in the OpenTelemetry
+ * context, which are automatically propagated to all spans created within the wrapped function.
+ *
+ * Instrumentation behavior:
+ * - If `initializePingops` was called: All HTTP requests are instrumented by default.
+ *   `wrapHttp` only adds attributes to spans created within the wrapped block.
+ * - If `initializePingops` was NOT called: Only HTTP requests within `wrapHttp` blocks
+ *   are instrumented. Requests outside `wrapHttp` are not instrumented.
+ *
+ * Note: This is the low-level API. For a simpler API with automatic setup,
+ * use `wrapHttp` from `@pingops/sdk` instead.
+ *
+ * @param options - Options including attributes and required callbacks
+ * @param fn - Function to execute within the attribute context
+ * @returns The result of the function
+ */
+declare function wrapHttp<T>(options: WrapHttpOptions, fn: () => T | Promise<T>): T | Promise<T>;
+//#endregion
+export { DEFAULT_REDACTION_CONFIG, DEFAULT_SENSITIVE_HEADER_PATTERNS, DomainRule, HeaderRedactionConfig, HeaderRedactionStrategy, LogLevel, Logger, PINGOPS_CAPTURE_REQUEST_BODY, PINGOPS_CAPTURE_RESPONSE_BODY, PINGOPS_HTTP_ENABLED, PINGOPS_METADATA, PINGOPS_SESSION_ID, PINGOPS_TAGS, PINGOPS_USER_ID, SpanPayload, WrapHttpAttributes, WrapHttpOptions, createLogger, extractHeadersFromAttributes, extractSpanPayload, filterHeaders, getPropagatedAttributesFromContext, isSensitiveHeader, isSpanEligible, normalizeHeaders, redactHeaderValue, shouldCaptureSpan, wrapHttp };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/filtering/span-filter.ts","../src/filtering/domain-filter.ts","../src/filtering/sensitive-headers.ts","../src/filtering/header-filter.ts","../src/utils/span-extractor.ts","../src/utils/context-extractor.ts","../src/logger.ts","../src/context-keys.ts","../src/wrap-http.ts"],"sourcesContent":[],"mappings":"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"}