@cliwant/mcp-sam-gov 1.2.0 → 1.4.0

package/dist/openfda-device.js

@@ -0,0 +1,277 @@
+/**
+ * openfda-device.ts — openFDA 510(k) DEVICE CLEARANCES (api.fda.gov) — the
+ * MEDICAL-DEVICE REGULATORY lane (ADR-0056). The FDA's premarket-notification
+ * (510(k)) clearances: the applicant, the device, the clearance number (K-number),
+ * the decision (date + description), the clearance type, the product code, the
+ * advisory committee, and geography.
+ *
+ * ★ THIS IS THE SAME SOURCE + ENVELOPE + CRUX as openfda.ts (ADR-0054). Same host
+ *   (api.fda.gov), same response envelope `{ meta:{ results:{ skip, limit, total }},
+ *   results:[…] }`, same ★no-match→HTTP-404-NOT_FOUND-as-honest-empty crux, same
+ *   optional query-key K-test, same fixed-host SSRF idiom, same structured-only
+ *   (no raw Lucene passthrough) search assembly. It REUSES openfda.ts's `fetchOpenfda`
+ *   (the SSRF-guarded classified fetch) and `readOpenfdaError` (the error-body reader)
+ *   verbatim — the 404-reclassification logic is NOT reinvented — plus `luceneQuote`
+ *   (the phrase-escape), `openfdaApiKey` (the optional-key env seam), and `OPENFDA_HOST`.
+ *
+ *   GET https://api.fda.gov/device/510k.json
+ *       ?search=<lucene>&limit=<1..100>&skip=<offset>[&api_key=<KEY>]
+ *   → { meta:{ disclaimer, results:{ skip, limit, total }}, results:[ {…} ] }
+ *     (live total ~175507).
+ *
+ * ★ HONESTY (mirrors openfda.ts exactly):
+ *   [P1]  totalAvailable = `meta.results.total` EXACT (e.g. 175507), NEVER
+ *         results.length. skip/limit offset pagination:
+ *         hasMore = skip + returned < total; nextOffset = hasMore ? skip+returned : null.
+ *   [★P2] a 404 whose body is `{error:{code:"NOT_FOUND"}}` (a no-match query OR an
+ *         unknown field) ⇒ HONEST EMPTY (returned:0, totalAvailable:0) — NOT thrown,
+ *         NOT not_found. Any OTHER 4xx (e.g. a 400 syntax error) ⇒ invalid_input
+ *         surfacing openFDA's message. 5xx/timeout ⇒ upstream_unavailable THROW. A
+ *         200 non-JSON body ⇒ schema_drift. (Reuses openfda.ts's exact fetch path.)
+ *   [P3]  dates (`decision_date`, YYYY-MM-DD) and every scalar surfaced as a STRING
+ *         via `str` (null-never-empty-string) — no numeric coercion; never fabricated.
+ *   [P4]  `meta.results` or `results` absent / non-array ⇒ driftError (never a
+ *         fabricated empty).
+ *   [K-test] OPTIONAL OPENFDA_API_KEY: when set it rides `&api_key=` ONLY (openFDA has
+ *         no header option — the query-key is inherent). Mitigation: the `label` is
+ *         host+path ONLY (`openfda:/device/510k`, NO query), so no token reaches
+ *         ToolError.upstreamEndpoint; `_meta.source` names the MODE only; the key is
+ *         ABSENT from the serialized {data,_meta}, notes, and any log. Unset ⇒ keyless.
+ *   [SSRF] fixed host `api.fda.gov` (fetchOpenfda asserts hostname/protocol +
+ *         redirect:"error"); all filter VALUES are Lucene-escaped + phrase-quoted and
+ *         ride URLSearchParams `search=`; limit/skip are integers; state is charclass
+ *         `^[A-Za-z]{2}$`. No raw Lucene passthrough — structured only, injection-safe.
+ */
+import { ToolErrorCarrier, errorFromResponse } from "./errors.js";
+import { driftError } from "./datasource.js";
+import { str } from "./coerce.js";
+import { withMeta } from "./meta.js";
+import { OPENFDA_HOST, fetchOpenfda, readOpenfdaError, luceneQuote, openfdaApiKey, } from "./openfda.js";
+// state filter charclass (a 2-letter US state/territory postal code).
+const STATE_RE = /^[A-Za-z]{2}$/;
+const DEFAULT_LIMIT = 25;
+const MAX_LIMIT = 100;
+/** host+path-only label (→ ToolError.upstreamEndpoint); NEVER carries the key. */
+const DEVICE_LABEL = "openfda:/device/510k";
+// ─── Honesty notes (ADR-0056 required set) ────────────────────────
+const NOT_DETERMINATION_NOTE = "openFDA 510(k) device clearances are FDA-published premarket-notification records; treat the decision/date/clearance-type as of the source's last publication. This is reference data, not a live regulatory determination.";
+const KEYLESS_NOTE = "Keyless: no OPENFDA_API_KEY is set. openFDA allows ~1000 requests/day without a key; a free key raises the rate limit (get one at https://open.fda.gov/apis/authentication/).";
+const KEYED_NOTE = "OPENFDA_API_KEY is set — it rides ONLY the &api_key= query parameter to api.fda.gov (openFDA has no header option), raising the rate limit. Its value is NEVER logged, echoed, or placed in this response.";
+const NO_FILTER_NOTE = "No structured filters were applied — this is an unscoped scan of the WHOLE 510(k) device-clearance collection. Add applicant / deviceName / productCode / clearanceType / kNumber / state to scope the result set.";
+/** Map ONE openFDA 510(k) result row → the curated shape. Every scalar via `str`. */
+function mapClearance(row) {
+    const r = (row ?? {});
+    return {
+        applicant: str(r.applicant),
+        deviceName: str(r.device_name),
+        kNumber: str(r.k_number),
+        decisionDate: str(r.decision_date),
+        decisionDescription: str(r.decision_description),
+        clearanceType: str(r.clearance_type),
+        productCode: str(r.product_code),
+        advisoryCommittee: str(r.advisory_committee),
+        state: str(r.state),
+    };
+}
+/**
+ * Assemble the openFDA `search=` Lucene string from structured 510(k) filters — each
+ * value Lucene-escaped + phrase-quoted (reusing openfda.ts's `luceneQuote`), joined by
+ * ` AND `. Returns "" when no filter is present (openFDA then returns the whole
+ * collection). The clause → field mapping is FIXED here; a caller can never inject a
+ * raw field:value (no raw Lucene passthrough).
+ */
+export function buildDeviceSearch(f) {
+    const clauses = [];
+    if (f.applicant !== undefined)
+        clauses.push(`applicant:${luceneQuote(f.applicant)}`);
+    if (f.deviceName !== undefined)
+        clauses.push(`device_name:${luceneQuote(f.deviceName)}`);
+    if (f.productCode !== undefined)
+        clauses.push(`product_code:${luceneQuote(f.productCode)}`);
+    if (f.clearanceType !== undefined)
+        clauses.push(`clearance_type:${luceneQuote(f.clearanceType)}`);
+    if (f.kNumber !== undefined)
+        clauses.push(`k_number:${luceneQuote(f.kNumber)}`);
+    if (f.state !== undefined)
+        clauses.push(`state:${luceneQuote(f.state.toUpperCase())}`);
+    return clauses.join(" AND ");
+}
+/**
+ * Search openFDA 510(k) DEVICE CLEARANCES with structured filters → curated clearance
+ * rows + honest `_meta`. KEYLESS (an OPTIONAL OPENFDA_API_KEY only raises the rate
+ * limit). totalAvailable = meta.results.total (EXACT); skip/limit offset pagination.
+ * ★A no-match query (openFDA HTTP 404 NOT_FOUND) ⇒ an honest empty, never a throw.
+ */
+export async function deviceClearances(args) {
+    // ── Validate + default the inputs (belt-and-suspenders behind the server Zod; a
+    //    DIRECT handler call bypasses Zod). ──
+    if (args.state !== undefined && !STATE_RE.test(args.state)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Invalid state ${JSON.stringify(args.state)} — expected a 2-letter US state/territory postal code (^[A-Za-z]{2}$), e.g. "CA".`,
+            upstreamEndpoint: DEVICE_LABEL,
+        });
+    }
+    const limit = clampLimit(args.limit);
+    const skip = clampSkip(args.skip);
+    // ── Assemble the query (structured-only; all VALUES via URLSearchParams — no
+    //    host/path steer). The OPTIONAL key rides ONLY here in &api_key=. ──
+    const filters = {
+        applicant: args.applicant,
+        deviceName: args.deviceName,
+        productCode: args.productCode,
+        clearanceType: args.clearanceType,
+        kNumber: args.kNumber,
+        state: args.state,
+    };
+    const search = buildDeviceSearch(filters);
+    const filtersApplied = [];
+    if (args.applicant !== undefined)
+        filtersApplied.push("applicant");
+    if (args.deviceName !== undefined)
+        filtersApplied.push("deviceName");
+    if (args.productCode !== undefined)
+        filtersApplied.push("productCode");
+    if (args.clearanceType !== undefined)
+        filtersApplied.push("clearanceType");
+    if (args.kNumber !== undefined)
+        filtersApplied.push("kNumber");
+    if (args.state !== undefined)
+        filtersApplied.push("state");
+    const params = new URLSearchParams();
+    if (search !== "")
+        params.set("search", search);
+    params.set("limit", String(limit));
+    params.set("skip", String(skip));
+    const key = openfdaApiKey();
+    if (key !== undefined)
+        params.set("api_key", key); // OPTIONAL — &api_key= ONLY
+    const url = `https://${OPENFDA_HOST}/device/510k.json?${params.toString()}`;
+    // ── Fetch + classify. ★P2 CRUX: a 404 whose body is {error:{code:"NOT_FOUND"}} is
+    //    a genuine no-match (or an unknown field) ⇒ an HONEST EMPTY, never a thrown
+    //    not_found. Any OTHER 4xx (e.g. 400 syntax) ⇒ invalid_input surfacing openFDA's
+    //    message; a 5xx/429 ⇒ the shared taxonomy THROWS. (fetchOpenfda/readOpenfdaError
+    //    are the SAME helpers as openfda.ts — the 404-reclassify logic is not reinvented.) ──
+    const res = await fetchOpenfda(url, DEVICE_LABEL);
+    if (res.status === 404) {
+        const { code, message } = await readOpenfdaError(res);
+        if (code === "NOT_FOUND") {
+            // Honest empty — NOT thrown, NOT not_found (the openFDA no-match idiom).
+            return emptyResult(limit, skip, filtersApplied, key !== undefined);
+        }
+        // A non-NOT_FOUND 404 ⇒ the shared not_found taxonomy (never a fake-empty).
+        throw new ToolErrorCarrier({
+            ...errorFromResponse(res, DEVICE_LABEL),
+            message: message
+                ? `openFDA returned HTTP 404 at ${DEVICE_LABEL}: ${message}`
+                : `Resource not found at ${DEVICE_LABEL} (HTTP 404).`,
+        });
+    }
+    if (res.status >= 400 && res.status < 500 && res.status !== 429) {
+        // A 4xx OTHER than 404/429 (e.g. 400 syntax) ⇒ invalid_input surfacing the
+        // openFDA error message (a caller-fixable request, never a fake-empty).
+        const { message } = await readOpenfdaError(res);
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: message
+                ? `openFDA rejected the request (HTTP ${res.status}) at ${DEVICE_LABEL}: ${message}`
+                : `Bad request (HTTP ${res.status}) at ${DEVICE_LABEL}.`,
+            upstreamStatus: res.status,
+            upstreamEndpoint: DEVICE_LABEL,
+        });
+    }
+    if (!res.ok) {
+        // 429 → rate_limited; 5xx → upstream_unavailable (a DOWN service is NEVER an empty
+        // result). Delegated to the shared errors.ts taxonomy.
+        throw new ToolErrorCarrier(errorFromResponse(res, DEVICE_LABEL));
+    }
+    // ── 200 ⇒ parse JSON; a non-JSON body ⇒ r.json() SyntaxError ⇒ schema_drift (never
+    //    read as an empty result). ──
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch (e) {
+        if (e instanceof SyntaxError) {
+            throw driftError(DEVICE_LABEL, `openFDA ${DEVICE_LABEL} returned a non-JSON body at HTTP 200 — schema drift (never read as an empty result).`);
+        }
+        throw e;
+    }
+    // ── [P4] meta.results (the total carrier) and results (the rows) MUST be present +
+    //    well-shaped; anything else is drift, never a fabricated empty. ──
+    const b = (body ?? {});
+    const meta = (b.meta ?? {});
+    const metaResults = meta.results;
+    if (metaResults === undefined ||
+        metaResults === null ||
+        typeof metaResults !== "object") {
+        throw driftError(DEVICE_LABEL, `openFDA ${DEVICE_LABEL} shape drift — meta.results (the skip/limit/total carrier) is missing.`);
+    }
+    if (!Array.isArray(b.results)) {
+        throw driftError(DEVICE_LABEL, `openFDA ${DEVICE_LABEL} shape drift — results must be an array.`);
+    }
+    const clearances = b.results.map(mapClearance);
+    const returned = clearances.length;
+    // ── [P1] totalAvailable = meta.results.total EXACT (the REAL total), NEVER
+    //    results.length. skip/limit offset pagination. ──
+    const rawTotal = metaResults.total;
+    const totalAvailable = typeof rawTotal === "number" && Number.isFinite(rawTotal) ? rawTotal : null;
+    const hasMore = totalAvailable !== null && skip + returned < totalAvailable;
+    const nextOffset = hasMore ? skip + returned : null;
+    const notes = [NOT_DETERMINATION_NOTE, keyNote(key !== undefined)];
+    if (filtersApplied.length === 0)
+        notes.push(NO_FILTER_NOTE);
+    return withMeta({ clearances }, {
+        // MODE only — never the key value (K-test).
+        source: `${OPENFDA_HOST} /device/510k (openFDA 510(k) device clearances; ${key !== undefined ? "OPENFDA_API_KEY rate-limit key applied" : "keyless"})`,
+        keylessMode: true, // a keyless tool; the optional key only raises the rate limit
+        returned,
+        totalAvailable,
+        filtersApplied,
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        pagination: { offset: skip, limit, hasMore, nextOffset },
+        notes,
+    });
+}
+// ─── Small helpers ────────────────────────────────────────────────
+function keyNote(hasKey) {
+    return hasKey ? KEYED_NOTE : KEYLESS_NOTE;
+}
+/** An honest empty result (★P2: a 404 NOT_FOUND no-match) — returned:0, total:0. */
+function emptyResult(limit, skip, filtersApplied, hasKey) {
+    return withMeta({ clearances: [] }, {
+        source: `${OPENFDA_HOST} /device/510k (openFDA 510(k) device clearances; ${hasKey ? "OPENFDA_API_KEY rate-limit key applied" : "keyless"})`,
+        keylessMode: true,
+        returned: 0,
+        totalAvailable: 0,
+        filtersApplied,
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        pagination: { offset: skip, limit, hasMore: false, nextOffset: null },
+        notes: [
+            "No 510(k) device clearances matched this query (openFDA returned HTTP 404 NOT_FOUND — the source's honest no-match). This is an exact empty, not an error.",
+            NOT_DETERMINATION_NOTE,
+            keyNote(hasKey),
+        ],
+    });
+}
+function clampLimit(v) {
+    if (typeof v !== "number" || !Number.isFinite(v))
+        return DEFAULT_LIMIT;
+    const n = Math.floor(v);
+    if (n < 1)
+        return 1;
+    if (n > MAX_LIMIT)
+        return MAX_LIMIT;
+    return n;
+}
+function clampSkip(v) {
+    if (typeof v !== "number" || !Number.isFinite(v))
+        return 0;
+    const n = Math.floor(v);
+    return n < 0 ? 0 : n;
+}
+//# sourceMappingURL=openfda-device.js.map

