@sealmetrics/mcp 0.1.0 → 1.3.0

package/dist/tools/pages.js

@@ -0,0 +1,307 @@
+import { PERIOD_SCHEMA, COMPARE_SCHEMA, LIMIT_SCHEMA, SORT_ORDER_SCHEMA, PAGE_SCHEMA, resolveSiteId, } from "./shared.js";
+// Common multi-value filter and `include` schema for /stats/pages and /stats/landing-pages.
+// Mirrors the API parameters declared in routers/stats.py (PRD 03).
+const MULTI_FILTER_SCHEMA = {
+    country: {
+        type: "array",
+        items: { type: "string", minLength: 1 },
+        minItems: 1,
+        description: "Filter by country code(s) (e.g. ['ES', 'US']).",
+    },
+    device_type: {
+        type: "array",
+        items: { type: "string", minLength: 1 },
+        minItems: 1,
+        description: "Filter by device type(s) (e.g. ['mobile', 'desktop']).",
+    },
+    browser: {
+        type: "array",
+        items: { type: "string", minLength: 1 },
+        minItems: 1,
+        description: "Filter by browser name(s).",
+    },
+    os: {
+        type: "array",
+        items: { type: "string", minLength: 1 },
+        minItems: 1,
+        description: "Filter by operating system name(s).",
+    },
+    channel_group: {
+        type: "array",
+        items: { type: "string", minLength: 1 },
+        minItems: 1,
+        description: "Filter by channel group(s).",
+    },
+    utm_source: {
+        type: "array",
+        items: { type: "string", minLength: 1 },
+        minItems: 1,
+        description: "Filter by UTM source(s).",
+    },
+    utm_medium: {
+        type: "array",
+        items: { type: "string", minLength: 1 },
+        minItems: 1,
+        description: "Filter by UTM medium(s).",
+    },
+    utm_campaign: {
+        type: "array",
+        items: { type: "string", minLength: 1 },
+        minItems: 1,
+        description: "Filter by UTM campaign(s).",
+    },
+    utm_term: {
+        type: "array",
+        items: { type: "string", minLength: 1 },
+        minItems: 1,
+        description: "Filter by UTM term(s).",
+    },
+    // `minItems` intentionally absent — empty array ≡ no grouping (PRD 08
+    // VAL-006 exception). Filter arrays use minItems: 1 because an empty
+    // filter list would silently match nothing; `include` instead is a no-op
+    // when empty, matching the API behavior.
+    include: {
+        type: "array",
+        items: { type: "string", enum: ["device", "browser", "os", "channel_group"] },
+        description: "Add dimension(s) to GROUP BY and response. Allowed values: device, browser, os, channel_group. Empty/absent means no extra grouping.",
+    },
+};
+const MULTI_FILTER_KEYS = [
+    "country",
+    "device_type",
+    "browser",
+    "os",
+    "channel_group",
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "utm_term",
+    "include",
+];
+function pickMultiFilters(args) {
+    const out = {};
+    for (const key of MULTI_FILTER_KEYS) {
+        const value = args[key];
+        if (Array.isArray(value) && value.length > 0) {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+export const getPagesTool = {
+    name: "get_pages",
+    description: "Get metrics per page URL path: pageviews and entrances. Useful for finding most popular pages and content performance. " +
+        "For bounce rate by entry page, use get_landing_pages instead — bounce is not interpretable at page granularity. " +
+        "Supports multi-value filters (country, device_type, browser, os, channel_group, UTMs) as arrays of strings — e.g. " +
+        "device_type=['mobile'] to filter to mobile only. Pass include=['device'] to also break down metrics by device. " +
+        "The two are orthogonal — combine them as needed.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            site_id: {
+                type: "string",
+                description: "Site ID. Optional if SEALMETRICS_SITE_ID env var is set.",
+            },
+            period: PERIOD_SCHEMA,
+            compare: COMPARE_SCHEMA,
+            limit: LIMIT_SCHEMA,
+            sort_by: {
+                type: "string",
+                description: "Field to sort by.",
+                enum: ["page_views", "entrances"],
+                default: "page_views",
+            },
+            sort_order: SORT_ORDER_SCHEMA,
+            page: PAGE_SCHEMA,
+            path_filter: {
+                type: "string",
+                description: "Filter pages by URL path pattern (e.g. '/blog').",
+            },
+            ...MULTI_FILTER_SCHEMA,
+        },
+    },
+    handler: async (client, args) => {
+        return client.requestPaginated("/stats/pages", {
+            site_id: resolveSiteId(args),
+            period: args.period ?? "30d",
+            compare: args.compare,
+            page_size: String(args.limit ?? 20),
+            page: args.page != null ? String(args.page) : undefined,
+            sort_by: args.sort_by ?? "page_views",
+            sort_order: args.sort_order ?? "desc",
+            path_filter: args.path_filter,
+            ...pickMultiFilters(args),
+        });
+    },
+};
+export const getLandingPagesTool = {
+    name: "get_landing_pages",
+    description: "Get landing page performance: entrances, bounce rate, conversions. Landing pages are the first page users see when entering the site. High bounce rates indicate poor landing page experience. " +
+        "Supports multi-value filters (country, device_type, browser, os, channel_group, UTMs) as arrays of strings — e.g. " +
+        "country=['ES','PT'] to filter to two countries. Pass include=['channel_group'] to also break down by channel group. " +
+        "The two are orthogonal — combine them as needed.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            site_id: {
+                type: "string",
+                description: "Site ID. Optional if SEALMETRICS_SITE_ID env var is set.",
+            },
+            period: PERIOD_SCHEMA,
+            compare: COMPARE_SCHEMA,
+            limit: LIMIT_SCHEMA,
+            sort_by: {
+                type: "string",
+                description: "Field to sort by.",
+                enum: ["entrances", "engaged_entrances", "page_views", "conversions", "revenue", "bounce_rate"],
+                default: "entrances",
+            },
+            sort_order: SORT_ORDER_SCHEMA,
+            page: PAGE_SCHEMA,
+            path_filter: {
+                type: "string",
+                description: "Filter by URL path pattern.",
+            },
+            ...MULTI_FILTER_SCHEMA,
+        },
+    },
+    handler: async (client, args) => {
+        return client.requestPaginated("/stats/landing-pages", {
+            site_id: resolveSiteId(args),
+            period: args.period ?? "30d",
+            compare: args.compare,
+            page_size: String(args.limit ?? 20),
+            page: args.page != null ? String(args.page) : undefined,
+            sort_by: args.sort_by ?? "entrances",
+            sort_order: args.sort_order ?? "desc",
+            path_filter: args.path_filter,
+            ...pickMultiFilters(args),
+        });
+    },
+};
+// --- Top N tools (non-paginated, client.request) ---
+export const getTopPagesTool = {
+    name: "get_top_pages",
+    description: "Get top pages ranked by page views. Returns a compact list of the top N pages — ideal for quick rankings and summaries.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            site_id: {
+                type: "string",
+                description: "Site ID. Optional if SEALMETRICS_SITE_ID env var is set.",
+            },
+            period: PERIOD_SCHEMA,
+            limit: LIMIT_SCHEMA,
+            country: {
+                type: "string",
+                description: "Filter by country code (e.g. 'ES', 'US').",
+            },
+            utm_source: {
+                type: "string",
+                description: "Filter by UTM source.",
+            },
+            utm_medium: {
+                type: "string",
+                description: "Filter by UTM medium.",
+            },
+            utm_campaign: {
+                type: "string",
+                description: "Filter by UTM campaign.",
+            },
+            utm_term: {
+                type: "string",
+                description: "Filter by UTM term.",
+            },
+        },
+    },
+    handler: async (client, args) => {
+        return client.request("/stats/pages/top", {
+            site_id: resolveSiteId(args),
+            period: args.period ?? "30d",
+            limit: String(args.limit ?? 10),
+            country: args.country,
+            utm_source: args.utm_source,
+            utm_medium: args.utm_medium,
+            utm_campaign: args.utm_campaign,
+            utm_term: args.utm_term,
+        });
+    },
+};
+export const getTopLandingPagesTool = {
+    name: "get_top_landing_pages",
+    description: "Get top landing pages ranked by entrances. Returns a compact list of the top N landing pages — ideal for quick rankings.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            site_id: {
+                type: "string",
+                description: "Site ID. Optional if SEALMETRICS_SITE_ID env var is set.",
+            },
+            period: PERIOD_SCHEMA,
+            limit: LIMIT_SCHEMA,
+            utm_source: {
+                type: "string",
+                description: "Filter by UTM source.",
+            },
+            utm_medium: {
+                type: "string",
+                description: "Filter by UTM medium.",
+            },
+            country: {
+                type: "string",
+                description: "Filter by country code (e.g. 'ES', 'US').",
+            },
+            content_grouping: {
+                type: "string",
+                description: "Filter by content grouping name.",
+            },
+        },
+    },
+    handler: async (client, args) => {
+        return client.request("/stats/landing-pages/top", {
+            site_id: resolveSiteId(args),
+            period: args.period ?? "30d",
+            limit: String(args.limit ?? 10),
+            utm_source: args.utm_source,
+            utm_medium: args.utm_medium,
+            country: args.country,
+            content_grouping: args.content_grouping,
+        });
+    },
+};
+export const getLandingPagesByContentGroupTool = {
+    name: "get_landing_pages_by_content_group",
+    description: "Get landing page metrics grouped by content grouping. Shows aggregate performance per content group (e.g. blog, product, category).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            site_id: {
+                type: "string",
+                description: "Site ID. Optional if SEALMETRICS_SITE_ID env var is set.",
+            },
+            period: PERIOD_SCHEMA,
+            utm_source: {
+                type: "string",
+                description: "Filter by UTM source.",
+            },
+            utm_medium: {
+                type: "string",
+                description: "Filter by UTM medium.",
+            },
+            country: {
+                type: "string",
+                description: "Filter by country code (e.g. 'ES', 'US').",
+            },
+        },
+    },
+    handler: async (client, args) => {
+        return client.request("/stats/landing-pages/by-content-group", {
+            site_id: resolveSiteId(args),
+            period: args.period ?? "30d",
+            utm_source: args.utm_source,
+            utm_medium: args.utm_medium,
+            country: args.country,
+        });
+    },
+};
+//# sourceMappingURL=pages.js.map

