@traceten/sdk-node 1.0.0

package/dist/queue.js

@@ -0,0 +1,232 @@
+/**
+ * Transport layer for the Traceten Node SDK.
+ *
+ * Owns the "one HTTP request, with retry" primitive that both queues share.
+ * Batching/chunking lives in the {@link Client}; this module only knows how to
+ * deliver a single already-shaped body to a single endpoint, retrying on
+ * transient failures per DESIGN.md §4.
+ *
+ * Retry policy:
+ *   - 2xx                       → success.
+ *   - 5xx or 429 or network/timeout → retryable; exponential backoff with full
+ *                                     jitter (`base 200ms * 2^attempt`), up to
+ *                                     `maxRetries` retries.
+ *   - other 4xx                 → the payload is malformed; DROP it and call
+ *                                 `onError`. Retrying a 400 forever is a
+ *                                 self-DoS.
+ */
+import { request } from "undici";
+/** Base backoff in ms — `delay ∈ [0, BASE * 2^attempt)` (full jitter). */
+const BASE_BACKOFF_MS = 200;
+/** Split `items` into contiguous chunks of at most `size`. */
+export function chunk(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size) {
+        out.push(items.slice(i, i + size));
+    }
+    return out;
+}
+/** Resolve after `ms` milliseconds. */
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const t = setTimeout(resolve, ms);
+        // Never let a pending backoff keep the process alive on its own.
+        if (typeof t === "object" && typeof t.unref === "function") {
+            t.unref();
+        }
+    });
+}
+/** Full-jitter exponential backoff for retry attempt `n` (0-indexed). */
+function backoffDelay(attempt) {
+    // Cap the exponent so a caller-supplied large maxRetries can't overflow into
+    // an absurd multi-hour sleep (mirrors the Go SDK's guard).
+    const exp = Math.min(attempt, 20);
+    return Math.random() * (BASE_BACKOFF_MS * 2 ** exp);
+}
+export class Transport {
+    eventsUrl;
+    conversionsUrl;
+    paymentsUrl;
+    headers;
+    maxRetries;
+    timeoutMs;
+    onError;
+    constructor(opts) {
+        // The AUTHENTICATED ingestion endpoints. `/v1/events` and
+        // `/v1/conversions` are still open — the browser snippet shares them and
+        // structurally cannot hold a secret — but a server SDK can, so it uses the
+        // door where the key is mandatory and gets its own rate-limit quota,
+        // isolated from the public per-site one.
+        this.eventsUrl = `${opts.host}/v1/server/events`;
+        this.conversionsUrl = `${opts.host}/v1/server/conversions`;
+        this.paymentsUrl = `${opts.host}/v1/server/payments`;
+        this.maxRetries = opts.maxRetries;
+        this.timeoutMs = opts.timeoutMs;
+        this.onError = opts.onError;
+        // Always sent. The Client validates the key's shape in its constructor, so
+        // an empty value can never reach here.
+        this.headers = {
+            "content-type": "application/json",
+            authorization: `Bearer ${opts.apiKey}`,
+        };
+    }
+    /** Send one `/v1/server/events` batch envelope. Never throws. */
+    async sendEvents(events) {
+        if (events.length === 0)
+            return;
+        await this.deliver(this.eventsUrl, JSON.stringify({ events }));
+    }
+    /** Send one `/v1/server/conversions` body (one event per request). Never throws. */
+    async sendConversion(conversion) {
+        await this.deliver(this.conversionsUrl, JSON.stringify(conversion));
+    }
+    /**
+     * Send one `/v1/server/payments` body and RETURN the outcome (#794).
+     *
+     * Unlike the two above, this one is awaited and its result surfaced: the
+     * endpoint's whole contract is the idempotency answer, so swallowing it would
+     * discard the one thing the caller asked for.
+     *
+     * Retrying is safe for the same reason — the server deduplicates on
+     * `(site, provider, transaction_id)` durably, so a retried 5xx cannot become a
+     * second payment.
+     *
+     * @throws when the payment was NOT accepted after every retry. `payment()` is
+     *   the only SDK call that rejects, because a silently dropped payment is
+     *   missing revenue rather than a missing pageview.
+     */
+    async sendPayment(payment) {
+        const body = JSON.stringify(payment);
+        const maxAttempts = this.maxRetries + 1;
+        let lastError = new Error("Traceten: payment was not sent");
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            const outcome = await this.attemptJson(this.paymentsUrl, body);
+            if (outcome.kind === "ok") {
+                return {
+                    status: outcome.status,
+                    transactionId: payment.transaction_id,
+                };
+            }
+            lastError = outcome.error;
+            if (outcome.kind === "drop")
+                break;
+            if (attempt < maxAttempts - 1)
+                await sleep(backoffDelay(attempt));
+        }
+        this.reportError(lastError);
+        throw lastError;
+    }
+    /** One attempt that also reads the JSON body, for the payments endpoint. */
+    async attemptJson(url, body) {
+        try {
+            const res = await request(url, {
+                method: "POST",
+                headers: this.headers,
+                body,
+                headersTimeout: this.timeoutMs,
+                bodyTimeout: this.timeoutMs,
+            });
+            const status = res.statusCode;
+            if (status >= 200 && status < 300) {
+                const parsed = (await res.body.json());
+                const known = ["recorded", "trial", "refunded", "duplicate"];
+                // An unrecognised status means the server is ahead of this SDK. Reported
+                // as `recorded` rather than thrown: the payment WAS accepted, and
+                // failing here would make the caller retry something already stored.
+                return {
+                    kind: "ok",
+                    status: (known.includes(parsed.status ?? "")
+                        ? parsed.status
+                        : "recorded"),
+                };
+            }
+            await res.body.dump();
+            if (status === 429 || status >= 500) {
+                return { kind: "retry", error: new Error(`Traceten payments responded ${status}`) };
+            }
+            return {
+                kind: "drop",
+                error: new Error(status === 401
+                    ? "Traceten payments rejected the request: the apiKey was not accepted " +
+                        "(missing, revoked, expired, or scoped to a different site)."
+                    : `Traceten payments rejected the payload with status ${status}`),
+            };
+        }
+        catch (err) {
+            return { kind: "retry", error: err instanceof Error ? err : new Error(String(err)) };
+        }
+    }
+    /**
+     * POST `body` to `url`, retrying transient failures. Resolves once the
+     * request either succeeds or is permanently given up on (after calling
+     * `onError`). Deliberately never rejects — `page()`/`track()`/`flush()` must
+     * not throw on network problems.
+     */
+    async deliver(url, body) {
+        const maxAttempts = this.maxRetries + 1;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            const outcome = await this.attempt(url, body);
+            if (outcome.kind === "ok")
+                return;
+            if (outcome.kind === "drop") {
+                this.reportError(outcome.error);
+                return;
+            }
+            // retryable — back off unless this was the final attempt.
+            if (attempt < maxAttempts - 1) {
+                await sleep(backoffDelay(attempt));
+                continue;
+            }
+            this.reportError(outcome.error);
+            return;
+        }
+    }
+    /** A single HTTP attempt, classified into an {@link Outcome}. */
+    async attempt(url, body) {
+        try {
+            const res = await request(url, {
+                method: "POST",
+                headers: this.headers,
+                body,
+                headersTimeout: this.timeoutMs,
+                bodyTimeout: this.timeoutMs,
+            });
+            const status = res.statusCode;
+            // Always drain the body so the socket can be released back to the pool.
+            await res.body.dump();
+            if (status >= 200 && status < 300) {
+                return { kind: "ok" };
+            }
+            if (status === 429 || status >= 500) {
+                return { kind: "retry", error: new Error(`Traceten ingest responded ${status}`) };
+            }
+            // 401 gets its own message. It is now by far the most likely 4xx — the
+            // key is mandatory — and "rejected the payload" points the reader at
+            // their event shape, which is exactly the wrong place to look when the
+            // real cause is a missing, revoked, expired, or wrong-site key.
+            return {
+                kind: "drop",
+                error: new Error(status === 401
+                    ? "Traceten ingest rejected the request: the apiKey was not accepted " +
+                        "(missing, revoked, expired, or scoped to a different site). " +
+                        "Check Settings -> API keys in the dashboard."
+                    : `Traceten ingest rejected the payload with status ${status}`),
+            };
+        }
+        catch (err) {
+            // Network error / DNS / timeout — all retryable.
+            const error = err instanceof Error ? err : new Error(String(err));
+            return { kind: "retry", error };
+        }
+    }
+    /** Invoke the user `onError` hook, swallowing any error it throws. */
+    reportError(error) {
+        try {
+            this.onError(error);
+        }
+        catch {
+            // An observability hook must never take down delivery.
+        }
+    }
+}
+//# sourceMappingURL=queue.js.map