package/dist/openfda-device.js.map

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

package/dist/openfda.d.ts

@@ -0,0 +1,133 @@
+/**
+ * openfda.ts — openFDA recall/enforcement records (api.fda.gov) — the
+ * PRODUCT-SAFETY / RECALL lane (ADR-0054). Drug / device / food recall
+ * enforcement reports: the recalling firm, the product, the reason, the FDA
+ * classification (Class I/II/III), status, and geography.
+ *
+ * ★ THIS IS A KEYLESS TOOL WITH AN *OPTIONAL* RATE-LIMIT KEY. openFDA works
+ *   keyless (~1000 requests/day); a free OPENFDA_API_KEY only RAISES the rate
+ *   limit. So — unlike Census/FRED/BEA/DOL (key-REQUIRED, throw without it) —
+ *   this tool NEVER throws for a missing key. When OPENFDA_API_KEY IS set it
+ *   rides ONLY the `&api_key=` query param (openFDA has NO header option — query
+ *   only). See the K-test discipline below.
+ *
+ *   GET https://api.fda.gov/{category}/enforcement.json
+ *       ?search=<lucene>&limit=<1..100>&skip=<offset>[&api_key=<KEY>]
+ *     category ∈ {drug, device, food}
+ *   → { meta: { disclaimer, results: { skip, limit, total } }, results: [ {...} ] }
+ *
+ * This module COPIES (does NOT import) the census-economic.ts bespoke-fetch idiom
+ * (a single classified `fetch` rather than the shared getJson) — the reason is
+ * the ★P2 CRUX below: a no-match query returns HTTP 404, and getJson→
+ * fetchWithRetry throws a `not_found` ToolErrorCarrier that DISCARDS the body, so
+ * we could not distinguish a genuine no-match (→ honest empty) from a real 404.
+ * A bespoke fetch returns the Response so we can READ the 404 body and reclassify
+ * `{error:{code:"NOT_FOUND"}}` → an honest empty. Coercion/meta code is REUSED
+ * (`str` coerce.ts null-never-empty-string, `driftError`, `errorFromResponse`,
+ * `withMeta`/`buildMeta` with skip/limit offset pagination). NO local str/num.
+ *
+ * ★ HONESTY (ADR-0054 P1–P5):
+ *   [P1]  totalAvailable = `meta.results.total` EXACT (the REAL total, e.g. drug
+ *         17793), NEVER results.length. skip/limit offset pagination:
+ *         hasMore = skip + returned < total; nextOffset = hasMore ? skip+returned : null.
+ *   [★P2] a 404 whose body is `{error:{code:"NOT_FOUND"}}` (a no-match query OR an
+ *         unknown field) ⇒ HONEST EMPTY (returned:0, totalAvailable:0) — NOT thrown,
+ *         NOT not_found. Any OTHER 4xx (e.g. a 400 syntax error) ⇒ invalid_input
+ *         surfacing openFDA's error message. 5xx/timeout ⇒ upstream_unavailable
+ *         THROW. A 200 non-JSON body ⇒ schema_drift. (Reverting the
+ *         404-NOT_FOUND-as-empty handling ⇒ RED.)
+ *   [P3]  dates (`recall_initiation_date`, YYYYMMDD) and every scalar surfaced as a
+ *         STRING via `str` (null-never-empty-string) — no numeric coercion; never
+ *         fabricated.
+ *   [P4]  `meta.results` or `results` absent / non-array ⇒ driftError (never a
+ *         fabricated empty).
+ *   [K-test] OPTIONAL key: when OPENFDA_API_KEY is set it rides `&api_key=` ONLY,
+ *         so the key WILL appear in the raw fetch URL (an unavoidable openFDA
+ *         constraint — no header option). Mitigation: the `label` is host+path
+ *         ONLY (`openfda:/{category}/enforcement`, NO query), so no token can reach
+ *         ToolError.upstreamEndpoint; `_meta.source` names the MODE only; the key is
+ *         ABSENT from the serialized {data,_meta}, notes, and any log. Unset ⇒
+ *         keyless (no api_key param at all).
+ *   [SSRF] fixed host `api.fda.gov`; `category` is an ENUM (→ the path segment);
+ *         all filter VALUES are Lucene-escaped + phrase-quoted and ride
+ *         URLSearchParams `search=`; limit/skip are integers; state is charclass
+ *         `^[A-Za-z]{2}$`. A post-construction hostname/protocol assertion +
+ *         `redirect:"error"` lock it (no raw Lucene passthrough — structured only,
+ *         injection-safe).
+ */
+import { type MetaBundle } from "./meta.js";
+export declare const OPENFDA_HOST = "api.fda.gov";
+export declare const OPENFDA_CATEGORIES: readonly ["drug", "device", "food"];
+export type OpenfdaCategory = (typeof OPENFDA_CATEGORIES)[number];
+export declare const OPENFDA_CLASSIFICATIONS: readonly ["Class I", "Class II", "Class III"];
+/** Read OPENFDA_API_KEY from env; trim; return the value or undefined (unset/blank). */
+export declare function openfdaApiKey(): string | undefined;
+export type OpenfdaRecall = {
+    recallingFirm: string | null;
+    productDescription: string | null;
+    reasonForRecall: string | null;
+    classification: string | null;
+    status: string | null;
+    state: string | null;
+    city: string | null;
+    recallInitiationDate: string | null;
+    recallNumber: string | null;
+    voluntaryMandated: string | null;
+    distributionPattern: string | null;
+};
+/**
+ * Quote a filter value as a Lucene phrase term. Wrapping in double quotes makes a
+ * multi-word value (e.g. "Class I", "johnson & johnson") match as a phrase and
+ * closes every operator-injection surface; within the quoted term only `"` and
+ * `\` are special, so we backslash-escape BOTH (a `"` in the value can never break
+ * out of the quotes). There is NO raw Lucene passthrough — the tool assembles the
+ * whole `search=` string from validated typed args.
+ */
+export declare function luceneQuote(v: string): string;
+/** The structured filter set → openFDA `field:value` clauses. */
+export type OpenfdaFilters = {
+    firm?: string;
+    product?: string;
+    reason?: string;
+    classification?: string;
+    status?: string;
+    state?: string;
+};
+/**
+ * Assemble the openFDA `search=` Lucene string from structured filters — each
+ * value Lucene-escaped + phrase-quoted, joined by ` AND `. Returns "" when no
+ * filter is present (openFDA then returns the whole category). The mapping of
+ * clause → field is FIXED here; a caller can never inject a raw field:value.
+ */
+export declare function buildSearch(f: OpenfdaFilters): string;
+/**
+ * A SINGLE classified `fetch` to api.fda.gov (NOT the shared getJson — we must
+ * READ a 404 body to distinguish a NOT_FOUND no-match from a real outage; see the
+ * ★P2 crux in the caller). Builds the URL on the FIXED host from `params`, asserts
+ * the constructed URL cannot have been steered off-host (belt-and-suspenders), and
+ * sets `redirect:"error"` (fail closed on any off-host 3xx — a redirect could
+ * carry the api_key away). Returns the raw Response for the caller to classify. A
+ * timeout/abort ⇒ non-retryable upstream_unavailable; a network TypeError ⇒
+ * retryable upstream_unavailable; a redirect TypeError ⇒ schema_drift (never a
+ * fake-empty). `label` is host+path only.
+ */
+export declare function fetchOpenfda(url: string, label: string): Promise<Response>;
+/** Best-effort read of an openFDA error body `{error:{code,message}}`. null on any failure. */
+export declare function readOpenfdaError(res: Response): Promise<{
+    code: string | null;
+    message: string | null;
+}>;
+export type OpenfdaEnforcementArgs = OpenfdaFilters & {
+    category?: string;
+    limit?: number;
+    skip?: number;
+};
+/**
+ * Search openFDA recall/enforcement records for a category (drug/device/food) with
+ * structured filters → curated recall rows + honest `_meta`. KEYLESS (an OPTIONAL
+ * OPENFDA_API_KEY only raises the rate limit). totalAvailable = meta.results.total
+ * (EXACT); skip/limit offset pagination. ★A no-match query (openFDA HTTP 404
+ * NOT_FOUND) ⇒ an honest empty, never a throw.
+ */
+export declare function enforcement(args: OpenfdaEnforcementArgs): Promise<MetaBundle>;
+//# sourceMappingURL=openfda.d.ts.map

package/dist/openfda.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openfda.d.ts","sourceRoot":"","sources":["../src/openfda.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAKH,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAGzE,eAAO,MAAM,YAAY,gBAAgB,CAAC;AAG1C,eAAO,MAAM,kBAAkB,qCAAsC,CAAC;AACtE,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAIlE,eAAO,MAAM,uBAAuB,+CAAgD,CAAC;AA2BrF,wFAAwF;AACxF,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAIlD;AAGD,MAAM,MAAM,aAAa,GAAG;IAC1B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC,CAAC;AAqBF;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,iEAAiE;AACjE,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAarD;AAGD;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAyChF;AAED,+FAA+F;AAC/F,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,QAAQ,GACZ,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAY1D;AAGD,MAAM,MAAM,sBAAsB,GAAG,cAAc,GAAG;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,UAAU,CAAC,CA8KrB"}