@dexcost/sdk 0.2.0

package/dist/schema/dexcost-task.v1.json

@@ -0,0 +1,160 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://dexcost.io/schemas/dexcost-task.v1.json",
+  "title": "Dexcost Task v1",
+  "description": "Standard Event Schema v1 — Task payload. Represents a tracked business task with aggregated costs, tokens, and waste metrics.",
+  "type": "object",
+  "required": [
+    "task_id",
+    "task_type",
+    "status",
+    "started_at",
+    "schema_version",
+    "llm_cost_usd",
+    "external_cost_usd",
+    "compute_cost_usd",
+    "total_cost_usd",
+    "total_input_tokens",
+    "total_output_tokens",
+    "total_cached_tokens",
+    "retry_count",
+    "retry_cost_usd",
+    "failure_count"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "task_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Unique identifier for the task."
+    },
+    "task_type": {
+      "type": "string",
+      "description": "Business task type (e.g. resolve_ticket, generate_report)."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["pending", "success", "failed"],
+      "description": "Lifecycle status of the task."
+    },
+    "started_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp when the task started."
+    },
+    "ended_at": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "ISO-8601 timestamp when the task ended, or null if still running."
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Caller-defined context (customer tier, ticket id, etc.)."
+    },
+    "customer_id": {
+      "type": ["string", "null"],
+      "description": "Denormalised customer identifier for fast queries."
+    },
+    "project_id": {
+      "type": ["string", "null"],
+      "description": "Denormalised project identifier for fast queries."
+    },
+    "parent_task_id": {
+      "type": ["string", "null"],
+      "format": "uuid",
+      "description": "UUID of the parent task, or null for top-level tasks."
+    },
+    "experiment_id": {
+      "type": ["string", "null"],
+      "description": "Groups tasks into an experiment for variant comparison."
+    },
+    "variant": {
+      "type": ["string", "null"],
+      "description": "Labels which variant this task run belongs to within an experiment."
+    },
+    "llm_cost_usd": {
+      "type": "string",
+      "pattern": "^-?\\d+(\\.\\d+)?$",
+      "description": "Aggregated LLM cost in USD (Decimal as string)."
+    },
+    "external_cost_usd": {
+      "type": "string",
+      "pattern": "^-?\\d+(\\.\\d+)?$",
+      "description": "Aggregated external service cost in USD (Decimal as string)."
+    },
+    "compute_cost_usd": {
+      "type": "string",
+      "pattern": "^-?\\d+(\\.\\d+)?$",
+      "description": "Aggregated compute cost in USD (Decimal as string)."
+    },
+    "network_cost_usd": {
+      "type": "string",
+      "pattern": "^-?\\d+(\\.\\d+)?$",
+      "description": "Aggregated cloud-egress cost in USD (Decimal as string). Distinct from external_cost_usd, which captures vendor API fees — see spec Decision #7."
+    },
+    "gpu_cost_usd": {
+      "type": "string",
+      "pattern": "^-?\\d+(\\.\\d+)?$",
+      "description": "Aggregated GPU cost in USD (Decimal as string). Computed at task finalize from per-PID NVML SM-time × catalog rate. Distinct from compute_cost_usd (CPU/memory billing dimension)."
+    },
+    "total_cost_usd": {
+      "type": "string",
+      "pattern": "^-?\\d+(\\.\\d+)?$",
+      "description": "Total aggregated cost in USD (Decimal as string)."
+    },
+    "total_input_tokens": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total input tokens across all LLM events."
+    },
+    "total_output_tokens": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total output tokens across all LLM events."
+    },
+    "total_cached_tokens": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total cached tokens across all LLM events."
+    },
+    "retry_count": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Number of retried events in this task."
+    },
+    "retry_cost_usd": {
+      "type": "string",
+      "pattern": "^-?\\d+(\\.\\d+)?$",
+      "description": "Aggregated retry waste in USD (Decimal as string)."
+    },
+    "failure_count": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Number of failed events in this task."
+    },
+    "network_bytes_in": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total bytes received across all HTTP responses for this task."
+    },
+    "network_bytes_out": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total bytes sent across all HTTP requests for this task."
+    },
+    "network_call_count": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total number of outbound HTTP calls recorded for this task."
+    },
+    "network_by_host": {
+      "type": "object",
+      "description": "Per-host breakdown of network usage, shape {\"hosts\": [...]} capped at 20 entries plus an _other overflow bucket."
+    },
+    "schema_version": {
+      "type": "string",
+      "const": "1",
+      "description": "Schema version — always '1' for v1 payloads."
+    }
+  }
+}

