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

@lacneu/wix-openclaw 0.2.2 → 0.3.1

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 +418 -2
package/README.md +94 -8
package/dist/config.d.ts +1 -0
package/dist/config.js +16 -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 +1348 -8
package/dist/index.js +47 -18
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 +199 -0
package/dist/tools/seo.js +836 -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 +40 -6
package/package.json +1 -1

package/dist/tools/seo.js ADDED Viewed

@@ -0,0 +1,836 @@
+// 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>." })),
+    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 } : {}),
+    };
+}
+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),
+    ];
+}
+// `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