@sealmetrics/mcp 1.2.0 → 1.3.0

package/dist/tools/pages.js

@@ -1,7 +1,100 @@
 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, entrances, conversions. Useful for finding most popular pages and content performance.",
+    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: {
@@ -15,7 +108,7 @@ export const getPagesTool = {
             sort_by: {
                 type: "string",
                 description: "Field to sort by.",
-                enum: ["page_views", "entrances", "engaged_entrances", "conversions", "revenue"],
+                enum: ["page_views", "entrances"],
                 default: "page_views",
             },
             sort_order: SORT_ORDER_SCHEMA,
@@ -24,6 +117,7 @@ export const getPagesTool = {
                 type: "string",
                 description: "Filter pages by URL path pattern (e.g. '/blog').",
             },
+            ...MULTI_FILTER_SCHEMA,
         },
     },
     handler: async (client, args) => {
@@ -36,12 +130,16 @@ export const getPagesTool = {
             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.",
+    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: {
@@ -64,6 +162,7 @@ export const getLandingPagesTool = {
                 type: "string",
                 description: "Filter by URL path pattern.",
             },
+            ...MULTI_FILTER_SCHEMA,
         },
     },
     handler: async (client, args) => {
@@ -76,6 +175,7 @@ export const getLandingPagesTool = {
             sort_by: args.sort_by ?? "entrances",
             sort_order: args.sort_order ?? "desc",
             path_filter: args.path_filter,
+            ...pickMultiFilters(args),
         });
     },
 };

package/dist/tools/pages.js.map

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

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"}

package/dist/tools/setup.js

