@37signals/basecamp 0.2.0

package/dist/hooks/otel.d.ts

@@ -0,0 +1,136 @@
+/**
+ * OpenTelemetry hooks for the Basecamp SDK.
+ *
+ * Provides distributed tracing and metrics for API operations.
+ * Requires @opentelemetry/api as an optional peer dependency.
+ *
+ * @example
+ * ```ts
+ * import { createBasecampClient, otelHooks } from "@37signals/basecamp";
+ * import { trace, metrics } from "@opentelemetry/api";
+ *
+ * const tracer = trace.getTracer("my-app");
+ * const meter = metrics.getMeter("my-app");
+ *
+ * const client = createBasecampClient({
+ *   accountId: "12345",
+ *   accessToken: "token",
+ *   hooks: otelHooks({ tracer, meter }),
+ * });
+ *
+ * // All SDK operations will now create spans and record metrics
+ * const projects = await client.projects.list();
+ * ```
+ */
+import type { BasecampHooks } from "../hooks.js";
+interface OtelSpan {
+    setAttribute(key: string, value: string | number | boolean): this;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): this;
+    recordException(exception: Error): this;
+    end(): void;
+}
+interface OtelTracer {
+    startSpan(name: string, options?: {
+        attributes?: Record<string, string | number | boolean>;
+    }): OtelSpan;
+}
+interface OtelMeter {
+    createHistogram(name: string, options?: {
+        description?: string;
+        unit?: string;
+    }): OtelHistogram;
+    createCounter(name: string, options?: {
+        description?: string;
+    }): OtelCounter;
+}
+interface OtelHistogram {
+    record(value: number, attributes?: Record<string, string | number | boolean>): void;
+}
+interface OtelCounter {
+    add(value: number, attributes?: Record<string, string | number | boolean>): void;
+}
+/**
+ * Options for OpenTelemetry hooks.
+ */
+export interface OtelHooksOptions {
+    /**
+     * OpenTelemetry tracer instance.
+     * Create with: `trace.getTracer("your-app-name")`
+     */
+    tracer?: OtelTracer;
+    /**
+     * OpenTelemetry meter instance for metrics.
+     * Create with: `metrics.getMeter("your-app-name")`
+     */
+    meter?: OtelMeter;
+    /**
+     * Whether to record request-level spans (in addition to operation spans).
+     * Defaults to false for reduced noise.
+     */
+    recordRequestSpans?: boolean;
+    /**
+     * Prefix for span names.
+     * Defaults to "basecamp"
+     */
+    spanPrefix?: string;
+    /**
+     * Prefix for metric names.
+     * Defaults to "basecamp"
+     */
+    metricPrefix?: string;
+}
+/**
+ * Creates OpenTelemetry hooks for distributed tracing and metrics.
+ *
+ * This function creates hooks that integrate with OpenTelemetry for:
+ * - **Tracing**: Creates spans for SDK operations with relevant attributes
+ * - **Metrics**: Records histograms for latency and counters for operations/errors
+ *
+ * Span attributes include:
+ * - `basecamp.service`: Service name (e.g., "Todos", "Projects")
+ * - `basecamp.operation`: Operation name (e.g., "List", "Create")
+ * - `basecamp.resource_type`: Type of resource being accessed
+ * - `basecamp.is_mutation`: Whether the operation modifies data
+ * - `basecamp.project_id`: Project ID if applicable
+ * - `basecamp.resource_id`: Resource ID if applicable
+ *
+ * Metrics recorded:
+ * - `basecamp.operation.duration`: Histogram of operation durations (ms)
+ * - `basecamp.request.duration`: Histogram of HTTP request durations (ms)
+ * - `basecamp.operations.total`: Counter of total operations
+ * - `basecamp.errors.total`: Counter of errors
+ * - `basecamp.retries.total`: Counter of retry attempts
+ *
+ * @param options - Configuration options
+ * @returns Hooks object for use with createBasecampClient
+ *
+ * @example
+ * ```ts
+ * import { createBasecampClient, otelHooks } from "@37signals/basecamp";
+ * import { trace, metrics } from "@opentelemetry/api";
+ *
+ * // Set up OpenTelemetry first (SDK configuration not shown)
+ * const tracer = trace.getTracer("my-app", "1.0.0");
+ * const meter = metrics.getMeter("my-app", "1.0.0");
+ *
+ * const client = createBasecampClient({
+ *   accountId: "12345",
+ *   accessToken: "token",
+ *   hooks: otelHooks({
+ *     tracer,
+ *     meter,
+ *     spanPrefix: "basecamp",
+ *     recordRequestSpans: true,
+ *   }),
+ * });
+ *
+ * // Operations will create spans and record metrics
+ * const todos = await client.todos.list(projectId, todolistId);
+ * ```
+ */
+export declare function otelHooks(options?: OtelHooksOptions): BasecampHooks;
+export {};
+//# sourceMappingURL=otel.d.ts.map

