@flowcore/pathways 0.16.4 → 0.17.0

package/esm/deps/jsr.io/@flowcore/time-uuid/0.1.2/src/lib/uuid.js

@@ -0,0 +1,131 @@
+/*
+ * Copyright DataStax, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+"use strict";
+import * as crypto from "node:crypto";
+import { Buffer } from "node:buffer";
+/** @module types */
+/**
+ * Represents an immutable universally unique identifier (UUID).
+ * A UUID represents a 128-bit value.
+ */
+export class Uuid {
+    /**
+     * Creates a new instance of Uuid based on a Buffer
+     * @param buffer The 16-length buffer.
+     */
+    constructor(buffer) {
+        Object.defineProperty(this, "buffer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        if (!buffer || buffer.length !== 16) {
+            throw new Error("You must provide a buffer containing 16 bytes");
+        }
+        this.buffer = buffer;
+    }
+    /**
+     * Parses a string representation of a Uuid
+     * @param value The string representation of UUID
+     * @returns A new Uuid instance
+     */
+    static fromString(value) {
+        //36 chars: 32 + 4 hyphens
+        if (typeof value !== "string" || value.length !== 36) {
+            throw new Error("Invalid string representation of Uuid, it should be in the 00000000-0000-0000-0000-000000000000");
+        }
+        return new Uuid(Buffer.from(value.replace(/-/g, ""), "hex"));
+    }
+    /**
+     * Creates a new random (version 4) Uuid.
+     */
+    static random() {
+        const buffer = getRandomBytes();
+        return createUuidFromBuffer(buffer);
+    }
+    /**
+     * Gets the bytes representation of a Uuid
+     * @returns The buffer containing the bytes
+     */
+    getBuffer() {
+        return this.buffer;
+    }
+    /**
+     * Compares this object to the specified object.
+     * The result is true if and only if the argument is not null, is a UUID object,
+     * and contains the same value, bit for bit, as this UUID.
+     * @param other The other value to test for equality.
+     */
+    equals(other) {
+        return other instanceof Uuid && this.buffer.equals(other.buffer);
+    }
+    /**
+     * Returns a string representation of the value of this Uuid instance.
+     * 32 hex separated by hyphens, in the form of 00000000-0000-0000-0000-000000000000.
+     */
+    toString() {
+        //32 hex representation of the Buffer
+        const hexValue = getHex(this);
+        return (hexValue.substr(0, 8) + "-" +
+            hexValue.substr(8, 4) + "-" +
+            hexValue.substr(12, 4) + "-" +
+            hexValue.substr(16, 4) + "-" +
+            hexValue.substr(20, 12));
+    }
+    /**
+     * Provide the name of the constructor and the string representation
+     */
+    inspect() {
+        return this.constructor.name + ": " + this.toString();
+    }
+    /**
+     * Returns the string representation.
+     * Method used by the native JSON.stringify() to serialize this instance.
+     */
+    toJSON() {
+        return this.toString();
+    }
+}
+/**
+ * Returns new Uuid
+ * @private
+ */
+function createUuidFromBuffer(buffer) {
+    //clear the version
+    buffer[6] &= 0x0f;
+    //set the version 4
+    buffer[6] |= 0x40;
+    //clear the variant
+    buffer[8] &= 0x3f;
+    //set the IETF variant
+    buffer[8] |= 0x80;
+    return new Uuid(buffer);
+}
+/**
+ * @private
+ * @returns 32 hex representation of the instance, without separators
+ */
+function getHex(uuid) {
+    return uuid.getBuffer().toString("hex");
+}
+/**
+ * Gets a crypto generated 16 bytes
+ * @private
+ */
+function getRandomBytes() {
+    return crypto.randomBytes(16);
+}

package/esm/deps/jsr.io/@flowcore/time-uuid/0.1.2/src/mod.d.ts

@@ -0,0 +1,3 @@
+export * from "./lib/time-uuid.js";
+export * from "./lib/uuid.js";
+//# sourceMappingURL=mod.d.ts.map

package/esm/deps/jsr.io/@flowcore/time-uuid/0.1.2/src/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../../../../../src/deps/jsr.io/@flowcore/time-uuid/0.1.2/src/mod.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA"}

package/esm/deps/jsr.io/@flowcore/time-uuid/0.1.2/src/mod.js

@@ -0,0 +1,2 @@
+export * from "./lib/time-uuid.js";
+export * from "./lib/uuid.js";

package/esm/mod.d.ts

@@ -9,6 +9,7 @@
  *
  * @module
  */