package/dist/tools/pages.js.map

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

package/dist/tools/properties.d.ts

@@ -0,0 +1,5 @@
+import type { ToolDef } from "./index.js";
+export declare const listPropertyKeysTool: ToolDef;
+export declare const getPropertyValuesTool: ToolDef;
+export declare const getPropertyBreakdownTool: ToolDef;
+//# sourceMappingURL=properties.d.ts.map

package/dist/tools/properties.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"properties.d.ts","sourceRoot":"","sources":["../../src/tools/properties.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAU1C,eAAO,MAAM,oBAAoB,EAAE,OAsBlC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,OA6CnC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,OAiCtC,CAAC"}

package/dist/tools/properties.js

@@ -0,0 +1,107 @@
+import { PERIOD_SCHEMA, LIMIT_SCHEMA, PAGE_SCHEMA, resolveSiteId, } from "./shared.js";
+const TABLE_SCHEMA = {
+    type: "string",
+    description: 'Table to query: "conversions", "microconversions", "both", or "conversion_items". Default: "both".',
+    enum: ["conversions", "microconversions", "both", "conversion_items"],
+    default: "both",
+};
+export const listPropertyKeysTool = {
+    name: "list_property_keys",
+    description: "Get the list of available custom property keys from conversions and/or microconversions. Use this to discover what property keys exist before querying values or breakdowns.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            site_id: {
+                type: "string",
+                description: "Site ID. Optional if SEALMETRICS_SITE_ID env var is set.",
+            },
+            period: PERIOD_SCHEMA,
+            table: TABLE_SCHEMA,
+        },
+    },
+    handler: async (client, args) => {
+        return client.request("/stats/properties/keys", {
+            site_id: resolveSiteId(args),
+            period: args.period ?? "30d",
+            table: args.table ?? "both",
+        });
+    },
+};
+export const getPropertyValuesTool = {
+    name: "get_property_values",
+    description: "Get property values with counts, grouped by a UTM parameter. Paginated. Use to see which values a specific property key has and how they distribute across traffic sources.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            site_id: {
+                type: "string",
+                description: "Site ID. Optional if SEALMETRICS_SITE_ID env var is set.",
+            },
+            property_key: {
+                type: "string",
+                description: "The property key to analyze (e.g. 'product_name', 'plan_type').",
+            },
+            period: PERIOD_SCHEMA,
+            group_by: {
+                type: "string",
+                description: 'Group results by: "utm_source", "utm_medium", "utm_campaign", or "all". Default: "utm_source".',
+                enum: ["utm_source", "utm_medium", "utm_campaign", "all"],
+                default: "utm_source",
+            },
+            table: TABLE_SCHEMA,
+            conversion_type: {
+                type: "string",
+                description: "Filter by conversion type.",
+            },
+            limit: LIMIT_SCHEMA,
+            page: PAGE_SCHEMA,
+        },
+        required: ["property_key"],
+    },
+    handler: async (client, args) => {
+        return client.requestPaginated("/stats/properties/values", {
+            site_id: resolveSiteId(args),
+            property_key: args.property_key,
+            period: args.period ?? "30d",
+            group_by: args.group_by ?? "utm_source",
+            table: args.table ?? "both",
+            conversion_type: args.conversion_type,
+            page_size: String(args.limit ?? 50),
+            page: args.page != null ? String(args.page) : undefined,
+        });
+    },
+};
+export const getPropertyBreakdownTool = {
+    name: "get_property_breakdown",
+    description: "Get a complete property breakdown with pivot-table style data. Shows all values for a property key with their counts and revenue — ideal for analyzing product or category performance.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            site_id: {
+                type: "string",
+                description: "Site ID. Optional if SEALMETRICS_SITE_ID env var is set.",
+            },
+            property_key: {
+                type: "string",
+                description: "The property key to analyze (e.g. 'product_name', 'plan_type').",
+            },
+            period: PERIOD_SCHEMA,
+            table: TABLE_SCHEMA,
+            conversion_type: {
+                type: "string",
+                description: "Filter by conversion type.",
+            },
+        },
+        required: ["property_key"],
+    },
+    handler: async (client, args) => {
+        return client.request("/stats/properties/breakdown", {
+            site_id: resolveSiteId(args),
+            property_key: args.property_key,
+            period: args.period ?? "30d",
+            table: args.table ?? "both",
+            conversion_type: args.conversion_type,
+        });
+    },
+};
+//# sourceMappingURL=properties.js.map

