@newrelic/preflight 0.0.1-pre.1 → 1.0.0

package/dist/shared/events/types.d.ts.map

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

package/dist/shared/events/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/shared/events/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/shared/events/types.ts"],"names":[],"mappings":""}

package/dist/shared/harvest/event-buffer.d.ts

@@ -0,0 +1,59 @@
+import type { NrEventData } from '../events/types.js';
+export interface EventBufferOptions {
+    readonly maxSize?: number;
+}
+/**
+ * Bounded in-memory event queue with head-drop overflow.
+ *
+ * When `add()` is called on a full buffer, the OLDEST event is discarded to
+ * make room for the new one. This preserves recency, which matters for
+ * observability data feeding alerts and dashboards — a user looking at New
+ * Relic during a latency spike wants the last 30 seconds, not a uniform random
+ * sample of the last hour. It also matches the head-drop policy used by the
+ * scheduler's retry buffers (§4.5), so callers see consistent behavior across
+ * the harvest pipeline.
+ *
+ * Each drop increments `dropCount`. `HarvestScheduler` drains this counter
+ * each harvest tick and emits it as the `nr.ai.dropped_events` self-monitoring
+ * metric so the loss is visible in the consumer's own NR dashboards.
+ */
+export declare class EventBuffer {
+    private readonly maxSize;
+    private buffer;
+    private totalSeen;
+    private droppedSinceDrain;
+    constructor(options?: EventBufferOptions);
+    /**
+     * Append an event to the buffer.
+     *
+     * Returns `true` when the event was added without evicting another, and
+     * `false` when the buffer was already at `maxSize` and the oldest event
+     * was head-dropped to make room. Callers ignoring
+     * the return value see the same behavior as before; callers that want
+     * backpressure feedback can use it to throttle producers.
+     */
+    add(event: NrEventData): boolean;
+    flush(): NrEventData[];
+    /**
+     * Return the number of events added since the last call, resetting the
+     * counter to 0. Mirrors `drainDropCount()` so callers that need per-flush
+     * production rate can use both symmetrically (§EB1).
+     */
+    drainAddCount(): number;
+    /**
+     * Return the number of events dropped due to overflow since the last call,
+     * resetting the counter to 0. Intended to be called once per harvest tick so
+     * the count can be surfaced as a self-monitoring metric.
+     */
+    drainDropCount(): number;
+    get size(): number;
+    /**
+     * Total events added since the last `drainAddCount()` call (or since
+     * construction if `drainAddCount()` has never been called). Peek-only —
+     * does NOT reset. Use `drainAddCount()` to consume and reset, matching
+     * the `dropCount` / `drainDropCount()` pattern.
+     */
+    get totalAdded(): number;
+    get dropCount(): number;
+}
+//# sourceMappingURL=event-buffer.d.ts.map

package/dist/shared/harvest/event-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-buffer.d.ts","sourceRoot":"","sources":["../../../src/shared/harvest/event-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAID;;;;;;;;;;;;;;GAcG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,iBAAiB,CAAS;gBAEtB,OAAO,CAAC,EAAE,kBAAkB;IAkBxC;;;;;;;;OAQG;IACH,GAAG,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IAahC,KAAK,IAAI,WAAW,EAAE;IAQtB;;;;OAIG;IACH,aAAa,IAAI,MAAM;IAMvB;;;;OAIG;IACH,cAAc,IAAI,MAAM;IAMxB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;OAKG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;CACF"}

package/dist/shared/harvest/event-buffer.js