+import "./_dnt.polyfills.js";
 export * from "./common/index.js";
 export * from "./contracts/index.js";
 export * from "./pathways/index.js";

package/esm/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAA;AACjC,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,qBAAqB,CAAC;AAE7B,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAA;AACjC,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAA"}

package/esm/mod.js

@@ -9,6 +9,7 @@
  *
  * @module
  */
+import "./_dnt.polyfills.js";
 export * from "./common/index.js";
 export * from "./contracts/index.js";
 export * from "./pathways/index.js";

package/esm/pathways/builder.d.ts

@@ -3,6 +3,10 @@ import type { WebhookSendOptions } from "@flowcore/sdk-transformer-core";
 import type { FlowcoreEvent } from "../contracts/event.js";
 import type { Logger } from "./logger.js";
 import type { EventMetadata, PathwayContract, PathwayKey, PathwayState, PathwayWriteOptions, WritablePathway } from "./types.js";
+import type { PathwayClusterOptions } from "./cluster/types.js";
+import { ClusterManager } from "./cluster/cluster-manager.js";
+import type { PathwayPumpOptions } from "./pump/types.js";
+import { PathwayPump } from "./pump/pathway-pump.js";
 import { FileEventSchema, FileInputSchema } from "./types.js";
 /**
  * Defines the mode for auditing pathway operations
@@ -151,6 +155,14 @@ export declare class PathwaysBuilder<TPathway extends Record<string, {
     private readonly dataCore;
     private readonly apiKey;
     private readonly logLevel;
+    private readonly flowTypeDescriptions;
+    private readonly eventTypeDescriptions;
+    private readonly dataCoreDescription?;
+    private readonly dataCoreAccessControl;
+    private readonly dataCoreDeleteProtection;
+    private clusterManager;
+    private pathwayPump;
+    private clusterBypassProcess;
     /**
      * Creates a new PathwaysBuilder instance
      * @param options Configuration options for the PathwaysBuilder
@@ -165,7 +177,7 @@ export declare class PathwaysBuilder<TPathway extends Record<string, {
      * @param options.logLevel Optional configuration for log levels
      * @param options.logLevel.writeSuccess Log level for write success messages ('info' or 'debug'). Defaults to 'info'.
      */