package/dist/queue.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Public and wire-format types for the Traceten Node SDK.
+ *
+ * The two wire types (`EventWire`, `ConversionWire`) mirror the exact shapes
+ * validated by the ingestion Worker (`apps/workers/src/index.ts` —
+ * `EventPayloadSchema`, `ConversionPayloadSchema`). The events payload is
+ * camelCase; the conversions payload is snake_case. Do not "fix" the casing —
+ * it is the contract.
+ *
+ * The SDK posts to `/v1/server/events` and `/v1/server/conversions`: the same
+ * schemas and the same Kafka records as the open `/v1/events` and
+ * `/v1/conversions` routes the browser snippet uses, behind a mandatory
+ * `Authorization: Bearer` and an isolated rate-limit bucket (#725).
+ */
+/** Observability hook invoked when a payload is permanently dropped or errors. */
+export type OnError = (err: Error) => void;
+/**
+ * Constructor options for {@link Client}.
+ *
+ * `siteId`, `host` and `apiKey` are required; everything else has a documented
+ * default.
+ * See `DESIGN.md` §3.1 for the canonical, cross-language contract.
+ */
+export interface ClientOptions {
+    /**
+     * The site's PUBLIC site id (`snippet_key`) — the same value the browser
+     * snippet embeds. 1–64 chars, `^[A-Za-z0-9_-]+$`. It is an identifier, not a
+     * credential; {@link ClientOptions.apiKey} is the credential.
+     */
+    siteId: string;
+    /**
+     * Ingest base URL, e.g. `https://ingest.traceten.com`. Must be an absolute
+     * http(s) URL. A trailing slash is stripped. There is no hardcoded default —
+     * every deployment has its own Worker URL.
+     */
+    host: string;
+    /**
+     * REQUIRED. Sent as `Authorization: Bearer <apiKey>`.
+     *
+     * A secret — keep it server-side, never in client code or a public repo.
+     * Create one in the dashboard under Settings -> API keys, or take the key
+     * returned once when the site was created.
+     *
+     * The SDK posts to the authenticated endpoints (`/v1/server/events`,
+     * `/v1/server/conversions`), which return 401 without a valid key. In
+     * exchange, the traffic gets its own rate-limit quota, isolated from the
+     * shared per-site one that anyone holding the public `siteId` can consume.
+     *
+     * Validated for shape in the constructor, which throws — a missing key would
+     * otherwise produce an integration that buffers, flushes, 401s every batch,
+     * and looks healthy.
+     */
+    apiKey: string;
+    /**
+     * Flush the events queue once it reaches this many buffered events. Also the
+     * hard chunk cap for `/v1/server/events` batches. Clamped to `[1, 50]`. Default 50.
+     */
+    flushAt?: number;
+    /** Background flush cadence in milliseconds. Default 5000. */
+    flushInterval?: number;
+    /** Per-batch retry attempts on 5xx / 429 / network error. Default 3. */
+    maxRetries?: number;
+    /** Per-request timeout in milliseconds. Default 10000. */
+    timeoutMs?: number;
+    /** Called when a batch is permanently dropped. The SDK never throws here. */
+    onError?: OnError;
+    /**
+     * Register best-effort flush-on-exit hooks (`beforeExit`, `SIGTERM`,
+     * `SIGINT`). Default `true`. Set `false` in short-lived scripts or when the
+     * host process owns its own signal handling.
+     */
+    flushOnExit?: boolean;
+}
+/** Arguments to {@link Client.page}. */
+export interface PageProps {
+    /** Valid URL of the page/request. Required, ≤2048 chars. */
+    url: string;
+    /** Referrer URL. Defaults to `""`. */
+    referrer?: string;
+    /** Long-lived visitor id (UUID or `h:<64-hex>`). Maps to wire `vid`. */
+    visitorId?: string;
+    /** Opaque session token. */
+    sessionId?: string;
+    /** End-user User-Agent, if the server knows it. Maps to wire `ua`. */
+    userAgent?: string;
+    /** Event name. Defaults to `"pageview"`. Must match `^[a-z][a-z0-9_-]*$`. */
+    eventName?: string;
+    /** Event time. Defaults to now. Accepts a `Date` or ISO-8601 string. */
+    timestamp?: Date | string;
+}
+/** Arguments to {@link Client.track}. */
+export interface TrackOptions {
+    /** Long-lived visitor id (UUID or `h:<64-hex>`). REQUIRED for conversions. */
+    visitorId: string;
+    /** Arbitrary JSON properties. Defaults to `{}`. */
+    properties?: Record<string, unknown>;
+    /**
+     * Conversion value in integer minor units (cents). Maps to `value_cents`.
+     * Named `*Cents` to prevent the classic dollars-vs-cents mistake.
+     */
+    valueCents?: number;
+    /** ISO-4217 currency code. Lowercased before send. */
+    currency?: string;
+    /** Opaque session token. */
+    sessionId?: string;
+    /** Event time. Defaults to now. Accepts a `Date` or ISO-8601 string. */
+    timestamp?: Date | string;
+}
+/** Wire payload for `POST /v1/server/events` (camelCase — do not change casing). */
+export interface EventWire {
+    siteId: string;
+    ts: string;
+    url: string;
+    referrer: string;
+    eventName: string;
+    sessionId?: string;
+    vid?: string;
+    ua?: string;
+}
+/**
+ * Arguments to {@link Client.payment} (#794).
+ *
+ * `amount` is a DECIMAL in the currency's major unit — 49.99, or 5000 for
+ * ¥5000 — NOT minor units. Named `amount` rather than `amountCents` for exactly
+ * that reason: it is the number the merchant reads off their processor.
+ */
+export interface PaymentProps {
+    /** The processor's own id for this payment. The idempotency key. Required. */
+    transactionId: string;
+    /** Decimal, major unit, non-negative. `0` records a free trial. */
+    amount: number;
+    /** ISO-4217 code. Uppercased before send. */
+    currency: string;
+    /**
+     * Your label for the processor, e.g. `"dodo"`, `"polar"`, `"kajabi"`.
+     * Lowercase, 1-32 chars. Defaults to `"api"`.
+     *
+     * ⚠️ Do NOT use a label for a processor you have ALSO connected natively —
+     * both paths would record the same payment and revenue would double-count.
+     */
+    provider?: string;
+    /** Long-lived visitor id (UUID or `h:<64-hex>`). The strongest match. */
+    visitorId?: string;
+    /** Customer email. Hashed server-side for lookup; never stored. */
+    email?: string;
+    /** The processor's opaque customer token. */
+    customerId?: string;
+    /** A subscription renewal rather than a first payment. */
+    renewal?: boolean;
+    /** Records the payment as refunded. Never send a negative `amount`. */
+    refunded?: boolean;
+    /** Records a trial signup with no revenue. Implied by `amount: 0`. */
+    isFreeTrial?: boolean;
+    /** Payment time. Defaults to now. Accepts a `Date` or ISO-8601 string. */
+    timestamp?: Date | string;
+    /**
+     * The processor's OWN conversion of this payment into a currency Traceten
+     * can price (e.g. Dodo's `settlement_amount`, always USD/GBP/EUR) — a
+     * fallback used ONLY when {@link PaymentProps.currency} isn't one of the
+     * ~30 ECB publishes a reference rate for, so the payment doesn't have to be
+     * dropped. Decimal, major unit, like `amount`.
+     *
+     * Must be paired with {@link PaymentProps.settlementCurrency} — set one
+     * without the other and the SDK sends neither.
+     */
+    settlementAmount?: number;
+    /** ISO-4217 code for {@link PaymentProps.settlementAmount}. Uppercased before send. */
+    settlementCurrency?: string;
+}
+/** What the Payment API did with a payment. See {@link Client.payment}. */
+export type PaymentStatus = "recorded" | "trial" | "refunded" | "duplicate";
+/** Resolved value of {@link Client.payment}. */
+export interface PaymentResult {
+    /**
+     * `recorded` — attributed. `trial` — recorded with no revenue.
+     * `refunded` — the refund was noted. `duplicate` — already had this one.
+     *
+     * Only `recorded` and `trial` created anything new; the other two are the
+     * idempotent answers, and neither creates a second payment.
+     */
+    status: PaymentStatus;
+    transactionId: string;
+}
+/** Wire payload for `POST /v1/server/payments` (snake_case — do not change casing). */
+export interface PaymentWire {
+    site_id: string;
+    transaction_id: string;
+    amount: number;
+    currency: string;
+    provider?: string;
+    visitor_id?: string;
+    email?: string;
+    customer_id?: string;
+    renewal?: boolean;
+    refunded?: boolean;
+    is_free_trial?: boolean;
+    timestamp?: string;
+    settlement_amount?: number;
+    settlement_currency?: string;
+}
+/** Wire payload for `POST /v1/server/conversions` (snake_case — do not change casing). */
+export interface ConversionWire {
+    event_name: string;
+    site_id: string;
+    timestamp: string;
+    visitor_id: string;
+    properties: Record<string, unknown>;
+    session_id?: string;
+    value_cents?: number;
+    currency?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * Public and wire-format types for the Traceten Node SDK.
+ *
+ * The two wire types (`EventWire`, `ConversionWire`) mirror the exact shapes
+ * validated by the ingestion Worker (`apps/workers/src/index.ts` —
+ * `EventPayloadSchema`, `ConversionPayloadSchema`). The events payload is
+ * camelCase; the conversions payload is snake_case. Do not "fix" the casing —
+ * it is the contract.
+ *
+ * The SDK posts to `/v1/server/events` and `/v1/server/conversions`: the same
+ * schemas and the same Kafka records as the open `/v1/events` and
+ * `/v1/conversions` routes the browser snippet uses, behind a mandatory
+ * `Authorization: Bearer` and an isolated rate-limit bucket (#725).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/validate.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Client-side validation for the Traceten Node SDK.
+ *
+ * Philosophy (see DESIGN.md §5): programmer errors surface *loudly and
+ * synchronously* at call time — a mis-shaped call is a bug you want to find in
+ * development, not a silent server-side 422 buried in logs. Delivery failures,
+ * by contrast, never throw (they go through `onError`).
+ *
+ * Every regex here is copied verbatim from the ingestion Worker
+ * (`apps/workers/src/index.ts`) so the client rejects exactly what the server
+ * would reject — never more, never less.
+ */
+/**
+ * Validate the constructor `siteId`. Throws synchronously on a bad value —
+ * a wrong site id means every event silently 422s server-side.
+ */
+export declare function validateSiteId(siteId: unknown): string;
+/**
+ * Validate the constructor `apiKey`.
+ *
+ * REQUIRED since the SDK moved to `/v1/server/*` — that endpoint rejects an
+ * unauthenticated request with 401, so a missing key means every event is
+ * silently dropped server-side. Failing loudly in the constructor is the whole
+ * point: the alternative is a production integration that looks healthy and
+ * records nothing.
+ *
+ * Only the SHAPE is checked here. Whether the key is live, unrevoked and
+ * scoped to `siteId` is a server-side question, answered per request.
+ */
+export declare function validateApiKey(apiKey: unknown): string;
+/**
+ * Validate + normalize the constructor `host`: absolute http(s) URL, trailing
+ * slash stripped. Throws on anything else.
+ */
+export declare function normalizeHost(host: unknown): string;
+/** Validate the `page()` url: valid URL, ≤2048 chars. */
+export declare function validateUrl(url: unknown): string;
+/** Validate a `/v1/events` `eventName`. */
+export declare function validateEventName(name: unknown): string;
+/** Validate a `/v1/conversions` `event_name` (stricter — no hyphen). */
+export declare function validateConversionName(name: unknown): string;
+/**
+ * Goal names the Stripe/Shopify pipeline emits. `goal()` refuses them because a
+ * collision silently corrupts the site's revenue funnel; `track()` still accepts
+ * them, since that is how those events are legitimately sent.
+ *
+ * Mirrors RESERVED_GOAL_NAMES in Traceten's shared contract.
+ */
+export declare const RESERVED_GOAL_NAMES: readonly ["payment", "free_trial", "trial_started", "trial_converted", "subscription_started", "subscription_upgraded", "subscription_downgraded", "subscription_renewed", "subscription_cancel_scheduled", "subscription_reactivated", "subscription_ended"];
+/** Validate a `goal()` name: a conversion name that is not reserved. */
+export declare function validateGoalName(name: unknown): string;
+/** Validate a visitor id against the shared UUID | `h:<hash>` format. */
+export declare function validateVisitorId(vid: unknown): string;
+/** Validate an `/v1/events` `sessionId` (charset-restricted, ≤128). */
+export declare function validateEventSessionId(sessionId: unknown): string;
+/** Validate a `/v1/conversions` `session_id` (length only, ≤128). */
+export declare function validateConversionSessionId(sessionId: unknown): string;
+/** Validate a User-Agent string (≤512). */
+export declare function validateUserAgent(ua: unknown): string;
+/** Validate a referrer string (≤2048). */
+export declare function validateReferrer(referrer: unknown): string;
+/** Validate `valueCents`: a non-negative integer (minor units). */
+export declare function validateValueCents(value: unknown): number;
+/**
+ * Lowercase + validate an ISO-4217 currency code.
+ *
+ * The lowercasing is a CLIENT-SIDE normalisation only, and deliberately kept
+ * (#793): Traceten uppercases at every server boundary, so the case sent here
+ * does not reach storage. Do not read this as the wire format — stored and
+ * returned codes are uppercase.
+ */
+export declare function normalizeCurrency(currency: unknown): string;
+/** Validate the processor's transaction id — the Payment API idempotency key. */
+export declare function validateTransactionId(value: unknown): string;
+/**
+ * Validate a payment amount: a finite, non-negative DECIMAL in the major unit.
+ *
+ * Not integer cents, unlike `valueCents` — see {@link PaymentProps.amount}. A
+ * negative is rejected outright because a refund is the `refunded` flag; the
+ * server stores revenue as an unsigned integer and could not hold one anyway.
+ */
+export declare function validateAmount(value: unknown): number;
+/** Validate the optional Payment API `provider` label. */
+export declare function validateProvider(value: unknown): string;
+/**
+ * Uppercase + validate an ISO-4217 code for the Payment API.
+ *
+ * Uppercase, unlike {@link normalizeCurrency}: this endpoint is newer than the
+ * conversions one and there is no legacy lowercase behaviour to preserve, so it
+ * sends the case the server actually stores.
+ */
+export declare function normalizePaymentCurrency(currency: unknown): string;
+/**
+ * Normalize a caller-supplied timestamp to an ISO-8601 UTC string (the format
+ * the ingest Worker's `z.string().datetime()` accepts). An invalid `Date` or
+ * unparseable string is a programmer error and throws.
+ */
+export declare function toIsoTimestamp(value?: Date | string): string;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA+BH;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAQtD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAWtD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAgCnD;AAeD,yDAAyD;AACzD,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAmBhD;AAED,2CAA2C;AAC3C,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAQvD;AAED,wEAAwE;AACxE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAQ5D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,+PAYtB,CAAC;AAEX,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAStD;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAKtD;AAED,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAQjE;AAED,qEAAqE;AACrE,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAKtE;AAED,2CAA2C;AAC3C,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAKrD;AAED,0CAA0C;AAC1C,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAK1D;AAED,mEAAmE;AACnE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKzD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAS3D;AAKD,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAK5D;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKrD;AAED,0DAA0D;AAC1D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKvD;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CASlE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAkB5D"}