@@ -0,0 +1,100 @@
+const DEFAULT_MAX_SIZE = 1000;
+/**
+ * Bounded in-memory event queue with head-drop overflow.
+ *
+ * When `add()` is called on a full buffer, the OLDEST event is discarded to
+ * make room for the new one. This preserves recency, which matters for
+ * observability data feeding alerts and dashboards — a user looking at New
+ * Relic during a latency spike wants the last 30 seconds, not a uniform random
+ * sample of the last hour. It also matches the head-drop policy used by the
+ * scheduler's retry buffers (§4.5), so callers see consistent behavior across
+ * the harvest pipeline.
+ *
+ * Each drop increments `dropCount`. `HarvestScheduler` drains this counter
+ * each harvest tick and emits it as the `nr.ai.dropped_events` self-monitoring
+ * metric so the loss is visible in the consumer's own NR dashboards.
+ */
+export class EventBuffer {
+    maxSize;
+    buffer;
+    totalSeen;
+    droppedSinceDrain;
+    constructor(options) {
+        const maxSize = options?.maxSize ?? DEFAULT_MAX_SIZE;
+        // 4: validate maxSize at construction. Pre-fix, values like
+        // 0 / negative / NaN turned the buffer into a silent /dev/null because the
+        // overflow comparison `buffer.length >= maxSize` is never true (NaN) or
+        // immediately true with no event ever stored (0 / negative). All
+        // observability would silently disappear with no diagnostic.
+        if (!Number.isInteger(maxSize) || maxSize <= 0) {
+            throw new RangeError(`EventBuffer: maxSize must be a positive integer, got ${String(maxSize)}`);
+        }
+        this.maxSize = maxSize;
+        this.buffer = [];
+        this.totalSeen = 0;
+        this.droppedSinceDrain = 0;
+    }
+    /**
+     * Append an event to the buffer.
+     *
+     * Returns `true` when the event was added without evicting another, and
+     * `false` when the buffer was already at `maxSize` and the oldest event
+     * was head-dropped to make room. Callers ignoring
+     * the return value see the same behavior as before; callers that want
+     * backpressure feedback can use it to throttle producers.
+     */
+    add(event) {
+        this.totalSeen++;
+        let dropped = false;
+        if (this.buffer.length >= this.maxSize) {
+            this.buffer.shift();
+            this.droppedSinceDrain++;
+            dropped = true;
+        }
+        this.buffer.push(event);
+        return !dropped;
+    }
+    flush() {
+        const snapshot = this.buffer;
+        this.buffer = [];
+        // totalSeen is NOT reset here — it is a monotonic lifetime counter drained
+        // explicitly via drainAddCount() (same pattern as dropCount / drainDropCount).
+        return snapshot;
+    }
+    /**
+     * Return the number of events added since the last call, resetting the
+     * counter to 0. Mirrors `drainDropCount()` so callers that need per-flush
+     * production rate can use both symmetrically (§EB1).
+     */
+    drainAddCount() {
+        const n = this.totalSeen;
+        this.totalSeen = 0;
+        return n;
+    }
+    /**
+     * Return the number of events dropped due to overflow since the last call,
+     * resetting the counter to 0. Intended to be called once per harvest tick so
+     * the count can be surfaced as a self-monitoring metric.
+     */
+    drainDropCount() {
+        const n = this.droppedSinceDrain;
+        this.droppedSinceDrain = 0;
+        return n;
+    }
+    get size() {
+        return this.buffer.length;
+    }
+    /**
+     * Total events added since the last `drainAddCount()` call (or since
+     * construction if `drainAddCount()` has never been called). Peek-only —
+     * does NOT reset. Use `drainAddCount()` to consume and reset, matching
+     * the `dropCount` / `drainDropCount()` pattern.
+     */
+    get totalAdded() {
+        return this.totalSeen;
+    }
+    get dropCount() {
+        return this.droppedSinceDrain;
+    }
+}
+//# sourceMappingURL=event-buffer.js.map