package/dist/schema/validate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * JSON Schema validation for dexcost Standard Event Schema v1.
+ *
+ * Validates task and event payloads against bundled JSON Schema v1 files
+ * using Ajv. Mirrors the Python SDK's schema.py validate() function.
+ */
+/**
+ * Validate a task or event payload against the bundled JSON Schema v1.
+ *
+ * @param payload - A Record produced by `taskToDict()` or `eventToDict()`.
+ * @returns An empty array when the payload is valid; otherwise an array of
+ *          human-readable error strings in `"path: message"` format.
+ */
+export declare function validate(payload: Record<string, unknown>): string[];
+//# sourceMappingURL=validate.d.ts.map

package/dist/schema/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/schema/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAuDH;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAuBnE"}

package/dist/schema/validate.js

@@ -0,0 +1,87 @@
+/**
+ * JSON Schema validation for dexcost Standard Event Schema v1.
+ *
+ * Validates task and event payloads against bundled JSON Schema v1 files
+ * using Ajv. Mirrors the Python SDK's schema.py validate() function.
+ */
+// Sprint 3 Theme E / §4.2.3 — runtime JSON load for Node 18 support.
+// `import x from "./x.json" with { type: "json" }` is Node 22+ syntax;
+// reading the file at runtime works on every supported Node version.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+const _thisDir = dirname(fileURLToPath(import.meta.url));
+const eventSchema = JSON.parse(readFileSync(join(_thisDir, "dexcost-event.v1.json"), "utf-8"));
+const taskSchema = JSON.parse(readFileSync(join(_thisDir, "dexcost-task.v1.json"), "utf-8"));
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let ajv;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let validateEvent;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let validateTask;
+try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const AjvModule = require("ajv");
+    const AjvClass = AjvModule.default ?? AjvModule;
+    // Build Ajv instance with allErrors so all problems are reported at once.
+    ajv = new AjvClass({ allErrors: true });
+    // Attempt to load ajv-formats for uuid and date-time format validation.
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const formats = require("ajv-formats");
+        const addFormats = formats.default ?? formats;
+        addFormats(ajv);
+    }
+    catch {
+        /* ajv-formats not available — format keywords are silently ignored */
+    }
+    validateEvent = ajv.compile(eventSchema);
+    validateTask = ajv.compile(taskSchema);
+}
+catch {
+    // ajv not installed — validators will be null, validate() returns empty errors
+    ajv = null;
+    validateEvent = null;
+    validateTask = null;
+}
+/**
+ * Validate a task or event payload against the bundled JSON Schema v1.
+ *
+ * @param payload - A Record produced by `taskToDict()` or `eventToDict()`.
+ * @returns An empty array when the payload is valid; otherwise an array of
+ *          human-readable error strings in `"path: message"` format.
+ */
+export function validate(payload) {
+    // If ajv failed to load, we can't validate — return empty (no errors)
+    if (ajv === null || validateEvent === null || validateTask === null) {
+        return [];
+    }
+    // Step 1: check schema_version
+    const sv = payload["schema_version"];
+    if (sv !== "1") {
+        return [`Unsupported schema_version: ${String(sv)}`];
+    }
+    // Step 2: route to the correct schema validator
+    if ("event_id" in payload) {
+        return runValidator(validateEvent, payload);
+    }
+    if ("task_id" in payload) {
+        return runValidator(validateTask, payload);
+    }
+    // Step 3: cannot determine type
+    return ["Cannot determine payload type: missing task_id or event_id"];
+}
+/** Run an Ajv compiled validator and format its errors. */
+function runValidator(validator, payload) {
+    const valid = validator(payload);
+    if (valid) {
+        return [];
+    }
+    const errors = validator.errors ?? [];
+    return errors.map((err) => {
+        const path = err.instancePath || "(root)";
+        const message = err.message ?? "unknown error";
+        return `${path}: ${message}`;
+    });
+}
+//# sourceMappingURL=validate.js.map

package/dist/schema/validate.js.map

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

package/dist/security/redaction.d.ts

