npm - @lacneu/wix-openclaw - Versions diffs - 0.2.2 → 0.4.0 - Mend

@lacneu/wix-openclaw 0.2.2 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

package/CHANGELOG.md +510 -1
package/README.md +109 -8
package/dist/config.d.ts +1 -0
package/dist/config.js +25 -1
package/dist/config.js.map +1 -1
package/dist/hooks/approval.d.ts +10 -0
package/dist/hooks/approval.js +301 -18
package/dist/hooks/approval.js.map +1 -1
package/dist/index.d.ts +1586 -8
package/dist/index.js +63 -19
package/dist/index.js.map +1 -1
package/dist/tools/_factory.d.ts +26 -2
package/dist/tools/_factory.js.map +1 -1
package/dist/tools/blog.d.ts +11 -11
package/dist/tools/bookings.d.ts +5 -5
package/dist/tools/contacts.d.ts +5 -5
package/dist/tools/data.d.ts +5 -5
package/dist/tools/design.d.ts +1 -1
package/dist/tools/events.d.ts +3 -3
package/dist/tools/faq.d.ts +5 -5
package/dist/tools/forms.d.ts +2 -2
package/dist/tools/media.d.ts +2 -2
package/dist/tools/multilingual.d.ts +2 -2
package/dist/tools/reviews.d.ts +3 -3
package/dist/tools/seo.d.ts +438 -0
package/dist/tools/seo.js +1875 -0
package/dist/tools/seo.js.map +1 -0
package/dist/tools/site.d.ts +2 -2
package/dist/types.d.ts +11 -0
package/dist/wix-client.js +30 -4
package/dist/wix-client.js.map +1 -1
package/openclaw.plugin.json +57 -6
package/package.json +1 -1

package/dist/tools/seo.js ADDED Viewed