package/dist/shared/harvest/event-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-buffer.js","sourceRoot":"","sources":["../../../src/shared/harvest/event-buffer.ts"],"names":[],"mappings":"AAMA,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAE9B;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,WAAW;IACL,OAAO,CAAS;IACzB,MAAM,CAAgB;IACtB,SAAS,CAAS;IAClB,iBAAiB,CAAS;IAElC,YAAY,OAA4B;QACtC,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,gBAAgB,CAAC;QACrD,4DAA4D;QAC5D,2EAA2E;QAC3E,wEAAwE;QACxE,iEAAiE;QACjE,6DAA6D;QAC7D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,IAAI,CAAC,EAAE,CAAC;YAC/C,MAAM,IAAI,UAAU,CAClB,wDAAwD,MAAM,CAAC,OAAO,CAAC,EAAE,CAC1E,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;QACnB,IAAI,CAAC,iBAAiB,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED;;;;;;;;OAQG;IACH,GAAG,CAAC,KAAkB;QACpB,IAAI,CAAC,SAAS,EAAE,CAAC;QAEjB,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACvC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YACpB,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACzB,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,OAAO,CAAC,OAAO,CAAC;IAClB,CAAC;IAED,KAAK;QACH,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;QACjB,2EAA2E;QAC3E,+EAA+E;QAC/E,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACH,aAAa;QACX,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;QACnB,OAAO,CAAC,CAAC;IACX,CAAC;IAED;;;;OAIG;IACH,cAAc;QACZ,MAAM,CAAC,GAAG,IAAI,CAAC,iBAAiB,CAAC;QACjC,IAAI,CAAC,iBAAiB,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED;;;;;OAKG;IACH,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,iBAAiB,CAAC;IAChC,CAAC;CACF"}

package/dist/shared/harvest/harvest-scheduler.d.ts