package/dist/tools/properties.js.map

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

package/dist/tools/segments.d.ts

@@ -0,0 +1,4 @@
+import type { ToolDef } from "./index.js";
+export declare const listSegmentsTool: ToolDef;
+export declare const getSegmentTool: ToolDef;
+//# sourceMappingURL=segments.d.ts.map

package/dist/tools/segments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"segments.d.ts","sourceRoot":"","sources":["../../src/tools/segments.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,eAAO,MAAM,gBAAgB,EAAE,OAuB9B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,OAwB5B,CAAC"}

package/dist/tools/segments.js

@@ -0,0 +1,49 @@
+import { resolveSiteId } from "./shared.js";
+export const listSegmentsTool = {
+    name: "list_segments",
+    description: "List all segments available for a site. Segments are saved filter sets (e.g. 'Mobile users from Spain', 'Organic traffic') that can be applied to stats queries via the segment parameter.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            site_id: {
+                type: "string",
+                description: "Site ID (account_id). Optional if SEALMETRICS_SITE_ID env var is set.",
+            },
+            include_system: {
+                type: "boolean",
+                description: "Include system segments like 'All Traffic', 'Direct' (default: true).",
+            },
+        },
+    },
+    handler: async (client, args) => {
+        return client.request("/segments", {
+            account_id: resolveSiteId(args),
+            include_system: args.include_system != null ? String(args.include_system) : undefined,
+        });
+    },
+};
+export const getSegmentTool = {
+    name: "get_segment",
+    description: "Get details of a specific segment including its filter definition. The segment_id can be either the segment ID (seg_xxx) or the segment name.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            site_id: {
+                type: "string",
+                description: "Site ID (account_id). Optional if SEALMETRICS_SITE_ID env var is set.",
+            },
+            segment_id: {
+                type: "string",
+                description: "Segment ID (seg_xxx) or segment name.",
+            },
+        },
+        required: ["segment_id"],
+    },
+    handler: async (client, args) => {
+        const segmentId = args.segment_id;
+        return client.request(`/segments/${encodeURIComponent(segmentId)}`, {
+            account_id: resolveSiteId(args),
+        });
+    },
+};
+//# sourceMappingURL=segments.js.map

