@pingops/sdk 0.1.0

package/dist/pingops.js

@@ -0,0 +1,259 @@
+/**
+ * PingOps SDK singleton for manual instrumentation
+ *
+ * Provides initializePingops and shutdownPingops functions.
+ * wrapHttp is available from @pingops/core and will auto-initialize
+ * from environment variables if needed.
+ */
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { setPingopsTracerProvider, shutdownTracerProvider, PingopsSpanProcessor, } from "@pingops/otel";
+import { createLogger } from "@pingops/core";
+import { setSdkInitialized, isGlobalInstrumentationEnabled, } from "./init-state";
+import { wrapHttp as coreWrapHttp, } from "@pingops/core";
+import { getPingopsTracerProvider } from "@pingops/otel";
+import { getInstrumentations } from "@pingops/otel";
+const initLogger = createLogger("[PingOps Initialize]");
+const logger = createLogger("[PingOps Pingops]");
+let sdkInstance = null;
+let isSdkInitializedFlag = false;
+/**
+ * Global state to track initialization
+ */
+let isInitialized = false;
+let initializationPromise = null;
+/**
+ * Initializes PingOps SDK
+ *
+ * This function:
+ * 1. Creates an OpenTelemetry NodeSDK instance
+ * 2. Configures Resource with service.name
+ * 3. Registers PingopsSpanProcessor
+ * 4. Enables HTTP/fetch/GenAI instrumentation
+ * 5. Starts the SDK
+ *
+ * @param config - Configuration for the SDK
+ * @param explicit - Whether this is an explicit call (default: true).
+ *                   Set to false when called internally by wrapHttp auto-initialization.
+ */
+export function initializePingops(config, explicit = true) {
+    if (isSdkInitializedFlag) {
+        if (config.debug) {
+            initLogger.warn("[PingOps] SDK already initialized, skipping");
+        }
+        return;
+    }
+    // Create resource with service name
+    const resource = resourceFromAttributes({
+        [ATTR_SERVICE_NAME]: config.serviceName,
+    });
+    const processor = new PingopsSpanProcessor(config);
+    const instrumentations = getInstrumentations(isGlobalInstrumentationEnabled);
+    // Node.js SDK
+    const nodeSdk = new NodeSDK({
+        resource,
+        spanProcessors: [processor],
+        instrumentations,
+    });
+    nodeSdk.start();
+    sdkInstance = nodeSdk;
+    // Mark SDK as initialized
+    isSdkInitializedFlag = true;
+    // Only enable global instrumentation if this was an explicit call
+    // If called via wrapHttp auto-initialization, global instrumentation stays disabled
+    setSdkInitialized(explicit);
+    // Initialize isolated TracerProvider for manual spans AFTER NodeSDK starts
+    // This ensures manual spans created via startSpan are processed by the same processor
+    // We register it after NodeSDK so it takes precedence as the global provider
+    try {
+        // In version 2.2.0, span processors are passed in the constructor
+        const isolatedProvider = new NodeTracerProvider({
+            resource,
+            spanProcessors: [processor],
+        });
+        // Register the provider globally
+        isolatedProvider.register();
+        // Set it in global state
+        setPingopsTracerProvider(isolatedProvider);
+    }
+    catch (error) {
+        if (config.debug) {
+            initLogger.error("[PingOps] Failed to create isolated TracerProvider:", error instanceof Error ? error.message : String(error));
+        }
+        // Continue without isolated provider - manual spans will use global provider
+    }
+    if (config.debug) {
+        initLogger.info("[PingOps] SDK initialized");
+    }
+}
+/**
+ * Shuts down the SDK and flushes remaining spans
+ */
+export async function shutdownPingops() {
+    // Shutdown isolated TracerProvider first
+    await shutdownTracerProvider();
+    if (!sdkInstance) {
+        return;
+    }
+    await sdkInstance.shutdown();
+    sdkInstance = null;
+    isSdkInitializedFlag = false;
+    setSdkInitialized(false);
+}
+/**
+ * Checks if the SDK is already initialized by checking if a NodeTracerProvider is available
+ */
+function isSdkInitialized() {
+    try {
+        const provider = getPingopsTracerProvider();
+        // If we have a NodeTracerProvider (not the default NoOpTracerProvider), SDK is initialized
+        const initialized = provider instanceof NodeTracerProvider;
+        logger.debug("Checked SDK initialization status", {
+            initialized,
+            providerType: provider.constructor.name,
+        });
+        return initialized;
+    }
+    catch (error) {
+        logger.debug("Error checking SDK initialization status", {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+}
+/**
+ * Auto-initializes the SDK from environment variables if not already initialized
+ */
+async function ensureInitialized() {
+    // Check if SDK is already initialized (e.g., by calling initializePingops directly)
+    if (isSdkInitialized()) {
+        logger.debug("SDK already initialized, skipping auto-initialization");
+        isInitialized = true;
+        return;
+    }
+    if (isInitialized) {
+        logger.debug("SDK initialization flag already set, skipping");
+        return;
+    }
+    // If initialization is in progress, wait for it
+    if (initializationPromise) {
+        logger.debug("SDK initialization already in progress, waiting...");
+        return initializationPromise;
+    }
+    // Start initialization
+    logger.info("Starting SDK auto-initialization from environment variables");
+    initializationPromise = Promise.resolve().then(() => {
+        const apiKey = process.env.PINGOPS_API_KEY;
+        const baseUrl = process.env.PINGOPS_BASE_URL;
+        const serviceName = process.env.PINGOPS_SERVICE_NAME;
+        const debug = process.env.PINGOPS_DEBUG === "true";
+        logger.debug("Reading environment variables", {
+            hasApiKey: !!apiKey,
+            hasBaseUrl: !!baseUrl,
+            hasServiceName: !!serviceName,
+            debug,
+        });
+        if (!apiKey || !baseUrl || !serviceName) {
+            const missing = [
+                !apiKey && "PINGOPS_API_KEY",
+                !baseUrl && "PINGOPS_BASE_URL",
+                !serviceName && "PINGOPS_SERVICE_NAME",
+            ].filter(Boolean);
+            logger.error("Missing required environment variables for auto-initialization", {
+                missing,
+            });
+            throw new Error(`PingOps SDK auto-initialization requires PINGOPS_API_KEY, PINGOPS_BASE_URL, and PINGOPS_SERVICE_NAME environment variables. Missing: ${missing.join(", ")}`);
+        }
+        const config = {
+            apiKey,
+            baseUrl,
+            serviceName,
+            debug,
+        };
+        logger.info("Initializing SDK with config", {
+            baseUrl,
+            serviceName,
+            debug,
+        });
+        // Call initializePingops with explicit=false since this is auto-initialization
+        initializePingops(config, false);
+        isInitialized = true;
+        logger.info("SDK auto-initialization completed successfully");
+    });
+    try {
+        await initializationPromise;
+    }
+    catch (error) {
+        logger.error("SDK auto-initialization failed", {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+    }
+    finally {
+        initializationPromise = null;
+    }
+}
+/**
+ * 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.
+ *
+ * @param options - Options including attributes to propagate to spans
+ * @param fn - Function to execute within the attribute context
+ * @returns The result of the function
+ *
+ * @example
+ * ```typescript
+ * import { wrapHttp } from '@pingops/sdk';
+ *
+ * // Scenario 1: initializePingops was called
+ * initializePingops({ ... });
+ *
+ * // All HTTP requests are instrumented, but this block adds attributes
+ * const result = await wrapHttp({
+ *   attributes: {
+ *     userId: 'user-123',
+ *     sessionId: 'session-456',
+ *     tags: ['production', 'api'],
+ *     metadata: { environment: 'prod', version: '1.0.0' }
+ *   }
+ * }, async () => {
+ *   // This HTTP request will be instrumented AND have the attributes set above
+ *   const response = await fetch('https://api.example.com/users/123');
+ *   return response.json();
+ * });
+ *
+ * // HTTP requests outside wrapHttp are still instrumented, just without the attributes
+ * const otherResponse = await fetch('https://api.example.com/other');
+ *
+ * // Scenario 2: initializePingops was NOT called
+ * // Only requests within wrapHttp are instrumented
+ * await wrapHttp({
+ *   attributes: { userId: 'user-123' }
+ * }, async () => {
+ *   // This request IS instrumented
+ *   return fetch('https://api.example.com/data');
+ * });
+ *
+ * // This request is NOT instrumented (outside wrapHttp)
+ * await fetch('https://api.example.com/other');
+ * ```
+ */
+export function wrapHttp(options, fn) {
+    return coreWrapHttp({
+        ...options,
+        checkInitialized: isSdkInitialized,
+        isGlobalInstrumentationEnabled: isGlobalInstrumentationEnabled,
+        ensureInitialized: ensureInitialized,
+    }, fn);
+}
+//# sourceMappingURL=pingops.js.map

package/dist/pingops.js.map

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

package/dist/span-wrapper.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Span wrapper for PingOps SDK
+ *
+ * Provides PingopsSpan class similar to LangfuseSpan for wrapping OpenTelemetry spans
+ * with PingOps-specific functionality.
+ */
+import { TimeInput, Span, SpanContext } from '@opentelemetry/api';
+import type { Attributes } from '@opentelemetry/api';
+import type { SpanAttributes } from './tracer-provider';
+/**
+ * Base class for PingOps span wrappers
+ *
+ * Provides common functionality for wrapping OpenTelemetry spans with PingOps-specific features.
+ */
+declare abstract class PingopsBaseSpan {
+    /** The underlying OpenTelemetry span */
+    readonly otelSpan: Span;
+    /** The span ID from the OpenTelemetry span context */
+    id: string;
+    /** The trace ID from the OpenTelemetry span context */
+    traceId: string;
+    constructor(otelSpan: Span);
+    /**
+     * Ends the span, marking it as complete.
+     *
+     * @param endTime - Optional end time, defaults to current time
+     */
+    end(endTime?: TimeInput): void;
+    /**
+     * Updates the span with new attributes.
+     *
+     * @param attributes - Span attributes to set
+     * @returns This span for method chaining
+     */
+    update(attributes: SpanAttributes): PingopsSpan;
+}
+/**
+ * PingOps span wrapper for tracking operations
+ *
+ * Provides a convenient wrapper around OpenTelemetry spans with PingOps-specific
+ * attribute handling and lifecycle management.
+ */
+export declare class PingopsSpan extends PingopsBaseSpan {
+    constructor(otelSpan: Span);
+}
+/**
+ * Creates an OpenTelemetry span with the PingOps tracer.
+ *
+ * @param params - Parameters for span creation
+ * @returns The created OpenTelemetry span
+ * @internal
+ */
+export declare function createOtelSpan(params: {
+    name: string;
+    startTime?: TimeInput;
+    parentSpanContext?: SpanContext;
+    attributes?: Attributes;
+}): Span;
+export {};
+//# sourceMappingURL=span-wrapper.d.ts.map

package/dist/span-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-wrapper.d.ts","sourceRoot":"","sources":["../src/span-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAkB,SAAS,EAAE,IAAI,EAAE,WAAW,EAAW,MAAM,oBAAoB,CAAC;AAC3F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD;;;;GAIG;AACH,uBAAe,eAAe;IAC5B,wCAAwC;IACxC,SAAgB,QAAQ,EAAE,IAAI,CAAC;IAC/B,sDAAsD;IAC/C,EAAE,EAAE,MAAM,CAAC;IAClB,uDAAuD;IAChD,OAAO,EAAE,MAAM,CAAC;gBAEX,QAAQ,EAAE,IAAI;IAO1B;;;;OAIG;IACI,GAAG,CAAC,OAAO,CAAC,EAAE,SAAS,GAAG,IAAI;IAIrC;;;;;OAKG;IACI,MAAM,CAAC,UAAU,EAAE,cAAc,GAAG,WAAW;CA8CvD;AAED;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,eAAe;gBAClC,QAAQ,EAAE,IAAI;CAG3B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,iBAAiB,CAAC,EAAE,WAAW,CAAC;IAChC,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,GAAG,IAAI,CAYP"}

package/dist/span-wrapper.js

@@ -0,0 +1,118 @@
+/**
+ * Span wrapper for PingOps SDK
+ *
+ * Provides PingopsSpan class similar to LangfuseSpan for wrapping OpenTelemetry spans
+ * with PingOps-specific functionality.
+ */
+import { trace, context } from '@opentelemetry/api';
+import { getPingopsTracerProvider } from './tracer-provider';
+/**
+ * Base class for PingOps span wrappers
+ *
+ * Provides common functionality for wrapping OpenTelemetry spans with PingOps-specific features.
+ */
+class PingopsBaseSpan {
+    /** The underlying OpenTelemetry span */
+    otelSpan;
+    /** The span ID from the OpenTelemetry span context */
+    id;
+    /** The trace ID from the OpenTelemetry span context */
+    traceId;
+    constructor(otelSpan) {
+        this.otelSpan = otelSpan;
+        const spanContext = otelSpan.spanContext();
+        this.id = spanContext.spanId;
+        this.traceId = spanContext.traceId;
+    }
+    /**
+     * Ends the span, marking it as complete.
+     *
+     * @param endTime - Optional end time, defaults to current time
+     */
+    end(endTime) {
+        this.otelSpan.end(endTime);
+    }
+    /**
+     * Updates the span with new attributes.
+     *
+     * @param attributes - Span attributes to set
+     * @returns This span for method chaining
+     */
+    update(attributes) {
+        const otelAttributes = {};
+        // Handle nested attributes object
+        if (attributes.attributes) {
+            Object.assign(otelAttributes, attributes.attributes);
+        }
+        // Handle input/output
+        if (attributes.input !== undefined) {
+            otelAttributes['span.input'] =
+                typeof attributes.input === 'string'
+                    ? attributes.input
+                    : JSON.stringify(attributes.input);
+        }
+        if (attributes.output !== undefined) {
+            otelAttributes['span.output'] =
+                typeof attributes.output === 'string'
+                    ? attributes.output
+                    : JSON.stringify(attributes.output);
+        }
+        // Handle metadata
+        if (attributes.metadata !== undefined) {
+            for (const [key, value] of Object.entries(attributes.metadata)) {
+                otelAttributes[`span.metadata.${key}`] =
+                    typeof value === 'string' ? value : JSON.stringify(value);
+            }
+        }
+        // Add any other custom attributes (excluding the special keys)
+        for (const [key, value] of Object.entries(attributes)) {
+            if (key !== 'attributes' &&
+                key !== 'input' &&
+                key !== 'output' &&
+                key !== 'metadata') {
+                otelAttributes[key] = value;
+            }
+        }
+        this.otelSpan.setAttributes(otelAttributes);
+        return this;
+    }
+}
+/**
+ * PingOps span wrapper for tracking operations
+ *
+ * Provides a convenient wrapper around OpenTelemetry spans with PingOps-specific
+ * attribute handling and lifecycle management.
+ */
+export class PingopsSpan extends PingopsBaseSpan {
+    constructor(otelSpan) {
+        super(otelSpan);
+    }
+}
+/**
+ * Creates an OpenTelemetry span with the PingOps tracer.
+ *
+ * @param params - Parameters for span creation
+ * @returns The created OpenTelemetry span
+ * @internal
+ */
+export function createOtelSpan(params) {
+    const provider = getPingopsTracerProvider();
+    const tracer = provider.getTracer('@pingops/sdk', '0.1.0');
+    return tracer.startSpan(params.name, {
+        startTime: params.startTime,
+        attributes: params.attributes,
+    }, createParentContext(params.parentSpanContext));
+}
+/**
+ * Creates a parent context from a span context.
+ *
+ * @param parentSpanContext - The span context to use as parent
+ * @returns The created context or undefined if no parent provided
+ * @internal
+ */
+function createParentContext(parentSpanContext) {
+    if (!parentSpanContext)
+        return undefined;
+    return trace.setSpanContext(context.active(), parentSpanContext);
+}
+//# sourceMappingURL=span-wrapper.js.map

package/dist/span-wrapper.js.map

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

package/dist/tracer-provider.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Tracer Provider with global state and isolated TracerProvider architecture
+ *
+ * This module provides an isolated TracerProvider that shares the same
+ * span processors (like PingopsSpanProcessor) with the main OpenTelemetry SDK.
+ * This ensures manual spans created via startSpan are properly processed.
+ *
+ * Architecture follows Langfuse's pattern with global state management.
+ */
+import { TimeInput } from '@opentelemetry/api';
+import type { Attributes, Span, TracerProvider } from '@opentelemetry/api';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import type { SpanProcessor } from '@opentelemetry/sdk-trace-base';
+/**
+ * Options for starting a span
+ */
+export interface StartSpanOptions {
+    /** Span attributes */
+    attributes?: Attributes;
+    /** Custom start time for the span */
+    startTime?: TimeInput;
+}
+/**
+ * Attributes for updating trace-level information
+ */
+export interface TraceAttributes {
+    /** User ID associated with the trace */
+    userId?: string;
+    /** Session ID for grouping related traces */
+    sessionId?: string;
+    /** Tags for categorizing traces */
+    tags?: string[];
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Custom attributes */
+    [key: string]: unknown;
+}
+/**
+ * Attributes for updating span-level information
+ */
+export interface SpanAttributes {
+    /** Input data for the operation */
+    input?: unknown;
+    /** Output data from the operation */
+    output?: unknown;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Custom attributes */
+    attributes?: Attributes;
+    /** Custom attributes */
+    [key: string]: unknown;
+}
+/**
+ * Sets an isolated TracerProvider for PingOps tracing operations.
+ *
+ * This allows PingOps to use its own TracerProvider instance, separate from
+ * the global OpenTelemetry TracerProvider. This is useful for avoiding conflicts
+ * with other OpenTelemetry instrumentation in the application.
+ *
+ * @param provider - The TracerProvider instance to use, or null to clear the isolated provider
+ * @public
+ */
+export declare function setPingopsTracerProvider(provider: TracerProvider | null): void;
+/**
+ * Gets the TracerProvider for PingOps tracing operations.
+ *
+ * Returns the isolated TracerProvider if one has been set via setPingopsTracerProvider(),
+ * otherwise falls back to the global OpenTelemetry TracerProvider.
+ *
+ * @returns The TracerProvider instance to use for PingOps tracing
+ * @public
+ */
+export declare function getPingopsTracerProvider(): TracerProvider;
+/**
+ * Initializes the isolated TracerProvider with the given span processors
+ *
+ * This creates a separate TracerProvider that shares the same span processors
+ * (like PingopsSpanProcessor) with the main SDK. This ensures manual spans
+ * are processed correctly.
+ *
+ * @param spanProcessors - Array of span processors to use (e.g., PingopsSpanProcessor)
+ * @param serviceName - Service name for resource attributes
+ * @deprecated Use setPingopsTracerProvider instead
+ */
+export declare function initializeTracerProvider(spanProcessors: SpanProcessor[], serviceName: string): void;
+/**
+ * Gets the isolated TracerProvider instance
+ *
+ * @returns The TracerProvider instance, or null if not initialized
+ * @deprecated Use getPingopsTracerProvider instead
+ */
+export declare function getTracerProvider(): NodeTracerProvider | null;
+/**
+ * Shuts down the TracerProvider and flushes remaining spans
+ */
+export declare function shutdownTracerProvider(): Promise<void>;
+/**
+ * Starts a span, executes the function, and automatically ends the span
+ *
+ * This function uses the isolated TracerProvider to ensure spans are
+ * properly processed by PingopsSpanProcessor and other registered processors.
+ *
+ * The span is automatically set as active in the OpenTelemetry context, allowing
+ * child spans and updates to work correctly.
+ *
+ * @param name - Span name
+ * @param options - Span options including attributes
+ * @param fn - Function to execute within the span context (can be sync or async)
+ * @returns The result of the function
+ *
+ * @example
+ * ```typescript
+ * import { startSpan } from '@pingops/sdk';
+ *
+ * const result = await startSpan('your-span-name', {
+ *   attributes: {
+ *     customer_id: 'cust_123',
+ *     correlation_id: 'req_456',
+ *   },
+ * }, async (span) => {
+ *   const result = await fetch('https://api.example.com');
+ *   return 'done';
+ * });
+ * ```
+ */
+export declare function startSpan<T>(name: string, options: StartSpanOptions, fn: (span: Span) => T | Promise<T>): T | Promise<T>;
+/**
+ * Updates the currently active trace with new attributes.
+ *
+ * This function finds the currently active OpenTelemetry span and updates
+ * it with trace-level attributes. If no active span is found, a warning is logged.
+ *
+ * @param attributes - Trace attributes to set
+ *
+ * @example
+ * ```typescript
+ * import { updateActiveTrace } from '@pingops/sdk';
+ *
+ * // Inside an active span context
+ * updateActiveTrace({
+ *   userId: 'user-123',
+ *   sessionId: 'session-456',
+ *   tags: ['production', 'critical'],
+ * });
+ * ```
+ */
+export declare function updateActiveTrace(attributes: TraceAttributes): void;
+/**
+ * Updates the currently active span with new attributes.
+ *
+ * This function finds the currently active OpenTelemetry span in the execution context
+ * and updates it with span-level attributes. If no active span exists, the update is skipped.
+ *
+ * @param attributes - Span attributes to update
+ *
+ * @example
+ * ```typescript
+ * import { startSpan, updateActiveSpan } from '@pingops/sdk';
+ *
+ * await startSpan('data-processing', {
+ *   attributes: { step: 'initialization' },
+ * }, async (span) => {
+ *   // Process data...
+ *   const result = await processData(inputData);
+ *
+ *   // Update with results
+ *   updateActiveSpan({
+ *     attributes: { processed_records: result.count },
+ *     output: { success: true },
+ *   });
+ * });
+ * ```
+ */
+export declare function updateActiveSpan(attributes: SpanAttributes): void;
+//# sourceMappingURL=tracer-provider.d.ts.map

package/dist/tracer-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer-provider.d.ts","sourceRoot":"","sources":["../src/tracer-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAA4C,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACzF,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AA0EnE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sBAAsB;IACtB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,qCAAqC;IACrC,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,wBAAwB;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qCAAqC;IACrC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,wBAAwB;IACxB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,wBAAwB;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAc9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,cAAc,CAezD;AAqBD;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,aAAa,EAAE,EAC/B,WAAW,EAAE,MAAM,GAClB,IAAI,CA4BN;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,kBAAkB,GAAG,IAAI,CAG7D;AAED;;GAEG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAoB5D;AA6DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,gBAAgB,EACzB,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACjC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CA0EhB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI,CAuEnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,cAAc,GAAG,IAAI,CAgHjE"}