@@ -0,0 +1,55 @@
+/**
+ * PII redaction and metadata safety utilities.
+ *
+ * Provides field-level redaction, SHA-256 hashing, and metadata size
+ * enforcement to protect sensitive data before it leaves the SDK.
+ */
+/**
+ * Recursively remove specified fields from a dictionary.
+ *
+ * Returns a new dict with any key found in `fields` stripped entirely at
+ * all nesting levels.  Matching is case-sensitive.  This mirrors the
+ * Python SDK's `redact_dict`, which DELETES matched keys rather than
+ * masking them, so redacted PII never leaves the process.
+ */
+export declare function redactDict(data: Record<string, unknown>, fields: string[]): Record<string, unknown>;
+/**
+ * Compute a SHA-256 hex digest of the given value.
+ *
+ * Uses the Node.js built-in `crypto` module.
+ */
+export declare function hashValue(value: string): string;
+/**
+ * Enforce a maximum serialised size on a metadata/details dictionary.
+ *
+ * If the JSON representation of `details` exceeds `maxBytes`, returns a
+ * deterministic stub `{ _truncated: true, _original_size_bytes: N }`
+ * rather than partially removing keys.  This mirrors the Python SDK's
+ * `enforce_metadata_limit`.  When `details` is unserialisable a
+ * `{ _truncated: true, _error: "unserializable" }` stub is returned.
+ *
+ * @param details - The metadata dictionary to enforce limits on.
+ * @param maxBytes - Maximum allowed byte size. Defaults to 10 KB.
+ * @returns The original dictionary when within the limit, otherwise a stub.
+ */
+export declare function enforceMetadataLimit(details: Record<string, unknown>, maxBytes?: number): Record<string, unknown>;
+/**
+ * Strip credentials from a URL before it is captured into an event.
+ *
+ * Removes:
+ *  - userinfo (`user:pass@`) from the authority
+ *  - query parameters whose name (case-insensitive) is in the canonical
+ *    sensitive set OR ends with `-signature`, `-credential`, or
+ *    `-security-token` (AWS SigV4 surface)
+ *
+ * Preserves scheme, host, port, path, non-sensitive query params, and
+ * fragment. The shape of every removed query parameter is preserved as
+ * `name=REDACTED` so downstream callers can still see which keys were
+ * present without leaking the values.
+ *
+ * Canonical algorithm — Python/Go/Rust SDK implementations must produce
+ * byte-identical output for the same input (enforced by
+ * /fixtures/expected_outputs/security/).
+ */
+export declare function scrubUrl(url: string): string;
+//# sourceMappingURL=redaction.d.ts.map

package/dist/security/redaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.d.ts","sourceRoot":"","sources":["../../src/security/redaction.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,MAAM,EAAE,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqBzB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,GAAE,MAA0B,GACnC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAezB;AAyBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA8B5C"}

package/dist/security/redaction.js

