@lacneu/wix-openclaw 0.5.1 → 0.6.0

package/dist/tools/analytics.js

@@ -0,0 +1,655 @@
+// Analytics — a discoverable query surface, plus one legacy endpoint.
+//
+// A THIRD KIND OF DANGER. The SEO writes destroyed the previous value of what
+// they wrote; the accessibility scans could call an unchecked site clean. Here
+// nothing is destroyed and nothing is scanned — what goes wrong is that the
+// ANSWER IS QUIETLY SHORTER THAN THE QUESTION. Wix says so in the contract's
+// own words, on the `fields` parameter:
+//
+//   "Fields with unmet dependencies (see the `dependencies` property in the
+//    semantic model schema) are silently omitted from results."
+//
+// So a report can be missing an entire measure and look finished: nobody sees
+// the column that never came back. Every answer here therefore names what was
+// asked for and did not arrive, and says when a result was cut short.
+//
+// Two more of the same shape, both from the contract:
+//   - a query returns at most 1000 rows, so a truncated set must never read as
+//     a total;
+//   - the legacy Data API's `endDate` is EXCLUSIVE — `2024-01-01 → 2024-01-03`
+//     returns the 1st and the 2nd — so the days actually covered are stated,
+//     not left to be inferred.
+//
+// Contract sourced from the public Introductions and from the published SDK
+// packages `@wix/auto_sdk_analytics-semantic-model_analytics-semantic-model`
+// and `@wix/auto_sdk_analytics-data_analytics-data`, whose own host mappings
+// give the REST prefixes verbatim. No path here is inferred from a convention.
+import { Type } from "@sinclair/typebox";
+import { defineWixTool } from "./_factory.js";
+import { compactQuery } from "./_query.js";
+import { WixApiError } from "../wix-client.js";
+const SiteIdParam = Type.Optional(Type.String());
+/** srcPath "/analytics/semantic-model/v3/semantic-models" → destPath "/v3/…" */
+const MODELS = "/analytics/semantic-model/v3/semantic-models";
+/** srcPath "/analytics-ng/v2" → destPath "/v2", protoPath "/v2/site-analytics/data" */
+const DATA = "/analytics-ng/v2/site-analytics/data";
+// TWO CONVENTIONS THIS MODULE REFUSES TO INVENT, and the evidence, because
+// review has proposed both three times:
+//
+//   - the semantic `interval` end bound. The full method reference describes
+//     `start` and `end` only as "an absolute instant"; the sole "inclusive" and
+//     "exclusive" wording on that page belongs to the RANGE_* FILTER
+//     conditions, not to the interval. And Wix's own example ends a period at
+//     `…T23:59:59.000Z` rather than at the next midnight, which is what an
+//     INCLUSIVE bound looks like. Advising "the next period's start" would
+//     silently drop a whole day if the bound is inclusive; advising "the last
+//     instant you mean" costs at most one second if it is exclusive. The tool
+//     states that the convention is undocumented and lets the caller choose.
+//   - the timezone applied when none is passed. The reference documents the
+//     defaults it does have — `paging.limit` is 50, `paging.offset` is 0,
+//     `formattingEnabled` is false, `totalsIncluded` is false — and names none
+//     for `timezone`. Reporting a guessed default would put day boundaries in
+//     a report that nothing supports.
+//
+// If either is ever documented, replace the wording — and only then.
+// A BOUND THIS LOT DOES NOT RESOLVE, written down rather than guessed.
+//
+// These calls go out site-scoped, so the client sends `wix-site-id` and not
+// `wix-account-id` — the two are mutually exclusive in this plugin, and
+// `wix-site-id` is what the site whitelist is enforced on. Since the error is
+// literally named `NO_ACCOUNT_IDENTITY`, it is possible that one or more of
+// these endpoints wants the account header instead. Switching to it would
+// silently remove the whitelist from this family, which is the plugin's main
+// safety property, on nothing better than the wording of an error name — the
+// reference itself calls the scope "Site Analytics" and classifies the error
+// as a 401 about credentials, both of which point the other way.
+//
+// So: site-scoped, and if a live call with a valid key still answers
+// NO_ACCOUNT_IDENTITY, that is the experiment that settles it. It has not been
+// run.
+/** An abort is not a failed read. Swallowed by a general `catch`, a cancelled
+ *  call carried on and answered `ok` with a generic explanation — the caller
+ *  had already given up, and got an answer that looked like a result. */
+function rethrowIfAborted(err, signal) {
+    if (signal?.aborted === true)
+        throw err;
+    if (err instanceof Error && err.name === "AbortError")
+        throw err;
+}
+/** Wix returns at most this many rows per query.
+ *
+ *  From the Introduction, verbatim: "A single query can return up to 1,000
+ *  rows." The request schema separately allows `paging.limit` up to 5000; the
+ *  smaller, documented number is used, because over-asking would make the
+ *  truncation check answer about a page size the service may not honour. */
+const ROW_CAP = 1000;
+/** What we ask for when the caller does not say.
+ *
+ *  NOT `ROW_CAP`. The whole response is serialised into the model's context, and
+ *  1000 rows across up to 60 fields is tens of thousands of values — enough to
+ *  swamp the context on an ordinary question. A conservative page keeps the tool
+ *  usable while `rowsMayBeTruncated` still reports a full page exactly, because
+ *  the limit is sent rather than assumed. A caller who wants more says so. */
+const DEFAULT_LIMIT = 100;
+/** The six measurement types the legacy Data API defines. Listed so a typo
+ *  fails here, with the whole set in front of the caller, instead of coming
+ *  back as an empty series that reads like "no activity". */
+const MEASURES = [
+    "TOTAL_SESSIONS",
+    "TOTAL_UNIQUE_VISITORS",
+    "TOTAL_ORDERS",
+    "TOTAL_SALES",
+    "TOTAL_FORMS_SUBMITTED",
+    "CLICKS_TO_CONTACT",
+];
+// ---------------------------------------------------------------------------
+// The honesty layer.
+// ---------------------------------------------------------------------------
+/** Which requested fields never came back?
+ *
+ *  A DROPPED FIELD IS INVISIBLE IN THE RESPONSE. The rows simply lack the key,
+ *  so a caller mapping over them reads `undefined` and, more often, never looks
+ *  — the measure is missing from the report and nothing said so. */
+function fieldsOf(row) {
+    // A ROW IS `{ fields: { name: value } }`, NOT a flat object. Reading the
+    // outer level found only the key `fields`, so every requested field looked
+    // absent on every real response. The flat form is still accepted, because
+    // being wrong in that direction costs nothing.
+    const inner = row.fields;
+    const source = inner !== null && typeof inner === "object" && !Array.isArray(inner)
+        ? inner
+        : row;
+    return Object.keys(source);
+}
+/** Which requested fields never came back, and which cannot be judged.
+ *
+ *  TWO DIFFERENT ANSWERS. Data rows establish presence for anything —
+ *  dimensions included. The totals row does not: the contract defines it as the
+ *  sum of the NUMERIC fields, so a dimension is not expected there and its
+ *  absence from it proves nothing. With no data rows at all, a measure found in
+ *  the totals did come back; everything else is unknown, not missing. */
+function judgePresence(requested, rows, totals) {
+    const inTotals = new Set(totals !== undefined ? fieldsOf(totals) : []);
+    if (rows.length === 0) {
+        return {
+            missing: [],
+            undeterminable: requested.filter((f) => !inTotals.has(f)),
+        };
+    }
+    // ROWS ONLY, ON PURPOSE. `totals` is a SEPARATE aggregate over the whole
+    // result set; it does not supply the per-row column that was asked for. A
+    // measure present in the totals and absent from every row IS missing from
+    // this answer, and letting the totals cover for it put `fieldsNotReturned: []`
+    // on a response whose column was gone.
+    const present = new Set();
+    for (const row of rows)
+        for (const k of fieldsOf(row))
+            present.add(k);
+    return {
+        missing: requested.filter((f) => !present.has(f)),
+        undeterminable: [],
+    };
+}
+/** Every field name the model declares, across measures, dimensions and
+ *  parameters. */
+function declaredNames(model) {
+    const all = [
+        ...(Array.isArray(model?.measures) ? model.measures : []),
+        ...(Array.isArray(model?.dimensions) ? model.dimensions : []),
+        ...(Array.isArray(model?.parameters) ? model.parameters : []),
+    ];
+    return new Set(all.map((f) => f.name).filter((n) => typeof n === "string"));
+}
+/** Why a field was dropped, from the model's own schema.
+ *
+ *  The rule is "at least one of `dependencies` must also be in the query", so
+ *  the plugin can say exactly what to add — the caller should not have to
+ *  re-derive it from a schema it already asked the plugin to read. */
+function explainMissing(missing, fields, model, schemaRead) {
+    // NO SCHEMA, NO EXPLANATION. With the model unread, every field looked
+    // "not declared by the model" — a factual claim invented out of a failed
+    // second request. The report of what is missing stands on its own; the
+    // cause does not.
+    if (!schemaRead) {
+        return missing.map((field) => ({
+            field,
+            reason: "this field did not come back, and the model's schema could not be read — the cause is NOT established. Do not treat its absence as a zero.",
+        }));
+    }
+    const all = [
+        ...(Array.isArray(model?.measures) ? model.measures : []),
+        ...(Array.isArray(model?.dimensions) ? model.dimensions : []),
+        ...(Array.isArray(model?.parameters) ? model.parameters : []),
+    ];
+    const asked = new Set(fields);
+    return missing.map((name) => {
+        const decl = all.find((f) => f.name === name);
+        if (decl === undefined) {
+            return {
+                field: name,
+                reason: "this field is not declared by the model — check the spelling against `wix_analytics_get_semantic_model`",
+            };
+        }
+        const deps = Array.isArray(decl.dependencies)
+            ? decl.dependencies
+            : [];
+        if (deps.length === 0) {
+            return {
+                field: name,
+                reason: "the model declares this field with no dependencies, so its absence is not explained by the dependency rule — treat this result as incomplete rather than as a zero",
+            };
+        }
+        if (deps.some((d) => asked.has(d))) {
+            // NO `addOneOf` HERE. The dependency is already in the query, so handing
+            // the list back invites the same request a second time instead of
+            // treating the result as incomplete.
+            return {
+                field: name,
+                reason: "a dependency of this field WAS in the query, so the dependency rule does not explain its absence — treat this result as incomplete rather than as a zero",
+            };
+        }
+        return {
+            field: name,
+            reason: "none of this field's dependencies was in the query, so Wix omitted it silently",
+            addOneOf: deps,
+        };
+    });
+}
+/** The documented application errors, and what each means for the caller. */
+const ERROR_GUIDANCE = {
+    NO_ACCOUNT_IDENTITY: "Wix did not accept this identity for analytics. The reference classifies this as HTTP 401 / UNAUTHENTICATED: \"The caller isn't authenticated. Provide valid credentials and try again.\" So fix the CREDENTIALS first — the API key or the identity context it is sent with. Granting a permission does not fix an unauthenticated call. (Separately, all four methods require `SCOPE.DC-ANALYTICS-AND-REPORTS.READ-SITE-ANALYTICS`; that is a prerequisite to check once authentication works, not the meaning of this code.) It is NEVER evidence of a site with no traffic. Stop here and report it; do not retry with another range or another model.",
+    SEMANTIC_MODEL_NOT_FOUND: "No semantic model with that id. Call `wix_analytics_list_semantic_models` and use an id from it — the models available depend on the site and its installed apps.",
+};
+function explainError(err) {
+    if (!(err instanceof WixApiError))
+        return undefined;
+    const body = err.bodyPreview;
+    let structuredCode;
+    try {
+        const parsed = JSON.parse(body);
+        const code = parsed.details?.applicationError?.code;
+        if (typeof code === "string")
+            structuredCode = code;
+    }
+    catch {
+        // Unparseable body: fall through to the text checks below.
+    }
+    if (structuredCode !== undefined) {
+        // A STRUCTURED CODE THIS VERSION DOES NOT KNOW ENDS THE CLASSIFICATION,
+        // for the same reason as in the accessibility module: answering a new
+        // error as a known one returns `ok` with the wrong recovery.
+        const known = ERROR_GUIDANCE[structuredCode];
+        return known === undefined
+            ? undefined
+            : { code: structuredCode, guidance: known };
+    }
+    // THE 62-DAY BOUND ARRIVES AS PROSE, not as a code — the reference quotes the
+    // message verbatim. Matching it is the only way to turn it into the one thing
+    // the caller needs to know: the data does not exist, the query was not wrong.
+    if (/do not have data for this start date/i.test(body)) {
+        return {
+            code: "START_DATE_BEYOND_RETENTION",
+            guidance: "Wix stores analytics data for 62 days only. A `startDate` more than 61 days before today is refused. This is a RETENTION limit, not an empty site: move the start date forward and say in the report that earlier data does not exist.",
+        };
+    }
+    for (const code of Object.keys(ERROR_GUIDANCE)) {
+        if (body.includes(code))
+            return { code, guidance: ERROR_GUIDANCE[code] };
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+export function buildAnalyticsTools(client) {
+    return [
+        defineWixTool({
+            name: "wix_analytics_list_semantic_models",
+            description: "ENTRY POINT for analytics. The semantic models this site exposes — " +
+                "each one an analytics subject area such as traffic or revenue. What " +
+                "exists depends on the site and its installed apps, so this list is " +
+                "READ, never assumed: there is no fixed set of models, measures or " +
+                "dimensions to hardcode. Take an `id` from here, inspect it with " +
+                "`wix_analytics_get_semantic_model`, then query it. Read-only.",
+            parameters: Type.Object({ siteId: SiteIdParam }),
+            run: async (params, c, signal) => {
+                try {
+                    return await c.request("GET", MODELS, {
+                        siteId: params.siteId,
+                        signal,
+                    });
+                }
+                catch (err) {
+                    const known = explainError(err);
+                    if (known === undefined)
+                        throw err;
+                    return { refused: known.code, ...known };
+                }
+            },
+        }, client),
+        defineWixTool({
+            name: "wix_analytics_get_semantic_model",
+            description: "One model's SCHEMA: its measures, dimensions and parameters, each " +
+                "with the exact `name` to put in a query, its type, whether it is " +
+                "sortable, its allowed values, and its `dependencies`. " +
+                "CALL THIS BEFORE QUERYING. A field whose dependencies are not also " +
+                "in the query is dropped from the results by Wix WITHOUT AN ERROR, " +
+                "so a query written without the schema can come back quietly short. " +
+                "This is also the only way to know whether this site exposes a " +
+                "per-page or per-URL dimension — that is a property of the site, not " +
+                "something to assume either way. Read-only.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                semanticModelId: Type.String({ minLength: 1 }),
+            }),
+            run: async (params, c, signal) => {
+                try {
+                    return await c.request("GET", `${MODELS}/${encodeURIComponent(params.semanticModelId)}`, { siteId: params.siteId, signal });
+                }
+                catch (err) {
+                    const known = explainError(err);
+                    if (known === undefined)
+                        throw err;
+                    return { refused: known.code, ...known };
+                }
+            },
+        }, client),
+        defineWixTool({
+            name: "wix_analytics_query_semantic_model",
+            description: "Query one semantic model over a time interval. `fields` are the " +
+                "exact names from `wix_analytics_get_semantic_model` — a name that " +
+                "does not match returns nothing rather than an error. " +
+                "THE ANSWER CAN BE SHORTER THAN THE QUESTION: Wix silently omits a " +
+                "field whose dependencies are absent, so this tool compares what you " +
+                "asked for against what came back and reports every field that did " +
+                "not arrive, with the dependency to add. It also says when the " +
+                "1000-row cap was reached — a truncated set is never a total. " +
+                "`timezone` decides where each day starts; it is echoed back so a " +
+                "report can state it, and the contract does not document what Wix " +
+                "uses when it is omitted — pass it. The end bound's convention is " +
+                "not documented either: give the last instant you mean. " +
+                "UNIQUE MEASURES ARE NOT ADDITIVE across rows — ask for the period " +
+                "total rather than summing. Read-only.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                semanticModelId: Type.String({ minLength: 1 }),
+                fields: Type.Array(Type.String({ minLength: 1 }), {
+                    minItems: 1,
+                    maxItems: 60,
+                    description: "Exact field names from the model's schema. Mixing measures and the dimensions they depend on is what makes a query return data.",
+                }),
+                start: Type.String({
+                    minLength: 1,
+                    description: "Interval start, ISO 8601.",
+                }),
+                end: Type.String({
+                    minLength: 1,
+                    description: "Interval end, ISO 8601. The contract does NOT say whether this bound is inclusive, and Wix's own reference example ends a period at `…T23:59:59.000Z` rather than at the next midnight — so give the last instant you mean rather than assuming either convention.",
+                }),
+                timezone: Type.Optional(Type.String({
+                    description: "IANA timezone deciding where each day begins, e.g. `Europe/Paris`. Omitting it lets Wix choose, and day boundaries move.",
+                })),
+                limit: Type.Optional(Type.Integer({
+                    minimum: 1,
+                    maximum: ROW_CAP,
+                    description: `Rows to ask for. Defaults to ${DEFAULT_LIMIT}: the whole response goes into the model's context, and Wix's own ceiling of ${ROW_CAP} rows across up to 60 fields would swamp it. Raise it deliberately.`,
+                })),
+                offset: Type.Optional(Type.Integer({ minimum: 0 })),
+                totalsIncluded: Type.Optional(Type.Boolean()),
+                sort: Type.Optional(Type.Object({
+                    fieldName: Type.String({ minLength: 1 }),
+                    order: Type.Optional(Type.Union([Type.Literal("ASC"), Type.Literal("DESC")])),
+                    nullsLast: Type.Optional(Type.Boolean()),
+                }, {
+                    description: "Sort by ONE field. The schema says per field whether it is `sortable` — check it before sorting, and note that a top-N answer needs both a sort and a `limit`.",
+                })),
+                filters: Type.Optional(Type.Array(
+                // THE CONTRACT'S OWN SHAPE: `field`, and `values` as a LIST —
+                // not `fieldName`/`value`. A range condition takes exactly two
+                // values, the start and the end.
+                Type.Object({
+                    field: Type.String({
+                        minLength: 1,
+                        description: "Must match a measure or dimension name from the model's schema.",
+                    }),
+                    values: Type.Array(Type.String(), {
+                        maxItems: 100,
+                        description: "Values to compare against. A RANGE_* condition takes exactly two: the start and the end.",
+                    }),
+                    // CLOSED SETS, because they ARE closed. A plausible
+                    // invention like `NOT_EQUAL` used to be accepted by the tool
+                    // and rejected by Wix — the schema promising something the API
+                    // does not honour. Negation is `prefix: "NOT"`, not a
+                    // condition of its own.
+                    condition: Type.Optional(Type.Union([
+                        Type.Literal("EQUAL"),
+                        Type.Literal("GREATER_THAN"),
+                        Type.Literal("GREATER_THAN_OR_EQUAL"),
+                        Type.Literal("LESS_THAN"),
+                        Type.Literal("LESS_THAN_OR_EQUAL"),
+                        Type.Literal("NULL"),
+                        Type.Literal("EMPTY"),
+                        Type.Literal("START_WITH"),
+                        Type.Literal("END_WITH"),
+                        Type.Literal("CONTAINS_ANY"),
+                        Type.Literal("CONTAINS_ALL"),
+                        Type.Literal("RANGE_II"),
+                        Type.Literal("RANGE_IE"),
+                        Type.Literal("RANGE_EI"),
+                        Type.Literal("RANGE_EE"),
+                    ], {
+                        description: "Default `EQUAL`. The model's schema lists which conditions each field supports; a RANGE_* condition takes exactly two `values`.",
+                    })),
+                    prefix: Type.Optional(Type.Union([Type.Literal("IS"), Type.Literal("NOT")], {
+                        description: "Default `IS`. `NOT` negates the condition — there is no separate negated condition.",
+                    })),
+                }), {
+                    maxItems: 60,
+                    description: "Filters, combined with AND. Without them a question like `the ten busiest days` cannot be expressed at all.",
+                })),
+                formattingEnabled: Type.Optional(Type.Boolean()),
+            }),
+            run: async (params, c, signal) => {
+                // A RANGE CONDITION TAKES EXACTLY TWO VALUES, says the contract.
+                // Accepting one or three passed this tool's own validation and then
+                // failed at Wix — the schema promising something it does not honour.
+                for (const f of params.filters ?? []) {
+                    if (typeof f.condition === "string" &&
+                        f.condition.startsWith("RANGE_") &&
+                        f.values.length !== 2) {
+                        throw new Error(`Refusing to query: filter on \`${f.field}\` uses ${f.condition} ` +
+                            `with ${f.values.length} value(s). A RANGE condition takes ` +
+                            "exactly two: the start and the end of the range.");
+                    }
+                }
+                let resp = null;
+                try {
+                    resp = (await c.request("POST", `${MODELS}/query-data`, {
+                        siteId: params.siteId,
+                        signal,
+                        body: {
+                            semanticModelId: params.semanticModelId,
+                            interval: {
+                                start: params.start,
+                                end: params.end,
+                                ...(params.timezone !== undefined
+                                    ? { timezone: params.timezone }
+                                    : {}),
+                            },
+                            fields: params.fields,
+                            // THE LIMIT IS ALWAYS SENT. The documented default is
+                            // `paging.limit = 50`, so omitting it returned the first 50
+                            // rows of a larger answer while truncation was judged
+                            // against 1000 — a first page reported as the whole thing.
+                            // Sent explicitly, "did it hit the limit" is exact.
+                            paging: {
+                                limit: params.limit ?? DEFAULT_LIMIT,
+                                ...(params.offset !== undefined
+                                    ? { offset: params.offset }
+                                    : {}),
+                            },
+                            ...(params.totalsIncluded !== undefined
+                                ? { totalsIncluded: params.totalsIncluded }
+                                : {}),
+                            ...(params.sort !== undefined ? { sort: params.sort } : {}),
+                            ...(params.filters !== undefined
+                                ? { filters: params.filters }
+                                : {}),
+                            ...(params.formattingEnabled !== undefined
+                                ? { formattingEnabled: params.formattingEnabled }
+                                : {}),
+                        },
+                    }));
+                }
+                catch (err) {
+                    const known = explainError(err);
+                    if (known === undefined)
+                        throw err;
+                    return { refused: known.code, ...known };
+                }
+                const rows = Array.isArray(resp?.results)
+                    ? resp.results
+                    : [];
+                const totalsRow = resp?.totals !== null &&
+                    typeof resp?.totals === "object" &&
+                    !Array.isArray(resp.totals)
+                    ? resp.totals
+                    : undefined;
+                const { missing, undeterminable } = judgePresence(params.fields, rows, totalsRow);
+                // A DIMENSION IS NOT EXPECTED IN THE TOTALS ROW, so with no data
+                // rows its absence proves nothing — that is "unknown", not
+                // "missing", and an invalid field name looks identical.
+                const noRows = undeterminable.length > 0;
+                // THE SCHEMA IS READ ONLY WHEN IT CAN CHANGE THE ANSWER: something
+                // is missing, or nothing came back at all. The happy path pays
+                // nothing.
+                let explained = [];
+                let undeclared = [];
+                let schemaRead = false;
+                if (missing.length > 0 || noRows) {
+                    let model;
+                    try {
+                        const got = (await c.request("GET", `${MODELS}/${encodeURIComponent(params.semanticModelId)}`, { siteId: params.siteId, signal }));
+                        model = (got?.semanticModel ?? got ?? undefined);
+                        schemaRead = model !== undefined;
+                    }
+                    catch (err) {
+                        rethrowIfAborted(err, signal);
+                        // The explanation is a courtesy; the REPORT of what is missing
+                        // is not, and it stands without the schema.
+                    }
+                    if (schemaRead) {
+                        const declared = declaredNames(model);
+                        undeclared = params.fields.filter((f) => !declared.has(f));
+                    }
+                    // THE DEPENDENCY RULE IS A FACT ABOUT THE SCHEMA, not about the
+                    // data — so it explains just as much when NOTHING came back. An
+                    // empty page used to answer only "no data returned" for a field
+                    // the schema already proved could not have been returned, hiding
+                    // the very mistake this layer exists to name.
+                    const toExplain = missing.length > 0 ? missing : undeterminable;
+                    if (toExplain.length > 0 && schemaRead) {
+                        explained = explainMissing(toExplain, params.fields, model, schemaRead).filter((e) => 
+                        // On an empty page, keep only the reasons that do NOT depend
+                        // on the data: a dependency that was absent, or a name the
+                        // model does not declare. "Incomplete result" says nothing
+                        // there and would read as a finding.
+                        missing.length > 0 ||
+                            e.addOneOf !== undefined ||
+                            /not declared by the model/.test(e.reason));
+                    }
+                    else if (missing.length > 0) {
+                        explained = explainMissing(missing, params.fields, model, schemaRead);
+                    }
+                }
+                const sentLimit = params.limit ?? DEFAULT_LIMIT;
+                // A FULL PAGE IS NOT PROOF OF TRUNCATION. Exactly `limit` rows
+                // may be the entire answer, and `pagingMetadata` carries no total to
+                // settle it — so this says MAYBE, and says how to find out. Claiming
+                // "cut short" for a complete result is the same false certainty this
+                // module exists to avoid, pointed the other way.
+                const maybeTruncated = rows.length >= sentLimit;
+                // AN OFFSET ALREADY OMITTED EVERYTHING BEFORE IT. A short last page
+                // reported nothing partial, so a single call on page three read like
+                // the whole interval.
+                const skipped = params.offset ?? 0;
+                return {
+                    results: rows,
+                    pagingMetadata: resp?.pagingMetadata,
+                    interval: {
+                        start: params.start,
+                        end: params.end,
+                        timezone: params.timezone ??
+                            "NOT SPECIFIED — the contract does not document the default, so the day boundaries behind these numbers are unknown. Pass `timezone` before reporting anything per-day.",
+                    },
+                    // COUNTED AND NAMED, not left in prose. A measure that never came
+                    // back is invisible in the rows themselves.
+                    fieldsRequested: params.fields.length,
+                    fieldsNotReturned: missing,
+                    ...(explained.length > 0 ? { whyFieldsAreMissing: explained } : {}),
+                    ...(noRows
+                        ? {
+                            fieldPresenceUndeterminable: undeterminable,
+                            noRowsCaveat: "NO DATA ROWS CAME BACK, so this response cannot say whether these fields would have arrived — an invalid field name gives the same empty result as a genuinely quiet period. Report it as 'no data returned', not as zeros.",
+                        }
+                        : {}),
+                    ...(undeclared.length > 0
+                        ? {
+                            fieldsNotDeclaredByTheModel: undeclared,
+                            fieldsNotDeclaredCaveat: "The model does not declare these names. Check them against `wix_analytics_get_semantic_model` — a name that does not match returns nothing rather than an error.",
+                        }
+                        : {}),
+                    rowsMayBeTruncated: maybeTruncated,
+                    rowsRequestedAtMost: sentLimit,
+                    rowsSkippedByOffset: skipped,
+                    ...(skipped > 0
+                        ? {
+                            offsetCaveat: `This page starts at offset ${skipped}, so it OMITS every row before it by construction. It is a slice, not the interval — say so, or page from 0.`,
+                        }
+                        : {}),
+                    // NOT CONDITIONAL ON THE PAGE BEING FULL. Whether a measure can be
+                    // added up is a property of the measure, and seven daily rows are
+                    // just as easy to sum wrongly as a thousand.
+                    additivity: "Before summing anything: a UNIQUE measure such as unique visitors counts the same person once per row, so adding rows overstates it — and `totalsIncluded` does not rescue it either, since `totals` is defined as the SUM of the numeric fields. The only meaningful total for a unique measure is a query for it over the whole interval WITHOUT a grouping dimension.",
+                    ...(maybeTruncated
+                        ? {
+                            caveat: "This result fills the page exactly, so it MAY be the first page of more — nothing in the response settles it. Page with `offset` until fewer rows come back before drawing any conclusion about the whole period. And do NOT add the rows up: a UNIQUE measure such as unique visitors counts the same person once per row, so summing rows overstates it however many pages you fetch. See `additivity` before summing.",
+                        }
+                        : {}),
+                    // An absent `totals` is not a zero: it is simply not asked for.
+                    // A REQUESTED TOTAL THAT DID NOT COME BACK MUST STILL SAY SO.
+                    // Left as `undefined`, `JSON.stringify` dropped the key entirely —
+                    // so the one guarantee that matters here, "an absent total is not
+                    // a zero", vanished exactly when the total was actually absent.
+                    totals: params.totalsIncluded !== true
+                        ? "not requested — pass `totalsIncluded: true` to get it; its absence is not a zero"
+                        : totalsRow !== undefined
+                            ? resp?.totals
+                            : "REQUESTED BUT NOT RETURNED — Wix omitted the totals row. That is not a zero: query the period directly, or check that the fields you asked for can be totalled at all.",
+                };
+            },
+        }, client),
+        defineWixTool({
+            name: "wix_analytics_get_data",
+            description: "The legacy site-wide counters: sessions, unique visitors, orders, " +
+                "sales, forms submitted, clicks to contact. SITE LEVEL ONLY — there " +
+                "is no per-page breakdown here; for anything richer use the semantic " +
+                "models. " +
+                "TWO BOUNDS THAT CHANGE WHAT THE NUMBERS MEAN. Wix keeps 62 days: a " +
+                "`startDate` more than 61 days back is refused, and that is a " +
+                "retention limit, not an empty site. And `endDate` is EXCLUSIVE — " +
+                "`2024-01-01` to `2024-01-03` covers the 1st and the 2nd — so this " +
+                "tool reports the days it actually covered. Read-only.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                startDate: Type.String({
+                    minLength: 1,
+                    description: "ISO date, e.g. `2026-08-01`. At most 61 days back.",
+                }),
+                endDate: Type.String({
+                    minLength: 1,
+                    description: "ISO date, EXCLUSIVE — the returned data stops the day before.",
+                }),
+                measurementTypes: Type.Array(Type.String({ minLength: 1 }), {
+                    minItems: 1,
+                    description: `One or more of: ${MEASURES.join(", ")}.`,
+                }),
+                timeZone: Type.Optional(Type.String()),
+            }),
+            run: async (params, c, signal) => {
+                // A TYPO WOULD COME BACK AS AN EMPTY SERIES, which reads like "no
+                // activity" rather than "you asked for something that does not
+                // exist". The whole set is put in front of the caller instead.
+                const unknown = params.measurementTypes.filter((m) => !MEASURES.includes(m));
+                if (unknown.length > 0) {
+                    throw new Error(`Refusing to query: unknown measurement type(s) ${unknown.join(", ")}. ` +
+                        `This endpoint defines exactly six: ${MEASURES.join(", ")}.`);
+                }
+                try {
+                    const resp = (await c.request("GET", DATA, {
+                        siteId: params.siteId,
+                        signal,
+                        query: compactQuery({
+                            "dateRange.startDate": params.startDate,
+                            "dateRange.endDate": params.endDate,
+                            timeZone: params.timeZone,
+                            measurementTypes: params.measurementTypes,
+                        }),
+                    }));
+                    return {
+                        data: resp?.data,
+                        // SAID, NOT INFERRED. The exclusive end is an off-by-one that
+                        // silently drops the last day a caller thought it asked for.
+                        covers: `${params.startDate} up to but NOT including ${params.endDate}`,
+                        siteLevelOnly: true,
+                    };
+                }
+                catch (err) {
+                    const known = explainError(err);
+                    if (known === undefined)
+                        throw err;
+                    return { refused: known.code, ...known };
+                }
+            },
+        }, client),
+    ];
+}
+//# sourceMappingURL=analytics.js.map