package/dist/tools/segments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"segments.js","sourceRoot":"","sources":["../../src/tools/segments.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,MAAM,CAAC,MAAM,gBAAgB,GAAY;IACvC,IAAI,EAAE,eAAe;IACrB,WAAW,EACT,4LAA4L;IAC9L,WAAW,EAAE;QACX,IAAI,EAAE,QAAiB;QACvB,UAAU,EAAE;YACV,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,uEAAuE;aACrF;YACD,cAAc,EAAE;gBACd,IAAI,EAAE,SAAS;gBACf,WAAW,EAAE,uEAAuE;aACrF;SACF;KACF;IACD,OAAO,EAAE,KAAK,EAAE,MAAyB,EAAE,IAA6B,EAAE,EAAE;QAC1E,OAAO,MAAM,CAAC,OAAO,CAAU,WAAW,EAAE;YAC1C,UAAU,EAAE,aAAa,CAAC,IAAI,CAAC;YAC/B,cAAc,EAAE,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,SAAS;SACtF,CAAC,CAAC;IACL,CAAC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAY;IACrC,IAAI,EAAE,aAAa;IACnB,WAAW,EACT,+IAA+I;IACjJ,WAAW,EAAE;QACX,IAAI,EAAE,QAAiB;QACvB,UAAU,EAAE;YACV,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,uEAAuE;aACrF;YACD,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,uCAAuC;aACrD;SACF;QACD,QAAQ,EAAE,CAAC,YAAY,CAAC;KACzB;IACD,OAAO,EAAE,KAAK,EAAE,MAAyB,EAAE,IAA6B,EAAE,EAAE;QAC1E,MAAM,SAAS,GAAG,IAAI,CAAC,UAAoB,CAAC;QAC5C,OAAO,MAAM,CAAC,OAAO,CAAU,aAAa,kBAAkB,CAAC,SAAS,CAAC,EAAE,EAAE;YAC3E,UAAU,EAAE,aAAa,CAAC,IAAI,CAAC;SAChC,CAAC,CAAC;IACL,CAAC;CACF,CAAC"}