@@ -0,0 +1,1875 @@
+// Wix SEO tools — auditing a site's SEO, and managing its URL redirects.
+//
+// DEVELOPER PREVIEW, AND OPT-IN. Every endpoint used here is listed in Wix's
+// Developer Preview: Wix may change them at any time and says they "shouldn't
+// be used on live sites". `buildAllTools` registers them only when
+// `config.enableSeoTools` is true, because four of them also write
+// irreversibly to a live site — the two risks compound, and neither should be
+// taken on someone's behalf by a default.
+//
+// Two APIs, two base paths:
+//   - Item/Site SEO tags: `/promote/seo/v1/...`
+//   - Redirects:          `/seo-redirects-service/v1/...`
+//
+// Both sit behind ONE Wix permission, `SCOPE.PROMOTE.MANAGE-SEO`. Wix has no
+// read-only SEO scope, so a key that can audit can also destroy redirects: the
+// read/write boundary is this plugin's (`enableSeoTools` + approvals), not Wix's.
+//
+// `wix_seo_list_item_tags` is the entry point for an audit: it enumerates the
+// items of one type — `STATIC_PAGE` gives the site's pages — each with the tags
+// it sets itself, whether it sets any at all, and the tags it is expected to
+// render with, marked with where each came from.
+//
+// TWO LIMITS THE MODEL MUST KNOW, so they live in the tool descriptions rather
+// than only here:
+//
+//   1. For `STATIC_PAGE`, every read reflects the SAVED revision, never the
+//      published one, and `publishStatus` is always `PUBLISH_STATUS_UNSPECIFIED`.
+//      An audit that doesn't say so reports on a draft as if it were the live
+//      page.
+//   2. `resolvedTags` is derived from the sources Wix manages. Tags that site
+//      code, apps or page components add at render time aren't in it, so it is
+//      not a copy of the page's rendered `<head>`.
+//
+// Verified against:
+//   - https://dev.wix.com/docs/api-reference/business-management/seo/item-seo-tags-v1/list-item-seo-tags.md
+//   - https://dev.wix.com/docs/api-reference/business-management/seo/item-seo-tags-v1/get-item-seo-tags.md
+//   - https://dev.wix.com/docs/api-reference/business-management/seo/site-seo-tags-v1/get-site-seo-tags.md
+//   - https://dev.wix.com/docs/api-reference/business-management/seo/redirects/skills/manage-url-redirects-on-a-wix-site.md
+import { createHmac, randomBytes } from "node:crypto";
+import { Type } from "@sinclair/typebox";
+import { defineWixTool } from "./_factory.js";
+import { compactQuery, } from "./_query.js";
+const SiteIdParam = Type.Optional(Type.String());
+/** Minted once per process. See `redirectToken`. */
+const TOKEN_SECRET = randomBytes(32);
+/** Stop before doing anything irreversible for a caller who has given up. */
+function throwIfAborted(signal) {
+    if (signal?.aborted === true) {
+        throw new Error("Aborted before the write: nothing was sent to Wix.");
+    }
+}
+/** Base path of the SEO redirects service. Its routes are NOT REST-conventional
+ *  — creation is `POST /create-redirect`, and the bulk routes are verbs too —
+ *  so every path here comes from the reference, never from a convention. */
+const REDIRECTS = "/seo-redirects-service/v1";
+/** A single SEO tag, in Wix's shape. Left permissive on purpose: which `type`
+ *  values an endpoint accepts differs per endpoint, and the API rejects the
+ *  wrong ones with a named error that reaches the model intact. */
+const SeoTagSchema = Type.Object({
+    type: Type.String({
+        description: "Tag type: `title`, `meta`, `script` or `link`.",
+    }),
+    props: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {
+        description: 'Tag properties, e.g. `{"name": "description", "content": "…"}`.',
+    })),
+    children: Type.Optional(Type.String({ description: "Inner content, e.g. the text of a <title>." })),
+    meta: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {
+        description: 'Tag metadata, e.g. `{"height": 300, "width": 240}`.',
+    })),
+    custom: Type.Optional(Type.Boolean()),
+    disabled: Type.Optional(Type.Boolean()),
+});
+/** One redirect, as Create and Bulk Create accept it. */
+const RedirectSchema = Type.Object({
+    from: Type.String({
+        description: "Path the redirect starts from, URL-encoded, e.g. `/old-page`. Cannot " +
+            "be the site root. Two paths differing only by a trailing slash count " +
+            "as the same path.",
+    }),
+    to: Type.String({
+        description: "Where it sends the visitor: a path such as `/new-page`, or a full URL.",
+    }),
+    options: Type.Optional(Type.Object({
+        groupRedirect: Type.Optional(Type.Boolean({
+            description: "true = match everything UNDER `from` and carry the rest of the " +
+                "URL over. false/omitted = exact path only. A group and an exact " +
+                "redirect sharing a `from` path are two different redirects.",
+        })),
+    })),
+    language: Type.Optional(Type.String({
+        description: "Language version this applies to (`fr`, `en-US`). Omit to apply to " +
+            "every language. A language-scoped path is stored WITHOUT its " +
+            "language prefix.",
+    })),
+    id: Type.Optional(Type.String({
+        description: "Redirect GUID. Supply one only to preserve an existing redirect's " +
+            "identity while re-creating it; omit for a new redirect.",
+    })),
+});
+/** Wix stores a language-scoped redirect WITHOUT its language prefix: a `fr`
+ *  redirect from `/fr/about` comes back as `/about`. A candidate written with
+ *  the prefix would be compared against a stored path that never has one, and
+ *  the conflict this check exists to find would be invisible. */
+function stripLanguagePrefix(path, language) {
+    if (language === undefined || language.length === 0)
+        return path;
+    // `fr` and `fr-CA` both prefix as `/fr/`.
+    const code = language.split("-")[0].toLowerCase();
+    const lower = path.toLowerCase();
+    if (lower === `/${code}`)
+        return "/";
+    return lower.startsWith(`/${code}/`) ? path.slice(code.length + 1) : path;
+}
+/** Wix treats two paths differing only by a trailing slash as the same path,
+ *  and matches case-insensitively on the stored path. Comparing raw strings
+ *  would miss exactly the conflicts this check exists to find. */
+function samePath(a, b) {
+    if (a === undefined || b === undefined)
+        return false;
+    const norm = (p) => p.replace(/\/+$/, "").toLowerCase();
+    return norm(a) === norm(b);
+}
+/** Whether two redirects can collide at all.
+ *
+ *  A redirect with no `language` applies to every language; one scoped to a
+ *  language conflicts only with the same language and with the global ones. */
+function scopesOverlap(a, b) {
+    if (a === undefined || a === "" || b === undefined || b === "")
+        return true;
+    return a.toLowerCase() === b.toLowerCase();
+}
+/**
+ * The redirects a create would DESTROY, found before it is sent.
+ *
+ * Two ways a create removes something, and neither is obvious from the call:
+ *   - LOOP RESOLUTION: an existing redirect that STARTS AT the path this one
+ *     points to is deleted so the create can proceed. No flag asks for it, and
+ *     the API does not report it.
+ *   - FORCE REPLACE: with the flag, the redirect holding the same `from` path
+ *     is deleted. Without it, the create fails instead.
+ *
+ * Leaving this to the tool description made it advice: a direct call, a model
+ * that skipped it, or a change between the listing and the write would still
+ * lose a redirect nobody named. Run in the execution path, it cannot be
+ * skipped — and it reports WHICH redirect, which an approval prompt alone
+ * cannot say.
+ */
+/** A leading path segment shaped like a language tag: `/fr`, `/pt-br`. Used
+ *  only to widen what a create is said to endanger, never to narrow it. */
+const LANGUAGE_SEGMENT = /^\/[a-z]{2,3}(?:-[a-z0-9]{2,8})?(?=\/|$)/i;
+function deletionsCausedBy(existing, candidate, forceReplace) {
+    const found = [];
+    // Compare on what Wix STORES, not on what the caller wrote.
+    for (const one of existing) {
+        const sameScope = scopesOverlap(one.language, candidate.language);
+        // Compare on what Wix STORES — and the prefix to strip belongs to the
+        // EXISTING redirect as much as to the candidate. A GLOBAL create pointing
+        // at `/fr/blog` aims at the public path of a `fr` redirect that Wix returns
+        // as `/blog`: normalising only by the candidate's own language (none, here)
+        // left the two looking unrelated, and the deletion went through unannounced.
+        const candidateTo = stripLanguagePrefix(stripLanguagePrefix(candidate.to, candidate.language), one.language);
+        const candidateFrom = stripLanguagePrefix(stripLanguagePrefix(candidate.from, candidate.language), one.language);
+        // SCOPE-BLIND ON `groupRedirect`, DELIBERATELY. An exact and a group
+        // redirect sharing a `from` are "two different redirects" upstream, which
+        // invites the conclusion that a forceReplace aimed at one spares the other
+        // — so this announces a loss Wix might not take. But the rules upstream
+        // states for both checks are written on `from` equality alone, with no
+        // qualification by scope, and nothing says which of the two a create
+        // displaces. Announcing a superset costs one acknowledgement the operator
+        // can judge (`groupRedirect` is on every entry); announcing a subset means
+        // a permanent deletion nobody was shown. Narrow this only on a documented
+        // scope-aware rule or an observed live behaviour, not on the inference.
+        // ACROSS LANGUAGES, BUT ONLY WHEN THE CALLER SAID SO. Two languages live in
+        // different URL namespaces — a `fr` redirect answers at `/fr/blog`, a `de`
+        // one at `/de/blog` — so a create in one language pointing at its own
+        // `/blog` cannot loop with the other, and refusing there would block a
+        // create that destroys nothing. But a caller can write the OTHER language's
+        // prefix explicitly: an `en` redirect pointing at `/fr/blog` names exactly
+        // the public path of the `fr` redirect Wix stores as `/blog`. The scope
+        // filter alone never reached that comparison, so the deletion went
+        // unannounced. This adds that case and takes none away.
+        const acrossLanguages = !sameScope &&
+            one.language !== undefined &&
+            stripLanguagePrefix(candidate.to, one.language) !== candidate.to &&
+            samePath(one.from, stripLanguagePrefix(candidate.to, one.language));
+        // A GLOBAL REDIRECT ANSWERS UNDER EVERY LANGUAGE. Upstream: omitting
+        // `language` applies the redirect to every one of them, so a global rule
+        // stored as `/blog` also entered at `/de/blog`. `sameScope` is always true
+        // against a global rule, which meant the branch above could never look at a
+        // foreign prefix, and a create pointing at `/de/blog` closed a loop with it
+        // unannounced. The site's configured languages are not knowable here — the
+        // endpoint that lists them needs a different scope and can 403 — so this
+        // recognises a leading segment SHAPED like a language tag. It errs towards
+        // announcing: a `/fr/...` that is really a content folder costs one
+        // acknowledgement, and the operator sees the redirect it names.
+        const strippedGuess = candidate.to.replace(LANGUAGE_SEGMENT, "");
+        const globalAcrossLanguages = one.language === undefined &&
+            strippedGuess !== candidate.to &&
+            strippedGuess.length > 0 &&
+            samePath(one.from, strippedGuess);
+        if ((sameScope && samePath(one.from, candidateTo)) ||
+            acrossLanguages ||
+            globalAcrossLanguages)
+            found.push({ reason: "loop", redirect: one });
+        else if (sameScope && forceReplace && samePath(one.from, candidateFrom)) {
+            found.push({ reason: "force_replace", redirect: one });
+        }
+    }
+    return found;
+}
+/** A SECOND GAP, same reasoning: whether a create in one language pointing at
+ *  its own namespace can ever resolve a loop against another language's
+ *  redirect is not something upstream states, and the two models — compare the
+ *  stored paths, or compare the public ones — disagree. This compares public
+ *  paths, adding only the case where the caller wrote the other language's
+ *  prefix. Settling the rest needs a live create and delete. */
+/** A GAP THIS DOES NOT CLOSE, stated rather than hidden: if an existing GROUP
+ *  redirect from `/docs` also resolves a loop for a create pointing at
+ *  `/docs/page` — because a group redirect covers everything under its `from` —
+ *  no victim is reported. Upstream defines the loop rule as the existing `from`
+ *  EQUALLING the new `to`, never as covering it, and inventing the wider rule
+ *  would make every create landing anywhere under a group redirect demand an
+ *  acknowledgement. Settling it needs a create and a delete against a live site,
+ *  which this plugin will not do to answer a question. */
+/** Read every redirect on the site. Unpaged by contract — one call is the whole
+ *  list. */
+async function listExisting(client, siteId, signal) {
+    const resp = await client.request("GET", `${REDIRECTS}/redirects`, {
+        siteId,
+        signal,
+    });
+    // FAIL CLOSED. `resp?.redirects ?? []` read any unexpected 2xx — a body the
+    // client could not parse as JSON, a schema change, a proxy's own page — as
+    // "this site has no redirects", and the destructive write went out on the
+    // strength of it. The one answer a safety check must never invent is the
+    // reassuring one.
+    const redirects = resp !== null && typeof resp === "object"
+        ? resp.redirects
+        : undefined;
+    if (!Array.isArray(redirects)) {
+        throw new Error("Refusing to write: could not read the site's existing redirects, so " +
+            "the check for what this would delete could not run. List Redirects " +
+            "returned no `redirects` array.");
+    }
+    // AND EVERY ELEMENT. Validating only the envelope left the check open to a
+    // schema drift — these endpoints are in Developer Preview, so one is a
+    // stated possibility rather than a hypothetical: `[{ id, source }]` passes an
+    // array test, every `from` reads as undefined, no conflict is ever found, and
+    // the destructive write goes out.
+    //
+    // EVERY FIELD THE TOKEN BINDS, not just `from`. `redirectToken` hashes id,
+    // from, to, language and groupRedirect, substituting `""`/`false` for what is
+    // absent. Checking only `from` therefore left a drift that renames or drops
+    // `to` silently degrading the token into one that no longer changes when the
+    // destination does — and an acknowledgement is only a safeguard because it
+    // goes stale. The scope fields are checked for SHAPE: an unknown shape is a
+    // scope this version cannot reason about.
+    for (const one of redirects) {
+        const r = one;
+        const options = r.options;
+        const understood = one !== null &&
+            typeof one === "object" &&
+            typeof r.id === "string" &&
+            typeof r.from === "string" &&
+            typeof r.to === "string" &&
+            (r.language === undefined || typeof r.language === "string") &&
+            (r.options === undefined ||
+                // A PLAIN OBJECT CARRYING ONLY WHAT THIS VERSION READS. `options: []`
+                // is `typeof "object"` and passed; so did a drift that renamed the flag
+                // (`isGroupRedirect`), leaving the redirect described to the operator
+                // as exact and its token blind to the scope it really has — the two
+                // things the acknowledgement exists to bind.
+                (typeof r.options === "object" &&
+                    r.options !== null &&
+                    !Array.isArray(r.options) &&
+                    Object.keys(r.options).every((k) => k === "groupRedirect") &&
+                    (options?.groupRedirect === undefined ||
+                        typeof options.groupRedirect === "boolean")));
+        if (!understood) {
+            throw new Error("Refusing to write: the site's redirect list contains an entry this " +
+                "version does not understand (it must carry string `id`, `from` and " +
+                "`to`, an optional string `language`, and an optional `options` " +
+                "object whose `groupRedirect` is a boolean), so the check for what " +
+                "this would delete cannot be trusted.");
+        }
+    }
+    return redirects;
+}
+/**
+ * One destructive redirect write per site at a time.
+ *
+ * The check and the write are two requests. Two concurrent creates can each
+ * read a state in which the other's redirect does not exist yet, and the second
+ * to land then deletes the first's — a deletion neither caller was shown.
+ * Serialising per site removes the race this plugin creates itself.
+ *
+ * It does NOT make the window disappear: a change made in the Wix dashboard, or
+ * by another process, between the read and the write is still possible, and no
+ * Wix precondition exists to close it. That residual is stated in the tool
+ * descriptions rather than papered over.
+ */
+const siteWriteQueues = new Map();
+/** TEST ONLY: how many per-site write chains are still retained.
+ *
+ *  Retention is a COST, not a behaviour — no sequence of tool calls tells a map
+ *  that grows for ever apart from one that is emptied, so the guard needs a
+ *  window into the module rather than an assertion about output. */
+export function seoWriteQueueDepth() {
+    return siteWriteQueues.size;
+}
+/** `item-seo-tags` pages by CURSOR only. The shared GET envelope also offers
+ *  `offset`, so the schema accepted — and `buildGetPagingQuery` forwarded — a
+ *  call mixing the two, which the endpoint does not define. Advertising only
+ *  what it serves is cheaper than explaining the result of the mixture. */
+const SeoCursorPagingSchema = Type.Object({
+    limit: Type.Optional(Type.Number({ minimum: 1, maximum: 1000 })),
+    cursor: Type.Optional(Type.String()),
+});
+function serializedBySite(client, siteId, work) {
+    // THE EFFECTIVE SITE, resolved before queuing. Keying on the raw argument put
+    // an omitted `siteId` and an explicit one naming the same site in two
+    // different queues, so the two calls the lock exists to order ran side by
+    // side.
+    const key = siteId ?? client.defaultSiteId ?? "<default>";
+    const previous = siteWriteQueues.get(key) ?? Promise.resolve();
+    const next = previous.then(work, work);
+    // Keep the chain alive on failure.
+    const settled = next.then(() => undefined, () => undefined);
+    siteWriteQueues.set(key, settled);
+    // AND DROP IT once it is the last one — the comment claimed this before the
+    // code did it. The key is a caller-supplied site id, queued BEFORE the
+    // whitelist rejects it, so a long-lived gateway retained one settled promise
+    // per distinct string ever passed. Deleting only while we are still the tail
+    // is what keeps the ordering: if a later call has already chained onto us, it
+    // owns the entry and must keep it.
+    void settled.then(() => {
+        if (siteWriteQueues.get(key) === settled)
+            siteWriteQueues.delete(key);
+    });
+    return next;
+}
+/**
+ * A token identifying a redirect AS IT IS RIGHT NOW.
+ *
+ *  Acknowledging a bare GUID was two holes at once: a caller could name an ID
+ *  on the first call and never be shown what it destroys, and an ID stays valid
+ *  while the redirect behind it changes — Wix lets a create supply its own GUID,
+ *  so between the refusal and the retry the same ID can point somewhere else,
+ *  and the write would delete something the user never saw.
+ *
+ *  Deriving the token from the redirect's identifying fields makes it stale the
+ *  moment the redirect changes, and the per-process secret makes it impossible
+ *  to produce without having listed. The EFFECTIVE SITE is part of it because
+ *  two allowed sites can hold an identical redirect — Wix accepts caller-supplied
+ *  GUIDs — and a token earned on one would otherwise authorise deleting its twin
+ *  on the other, on a tenant whose state was never shown.
+ */
+function redirectToken(site, one) {
+    const canonical = JSON.stringify([
+        site,
+        one.id ?? "",
+        one.from ?? "",
+        one.to ?? "",
+        one.language ?? "",
+        one.options?.groupRedirect === true,
+    ]);
+    // HMAC with a secret minted once per process, so a token cannot be computed
+    // by a caller who never listed. A restart invalidates outstanding tokens,
+    // which fails in the safe direction: the call refuses again with a fresh one.
+    return `${one.id ?? "no-id"}:${createHmac("sha256", TOKEN_SECRET)
+        .update(canonical)
+        .digest("hex")
+        .slice(0, 16)}`;
+}
+/** What the caller must repeat back to proceed with a destructive create. */
+const AcknowledgeParam = Type.Optional(Type.Array(Type.String(), {
+    description: "The `token` values from a previous refusal, for the redirects you " +
+        "accept losing. The call is REFUSED, listing them, until every redirect " +
+        "it would delete is acknowledged. A token is tied to the redirect's " +
+        "CURRENT state: if it changed since the refusal, the token no longer " +
+        "matches and the call refuses again with the new one. Show the listed " +
+        "redirects to the user and get their answer before filling this in — the " +
+        "deletions are permanent.",
+}));
+/**
+ * A redirect stripped to the fields this plugin actually supports.
+ *
+ * TypeBox objects accept unknown properties, so `options.forceReplace` rode
+ * through a bulk create untouched — a flag whose whole effect is to delete the
+ * redirect holding the `from` path, while the preflight had been run with
+ * `forceReplace: false` and the approval prompt never showed it. A schema that
+ * merely fails to mention a field does not remove it, and `execute` can be
+ * called directly, so the stripping happens here rather than being assumed.
+ *
+ * `forceReplace` is supported ONLY as the single create's own top-level
+ * parameter, where the preflight accounts for it.
+ */
+function sanitizeRedirect(one) {
+    return {
+        from: one.from,
+        to: one.to,
+        ...(one.options?.groupRedirect === true
+            ? { options: { groupRedirect: true } }
+            : {}),
+        ...(one.language !== undefined ? { language: one.language } : {}),
+        ...(one.id !== undefined ? { id: one.id } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// TRANCHE 2 — writing tags. A DIFFERENT DESTRUCTIVENESS FROM THE REDIRECTS.
+//
+// A redirect delete destroys another row: it can be listed, named, hashed. A
+// tag write destroys THE PREVIOUS VALUE OF WHAT IT WRITES — `tags` replaces the
+// item's set in full. So a caller that sets a title wipes the description that
+// was there, gets exactly what it asked for, and loses something it never
+// mentioned. That is this half's "redirects do not chain".
+//
+// The pre-flight therefore reports what DISAPPEARS — the tags the item holds
+// now whose slot the new set does not fill — never an echo of what is being
+// sent. A caller reading back its own input learns nothing.
+// ---------------------------------------------------------------------------
+/** What a tag occupies, as a human-readable slot: two tags with the same label
+ *  are the same fact about the page, so one replaces the other. */
+function tagLabel(tag) {
+    const type = typeof tag.type === "string" ? tag.type : "?";
+    const props = (tag.props ?? {});
+    // EVERY DISCRIMINATOR, not the first one found. Stopping at `rel` collapsed
+    // every `link rel="alternate"` onto one slot, and `script` had no
+    // discriminator at all: a page carrying three JSON-LD blocks or four
+    // hreflang alternates would have read as "all kept" when a single tag was
+    // sent, and the other two or three would have gone unannounced.
+    const parts = ["name", "property", "rel", "httpEquiv", "hreflang", "type", "href"]
+        .map((k) => [k, props[k]])
+        .filter(([, v]) => typeof v === "string" && v.length > 0)
+        .map(([k, v]) => `${k}=${String(v)}`);
+    // A `script` is identified by what it carries: two JSON-LD blocks share every
+    // property. Hashing the body means EDITING one reads as a loss plus an
+    // addition — over-announcing, which is the safe direction here.
+    if (type === "script" && typeof tag.children === "string") {
+        parts.push(`body=${createHmac("sha256", TOKEN_SECRET).update(tag.children).digest("hex").slice(0, 8)}`);
+    }
+    // A DISCRIMINATOR THIS VERSION DOES NOT LIST STILL IDENTIFIES A TAG.
+    // `meta charset=…`, `meta itemprop=…` and whatever Wix adds next matched
+    // none of the keys above, so every one of them collapsed onto the bare
+    // `meta` slot — a SINGULAR slot, which reads as an edit, so proposing one
+    // replaced another without announcing the loss. A digest of the props that
+    // are not the tag's payload keeps them apart. Editing such a tag then reads
+    // as a loss plus an addition: over-announcing, the safe direction here.
+    if (parts.length === 0) {
+        const identity = Object.entries(props)
+            .filter(([k, v]) => k !== "content" && typeof v === "string" && v.length > 0)
+            .map(([k, v]) => `${k}=${String(v)}`)
+            .sort();
+        if (identity.length > 0) {
+            parts.push(`props=${createHmac("sha256", TOKEN_SECRET)
+                .update(identity.join("\u0000"))
+                .digest("hex")
+                .slice(0, 8)}`);
+        }
+    }
+    // A TAG WITH NO DISCRIMINATOR AT ALL is told apart by what it carries, or
+    // not at all. A `meta` holding only `content` matched nothing above and fell
+    // back onto the bare `meta` slot, where one silently replaced another.
+    // `title` is the one type that is singular BY NATURE, so it keeps its bare
+    // slot and an edit of it still reads as an edit.
+    if (parts.length === 0 && type !== "title" && typeof props.content === "string") {
+        parts.push(`content=${createHmac("sha256", TOKEN_SECRET)
+            .update(props.content)
+            .digest("hex")
+            .slice(0, 8)}`);
+    }
+    return parts.length > 0 ? `${type}[${parts.join(",")}]` : type;
+}
+/** A slot plus the value it carries, bounded.
+ *
+ *  A LABEL ALONE CANNOT BE DECIDED ON. Editing a `title` in place keeps its
+ *  slot, so `wouldLose` is empty and the before/after read identically —
+ *  `title` and `title`. On a PATTERN, that is an operator handing over a token
+ *  for a rewrite of every page of a type without ever seeing the old template
+ *  or the new one. The value is what makes the two tell apart. */
+function tagPreview(tag) {
+    const t = (tag ?? {});
+    const props = (t.props ?? {});
+    const raw = typeof t.children === "string"
+        ? t.children
+        : typeof props.content === "string"
+            ? props.content
+            : typeof props.href === "string"
+                ? props.href
+                : undefined;
+    // BOUNDED: a JSON-LD block or a long description would otherwise push the
+    // rest of the refusal — the part that says what disappears — out of view.
+    const value = raw === undefined ? undefined : raw.length > 200 ? `${raw.slice(0, 200)}…` : raw;
+    return {
+        slot: tagLabel(t),
+        ...(value !== undefined ? { value } : {}),
+    };
+}
+/** Rebuild a tag from the fields Wix defines, dropping everything else.
+ *
+ *  TypeBox passes undeclared properties through and `execute` is callable
+ *  directly, so a schema that omits a field does not remove it. `language` in
+ *  particular must be actively dropped: tags can only be written for the item's
+ *  primary language, and sending one fails with `LANGUAGE_NOT_SUPPORTED` even
+ *  when the field mask does not name it. */
+function sanitizeTag(raw, allowedTypes) {
+    const t = (raw ?? {});
+    const type = typeof t.type === "string" ? t.type : "";
+    if (!allowedTypes.includes(type)) {
+        throw new Error(`Refusing to write: tag type ${JSON.stringify(type)} is not accepted here. ` +
+            `This endpoint accepts ${allowedTypes.map((x) => `\`${x}\``).join(", ")}. ` +
+            "Wix reuses one tag shape across APIs but each accepts only some types.");
+    }
+    // `custom: true` routes the write through the site's Advanced/Custom Tags
+    // list, which refuses `title` and `script` with TAG_TYPE_NOT_ALLOWED.
+    if (t.custom === true && (type === "title" || type === "script")) {
+        throw new Error("Refusing to write: a `title` or `script` tag cannot carry `custom: true` " +
+            "— Wix rejects it with TAG_TYPE_NOT_ALLOWED. Omit `custom` for those, " +
+            "including for JSON-LD structured data.");
+    }
+    const out = { type };
+    if (t.props !== undefined && t.props !== null && typeof t.props === "object" && !Array.isArray(t.props)) {
+        out.props = t.props;
+    }
+    // `meta` IS PART OF THE WRITABLE SHAPE (e.g. `{height, width}`). Dropping it
+    // made every read-modify-write quietly degrade a tag that carried it — and
+    // the loss guard could not see it, since a singular slot is matched by slot.
+    if (t.meta !== undefined &&
+        t.meta !== null &&
+        typeof t.meta === "object" &&
+        !Array.isArray(t.meta)) {
+        out.meta = t.meta;
+    }
+    if (typeof t.children === "string")
+        out.children = t.children;
+    if (typeof t.custom === "boolean")
+        out.custom = t.custom;
+    if (typeof t.disabled === "boolean")
+        out.disabled = t.disabled;
+    return out;
+}
+/** The tags an item or the site holds RIGHT NOW, hashed like a redirect token:
+ *  consent is given on a list that was shown, and stops being consent the
+ *  moment that list changes. */
+function tagsToken(site, scope, current, proposed = []) {
+    // THE TOKEN SIGNS THE CHANGE, not just the state. Binding it to the current
+    // tags alone let a caller earn a token by proposing to drop the description,
+    // then reuse that same token with `tags: []` and take the title too — a loss
+    // nobody was ever shown. Proposal included, any edit to what is being written
+    // mints a different token and earns a fresh refusal.
+    const canonical = JSON.stringify([
+        site,
+        scope,
+        current.map((t) => [tagLabel(t), JSON.stringify(t)]).sort(),
+        proposed.map((t) => [tagLabel(t), JSON.stringify(t)]).sort(),
+    ]);
+    return `${scope}:${createHmac("sha256", TOKEN_SECRET)
+        .update(canonical)
+        .digest("hex")
+        .slice(0, 16)}`;
+}
+/** Tags the item holds now that the incoming set does not replace — the loss
+ *  nobody asked for. */
+/** What identifies one tag AMONG OTHERS IN THE SAME SLOT: its content. */
+function tagContent(t) {
+    // THE WHOLE TAG, not just its text. Two tags sharing a slot and a `content`
+    // can still differ by `custom` or `disabled`, and comparing only the text
+    // reported the odd one out as kept.
+    const tag = (t ?? {});
+    const props = (tag.props ?? {});
+    return JSON.stringify([
+        Object.keys(props)
+            .sort()
+            .map((k) => [k, props[k]]),
+        tag.meta ?? null,
+        typeof tag.children === "string" ? tag.children : null,
+        tag.custom === true,
+        tag.disabled === true,
+    ]);
+}
+/** Tags the item holds now that the incoming set does not replace.
+ *
+ *  A slot that appears ONCE is matched by slot alone: replacing a description
+ *  with another description is an edit, not a loss, and demanding an
+ *  acknowledgement for every routine rewrite would be ceremony.
+ *
+ *  A slot that REPEATS — two `og:image`, several `article:tag`, several JSON-LD
+ *  blocks — cannot be matched that way: sending one of them made all of them
+ *  read as kept, and the rest went out silently. There, a tag survives only if
+ *  an identical one is being sent. */
+function tagsLostBy(current, next) {
+    const incomingBySlot = new Map();
+    for (const t of next) {
+        const slot = tagLabel(t);
+        const list = incomingBySlot.get(slot) ?? [];
+        list.push(tagContent(t));
+        incomingBySlot.set(slot, list);
+    }
+    const currentCounts = new Map();
+    for (const t of current) {
+        const slot = tagLabel(t);
+        currentCounts.set(slot, (currentCounts.get(slot) ?? 0) + 1);
+    }
+    // THE VALUE TRAVELS WITH THE LOSS. A slot alone reads the same whether the
+    // description that disappears said one thing or another, and the operator is
+    // deciding on the thing, not on its address.
+    const lost = [];
+    // MATCHES ARE CONSUMED. Two identical tags held today against ONE being sent
+    // is a loss of one of them; a set that only tested membership called both
+    // kept.
+    const unclaimed = new Map([...incomingBySlot].map(([k, v]) => [k, [...v]]));
+    for (const t of current) {
+        const slot = tagLabel(t);
+        const incoming = incomingBySlot.get(slot);
+        if (incoming === undefined || incoming.length === 0) {
+            lost.push({ ...tagPreview(t), tag: t });
+            continue;
+        }
+        const repeated = (currentCounts.get(slot) ?? 0) > 1 || incoming.length > 1;
+        if (!repeated)
+            continue;
+        const pool = unclaimed.get(slot) ?? [];
+        const at = pool.indexOf(tagContent(t));
+        if (at === -1) {
+            lost.push({ ...tagPreview(t), tag: t });
+        }
+        else {
+            pool.splice(at, 1);
+            unclaimed.set(slot, pool);
+        }
+    }
+    return lost;
+}
+/** Read one item's SEO tags, failing closed like `listExisting`. */
+async function readItemOwnTags(client, siteId, itemType, itemId, signal) {
+    const resp = await client.request("GET", `/promote/seo/v1/item-seo-tags/${encodeURIComponent(itemType)}/${encodeURIComponent(itemId)}`, { siteId, signal });
+    // THE ENVELOPE MUST BE THERE. Falling back to the whole response accepted any
+    // 2xx object — `{}` , or a Developer Preview reshuffle — as "this item owns no
+    // tags", and a full replacement then went out with nothing to acknowledge.
+    // An item with no tags of its own still returns `itemSeoTags`; it is `tags`
+    // that is legitimately empty.
+    const holder = resp !== null && typeof resp === "object"
+        ? resp.itemSeoTags
+        : undefined;
+    if (holder === null || typeof holder !== "object" || Array.isArray(holder)) {
+        throw new Error("Refusing to write: the read of this item's SEO tags did not return the " +
+            "`itemSeoTags` object this version understands, so the check for what " +
+            "the write would replace cannot be trusted.");
+    }
+    const tags = holder.tags;
+    if (tags !== undefined && !Array.isArray(tags)) {
+        throw new Error("Refusing to write: this item's SEO tags could not be read as a list, so " +
+            "the check for what the write would replace cannot be trusted.");
+    }
+    return tags ?? [];
+}
+/** The acknowledgement a tag write takes, mirroring the redirects'. */
+const AcknowledgeReplacementParam = Type.Optional(Type.String({
+    description: "The `token` from a previous refusal, once the user has accepted losing " +
+        "the tags it listed. Tied to what the item holds RIGHT NOW: if the tags " +
+        "changed since the refusal, the token no longer matches and the call is " +
+        "refused again with a fresh list.",
+}));
+/** `fieldMask` travels as a COMMA-SEPARATED STRING over REST. The SDK takes an
+ *  array, which is what a model reaches for; sending one here is silently not
+ *  the documented shape. Built, never accepted from the caller. */
+function fieldMaskOf(...fields) {
+    return fields.filter((f) => typeof f === "string").join(",");
+}
+const SEO_PATTERNS = "/promote/seo/v1/seo-patterns";
+/** The current pattern for a page type, plus HOW MANY PAGES it drives.
+ *
+ *  The count is best-effort on purpose: `pageType` and the item-tags
+ *  `itemType` are two vocabularies that overlap but are not documented as the
+ *  same, so a type that lists nothing is reported as `unknown` rather than
+ *  blocking the write. Refusing on a failed COUNT would be refusing on an
+ *  inference. */
+async function readPatternPreflight(client, siteId, pageType, pageId, signal) {
+    // THE COUNT RUNS FIRST, AND THE PATTERN IS READ LAST. Both orders answer
+    // the same, but the pattern read is what the caller's token is computed
+    // over: with up to ten listing requests standing between that read and
+    // the PATCH, a dashboard edit landing in between was overwritten under a
+    // token that had never been shown it. Reading it last leaves no request
+    // of ours inside the window.
+    // THE COUNT IS A CLAIM, so it says what it does not know.
+    //   - it follows the cursor instead of reporting the first page as the total;
+    //   - it excludes items that carry their OWN tags, which a pattern does not
+    //     drive — counting them overstated the blast radius;
+    //   - an EMPTY list reads as `unknown`, not `0`: `pageType` and the item-tags
+    //     `itemType` are two vocabularies that overlap without being documented
+    //     as the same, so "nothing came back" cannot be told apart from "this
+    //     type is not listable here";
+    //   - past the page bound it reports `"100+"` rather than a number it did
+    //     not finish counting.
+    let pageCount = "unknown";
+    // UNKNOWN UNTIL COUNTED. Reporting `0` when the listing failed asserted that
+    // no page carries tags of its own — a fact the pre-flight never established.
+    let partialOverrides = "unknown";
+    try {
+        let cursor = null;
+        let unreadableCursor = false;
+        let driven = 0;
+        let overridden = 0;
+        let seen = 0;
+        let rounds = 0;
+        do {
+            // THE COMPOSITE TYPE for a Wix Data page — `WIX_DATA_PAGE_ITEM-{pageId}`,
+            // as this plugin's own `wix_seo_list_item_tags` description already
+            // states. Listing the bare type returned nothing, so a dynamic page
+            // pattern lost exactly the blast radius the pre-flight exists to show.
+            const listType = pageType === "WIX_DATA_PAGE_ITEM" && pageId !== undefined
+                ? `${pageType}-${pageId}`
+                : pageType;
+            const listed = await client.request("GET", `/promote/seo/v1/item-seo-tags/${encodeURIComponent(listType)}`, {
+                siteId,
+                signal,
+                query: compactQuery({
+                    "paging.limit": 100,
+                    ...(cursor !== null ? { "paging.cursor": cursor } : {}),
+                }),
+            });
+            const body = (listed ?? {});
+            const items = Array.isArray(body.itemsSeoTags) ? body.itemsSeoTags : [];
+            seen += items.length;
+            // EVERY ITEM COUNTS. `hasOverride` says the item sets SOME tag of its
+            // own, not that it escapes the pattern — the tags it does not override
+            // still resolve from it. Excluding those pages understated the blast
+            // radius, down to zero on a type where every item has a title of its own.
+            driven += items.length;
+            overridden += items.filter((i) => i.hasOverride === true).length;
+            const next = body.pagingMetadata?.cursors?.next;
+            // A CURSOR IN A SHAPE THIS VERSION DOES NOT READ IS NOT AN END OF LIST.
+            // Coercing it to `null` stopped the walk early and then reported the
+            // pages counted so far as an EXACT total — understating the blast
+            // radius on the very screen that exists to show it.
+            if (next !== undefined && next !== null && typeof next !== "string") {
+                unreadableCursor = true;
+                break;
+            }
+            cursor = typeof next === "string" && next.length > 0 ? next : null;
+        } while (cursor !== null && ++rounds < 10);
+        if (!unreadableCursor && seen > 0) {
+            // PAST THE BOUND, BOTH NUMBERS ARE LOWER BOUNDS. Only `pageCount` said
+            // so: pages never walked can carry overrides too, so an exact
+            // `partialOverrides` understated how many pages keep tags of their own
+            // — on the screen that exists to size the blast radius.
+            pageCount = cursor !== null ? `${driven}+` : driven;
+            partialOverrides = cursor !== null ? `${overridden}+` : overridden;
+        }
+    }
+    catch (err) {
+        // AN ABORT IS NOT A FAILED COUNT. Swallowing it let a cancelled call carry
+        // on and answer with a refusal, reported as a successful result.
+        throwIfAborted(signal);
+        if (err instanceof Error && err.name === "AbortError")
+            throw err;
+        pageCount = "unknown";
+        partialOverrides = "unknown";
+    }
+    const resp = await client.request("GET", `${SEO_PATTERNS}/${encodeURIComponent(pageType)}`, {
+        siteId,
+        signal,
+        // THE RESOURCE THE WRITE WILL TOUCH. `pageId` narrows the pattern to one
+        // dynamic page; omitting it here read the page TYPE's generic pattern
+        // while the write went to the page's own — so the token, the templates
+        // shown and the page count all described something else.
+        query: compactQuery({ pageId }),
+    });
+    // FAIL CLOSED. Falling back to the whole response turned an unrecognised
+    // body into "this page type has no pattern" — and for the reset that is the
+    // branch that skips the acknowledgement entirely, sending a site-wide reset
+    // with nothing shown.
+    const holder = resp !== null && typeof resp === "object"
+        ? resp.seoPattern
+        : undefined;
+    if (holder === null || typeof holder !== "object" || Array.isArray(holder)) {
+        throw new Error("Refusing to write: the read of this page type's pattern did not return " +
+            "the `seoPattern` object this version understands, so the check for " +
+            "what the write would replace cannot be trusted.");
+    }
+    const pattern = holder.pattern;
+    // A `pattern` THAT IS THERE BUT UNREADABLE IS NOT AN ABSENT ONE. A string or
+    // an array used to fall through to `tags: []`, and the reset — whose whole
+    // acknowledgement hangs on `tags.length > 0` — then fired immediately on
+    // every page of the type.
+    if (pattern !== undefined &&
+        (pattern === null || typeof pattern !== "object" || Array.isArray(pattern))) {
+        throw new Error("Refusing to write: this page type's `pattern` came back in a shape this " +
+            "version does not understand, so it cannot be told apart from a page " +
+            "type that has no pattern at all.");
+    }
+    const rawTags = pattern !== null && pattern !== undefined && typeof pattern === "object"
+        ? pattern.tags
+        : undefined;
+    if (rawTags !== undefined && !Array.isArray(rawTags)) {
+        throw new Error("Refusing to write: this page type's pattern could not be read as a list " +
+            "of tag templates, so the check for what the write would replace " +
+            "cannot be trusted.");
+    }
+    // OWNERSHIP COMES FROM `source`, NOT FROM A COUNT. A site pattern holding
+    // zero templates is still the site's own: inferring absence from
+    // `tags.length` made the create recommend a POST that fails
+    // PATTERN_ALREADY_EXISTS, and let the reset fire with no acknowledgement.
+    const source = holder.source;
+    // NO `source`, NO ANSWER. Deducing ownership from the template count made an
+    // OWNED but empty pattern read as the Wix default — the branch on which the
+    // reset skips its acknowledgement entirely and deletes that pattern.
+    if (typeof source !== "string" || source.length === 0) {
+        throw new Error("Refusing to write: this page type's pattern came back without a " +
+            "`source`, so a pattern the site owns cannot be told apart from the " +
+            "Wix default — and the two lead to opposite writes.");
+    }
+    const hasOwnPattern = source !== "PATTERN_SOURCE_DEFAULT";
+    return {
+        tags: rawTags ?? [],
+        pageCount,
+        partialOverrides,
+        hasOwnPattern,
+    };
+}
+/** The blast radius, as the token sees it.
+ *
+ *  THE RADIUS IS PART OF WHAT WAS ACKNOWLEDGED. Binding only the templates let
+ *  a token minted while the type held 12 pages authorise the same write once it
+ *  held 400: the second pre-flight recomputed the count, printed nothing, and
+ *  wrote. An operator who accepted "this changes 12 pages" never accepted 400.
+ *  A count that becomes `unknown` expires the token too — fail-closed is the
+ *  same direction as everywhere else here. */
+function radiusOf(p) {
+    return `pages=${p.pageCount}:own=${p.partialOverrides}`;
+}
+export function buildSeoTools(client) {
+    return [
+        // ---------------------------------------------------------------- audit
+        defineWixTool({
+            name: "wix_seo_list_item_tags",
+            description: "AUDIT ENTRY POINT. List the items of one type with their SEO tags. " +
+                "Pass `STATIC_PAGE` to enumerate the site's pages; other types are " +
+                "`BLOG_POST`, `STORES_PRODUCT`, and `WIX_DATA_PAGE_ITEM-{pageId}` " +
+                "for a page built from a CMS collection. Each item reports " +
+                "`hasOverride` (does it set tags of its own), `tags` (those it sets) " +
+                "and `resolvedTags` (what it is expected to render, each marked with " +
+                "its source: item, host page, user pattern, Wix pattern, or site). " +
+                "WIRE SHAPE — a `resolvedTags` entry is an ENVELOPE: the tag is at " +
+                "`entry.tag` and its provenance at `entry.source`, whereas `tags` " +
+                "holds bare tags with no envelope. Reading `resolvedTags[].type` " +
+                "yields nothing, which reads as a missing title rather than as a " +
+                "mistake. " +
+                "A site without the business solution behind a type returns an empty " +
+                "list. Cursor paging: pass the response's cursor back as " +
+                "`paging.cursor`. " +
+                "LIMIT — for `STATIC_PAGE` the tags reflect the SAVED revision, " +
+                "never the published one, and `publishStatus` is always " +
+                "`PUBLISH_STATUS_UNSPECIFIED`: report findings as being about the " +
+                "saved page, not the live one. `resolvedTags` also omits tags added " +
+                "by site code or apps at render time, so it is not the rendered head.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                itemType: Type.String({
+                    description: "Item type, e.g. `STATIC_PAGE`, `BLOG_POST`, `STORES_PRODUCT`.",
+                }),
+                paging: Type.Optional(SeoCursorPagingSchema),
+            }),
+            run: (params, _client, signal) => client.request("GET", `/promote/seo/v1/item-seo-tags/${encodeURIComponent(params.itemType)}`, {
+                siteId: params.siteId,
+                signal,
+                // BUILT FROM THE TWO KEYS THIS ENDPOINT DEFINES, not from the
+                // generic helper. Narrowing the schema only stops `offset` being
+                // ADVERTISED: TypeBox passes undeclared properties through and
+                // `execute` can be called directly, so the helper would still
+                // have forwarded a `paging.offset` that arrived at runtime.
+                query: compactQuery({
+                    "paging.limit": params.paging?.limit,
+                    "paging.cursor": params.paging?.cursor,
+                }),
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_get_item_tags",
+            description: "Read one item's SEO tags: what it sets itself (`tags`), whether it " +
+                "sets anything (`hasOverride`), and what it is expected to render " +
+                "(`resolvedTags`, each marked with its source). For a static page, " +
+                "`itemId` is the page GUID — get it from `wix_seo_list_item_tags`. " +
+                "Same STATIC_PAGE limit: this is the SAVED revision, not the live one.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                itemType: Type.String(),
+                itemId: Type.String({
+                    description: "Item GUID. For a static page, the page GUID.",
+                }),
+            }),
+            run: (params, _client, signal) => client.request("GET", `/promote/seo/v1/item-seo-tags/${encodeURIComponent(params.itemType)}/${encodeURIComponent(params.itemId)}`, { siteId: params.siteId, signal }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_get_site_tags",
+            description: "Read the site-wide SEO tags: the ones that can be changed (`tags` " +
+                "— default `og:image`, a `robots` directive, site verification " +
+                "tags, other site-wide meta) and the verification tags added " +
+                "through the dashboard as HTML embeds (`embedTags`, read-only). " +
+                "Per-page tags — titles, descriptions, canonical links, structured " +
+                "data — are NOT here: read those with `wix_seo_get_item_tags`.",
+            parameters: Type.Object({ siteId: SiteIdParam }),
+            run: (params, _client, signal) => client.request("GET", "/promote/seo/v1/site-seo-tags", {
+                siteId: params.siteId,
+                signal,
+            }),
+        }, client),
+        // ------------------------------------------------------------ redirects
+        defineWixTool({
+            name: "wix_seo_list_redirects",
+            description: "List EVERY redirect on the site in one response. There is no query " +
+                "or search endpoint for redirects and no paging — filter and sort " +
+                "the returned array yourself. Includes redirects Wix created on the " +
+                "owner's behalf, such as when a page's slug was renamed in the " +
+                "editor. ALWAYS call this before creating a redirect: a create can " +
+                "delete an existing one (see `wix_seo_create_redirect`).",
+            parameters: Type.Object({ siteId: SiteIdParam }),
+            run: (params, _client, signal) => client.request("GET", `${REDIRECTS}/redirects`, {
+                siteId: params.siteId,
+                signal,
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_get_redirect",
+            description: "Retrieve one redirect by GUID. A 404 means no redirect has that " +
+                "GUID — the API does not return the documented `REDIRECT_NOT_FOUND` " +
+                "code today, so do not report the GUID as valid.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                redirectId: Type.String({ description: "Redirect GUID." }),
+            }),
+            run: (params, _client, signal) => client.request("GET", `${REDIRECTS}/redirects/${encodeURIComponent(params.redirectId)}`, { siteId: params.siteId, signal }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_create_redirect",
+            description: "Create a 301 redirect. It takes effect on the live site " +
+                "immediately, with no publish, and TAKES PRECEDENCE OVER A REAL " +
+                "PAGE at the same path — creating one from a path that still serves " +
+                "a page makes that page unreachable. " +
+                "THIS CALL CAN DELETE ANOTHER REDIRECT. Redirects do not chain: if " +
+                "an existing redirect STARTS AT the path this one points to, that " +
+                "existing redirect is deleted and the create proceeds. With this " +
+                "tool's OWN top-level `forceReplace` parameter, a redirect holding " +
+                "the same `from` path is deleted too; without it, a taken `from` " +
+                "path fails with `FROM_URL_EXISTS` and writes nothing. Wix documents " +
+                "that flag as `options.forceReplace`, nested in the redirect — DO " +
+                "NOT send it there: this tool rebuilds the redirect from the fields " +
+                "it supports, so a nested flag is dropped and the create fails as if " +
+                "you had never set it. Deletions here are permanent. " +
+                "THE CHECK IS RUN FOR YOU: the tool lists the site's redirects first " +
+                "and REFUSES, naming what it would delete, until you call again with " +
+                "`acknowledgeDeletions` listing the `token` of each — the redirect's " +
+                "GUID is NOT accepted, since an id stays valid while the redirect " +
+                "behind it changes. Show them to the user and get an answer before " +
+                "doing that. " +
+                "Never set `forceReplace` on your own initiative. " +
+                "There is no update method: to change a redirect, get it, delete it, " +
+                "then create it with EVERY field carried over — an omitted field is " +
+                "filled with its default, not its previous value.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                redirect: RedirectSchema,
+                forceReplace: Type.Optional(Type.Boolean({
+                    description: "Delete the redirect already holding the `from` path and put " +
+                        "this one in its place. The replaced redirect is gone for " +
+                        "good. Only ever set this when the user asked for it after " +
+                        "being told what it destroys.",
+                })),
+                acknowledgeDeletions: AcknowledgeParam,
+            }),
+            run: (params, _client, signal) => serializedBySite(client, params.siteId, async () => {
+                // ABORT IS CHECKED AFTER THE QUEUE, not only before it. A call can
+                // sit behind another site-write for as long as that one takes, and
+                // running it once the caller has given up sends an irreversible
+                // POST for an operation the runtime already reported as cancelled.
+                throwIfAborted(signal);
+                const effectiveSite = params.siteId ?? client.defaultSiteId ?? "";
+                // THE PREFLIGHT IS THE CODE'S, not the model's.
+                const existing = await listExisting(client, params.siteId, signal);
+                // NORMALISED ONCE, then used for BOTH the check and the body. The
+                // preflight tested `=== true` while the body forwarded whatever was
+                // passed, so a truthy non-boolean — reachable through a direct
+                // `execute`, which the schema does not police — ran the check as
+                // "no force replace" and then serialised to `true` on the wire.
+                // The flag decides a permanent deletion; it cannot mean two things.
+                const forceReplace = params.forceReplace === true;
+                const doomed = deletionsCausedBy(existing, params.redirect, forceReplace);
+                const acknowledged = new Set(params.acknowledgeDeletions ?? []);
+                const unacknowledged = doomed.filter((d) => !acknowledged.has(redirectToken(effectiveSite, d.redirect)));
+                if (unacknowledged.length > 0) {
+                    return {
+                        refused: "this create would permanently delete existing redirect(s)",
+                        // THE FULL BLAST RADIUS, never the remainder. Listing only what
+                        // was still unacknowledged made `howToProceed` — "every token
+                        // above" — name a DIFFERENT set on each refusal: a caller that
+                        // REPLACED its list instead of extending it alternated between
+                        // halves and never converged, so a legitimate deletion became
+                        // impossible. It also understated the loss, the second prompt
+                        // showing fewer deletions than the first.
+                        wouldDelete: doomed.map((d) => ({
+                            acknowledged: acknowledged.has(redirectToken(effectiveSite, d.redirect)),
+                            reason: d.reason === "loop"
+                                ? "redirects do not chain: this one starts at the path your new redirect points to"
+                                : "forceReplace: this one holds the `from` path you are taking",
+                            // Tied to the redirect's CURRENT state: it stops matching the
+                            // moment the redirect changes, so an acknowledgement can
+                            // never authorise deleting something else.
+                            token: redirectToken(effectiveSite, d.redirect),
+                            id: d.redirect.id,
+                            from: d.redirect.from,
+                            to: d.redirect.to,
+                            language: d.redirect.language ?? "all languages",
+                            groupRedirect: d.redirect.options?.groupRedirect === true,
+                        })),
+                        howToProceed: "Show these to the user. Only if they accept the loss, call " +
+                            "again with `acknowledgeDeletions` listing EVERY token above, " +
+                            "including any already marked `acknowledged: true`. A partial " +
+                            "list is refused again.",
+                    };
+                }
+                throwIfAborted(signal);
+                return client.request("POST", `${REDIRECTS}/create-redirect`, {
+                    siteId: params.siteId,
+                    signal,
+                    // NOT REPLAYED. A create that Wix applied before answering 502 —
+                    // deleting a loop-closing redirect on the way — would be applied
+                    // twice by a retry, and nothing in either answer says which
+                    // happened. Surfacing the error and letting the caller re-read is
+                    // the only honest outcome.
+                    retry: false,
+                    body: {
+                        redirect: sanitizeRedirect(params.redirect),
+                        ...(forceReplace ? { options: { forceReplace: true } } : {}),
+                    },
+                });
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_delete_redirect",
+            description: "Delete one redirect by GUID. Permanent, and effective on the live " +
+                "site immediately. The redirect is RE-READ first and the call is " +
+                "REFUSED, showing its paths, language and scope, until you call again " +
+                "with the `token` from that refusal in `acknowledgeDeletions` — a GUID " +
+                "alone is not a target, because Wix accepts caller-supplied GUIDs and " +
+                "the same id can name a different redirect by the time you get here.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                redirectId: Type.String({ description: "Redirect GUID." }),
+                acknowledgeDeletions: AcknowledgeParam,
+            }),
+            run: (params, _client, signal) => serializedBySite(client, params.siteId, async () => {
+                throwIfAborted(signal);
+                const effectiveSite = params.siteId ?? client.defaultSiteId ?? "";
+                // AN ID IS NOT A TARGET. Wix accepts caller-supplied GUIDs, so
+                // between a listing, the operator's approval and this call the same
+                // id can name a different redirect — and the prompt showed nothing
+                // but the id. The redirect is re-read here and must be
+                // acknowledged by a token bound to its current state, the same
+                // protocol the creates use.
+                const existing = await listExisting(client, params.siteId, signal);
+                const target = existing.find((r) => r.id === params.redirectId);
+                if (target === undefined) {
+                    return {
+                        refused: "no redirect with that id is on this site right now",
+                        howToProceed: "Call `wix_seo_list_redirects` and pick the redirect again.",
+                    };
+                }
+                const token = redirectToken(effectiveSite, target);
+                if (!(params.acknowledgeDeletions ?? []).includes(token)) {
+                    return {
+                        refused: "this deletion is permanent and has not been acknowledged",
+                        wouldDelete: {
+                            token,
+                            id: target.id,
+                            from: target.from,
+                            to: target.to,
+                            language: target.language ?? "all languages",
+                            groupRedirect: target.options?.groupRedirect === true,
+                        },
+                        howToProceed: "Show this to the user. Only if they accept the loss, call " +
+                            "again with `acknowledgeDeletions: [\"<token>\"]`.",
+                    };
+                }
+                throwIfAborted(signal);
+                return client.request("DELETE", `${REDIRECTS}/redirects/${encodeURIComponent(params.redirectId)}`,
+                // NOT REPLAYED. A delete Wix applied before answering 503 comes
+                // back 404 on the replay, and the plugin would report a failure
+                // for a permanent deletion that did happen.
+                { siteId: params.siteId, signal, retry: false });
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_bulk_create_redirects",
+            description: "Create 1 to 100 redirects in one call. NOT ATOMIC, and each item " +
+                "carries its own outcome INSIDE a successful response: read " +
+                "`results[].itemMetadata`, matched to your request by " +
+                "`originalIndex`; a failed item carries `error.code` such as " +
+                "`FROM_URL_EXISTS`. `bulkActionMetadata.undetailedFailures` counts " +
+                "items whose outcome is UNKNOWN — they may or may not have been " +
+                "written; call `wix_seo_list_redirects` to find out, and never " +
+                "report them as successes. " +
+                "TWO KINDS OF LOOP, and only one of them destroys. An item that " +
+                "closes a loop with an EARLIER ITEM OF THIS SAME REQUEST fails on its " +
+                "own with `REDIRECT_LOOP` and the rest of the batch goes ahead — " +
+                "nothing is deleted, so report that item as failed rather than as a " +
+                "loss. An item that closes a loop with a redirect ALREADY ON THE SITE " +
+                "is created and that site redirect is DELETED, permanently. Only the " +
+                "second is checked for you: the call is REFUSED, naming every existing " +
+                "redirect it would delete and the item causing it, until you call " +
+                "again with `acknowledgeDeletions` listing the `token` of each — a " +
+                "GUID is not accepted. " +
+                "A malformed request (an empty list) is rejected " +
+                "whole with a 400 and returns no per-item results.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                // ONE HUNDRED, from the reference. The skill page says 1–500; the
+                // method page and the Developer Preview index both say 100, and a
+                // batch Wix rejects outright helps nobody.
+                redirects: Type.Array(RedirectSchema, { minItems: 1, maxItems: 100 }),
+                returnFullEntity: Type.Optional(Type.Boolean({
+                    description: "Return each created redirect in `results[].item`.",
+                })),
+                acknowledgeDeletions: AcknowledgeParam,
+            }),
+            run: (params, _client, signal) => serializedBySite(client, params.siteId, async () => {
+                throwIfAborted(signal);
+                const effectiveSite = params.siteId ?? client.defaultSiteId ?? "";
+                // Same code-run preflight as the single create: bulk is not atomic,
+                // so a loop-causing redirect can still be deleted before the item
+                // that caused it fails to be written.
+                const existing = await listExisting(client, params.siteId, signal);
+                const acknowledged = new Set(params.acknowledgeDeletions ?? []);
+                const doomed = params.redirects.flatMap((candidate, index) => deletionsCausedBy(existing, candidate, false).map((d) => ({
+                    ...d,
+                    index,
+                })));
+                const unacknowledged = doomed.filter((d) => !acknowledged.has(redirectToken(effectiveSite, d.redirect)));
+                if (unacknowledged.length > 0) {
+                    return {
+                        refused: "this bulk create would permanently delete existing redirect(s)",
+                        // THE FULL BLAST RADIUS, never the remainder. Listing only what
+                        // was still unacknowledged made `howToProceed` — "every token
+                        // above" — name a DIFFERENT set on each refusal: a caller that
+                        // REPLACED its list instead of extending it alternated between
+                        // halves and never converged, so a legitimate deletion became
+                        // impossible. It also understated the loss, the second prompt
+                        // showing fewer deletions than the first.
+                        wouldDelete: doomed.map((d) => ({
+                            acknowledged: acknowledged.has(redirectToken(effectiveSite, d.redirect)),
+                            causedByItemIndex: d.index,
+                            reason: "redirects do not chain: this one starts at the path that item points to",
+                            token: redirectToken(effectiveSite, d.redirect),
+                            id: d.redirect.id,
+                            from: d.redirect.from,
+                            to: d.redirect.to,
+                            language: d.redirect.language ?? "all languages",
+                            groupRedirect: d.redirect.options?.groupRedirect === true,
+                        })),
+                        howToProceed: "Show these to the user. Only if they accept the loss, call " +
+                            "again with `acknowledgeDeletions` listing EVERY token above, " +
+                            "including any already marked `acknowledged: true`. A partial " +
+                            "list is refused again.",
+                    };
+                }
+                throwIfAborted(signal);
+                return client.request("POST", `${REDIRECTS}/bulk/redirects/create`, {
+                    siteId: params.siteId,
+                    signal,
+                    // NOT REPLAYED: bulk create is explicitly non-atomic upstream,
+                    // so a partial application followed by a retry is a real path
+                    // to duplicated writes and lost redirects.
+                    retry: false,
+                    body: {
+                        redirects: params.redirects.map(sanitizeRedirect),
+                        ...(params.returnFullEntity !== undefined
+                            ? { returnFullEntity: params.returnFullEntity }
+                            : {}),
+                    },
+                });
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_bulk_delete_redirects",
+            description: "Delete 1 to 500 redirects by GUID. Each one is RE-READ first and the " +
+                "call is REFUSED, showing every redirect's paths, language and scope, " +
+                "until the `token` for each comes back in `acknowledgeDeletions` — a " +
+                "GUID alone is not a target. " +
+                "Same per-item reporting as the " +
+                "bulk create: read `results[].itemMetadata` and treat " +
+                "`bulkActionMetadata.undetailedFailures` as unknown, not as " +
+                "success. A successful item means the deletion was found and sent, " +
+                "not confirmed — call `wix_seo_list_redirects` if the user needs " +
+                "confirmation. Permanent.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                redirectIds: Type.Array(Type.String(), {
+                    minItems: 1,
+                    maxItems: 500,
+                }),
+                acknowledgeDeletions: AcknowledgeParam,
+            }),
+            run: (params, _client, signal) => serializedBySite(client, params.siteId, async () => {
+                throwIfAborted(signal);
+                const effectiveSite = params.siteId ?? client.defaultSiteId ?? "";
+                // THE SAME PROTOCOL AS THE SINGLE DELETE. Sending 500 GUIDs straight
+                // through had exactly the identity hole the single delete just
+                // closed: Wix accepts caller-supplied GUIDs, so an id can name a
+                // different redirect by the time this runs, and the approval prompt
+                // carries ids — not paths, language or scope.
+                const existing = await listExisting(client, params.siteId, signal);
+                const acknowledged = new Set(params.acknowledgeDeletions ?? []);
+                const resolved = params.redirectIds.map((id) => ({
+                    id,
+                    target: existing.find((r) => r.id === id),
+                }));
+                const missing = resolved.filter((r) => r.target === undefined);
+                const targets = resolved.filter((r) => r.target !== undefined);
+                const unacknowledged = targets.filter((r) => !acknowledged.has(redirectToken(effectiveSite, r.target)));
+                if (missing.length > 0 || unacknowledged.length > 0) {
+                    return {
+                        refused: "these deletions are permanent and have not all been acknowledged for their CURRENT state",
+                        notOnThisSite: missing.map((r) => r.id),
+                        // THE FULL BLAST RADIUS, never the remainder. Listing only what
+                        // was still unacknowledged made `howToProceed` — "every token
+                        // above" — name a DIFFERENT set on each refusal: a caller that
+                        // REPLACED its list instead of extending it alternated between
+                        // halves and never converged, so a legitimate deletion became
+                        // impossible. It also understated the loss, the second prompt
+                        // showing fewer deletions than the first.
+                        wouldDelete: targets.map((r) => ({
+                            acknowledged: acknowledged.has(redirectToken(effectiveSite, r.target)),
+                            token: redirectToken(effectiveSite, r.target),
+                            id: r.target.id,
+                            from: r.target.from,
+                            to: r.target.to,
+                            language: r.target.language ?? "all languages",
+                            groupRedirect: r.target.options?.groupRedirect === true,
+                        })),
+                        howToProceed: "Show these to the user. Only if they accept the loss, call " +
+                            "again with `acknowledgeDeletions` listing EVERY token above, " +
+                            "including any already marked `acknowledged: true`. A partial " +
+                            "list is refused again. Drop any id listed under " +
+                            "`notOnThisSite`.",
+                    };
+                }
+                throwIfAborted(signal);
+                return client.request("POST", `${REDIRECTS}/bulk/redirects/delete`, {
+                    siteId: params.siteId,
+                    signal,
+                    // NOT REPLAYED: a partly-applied batch replaced by the replay's own
+                    // per-item results hides which deletions actually landed.
+                    retry: false,
+                    body: { redirectIds: params.redirectIds },
+                });
+            }),
+        }, client),
+        // ---------------------------------------------------- tranche 2: writes
+        defineWixTool({
+            name: "wix_seo_set_item_tags",
+            description: "Set one item's SEO tags. REPLACES the item's own tags IN FULL: send " +
+                "the complete set you want it to have, not just the one you are " +
+                "changing. To give an item back the tags it inherits, call " +
+                "`wix_seo_reset_item_tags` — an empty list is not the way. " +
+                "THE CHECK IS RUN FOR YOU: the tool reads the item first and REFUSES, " +
+                "naming every tag the write would drop, until you call again with " +
+                "`acknowledgeReplacement` set to the `token` from that refusal. " +
+                "PUBLISHED vs SAVED — a static page keeps both. Without `publish` you " +
+                "change the saved revision; with `publish: true` you change ONLY the " +
+                "published one. The read tools always return the SAVED revision, so " +
+                "after a `publish` write they keep showing the old values: that is " +
+                "NOT a failed write and re-sending will not change it. To move both, " +
+                "call twice — once without `publish`, once with. This tool's own " +
+                "response is not a read of the published page either, so never report " +
+                "the live page as changed on the strength of it. " +
+                "Tags are validated before anything is saved: an invalid tag changes " +
+                "nothing. Tags can only be written for the item's primary language.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                itemType: Type.String({
+                    description: "e.g. `STATIC_PAGE`, `BLOG_POST`, `STORES_PRODUCT`.",
+                }),
+                itemId: Type.String({ description: "GUID of the item." }),
+                tags: Type.Array(SeoTagSchema, {
+                    maxItems: 100,
+                    description: "The COMPLETE set of tags this item should own. Accepted types: " +
+                        "`title`, `meta`, `script`, `link`" + ".",
+                }),
+                publish: Type.Optional(Type.Boolean({
+                    description: "Write the PUBLISHED revision instead of the saved one. Read " +
+                        "the tool description before using it.",
+                })),
+                acknowledgeReplacement: AcknowledgeReplacementParam,
+            }),
+            run: (params, _client, signal) => serializedBySite(client, params.siteId, async () => {
+                throwIfAborted(signal);
+                const effectiveSite = params.siteId ?? client.defaultSiteId ?? "";
+                // AN EMPTY LIST IS NOT A REPLACEMENT. Upstream is explicit: to give
+                // an item back what it inherits, call Reset — sending no tags
+                // leaves an empty override behind instead. `minItems` in the schema
+                // does not cover it, since `execute` is callable directly.
+                if (params.tags.length === 0) {
+                    return {
+                        refused: "an empty tag list does not restore inherited tags, it leaves an empty override",
+                        howToProceed: "Call `wix_seo_reset_item_tags` to return this item to the " +
+                            "tags it inherits.",
+                    };
+                }
+                const next = params.tags.map((t) => sanitizeTag(t, ["title", "meta", "script", "link"]));
+                const current = await readItemOwnTags(client, params.siteId, params.itemType, params.itemId, signal);
+                // THE PUBLISHED REVISION CANNOT BE PRE-READ. `publish: true` writes
+                // the published revision, while every read returns the SAVED one —
+                // Wix exposes no way to read the published tags. So the list below
+                // describes the draft, and a live-only tag would be dropped without
+                // ever appearing in it. A write nobody could be shown is refused
+                // every time, loss detected or not: the one answer a safety check
+                // must never invent is the reassuring one.
+                const blindToLive = params.publish === true;
+                const scope = `item:${params.itemType}:${params.itemId}:${blindToLive ? "published" : "saved"}`;
+                const token = tagsToken(effectiveSite, scope, current, next);
+                const lost = tagsLostBy(current, next);
+                if ((lost.length > 0 || blindToLive) &&
+                    params.acknowledgeReplacement !== token) {
+                    return {
+                        refused: blindToLive
+                            ? "this writes the PUBLISHED revision, which cannot be read back — what it replaces there is not knowable, and has not been acknowledged"
+                            : "this write would drop tags the item holds today, and they have not been acknowledged for their CURRENT state",
+                        ...(blindToLive
+                            ? {
+                                publishedRevisionUnreadable: "`wouldLose` below is the SAVED revision. If the published page carries tags the draft does not, this write drops them and they are not listed — no API returns them.",
+                            }
+                            : {}),
+                        wouldLose: lost,
+                        keeping: next.map((t) => tagPreview(t)),
+                        token,
+                        howToProceed: "Show what would be lost to the user — these are facts the " +
+                            "page states today. Only if they accept, call again with " +
+                            "`acknowledgeReplacement` set to the token above, adding any " +
+                            "of those tags you meant to keep to `tags`.",
+                    };
+                }
+                throwIfAborted(signal);
+                return client.request("PATCH", `/promote/seo/v1/item-seo-tags/${encodeURIComponent(params.itemType)}/${encodeURIComponent(params.itemId)}`, {
+                    siteId: params.siteId,
+                    signal,
+                    // NOT REPLAYED: the pre-flight ran against the state read once;
+                    // a replay re-applies a write whose basis may have moved.
+                    retry: false,
+                    body: {
+                        itemSeoTags: { tags: next },
+                        // BUILT, NOT ACCEPTED. Over REST the mask is a comma-separated
+                        // STRING; the SDK takes an array, which is what a model
+                        // reaches for.
+                        fieldMask: fieldMaskOf("tags"),
+                        ...(params.publish === true ? { publish: true } : {}),
+                    },
+                });
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_reset_item_tags",
+            description: "Give one item back the tags it INHERITS, discarding every tag of its " +
+                "own. All or nothing: there is no way to reset only some of them. " +
+                "The tool reads the item first and REFUSES, listing everything that " +
+                "would go, until you call again with `acknowledgeReplacement` set to " +
+                "the `token` from that refusal. Permanent — the previous tags are not " +
+                "kept anywhere.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                itemType: Type.String(),
+                itemId: Type.String(),
+                acknowledgeReplacement: AcknowledgeReplacementParam,
+            }),
+            run: (params, _client, signal) => serializedBySite(client, params.siteId, async () => {
+                throwIfAborted(signal);
+                const effectiveSite = params.siteId ?? client.defaultSiteId ?? "";
+                const current = await readItemOwnTags(client, params.siteId, params.itemType, params.itemId, signal);
+                const scope = `reset:${params.itemType}:${params.itemId}`;
+                const token = tagsToken(effectiveSite, scope, current);
+                // A TOKEN EVEN THOUGH THE OUTCOME IS A NAMED STATE. The outcome
+                // does not depend on what is there now, but the CONSENT does: the
+                // user accepts losing the list they were shown. If the item's tags
+                // changed in between, that list no longer describes the loss.
+                if (current.length > 0 && params.acknowledgeReplacement !== token) {
+                    return {
+                        refused: "resetting discards every tag this item owns, and they have not been acknowledged for their CURRENT state",
+                        wouldLose: current.map((t) => ({ ...tagPreview(t), tag: t })),
+                        token,
+                        howToProceed: "Show these to the user. Only if they accept the loss, call " +
+                            "again with `acknowledgeReplacement` set to the token above.",
+                    };
+                }
+                throwIfAborted(signal);
+                return client.request("POST", `/promote/seo/v1/item-seo-tags/${encodeURIComponent(params.itemType)}/${encodeURIComponent(params.itemId)}/reset-to-default`, { siteId: params.siteId, signal, retry: false });
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_set_site_tags",
+            description: "Set the SITE-WIDE SEO tags — they apply to every page. REPLACES the " +
+                "site's tags IN FULL, same rule as the per-item write. The tool REFUSES, " +
+                "naming every site-wide tag the write would drop, until you call " +
+                "again with `acknowledgeReplacement` set to the `token` from that " +
+                "refusal. " +
+                "ONLY `meta` TAGS: Wix rejects `title`, `script` and `link` here even " +
+                "though the shared tag shape lists them. There is currently no way to " +
+                "set site-wide structured data through any Wix API — write a per-page " +
+                "`script` tag with `wix_seo_set_item_tags` instead.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                tags: Type.Array(SeoTagSchema, {
+                    maxItems: 100,
+                    description: "The COMPLETE set of site-wide tags. `meta` only.",
+                }),
+                acknowledgeReplacement: AcknowledgeReplacementParam,
+            }),
+            run: (params, _client, signal) => serializedBySite(client, params.siteId, async () => {
+                throwIfAborted(signal);
+                const effectiveSite = params.siteId ?? client.defaultSiteId ?? "";
+                const next = params.tags.map((t) => sanitizeTag(t, ["meta"]));
+                const resp = await client.request("GET", "/promote/seo/v1/site-seo-tags", { siteId: params.siteId, signal });
+                // Same fail-closed rule as the per-item read: falling back to the
+                // whole response turned `{}` into "the site has no tags", and the
+                // PATCH then replaced every site-wide tag with nothing to
+                // acknowledge.
+                const holder = resp !== null && typeof resp === "object"
+                    ? resp.siteSeoTags
+                    : undefined;
+                if (holder === null ||
+                    typeof holder !== "object" ||
+                    Array.isArray(holder)) {
+                    throw new Error("Refusing to write: the read of the site's SEO tags did not " +
+                        "return the `siteSeoTags` object this version understands, " +
+                        "so the check for what the write would replace cannot be " +
+                        "trusted.");
+                }
+                const rawTags = holder.tags;
+                if (rawTags !== undefined && !Array.isArray(rawTags)) {
+                    throw new Error("Refusing to write: the site's SEO tags could not be read as a " +
+                        "list, so the check for what the write would replace cannot " +
+                        "be trusted.");
+                }
+                const current = rawTags ?? [];
+                const token = tagsToken(effectiveSite, "site", current, next);
+                const lost = tagsLostBy(current, next);
+                if (lost.length > 0 && params.acknowledgeReplacement !== token) {
+                    return {
+                        refused: "this write would drop site-wide tags in force today, and they have not been acknowledged for their CURRENT state",
+                        wouldLose: lost,
+                        keeping: next.map((t) => tagPreview(t)),
+                        token,
+                        howToProceed: "These apply to EVERY page. Show them to the user and only " +
+                            "call again, with `acknowledgeReplacement` set to the token " +
+                            "above, once they accept the loss.",
+                    };
+                }
+                throwIfAborted(signal);
+                return client.request("PATCH", "/promote/seo/v1/site-seo-tags", {
+                    siteId: params.siteId,
+                    signal,
+                    retry: false,
+                    body: {
+                        siteSeoTags: { tags: next },
+                        fieldMask: fieldMaskOf("tags"),
+                    },
+                });
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_bulk_set_item_tags",
+            description: "Set the SEO tags of MANY items of the same type in one call. Each " +
+                "entry behaves like `wix_seo_set_item_tags`: it REPLACES that item's " +
+                "own tags in full. The tool reads every item first and REFUSES, " +
+                "listing per entry what would be dropped, until you call again with " +
+                "`acknowledgeReplacement` set to the `token` from that refusal. " +
+                "SIZE: up to 100 entries, but `BLOG_POST` is capped at 20 by Wix and " +
+                "exceeding an item type's own limit fails the WHOLE call with " +
+                "`BULK_CHUNK_SIZE_EXCEEDED` — split and retry. " +
+                "PARTIAL SUCCESS: read `results[].itemMetadata` and correlate by " +
+                "`originalIndex`; check `bulkActionMetadata.totalFailures`. One bad " +
+                "entry fails alone. But an unsupported item type, or an unauthorized " +
+                "request, rejects the whole call with no per-entry results — handle " +
+                "both. Re-sending an entry that already succeeded is safe: the writes " +
+                "are idempotent. " +
+                "`publish` is REQUEST-level here: it applies to every entry, and like " +
+                "the single write it moves only the published revision while the read " +
+                "tools keep returning the saved one.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                itemType: Type.String(),
+                entries: Type.Array(Type.Object({
+                    itemId: Type.String(),
+                    tags: Type.Array(SeoTagSchema, { maxItems: 100 }),
+                }), { minItems: 1, maxItems: 100 }),
+                publish: Type.Optional(Type.Boolean()),
+                acknowledgeReplacement: AcknowledgeReplacementParam,
+            }),
+            run: (params, _client, signal) => serializedBySite(client, params.siteId, async () => {
+                throwIfAborted(signal);
+                const effectiveSite = params.siteId ?? client.defaultSiteId ?? "";
+                // ENFORCED HERE because Wix fails the WHOLE call, not the offending
+                // entries: a 40-post batch would write nothing at all. The cap is
+                // the reference's own (`BLOG_POST` 20), not a guess.
+                const perTypeCap = params.itemType === "BLOG_POST" ? 20 : 100;
+                if (params.entries.length > perTypeCap) {
+                    return {
+                        refused: `Wix caps a ${params.itemType} bulk write at ${perTypeCap} entries and rejects the whole call beyond it`,
+                        entries: params.entries.length,
+                        howToProceed: `Split into batches of at most ${perTypeCap} and call again.`,
+                    };
+                }
+                // DUPLICATES REFUSED BEFORE THE READS. Two entries for one item are
+                // two FULL replacements of the same tags, both pre-flighted against
+                // the same starting state: the second silently undoes whatever the
+                // first introduced, and neither loss appears in `wouldLose`.
+                const ids = params.entries.map((e) => e.itemId);
+                const duplicated = [...new Set(ids.filter((id, i) => ids.indexOf(id) !== i))];
+                if (duplicated.length > 0) {
+                    return {
+                        refused: "the same item appears more than once in this batch, and each entry replaces its tags in full",
+                        duplicated,
+                        howToProceed: "Merge the entries for each item into one complete set of " +
+                            "tags and call again.",
+                    };
+                }
+                const empties = params.entries
+                    .filter((e) => e.tags.length === 0)
+                    .map((e) => e.itemId);
+                if (empties.length > 0) {
+                    return {
+                        refused: "an empty tag list does not restore inherited tags, it leaves an empty override",
+                        entriesWithNoTags: empties,
+                        howToProceed: "Drop those entries and call `wix_seo_reset_item_tags` for " +
+                            "each item that should go back to what it inherits.",
+                    };
+                }
+                const prepared = params.entries.map((e) => ({
+                    itemId: e.itemId,
+                    next: e.tags.map((t) => sanitizeTag(t, ["title", "meta", "script", "link"])),
+                }));
+                // ONE READ PER ENTRY. There is no bulk read of item tags, and the
+                // loss cannot be shown without knowing what each item holds today.
+                const losses = [];
+                const currentOf = new Map();
+                for (const e of prepared) {
+                    throwIfAborted(signal);
+                    const current = await readItemOwnTags(client, params.siteId, params.itemType, e.itemId, signal);
+                    currentOf.set(e.itemId, current);
+                    const lost = tagsLostBy(current, e.next);
+                    if (lost.length > 0)
+                        losses.push({ itemId: e.itemId, wouldLose: lost });
+                }
+                // Same blindness as the single write, request-wide here.
+                const blindToLive = params.publish === true;
+                const scope = `bulk:${params.itemType}:${blindToLive ? "published" : "saved"}`;
+                const token = tagsToken(effectiveSite, scope,
+                // PAIRED, NOT TWO SORTED LISTS. Signing the proposals apart from
+                // their item ids made A→X/B→Y and A→Y/B→X hash identically, so an
+                // acknowledgement earned for one pairing authorised the other and
+                // replaced tags whose loss was never approved.
+                prepared
+                    .map((e) => [e.itemId, currentOf.get(e.itemId) ?? [], e.next])
+                    .sort((a, b) => String(a[0]).localeCompare(String(b[0]))), []);
+                if ((losses.length > 0 || blindToLive) &&
+                    params.acknowledgeReplacement !== token) {
+                    return {
+                        refused: blindToLive
+                            ? "this batch writes the PUBLISHED revision of every entry, which cannot be read back — what it replaces there is not knowable, and has not been acknowledged"
+                            : "this batch would drop tags these items hold today, and they have not been acknowledged for their CURRENT state",
+                        ...(blindToLive
+                            ? {
+                                publishedRevisionUnreadable: "`wouldLose` below is each item's SAVED revision. Tags that exist only on the published page are dropped without being listed.",
+                            }
+                            : {}),
+                        wouldLose: losses,
+                        itemsAffected: prepared.length,
+                        token,
+                        howToProceed: "Show the losses to the user, grouped by item. Only if they " +
+                            "accept, call again with `acknowledgeReplacement` set to the " +
+                            "token above — the token covers the WHOLE batch and goes " +
+                            "stale if any of these items changes.",
+                    };
+                }
+                throwIfAborted(signal);
+                return client.request("POST", "/promote/seo/v1/bulk/item-seo-tags/set", {
+                    siteId: params.siteId,
+                    signal,
+                    // NOT REPLAYED: bulk is non-atomic, so a replay's own per-entry
+                    // results would hide which of the first attempt's writes landed.
+                    retry: false,
+                    body: {
+                        itemType: params.itemType,
+                        entries: prepared.map((e) => ({
+                            itemId: e.itemId,
+                            itemSeoTags: { tags: e.next },
+                            fieldMask: fieldMaskOf("tags"),
+                        })),
+                        ...(params.publish === true ? { publish: true } : {}),
+                    },
+                });
+            }),
+        }, client),
+        // ------------------------------------------------- tranche 2: patterns
+        //
+        // THE WIDEST BLAST RADIUS IN THIS PLUGIN. A pattern is the tag template for
+        // an ENTIRE page type: writing one changes the title of every blog post, or
+        // every product, at once. It also has NO REVISION, and the site's SEO
+        // settings in the Wix dashboard write to the same pattern — last write
+        // wins. Hence: read immediately before writing, bind the token to what was
+        // read, and say how many pages are downstream.
+        defineWixTool({
+            name: "wix_seo_list_patterns",
+            description: "List the site's SEO patterns — the tag templates applied per page " +
+                "type. A page type absent from the list is on its Wix default. " +
+                "Read-only.",
+            parameters: Type.Object({ siteId: SiteIdParam }),
+            run: (params, _client, signal) => client.request("GET", `${SEO_PATTERNS}`, {
+                siteId: params.siteId,
+                signal,
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_get_pattern",
+            description: "One page type's SEO pattern. Read `source` to know whose it is: " +
+                "`PATTERN_SOURCE_DEFAULT` means the page type renders Wix's default, " +
+                "anything else means the site owns the pattern — an owned pattern " +
+                "may legitimately hold ZERO templates, so an empty `pattern` is not " +
+                "the same as having none. `wix_seo_create_pattern` is for a page type " +
+                "on the Wix default; `wix_seo_set_pattern` for one the site owns. " +
+                "Pass `pageId` to read the pattern of ONE dynamic page rather than " +
+                "the page type's — the writes accept the same targeting, and a write " +
+                "replaces the pattern in full, so this is how you read what to send " +
+                "back. Read-only.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                pageType: Type.String({
+                    description: "e.g. `BLOG_POST`, `STORES_PRODUCT`.",
+                }),
+                pageId: Type.Optional(Type.String({
+                    description: "GUID of a single dynamic page. Supported for " +
+                        "`WIX_DATA_PAGE_ITEM` page types.",
+                })),
+            }),
+            run: (params, _client, signal) => client.request("GET", `${SEO_PATTERNS}/${encodeURIComponent(params.pageType)}`, {
+                siteId: params.siteId,
+                signal,
+                query: compactQuery({ pageId: params.pageId }),
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_list_pattern_variables",
+            description: "The variables a page type's pattern may reference. A pattern tag " +
+                "that names anything else is invalid — call this BEFORE writing a " +
+                "pattern rather than guessing a variable name. Read-only.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                pageType: Type.String(),
+            }),
+            run: (params, _client, signal) => client.request("GET", `${SEO_PATTERNS}/${encodeURIComponent(params.pageType)}/variables`, { siteId: params.siteId, signal }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_set_pattern",
+            description: "Change the pattern of a page type that ALREADY HAS ONE. For a page " +
+                "type still on its Wix default, use `wix_seo_create_pattern` — this " +
+                "one changes, it does not create. " +
+                "REPLACES the page type's tag templates IN FULL: read the pattern " +
+                "first and send back the complete set. Wix documents an empty " +
+                "pattern as CLEARING it, returning the page type to the Wix default " +
+                "— but `wix_seo_reset_pattern` is the method that says so plainly, " +
+                "and it is the one to use when that is the intent. " +
+                "THIS CHANGES EVERY PAGE OF THE TYPE AT ONCE. The tool reads the " +
+                "current pattern, reports how many pages are downstream, and REFUSES " +
+                "until you call again with `acknowledgeReplacement` set to the " +
+                "`token` from that refusal. " +
+                "A pattern has no revision and the Wix dashboard writes to the same " +
+                "one: last write wins, so a token that has gone stale means somebody " +
+                "else changed it — re-read before insisting. " +
+                "A tag may reference only the variables `wix_seo_list_pattern_variables` " +
+                "returns for this page type.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                pageType: Type.String(),
+                tags: Type.Array(SeoTagSchema, {
+                    maxItems: 100,
+                    description: "The COMPLETE set of tag templates for this page type.",
+                }),
+                pageId: Type.Optional(Type.String({
+                    description: "GUID of a single dynamic page, when the pattern applies to " +
+                        "that page alone rather than to the whole type.",
+                })),
+                acknowledgeReplacement: AcknowledgeReplacementParam,
+            }),
+            run: (params, _client, signal) => serializedBySite(client, params.siteId, async () => {
+                throwIfAborted(signal);
+                const effectiveSite = params.siteId ?? client.defaultSiteId ?? "";
+                const next = params.tags.map((t) => sanitizeTag(t, ["title", "meta", "script", "link"]));
+                const preflight = await readPatternPreflight(client, params.siteId, params.pageType, params.pageId, signal);
+                const token = tagsToken(effectiveSite, `pattern:${params.pageType}:${params.pageId ?? "-"}:${preflight.hasOwnPattern ? "owned" : "default"}:${radiusOf(preflight)}`, preflight.tags, next);
+                const lost = tagsLostBy(preflight.tags, next);
+                // The mirror of the create's check: PATCH changes a pattern that
+                // exists, so on a page type still rendering the Wix default it
+                // cannot do anything but fail — asking for an acknowledgement
+                // first would only make the failure slower.
+                if (!preflight.hasOwnPattern) {
+                    return {
+                        refused: "this page type is on the Wix default and has no pattern of its own to change",
+                        pageType: params.pageType,
+                        pagesAffected: preflight.pageCount,
+                        howToProceed: "Use `wix_seo_create_pattern` to give it its first pattern.",
+                    };
+                }
+                if (params.acknowledgeReplacement !== token) {
+                    return {
+                        refused: "a pattern applies to every page of its type; this write has not been acknowledged for the pattern's CURRENT state",
+                        pageType: params.pageType,
+                        pagesAffected: preflight.pageCount,
+                        pagesWithSomeTagsOfTheirOwn: preflight.partialOverrides,
+                        currentTemplates: preflight.tags.map((t) => tagPreview(t)),
+                        wouldLose: lost,
+                        keeping: next.map((t) => tagPreview(t)),
+                        token,
+                        howToProceed: "Tell the user how many pages this changes and what the " +
+                            "templates become. Only once they accept, call again with " +
+                            "`acknowledgeReplacement` set to the token above.",
+                    };
+                }
+                throwIfAborted(signal);
+                return client.request("PATCH", `${SEO_PATTERNS}/${encodeURIComponent(params.pageType)}`, {
+                    siteId: params.siteId,
+                    signal,
+                    retry: false,
+                    body: {
+                        seoPattern: {
+                            pattern: { tags: next },
+                            ...(params.pageId !== undefined ? { pageId: params.pageId } : {}),
+                        },
+                        fieldMask: fieldMaskOf("pattern"),
+                    },
+                });
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_create_pattern",
+            description: "Give a page type its FIRST pattern, replacing the Wix default. If " +
+                "the page type already has one, use `wix_seo_set_pattern` instead — " +
+                "these two share a path and differ only by HTTP method, so the wrong " +
+                "one is an easy mistake. " +
+                "Same blast radius as the set: every page of the type renders from " +
+                "this template. The tool REFUSES, reporting how many pages are " +
+                "downstream, until you call again with `acknowledgeReplacement` set " +
+                "to the `token` from that refusal.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                pageType: Type.String(),
+                tags: Type.Array(SeoTagSchema, { maxItems: 100 }),
+                pageId: Type.Optional(Type.String()),
+                acknowledgeReplacement: AcknowledgeReplacementParam,
+            }),
+            run: (params, _client, signal) => serializedBySite(client, params.siteId, async () => {
+                throwIfAborted(signal);
+                const effectiveSite = params.siteId ?? client.defaultSiteId ?? "";
+                const next = params.tags.map((t) => sanitizeTag(t, ["title", "meta", "script", "link"]));
+                const preflight = await readPatternPreflight(client, params.siteId, params.pageType, params.pageId, signal);
+                const token = tagsToken(effectiveSite, `pattern-create:${params.pageType}:${params.pageId ?? "-"}:${preflight.hasOwnPattern ? "owned" : "default"}:${radiusOf(preflight)}`, preflight.tags, next);
+                // TERMINAL, NOT A TOKEN. Handing one out for a page type that
+                // already owns a pattern only bought a POST Wix answers with
+                // PATTERN_ALREADY_EXISTS.
+                if (preflight.hasOwnPattern) {
+                    return {
+                        refused: "this page type already has a pattern of its own — create is for a page type still on the Wix default",
+                        pageType: params.pageType,
+                        pagesAffected: preflight.pageCount,
+                        howToProceed: "Use `wix_seo_set_pattern` to change it, or " +
+                            "`wix_seo_reset_pattern` to return the page type to the Wix " +
+                            "default first.",
+                    };
+                }
+                if (params.acknowledgeReplacement !== token) {
+                    return {
+                        refused: "this pattern will drive every page of its type, and has not been acknowledged",
+                        pageType: params.pageType,
+                        pagesAffected: preflight.pageCount,
+                        pagesWithSomeTagsOfTheirOwn: preflight.partialOverrides,
+                        // SHOWN, like the set's. Acknowledging a replacement of
+                        // something never displayed is not consent.
+                        currentTemplates: preflight.tags.map((t) => tagPreview(t)),
+                        proposedTemplates: next.map((t) => tagPreview(t)),
+                        token,
+                        howToProceed: preflight.hasOwnPattern
+                            ? "This page type ALREADY has a pattern — `wix_seo_set_pattern` is the method for that. Confirm with the user before proceeding."
+                            : "Tell the user how many pages this changes, then call again with `acknowledgeReplacement` set to the token above.",
+                    };
+                }
+                throwIfAborted(signal);
+                return client.request("POST", `${SEO_PATTERNS}/${encodeURIComponent(params.pageType)}`, {
+                    siteId: params.siteId,
+                    signal,
+                    retry: false,
+                    body: {
+                        seoPattern: {
+                            pattern: { tags: next },
+                            ...(params.pageId !== undefined ? { pageId: params.pageId } : {}),
+                        },
+                    },
+                });
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_seo_reset_pattern",
+            description: "Return a page type to its WIX DEFAULT pattern, discarding the site's " +
+                "own. Every page of the type re-renders from the default. The tool " +
+                "reads the current pattern, reports how many pages are downstream and " +
+                "REFUSES until you call again with `acknowledgeReplacement` set to " +
+                "the `token` from that refusal. Permanent. " +
+                "Pass `pageId` to reset the pattern of ONE dynamic page — without it " +
+                "the reset targets the page TYPE's own pattern, which is a different " +
+                "object and leaves a per-page override in place.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                pageType: Type.String(),
+                pageId: Type.Optional(Type.String({
+                    description: "GUID of a single dynamic page whose pattern to reset. " +
+                        "`wix_seo_set_pattern` and `wix_seo_create_pattern` can create " +
+                        "such an override, so this is how it is undone.",
+                })),
+                acknowledgeReplacement: AcknowledgeReplacementParam,
+            }),
+            run: (params, _client, signal) => serializedBySite(client, params.siteId, async () => {
+                throwIfAborted(signal);
+                const effectiveSite = params.siteId ?? client.defaultSiteId ?? "";
+                const preflight = await readPatternPreflight(client, params.siteId, params.pageType, params.pageId, signal);
+                const token = tagsToken(effectiveSite, `pattern-reset:${params.pageType}:${params.pageId ?? "-"}:${radiusOf(preflight)}`, preflight.tags);
+                if (preflight.hasOwnPattern && params.acknowledgeReplacement !== token) {
+                    return {
+                        refused: "resetting discards the site's own pattern for this page type, and it has not been acknowledged for its CURRENT state",
+                        pageType: params.pageType,
+                        pagesAffected: preflight.pageCount,
+                        // BOUND, THEREFORE SHOWN. The token covers this number, so a
+                        // retry could be refused with a refusal that read identically
+                        // — the caller unable to see which half of the radius moved.
+                        pagesWithSomeTagsOfTheirOwn: preflight.partialOverrides,
+                        wouldLose: preflight.tags.map((t) => ({
+                            ...tagPreview(t),
+                            tag: t,
+                        })),
+                        token,
+                        howToProceed: "Show the templates that would go and the number of pages " +
+                            "affected. Only if the user accepts, call again with " +
+                            "`acknowledgeReplacement` set to the token above.",
+                    };
+                }
+                throwIfAborted(signal);
+                return client.request("POST", `${SEO_PATTERNS}/${encodeURIComponent(params.pageType)}/reset-to-default`, {
+                    siteId: params.siteId,
+                    signal,
+                    retry: false,
+                    // PLACEMENT INFERRED, AND SAID SO. The reference lists
+                    // `pageId` as a method parameter of this POST without showing
+                    // it on the wire, so the body is the REST convention rather
+                    // than a documented fact. It matters: if Wix ignored the field
+                    // the reset would hit the page TYPE's pattern instead of the
+                    // one page, which is a far wider loss than the refusal
+                    // described. Confirming it needs a live create-then-reset on a
+                    // throwaway dynamic page, which this plugin will not do to
+                    // answer a question.
+                    ...(params.pageId !== undefined
+                        ? { body: { pageId: params.pageId } }
+                        : {}),
+                });
+            }),
+        }, client),
+    ];
+}
+// `SeoTagSchema` is exported for the write tools that land in tranche 2
+// (set item tags, set site tags, SEO patterns).
+export { SeoTagSchema };
+//# sourceMappingURL=seo.js.map