@vtvlive/interactive-apm 0.0.2 → 0.0.4

package/dist/types/apm.types.d.ts

@@ -0,0 +1,162 @@
+/**
+ * APM Common Types
+ *
+ * Defines common types that work with both Elastic APM and OpenTelemetry providers.
+ * This provides type safety and IntelliSense for users of this package.
+ */
+/**
+ * Common Span interface - works with both Elastic APM and OpenTelemetry
+ */
+export interface ISpan {
+    /** Span name */
+    name: string;
+    /** End the span */
+    end(): void;
+    /** Set an attribute on the span */
+    setAttribute(key: string, value: string | number | boolean | string[] | undefined): void;
+    /** Add an event to the span */
+    addEvent?(name: string, attributes?: Record<string, unknown>): void;
+    /** Set the span status */
+    setStatus?(status: SpanStatus): void;
+    /** Record an exception on the span */
+    recordException?(error: Error | unknown): void;
+}
+/**
+ * Span status
+ */
+export interface SpanStatus {
+    code: number;
+    message?: string;
+}
+/**
+ * Common Tracer interface
+ */
+export interface ITracer {
+    /** Start a new span */
+    startSpan(name: string, options?: SpanOptions): ISpan;
+    /** Get the currently active span */
+    getActiveSpan?(): ISpan | undefined;
+    /** Start a span with a parent context */
+    startSpanWithParent?<T>(name: string, fn: (span: ISpan) => Promise<T> | T, options?: SpanOptions): Promise<T>;
+}
+/**
+ * Span options
+ */
+export interface SpanOptions {
+    /** Span attributes */
+    attributes?: Record<string, string | number | boolean>;
+    /** Span kind (server, client, internal, etc.) */
+    kind?: SpanKind;
+    /** Parent span context */
+    parent?: ISpan;
+}
+/**
+ * Span kind enumeration
+ */
+export declare enum SpanKind {
+    INTERNAL = 0,
+    SERVER = 1,
+    CLIENT = 2,
+    PRODUCER = 3,
+    CONSUMER = 4
+}
+/**
+ * Common APM Provider configuration
+ */
+export interface IApmProviderConfig {
+    /** Service name */
+    serviceName?: string;
+    /** Environment (development, staging, production) */
+    environment?: string;
+    /** Secret token for authentication */
+    secretToken?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Elastic APM specific configuration
+ */
+export interface IElasticApmConfig extends IApmProviderConfig {
+    /** APM server URL */
+    serverUrl?: string;
+    /** Secret token */
+    secretToken?: string;
+    /** API key */
+    apiKey?: string;
+    /** Server timeout in milliseconds */
+    serverTimeout?: number;
+    /** Disable instrumentations */
+    disableInstrumentations?: string[];
+}
+/**
+ * OpenTelemetry specific configuration
+ */
+export interface IOpenTelemetryConfig extends IApmProviderConfig {
+    /** OTLP endpoint URL */
+    otlpEndpoint?: string;
+    /** OTLP transport type (http, grpc, proto) */
+    otlpTransport?: OtlpTransport | string;
+    /** OTLP auth token */
+    otlpAuthToken?: string;
+    /** OTLP headers */
+    otlpHeaders?: Record<string, string>;
+    /** Enable console exporter */
+    enableConsoleExporter?: boolean;
+}
+/**
+ * OTLP Transport types
+ */
+export declare enum OtlpTransport {
+    HTTP = "http",
+    GRPC = "grpc",
+    PROTO = "proto"
+}
+/**
+ * OTLP Transport type string
+ */
+export type OtlpTransportType = `${OtlpTransport}`;
+/**
+ * APM Provider types
+ */
+export declare enum ApmProvider {
+    ELASTIC = "elastic-apm",
+    OPENTELEMETRY = "opentelemetry"
+}
+/**
+ * APM Provider type string
+ */
+export type ApmProviderType = `${ApmProvider}`;
+/**
+ * Export result from span export
+ */
+export interface IExportResult {
+    /** Export status code (0 = success, non-zero = error) */
+    code: number;
+    /** Error if export failed */
+    error?: Error;
+}
+/**
+ * Span processor interface
+ */
+export interface ISpanProcessor {
+    /** Called when a span is started */
+    onStart(span: ISpan, parentContext?: unknown): void;
+    /** Called when a span is ended */
+    onEnd(span: ISpan): void;
+    /** Force flush any pending spans */
+    forceFlush(): Promise<void>;
+    /** Shutdown the processor */
+    shutdown(): Promise<void>;
+}
+/**
+ * Span exporter interface
+ */
+export interface ISpanExporter {
+    /** Export spans */
+    export(spans: ISpan[], callback: (result: IExportResult) => void): void;
+    /** Shutdown the exporter */
+    shutdown(): Promise<void>;
+    /** Force flush (optional) */
+    forceFlush?(): Promise<void>;
+}
+//# sourceMappingURL=apm.types.d.ts.map

package/dist/types/apm.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apm.types.d.ts","sourceRoot":"","sources":["../../src/types/apm.types.ts"],"names":[],"mappings":"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"}

package/dist/types/apm.types.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * APM Common Types
+ *
+ * Defines common types that work with both Elastic APM and OpenTelemetry providers.
+ * This provides type safety and IntelliSense for users of this package.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApmProvider = exports.OtlpTransport = exports.SpanKind = void 0;
+/**
+ * Span kind enumeration
+ */
+var SpanKind;
+(function (SpanKind) {
+    SpanKind[SpanKind["INTERNAL"] = 0] = "INTERNAL";
+    SpanKind[SpanKind["SERVER"] = 1] = "SERVER";
+    SpanKind[SpanKind["CLIENT"] = 2] = "CLIENT";
+    SpanKind[SpanKind["PRODUCER"] = 3] = "PRODUCER";
+    SpanKind[SpanKind["CONSUMER"] = 4] = "CONSUMER";
+})(SpanKind || (exports.SpanKind = SpanKind = {}));
+/**
+ * OTLP Transport types
+ */
+var OtlpTransport;
+(function (OtlpTransport) {
+    OtlpTransport["HTTP"] = "http";
+    OtlpTransport["GRPC"] = "grpc";
+    OtlpTransport["PROTO"] = "proto";
+})(OtlpTransport || (exports.OtlpTransport = OtlpTransport = {}));
+/**
+ * APM Provider types
+ */
+var ApmProvider;
+(function (ApmProvider) {
+    ApmProvider["ELASTIC"] = "elastic-apm";
+    ApmProvider["OPENTELEMETRY"] = "opentelemetry";
+})(ApmProvider || (exports.ApmProvider = ApmProvider = {}));

package/dist/types/otlp-transport.type.d.ts

@@ -0,0 +1,14 @@
+/**
+ * OTLP Transport Type
+ *
+ * Defines the transport protocol used for exporting traces to APM
+ * - HTTP: Uses HTTP/JSON protocol (@opentelemetry/exporter-trace-otlp-http)
+ * - GRPC: Uses gRPC/protobuf protocol (@opentelemetry/exporter-trace-otlp-grpc)
+ * - PROTO: Uses protobuf over HTTP (@opentelemetry/exporter-trace-otlp-proto) - recommended for Elastic APM
+ */
+export declare enum OtlpTransport {
+    HTTP = "http",
+    GRPC = "grpc",
+    PROTO = "proto"
+}
+//# sourceMappingURL=otlp-transport.type.d.ts.map

package/dist/types/otlp-transport.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlp-transport.type.d.ts","sourceRoot":"","sources":["../../src/types/otlp-transport.type.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,oBAAY,aAAa;IACvB,IAAI,SAAS;IACb,IAAI,SAAS;IACb,KAAK,UAAU;CAChB"}

package/dist/types/otlp-transport.type.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OtlpTransport = void 0;
+/**
+ * OTLP Transport Type
+ *
+ * Defines the transport protocol used for exporting traces to APM
+ * - HTTP: Uses HTTP/JSON protocol (@opentelemetry/exporter-trace-otlp-http)
+ * - GRPC: Uses gRPC/protobuf protocol (@opentelemetry/exporter-trace-otlp-grpc)
+ * - PROTO: Uses protobuf over HTTP (@opentelemetry/exporter-trace-otlp-proto) - recommended for Elastic APM
+ */
+var OtlpTransport;
+(function (OtlpTransport) {
+    OtlpTransport["HTTP"] = "http";
+    OtlpTransport["GRPC"] = "grpc";
+    OtlpTransport["PROTO"] = "proto";
+})(OtlpTransport || (exports.OtlpTransport = OtlpTransport = {}));

package/dist/utils/debug-exporter-wrapper.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Debug Exporter Wrapper for OpenTelemetry OTLP
+ *
+ * Wraps the OTLPTraceExporter to log full request/response details
+ * when APM_DEBUG=true. This helps debug connection issues with APM servers.
+ */
+/**
+ * Wrap OTLPTraceExporter with debug logging
+ *
+ * This intercepts the export calls to log:
+ * - Outgoing request details (URL, headers, body)
+ * - Response details (status code, headers, body)
+ * - Success/failure of exports
+ *
+ * @param baseExporter The original OTLPTraceExporter instance
+ * @param endpointUrl The OTLP endpoint URL for logging
+ * @returns Wrapped exporter with debug capabilities
+ */
+export declare function createDebugExporter(baseExporter: {
+    export(spans: unknown[], callback: (result: unknown) => void): void;
+    shutdown(): Promise<void>;
+    forceFlush?(): Promise<void>;
+}, endpointUrl: string): {
+    export(spans: unknown[], callback: (result: unknown) => void): void;
+    shutdown(): Promise<void>;
+    forceFlush?(): Promise<void>;
+};
+/**
+ * Create an HTTP interceptor for more detailed debugging
+ * This can be used to intercept the actual HTTP requests made by OTLP exporter
+ */
+export declare function createHttpRequestInterceptor(): {
+    install(): void;
+    uninstall(): void;
+} | null;
+//# sourceMappingURL=debug-exporter-wrapper.d.ts.map

package/dist/utils/debug-exporter-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-exporter-wrapper.d.ts","sourceRoot":"","sources":["../../src/utils/debug-exporter-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE;IACZ,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IACpE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,EACD,WAAW,EAAE,MAAM,GAClB;IACD,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IACpE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,CA6FA;AAyBD;;;GAGG;AACH,wBAAgB,4BAA4B,IAAI;IAC9C,OAAO,IAAI,IAAI,CAAC;IAChB,SAAS,IAAI,IAAI,CAAC;CACnB,GAAG,IAAI,CAwKP"}

package/dist/utils/debug-exporter-wrapper.js

@@ -0,0 +1,247 @@
+"use strict";
+/**
+ * Debug Exporter Wrapper for OpenTelemetry OTLP
+ *
+ * Wraps the OTLPTraceExporter to log full request/response details
+ * when APM_DEBUG=true. This helps debug connection issues with APM servers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDebugExporter = createDebugExporter;
+exports.createHttpRequestInterceptor = createHttpRequestInterceptor;
+const debug_logger_1 = require("./debug-logger");
+/**
+ * Wrap OTLPTraceExporter with debug logging
+ *
+ * This intercepts the export calls to log:
+ * - Outgoing request details (URL, headers, body)
+ * - Response details (status code, headers, body)
+ * - Success/failure of exports
+ *
+ * @param baseExporter The original OTLPTraceExporter instance
+ * @param endpointUrl The OTLP endpoint URL for logging
+ * @returns Wrapped exporter with debug capabilities
+ */
+function createDebugExporter(baseExporter, endpointUrl) {
+    if (!(0, debug_logger_1.isDebugEnabled)()) {
+        // When debug is off, just log errors only
+        return {
+            export: (spans, resultCallback) => {
+                baseExporter.export(spans, (result) => {
+                    const exportResult = result;
+                    if (exportResult.error) {
+                        (0, debug_logger_1.logExportFailure)("OpenTelemetry", exportResult.error);
+                    }
+                    resultCallback(result);
+                });
+            },
+            shutdown: async () => {
+                await baseExporter.shutdown();
+            },
+            forceFlush: async () => {
+                if (baseExporter.forceFlush) {
+                    await baseExporter.forceFlush();
+                }
+            },
+        };
+    }
+    // Debug mode ON - intercept everything
+    const wrappedExporter = {
+        export: (spans, resultCallback) => {
+            const startTime = Date.now();
+            // Log what we're about to send
+            (0, debug_logger_1.logRequest)("OpenTelemetry", endpointUrl, getExporterHeaders(baseExporter), {
+                spanCount: spans.length,
+                spans: spans.map((s) => {
+                    const span = s;
+                    return {
+                        name: span.name,
+                        kind: span.kind,
+                        startTime: span.startTime,
+                        endTime: span.endTime,
+                    };
+                }),
+            });
+            // Wrap the result callback to capture response
+            baseExporter.export(spans, (result) => {
+                const duration = Date.now() - startTime;
+                const exportResult = result;
+                if (exportResult.error) {
+                    (0, debug_logger_1.logExportFailure)("OpenTelemetry", exportResult.error, {
+                        endpoint: endpointUrl,
+                        spanCount: spans.length,
+                        duration: `${duration}ms`,
+                    });
+                }
+                else {
+                    (0, debug_logger_1.logExportSuccess)("OpenTelemetry", spans.length);
+                    (0, debug_logger_1.logResponse)("OpenTelemetry", 200, { "content-type": "application/json" }, {
+                        message: `Exported ${spans.length} span(s) in ${duration}ms`,
+                    });
+                }
+                resultCallback(result);
+            });
+        },
+        shutdown: async () => {
+            (0, debug_logger_1.logRequest)("OpenTelemetry", endpointUrl, {}, { action: "shutdown" });
+            try {
+                await baseExporter.shutdown();
+                (0, debug_logger_1.logResponse)("OpenTelemetry", 200, {}, { message: "Exporter shutdown complete" });
+            }
+            catch (err) {
+                const errorMessage = err instanceof Error ? err.message : String(err);
+                (0, debug_logger_1.logResponse)("OpenTelemetry", 500, {}, { message: "Exporter shutdown failed", error: errorMessage });
+                throw err;
+            }
+        },
+        forceFlush: async () => {
+            if (baseExporter.forceFlush) {
+                await baseExporter.forceFlush();
+            }
+        },
+    };
+    return wrappedExporter;
+}
+/**
+ * Get headers from the exporter instance for logging
+ * The OTLPTraceExporter stores headers internally, we need to extract them
+ */
+function getExporterHeaders(exporter) {
+    try {
+        // Try to access headers from the exporter
+        // @ts-ignore - accessing internal property
+        if (exporter._headers) {
+            // @ts-ignore
+            return { ...exporter._headers };
+        }
+        // @ts-ignore - alternative internal property
+        if (exporter.headers) {
+            // @ts-ignore
+            return { ...exporter.headers };
+        }
+    }
+    catch {
+        // Silently fail if we can't access headers
+    }
+    return {};
+}
+/**
+ * Create an HTTP interceptor for more detailed debugging
+ * This can be used to intercept the actual HTTP requests made by OTLP exporter
+ */
+function createHttpRequestInterceptor() {
+    if (!(0, debug_logger_1.isDebugEnabled)()) {
+        return null;
+    }
+    const originalRequest = require("http").request;
+    const originalHttpsRequest = require("https").request;
+    return {
+        install: () => {
+            const { logRequest: logReq, logResponse: logResp } = require("./debug-logger");
+            // Override http.request
+            require("http").request = function (options, ...args) {
+                const opts = typeof options === "string" ? undefined : options;
+                let url;
+                if (typeof options === "string") {
+                    url = options;
+                }
+                else {
+                    const protocol = opts?.protocol || "http:";
+                    const hostname = opts?.hostname || opts?.host || "localhost";
+                    const port = opts?.port;
+                    const path = opts?.path || "/";
+                    // Build URL with port if specified
+                    const hostWithPort = port ? `${hostname}:${port}` : hostname;
+                    url = `${protocol}//${hostWithPort}${path}`;
+                }
+                // Only intercept APM-related requests
+                if (url.includes("/v1/traces") ||
+                    url.includes("/v1/metrics") ||
+                    url.includes("/intake/v2/traces")) {
+                    const req = originalRequest.call(this, options, ...args);
+                    const originalWrite = req.write.bind(req);
+                    req.write = function (chunk, ...rest) {
+                        // Handle binary data safely - don't stringify protobuf/binary payloads
+                        let logData;
+                        if (Buffer.isBuffer(chunk) || chunk instanceof Uint8Array) {
+                            logData = `<binary data: ${chunk.length} bytes>`;
+                        }
+                        else if (typeof chunk === "string") {
+                            logData = chunk;
+                        }
+                        else {
+                            logData = chunk?.toString();
+                        }
+                        logReq("OpenTelemetry", url, typeof opts === "object" ? (opts.headers || {}) : {}, logData);
+                        return originalWrite(chunk, ...rest);
+                    };
+                    req.on("response", (res) => {
+                        let body = "";
+                        res.on("data", (chunk) => {
+                            body += chunk;
+                        });
+                        res.on("end", () => {
+                            logResp("OpenTelemetry", res.statusCode, res.headers, body);
+                        });
+                    });
+                    return req;
+                }
+                return originalRequest.call(this, options, ...args);
+            };
+            // Override https.request
+            require("https").request = function (options, ...args) {
+                const opts = typeof options === "string" ? undefined : options;
+                let url;
+                if (typeof options === "string") {
+                    url = options;
+                }
+                else {
+                    const protocol = opts?.protocol || "https:";
+                    const hostname = opts?.hostname || opts?.host || "localhost";
+                    const port = opts?.port;
+                    const path = opts?.path || "/";
+                    // Build URL with port if specified
+                    const hostWithPort = port ? `${hostname}:${port}` : hostname;
+                    url = `${protocol}//${hostWithPort}${path}`;
+                }
+                // Only intercept APM-related requests
+                if (url.includes("/v1/traces") ||
+                    url.includes("/v1/metrics") ||
+                    url.includes("/intake/v2/traces")) {
+                    const req = originalHttpsRequest.call(this, options, ...args);
+                    const originalWrite = req.write.bind(req);
+                    req.write = function (chunk, ...rest) {
+                        // Handle binary data safely - don't stringify protobuf/binary payloads
+                        let logData;
+                        if (Buffer.isBuffer(chunk) || chunk instanceof Uint8Array) {
+                            logData = `<binary data: ${chunk.length} bytes>`;
+                        }
+                        else if (typeof chunk === "string") {
+                            logData = chunk;
+                        }
+                        else {
+                            logData = chunk?.toString();
+                        }
+                        logReq("OpenTelemetry", url, typeof opts === "object" ? (opts.headers || {}) : {}, logData);
+                        return originalWrite(chunk, ...rest);
+                    };
+                    req.on("response", (res) => {
+                        let body = "";
+                        res.on("data", (chunk) => {
+                            body += chunk;
+                        });
+                        res.on("end", () => {
+                            logResp("OpenTelemetry", res.statusCode, res.headers, body);
+                        });
+                    });
+                    return req;
+                }
+                return originalHttpsRequest.call(this, options, ...args);
+            };
+        },
+        uninstall: () => {
+            // Restore original functions
+            require("http").request = originalRequest;
+            require("https").request = originalHttpsRequest;
+        },
+    };
+}

package/dist/utils/debug-logger.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Debug Logger for APM Package
+ *
+ * Provides centralized debug logging that only outputs when APM_DEBUG=true.
+ * Used by both Elastic APM and OpenTelemetry providers.
+ */
+/**
+ * Represents a span for logging purposes
+ */
+interface LogSpan {
+    name: string;
+    kind: number;
+    startTime: number;
+    endTime: number;
+    attributes?: Record<string, unknown>;
+    status?: unknown;
+}
+/**
+ * Configuration object for APM providers
+ */
+type ApmConfig = Record<string, unknown> | unknown[];
+/**
+ * Request details for export failure logging
+ */
+interface ExportFailureDetails {
+    endpoint?: string;
+    spanCount?: number;
+    duration?: string;
+    [key: string]: unknown;
+}
+/**
+ * Check if debug mode is enabled via environment variable
+ */
+export declare function isDebugEnabled(): boolean;
+/**
+ * Sanitize headers for logging (mask sensitive values)
+ */
+export declare function sanitizeHeaders(headers: Record<string, string>): Record<string, string>;
+/**
+ * Sanitize config object for logging (mask sensitive values)
+ * Handles arrays and circular references safely
+ */
+export declare function sanitizeConfig<T extends ApmConfig>(config: T, seen?: WeakMap<object, unknown>): T;
+/**
+ * Debug log - only outputs when APM_DEBUG=true
+ */
+export declare function debugLog(message: string, ...args: unknown[]): void;
+/**
+ * Info log - always outputs
+ */
+export declare function infoLog(message: string, ...args: unknown[]): void;
+/**
+ * Error log - always outputs
+ */
+export declare function errorLog(message: string, ...args: unknown[]): void;
+/**
+ * Log initialization details
+ */
+export declare function logInitialization(provider: string, config: ApmConfig): void;
+/**
+ * Log span export success (debug mode only)
+ */
+export declare function logExportSuccess(provider: string, spanCount: number): void;
+/**
+ * Log span export failure - ALWAYS logs regardless of debug mode
+ */
+export declare function logExportFailure(provider: string, error: Error | unknown, requestDetails?: ExportFailureDetails): void;
+/**
+ * Log outgoing HTTP request (for debugging APM communication)
+ */
+export declare function logRequest(provider: string, url: string, headers: Record<string, string>, body?: unknown): void;
+/**
+ * Log incoming HTTP response (for debugging APM communication)
+ */
+export declare function logResponse(provider: string, statusCode: number, headers: Record<string, string>, body?: unknown): void;
+/**
+ * Log span details (when debug mode is on)
+ */
+export declare function logSpan(provider: string, span: LogSpan): void;
+export {};
+//# sourceMappingURL=debug-logger.d.ts.map

package/dist/utils/debug-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-logger.d.ts","sourceRoot":"","sources":["../../src/utils/debug-logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,UAAU,OAAO;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,EAAE,CAAC;AAErD;;GAEG;AACH,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAwBD;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMvF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,SAAS,EAChD,MAAM,EAAE,CAAC,EACT,IAAI,GAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAiB,GAC7C,CAAC,CA8CH;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAIlE;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAEjE;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAElE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAsB3E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAI1E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,KAAK,GAAG,OAAO,EACtB,cAAc,CAAC,EAAE,oBAAoB,GACpC,IAAI,CASN;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,IAAI,CAAC,EAAE,OAAO,GACb,IAAI,CA8BN;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,IAAI,CAAC,EAAE,OAAO,GACb,IAAI,CAUN;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAmB7D"}