@lacneu/wix-openclaw 0.4.0 → 0.5.0

package/dist/tools/accessibility.js

@@ -0,0 +1,740 @@
+// Accessibility Scans — Wix runs the scan, this module reads the result.
+//
+// A DIFFERENT DISCIPLINE FROM THE SEO WRITES. Nothing here destroys anything:
+// there is no token, no refusal, no `wouldLose`. The way this module fails a
+// user is by letting an agent report a CLEAN SITE from an incomplete scan.
+// Wix states the rule plainly, and it has three parts:
+//
+//   "A page or category is clear only when it has no matching findings, its
+//    page status is completed, and its coverage confirms that the relevant
+//    checks ran."
+//
+//   "A failed page with zero findings is unknown, not clean."
+//
+// So the shape of every answer here carries what it does NOT know:
+// `PARTIALLY_COMPLETED` never collapses into success, a failed page is never
+// reported as zero findings, and a missing finding is never evidence that a
+// rule passed unless `coverage` says the rule ran. That is this module's
+// "redirects do not chain".
+//
+// Contract sourced from the public reference (Introduction, Sample Flows, the
+// Wix agent Skill) and from the published SDK package
+// `@wix/auto_sdk_accessibility_accessibility-scans`, whose own host mapping
+// gives the REST prefix verbatim:
+//   srcPath "/accessibility/v1/accessibility-scans" → destPath "/v1/…"
+// No path here is inferred from a convention.
+import { createHash } from "node:crypto";
+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());
+/** Base path of the Accessibility Scans service. */
+const SCANS = "/accessibility/v1/accessibility-scans";
+/** The scan's id, as REST actually names it.
+ *
+ *  The SDK typings call it `_id`, and that is the shape every documented
+ *  example shows — but the SDK renames three keys on the way back from REST
+ *  (`id -> _id`, `createdDate -> _createdDate`, `updatedDate -> _updatedDate`).
+ *  This plugin speaks REST directly, so the wire says `id`. Reading `_id` gave
+ *  `undefined` on every real call: a run that hands back no scan id leaves the
+ *  caller with nothing to poll. Both are accepted because they name the same
+ *  thing and being wrong in this direction costs nothing. */
+function scanIdOf(scan) {
+    const rest = scan?.id;
+    if (typeof rest === "string" && rest !== "")
+        return rest;
+    const sdk = scan?._id;
+    return typeof sdk === "string" && sdk !== "" ? sdk : undefined;
+}
+/** Terminal statuses, verbatim from the reference. Anything else means the
+ *  scan is still moving and its numbers are not a result yet. */
+const TERMINAL = new Set([
+    "ACCESSIBILITY_SCAN_STATUS_COMPLETED",
+    "ACCESSIBILITY_SCAN_STATUS_PARTIALLY_COMPLETED",
+    "ACCESSIBILITY_SCAN_STATUS_FAILED",
+]);
+/** Domain separation for the idempotency key — a CONSTANT, deliberately.
+ *
+ *  This is not a secret and must never behave like one. The SEO tokens are
+ *  minted per process because an acknowledgement must not survive a restart;
+ *  this key is the exact opposite: it exists so that a retry after a LOST
+ *  RESPONSE cannot create a second scan, and a gateway restart or a retry
+ *  landing on another worker is precisely when that happens. Keying it on the
+ *  pid made the guarantee evaporate in the only situation it was for. */
+const KEY_DOMAIN = "wix-openclaw/accessibility/idempotency/v1";
+// ---------------------------------------------------------------------------
+// The target. Exactly one of three, and a discriminator that must agree.
+// ---------------------------------------------------------------------------
+/** `targetType` is a DISCRIMINATOR Wix requires to match the populated field.
+ *  It is built here and never accepted from the caller: a target that says
+ *  `PAGE` while carrying a collection is rejected by Wix with an error the
+ *  agent then has to interpret, when the plugin already knew the answer. */
+function buildTarget(p) {
+    const chosen = [
+        p.fullSite === true ? "fullSite" : undefined,
+        p.pageId !== undefined && p.pageId !== "" ? "pageId" : undefined,
+        p.pageUrl !== undefined && p.pageUrl !== "" ? "pageUrl" : undefined,
+        p.collectionId !== undefined && p.collectionId !== ""
+            ? "collectionId"
+            : undefined,
+    ].filter((x) => x !== undefined);
+    if (chosen.length === 0) {
+        throw new Error("Refusing to scan: no target. A scan checks exactly one of `fullSite: " +
+            "true`, one page (`pageId` or `pageUrl`), or one page collection " +
+            "(`collectionId`, from `wix_a11y_list_page_collections`).");
+    }
+    if (chosen.length > 1) {
+        // A SILENT PRECEDENCE WOULD SCAN THE WRONG THING. Picking the first field
+        // found would answer about a page while the caller asked about the site,
+        // and the answer would look valid.
+        throw new Error(`Refusing to scan: ${chosen.length} targets given (${chosen.join(", ")}). ` +
+            "A scan checks exactly one target. Split this into one call per target.");
+    }
+    if (p.fullSite === true) {
+        return {
+            target: {
+                targetType: "SCOPE",
+                scope: "ACCESSIBILITY_SCAN_SCOPE_FULL_SITE",
+            },
+            key: "scope:FULL_SITE",
+            label: "the full site",
+        };
+    }
+    if (p.collectionId !== undefined && p.collectionId !== "") {
+        return {
+            target: {
+                targetType: "PAGE_COLLECTION",
+                pageCollection: { collectionId: p.collectionId },
+            },
+            key: `collection:${p.collectionId}`,
+            label: `the page collection ${p.collectionId}`,
+        };
+    }
+    // THE IDENTIFIER THAT WAS CHOSEN, not the first field that exists. With an
+    // empty `pageId` alongside a real `pageUrl`, `pageId ?? pageUrl` kept the
+    // empty string: every URL sharing an `attempt` then derived the SAME key and
+    // an empty label, so one page's scan answered for another's.
+    const usingId = p.pageId !== undefined && p.pageId !== "";
+    const identifier = usingId ? p.pageId : p.pageUrl;
+    return {
+        target: {
+            targetType: "PAGE",
+            page: usingId ? { pageId: identifier } : { pageUrl: identifier },
+        },
+        key: `page:${usingId ? "id" : "url"}:${identifier}`,
+        label: `the page ${identifier}`,
+    };
+}
+/** The same target, flattened into the dotted query keys a GET takes. */
+function targetQuery(target) {
+    const out = {
+        "target.targetType": String(target.targetType),
+    };
+    if (typeof target.scope === "string")
+        out["target.scope"] = target.scope;
+    const page = target.page;
+    if (page?.pageId !== undefined)
+        out["target.page.pageId"] = page.pageId;
+    if (page?.pageUrl !== undefined)
+        out["target.page.pageUrl"] = page.pageUrl;
+    const coll = target.pageCollection;
+    if (coll?.collectionId !== undefined) {
+        out["target.pageCollection.collectionId"] = coll.collectionId;
+    }
+    return out;
+}
+/** A GUID derived from site + target + attempt.
+ *
+ *  WHY NOT RANDOM. The key exists so a lost response cannot create duplicate
+ *  work: a retry must send the SAME key. A fresh random key per invocation
+ *  would satisfy the schema and make the entire idempotency contract inert —
+ *  every retry a new scan, against a 5-per-minute limit.
+ *
+ *  WHY NOT THE TARGET ALONE. Wix requires a NEW key for a genuinely new scan,
+ *  which is exactly what verifying a fix is. Deriving from the target only
+ *  would make the second scan a retry of the first and hand back the stale
+ *  result as if it were fresh.
+ *
+ *  So the caller names the attempt, and that name is the whole difference
+ *  between "retry this" and "scan again". */
+function idempotencyKey(site, targetKey, attempt) {
+    const h = createHash("sha256")
+        .update([KEY_DOMAIN, site, targetKey, attempt].join("\u0000"))
+        .digest("hex");
+    // Shaped as a v4 GUID: Wix declares `@format GUID`, max length 36.
+    const b = h.slice(0, 32).split("");
+    b[12] = "4";
+    b[16] = "89ab"[parseInt(h[16], 16) % 4];
+    const s = b.join("");
+    return `${s.slice(0, 8)}-${s.slice(8, 12)}-${s.slice(12, 16)}-${s.slice(16, 20)}-${s.slice(20, 32)}`;
+}
+// ---------------------------------------------------------------------------
+// The honesty layer. Everything below exists so no answer can overstate what
+// the scan established.
+// ---------------------------------------------------------------------------
+/** Did the scan produce a result, and is that result whole?
+ *
+ *  `PARTIALLY_COMPLETED` carries usable findings AND failed pages. Collapsing
+ *  it into "completed" is the single most damaging thing this module could do:
+ *  the caller reports a site as checked when part of it was never read. */
+function scanCompleteness(scan) {
+    const status = typeof scan?.status === "string" ? scan.status : "unknown";
+    const progress = (scan?.progress ?? {});
+    const failed = typeof progress.failedPageCount === "number"
+        ? progress.failedPageCount
+        : "unknown";
+    const pending = typeof progress.pendingPageCount === "number"
+        ? progress.pendingPageCount
+        : "unknown";
+    const terminal = TERMINAL.has(status);
+    if (status === "ACCESSIBILITY_SCAN_STATUS_FAILED") {
+        return {
+            status,
+            terminal,
+            resultIsWhole: false,
+            unscannedPages: "unknown",
+            caveat: "This scan produced NO usable result. Do not present the site as " +
+                "checked, and do not request findings. Read `failure`, fix the cause, " +
+                "and start a new scan with a new `attempt`.",
+        };
+    }
+    if (status === "ACCESSIBILITY_SCAN_STATUS_PARTIALLY_COMPLETED") {
+        return {
+            status,
+            terminal,
+            resultIsWhole: false,
+            unscannedPages: failed,
+            caveat: "PART OF THIS TARGET WAS NEVER CHECKED. The findings below are real, " +
+                "but one or more pages failed to scan. List the page summaries and " +
+                "report every failed page: a failed page with zero findings is " +
+                "UNKNOWN, not clean.",
+        };
+    }
+    if (status === "ACCESSIBILITY_SCAN_STATUS_COMPLETED") {
+        return { status, terminal, resultIsWhole: true, unscannedPages: failed };
+    }
+    // QUEUED / RUNNING / anything this version does not know.
+    // FAILED PAGES COUNT WHILE IT RUNS TOO. Reporting only the pending ones
+    // understated how much of the target was still unaccounted for — and this
+    // number is the one a caller uses to decide whether to keep waiting.
+    const stillUnknown = typeof pending === "number" && typeof failed === "number"
+        ? pending + failed
+        : "unknown";
+    return {
+        status,
+        terminal,
+        resultIsWhole: "unknown",
+        unscannedPages: stillUnknown,
+        caveat: "This scan has not finished. Its numbers are progress, not a result — " +
+            "do not report them as an audit. Poll `wix_a11y_get_scan` until the " +
+            "status is terminal.",
+    };
+}
+/** Is this page clear? THREE CONDITIONS, never one.
+ *
+ *  `findingCount === 0` alone is the trap: it is also what a page that failed
+ *  to scan reports, and what a page reports when the relevant checks never
+ *  ran. Both are `"unknown"`, and saying so is the whole job. */
+function pageVerdict(summary) {
+    const status = typeof summary.status === "string" ? summary.status : "unknown";
+    const count = typeof summary.findingCount === "number" ? summary.findingCount : undefined;
+    const coverage = (summary.coverage ?? {});
+    const rules = Array.isArray(coverage.checkedRuleIds)
+        ? coverage.checkedRuleIds.length
+        : 0;
+    if (status === "ACCESSIBILITY_PAGE_SCAN_STATUS_FAILED") {
+        return {
+            clear: "unknown",
+            why: "this page failed to scan — it has zero findings because nothing was checked, not because nothing is wrong",
+        };
+    }
+    if (status !== "ACCESSIBILITY_PAGE_SCAN_STATUS_COMPLETED") {
+        return {
+            clear: "unknown",
+            why: `this page reports a status this version does not recognise (${status})`,
+        };
+    }
+    if (count === undefined) {
+        return { clear: "unknown", why: "this page reported no finding count" };
+    }
+    if (count > 0)
+        return { clear: false, why: `${count} finding(s) on this page` };
+    const categories = Array.isArray(coverage.checkedCategories)
+        ? coverage.checkedCategories
+        : [];
+    if (rules === 0 || categories.length === 0) {
+        return {
+            clear: "unknown",
+            why: "no findings, but coverage lists no executed rule or category — nothing confirms any relevant check ran on this page",
+        };
+    }
+    // CLEAR IS NEVER UNQUALIFIED. Coverage says which checks ran, not that the
+    // right ones did: a page with no `image-alt` finding whose contrast was
+    // never evaluated is clear FOR WHAT RAN and unknown for the rest. The plugin
+    // cannot invent the set of checks a given page ought to have had — a page
+    // with no images legitimately runs no alt-text rule — so instead of guessing
+    // an expectation it states the scope of its own claim, and `clearFor` is
+    // returned alongside so the claim cannot be read wider than it is.
+    return {
+        clear: true,
+        clearFor: { categories, ruleCount: rules },
+        why: `no findings among the ${rules} rule(s) that ran, covering ` +
+            `${categories.join(", ")}. Checks that did not run are not evidence: ` +
+            "this page is clear FOR THOSE CHECKS, not in general.",
+    };
+}
+/** The documented application errors, and what each one means for the CALLER.
+ *
+ *  Taken from the published per-method error unions, not from what a request
+ *  happened to return once. Two reasons they are handled here rather than left
+ *  to throw: several of them carry a scan id the caller is supposed to POLL —
+ *  buried in a thrown message, the only move left is to start a duplicate — and
+ *  every one of them describes a state in which the site is NOT known to be
+ *  clean. A raw error reaches an agent as "something went wrong"; these reach
+ *  it as "here is what you do not know, and what to do next".
+ */
+const ERROR_GUIDANCE = {
+    INVALID_SCAN_TARGET: "Wix rejected the target itself. Re-read the collection id from `wix_a11y_list_page_collections`, or check the page URL belongs to this site.",
+    SCAN_ALREADY_IN_PROGRESS: "A scan is already running for this target. Poll `wix_a11y_get_scan` with the `scanId` below. Do NOT start another scan.",
+    IDEMPOTENCY_KEY_REUSED: "This `attempt` label was already used for a DIFFERENT request. Choose a new `attempt` for a genuinely new scan; reuse one only to retry the exact same request.",
+    SCAN_TARGET_NOT_AVAILABLE: "The page or collection is not available on this site right now. Refresh `wix_a11y_list_page_collections` or confirm the page still exists.",
+    SCAN_SIZE_LIMIT_EXCEEDED: "This target is too large to scan in one run. NEVER report the site as fully scanned after this. Narrow the target — prefer page collections — and say which parts were left out.",
+    SCAN_STATE_UNKNOWN: "The scan's state could not be established. Read `wix_a11y_get_scan` with the `scanId` below until it is known. Do NOT start a replacement scan.",
+    ACCESSIBILITY_SCAN_NOT_FOUND: "No scan with that id. It may have expired — stored results are kept about six months. Start a new scan with a new `attempt`.",
+    SCAN_NOT_COMPLETE: "This scan has not reached a terminal state, so it has no results to read yet. Poll `wix_a11y_get_scan` first. Its progress numbers are NOT an audit.",
+    SCAN_RESULTS_NOT_AVAILABLE: "This scan is terminal but stored no readable results. Nothing here says the site is clean — start a new scan with a new `attempt`.",
+    SCAN_RESULTS_EXPIRED: "This scan's stored results have passed their retention. They cannot be read, and their absence is not a clean result. Start a new scan with a new `attempt`.",
+    RATE_LIMITED: "Run requests are limited to 5 per minute per site. Wait, then retry with the SAME `attempt` so the retry cannot create a second scan.",
+};
+/** Map a failed request onto the documented surface, or give up honestly.
+ *
+ *  `undefined` means this version does not recognise the error — the caller
+ *  rethrows, because inventing a reassuring explanation for an unknown failure
+ *  is worse than surfacing the raw one. */
+function explainError(err) {
+    if (!(err instanceof WixApiError))
+        return undefined;
+    const body = err.bodyPreview;
+    // THE FIELD THE CONTRACT DEFINES, not the first GUID in the body. An error
+    // body can carry a request id or an echoed idempotency key ahead of the scan
+    // id, and pointing the caller at one of those sends it to poll a scan that
+    // does not exist — on the very path whose whole purpose is "poll the
+    // existing one instead of starting another".
+    // THE ENVELOPE WIX ACTUALLY SENDS:
+    //   { message, details: { applicationError: { code, description, data } } }
+    // Reading `details` itself found the wrapper, so the code was still matched
+    // by text search while `accessibilityScanId` stayed undefined — the caller
+    // got "poll the existing scan" and nothing to poll it with.
+    let details = {};
+    let structuredCode;
+    try {
+        const parsed = JSON.parse(body);
+        const appError = parsed.details?.applicationError;
+        if (typeof appError?.code === "string")
+            structuredCode = appError.code;
+        const holder = appError?.data ??
+            parsed.data;
+        if (holder !== null && typeof holder === "object" && !Array.isArray(holder)) {
+            details = holder;
+        }
+    }
+    catch {
+        // A body this version cannot parse yields no id — which the guidance for
+        // those codes already covers, rather than a guessed one.
+    }
+    const rawId = details.accessibilityScanId;
+    const scanId = typeof rawId === "string" && rawId !== "" ? rawId : undefined;
+    const num = (v) => typeof v === "number" && Number.isFinite(v) ? v : undefined;
+    const sizes = {
+        detectedPageCount: num(details.detectedPageCount),
+        maxPageCount: num(details.maxPageCount),
+    };
+    // THE DECLARED CODE FIRST. A text search over the whole body also matches a
+    // code name quoted inside a human-readable description, which is how a
+    // "not found" message mentioning another state gets classified as it.
+    if (structuredCode !== undefined && ERROR_GUIDANCE[structuredCode] !== undefined) {
+        return {
+            code: structuredCode,
+            scanId,
+            ...sizes,
+            guidance: ERROR_GUIDANCE[structuredCode],
+        };
+    }
+    // A STRUCTURED CODE THIS VERSION DOES NOT KNOW ENDS THE CLASSIFICATION.
+    // Falling through to the text search let a NEW error whose description
+    // happens to name a known one be answered as that one — a genuine failure
+    // returned as `ok`, with recovery steps for a different problem. The status
+    // branches below still apply: they read the transport, not the body.
+    if (structuredCode === undefined) {
+        for (const code of Object.keys(ERROR_GUIDANCE)) {
+            if (code !== "RATE_LIMITED" && body.includes(code)) {
+                return { code, scanId, ...sizes, guidance: ERROR_GUIDANCE[code] };
+            }
+        }
+    }
+    if (err.status === 429) {
+        return { code: "RATE_LIMITED", guidance: ERROR_GUIDANCE.RATE_LIMITED };
+    }
+    if (err.status === 403 || body.includes("PERMISSION_DENIED")) {
+        return {
+            code: "PERMISSION_DENIED",
+            guidance: "This Wix identity cannot perform this call — starting a scan needs the `Manage Accessibility Scans` permission, which reading collections or stored results does not imply. Stop here: do NOT retry with another URL, target or site, and never present this as a site with no issues.",
+        };
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+const TargetParams = {
+    siteId: SiteIdParam,
+    fullSite: Type.Optional(Type.Boolean({
+        description: "Scan every supported page and the site-level rules.",
+    })),
+    pageId: Type.Optional(Type.String({ description: "Wix page ID of a single page to scan." })),
+    pageUrl: Type.Optional(Type.String({
+        description: "Absolute URL of a single page to scan. Prefer this for a generated page such as one product or one blog post.",
+    })),
+    collectionId: Type.Optional(Type.String({
+        description: "Collection ID from `wix_a11y_list_page_collections`, passed back UNCHANGED. Never invent one.",
+    })),
+};
+export function buildAccessibilityTools(client) {
+    return [
+        defineWixTool({
+            name: "wix_a11y_list_page_collections",
+            description: "The page collections this site currently supports — store products, " +
+                "blog posts, booking services and so on, depending on which Wix apps " +
+                "are installed. Call this BEFORE scanning a collection and pass the " +
+                "returned `collectionId` back unchanged: the list is a property of " +
+                "the site, not a fixed vocabulary, so a hardcoded or invented id is " +
+                "wrong by construction. Read-only. " +
+                "NOTE: being able to read this list does NOT prove the key may start " +
+                "a scan — starting one needs its own Wix permission.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                cursor: Type.Optional(Type.String()),
+                limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+            }),
+            run: async (params, c, signal) => c.request("GET", `${SCANS}/page-collections`, {
+                siteId: params.siteId,
+                signal,
+                query: compactQuery({
+                    "paging.limit": params.limit,
+                    "paging.cursor": params.cursor,
+                }),
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_a11y_run_scan",
+            description: "START an accessibility scan of exactly ONE target: the whole site " +
+                "(`fullSite: true`), one page (`pageId` or `pageUrl`), or one page " +
+                "collection (`collectionId`). Returns a scan id IMMEDIATELY — the " +
+                "scan runs asynchronously and this tool does NOT wait for it. Poll " +
+                "`wix_a11y_get_scan` after `suggestedPollIntervalSeconds` (or every " +
+                "5 seconds when it is absent) until the status is terminal. " +
+                "`attempt` NAMES THIS SCAN: the same `attempt` for the same target " +
+                "is a RETRY and can never create a second scan, so reuse it when a " +
+                "call fails or times out. Use a NEW `attempt` for a genuinely new " +
+                "scan — verifying a fix is a new scan, not a retry. " +
+                "Runs are limited to 5 per minute per site, and a multi-page scan " +
+                "covers at most 300 pages. Requires the Wix `Manage Accessibility " +
+                "Scans` permission; reading results does not imply it. " +
+                "This starts work on the live site but changes nothing on it.",
+            parameters: Type.Object({
+                ...TargetParams,
+                attempt: Type.String({
+                    minLength: 1,
+                    description: "Short label naming this intended scan, e.g. `baseline-2026-08` or `after-alt-text-fix`. Same label = retry, new label = new scan.",
+                }),
+            }),
+            run: async (params, c, signal) => {
+                const { target, key, label } = buildTarget(params);
+                // THE EFFECTIVE SITE, NOT THE PARAMETER. A first call that omits
+                // `siteId` and a retry that spells out the same default site are the
+                // SAME intended scan; deriving from the literal argument gave them
+                // two keys and let the retry start a duplicate.
+                const site = params.siteId ?? c.defaultSiteId;
+                try {
+                    const resp = (await c.request("POST", `${SCANS}/run`, {
+                        siteId: params.siteId,
+                        signal,
+                        body: {
+                            target,
+                            idempotencyKey: idempotencyKey(site, key, params.attempt),
+                        },
+                    }));
+                    const scan = (resp?.accessibilityScan ?? undefined);
+                    return {
+                        scanId: scanIdOf(scan),
+                        target: label,
+                        ...scanCompleteness(scan),
+                        // WHAT THE CAVEAT ASKS FOR, IN THE SAME RESPONSE. An idempotent
+                        // retry can land on a scan that already failed; telling the
+                        // caller to read `failure` while dropping it left it with an
+                        // instruction it could not follow.
+                        ...(scan?.failure !== undefined ? { failure: scan.failure } : {}),
+                        suggestedPollIntervalSeconds: resp?.suggestedPollIntervalSeconds,
+                        // AN IDEMPOTENT RETRY CAN RETURN A SCAN THAT IS ALREADY DONE.
+                        // Saying so stops the caller from waiting on a finished scan.
+                        howToProceed: scan?.status === "ACCESSIBILITY_SCAN_STATUS_FAILED"
+                            ? // A TERMINAL SCAN IS NOT A READABLE ONE. An idempotent
+                                // retry can hand back a scan that already failed, and
+                                // sending the caller to read its results contradicts the
+                                // caveat in the same response.
+                                "This scan already FAILED and has no usable result. Read `failure`, fix the cause, then run again with a NEW `attempt`."
+                            : TERMINAL.has(typeof scan?.status === "string" ? scan.status : "")
+                                ? "This scan is already terminal — read its results now."
+                                : "Poll `wix_a11y_get_scan` with the `scanId` above.",
+                    };
+                }
+                catch (err) {
+                    const known = explainError(err);
+                    if (known === undefined)
+                        throw err;
+                    return { refused: known.code, ...known, target: label };
+                }
+            },
+        }, client),
+        defineWixTool({
+            name: "wix_a11y_get_scan",
+            description: "Lifecycle, progress and AGGREGATE TOTALS for one scan. This is the " +
+                "poll target: keep calling it while the status is QUEUED or RUNNING. " +
+                "It does NOT return pages or findings — read `wix_a11y_list_page_summaries` " +
+                "and `wix_a11y_list_findings` for those. " +
+                "`resultIsWhole` is the field that matters: `false` means part of " +
+                "the target was never checked, and no report may call the site " +
+                "checked in that case. Read-only.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                scanId: Type.String({ minLength: 1 }),
+            }),
+            run: async (params, c, signal) => {
+                let resp = null;
+                try {
+                    resp = (await c.request("GET", `${SCANS}/${encodeURIComponent(params.scanId)}`, { siteId: params.siteId, signal }));
+                }
+                catch (err) {
+                    // THE POLL TARGET, of all places. `SCAN_STATE_UNKNOWN` here means
+                    // "keep reading this scan, do not start another" — as a raw error
+                    // it read as "this scan is gone", and the next move is a duplicate.
+                    const known = explainError(err);
+                    if (known === undefined)
+                        throw err;
+                    return { refused: known.code, ...known };
+                }
+                const scan = (resp?.accessibilityScan ?? undefined);
+                return {
+                    ...scanCompleteness(scan),
+                    scan,
+                    suggestedPollIntervalSeconds: resp?.suggestedPollIntervalSeconds,
+                };
+            },
+        }, client),
+        defineWixTool({
+            name: "wix_a11y_get_latest_scan",
+            description: "The most recently STORED scan for one target, WITHOUT starting a " +
+                "new one. Use it before running a scan when a recent result may " +
+                "already answer the question — and check `resultsExpirationDate` " +
+                "before reusing it: stored results are kept about six months, and a " +
+                "result from before the last site change describes the old site. " +
+                "Takes the same one-of-three target as `wix_a11y_run_scan`. Read-only.",
+            parameters: Type.Object(TargetParams),
+            run: async (params, c, signal) => {
+                const { target, label } = buildTarget(params);
+                let resp = null;
+                try {
+                    resp = (await c.request("GET", `${SCANS}/latest`, {
+                        siteId: params.siteId,
+                        signal,
+                        query: compactQuery(targetQuery(target)),
+                    }));
+                }
+                catch (err) {
+                    const known = explainError(err);
+                    // "NO STORED SCAN" IS AN ANSWER, NOT A FAILURE. Wix says so with
+                    // an application error, so the documented first-use path — ask for
+                    // the latest, find none, start one — arrived as a raw API error
+                    // and never reached the branch written for it.
+                    if (known?.code === "ACCESSIBILITY_SCAN_NOT_FOUND") {
+                        return {
+                            target: label,
+                            storedScan: false,
+                            howToProceed: "No stored scan for this target. Start one with `wix_a11y_run_scan`.",
+                        };
+                    }
+                    if (known === undefined)
+                        throw err;
+                    return { refused: known.code, ...known, target: label };
+                }
+                const scan = (resp?.accessibilityScan ?? undefined);
+                if (scan === undefined) {
+                    return {
+                        target: label,
+                        storedScan: false,
+                        howToProceed: "No stored scan for this target. Start one with `wix_a11y_run_scan`.",
+                    };
+                }
+                return {
+                    target: label,
+                    storedScan: true,
+                    ...scanCompleteness(scan),
+                    completedDate: scan.completedDate,
+                    resultsExpirationDate: scan.resultsExpirationDate,
+                    scan,
+                };
+            },
+        }, client),
+        defineWixTool({
+            name: "wix_a11y_list_page_summaries",
+            description: "EVERY page the scan discovered — the clear ones and the ones that " +
+                "failed to scan, not only the ones with findings. Each page carries " +
+                "`clear`, which is `true`, `false` or `\"unknown\"`, never a bare " +
+                "count: a page is clear ONLY when it completed, has no findings, AND " +
+                "its coverage confirms the checks actually ran. A page that failed " +
+                "reports zero findings because nothing was read — that is `\"unknown\"`, " +
+                "and reporting it as clean is the mistake this tool exists to " +
+                "prevent. Page through the cursor to the end. Read-only.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                scanId: Type.String({ minLength: 1 }),
+                cursor: Type.Optional(Type.String()),
+                limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+            }),
+            run: async (params, c, signal) => {
+                let resp = null;
+                try {
+                    resp = (await c.request("GET", `${SCANS}/${encodeURIComponent(params.scanId)}/page-summaries`, {
+                        siteId: params.siteId,
+                        signal,
+                        query: compactQuery({
+                            "paging.limit": params.limit,
+                            "paging.cursor": params.cursor,
+                        }),
+                    }));
+                }
+                catch (err) {
+                    const known = explainError(err);
+                    if (known === undefined)
+                        throw err;
+                    return { refused: known.code, ...known };
+                }
+                const raw = Array.isArray(resp?.pageSummaries)
+                    ? resp.pageSummaries
+                    : [];
+                // FLAT, because that is what the description and the README promise.
+                // Nesting it under `verdict` meant an agent following the stated
+                // contract looked for `clear` and found nothing — and a page whose
+                // state is unknown is exactly the one it would then miss.
+                const pages = raw.map((s) => ({ ...s, ...pageVerdict(s) }));
+                const unknown = pages.filter((p) => p.clear === "unknown");
+                return {
+                    pages,
+                    pagingMetadata: resp?.pagingMetadata,
+                    // COUNTED, NOT LEFT TO THE READER. A caller that skims the list
+                    // and reports "no findings" is the failure mode; a number it has
+                    // to mention is harder to skim past.
+                    pagesWhoseStateIsUnknown: unknown.length,
+                    ...(unknown.length > 0
+                        ? {
+                            caveat: `${unknown.length} of the ${pages.length} page(s) on this ` +
+                                "cursor page could not be established as clear. Name them " +
+                                "in the report; do not fold them into a clean total.",
+                        }
+                        : {}),
+                };
+            },
+        }, client),
+        defineWixTool({
+            name: "wix_a11y_list_findings",
+            description: "The actionable findings of a completed or partially completed scan, " +
+                "with severity, WCAG criteria, the affected page and element, and " +
+                "ordered remediation and verification steps. Filter by page, rule, " +
+                "severity or category instead of issuing one request per page. " +
+                "A FINDING THAT IS ABSENT IS NOT A RULE THAT PASSED — only the " +
+                "scan's `coverage` says which checks ran. When a finding carries " +
+                "`humanInputRequired`, ask the user for the content or design " +
+                "decision instead of guessing it. This tool reports; it never edits " +
+                "the site. Page through the cursor to the end. Read-only.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                scanId: Type.String({ minLength: 1 }),
+                pageId: Type.Optional(Type.String()),
+                pageUrl: Type.Optional(Type.String()),
+                ruleId: Type.Optional(Type.String()),
+                severity: Type.Optional(Type.String({
+                    description: "One of ACCESSIBILITY_SEVERITY_CRITICAL, _SERIOUS, _MODERATE, _MINOR, _INFO.",
+                })),
+                categories: Type.Optional(Type.Array(Type.String(), {
+                    description: "ACCESSIBILITY_FINDING_CATEGORY_ALTERNATIVE_TEXT, _HEADING_STRUCTURE, _COLOR_CONTRAST, _SCREEN_READER, _KEYBOARD, _OTHER. Combined with OR.",
+                })),
+                cursor: Type.Optional(Type.String()),
+                limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+            }),
+            run: async (params, c, signal) => {
+                // THE SAME ONE-OF AS A SCAN TARGET. A caller copying both identifiers
+                // off a page summary sent both, and Wix failed the WHOLE findings
+                // request — which reads like a page with nothing on it.
+                if (params.pageId !== undefined &&
+                    params.pageId !== "" &&
+                    params.pageUrl !== undefined &&
+                    params.pageUrl !== "") {
+                    throw new Error("Refusing to filter: `pageId` and `pageUrl` both given. The page " +
+                        "filter takes exactly one identifier — pass whichever the page " +
+                        "summary gave you, not both.");
+                }
+                const cats = params.categories ?? [];
+                const query = {
+                    "paging.limit": params.limit,
+                    "paging.cursor": params.cursor,
+                    "filter.ruleId": params.ruleId,
+                    "filter.severity": params.severity,
+                    "filter.page.pageId": params.pageId,
+                    "filter.page.pageUrl": params.pageUrl,
+                    // REPEATED, NOT INDEXED. `filter.categories.0` is a different
+                    // parameter from `filter.categories`, and a filter Wix ignores
+                    // returns UNFILTERED findings that this tool then labels filtered.
+                    ...(cats.length > 0 ? { "filter.categories": cats } : {}),
+                };
+                let resp = null;
+                try {
+                    resp = (await c.request("GET", `${SCANS}/${encodeURIComponent(params.scanId)}/findings`, { siteId: params.siteId, signal, query: compactQuery(query) }));
+                }
+                catch (err) {
+                    const known = explainError(err);
+                    if (known === undefined)
+                        throw err;
+                    return { refused: known.code, ...known };
+                }
+                const findings = Array.isArray(resp?.findings)
+                    ? resp.findings
+                    : [];
+                // UNDER `fixGuidance`, NOT AT THE ROOT. Read from the root, this
+                // counter was structurally always zero — the one signal that tells
+                // an agent to STOP and ask a person, silently absent.
+                const needsHuman = findings.filter((f) => f.fixGuidance
+                    ?.humanInputRequired === true).length;
+                // WHAT WAS ACTUALLY SENT. `compactQuery` drops empty strings, so a
+                // `severity: ""` produced an UNFILTERED request that this answer then
+                // described as filtered — and an empty result read as "none in that
+                // subset" instead of "none at all".
+                const isSet = (v) => v !== undefined && v !== "";
+                const filtered = isSet(params.ruleId) ||
+                    isSet(params.severity) ||
+                    isSet(params.pageId) ||
+                    isSet(params.pageUrl) ||
+                    cats.length > 0;
+                return {
+                    findings,
+                    pagingMetadata: resp?.pagingMetadata,
+                    findingsNeedingAHumanDecision: needsHuman,
+                    // A FILTERED EMPTY LIST IS NOT A CLEAN SITE, and neither is an
+                    // unfiltered one on its own.
+                    caveat: filtered
+                        ? "This list is FILTERED. An empty or short result says nothing about the rest of the scan."
+                        : "An absent finding is not a rule that passed — check the scan's `coverage` before calling anything clear.",
+                };
+            },
+        }, client),
+    ];
+}
+//# sourceMappingURL=accessibility.js.map