tapimo 0.0.0 → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# Tempo API
+
+## Overview
+
+The Tempo API is Tempo's next-generation data API. It is designed for
+clients that need a high-level surface for exploring the Tempo chain.
+
+## Usage
+
+The Tempo API is a composable [Hono](https://hono.dev) app. You can run your own
+instance (**Self-hosted**) or call the hosted API directly (**Hosted**).
+
+### Hosted
+
+Call the hosted Tempo API directly at `https://api.tempo.xyz`:
+
+```sh
+curl https://api.tempo.xyz/v1/tokens
+```
+
+```ts
+const response = await fetch('https://api.tempo.xyz/v1/tokens/0x…')
+const token = await response.json()
+```
+
+Explore the API interactively at the root [`/`](https://api.tempo.xyz).
+
+### Self-hosted
+
+Install the package:
+
+```sh
+pnpm i tapimo
+```
+
+Compose an app with `App.create`. It returns a handler with a Web `fetch`
+method and a Node.js `listener`, so you can serve it from any runtime or
+framework:
+
+<!-- prettier-ignore -->
+```ts
+import { App } from 'tapimo'
+
+const handler = App.create()
+
+createServer(handler.listener)                // Node.js
+Bun.serve({ fetch: handler.fetch })           // Bun
+Deno.serve({ fetch: handler.fetch })          // Deno
+app.all('*', (c) => handler.fetch(c.request)) // Elysia
+app.use(handler.listener)                     // Express
+app.use((c) => handler.fetch(c.req.raw))      // Hono
+export const GET = handler.fetch              // Next.js
+export const POST = handler.fetch             // Next.js
+```
+
+## Typed Client
+
+Use the typed client for endpoint autocomplete and API-key/header configuration:
+
+```ts twoslash
+import { Client } from 'tapimo'
+
+const client = Client.create({
+  // API key sugar for the canonical `tempo-api-key` header.
+  apiKey: 'tempo_api_key',
+  // Override the API URL. Defaults to `Client.defaultUrl`.
+  url: 'https://api.tempo.xyz',
+  // Or pass custom headers directly.
+  headers: { authorization: 'Bearer tempo_api_key' },
+})
+```
+
+Requests are end-to-end type-safe across params, statuses, response bodies, and errors. For example, `GET /v1/tokens/:token`:
+
+```ts twoslash
+const response = await client.v1.tokens[':token'].$get({
+  param: { token: '0x20c0000000000000000000000000000000000000' },
+})
+
+// Narrow responses by status
+if (response.status !== 200) {
+  response.status
+  //       ^? (property) status: 400 | 401 | 402 | 403 | 404 | 429 | 502
+
+  if (response.status === 404) {
+    const json = await response.json()
+    //    ^? const json: { error: { code: "token_not_found"; message: string; ... }; requestId: string }
+    json.error.code
+    //         ^? (property) code: "token_not_found"
+  } else if (response.status === 402) {
+    const challenge = await response.text()
+    //    ^? const challenge: string
+    // Handle the payment challenge from `WWW-Authenticate`.
+  } else {
+    const json = await response.json()
+    //    ^? const json: { error: { code: "query_invalid" | "api_key_invalid" | "upstream_error" | ...; ... }; requestId: string }
+    // Handle validation, auth, rate-limit, or upstream errors.
+  }
+
+  throw new Error('Request failed')
+}
+
+response.status
+//       ^? (property) status: 200
+const token = await response.json()
+//    ^? const token: { address: Hex.Hex; currency: string; decimals: number; name: string; ... }
+token.symbol
+//    ^? (property) symbol: string
+```
+
+## Development
+
+```sh
+pnpm install        # Install dependencies
+pnpm test           # Run tests
+pnpm app:dev        # Seed local KV (verified tokens) + run API app
+pnpm app:seed       # Seed local KV with curated verified tokens from seeds/
+```

package/dist/ApiKey.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The resolved API-key resource and the reusable credential primitives every
+ * source backend shares.
+ *
+ * Holds the resolved {@link ApiKey} type and its {@link schema}, the token
+ * format/generation ({@link generateToken}/{@link generateId}), the storage-key
+ * derivation ({@link keyFor}/{@link recordPrefix}), and log {@link redact}ion.
+ * These live here — not in a single source — so every `ApiKeySource` backend
+ * (the built-in store, a future D1/Postgres source) issues and parses
+ * byte-identical credentials and cannot drift. The persisted record/mint-input
+ * shapes and provisioning (mint/list/revoke) belong to the
+ * `ApiKeySource.Source` contract, which composes these primitives with its own
+ * persistence.
+ */
+import * as z from 'zod/mini';
+/** Zod schemas owned by the API-key module. */
+export declare namespace schema {
+    /**
+     * Canonical schema for resolved API-key metadata, and the single source of
+     * truth for the {@link ApiKey} type. `ApiKeySource` derives its persisted
+     * `Record` and `MintInput` schemas from this one, so the resolved and
+     * persisted shapes cannot drift.
+     */
+    const ApiKey: z.ZodMiniObject<{
+        environment: z.ZodMiniDefault<z.ZodMiniEnum<{
+            production: "production";
+            sandbox: "sandbox";
+        }>>;
+        id: z.ZodMiniString<string>;
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        orgId: z.ZodMiniString<string>;
+        rateLimits: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniObject<{
+            perMinute: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>>;
+        scopes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniEnum<{
+            "*": "*";
+            "data:read": "data:read";
+            "indexer:query": "indexer:query";
+            "webhooks:read": "webhooks:read";
+            "webhooks:write": "webhooks:write";
+        }>>>;
+    }, z.core.$strip>;
+}
+/** API-key metadata resolved by an auth source. */
+export type ApiKey = z.output<typeof schema.ApiKey>;
+/**
+ * Replaces every issued token in a string with a masked placeholder so secrets
+ * never reach logs. Apply to anything that may embed a credential — error
+ * stacks, request dumps, and the values of the `tempo-api-key` and
+ * `Authorization` headers (whose tokens match the issued-token pattern).
+ */
+export declare function redact(text: string): string;
+/**
+ * Generates a new plaintext token (environment prefix + 48 lowercase hex chars
+ * / 192 bits). Shared by every source backend so issued tokens are
+ * format-identical.
+ */
+export declare function generateToken(environment?: ApiKey['environment']): string;
+/** Generates a stable, opaque key id (`key_…`). */
+export declare function generateId(): string;
+/** Storage-key prefix under which key records are persisted, keyed by token hash. */
+export declare const recordPrefix = "apikey:";
+/** Storage key under which the record for a plaintext token is persisted. */
+export declare function keyFor(token: string): string;
+//# sourceMappingURL=ApiKey.d.ts.map

package/dist/ApiKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiKey.d.ts","sourceRoot":"","sources":["../src/ApiKey.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,CAAC,MAAM,UAAU,CAAA;AAK7B,+CAA+C;AAC/C,yBAAiB,MAAM,CAAC;IACtB;;;;;OAKG;IACI,MAAM,MAAM;;;;;;;;;;;;;;;;;;qBAiBjB,CAAA;CACH;AAED,mDAAmD;AACnD,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAA;AAEnD;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI3C;AAiCD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,WAAW,GAAE,MAAM,CAAC,aAAa,CAAgB,GAAG,MAAM,CAEvF;AAED,mDAAmD;AACnD,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,qFAAqF;AACrF,eAAO,MAAM,YAAY,YAAY,CAAA;AAOrC,6EAA6E;AAC7E,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5C"}

package/dist/ApiKey.js

@@ -0,0 +1,105 @@
+/**
+ * The resolved API-key resource and the reusable credential primitives every
+ * source backend shares.
+ *
+ * Holds the resolved {@link ApiKey} type and its {@link schema}, the token
+ * format/generation ({@link generateToken}/{@link generateId}), the storage-key
+ * derivation ({@link keyFor}/{@link recordPrefix}), and log {@link redact}ion.
+ * These live here — not in a single source — so every `ApiKeySource` backend
+ * (the built-in store, a future D1/Postgres source) issues and parses
+ * byte-identical credentials and cannot drift. The persisted record/mint-input
+ * shapes and provisioning (mint/list/revoke) belong to the
+ * `ApiKeySource.Source` contract, which composes these primitives with its own
+ * persistence.
+ */
+import { nanoid } from 'nanoid';
+import { Hash, Hex } from 'ox';
+import * as z from 'zod/mini';
+import * as RateLimit from './internal/RateLimit.js';
+import * as Scope from './Scope.js';
+/** Zod schemas owned by the API-key module. */
+export var schema;
+(function (schema) {
+    /**
+     * Canonical schema for resolved API-key metadata, and the single source of
+     * truth for the {@link ApiKey} type. `ApiKeySource` derives its persisted
+     * `Record` and `MintInput` schemas from this one, so the resolved and
+     * persisted shapes cannot drift.
+     */
+    schema.ApiKey = z.object({
+        environment: z
+            ._default(z.enum(['production', 'sandbox']), 'production')
+            .check(z.describe('Key environment.')),
+        id: z.string().check(z.describe('Stable key id.')),
+        name: z.optional(z.string()).check(z.describe('Human-readable key name.')),
+        orgId: z.string().check(z.describe('Owning organization id.')),
+        rateLimits: z
+            .optional(z.record(z.string(), RateLimit.schema.Limit))
+            .check(z.describe("Per-key quota overrides keyed by quota scope. The reserved '*' entry is the per-key default; any other key overrides that scope. Omit to inherit server config. The most specific match wins.")),
+        scopes: z
+            .readonly(z.array(z.enum([...Scope.catalog.map((entry) => entry.scope), Scope.wildcard])))
+            .check(z.describe("Granted scopes. '*' grants all scopes.")),
+    });
+})(schema || (schema = {}));
+/**
+ * Replaces every issued token in a string with a masked placeholder so secrets
+ * never reach logs. Apply to anything that may embed a credential — error
+ * stacks, request dumps, and the values of the `tempo-api-key` and
+ * `Authorization` headers (whose tokens match the issued-token pattern).
+ */
+export function redact(text) {
+    return text
+        .replace(tokenPattern(), (match) => `${match.split('sk:')[0]}sk:…`)
+        .replace(legacyTokenPattern(), 'tempo_…');
+}
+/**
+ * Token prefix per environment. The prefix encodes the environment so a leaked
+ * sandbox token is visibly distinct from a production one; otherwise there is a
+ * single token kind. Prefixes exist purely for recognizability and leak
+ * detection (CI secret scanning, log redaction — see {@link redact}).
+ */
+const tokenPrefix = {
+    production: 'tempo:sk:',
+    sandbox: 'tempo_sandbox:sk:',
+};
+/**
+ * Greppable pattern matching an issued token (`tempo:sk:`/`tempo_sandbox:sk:` +
+ * 48–64 lowercase hex chars), suitable for CI secret scanning and log
+ * redaction. A fresh instance is returned on each call so callers never share
+ * `lastIndex` state.
+ */
+function tokenPattern() {
+    return /tempo(_sandbox)?:sk:[a-f0-9]{48,64}/g;
+}
+/**
+ * Greppable pattern matching a deprecated v1 token (`tempo_` + 40 lowercase hex
+ * chars), kept so legacy credentials are redacted from logs with the same
+ * guarantees as current tokens. A fresh instance is returned on each call so
+ * callers never share `lastIndex` state.
+ */
+function legacyTokenPattern() {
+    return /tempo_[a-f0-9]{40}/g;
+}
+/**
+ * Generates a new plaintext token (environment prefix + 48 lowercase hex chars
+ * / 192 bits). Shared by every source backend so issued tokens are
+ * format-identical.
+ */
+export function generateToken(environment = 'production') {
+    return `${tokenPrefix[environment]}${Hex.random(24).slice(2)}`;
+}
+/** Generates a stable, opaque key id (`key_…`). */
+export function generateId() {
+    return `key_${nanoid()}`;
+}
+/** Storage-key prefix under which key records are persisted, keyed by token hash. */
+export const recordPrefix = 'apikey:';
+/** Hashes a plaintext token to its at-rest lookup hash (lowercase hex, no `0x`). */
+function hash(token) {
+    return Hash.sha256(Hex.fromString(token)).slice(2);
+}
+/** Storage key under which the record for a plaintext token is persisted. */
+export function keyFor(token) {
+    return `${recordPrefix}${hash(token)}`;
+}
+//# sourceMappingURL=ApiKey.js.map

package/dist/ApiKey.js.map

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

package/dist/ApiKeySource.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Pluggable API-key sources for Tempo API.
+ *
+ * Every backend implements one shared contract ({@link Source}) covering both
+ * the read path ({@link Source.resolve}, wired into `Auth.middleware`'s
+ * `apiKey.source`) and the provisioning path ({@link Source.mint}/{@link
+ * Source.list}/{@link Source.revoke}), so backends are interchangeable wherever a
+ * source is accepted. {@link store} is the built-in store-backed source (e.g. a
+ * Cloudflare KV namespace); {@link from} type-checks a bring-your-own backend
+ * (D1, Postgres, …) against the contract. The persisted {@link Record}/{@link
+ * MintInput} shapes live here (derived from `ApiKey.schema` so they cannot drift
+ * from the resolved shape), while the shared credential primitives (token
+ * format/generation, storage-key derivation, redaction) live in `./ApiKey.js`.
+ */
+import * as z from 'zod/mini';
+import * as ApiKey from './ApiKey.js';
+import type * as Store from './internal/Store.js';
+/** Zod schemas owned by the API-key source module. */
+export declare namespace schema {
+    /**
+     * Fields accepted when minting a key, and the single source of truth for the
+     * {@link MintInput} type and `mint` validation. Derived from the resolved
+     * `ApiKey.schema` (minus the generated `id`) so the scope vocabulary stays in
+     * lockstep with the resolved shape.
+     */
+    const MintInput: z.ZodMiniObject<{
+        environment: z.ZodMiniDefault<z.ZodMiniEnum<{
+            production: "production";
+            sandbox: "sandbox";
+        }>>;
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        rateLimits: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniObject<{
+            perMinute: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>>;
+        scopes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniEnum<{
+            "*": "*";
+            "data:read": "data:read";
+            "indexer:query": "indexer:query";
+            "webhooks:read": "webhooks:read";
+            "webhooks:write": "webhooks:write";
+        }>>>;
+        createdBy: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        expiresAt: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        orgId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>;
+    /**
+     * A persisted API-key record: the resolved `ApiKey.schema` plus
+     * persistence/display fields. Extending the resolved schema keeps the resolved
+     * and persisted shapes in lockstep.
+     */
+    const Record: z.ZodMiniObject<{
+        environment: z.ZodMiniDefault<z.ZodMiniEnum<{
+            production: "production";
+            sandbox: "sandbox";
+        }>>;
+        id: z.ZodMiniString<string>;
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        orgId: z.ZodMiniString<string>;
+        rateLimits: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniObject<{
+            perMinute: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>>;
+        scopes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniEnum<{
+            "*": "*";
+            "data:read": "data:read";
+            "indexer:query": "indexer:query";
+            "webhooks:read": "webhooks:read";
+            "webhooks:write": "webhooks:write";
+        }>>>;
+        createdAt: z.ZodMiniString<string>;
+        createdBy: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        expiresAt: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        tokenLast4: z.ZodMiniString<string>;
+    }, z.core.$strip>;
+}
+/**
+ * A durable API-key record as persisted by a source. A superset of the resolved
+ * `ApiKey.ApiKey` with provisioning/display metadata. The plaintext token is
+ * never stored — records are keyed by its hash (`ApiKey.keyFor`) and carry only
+ * `tokenLast4` for display.
+ */
+export type Record = z.output<typeof schema.Record>;
+/**
+ * Fields accepted when minting a key via {@link Source.mint}. Uses the schema's
+ * *input* type so defaulted fields (e.g. `environment`) are optional for callers
+ * — the default is applied during `mint`'s validation.
+ */
+export type MintInput = z.input<typeof schema.MintInput>;
+/** Result of {@link Source.mint}: the persisted record and its one-time token. */
+export type MintResult = {
+    /** The persisted key record (metadata only — never the token). */
+    record: Record;
+    /** The plaintext token, shown once and unrecoverable afterward. */
+    token: string;
+};
+/** Options for {@link Source.list}. */
+export type ListOptions = {
+    /** Restrict results to keys owned by this organization. */
+    orgId?: string | undefined;
+};
+/**
+ * The contract every pluggable API-key source implements — both the read path
+ * ({@link Source.resolve}, used by `Auth.middleware`'s `apiKey.source`) and the
+ * provisioning path ({@link Source.mint}/{@link Source.list}/{@link
+ * Source.revoke}). {@link store} is the built-in store-backed source; future
+ * database-backed sources (D1, Postgres, …) implement this same contract, so any
+ * backend stays interchangeable wherever a source is accepted.
+ */
+export type Source = {
+    /** Lists key records (metadata only — never tokens), newest first. */
+    list(options?: ListOptions): Promise<readonly Record[]>;
+    /**
+     * Mints a key: persists its hashed record and returns the record plus the
+     * one-time plaintext token (shown once, unrecoverable afterward).
+     */
+    mint(input: MintInput): Promise<MintResult>;
+    /** Resolves a plaintext API key token to its metadata, or `null`. */
+    resolve(token: string): Promise<ApiKey.ApiKey | null>;
+    /** Revokes a key by id. Returns whether a matching record was deleted. */
+    revoke(id: string): Promise<boolean>;
+};
+/**
+ * Creates a {@link Source} from a value, type-checking it against the contract.
+ * The escape hatch for bringing your own backend (D1, Postgres, …): author the
+ * implementation inline and have it validated against {@link Source}.
+ */
+export declare function from<const source extends Source>(source: source): source;
+/**
+ * The default {@link Source} when none is configured: it resolves every token to
+ * `null` and lists nothing, so API-key access stays closed until a real source
+ * (e.g. {@link store}) is wired in. Its provisioning methods are inert —
+ * {@link Source.list} returns `[]`, {@link Source.revoke} returns `false`, and
+ * {@link Source.mint} throws, since there is nowhere to persist a key.
+ */
+export declare const noop: Source;
+/**
+ * Creates a store-backed {@link Source} over a {@link Store.State}. Records are
+ * persisted keyed by token hash (`ApiKey.keyFor`) and validated against the
+ * scope catalog on read; unknown, corrupt, expired, or invalid records resolve
+ * to `null`. An `id → recordKey` index makes revoke-by-id O(1).
+ */
+export declare function store(state: Store.State): Source;
+/**
+ * Wraps a source with a short-TTL in-memory cache on the resolve path, so hot
+ * keys skip the backend read (e.g. a KV `get`) on every request. Positive
+ * results cache for `ttl` (default 60s), negative for `negativeTtl` (default
+ * 10s) so a freshly minted key is usable quickly; concurrent misses for one
+ * token are single-flighted. Entries are keyed by the token's storage-key
+ * derivation (`ApiKey.keyFor`, a sha256) — never the plaintext token.
+ *
+ * The cache is per-isolate, so a revoked key may stay resolvable elsewhere
+ * for up to `ttl` — the accepted trade-off for removing a backend read from
+ * the auth path of every request. Provisioning methods pass through uncached.
+ */
+export declare function cached(source: Source, options?: cached.Options): Source;
+export declare namespace cached {
+    /** Options for wrapping a source with a short-TTL resolve cache. */
+    type Options = {
+        /** Time-to-live for negative (`null`) results in milliseconds. */
+        negativeTtl?: number | undefined;
+        /** Clock used for expiry. */
+        now?: (() => number) | undefined;
+        /** Time-to-live for positive results in milliseconds. */
+        ttl?: number | undefined;
+    };
+}
+//# sourceMappingURL=ApiKeySource.d.ts.map

package/dist/ApiKeySource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiKeySource.d.ts","sourceRoot":"","sources":["../src/ApiKeySource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,CAAC,MAAM,UAAU,CAAA;AAE7B,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,KAAK,KAAK,MAAM,qBAAqB,CAAA;AAEjD,sDAAsD;AACtD,yBAAiB,MAAM,CAAC;IACtB;;;;;OAKG;IACI,MAAM,SAAS;;;;;;;;;;;;;;;;;;;qBASpB,CAAA;IAEF;;;;OAIG;IACI,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;qBAKjB,CAAA;CACH;AAED;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAA;AAEnD;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,SAAS,CAAC,CAAA;AAExD,kFAAkF;AAClF,MAAM,MAAM,UAAU,GAAG;IACvB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,uCAAuC;AACvC,MAAM,MAAM,WAAW,GAAG;IACxB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC3B,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,GAAG;IACnB,sEAAsE;IACtE,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAA;IACvD;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAC3C,qEAAqE;IACrE,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACrD,0EAA0E;IAC1E,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACrC,CAAA;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,KAAK,CAAC,MAAM,SAAS,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAExE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,EAAE,MAalB,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,MAAM,CA+DhD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,OAAY,GAAG,MAAM,CAsC3E;AAED,MAAM,CAAC,OAAO,WAAW,MAAM,CAAC;IAC9B,oEAAoE;IACpE,KAAK,OAAO,GAAG;QACb,kEAAkE;QAClE,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;QAChC,6BAA6B;QAC7B,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAA;QAChC,yDAAyD;QACzD,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KACzB,CAAA;CACF"}