package/dist/tools/setup.d.ts

@@ -0,0 +1,49 @@
+import type { SealMetricsClient } from "../client.js";
+export interface SetupState {
+    provisioned: boolean;
+    accountId?: string;
+    pixelVerified: boolean;
+}
+export interface SetupContext {
+    client: SealMetricsClient;
+    baseUrl: string;
+    provisionKey: string;
+    /** install_source attribution (RF-3205). */
+    installSource: string;
+    /** Project root if the client exposes one (editors); undefined in Desktop chat. */
+    cwd?: string;
+    state: SetupState;
+    /**
+     * Called after a successful provision_site so the server adopts the api_key and
+     * enables the ~47 read-only tools in the same session (RF-3202b). The api_key is
+     * passed here but NEVER returned to the model (VAL-3201).
+     */
+    onProvisioned: (apiKey: string, accountId: string) => void;
+    /** Poll tuning (tests pass small values). Defaults: 2s interval, 25s timeout. */
+    pollDefaults?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+    };
+    /** Injectable clock/sleep for the instrumentation verifier (tests). */
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Setup tool shape (like ToolDef but the handler closes over the SetupContext). */
+export interface SetupToolDef {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        openWorldHint?: boolean;
+    };
+    handler: (args: Record<string, unknown>) => Promise<unknown>;
+}
+/** Build the five (RF-3203) setup tools bound to a context. */
+export declare function createSetupTools(ctx: SetupContext): SetupToolDef[];
+//# sourceMappingURL=setup.d.ts.map

package/dist/tools/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/tools/setup.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;IAClB;;;;OAIG;IACH,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D,iFAAiF;IACjF,YAAY,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;IACF,WAAW,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,OAAO,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/E,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9D;AAWD,+DAA+D;AAC/D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,EAAE,CAwUlE"}