@@ -0,0 +1,200 @@
+import type { NrEventData } from '../events/types.js';
+import type { NrMetric, TransportMode, TransportOptions, TransportResult } from '../transport/types.js';
+import type { OtlpEventBridge } from '../transport/otlp-event-bridge.js';
+import type { OtlpTransport } from '../transport/otlp-transport.js';
+import type { MetricAttributeValue } from './metric-aggregator.js';
+type SendEventsFn = (events: NrEventData[], licenseKey: string, options: TransportOptions) => Promise<TransportResult>;
+type SendMetricsFn = (metrics: NrMetric[], licenseKey: string, options: TransportOptions) => Promise<TransportResult>;
+export interface HarvestSchedulerOptions {
+    readonly licenseKey: string;
+    readonly transportOptions: TransportOptions;
+    readonly eventHarvestIntervalMs?: number;
+    readonly metricHarvestIntervalMs?: number;
+    readonly maxEventBufferSize?: number;
+    /**
+     * Maximum number of events kept in the per-transport retry buffer when a
+     * harvest fails. Defaults to `maxEventBufferSize`,
+     * but can be set independently — operators with bursty failure modes may
+     * want a deeper retry cap than primary buffer cap. Note that peak
+     * in-memory event count is roughly `maxEventBufferSize + maxRetryEvents`.
+     */
+    readonly maxRetryEvents?: number;
+    /**
+     * Maximum number of metric snapshots kept in the per-transport retry
+     * buffer when a metric harvest fails. Defaults to 500.
+     * Each snapshot represents one (name, attributes) bucket; with §4.9's
+     * summary-metric wire format, the corresponding NrMetric count is also
+     * one per snapshot.
+     */
+    readonly maxRetryMetricSnapshots?: number;
+    readonly sendEventsFn: SendEventsFn;
+    readonly sendMetricsFn: SendMetricsFn;
+    readonly otlpEventBridge?: OtlpEventBridge;
+    readonly otlpTransport?: OtlpTransport;
+    readonly transport?: TransportMode;
+    /**
+     * If `true`, the harvest intervals are `unref()`'d so they do not keep the
+     * Node event loop alive on their own, and a best-effort `beforeExit` handler
+     * is registered to attempt a final flush.
+     *
+     * **Default: `false`.** With the default, the running scheduler keeps the
+     * process alive — consumers MUST call `await scheduler.stop()` before
+     * exiting. This is the safe default: silently dropping buffered events on
+     * exit is worse than a process that won't quit.
+     *
+     * Set this to `true` only when:
+     * 1. You are sure your shutdown path always calls `await scheduler.stop()`,
+     *    AND
+     * 2. You also want the scheduler not to delay process exit if your
+     *    shutdown path is missed (CLI tools, short-lived scripts).
+     *
+     * The `beforeExit` fallback is best-effort: Node may exit before its
+     * fire-and-forget `void this.stop()` finishes, so events may be lost
+     *.
+     */
+    readonly allowProcessExit?: boolean;
+}
+export declare class HarvestScheduler {
+    private readonly eventBuffer;
+    private readonly metricAggregator;
+    private readonly licenseKey;
+    private readonly transportOptions;
+    private readonly sendEventsFn;
+    private readonly sendMetricsFn;
+    private readonly eventHarvestIntervalMs;
+    private readonly metricHarvestIntervalMs;
+    private readonly otlpEventBridge?;
+    private readonly otlpTransport?;
+    private readonly transport;
+    private readonly allowProcessExit;
+    private eventIntervalId;
+    private metricIntervalId;
+    private running;
+    private stopPromise;
+    private inFlightEventHarvest;
+    private inFlightMetricHarvest;
+    private retryNrEventBatch;
+    private retryOtlpEventBatch;
+    private retryNrMetricSnapshots;
+    private retryOtlpMetricSnapshots;
+    private readonly maxRetryEvents;
+    private readonly maxRetryMetricSnapshotsCap;
+    private readonly boundBeforeExit;
+    constructor(options: HarvestSchedulerOptions);
+    /**
+     * Buffer an event for the next harvest tick.
+     *
+     * Returns `true` when the event was added without evicting another, and
+     * `false` when the event buffer was already full and the oldest event
+     * was head-dropped. Callers ignoring the return
+     * value see the same behavior as before — the per-harvest
+     * `nr.ai.dropped_events` self-monitoring metric still counts the drops
+     * regardless. The boolean lets producers throttle or surface a custom
+     * backpressure metric instead of polling.
+     */
+    addEvent(event: NrEventData): boolean;
+    /**
+     * Record a metric sample.
+     *
+     * Returns `true` when the sample was accepted into a bucket, and `false`
+     * when it was rejected (non-finite value or invalid attribute type) per
+     * the §4.8 strict validation contract. Existing
+     * callers that ignore the return value see unchanged behavior.
+     */
+    recordMetric(name: string, value: number, attributes?: Record<string, MetricAttributeValue>): boolean;
+    /**
+     * Start periodic harvesting.
+     *
+     * **Signal handling is the consumer's responsibility.** This library does
+     * NOT register `SIGTERM` or `SIGINT` handlers — auto-registering process-level
+     * signal handlers from a library is an anti-pattern:
+     *
+     * 1. The consumer's main process likely has its own `SIGTERM`/`SIGINT`
+     *    handler. If both fire and the consumer's `process.exit(0)` runs first,
+     *    our in-flight `stop()` is killed mid-flush and events are lost on
+     *    graceful K8s rollout.
+     * 2. The consumer can't know that *we* attached a handler, so they can't
+     *    coordinate ordering.
+     *
+     * To flush cleanly on shutdown, register your own signal handler and
+     * `await scheduler.stop()` before exiting:
+     *
+     * ```ts
+     * for (const sig of ['SIGTERM', 'SIGINT'] as const) {
+     *   process.once(sig, async () => {
+     *     await scheduler.stop();
+     *     process.exit(0);
+     *   });
+     * }
+     * ```
+     *
+     * **Process exit semantics.** By default
+     * (`allowProcessExit: false`), the harvest intervals keep the Node event
+     * loop alive — your process will NOT exit until you call
+     * `await scheduler.stop()`. This is intentional: silently dropping
+     * buffered events on exit is worse than a process that won't quit.
+     * Pass `allowProcessExit: true` to opt into `unref()` + a best-effort
+     * `beforeExit` fallback (suitable for short-lived CLI tools where
+     * losing the last few buffered events is acceptable).
+     */
+    start(): void;
+    /**
+     * Stop the scheduler and run a final flush.
+     *
+     * Concurrent calls are coalesced — the first call drives the shutdown,
+     * subsequent calls receive the same `Promise`.
+     *
+     * Order of operations:
+     * 1. Clear the harvest intervals.
+     * 2. Await any in-flight harvest started by an interval tick.
+     * 3. Run a final `harvestEvents()` + `harvestMetrics()`.
+     * 4. `flush()` the optional `otlpEventBridge` and `otlpTransport` so
+     *    pending OTLP batches are drained.
+     *
+     * **OTel SDK teardown is the consumer's responsibility.**
+     * `stop()` deliberately does not call `shutdown()` on `otlpTransport` /
+     * `otlpEventBridge` — the scheduler does not own those objects'
+     * lifecycles. If you do not call `shutdown()` yourself, you will leak
+     * keep-alive HTTP/2 connections, may drop in-flight OTLP batches sitting
+     * inside the SDK's batch processors, and SDK timer handles can keep the
+     * Node event loop alive past `stop()`. After `await scheduler.stop()`,
+     * call:
+     *
+     * ```ts
+     * await otlpTransport.shutdown();   // tracer + meter providers
+     * await otlpEventBridge.shutdown(); // logger provider
+     * ```
+     *
+     * Order matters: shut down only *after* `stop()` has resolved, otherwise
+     * the final flush above will fail mid-export.
+     */
+    stop(): Promise<void>;
+    private doStop;
+    private harvestEvents;
+    private validateInterval;
+    private doHarvestEvents;
+    private sendEventsToNr;
+    private sendEventsToOtlp;
+    private harvestMetrics;
+    private doHarvestMetrics;
+    /**
+     * Combine retry snapshots with a fresh harvest's snapshots, accumulating
+     * any duplicate (name, attributes) buckets. Returns a new snapshot list
+     * with one entry per unique key. Uses a throwaway {@link MetricAggregator}
+     * as the merge engine so the bucket-key logic is not duplicated here.
+     *
+     * without this re-merge, a failed-send retry plus a
+     * fresh harvest hitting the same metric+attrs would produce two wire
+     * data points with different timestamps, breaking downstream NRQL
+     * aggregation that expects one bucket per harvest interval.
+     */
+    private mergeSnapshots;
+    private sendMetricsToNr;
+    private sendMetricsToOtlp;
+    private requeueNrEvents;
+    private requeueOtlpEvents;
+    private requeueNrMetrics;
+    private requeueOtlpMetrics;
+}
+export {};
+//# sourceMappingURL=harvest-scheduler.d.ts.map