@@ -0,0 +1,144 @@
+/**
+ * PII redaction and metadata safety utilities.
+ *
+ * Provides field-level redaction, SHA-256 hashing, and metadata size
+ * enforcement to protect sensitive data before it leaves the SDK.
+ */
+import { createHash } from "node:crypto";
+/** Default maximum metadata size in bytes (10 KB). */
+const DEFAULT_MAX_BYTES = 10_240;
+/**
+ * Recursively remove specified fields from a dictionary.
+ *
+ * Returns a new dict with any key found in `fields` stripped entirely at
+ * all nesting levels.  Matching is case-sensitive.  This mirrors the
+ * Python SDK's `redact_dict`, which DELETES matched keys rather than
+ * masking them, so redacted PII never leaves the process.
+ */
+export function redactDict(data, fields) {
+    const fieldSet = new Set(fields);
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (fieldSet.has(key)) {
+            continue;
+        }
+        if (value !== null &&
+            typeof value === "object" &&
+            !Array.isArray(value)) {
+            // Recursively redact nested objects
+            result[key] = redactDict(value, fields);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Compute a SHA-256 hex digest of the given value.
+ *
+ * Uses the Node.js built-in `crypto` module.
+ */
+export function hashValue(value) {
+    return createHash("sha256").update(value, "utf-8").digest("hex");
+}
+/**
+ * Enforce a maximum serialised size on a metadata/details dictionary.
+ *
+ * If the JSON representation of `details` exceeds `maxBytes`, returns a
+ * deterministic stub `{ _truncated: true, _original_size_bytes: N }`
+ * rather than partially removing keys.  This mirrors the Python SDK's
+ * `enforce_metadata_limit`.  When `details` is unserialisable a
+ * `{ _truncated: true, _error: "unserializable" }` stub is returned.
+ *
+ * @param details - The metadata dictionary to enforce limits on.
+ * @param maxBytes - Maximum allowed byte size. Defaults to 10 KB.
+ * @returns The original dictionary when within the limit, otherwise a stub.
+ */
+export function enforceMetadataLimit(details, maxBytes = DEFAULT_MAX_BYTES) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(details);
+    }
+    catch {
+        return { _truncated: true, _error: "unserializable" };
+    }
+    if (serialized === undefined) {
+        return { _truncated: true, _error: "unserializable" };
+    }
+    const byteSize = Buffer.byteLength(serialized, "utf-8");
+    if (byteSize <= maxBytes) {
+        return details;
+    }
+    return { _truncated: true, _original_size_bytes: byteSize };
+}
+/**
+ * Canonical set of query parameter names (case-insensitive) that
+ * {@link scrubUrl} strips. Must stay in sync with the same set in
+ * Python (dexcost/redaction.py), Go (security/redaction.go), and Rust
+ * (security/redaction.rs).
+ */
+const SENSITIVE_QUERY_PARAMS = new Set([
+    "api_key",
+    "apikey",
+    "access_token",
+    "token",
+    "auth",
+    "password",
+    "secret",
+    "signature",
+    "x-amz-signature",
+    "x-amz-credential",
+    "x-amz-security-token",
+    "session",
+]);
+const USERINFO_RE = /^(https?:\/\/)([^@/?#]+@)?(.+)$/;
+/**
+ * Strip credentials from a URL before it is captured into an event.
+ *
+ * Removes:
+ *  - userinfo (`user:pass@`) from the authority
+ *  - query parameters whose name (case-insensitive) is in the canonical
+ *    sensitive set OR ends with `-signature`, `-credential`, or
+ *    `-security-token` (AWS SigV4 surface)
+ *
+ * Preserves scheme, host, port, path, non-sensitive query params, and
+ * fragment. The shape of every removed query parameter is preserved as
+ * `name=REDACTED` so downstream callers can still see which keys were
+ * present without leaking the values.
+ *
+ * Canonical algorithm — Python/Go/Rust SDK implementations must produce
+ * byte-identical output for the same input (enforced by
+ * /fixtures/expected_outputs/security/).
+ */
+export function scrubUrl(url) {
+    if (!url)
+        return url;
+    const m = USERINFO_RE.exec(url);
+    if (m) {
+        url = m[1] + m[3];
+    }
+    let fragment = "";
+    const hashIdx = url.indexOf("#");
+    if (hashIdx >= 0) {
+        fragment = url.slice(hashIdx);
+        url = url.slice(0, hashIdx);
+    }
+    const qIdx = url.indexOf("?");
+    if (qIdx < 0)
+        return url + fragment;
+    const base = url.slice(0, qIdx);
+    const query = url.slice(qIdx + 1);
+    const parts = query.split("&").map((part) => {
+        const eqIdx = part.indexOf("=");
+        const name = eqIdx >= 0 ? part.slice(0, eqIdx) : part;
+        const lname = name.toLowerCase();
+        const sensitive = SENSITIVE_QUERY_PARAMS.has(lname) ||
+            lname.endsWith("-signature") ||
+            lname.endsWith("-credential") ||
+            lname.endsWith("-security-token");
+        return sensitive ? `${name}=REDACTED` : part;
+    });
+    return `${base}?${parts.join("&")}${fragment}`;
+}
+//# sourceMappingURL=redaction.js.map

package/dist/security/redaction.js.map

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

package/dist/transport/buffer.d.ts

@@ -0,0 +1,117 @@
+/**
+ * SQLite-backed event buffer for dexcost.
+ *
+ * Persists cost events and tasks to a local SQLite database using the exact
+ * same schema as the Python SDK. Data survives process restarts.
+ *
+ * Uses better-sqlite3 for synchronous, high-performance SQLite access.
+ */
+import type { CostEvent, Task } from "../core/models.js";
+/**
+ * SQLite-backed buffer that persists events and tasks across process restarts.
+ *
+ * Schema is identical to the Python SDK so both SDKs can share a database file.
+ * Costs are stored as TEXT strings to avoid floating-point precision loss.
+ */
+export declare class EventBuffer {
+    private _db;
+    private _mem;
+    /**
+     * Test-only seam. When `true`, the constructor takes the no-binding
+     * fallback path without attempting the require — used by
+     * tests/runtime-fallback.test.ts to simulate Vercel Edge / Cloudflare
+     * Workers behaviour without touching the real native module. Do NOT
+     * set this in production code. Sprint 1 Theme B / §2.2.3 (B8).
+     */
+    static _forceFallbackForTest: boolean;
+    constructor(dbPath?: string);
+    /**
+     * Add `column` to `table` if it does not already exist.
+     *
+     * SQLite has no `ADD COLUMN IF NOT EXISTS`, so a duplicate-column error
+     * is the expected signal that the migration has already been applied and
+     * is swallowed. Any other failure is also tolerated so init never crashes.
+     */
+    private _migrateAddColumn;
+    /**
+     * Add a cost event to the buffer with sync_status = 'pending'.
+     */
+    addEvent(event: CostEvent): void;
+    /**
+     * Insert or replace a task in the buffer.
+     *
+     * The task is (re)marked `sync_status = 'pending'`: an upsert means the
+     * task's data changed (new cost rolled up, status flipped, etc.), so it
+     * must be re-sent on the next push. `markTasksSynced` flips it to
+     * `'synced'` after a successful POST so unchanged tasks are not re-sent.
+     */
+    upsertTask(task: Task): void;
+    /**
+     * Return up to `limit` pending events, ordered by timestamp ASC.
+     */
+    getPendingEvents(limit?: number): CostEvent[];
+    /**
+     * Mark the given event IDs as synced.
+     */
+    markSynced(eventIds: string[]): void;
+    /**
+     * Retrieve a task by ID, or undefined if not found.
+     */
+    getTask(taskId: string): Task | undefined;
+    /**
+     * Return all tasks in the buffer.
+     */
+    getAllTasks(): Task[];
+    /**
+     * Return all tasks awaiting sync (`sync_status = 'pending'`).
+     *
+     * The pusher sends only these so unchanged tasks are not re-POSTed on
+     * every push cycle.
+     */
+    getPendingTasks(): Task[];
+    /**
+     * Mark the given task IDs as synced.
+     *
+     * Called by the pusher after a successful POST so the tasks are excluded
+     * from subsequent pushes until they are upserted again.
+     */
+    markTasksSynced(taskIds: string[]): void;
+    /** The number of tasks awaiting sync (`sync_status = 'pending'`). */
+    get pendingTaskCount(): number;
+    /**
+     * Return all events in the buffer (including synced).
+     */
+    getAllEvents(): CostEvent[];
+    /**
+     * Return events for a specific task, ordered by timestamp DESC.
+     */
+    queryEvents(taskId: string): CostEvent[];
+    /**
+     * Update all columns of an existing event in-place.
+     */
+    updateEvent(event: CostEvent): void;
+    /**
+     * Return the number of pending (unsynced) events.
+     */
+    get pendingCount(): number;
+    /**
+     * Delete synced events older than `retentionHours` and VACUUM.
+     *
+     * Returns the number of deleted rows.
+     */
+    purgeSynced(retentionHours?: number): number;
+    /**
+     * Delete pending events older than `maxAgeDays` and VACUUM.
+     *
+     * Safety net for events that can never be synced (rejected API key,
+     * permanently-down endpoint, etc.) so the local buffer cannot grow
+     * unbounded. Mirrors the Python SDK's `purge_old_pending` (default 7
+     * days). Returns the number of deleted rows.
+     */
+    purgeOldPending(maxAgeDays?: number): number;
+    /**
+     * Close the underlying database connection.
+     */
+    close(): void;
+}
+//# sourceMappingURL=buffer.d.ts.map

package/dist/transport/buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer.d.ts","sourceRoot":"","sources":["../../src/transport/buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAaH,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAqZzD;;;;;GAKG;AACH,qBAAa,WAAW;IAGtB,OAAO,CAAC,GAAG,CAA2B;IACtC,OAAO,CAAC,IAAI,CAAkC;IAE9C;;;;;;OAMG;IACH,MAAM,CAAC,qBAAqB,UAAS;gBAEzB,MAAM,CAAC,EAAE,MAAM;IAiF3B;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IASzB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IA4ChC;;;;;;;OAOG;IACH,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAkD5B;;OAEG;IACH,gBAAgB,CAAC,KAAK,GAAE,MAAY,GAAG,SAAS,EAAE;IAWlD;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI;IAcpC;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IASzC;;OAEG;IACH,WAAW,IAAI,IAAI,EAAE;IAOrB;;;;;OAKG;IACH,eAAe,IAAI,IAAI,EAAE;IASzB;;;;;OAKG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI;IAcxC,qEAAqE;IACrE,IAAI,gBAAgB,IAAI,MAAM,CAO7B;IAED;;OAEG;IACH,YAAY,IAAI,SAAS,EAAE;IAO3B;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE;IASxC;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAqDnC;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,CAOzB;IAED;;;;OAIG;IACH,WAAW,CAAC,cAAc,GAAE,MAAW,GAAG,MAAM;IAsBhD;;;;;;;OAOG;IACH,eAAe,CAAC,UAAU,GAAE,MAAU,GAAG,MAAM;IAoB/C;;OAEG;IACH,KAAK,IAAI,IAAI;CAKd"}