-    constructor({ baseUrl, tenant, dataCore, apiKey, pathwayTimeoutMs, logger, enableSessionUserResolvers, overrideSessionUserResolvers, logLevel, }: {
+    constructor({ baseUrl, tenant, dataCore, apiKey, pathwayTimeoutMs, logger, enableSessionUserResolvers, overrideSessionUserResolvers, logLevel, dataCoreDescription, dataCoreAccessControl, dataCoreDeleteProtection, }: {
         baseUrl: string;
         tenant: string;
         dataCore: string;
@@ -175,6 +187,9 @@ export declare class PathwaysBuilder<TPathway extends Record<string, {
         enableSessionUserResolvers?: boolean;
         overrideSessionUserResolvers?: SessionUserResolver;
         logLevel?: LogLevelConfig;
+        dataCoreDescription?: string;
+        dataCoreAccessControl?: string;
+        dataCoreDeleteProtection?: boolean;
     });
     /**
      * Configures the PathwaysBuilder to use a custom pathway state implementation
@@ -323,6 +338,36 @@ export declare class PathwaysBuilder<TPathway extends Record<string, {
      * @throws Error if the timeout is exceeded
      */
     private waitForPathwayToBeProcessed;
+    /**
+     * Start cluster mode for distributed event processing.
+     * This instance joins the cluster and either becomes a leader (distributes events)
+     * or a worker (receives and processes events).
+     */
+    startCluster(options: PathwayClusterOptions): Promise<ClusterManager>;
+    /**
+     * Stop cluster mode
+     */
+    stopCluster(): Promise<void>;
+    /**
+     * Whether cluster mode is currently active
+     */
+    get isClusterActive(): boolean;
+    /**
+     * Provision Flowcore infrastructure (data core, flow types, event types).
+     * Creates missing resources when descriptions are provided, updates descriptions
+     * when they differ. Fails if a resource is missing and no description is provided.
+     * Additive only — never deletes.
+     */
+    provision(): Promise<void>;
+    /**
+     * Start the data pump to auto-fetch events from Flowcore.
+     * If cluster is active, pump only runs on the leader instance.
+     */
+    startPump(options: PathwayPumpOptions): Promise<PathwayPump>;
+    /**
+     * Stop the data pump
+     */
+    stopPump(): Promise<void>;
     /**
      * Converts a Zod validation error to a human-readable string
      * @param error The Zod validation error to convert

package/esm/pathways/builder.d.ts.map

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

package/esm/pathways/builder.js

@@ -4,6 +4,9 @@ import { Subject } from "rxjs";
 import { WebhookBuilder } from "../compatibility/flowcore-transformer-core.sdk.js";
 import { InternalPathwayState } from "./internal-pathway.state.js";
 import { NoopLogger } from "./logger.js";
+import { ClusterManager } from "./cluster/cluster-manager.js";
+import { PathwayPump } from "./pump/pathway-pump.js";
+import { PathwayProvisioner } from "./provisioner.js";
 import { AUDIT_ENTITY_ID, AUDIT_ENTITY_TYPE, AUDIT_MODE, AUDIT_ON_BEHALF_OF_ID, AUDIT_ON_BEHALF_OF_TYPE, AUDIT_SESSION_ID, AUDIT_SYSTEM_MODE, AUDIT_USER_MODE, } from "./constants.js";
 import { FileEventSchema, FileInputSchema } from "./types.js";
 import process from "node:process";
@@ -106,7 +109,7 @@ export class PathwaysBuilder {
      * @param options.logLevel Optional configuration for log levels
      * @param options.logLevel.writeSuccess Log level for write success messages ('info' or 'debug'). Defaults to 'info'.
      */
-    constructor({ baseUrl, tenant, dataCore, apiKey, pathwayTimeoutMs, logger, enableSessionUserResolvers, overrideSessionUserResolvers, logLevel, }) {
+    constructor({ baseUrl, tenant, dataCore, apiKey, pathwayTimeoutMs, logger, enableSessionUserResolvers, overrideSessionUserResolvers, logLevel, dataCoreDescription, dataCoreAccessControl, dataCoreDeleteProtection, }) {
         Object.defineProperty(this, "pathways", {
             enumerable: true,
             configurable: true,
@@ -279,6 +282,56 @@ export class PathwaysBuilder {
             writable: true,
             value: void 0
         });
+        // Provisioning descriptions
+        Object.defineProperty(this, "flowTypeDescriptions", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "eventTypeDescriptions", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "dataCoreDescription", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "dataCoreAccessControl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "dataCoreDeleteProtection", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        // Cluster + pump
+        Object.defineProperty(this, "clusterManager", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "pathwayPump", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "clusterBypassProcess", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
         // Initialize logger (use NoopLogger if none provided)
         this.logger = logger ?? new NoopLogger();
         // Initialize log levels with defaults
@@ -290,6 +343,10 @@ export class PathwaysBuilder {
         this.tenant = tenant;
         this.dataCore = dataCore;
         this.apiKey = apiKey;
+        // Store provisioning config
+        this.dataCoreDescription = dataCoreDescription;
+        this.dataCoreAccessControl = dataCoreAccessControl ?? "private";
+        this.dataCoreDeleteProtection = dataCoreDeleteProtection ?? false;
         if (enableSessionUserResolvers) {
             this.sessionUserResolvers = overrideSessionUserResolvers ?? new SessionUser();
         }
@@ -444,6 +501,11 @@ export class PathwaysBuilder {
             });
             this.auditHandler(pathwayStr, data);
         }
+        // Route through cluster if active and not bypassed (bypass = worker processing locally)
+        if (this.clusterManager && !this.clusterBypassProcess) {
+            await this.clusterManager.processEvent(pathwayStr, data);
+            return;
+        }
         if (this.handlers[pathway]) {
             let retryCount = 0;
             const maxRetries = this.maxRetries[pathway] ?? DEFAULT_MAX_RETRIES;
@@ -590,6 +652,13 @@ export class PathwaysBuilder {
             this.inputSchemas[path] = contract.schema ?? z.object({});
         }
         this.writable[path] = writable;
+        // Store provisioning descriptions
+        if (contract.description !== undefined) {
+            this.eventTypeDescriptions.set(path, contract.description);
+        }
+        if (contract.flowTypeDescription !== undefined) {
+            this.flowTypeDescriptions.set(contract.flowType, contract.flowTypeDescription);
+        }
         this.logger.info(`Pathway registered successfully`, {
             pathway: path,
             flowType: contract.flowType,
@@ -820,7 +889,7 @@ export class PathwaysBuilder {
                 fileId,
                 fileName,
                 fileType: fileType?.mime ?? "application/octet-stream",
-                fileContent: new Blob([fileContent]),
+                fileContent: new Blob([new Uint8Array(fileContent)]),
                 additionalProperties,
             }, finalMetadata, options).catch((error) => {
                 this.logger.error(`Error writing file to pathway`, {
@@ -906,6 +975,137 @@ export class PathwaysBuilder {
             attempts,
         });
     }
+    /**
+     * Start cluster mode for distributed event processing.
+     * This instance joins the cluster and either becomes a leader (distributes events)
+     * or a worker (receives and processes events).
+     */
+    async startCluster(options) {
+        if (this.clusterManager) {
+            throw new Error("Cluster already started");
+        }
+        this.clusterManager = new ClusterManager(options, this.logger);
+        // Set handler: when cluster needs to process locally, call process() with bypass
+        this.clusterManager.setEventHandler(async (pathway, event) => {
+            this.clusterBypassProcess = true;
+            try {
+                await this.process(pathway, event);
+            }
+            finally {
+                this.clusterBypassProcess = false;
+            }
+        });
+        await this.clusterManager.start();
+        this.logger.info("Cluster started", {
+            advertisedAddress: options.advertisedAddress,
+            port: options.port,
+        });
+        return this.clusterManager;
+    }
+    /**
+     * Stop cluster mode
+     */
+    async stopCluster() {
+        if (!this.clusterManager)
+            return;
+        await this.clusterManager.stop();
+        this.clusterManager = null;
+        this.logger.info("Cluster stopped");
+    }
+    /**
+     * Whether cluster mode is currently active
+     */
+    get isClusterActive() {
+        return this.clusterManager !== null && this.clusterManager.isRunning;
+    }
+    /**
+     * Provision Flowcore infrastructure (data core, flow types, event types).
+     * Creates missing resources when descriptions are provided, updates descriptions
+     * when they differ. Fails if a resource is missing and no description is provided.
+     * Additive only — never deletes.
+     */
+    async provision() {
+        const registrations = Object.keys(this.pathways).map((key) => {
+            const [flowType, eventType] = key.split("/");
+            return {
+                flowType,
+                eventType,
+                flowTypeDescription: this.flowTypeDescriptions.get(flowType),
+                eventTypeDescription: this.eventTypeDescriptions.get(key),
+            };
+        });
+        const provisioner = new PathwayProvisioner({
+            tenant: this.tenant,
+            dataCore: this.dataCore,
+            apiKey: this.apiKey,
+            dataCoreDescription: this.dataCoreDescription,
+            dataCoreAccessControl: this.dataCoreAccessControl,
+            dataCoreDeleteProtection: this.dataCoreDeleteProtection,
+            registrations,
+            logger: this.logger,
+        });
+        await provisioner.provision();
+    }
+    /**
+     * Start the data pump to auto-fetch events from Flowcore.
+     * If cluster is active, pump only runs on the leader instance.
+     */
+    async startPump(options) {
+        if (this.pathwayPump) {
+            throw new Error("Pump already started");
+        }
+        // Auto-provision infrastructure if requested
+        if (options.autoProvision) {
+            this.logger.info("Auto-provisioning Flowcore infrastructure before starting pump");
+            await this.provision();
+        }
+        // If cluster active and not leader, don't start pump
+        if (this.clusterManager && !this.clusterManager.isLeader) {
+            this.logger.info("Not starting pump — this instance is not the cluster leader");
+            // Still create the pump but don't start it — it can be started if we become leader
+            this.pathwayPump = new PathwayPump(options, this.logger);
+            this.pathwayPump.configure({
+                tenant: this.tenant,
+                dataCore: this.dataCore,
+                apiKey: this.apiKey,
+                baseUrl: this.baseUrl,
+                processEvent: async (pathway, event) => {
+                    await this.process(pathway, event);
+                },
+            });
+            return this.pathwayPump;
+        }
+        this.pathwayPump = new PathwayPump(options, this.logger);
+        this.pathwayPump.configure({
+            tenant: this.tenant,
+            dataCore: this.dataCore,
+            apiKey: this.apiKey,
+            baseUrl: this.baseUrl,
+            processEvent: async (pathway, event) => {
+                await this.process(pathway, event);
+            },
+        });
+        // Collect registered pathways
+        const registrations = Object.keys(this.pathways).map((key) => {
+            const [flowType, eventType] = key.split("/");
+            return { flowType, eventType };
+        });
+        await this.pathwayPump.start(registrations);
+        this.logger.info("Pump started", {
+            pathways: registrations.length,
+        });
+        return this.pathwayPump;
+    }
+    /**
+     * Stop the data pump
+     */
+    async stopPump() {
+        if (!this.pathwayPump)
+            return;
+        await this.pathwayPump.stop();
+        this.pathwayPump = null;
+        this.logger.info("Pump stopped");
+    }
     /**
      * Converts a Zod validation error to a human-readable string
      * @param error The Zod validation error to convert

package/esm/pathways/cluster/cluster-manager.d.ts

@@ -0,0 +1,75 @@
+import type { FlowcoreEvent } from "../../contracts/event.js";
+import type { Logger } from "../logger.js";
+import type { ClusterRole, PathwayClusterOptions } from "./types.js";
+/**
+ * ClusterManager handles distributed event processing via leader election and WS workers.
+ *
+ * Lifecycle: register → heartbeat loop → leader election loop
+ * - Leader: opens WS connections to workers, distributes events round-robin
+ * - Worker: accepts WS from leader, processes events, sends ack/fail
+ * - Fallback: leader processes locally when no workers available
+ */
+export declare class ClusterManager {
+    private readonly coordinator;
+    private readonly transport;
+    private readonly instanceId;
+    private readonly advertisedAddress;
+    private readonly port;
+    private readonly leaseTtlMs;
+    private readonly leaseRenewIntervalMs;
+    private readonly heartbeatIntervalMs;
+    private readonly staleThresholdMs;
+    private readonly deliveryTimeoutMs;
+    private readonly workerConcurrency;
+    private readonly logger;
+    private role;
+    private running;
+    private heartbeatTimer;
+    private leaseTimer;
+    private deliveryTimeoutTimer;
+    private workerConnections;
+    private pendingDeliveries;
+    private workerAddresses;
+    private roundRobinIndex;
+    private wsServer;
+    private leaderConnection;
+    private eventHandler;
+    constructor(options: PathwayClusterOptions, logger?: Logger);
+    /**
+     * Set the handler that processes events locally (used by both leader fallback and workers)
+     */
+    setEventHandler(handler: (pathway: string, event: FlowcoreEvent) => Promise<void>): void;
+    /**
+     * Start the cluster: register instance, begin heartbeat, attempt leader election
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the cluster: release lease, unregister, close connections
+     */
+    stop(): Promise<void>;
+    /**
+     * Process an event through the cluster.
+     * - Leader: distribute to a worker or process locally if no workers
+     * - Worker: should not call this directly (receives events via WS)
+     */
+    processEvent(pathway: string, event: FlowcoreEvent): Promise<void>;
+    get isLeader(): boolean;
+    get isWorker(): boolean;
+    get currentRole(): ClusterRole;
+    get isRunning(): boolean;
+    get currentInstanceId(): string;
+    private tryAcquireLease;
+    private leaseLoop;
+    private onBecomeLeader;
+    private refreshWorkers;
+    private cleanupLeaderState;
+    private startWsServer;
+    private handleWorkerMessage;
+    private connectToWorker;
+    private handleLeaderMessage;
+    private getNextWorker;
+    private distributeToWorker;
+    private processLocally;
+    private checkDeliveryTimeouts;
+}
+//# sourceMappingURL=cluster-manager.d.ts.map

package/esm/pathways/cluster/cluster-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-manager.d.ts","sourceRoot":"","sources":["../../../src/pathways/cluster/cluster-manager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAE1C,OAAO,KAAK,EACV,WAAW,EAGX,qBAAqB,EAMtB,MAAM,YAAY,CAAA;AAwCnB;;;;;;;GAOG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAQ;IAC1C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAQ;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAQ;IAC7C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAQ;IAC5C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAQ;IAC1C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAQ;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAE/B,OAAO,CAAC,IAAI,CAAyB;IACrC,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,oBAAoB,CAA8C;IAG1E,OAAO,CAAC,iBAAiB,CAAwC;IACjE,OAAO,CAAC,iBAAiB,CAA0C;IACnE,OAAO,CAAC,eAAe,CAAe;IACtC,OAAO,CAAC,eAAe,CAAI;IAG3B,OAAO,CAAC,QAAQ,CAA6C;IAC7D,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,YAAY,CAA0E;gBAElF,OAAO,EAAE,qBAAqB,EAAE,MAAM,CAAC,EAAE,MAAM;IAe3D;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC;IAIjF;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwC5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiE3B;;;;OAIG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BxE,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,WAAW,IAAI,WAAW,CAE7B;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,iBAAiB,IAAI,MAAM,CAE9B;YAIa,eAAe;YAgBf,SAAS;YAeT,cAAc;YAId,cAAc;IAmC5B,OAAO,CAAC,kBAAkB;YAeZ,aAAa;YAgCb,mBAAmB;IA8CjC,OAAO,CAAC,eAAe;IAwCvB,OAAO,CAAC,mBAAmB;IA4B3B,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,kBAAkB;YAkCZ,cAAc;IAO5B,OAAO,CAAC,qBAAqB;CAS9B"}