package/dist/shared/harvest/harvest-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harvest-scheduler.d.ts","sourceRoot":"","sources":["../../../src/shared/harvest/harvest-scheduler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EACV,QAAQ,EACR,aAAa,EACb,gBAAgB,EAChB,eAAe,EAChB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAIpE,OAAO,KAAK,EAAE,oBAAoB,EAAkB,MAAM,wBAAwB,CAAC;AAgBnF,KAAK,YAAY,GAAG,CAClB,MAAM,EAAE,WAAW,EAAE,EACrB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC,eAAe,CAAC,CAAC;AAE9B,KAAK,aAAa,GAAG,CACnB,OAAO,EAAE,QAAQ,EAAE,EACnB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC,eAAe,CAAC,CAAC;AAE9B,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC5C,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAC1C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAC1C,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAC3C,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IAEnC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACrC;AAKD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IACpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAS;IACjD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAkB;IACnD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAgB;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAU;IAE3C,OAAO,CAAC,eAAe,CAA+C;IACtE,OAAO,CAAC,gBAAgB,CAA+C;IACvE,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,WAAW,CAA8B;IAOjD,OAAO,CAAC,oBAAoB,CAA8B;IAC1D,OAAO,CAAC,qBAAqB,CAA8B;IAK3D,OAAO,CAAC,iBAAiB,CAAqB;IAC9C,OAAO,CAAC,mBAAmB,CAAqB;IAOhD,OAAO,CAAC,sBAAsB,CAAwB;IACtD,OAAO,CAAC,wBAAwB,CAAwB;IACxD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAS;IAMpD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAa;gBAEjC,OAAO,EAAE,uBAAuB;IA+C5C;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IAIrC;;;;;;;OAOG;IACH,YAAY,CACV,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAM,GACpD,OAAO;IAIV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,KAAK,IAAI,IAAI;IAkEb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAuBb,MAAM;YAoEN,aAAa;IAW3B,OAAO,CAAC,gBAAgB;YASV,eAAe;YAkDf,cAAc;YA0Bd,gBAAgB;YA0BhB,cAAc;YAQd,gBAAgB;IAgE9B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,cAAc;YAYR,eAAe;YAkCf,iBAAiB;IAiD/B,OAAO,CAAC,eAAe;IAiBvB,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,gBAAgB;IAaxB,OAAO,CAAC,kBAAkB;CAY3B"}