package/dist/hooks/otel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../../src/hooks/otel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAA8D,MAAM,aAAa,CAAC;AAI7G,UAAU,QAAQ;IAChB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAClE,SAAS,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5D,eAAe,CAAC,SAAS,EAAE,KAAK,GAAG,IAAI,CAAC;IACxC,GAAG,IAAI,IAAI,CAAC;CACb;AAED,UAAU,UAAU;IAClB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;KAAE,GAAG,QAAQ,CAAC;CACzG;AAED,UAAU,SAAS;IACjB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,aAAa,CAAC;IAChG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,WAAW,CAAC;CAC9E;AAED,UAAU,aAAa;IACrB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC;CACrF;AAED,UAAU,WAAW;IACnB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC;CAClF;AASD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IAEpB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAuCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,aAAa,CAyKvE"}

package/dist/hooks/otel.js

@@ -0,0 +1,240 @@
+/**
+ * OpenTelemetry hooks for the Basecamp SDK.
+ *
+ * Provides distributed tracing and metrics for API operations.
+ * Requires @opentelemetry/api as an optional peer dependency.
+ *
+ * @example
+ * ```ts
+ * import { createBasecampClient, otelHooks } from "@37signals/basecamp";
+ * import { trace, metrics } from "@opentelemetry/api";
+ *
+ * const tracer = trace.getTracer("my-app");
+ * const meter = metrics.getMeter("my-app");
+ *
+ * const client = createBasecampClient({
+ *   accountId: "12345",
+ *   accessToken: "token",
+ *   hooks: otelHooks({ tracer, meter }),
+ * });
+ *
+ * // All SDK operations will now create spans and record metrics
+ * const projects = await client.projects.list();
+ * ```
+ */
+// Span status codes from OpenTelemetry
+const SpanStatusCode = {
+    UNSET: 0,
+    OK: 1,
+    ERROR: 2,
+};
+/** Counter for generating unique keys */
+let keyCounter = 0;
+/**
+ * Creates a unique key for an operation.
+ */
+function operationKey(info) {
+    return `${info.service}.${info.operation}:${info.resourceId ?? ""}:${++keyCounter}`;
+}
+/**
+ * Creates a unique key for a request.
+ */
+function requestKey(info) {
+    return `${info.method}:${info.url}:${info.attempt}:${++keyCounter}`;
+}
+/**
+ * Creates OpenTelemetry hooks for distributed tracing and metrics.
+ *
+ * This function creates hooks that integrate with OpenTelemetry for:
+ * - **Tracing**: Creates spans for SDK operations with relevant attributes
+ * - **Metrics**: Records histograms for latency and counters for operations/errors
+ *
+ * Span attributes include:
+ * - `basecamp.service`: Service name (e.g., "Todos", "Projects")
+ * - `basecamp.operation`: Operation name (e.g., "List", "Create")
+ * - `basecamp.resource_type`: Type of resource being accessed
+ * - `basecamp.is_mutation`: Whether the operation modifies data
+ * - `basecamp.project_id`: Project ID if applicable
+ * - `basecamp.resource_id`: Resource ID if applicable
+ *
+ * Metrics recorded:
+ * - `basecamp.operation.duration`: Histogram of operation durations (ms)
+ * - `basecamp.request.duration`: Histogram of HTTP request durations (ms)
+ * - `basecamp.operations.total`: Counter of total operations
+ * - `basecamp.errors.total`: Counter of errors
+ * - `basecamp.retries.total`: Counter of retry attempts
+ *
+ * @param options - Configuration options
+ * @returns Hooks object for use with createBasecampClient
+ *
+ * @example
+ * ```ts
+ * import { createBasecampClient, otelHooks } from "@37signals/basecamp";
+ * import { trace, metrics } from "@opentelemetry/api";
+ *
+ * // Set up OpenTelemetry first (SDK configuration not shown)
+ * const tracer = trace.getTracer("my-app", "1.0.0");
+ * const meter = metrics.getMeter("my-app", "1.0.0");
+ *
+ * const client = createBasecampClient({
+ *   accountId: "12345",
+ *   accessToken: "token",
+ *   hooks: otelHooks({
+ *     tracer,
+ *     meter,
+ *     spanPrefix: "basecamp",
+ *     recordRequestSpans: true,
+ *   }),
+ * });
+ *
+ * // Operations will create spans and record metrics
+ * const todos = await client.todos.list(projectId, todolistId);
+ * ```
+ */
+export function otelHooks(options = {}) {
+    const { tracer, meter, recordRequestSpans = false, spanPrefix = "basecamp", metricPrefix = "basecamp", } = options;
+    // Initialize state
+    const state = {
+        operationSpans: new Map(),
+        requestSpans: new Map(),
+    };
+    // Initialize metrics if meter is provided
+    if (meter) {
+        state.operationDuration = meter.createHistogram(`${metricPrefix}.operation.duration`, {
+            description: "Duration of Basecamp SDK operations",
+            unit: "ms",
+        });
+        state.requestDuration = meter.createHistogram(`${metricPrefix}.request.duration`, {
+            description: "Duration of HTTP requests",
+            unit: "ms",
+        });
+        state.operationCounter = meter.createCounter(`${metricPrefix}.operations.total`, {
+            description: "Total number of Basecamp SDK operations",
+        });
+        state.errorCounter = meter.createCounter(`${metricPrefix}.errors.total`, {
+            description: "Total number of errors",
+        });
+        state.retryCounter = meter.createCounter(`${metricPrefix}.retries.total`, {
+            description: "Total number of retry attempts",
+        });
+    }
+    return {
+        onOperationStart(info) {
+            // Record operation count (even without tracer)
+            state.operationCounter?.add(1, {
+                service: info.service,
+                operation: info.operation,
+                is_mutation: info.isMutation,
+            });
+            if (!tracer)
+                return;
+            const spanName = `${spanPrefix}.${info.service}.${info.operation}`;
+            const attributes = {
+                [`${spanPrefix}.service`]: info.service,
+                [`${spanPrefix}.operation`]: info.operation,
+                [`${spanPrefix}.resource_type`]: info.resourceType,
+                [`${spanPrefix}.is_mutation`]: info.isMutation,
+            };
+            if (info.projectId) {
+                attributes[`${spanPrefix}.project_id`] = info.projectId;
+            }
+            if (info.resourceId) {
+                attributes[`${spanPrefix}.resource_id`] = info.resourceId;
+            }
+            const span = tracer.startSpan(spanName, { attributes });
+            const key = operationKey(info);
+            state.operationSpans.set(key, span);
+        },
+        onOperationEnd(info, result) {
+            // Find and end the span
+            if (tracer) {
+                // Find the most recent span for this operation
+                for (const [key, span] of state.operationSpans) {
+                    if (key.startsWith(`${info.service}.${info.operation}:`)) {
+                        if (result.error) {
+                            span.setStatus({ code: SpanStatusCode.ERROR, message: result.error.message });
+                            span.recordException(result.error);
+                            span.setAttribute("error", true);
+                            span.setAttribute("error.message", result.error.message);
+                        }
+                        else {
+                            span.setStatus({ code: SpanStatusCode.OK });
+                        }
+                        span.setAttribute("duration_ms", result.durationMs);
+                        span.end();
+                        state.operationSpans.delete(key);
+                        break;
+                    }
+                }
+            }
+            // Record metrics
+            const labels = {
+                service: info.service,
+                operation: info.operation,
+                is_mutation: info.isMutation,
+                success: !result.error,
+            };
+            state.operationDuration?.record(result.durationMs, labels);
+            if (result.error) {
+                state.errorCounter?.add(1, {
+                    service: info.service,
+                    operation: info.operation,
+                    error_type: result.error.name,
+                });
+            }
+        },
+        onRequestStart(info) {
+            if (!tracer || !recordRequestSpans)
+                return;
+            const spanName = `${spanPrefix}.http.${info.method}`;
+            const span = tracer.startSpan(spanName, {
+                attributes: {
+                    "http.method": info.method,
+                    "http.url": info.url,
+                    "http.attempt": info.attempt,
+                },
+            });
+            const key = requestKey(info);
+            state.requestSpans.set(key, span);
+        },
+        onRequestEnd(info, result) {
+            // Find and end the span
+            if (tracer && recordRequestSpans) {
+                for (const [key, span] of state.requestSpans) {
+                    if (key.startsWith(`${info.method}:${info.url}:${info.attempt}:`)) {
+                        span.setAttribute("http.status_code", result.statusCode);
+                        span.setAttribute("http.from_cache", result.fromCache);
+                        span.setAttribute("duration_ms", result.durationMs);
+                        if (result.error) {
+                            span.setStatus({ code: SpanStatusCode.ERROR, message: result.error.message });
+                            span.recordException(result.error);
+                        }
+                        else if (result.statusCode >= 400) {
+                            span.setStatus({ code: SpanStatusCode.ERROR, message: `HTTP ${result.statusCode}` });
+                        }
+                        else {
+                            span.setStatus({ code: SpanStatusCode.OK });
+                        }
+                        span.end();
+                        state.requestSpans.delete(key);
+                        break;
+                    }
+                }
+            }
+            // Record request metrics
+            state.requestDuration?.record(result.durationMs, {
+                method: info.method,
+                status_code: result.statusCode,
+                from_cache: result.fromCache,
+            });
+        },
+        onRetry(info, attempt, error, _delayMs) {
+            state.retryCounter?.add(1, {
+                method: info.method,
+                attempt,
+                error_type: error.name,
+            });
+        },
+    };
+}
+//# sourceMappingURL=otel.js.map

