@goable-io/sdk 0.1.0

package/README.md

@@ -0,0 +1,121 @@
+# @goable-io/sdk
+
+TypeScript client for the [Goable](https://goable.io) API — 0-100 suitability
+scoring for outdoor activities (water, snow, air, land) from real-time weather
+and multi-domain physics.
+
+> **Status: v0.1, publish-ready (not yet on npm).** Thin, typed transport over
+> the public tenant-facing REST surface. Zero runtime dependencies. Works in
+> Node ≥18 and modern browser/edge runtimes (uses the global `fetch`).
+
+## Install
+
+```bash
+npm install @goable-io/sdk   # once published
+```
+
+## Quickstart
+
+```ts
+import { GoableClient } from "@goable-io/sdk"
+
+const goable = new GoableClient({ apiKey: process.env.GOABLE_API_KEY! })
+
+const result = await goable.score({
+  activity: "kitesurfing",
+  location: { lat: 43.7, lng: 7.27 },
+  window: { from: "2026-06-01T06:00:00Z", to: "2026-06-01T18:00:00Z" },
+})
+
+result.score    // 0-100
+result.verdict  // "unsafe" | "poor" | "marginal" | "fair" | "favorable" | "excellent"
+result.confidence
+```
+
+## Configuration
+
+```ts
+new GoableClient({
+  apiKey: "…",                    // required — sent as Authorization: Bearer
+  baseUrl: "https://api.goable.io", // default
+  timeoutMs: 30_000,               // default; 0 disables
+  fetch: customFetch,              // default globalThis.fetch (inject for Node <18 / tests)
+})
+```
+
+## Methods
+
+| Method | Endpoint | Notes |
+|---|---|---|
+| `score(input)` | `POST /v1/score` | `ensemble: true` → probabilistic (Pro+) |
+| `scoreSeries(input)` | `POST /v1/score/series` | per-step over a window |
+| `scoreMulti(input)` | `POST /v1/score/multi` | many activities, one location |
+| `scoreHistorical(input)` | `POST /v1/score/historical` | climatology percentiles (Pro+) |
+| `scorePortfolio(input)` | `POST /v1/score/portfolio` | multi-spot joint variance |
+| `explainCounterfactual(input)` | `POST /v1/score/explain-counterfactual` | binding constraint, sensitivities, best window/spot |
+| `decision(input)` | `POST /v1/decision` | personalized go/no-go (Pro+) |
+| `deleteUserData(pseudonym)` | `DELETE /v1/decision/user-data/:p` | GDPR erasure; returns receipt headers |
+| `explain(input)` / `briefing(input)` | `POST /v1/intelligence/*` | LLM narratives (Pro+) |
+| `projections(input)` | `POST /v1/projections` | climate-decadal (Scale) |
+| `quote(input)` | `POST /v1/underwriting/quote` | parametric premium (Scale) |
+| `health()` | `GET /v1/health` | liveness |
+
+## Errors
+
+```ts
+import { GoableApiError, GoableNetworkError } from "@goable-io/sdk"
+
+try {
+  await goable.score({ activity: "kitesurfing", location: { lat: 43.7, lng: 7.27 }, ensemble: true })
+} catch (err) {
+  if (err instanceof GoableApiError) {
+    err.status  // 402
+    err.code    // "PAYMENT_REQUIRED"
+    err.issues  // Zod issues on 422 VALIDATION_ERROR
+    err.detail  // free-form context (e.g. plan info)
+  } else if (err instanceof GoableNetworkError) {
+    err.kind    // "timeout" | "network" | "parse"
+  }
+}
+```
+
+## Browser use
+
+The client runs in the browser, but **API keys are secrets** — prefer
+server-side use. For direct browser calls the API's CORS allowlist must
+include your origin (contact Goable to allowlist it).
+
+## Types are generated from the API contract
+
+The request/response types are **generated** from the API's OpenAPI
+document (`apps/api/src/openapi/spec.ts`) via
+[`openapi-typescript`](https://github.com/openapi-ts/openapi-typescript) —
+they are never hand-authored, so they can't drift from the server. When the
+API contract changes, a maintainer runs:
+
+```bash
+pnpm --filter @goable-io/sdk gen
+```
+
+which rewrites `src/generated/api.ts` + `openapi.json`. A test
+(`generatedFresh.test.ts`) fails in CI if the committed output is stale, so
+the types are always in lock-step with the contract. Adding a brand-new
+endpoint is the only manual step (a new client method).
+
+Request types are precise (the API rejects unknown fields). Some response
+bodies are modelled as open objects where the endpoint returns a rich,
+documented payload — the full wire payload is always returned, and these
+tighten automatically as the OpenAPI response schemas are enriched.
+
+## Release (maintainers)
+
+Publishing is automated by `.github/workflows/sdk-release.yml` (on changes
+to `packages/sdk/**` on `main`): it builds, runs the freshness guard +
+tests, resolves the next version, prints `npm pack --dry-run` as a leak
+check, and `pnpm publish --access public` using the org `NPM_TOKEN`. The
+private engine never leaves the repo — only this package's `files` are
+published. `publishConfig` repoints `main`/`types`/`exports` at `dist/` at
+publish time, so in-repo development keeps using the TS sources.
+
+> No npm provenance: it requires a public source repo, and the SDK source
+> stays in this private monorepo by design.

package/dist/client.d.ts

@@ -0,0 +1,52 @@
+/**
+ * GoableClient — thin typed transport over the public Goable REST API.
+ * No caching, no business logic; one `request<T>` powers every method.
+ */
+import type { BriefingRequest, BriefingResponse, CounterfactualRequest, CounterfactualResponse, DecisionRequest, DecisionResponse, DeleteUserDataResult, ExplainRequest, ExplainResponse, HealthResponse, ProjectionsRequest, ProjectionsResponse, QuoteRequest, QuoteResponse, ScoreHistoricalRequest, ScoreHistoricalResponse, ScoreMultiRequest, ScoreMultiResponse, ScorePortfolioRequest, ScorePortfolioResponse, ScoreRequest, ScoreResponse, ScoreSeriesRequest, ScoreSeriesResponse } from "./types.js";
+export type FetchLike = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}>;
+export interface GoableClientOptions {
+    /** Tenant API key — sent as `Authorization: Bearer <apiKey>`. */
+    apiKey: string;
+    /** Base URL. Default https://api.goable.io */
+    baseUrl?: string;
+    /** Injected fetch (tests, non-global-fetch runtimes). Default globalThis.fetch. */
+    fetch?: FetchLike;
+    /** Per-request timeout in ms. Default 30000. 0 disables. */
+    timeoutMs?: number;
+}
+export declare class GoableClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(options: GoableClientOptions);
+    health(): Promise<HealthResponse>;
+    score(input: ScoreRequest): Promise<ScoreResponse>;
+    scoreSeries(input: ScoreSeriesRequest): Promise<ScoreSeriesResponse>;
+    scoreMulti(input: ScoreMultiRequest): Promise<ScoreMultiResponse>;
+    scoreHistorical(input: ScoreHistoricalRequest): Promise<ScoreHistoricalResponse>;
+    scorePortfolio(input: ScorePortfolioRequest): Promise<ScorePortfolioResponse>;
+    explainCounterfactual(input: CounterfactualRequest): Promise<CounterfactualResponse>;
+    decision(input: DecisionRequest): Promise<DecisionResponse>;
+    explain(input: ExplainRequest): Promise<ExplainResponse>;
+    briefing(input: BriefingRequest): Promise<BriefingResponse>;
+    projections(input: ProjectionsRequest): Promise<ProjectionsResponse>;
+    quote(input: QuoteRequest): Promise<QuoteResponse>;
+    /** GDPR Art. 17 erasure. Surfaces the receipt headers from a 204. */
+    deleteUserData(pseudonym: string): Promise<DeleteUserDataResult>;
+    private request;
+    private rawRequest;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,sBAAsB,EACtB,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,YAAY,CAAA;AAEnB,MAAM,MAAM,SAAS,GAAG,CACtB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IACL,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,KACE,OAAO,CAAC;IACX,EAAE,EAAE,OAAO,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAA;IAC7C,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CACxB,CAAC,CAAA;AAEF,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAA;IACd,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,mFAAmF;IACnF,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAKD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;gBAEtB,OAAO,EAAE,mBAAmB;IAaxC,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;IAIjC,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAIlD,WAAW,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAIpE,UAAU,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIjE,eAAe,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAIhF,cAAc,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAI7E,qBAAqB,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAIpF,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAI3D,OAAO,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAIxD,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAI3D,WAAW,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAIpE,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAIlD,qEAAqE;IAC/D,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;YAsBxD,OAAO;YAOP,UAAU;CA+BzB"}

package/dist/client.js

@@ -0,0 +1,134 @@
+/**
+ * GoableClient — thin typed transport over the public Goable REST API.
+ * No caching, no business logic; one `request<T>` powers every method.
+ */
+import { GoableNetworkError, toApiError } from "./errors.js";
+const DEFAULT_BASE_URL = "https://api.goable.io";
+const DEFAULT_TIMEOUT_MS = 30_000;
+export class GoableClient {
+    apiKey;
+    baseUrl;
+    fetchImpl;
+    timeoutMs;
+    constructor(options) {
+        if (!options.apiKey)
+            throw new Error("GoableClient requires an apiKey");
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        const f = options.fetch ?? globalThis.fetch;
+        if (!f) {
+            throw new Error("No fetch available — pass options.fetch (Node < 18 or non-fetch runtime)");
+        }
+        this.fetchImpl = f;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    // ── public methods ──────────────────────────────────────────────────────
+    health() {
+        return this.request("GET", "/v1/health");
+    }
+    score(input) {
+        return this.request("POST", "/v1/score", input);
+    }
+    scoreSeries(input) {
+        return this.request("POST", "/v1/score/series", input);
+    }
+    scoreMulti(input) {
+        return this.request("POST", "/v1/score/multi", input);
+    }
+    scoreHistorical(input) {
+        return this.request("POST", "/v1/score/historical", input);
+    }
+    scorePortfolio(input) {
+        return this.request("POST", "/v1/score/portfolio", input);
+    }
+    explainCounterfactual(input) {
+        return this.request("POST", "/v1/score/explain-counterfactual", input);
+    }
+    decision(input) {
+        return this.request("POST", "/v1/decision", input);
+    }
+    explain(input) {
+        return this.request("POST", "/v1/intelligence/explain", input);
+    }
+    briefing(input) {
+        return this.request("POST", "/v1/intelligence/briefing", input);
+    }
+    projections(input) {
+        return this.request("POST", "/v1/projections", input);
+    }
+    quote(input) {
+        return this.request("POST", "/v1/underwriting/quote", input);
+    }
+    /** GDPR Art. 17 erasure. Surfaces the receipt headers from a 204. */
+    async deleteUserData(pseudonym) {
+        const res = await this.rawRequest("DELETE", `/v1/decision/user-data/${encodeURIComponent(pseudonym)}`);
+        if (!res.ok) {
+            throw toApiError(res.status, await safeJson(res));
+        }
+        const intHeader = (name) => {
+            const v = res.headers.get(name);
+            const n = v === null ? Number.NaN : Number(v);
+            return Number.isFinite(n) ? n : null;
+        };
+        return {
+            status: res.status,
+            anonymizedRows: intHeader("X-Anonymized-Rows"),
+            anonymizedDecisionRuns: intHeader("X-Anonymized-Decision-Runs"),
+            receipt: res.headers.get("X-Receipt"),
+        };
+    }
+    // ── transport ─────────────────────────────────────────────────────────────
+    async request(method, path, body) {
+        const res = await this.rawRequest(method, path, body);
+        const parsed = await safeJson(res);
+        if (!res.ok)
+            throw toApiError(res.status, parsed);
+        return parsed;
+    }
+    async rawRequest(method, path, body) {
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+        };
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        const controller = this.timeoutMs > 0 ? new AbortController() : undefined;
+        const timer = controller && this.timeoutMs > 0
+            ? setTimeout(() => controller.abort(), this.timeoutMs)
+            : undefined;
+        try {
+            return await this.fetchImpl(`${this.baseUrl}${path}`, {
+                method,
+                headers,
+                ...(body !== undefined && { body: JSON.stringify(body) }),
+                ...(controller && { signal: controller.signal }),
+            });
+        }
+        catch (err) {
+            const aborted = err?.name === "AbortError";
+            throw new GoableNetworkError(aborted ? `Request timed out after ${this.timeoutMs}ms` : `Network request failed: ${path}`, aborted ? "timeout" : "network", err);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+}
+async function safeJson(res) {
+    let text;
+    try {
+        text = await res.text();
+    }
+    catch (err) {
+        throw new GoableNetworkError("Failed to read response body", "parse", err);
+    }
+    if (text === "")
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * SDK error model. Two distinct failure modes:
+ *   - GoableApiError    : the API returned a non-2xx response. Maps the
+ *                         canonical flat error envelope
+ *                         ({ error, message?, issues?, detail? }).
+ *   - GoableNetworkError: the request never produced an HTTP response
+ *                         (DNS, connection, abort/timeout, JSON parse).
+ */
+export interface ZodIssueLike {
+    code?: string;
+    path?: Array<string | number>;
+    message?: string;
+    [k: string]: unknown;
+}
+export declare class GoableApiError extends Error {
+    readonly name = "GoableApiError";
+    /** HTTP status code. */
+    readonly status: number;
+    /** Machine-readable code from the `error` field (e.g. "PAYMENT_REQUIRED"). */
+    readonly code: string;
+    /** Zod validation issues, present on 422 VALIDATION_ERROR responses. */
+    readonly issues?: ZodIssueLike[];
+    /** Free-form extra context (e.g. plan info, quote id). */
+    readonly detail?: Record<string, unknown>;
+    constructor(status: number, code: string, message?: string, extra?: {
+        issues?: ZodIssueLike[];
+        detail?: Record<string, unknown>;
+    });
+}
+export declare class GoableNetworkError extends Error {
+    readonly name = "GoableNetworkError";
+    /** "timeout" when the request was aborted by the configured timeout. */
+    readonly kind: "timeout" | "network" | "parse";
+    readonly cause?: unknown;
+    constructor(message: string, kind: "timeout" | "network" | "parse", cause?: unknown);
+}
+/** Map a parsed error body + status into a GoableApiError. Tolerant of a
+ *  non-conforming body (falls back to the status code as the error code). */
+export declare function toApiError(status: number, body: unknown): GoableApiError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAA;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CACrB;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAkB,IAAI,oBAAmB;IACzC,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,CAAA;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;gBAGvC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE;CAUxE;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAkB,IAAI,wBAAuB;IAC7C,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAAA;IAC9C,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAA;gBAErB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,EAAE,KAAK,CAAC,EAAE,OAAO;CAMpF;AASD;6EAC6E;AAC7E,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,cAAc,CAQxE"}

package/dist/errors.js

@@ -0,0 +1,57 @@
+/**
+ * SDK error model. Two distinct failure modes:
+ *   - GoableApiError    : the API returned a non-2xx response. Maps the
+ *                         canonical flat error envelope
+ *                         ({ error, message?, issues?, detail? }).
+ *   - GoableNetworkError: the request never produced an HTTP response
+ *                         (DNS, connection, abort/timeout, JSON parse).
+ */
+export class GoableApiError extends Error {
+    name = "GoableApiError";
+    /** HTTP status code. */
+    status;
+    /** Machine-readable code from the `error` field (e.g. "PAYMENT_REQUIRED"). */
+    code;
+    /** Zod validation issues, present on 422 VALIDATION_ERROR responses. */
+    issues;
+    /** Free-form extra context (e.g. plan info, quote id). */
+    detail;
+    constructor(status, code, message, extra) {
+        super(message ?? code);
+        this.status = status;
+        this.code = code;
+        if (extra?.issues)
+            this.issues = extra.issues;
+        if (extra?.detail)
+            this.detail = extra.detail;
+        // Restore prototype chain for `instanceof` across transpilation targets.
+        Object.setPrototypeOf(this, GoableApiError.prototype);
+    }
+}
+export class GoableNetworkError extends Error {
+    name = "GoableNetworkError";
+    /** "timeout" when the request was aborted by the configured timeout. */
+    kind;
+    cause;
+    constructor(message, kind, cause) {
+        super(message);
+        this.kind = kind;
+        if (cause !== undefined)
+            this.cause = cause;
+        Object.setPrototypeOf(this, GoableNetworkError.prototype);
+    }
+}
+/** Map a parsed error body + status into a GoableApiError. Tolerant of a
+ *  non-conforming body (falls back to the status code as the error code). */
+export function toApiError(status, body) {
+    const b = (body ?? {});
+    const code = typeof b.error === "string" ? b.error : `HTTP_${status}`;
+    const message = typeof b.message === "string" ? b.message : undefined;
+    const extra = {};
+    if (Array.isArray(b.issues))
+        extra.issues = b.issues;
+    if (b.detail && typeof b.detail === "object")
+        extra.detail = b.detail;
+    return new GoableApiError(status, code, message, extra);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACrB,IAAI,GAAG,gBAAgB,CAAA;IACzC,wBAAwB;IACf,MAAM,CAAQ;IACvB,8EAA8E;IACrE,IAAI,CAAQ;IACrB,wEAAwE;IAC/D,MAAM,CAAiB;IAChC,0DAA0D;IACjD,MAAM,CAA0B;IAEzC,YACE,MAAc,EACd,IAAY,EACZ,OAAgB,EAChB,KAAqE;QAErE,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,CAAA;QACtB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,KAAK,EAAE,MAAM;YAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAA;QAC7C,IAAI,KAAK,EAAE,MAAM;YAAE,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAA;QAC7C,yEAAyE;QACzE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,cAAc,CAAC,SAAS,CAAC,CAAA;IACvD,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IACzB,IAAI,GAAG,oBAAoB,CAAA;IAC7C,wEAAwE;IAC/D,IAAI,CAAiC;IAC5B,KAAK,CAAU;IAEjC,YAAY,OAAe,EAAE,IAAqC,EAAE,KAAe;QACjF,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;QAC3C,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAA;IAC3D,CAAC;CACF;AASD;6EAC6E;AAC7E,MAAM,UAAU,UAAU,CAAC,MAAc,EAAE,IAAa;IACtD,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAiB,CAAA;IACtC,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,MAAM,EAAE,CAAA;IACrE,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAA;IACrE,MAAM,KAAK,GAAkE,EAAE,CAAA;IAC/E,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;QAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,MAAwB,CAAA;IACtE,IAAI,CAAC,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ;QAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,MAAiC,CAAA;IAChG,OAAO,IAAI,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,CAAA;AACzD,CAAC"}