@cliwant/mcp-sam-gov 1.2.0 → 1.4.0

package/dist/cpsc.js

@@ -0,0 +1,283 @@
+/**
+ * cpsc.ts — CPSC CONSUMER-PRODUCT RECALLS (www.saferproducts.gov) — the consumer
+ * goods / import product-safety vetting lane (ADR-0058). ONE keyless tool:
+ *   • cpsc_recalls — /RestWebServices/Recall?format=json + date/product/manufacturer/
+ *     recallNumber filters.
+ * The third leg of the cross-agency product-safety family alongside NHTSA (vehicles)
+ * and openFDA (medical/food): a manufacturer / product / hazard recall history for
+ * B2G supplier and import vetting.
+ *
+ * ★ KEYLESS — there is NO API key at all (no parameter, no header). This module
+ *   touches NO key seam (no KEY_REGISTRY / keys.ts / API_KEYS.md). It REUSES the
+ *   shared `getJson` (redirect:"error") / `driftError` fetch envelope, the `str`
+ *   coercion (null-never-empty-string), and `withMeta`/`buildMeta` — and mirrors
+ *   nhtsa.ts / datagov-catalog.ts's fixed-host SSRF idiom + schema_drift
+ *   catch-ladder verbatim.
+ *
+ * ★ THE HONESTY PILLARS (P1-P5, live-verified 2026-07-15):
+ *   P1: the /Recall response is a BARE JSON ARRAY with NO count field and NO server
+ *       pagination — it returns the COMPLETE set matching the filter. So
+ *       totalAvailable = results.length and complete:true, WITH a disclosing note
+ *       that CPSC reports no total-count field / no pagination. A total is NEVER
+ *       fabricated (there is no upstream total to trust; the honest total is the
+ *       length of the complete set).
+ *   P2: an empty array `[]` ⇒ an HONEST EMPTY (returned:0, complete:true) — a filter
+ *       that matches nothing is an honest no-match, NOT an error. A 4xx ⇒
+ *       invalid_input; a 5xx/timeout ⇒ THROW (never a fake empty); a 200 non-JSON
+ *       body OR a non-array body ⇒ schema_drift (never a fabricated empty).
+ *   P3: dates stay STRINGS (via `str`); NumberOfUnits is free text ("About 6,500")
+ *       kept as a STRING; nested arrays (Products/Manufacturers/Retailers/Hazards/
+ *       Remedies/Injuries/ManufacturerCountries) are flattened to string arrays by
+ *       extracting each object's `.Name` (★ManufacturerCountries uses `.Country`,
+ *       NOT `.Name`), SKIPPING an empty `{}` object (never a fabricated entry); a
+ *       genuinely-absent nested array ⇒ []; null-never-empty-string throughout.
+ *   P4: the top-level body MUST be an array — a non-array (object/string/null) ⇒
+ *       driftError (a broken response contract, never a fabricated empty).
+ *   DEFAULT-WINDOW: with NO filter given, the unfiltered result is huge, so the tool
+ *       defaults RecallDateStart to ~90 days ago and DISCLOSES the default in a note
+ *       — it NEVER silently fetches the whole dataset.
+ *   SSRF: fixed host `www.saferproducts.gov` (compile-time literal) + post-construction
+ *       hostname/protocol assertion + redirect:"error"; every filter rides a
+ *       module-built URLSearchParams (no raw passthrough); dates are ^\d{4}-\d{2}-\d{2}$;
+ *       recallNumber is charclass-validated (letters/digits/hyphen only), so a
+ *       `../` or `%` can never reach the fixed path.
+ */
+import { ToolErrorCarrier } from "./errors.js";
+import { getJson, driftError } from "./datasource.js";
+import { str } from "./coerce.js";
+import { withMeta } from "./meta.js";
+// ─── Fixed endpoint (SSRF core — compile-time CONSTANTS) ──────────
+export const CPSC_HOST = "www.saferproducts.gov";
+const CPSC_RECALL_PATH = "/RestWebServices/Recall";
+// HOST+path-only label (→ ToolError.upstreamEndpoint). Keyless ⇒ no token can ever
+// appear here regardless, but the label stays host+path for consistency.
+const CPSC_RECALL_LABEL = "cpsc:/RestWebServices/Recall";
+// ─── Input validation grammar (SSRF + injection guard) ────────────
+// dates: strict YYYY-MM-DD. recallNumber: letters/digits/hyphen only — rejects
+// `../`, `%`, `/`, `.`, spaces, quotes, so a value can never break out of the
+// URLSearchParams-encoded query onto the fixed host/path.
+export const CPSC_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+export const CPSC_RECALL_NUMBER_RE = /^[A-Za-z0-9-]+$/;
+// The default recent-window span (days) applied when NO filter is given, so an
+// unbounded whole-dataset fetch never happens silently.
+const CPSC_DEFAULT_WINDOW_DAYS = 90;
+const KEYLESS_NOTE = "CPSC SaferProducts is a keyless public API (www.saferproducts.gov) — no API key is required or accepted.";
+// The P1 load-bearing honesty caveat carried on EVERY response.
+const CPSC_NO_PAGINATION_NOTE = "CPSC returns the complete matching set (no server pagination or total-count field) — totalAvailable is the number of returned recalls (the size of the complete set), not an upstream-reported total.";
+// ─── Nested-array flatteners (P3) ─────────────────────────────────
+/**
+ * Flatten a CPSC nested array (Products/Manufacturers/Retailers/Hazards/Remedies/
+ * Injuries/ManufacturerCountries) to a string[] by extracting `field` from each
+ * object via `str` (null-never-empty-string). An empty `{}` object (or one whose
+ * `field` is absent/blank) is SKIPPED — never a fabricated entry. A non-array
+ * (absent nested array) ⇒ [].
+ */
+function extractField(x, field) {
+    if (!Array.isArray(x))
+        return [];
+    const out = [];
+    for (const el of x) {
+        if (el === null || typeof el !== "object")
+            continue;
+        const v = str(el[field]);
+        if (v !== null)
+            out.push(v);
+    }
+    return out;
+}
+/**
+ * The recall-level numberOfUnits (P3): CPSC carries NumberOfUnits per PRODUCT as
+ * FREE TEXT ("About 6,500"), so this returns the FIRST product's non-blank
+ * NumberOfUnits as a STRING (never numerically coerced), or null when none is
+ * present (null-never-empty-string).
+ */
+function firstNumberOfUnits(products) {
+    if (!Array.isArray(products))
+        return null;
+    for (const p of products) {
+        if (p === null || typeof p !== "object")
+            continue;
+        const v = str(p.NumberOfUnits);
+        if (v !== null)
+            return v;
+    }
+    return null;
+}
+/**
+ * Map ONE /Recall row → the curated recall shape. Scalars via `str`
+ * (null-never-empty-string; dates stay strings). Nested arrays flattened via
+ * `extractField` on `.Name` — EXCEPT ManufacturerCountries, which carries `.Country`.
+ */
+function mapRecall(row) {
+    const r = (row ?? {});
+    return {
+        recallNumber: str(r.RecallNumber),
+        recallDate: str(r.RecallDate),
+        title: str(r.Title),
+        description: str(r.Description),
+        url: str(r.URL),
+        products: extractField(r.Products, "Name"),
+        numberOfUnits: firstNumberOfUnits(r.Products),
+        manufacturers: extractField(r.Manufacturers, "Name"),
+        retailers: extractField(r.Retailers, "Name"),
+        hazards: extractField(r.Hazards, "Name"),
+        remedies: extractField(r.Remedies, "Name"),
+        injuries: extractField(r.Injuries, "Name"),
+        // ★ ManufacturerCountries objects carry `Country`, not `Name` (live-verified).
+        manufacturerCountries: extractField(r.ManufacturerCountries, "Country"),
+    };
+}
+/**
+ * Validate the optional inputs PRE-fetch (0 network call). A DIRECT handler call
+ * bypasses the server Zod, so re-guard the SSRF-relevant grammars here: dates are
+ * ^\d{4}-\d{2}-\d{2}$; recallNumber is letters/digits/hyphen only. productName /
+ * manufacturer are free text (they ride URLSearchParams-encoded, so injection is
+ * neutralized by encoding — no charclass needed, but they are validated as strings).
+ */
+function validateArgs(args) {
+    const dateChecks = [
+        ["dateStart", args.dateStart],
+        ["dateEnd", args.dateEnd],
+    ];
+    for (const [name, value] of dateChecks) {
+        if (value !== undefined && (typeof value !== "string" || !CPSC_DATE_RE.test(value))) {
+            throw new ToolErrorCarrier({
+                kind: "invalid_input",
+                retryable: false,
+                message: `Invalid ${name} ${JSON.stringify(value)} — expected a YYYY-MM-DD date (^\\d{4}-\\d{2}-\\d{2}$), e.g. "2025-01-01".`,
+                upstreamEndpoint: CPSC_RECALL_LABEL,
+            });
+        }
+    }
+    if (args.recallNumber !== undefined &&
+        (typeof args.recallNumber !== "string" || !CPSC_RECALL_NUMBER_RE.test(args.recallNumber))) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Invalid recallNumber ${JSON.stringify(args.recallNumber)} — expected letters/digits/hyphen only (^[A-Za-z0-9-]+$), e.g. "25088".`,
+            upstreamEndpoint: CPSC_RECALL_LABEL,
+        });
+    }
+    for (const [name, value] of [
+        ["productName", args.productName],
+        ["manufacturer", args.manufacturer],
+    ]) {
+        if (value !== undefined && typeof value !== "string") {
+            throw new ToolErrorCarrier({
+                kind: "invalid_input",
+                retryable: false,
+                message: `Invalid ${name} — expected a string.`,
+                upstreamEndpoint: CPSC_RECALL_LABEL,
+            });
+        }
+    }
+}
+// ─── SSRF-guarded fetch (fixed host + hostname assertion + redirect) ──
+/**
+ * GET the CPSC /Recall JSON on the FIXED host. Builds
+ * `https://www.saferproducts.gov/RestWebServices/Recall?${params}`, asserts the
+ * CONSTRUCTED URL's hostname === the fixed host over https (belt-and-suspenders),
+ * and sets `redirect:"error"` (fail closed on any off-host 3xx). Keyless — no
+ * header/token.
+ */
+async function getCpsc(params) {
+    const url = `https://${CPSC_HOST}${CPSC_RECALL_PATH}?${params.toString()}`;
+    const built = new URL(url);
+    if (built.hostname !== CPSC_HOST || built.protocol !== "https:") {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Constructed CPSC URL host ${JSON.stringify(built.hostname)} (${built.protocol}) does not match the fixed host ${JSON.stringify(CPSC_HOST)} over https — refusing to fetch (SSRF safety).`,
+            upstreamEndpoint: CPSC_RECALL_LABEL,
+        });
+    }
+    return getJson(url, { label: CPSC_RECALL_LABEL, redirect: "error" });
+}
+/** Compute an ISO YYYY-MM-DD `days` days before now (the default-window start). */
+function daysAgoIso(days) {
+    return new Date(Date.now() - days * 86_400_000).toISOString().slice(0, 10);
+}
+// ─── Tool: cpsc_recalls ───────────────────────────────────────────
+/**
+ * Fetch CPSC consumer-product RECALLS → curated recall rows + honest `_meta`.
+ * KEYLESS. All filters are optional; with NO filter given, RecallDateStart defaults
+ * to ~90 days ago (disclosed in a note) so the whole dataset is never silently
+ * fetched. The response is a bare array with no total-count field / no pagination
+ * ⇒ totalAvailable = the number of returned recalls, complete:true. An empty array
+ * ⇒ an honest empty; a 4xx ⇒ invalid_input; a 5xx/timeout ⇒ THROW; a 200 non-JSON
+ * OR a non-array body ⇒ schema_drift.
+ */
+export async function recalls(args) {
+    validateArgs(args);
+    // ── Build the query from VALIDATED typed args, key-by-key (SSRF: no raw
+    //    passthrough). format=json is ALWAYS appended. ──
+    const params = new URLSearchParams();
+    params.set("format", "json");
+    const filtersApplied = [];
+    if (args.dateStart !== undefined) {
+        params.set("RecallDateStart", args.dateStart);
+        filtersApplied.push("dateStart");
+    }
+    if (args.dateEnd !== undefined) {
+        params.set("RecallDateEnd", args.dateEnd);
+        filtersApplied.push("dateEnd");
+    }
+    if (args.productName !== undefined) {
+        params.set("ProductName", args.productName);
+        filtersApplied.push("productName");
+    }
+    if (args.manufacturer !== undefined) {
+        params.set("Manufacturer", args.manufacturer);
+        filtersApplied.push("manufacturer");
+    }
+    if (args.recallNumber !== undefined) {
+        params.set("RecallNumber", args.recallNumber);
+        filtersApplied.push("recallNumber");
+    }
+    // ── DEFAULT-WINDOW: with NO filter, an unbounded fetch would return the WHOLE
+    //    dataset. Bound it to a ~90-day recent window (RecallDateStart) and DISCLOSE
+    //    the default — never silently fetch everything. ──
+    const notes = [KEYLESS_NOTE, CPSC_NO_PAGINATION_NOTE];
+    let defaultWindowApplied = false;
+    if (filtersApplied.length === 0) {
+        const defaultStart = daysAgoIso(CPSC_DEFAULT_WINDOW_DAYS);
+        params.set("RecallDateStart", defaultStart);
+        defaultWindowApplied = true;
+        notes.push(`No filter was provided — to avoid silently fetching the ENTIRE recall dataset, results are bounded to a default recent window: RecallDateStart=${defaultStart} (~${CPSC_DEFAULT_WINDOW_DAYS} days ago). Pass dateStart/dateEnd, productName, manufacturer, or recallNumber for a scoped query.`);
+    }
+    // ── The typed catch-ladder (nhtsa.ts / datagov-catalog.ts shape, VERBATIM):
+    //    a ToolErrorCarrier (host-assert / 4xx-5xx taxonomy) rethrows FIRST
+    //    (preserving its kind); a 200 non-JSON `.json()` SyntaxError reclassifies to
+    //    schema_drift; a bare error rethrows LAST. ──
+    let body;
+    try {
+        body = await getCpsc(params);
+    }
+    catch (e) {
+        if (e instanceof ToolErrorCarrier)
+            throw e;
+        if (e instanceof SyntaxError)
+            throw driftError(CPSC_RECALL_LABEL, "CPSC /RestWebServices/Recall returned a non-JSON body at HTTP 200 — schema drift (never read as an empty result).");
+        throw e;
+    }
+    // ── P4: the top-level body MUST be an array (a non-array object/string/null is
+    //    drift, never a fabricated empty). ──
+    if (!Array.isArray(body)) {
+        throw driftError(CPSC_RECALL_LABEL, "CPSC /RestWebServices/Recall shape drift — the response must be a bare JSON array.");
+    }
+    const recalls = body.map(mapRecall);
+    const returned = recalls.length;
+    return withMeta({ recalls }, {
+        source: `${CPSC_HOST} /RestWebServices/Recall (CPSC consumer-product recalls; keyless)`,
+        keylessMode: true,
+        returned,
+        // P1 — no upstream total-count field / no pagination: the complete set IS the
+        // returned rows, so totalAvailable = returned and complete:true (derived).
+        totalAvailable: returned,
+        filtersApplied: defaultWindowApplied ? ["dateStart(default)"] : filtersApplied,
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        notes,
+    });
+}
+//# sourceMappingURL=cpsc.js.map

package/dist/cpsc.js.map

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

package/dist/dol.d.ts

@@ -0,0 +1,118 @@
+/**
+ * dol.ts — US Department of Labor Data API v4 (apiprod.dol.gov) — the LABOR
+ * ENFORCEMENT lane (ADR-0053). WHD wage/hour violations, OSHA inspections, ILAB
+ * child/forced-labor reports, MSHA mine safety … — the compliance/enforcement
+ * signal no contract/spending/market source carries.
+ *
+ * TWO tools with a DELIBERATE key split (the honest reflection of the live API):
+ *   • `dol_list_datasets` (KEYLESS) — GET /v4/datasets. The dataset CATALOG (and
+ *     /v4/agencies) is keyless; this tool needs NO key. It returns the machine
+ *     inventory (name / tablename / api_url / agency / …) you page + filter to find
+ *     an endpoint, then feed its `apiUrl` into dol_get_dataset.
+ *   • `dol_get_dataset` (KEY-REQUIRED, DOL_API_KEY) — GET
+ *     /v4/get/{agency}/{endpoint}/json?… . The DATA endpoint has NO keyless tier, so
+ *     with NO `DOL_API_KEY` this tool THROWS an invalid_input config error BEFORE any
+ *     fetch (0 network call; the message names DOL_API_KEY + dataportal.dol.gov/registration).
+ *   So DOL is the 4th REQUIRED key — but ONLY for the data tool; the catalog tool
+ *   (and every other tool on the server) stays keyless.
+ *
+ * ★LIVE-VERIFIED WIRE FACTS (2026-07-15):
+ *   - Host `apiprod.dol.gov` (AWS API Gateway) + base `/v4`.
+ *   - /v4/datasets is KEYLESS 200 → `{ datasets:[…], meta:{ current_page, next_page,
+ *     prev_page, total_pages, total_count } }`. `limit` is the PER-PAGE size (limit=1000
+ *     returns the whole 42-row catalog in one page, total_pages:1); server-side agency
+ *     filtering is NOT honored (verified: ?agency=ILAB still returned the full 42) — so
+ *     agency/query filtering is CLIENT-SIDE over the fetched catalog.
+ *   - The DATA route is the QUERY-STYLE form `/v4/get/{agency}/{endpoint}/{format}?…`
+ *     (NOT the path-style `/…/limit/N/offset/O/format/json`): the query-style URL
+ *     reached the DOL app and returned a proper `401 {"…key…missing…"}` on a bad key,
+ *     whereas the path-style URL only ever hit the AWS gateway's generic
+ *     `403 {"message":"Missing Authentication Token"}` (an unmatched route). The DOL
+ *     API User Guide (dataportal.dol.gov/pdf/dol-api-user-guide.pdf) confirms the
+ *     `/get/<agency>/<api_url>/<format>?limit=&offset=&filter_object=&…` template and
+ *     that `<endpoint>` is the dataset's **api_url** (NOT its tablename).
+ *
+ * ★UNVERIFIED (key-gated — coded DEFENSIVELY, honestly disclosed): the DATA response
+ *   body shape could not be observed live (every /v4/get call is 401 without a real
+ *   key, and the User Guide shows no body example). So `dol_get_dataset` accepts EITHER
+ *   a bare row array `[…]` OR `{ data:[…] }` OR `{ results:[…] }`; a top-level count
+ *   (`total_count`/`total`/`count`, or `meta.total_count`) is used for totalAvailable
+ *   ONLY if actually present, else `totalAvailable = null` (an HONEST unknown — never
+ *   `returned` passed off as the total). Records are surfaced VERBATIM (each dataset
+ *   has its own enforcement schema; blind coercion would distort compliance data — a
+ *   JSON `0` stays `0`, a JSON `null` stays `null`, field names are preserved as-is).
+ *
+ * ★HONESTY (ADR-0053 P1–P4 + KEY + SSRF):
+ *   [KEY]  dol_get_dataset with NO DOL_API_KEY ⇒ invalid_input THROW pre-fetch (0
+ *          fetch); the message names DOL_API_KEY + dataportal.dol.gov/registration. The key rides the
+ *          `X-API-KEY` HEADER ONLY — NEVER the URL / label / _meta / notes / a log (the
+ *          K-test). dol_list_datasets is keyless (no key read, no header).
+ *   [P1]   catalog: totalAvailable = meta.total_count (the API's real catalog total)
+ *          for an unfiltered scan; when a CLIENT-SIDE filter is applied it is the
+ *          filtered-set size (exact — the whole catalog is fetched in one page). data:
+ *          totalAvailable = a real count field when present, else null; offset/limit
+ *          pagination in both.
+ *   [P2]   data: 401/403 (missing/invalid key) ⇒ invalid_input reclassified with the
+ *          DOL_API_KEY guidance (the AWS "Missing Authentication Token" is a key problem
+ *          here) — never empty. 400 ⇒ invalid_input. empty rows ⇒ honest empty
+ *          (returned:0). 429 ⇒ rate_limited THROW (Retry-After honored). 5xx/timeout ⇒
+ *          upstream_unavailable THROW. 200 non-JSON ⇒ schema_drift.
+ *   [P3]   records verbatim (null-never-0 comes for free — JSON preserves 0/null and
+ *          every original field name; the tool never introduces a fabricated 0).
+ *   [P4]   the expected array (catalog `datasets`; data's row array) absent/non-array
+ *          ⇒ driftError. A ToolErrorCarrier (401/5xx/…) is a P2 outcome, rethrown
+ *          BEFORE the drift check.
+ *   [SSRF] fixed host `apiprod.dol.gov` + a post-construction hostname/https assert +
+ *          `redirect:"error"`; agency/endpoint charclass `^[A-Za-z0-9_]+$` (they ride
+ *          in the PATH); limit/offset integers; filterValue/fields ride URLSearchParams;
+ *          the key rides the X-API-KEY header only.
+ */
+import { num } from "./coerce.js";
+import { type MetaBundle } from "./meta.js";
+export { num };
+export declare const DOL_HOST = "apiprod.dol.gov";
+/** Read DOL_API_KEY from env; trim; return the value or undefined (unset/blank). */
+export declare function dolApiKey(): string | undefined;
+export type DolListDatasetsArgs = {
+    agency?: string;
+    query?: string;
+    limit?: number;
+    offset?: number;
+};
+export type DolDataset = {
+    name: string | null;
+    tablename: string | null;
+    apiUrl: string | null;
+    agency: string | null;
+    agencyAbbr: string | null;
+    description: string | null;
+    frequency: string | null;
+    datasetType: number | null;
+    category: string | null;
+};
+/**
+ * List the DOL Data API v4 dataset catalog (KEYLESS). Fetches the WHOLE catalog in
+ * one page, applies optional CLIENT-SIDE `agency` (abbr/name) + `query` (substring over
+ * name/description/tags) filters, then offset/limit-slices the filtered set. Honest
+ * `_meta`: totalAvailable = the catalog's real total (unfiltered) or the filtered-set
+ * size (exact — the whole catalog is in hand); offset pagination over the filtered set.
+ */
+export declare function listDatasets(args: DolListDatasetsArgs): Promise<MetaBundle>;
+export type DolGetDatasetArgs = {
+    agency?: string;
+    table?: string;
+    limit?: number;
+    offset?: number;
+    filterField?: string;
+    filterValue?: string;
+    fields?: string[];
+};
+/**
+ * Fetch records from one DOL dataset (KEY-REQUIRED). `agency` (abbr) + `table` (the
+ * dataset's api_url endpoint) ride the request PATH; limit/offset/filter ride the query;
+ * the DOL_API_KEY rides the X-API-KEY header ONLY. Records are surfaced VERBATIM. Honest
+ * `_meta`: totalAvailable is a real count field when present, else null (offset
+ * pagination). Unset key ⇒ invalid_input THROW pre-fetch (0 fetch).
+ */
+export declare function getDataset(args: DolGetDatasetArgs): Promise<MetaBundle>;
+//# sourceMappingURL=dol.d.ts.map

package/dist/dol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dol.d.ts","sourceRoot":"","sources":["../src/dol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAIH,OAAO,EAAE,GAAG,EAAO,MAAM,aAAa,CAAC;AACvC,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAIzE,OAAO,EAAE,GAAG,EAAE,CAAC;AAGf,eAAO,MAAM,QAAQ,oBAAoB,CAAC;AAkC1C,oFAAoF;AACpF,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAI9C;AAyBD,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC;AAoBF;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CAiGjF;AAGD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAyK7E"}