package/dist/hooks/otel.js.map

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

package/dist/hooks.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Observability hooks system for the Basecamp SDK.
+ *
+ * Provides a way to observe API operations and HTTP requests
+ * without modifying the core client logic. Hooks compile away
+ * when unused (no overhead).
+ *
+ * @example
+ * ```ts
+ * import { createBasecampClient, consoleHooks } from "@37signals/basecamp";
+ *
+ * // Simple console logging
+ * const client = createBasecampClient({
+ *   accountId: "12345",
+ *   accessToken: "token",
+ *   hooks: consoleHooks(),
+ * });
+ *
+ * // Custom metrics
+ * const client = createBasecampClient({
+ *   accountId: "12345",
+ *   accessToken: "token",
+ *   hooks: {
+ *     onOperationEnd: (info, result) => {
+ *       metrics.recordLatency(info.service, info.operation, result.durationMs);
+ *       if (result.error) {
+ *         metrics.recordError(info.service, info.operation);
+ *       }
+ *     },
+ *   },
+ * });
+ * ```
+ */
+/**
+ * Information about a high-level service operation.
+ */
+export interface OperationInfo {
+    /** Service name (e.g., "Todos", "Projects") */
+    service: string;
+    /** Operation name (e.g., "List", "Get", "Create") */
+    operation: string;
+    /** Type of resource being accessed */
+    resourceType: string;
+    /** Whether this operation modifies data */
+    isMutation: boolean;
+    /** Project ID if the operation is scoped to a project */
+    projectId?: number;
+    /** Resource ID if the operation targets a specific resource */
+    resourceId?: number;
+}
+/**
+ * Information about an HTTP request.
+ */
+export interface RequestInfo {
+    /** HTTP method */
+    method: string;
+    /** Full request URL */
+    url: string;
+    /** Current attempt number (1-based) */
+    attempt: number;
+}
+/**
+ * Result of an HTTP request.
+ */
+export interface RequestResult {
+    /** HTTP status code */
+    statusCode: number;
+    /** Request duration in milliseconds */
+    durationMs: number;
+    /** Whether the response was served from cache */
+    fromCache: boolean;
+    /** Error if the request failed */
+    error?: Error;
+}
+/**
+ * Result of an operation.
+ */
+export interface OperationResult {
+    /** Error if the operation failed */
+    error?: Error;
+    /** Operation duration in milliseconds */
+    durationMs: number;
+}
+/**
+ * Hooks interface for observing SDK operations.
+ * All hooks are optional - implement only what you need.
+ */
+export interface BasecampHooks {
+    /**
+     * Called when a service operation starts.
+     * Use for logging, tracing, or metrics.
+     */
+    onOperationStart?(info: OperationInfo): void;
+    /**
+     * Called when a service operation completes (success or failure).
+     * Always called, even if onOperationStart threw.
+     */
+    onOperationEnd?(info: OperationInfo, result: OperationResult): void;
+    /**
+     * Called when an HTTP request starts.
+     * Called for each attempt (including retries).
+     */
+    onRequestStart?(info: RequestInfo): void;
+    /**
+     * Called when an HTTP request completes.
+     * Called for each attempt (including retries).
+     */
+    onRequestEnd?(info: RequestInfo, result: RequestResult): void;
+    /**
+     * Called before a retry attempt.
+     * Use for logging retry behavior or implementing custom backoff.
+     */
+    onRetry?(info: RequestInfo, attempt: number, error: Error, delayMs: number): void;
+}
+/**
+ * Combines multiple hooks into a single hooks object.
+ * All hooks are called in order. Errors in hooks are caught and logged.
+ *
+ * @example
+ * ```ts
+ * const hooks = chainHooks(
+ *   consoleHooks(),
+ *   metricsHooks(),
+ *   sentryHooks(),
+ * );
+ * ```
+ */
+export declare function chainHooks(...hooks: BasecampHooks[]): BasecampHooks;
+/**
+ * Options for console logging hooks.
+ */
+export interface ConsoleHooksOptions {
+    /** Whether to log operation events (default: true) */
+    logOperations?: boolean;
+    /** Whether to log request events (default: false) */
+    logRequests?: boolean;
+    /** Whether to log retry events (default: true) */
+    logRetries?: boolean;
+    /** Minimum duration in ms to log (default: 0) */
+    minDurationMs?: number;
+    /** Custom logger (default: console) */
+    logger?: Pick<Console, "log" | "warn" | "error">;
+}
+/**
+ * Creates hooks that log to the console.
+ * Useful for debugging and development.
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const hooks = consoleHooks();
+ *
+ * // With custom options
+ * const hooks = consoleHooks({
+ *   logRequests: true,
+ *   minDurationMs: 100,
+ * });
+ * ```
+ */
+export declare function consoleHooks(options?: ConsoleHooksOptions): BasecampHooks;
+/**
+ * Creates a no-op hooks object.
+ * Useful as a default when hooks are optional.
+ */
+export declare function noopHooks(): BasecampHooks;
+/**
+ * Internal helper to safely invoke a hook.
+ * Returns silently if the hook throws.
+ */
+export declare function safeInvoke<K extends keyof BasecampHooks>(hooks: BasecampHooks | undefined, hookName: K, ...args: Parameters<NonNullable<BasecampHooks[K]>>): void;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,UAAU,EAAE,OAAO,CAAC;IACpB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,SAAS,EAAE,OAAO,CAAC;IACnB,kCAAkC;IAClC,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,oCAAoC;IACpC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,gBAAgB,CAAC,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;IAE7C;;;OAGG;IACH,cAAc,CAAC,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IAEpE;;;OAGG;IACH,cAAc,CAAC,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IAEzC;;;OAGG;IACH,YAAY,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAE9D;;;OAGG;IACH,OAAO,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACnF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,GAAG,KAAK,EAAE,aAAa,EAAE,GAAG,aAAa,CA+DnE;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qDAAqD;IACrD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kDAAkD;IAClD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iDAAiD;IACjD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CAClD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,aAAa,CA4D7E;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,aAAa,CAEzC;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,aAAa,EACtD,KAAK,EAAE,aAAa,GAAG,SAAS,EAChC,QAAQ,EAAE,CAAC,EACX,GAAG,IAAI,EAAE,UAAU,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,GACjD,IAAI,CAYN"}