@@ -0,0 +1,347 @@
+/**
+ * MCP write-path setup tools (Fase 3 Bloque 2, RF-3203). These let a user register
+ * + verify a SealMetrics site **from the chat** (Claude Desktop, no terminal),
+ * reusing `@sealmetrics/setup-core` (Bloque 1) so the logic is never duplicated
+ * CLI↔MCP. The MCP never edits the user's source (RF-3204) — provision_site hands
+ * back the snippet + guide; the agent (with repo) or the human (paste) places it.
+ *
+ * Privacy/secret handling (VAL-3201/3203, RF-3207):
+ *  - provision_site NEVER returns the api_key to the model (it is adopted into
+ *    memory to enable the read-only tools and saved by the user via env/email).
+ *  - provision_site NEVER returns the claim_url magic-link token (it goes by
+ *    email); it returns `claim_email_sent_to` + `dashboard_url` only.
+ */
+import { detectFramework, buildProvisionBody, unwrapProvisionData, provisionErrorForStatus, fetchPixelStatus, pollPixelStatus, getInstrumentationGuide, getStackGuide, getPlatformPluginGuide, checkInstrumentation, detectPII, } from "@sealmetrics/setup-core";
+import { SealMetricsAPIError } from "../errors.js";
+/** Terms of Service URL — shown so the human can read them before accepting (parity with the CLI). */
+const TOS_URL = "https://sealmetrics.com/terms";
+function str(v) {
+    if (v === undefined || v === null)
+        return undefined;
+    const s = String(v).trim();
+    return s.length > 0 ? s : undefined;
+}
+/** Build the five (RF-3203) setup tools bound to a context. */
+export function createSetupTools(ctx) {
+    const provisionSite = {
+        name: "provision_site",
+        description: "Register a NEW free SealMetrics site from the chat (no terminal needed). Creates the account, returns the tracker snippet to place in your site's <head>, and emails you a claim link to set a password. After this succeeds, the read-only analytics tools are enabled in this session. Does NOT edit your code — you (or the agent, if it has the repo) place the snippet.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                site_name: { type: "string", description: "Human-friendly name for the site (e.g. 'My Shop')." },
+                domain: { type: "string", description: "Primary domain of the site (e.g. 'myshop.com'). Optional." },
+                email: { type: "string", description: "Your email — receives the claim link to set a password." },
+                name: { type: "string", description: "Your name. Optional." },
+                accept_terms: {
+                    type: "boolean",
+                    description: "Must be true: confirms the user has read and accepts the SealMetrics Terms of Service (https://sealmetrics.com/terms). Show the user this link first; do NOT accept on their behalf.",
+                },
+            },
+            required: ["site_name", "email", "accept_terms"],
+        },
+        annotations: { title: "Provision a SealMetrics site", readOnlyHint: false, openWorldHint: true },
+        handler: async (args) => {
+            if (args.accept_terms !== true && args.accept_terms !== "true") {
+                throw new Error(`accept_terms must be true. Show the user the SealMetrics Terms of Service (${TOS_URL}) and ask them to confirm — do not accept on their behalf.`);
+            }
+            const siteName = str(args.site_name);
+            const email = str(args.email);
+            if (!siteName)
+                throw new Error("site_name is required.");
+            if (!email)
+                throw new Error("email is required.");
+            const input = {
+                siteName,
+                domain: str(args.domain),
+                email,
+                name: str(args.name),
+                installSource: ctx.installSource, // "mcp" — attribution (RF-3205/RF-3604)
+            };
+            let envelope;
+            try {
+                envelope = await ctx.client.post("/provision", buildProvisionBody(input), {
+                    provisionKey: ctx.provisionKey,
+                });
+            }
+            catch (e) {
+                if (e instanceof SealMetricsAPIError) {
+                    // Map HTTP status → the shared ProvisionError code/message (TEST-3203/3601).
+                    const pe = provisionErrorForStatus(e.statusCode);
+                    throw new Error(`${pe.code}: ${pe.message}`);
+                }
+                throw e;
+            }
+            const result = unwrapProvisionData(envelope);
+            // Adopt the api_key + enable read-only tools (RF-3202b). NEVER returned to the model.
+            ctx.onProvisioned(result.api_key, result.account_id);
+            ctx.state.provisioned = true;
+            ctx.state.accountId = result.account_id;
+            // Return ONLY non-secret fields: no api_key (VAL-3201), no claim_url token (RF-3207/VAL-3203).
+            return {
+                account_id: result.account_id,
+                snippet: result.snippet,
+                dashboard_url: result.dashboard_url,
+                claim_email_sent_to: email,
+                free_quota: result.free_quota,
+                next_steps: [
+                    "Place the snippet in your site's <head> on every page. If the agent has your repo it can do this; otherwise paste it yourself.",
+                    "Run verify_setup once the snippet is live to confirm the pixel is sending data.",
+                    "Read-only analytics tools are now enabled in THIS session.",
+                    "To keep them after restarting Claude Desktop, paste the api_key from your welcome email into the SEALMETRICS_API_KEY field of the extension settings.",
+                    "Check your email to claim the account (set a password) — this unlocks the web dashboard. Analytics work without it.",
+                ],
+            };
+        },
+    };
+    const verifySetup = {
+        name: "verify_setup",
+        description: "Poll until the SealMetrics pixel is confirmed installed (a real pageview has reached the backend) or it times out. Run this after placing the snippet. Reads only — sends no data.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                account_id: {
+                    type: "string",
+                    description: "Site/account id to verify. Defaults to the site provisioned in this session.",
+                },
+                timeout_seconds: {
+                    type: "number",
+                    description: "Max seconds to wait for the first hit (default 25).",
+                },
+            },
+        },
+        annotations: { title: "Verify pixel install", readOnlyHint: true, openWorldHint: true },
+        handler: async (args) => {
+            const accountId = str(args.account_id) ?? ctx.state.accountId;
+            if (!accountId)
+                throw new Error("account_id is required (provision a site first).");
+            const apiKey = ctx.client.getApiKey();
+            if (!apiKey) {
+                throw new Error("AUTH_REQUIRED: no api_key available to verify. Provision a site first, or set SEALMETRICS_API_KEY.");
+            }
+            const timeoutMs = ctx.pollDefaults?.timeoutMs ??
+                (typeof args.timeout_seconds === "number" ? Math.max(0, args.timeout_seconds) * 1000 : 25_000);
+            const intervalMs = ctx.pollDefaults?.intervalMs ?? 2_000;
+            const res = await pollPixelStatus({
+                fetchStatus: () => fetchPixelStatus(accountId, { baseUrl: ctx.baseUrl, apiKey }),
+                timeoutMs,
+                intervalMs,
+            });
+            if (res.verified === true)
+                ctx.state.pixelVerified = true;
+            return {
+                account_id: accountId,
+                installed: res.verified === true,
+                status: res.verified === true ? "verified" : "pending",
+                total_hits: res.totalHits ?? 0,
+                next_steps: res.verified === true
+                    ? ["Pixel confirmed. You can now query analytics with the read-only tools."]
+                    : [
+                        "No hits yet. Make sure the snippet is in the <head> of a live page, then load that page and re-run verify_setup.",
+                    ],
+            };
+        },
+    };
+    const getSetupStatus = {
+        name: "get_setup_status",
+        description: "Report where the setup flow is: whether a site has been provisioned in this session and whether its pixel has been verified.",
+        inputSchema: { type: "object", properties: {} },
+        annotations: { title: "Setup status", readOnlyHint: true },
+        handler: async () => ({
+            provisioned: ctx.state.provisioned,
+            account_id: ctx.state.accountId,
+            pixel_verified: ctx.state.pixelVerified,
+        }),
+    };
+    const detectFrameworkTool = {
+        name: "detect_framework",
+        description: "Best-effort detect the web framework/CMS of a project so the snippet can be placed correctly. Pass `path` if you have the repo; in a pure chat (no repo) returns 'unknown' plus the manual guide. Read-only — never edits files.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Absolute path to the project root. Optional; omit if you don't have the repo.",
+                },
+            },
+        },
+        annotations: { title: "Detect framework", readOnlyHint: true },
+        handler: async (args) => {
+            const path = str(args.path) ?? ctx.cwd;
+            if (!path) {
+                const guide = getStackGuide("unknown");
+                return {
+                    framework: "unknown",
+                    strategy: "manual",
+                    location: guide.location,
+                    placement: guide.placement,
+                    provision_only: true,
+                    note: "No project path available (e.g. Claude Desktop chat). Provide `path` if you have the repo, or place the snippet manually using loading_notes.",
+                    loading_notes: guide.notes,
+                };
+            }
+            const d = detectFramework(path);
+            const guide = getStackGuide(d.framework);
+            return {
+                framework: d.framework,
+                platform: d.platform,
+                strategy: d.strategy,
+                location: d.recommendedLocation,
+                placement: d.placementHint,
+                provision_only: d.provisionOnly,
+                loading_notes: guide.notes,
+                ...(d.platform
+                    ? { plugin_guidance: getPlatformPluginGuide(d.platform, ctx.state.accountId ?? "[YOUR_ACCOUNT_ID]") }
+                    : {}),
+            };
+        },
+    };
+    const getInstrumentationGuideTool = {
+        name: "get_instrumentation_guide",
+        description: "Return the canonical SealMetrics event-instrumentation guide (closed conv/micro taxonomy + privacy rules) with your account_id substituted. Use it before writing sealmetrics.conv()/micro() calls. The MCP does NOT write these calls — the agent does, guided by this.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                account_id: {
+                    type: "string",
+                    description: "Account id to substitute into the guide. Defaults to the provisioned site.",
+                },
+            },
+        },
+        annotations: { title: "Instrumentation guide", readOnlyHint: true },
+        handler: async (args) => {
+            const accountId = str(args.account_id) ?? ctx.state.accountId ?? "[YOUR_ACCOUNT_ID]";
+            return { account_id: accountId, guide: getInstrumentationGuide(accountId) };
+        },
+    };
+    const verifyEventInstrumented = {
+        name: "verify_event_instrumented",
+        description: "Close the instrumentation loop (Fase 3 Bloque 4): after you add a sealmetrics.conv()/micro() call AND trigger it (a test visit/action), confirm the event reached the backend with the expected type. ALSO validates the event name against the closed taxonomy and rejects PII in properties before declaring success. Reads only.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                account_id: { type: "string", description: "Site/account id. Defaults to the provisioned site." },
+                kind: { type: "string", enum: ["conv", "micro"], description: "Event kind: 'conv' or 'micro'." },
+                name: { type: "string", description: "Event name (must be in the closed taxonomy, e.g. 'purchase')." },
+                timeout_seconds: { type: "number", description: "Max seconds to wait for the event (default 25)." },
+            },
+            required: ["kind", "name"],
+        },
+        annotations: { title: "Verify instrumented event", readOnlyHint: true, openWorldHint: true },
+        handler: async (args) => {
+            const accountId = str(args.account_id) ?? ctx.state.accountId;
+            if (!accountId)
+                throw new Error("account_id is required (provision a site first).");
+            const kind = str(args.kind);
+            const name = str(args.name);
+            if (kind !== "conv" && kind !== "micro")
+                throw new Error("kind must be 'conv' or 'micro'.");
+            if (!name)
+                throw new Error("name is required.");
+            const apiKey = ctx.client.getApiKey();
+            if (!apiKey)
+                throw new Error("AUTH_REQUIRED: no api_key available. Provision a site first or set SEALMETRICS_API_KEY.");
+            // 1) Static gate: taxonomy (VAL-3401) + PII (VAL-3402). Reject before confirming.
+            const check = checkInstrumentation(kind, name);
+            if (!check.taxonomy.valid) {
+                return {
+                    status: "rejected",
+                    reason: "out_of_taxonomy",
+                    name,
+                    suggestion: check.taxonomy.suggestion,
+                    message: `'${name}' is not in the closed ${kind} taxonomy.${check.taxonomy.suggestion ? ` Did you mean '${check.taxonomy.suggestion}'?` : ""} Fix the event name before verifying.`,
+                };
+            }
+            // 2) Confirm the event reached the backend by polling the raw endpoint and
+            //    matching by recency (the raw routes filter by date, not last-N-seconds).
+            const path = kind === "conv" ? "/stats/conversions/raw" : "/stats/microconversions/raw";
+            const typeParam = kind === "conv" ? "conversion_type" : "microconversion_type";
+            const timeoutMs = ctx.pollDefaults?.timeoutMs ??
+                (typeof args.timeout_seconds === "number" ? Math.max(0, args.timeout_seconds) * 1000 : 25_000);
+            const intervalMs = ctx.pollDefaults?.intervalMs ?? 3_000;
+            const startedAt = ctx.now ? ctx.now() : Date.now();
+            const deadline = startedAt + timeoutMs;
+            let found;
+            let piiFlagged = [];
+            for (;;) {
+                try {
+                    const raw = await ctx.client.requestDirect(path, {
+                        site_id: accountId,
+                        period: "today",
+                        [typeParam]: name,
+                        include_properties: "true",
+                        page_size: "20",
+                    });
+                    const rows = Array.isArray(raw?.data) ? raw.data : [];
+                    // Match the most recent row whose timestamp is at/after we started.
+                    for (const row of rows) {
+                        const ts = Date.parse(String(row.timestamp_utc ?? ""));
+                        if (Number.isFinite(ts) && ts >= startedAt - 5_000) {
+                            found = row;
+                            const findings = detectPropertiesPII(row.properties);
+                            piiFlagged = findings;
+                            break;
+                        }
+                    }
+                }
+                catch {
+                    // transient — keep polling until the deadline
+                }
+                if (found)
+                    break;
+                const nowMs = ctx.now ? ctx.now() : Date.now();
+                if (nowMs + intervalMs >= deadline)
+                    break;
+                await sleep(intervalMs, ctx.sleep);
+            }
+            if (!found) {
+                return {
+                    status: "pending",
+                    account_id: accountId,
+                    kind,
+                    name,
+                    message: `No '${name}' ${kind} event seen yet. Trigger the event (a test visit/action), then re-run. Raw endpoints lag ~2-5s.`,
+                };
+            }
+            if (piiFlagged.length > 0) {
+                return {
+                    status: "warning_pii",
+                    account_id: accountId,
+                    kind,
+                    name,
+                    pii_properties: piiFlagged,
+                    message: `Event '${name}' arrived, but its properties look like PII (${piiFlagged
+                        .map((f) => f.key)
+                        .join(", ")}). Remove personal data / order/user IDs — these must NEVER be tracked.`,
+                };
+            }
+            return {
+                status: "verified",
+                account_id: accountId,
+                kind,
+                name,
+                message: `Event '${name}' confirmed in SealMetrics with no PII. Instrumentation verified.`,
+            };
+        },
+    };
+    return [
+        provisionSite,
+        verifySetup,
+        getSetupStatus,
+        detectFrameworkTool,
+        getInstrumentationGuideTool,
+        verifyEventInstrumented,
+    ];
+}
+// Local helpers ---------------------------------------------------------------
+function sleep(ms, custom) {
+    if (custom)
+        return custom(ms);
+    return new Promise((r) => setTimeout(r, ms));
+}
+function detectPropertiesPII(properties) {
+    if (!properties || typeof properties !== "object")
+        return [];
+    return detectPII(properties).map((f) => ({ reason: f.reason, key: f.key }));
+}
+//# sourceMappingURL=setup.js.map

package/dist/tools/setup.js.map

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

package/dist/tools/shared.d.ts

@@ -1,11 +1,3 @@
-/**
- * Convert a period string (e.g. "30d", "this_month") to start_date / end_date.
- * Needed for endpoints that don't accept the `period` shorthand.
- */
-export declare function periodToDateRange(period: string): {
-    start_date: string;
-    end_date: string;
-};
 export declare const PERIOD_SCHEMA: {
     readonly type: "string";
     readonly description: "Time period for the report. Examples: \"today\", \"yesterday\", \"7d\", \"30d\", \"90d\", \"this_month\", \"last_month\", \"this_year\". Default: \"30d\".";
@@ -33,10 +25,6 @@ export declare const PAGE_SCHEMA: {
     readonly description: "Page number for paginated results (default: 1).";
     readonly default: 1;
 };
-/**
- * Validate a freeform string input: reject control characters and enforce length limit.
- */
-export declare function sanitizeInput(value: unknown, name: string, maxLen?: number): string | undefined;
 /**
  * Resolve site_id from tool args or SEALMETRICS_SITE_ID env var.
  * Throws if neither is available.

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

@@ -1 +1 @@
-{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/tools/shared.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CA6E1F;AAED,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX,eAAO,MAAM,cAAc;;;;CAKjB,CAAC;AAEX,eAAO,MAAM,YAAY;;;;CAIf,CAAC;AAEX,eAAO,MAAM,iBAAiB;;;;;CAKpB,CAAC;AAEX,eAAO,MAAM,WAAW;;;;CAId,CAAC;AAIX;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,SAAmB,GAAG,MAAM,GAAG,SAAS,CAUzG;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAYnE"}
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/tools/shared.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX,eAAO,MAAM,cAAc;;;;CAKjB,CAAC;AAEX,eAAO,MAAM,YAAY;;;;CAIf,CAAC;AAEX,eAAO,MAAM,iBAAiB;;;;;CAKpB,CAAC;AAEX,eAAO,MAAM,WAAW;;;;CAId,CAAC;AAEX;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CASnE"}