@lacneu/wix-openclaw 0.0.1

package/dist/tools/reviews.js

@@ -0,0 +1,72 @@
+// Wix Reviews (`/reviews/v1/...`) tools.
+//
+// Requires the Wix Reviews app to be installed on the target site.
+// Without it, calls return HTTP 428 `APP_NOT_INSTALLED`. Endpoint paths
+// pattern-validated against the public docs; untested live (app not
+// installed on the smoke-test site).
+import { Type } from "@sinclair/typebox";
+import { defineWixTool } from "./_factory.js";
+const SiteIdParam = Type.Optional(Type.String());
+export function buildReviewsTools(client) {
+    return [
+        defineWixTool({
+            name: "wix_reviews_list",
+            description: "List reviews. Filter by moderation status if needed.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                moderationStatus: Type.Optional(Type.Union([
+                    Type.Literal("PENDING"),
+                    Type.Literal("APPROVED"),
+                    Type.Literal("REJECTED"),
+                ])),
+                paging: Type.Optional(Type.Object({
+                    limit: Type.Optional(Type.Number({ minimum: 1, maximum: 100 })),
+                    offset: Type.Optional(Type.Number({ minimum: 0 })),
+                })),
+            }),
+            run: (params) => client.request("POST", "/reviews/v1/reviews/query", {
+                siteId: params.siteId,
+                body: {
+                    query: {
+                        filter: params.moderationStatus
+                            ? { moderationStatus: params.moderationStatus }
+                            : undefined,
+                        paging: params.paging,
+                    },
+                },
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_reviews_get",
+            description: "Fetch a single review by id.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                reviewId: Type.String(),
+            }),
+            run: (params) => client.request("GET", `/reviews/v1/reviews/${encodeURIComponent(params.reviewId)}`, { siteId: params.siteId }),
+        }, client),
+        defineWixTool({
+            name: "wix_reviews_moderate",
+            description: "Approve or reject a pending review. APPROVAL GATED.",
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                reviewId: Type.String(),
+                decision: Type.Union([
+                    Type.Literal("APPROVED"),
+                    Type.Literal("REJECTED"),
+                ]),
+                reason: Type.Optional(Type.String({
+                    description: "Optional reason for rejection — surfaced to the reviewer.",
+                })),
+            }),
+            run: (params) => {
+                const verb = params.decision === "APPROVED" ? "approve" : "reject";
+                return client.request("POST", `/reviews/v1/reviews/${encodeURIComponent(params.reviewId)}/${verb}`, {
+                    siteId: params.siteId,
+                    body: params.reason ? { reason: params.reason } : {},
+                });
+            },
+        }, client),
+    ];
+}
+//# sourceMappingURL=reviews.js.map

package/dist/tools/reviews.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reviews.js","sourceRoot":"","sources":["../../src/tools/reviews.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,mEAAmE;AACnE,wEAAwE;AACxE,oEAAoE;AACpE,qCAAqC;AAErC,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAEzC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;AAEjD,MAAM,UAAU,iBAAiB,CAAC,MAAiB;IACjD,OAAO;QACL,aAAa,CACX;YACE,IAAI,EAAE,kBAAkB;YACxB,WAAW,EAAE,sDAAsD;YACnE,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC;gBACtB,MAAM,EAAE,WAAW;gBACnB,gBAAgB,EAAE,IAAI,CAAC,QAAQ,CAC7B,IAAI,CAAC,KAAK,CAAC;oBACT,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;oBACvB,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;oBACxB,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;iBACzB,CAAC,CACH;gBACD,MAAM,EAAE,IAAI,CAAC,QAAQ,CACnB,IAAI,CAAC,MAAM,CAAC;oBACV,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;oBAC/D,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;iBACnD,CAAC,CACH;aACF,CAAC;YACF,GAAG,EAAE,CAAC,MAAM,EAAE,EAAE,CACd,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,2BAA2B,EAAE;gBAClD,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,IAAI,EAAE;oBACJ,KAAK,EAAE;wBACL,MAAM,EAAE,MAAM,CAAC,gBAAgB;4BAC7B,CAAC,CAAC,EAAE,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,EAAE;4BAC/C,CAAC,CAAC,SAAS;wBACb,MAAM,EAAE,MAAM,CAAC,MAAM;qBACtB;iBACF;aACF,CAAC;SACL,EACD,MAAM,CACP;QAED,aAAa,CACX;YACE,IAAI,EAAE,iBAAiB;YACvB,WAAW,EAAE,8BAA8B;YAC3C,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC;gBACtB,MAAM,EAAE,WAAW;gBACnB,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE;aACxB,CAAC;YACF,GAAG,EAAE,CAAC,MAAM,EAAE,EAAE,CACd,MAAM,CAAC,OAAO,CACZ,KAAK,EACL,uBAAuB,kBAAkB,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,EAC5D,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAC1B;SACJ,EACD,MAAM,CACP;QAED,aAAa,CACX;YACE,IAAI,EAAE,sBAAsB;YAC5B,WAAW,EACT,qDAAqD;YACvD,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC;gBACtB,MAAM,EAAE,WAAW;gBACnB,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE;gBACvB,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC;oBACnB,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;oBACxB,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;iBACzB,CAAC;gBACF,MAAM,EAAE,IAAI,CAAC,QAAQ,CACnB,IAAI,CAAC,MAAM,CAAC;oBACV,WAAW,EACT,2DAA2D;iBAC9D,CAAC,CACH;aACF,CAAC;YACF,GAAG,EAAE,CAAC,MAAM,EAAE,EAAE;gBACd,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC;gBACnE,OAAO,MAAM,CAAC,OAAO,CACnB,MAAM,EACN,uBAAuB,kBAAkB,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,IAAI,EAAE,EACpE;oBACE,MAAM,EAAE,MAAM,CAAC,MAAM;oBACrB,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE;iBACrD,CACF,CAAC;YACJ,CAAC;SACF,EACD,MAAM,CACP;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/site.d.ts

@@ -0,0 +1,36 @@
+import type { WixClient } from "../wix-client.js";
+export declare function buildSiteTools(client: WixClient): ({
+    name: string;
+    description: string;
+    label: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        paging: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+            offset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        }>>;
+    }>;
+    execute: (toolCallId: string, params: {
+        paging?: {
+            limit?: number | undefined;
+            offset?: number | undefined;
+        } | undefined;
+    }, signal?: AbortSignal) => Promise<import("@mariozechner/pi-agent-core").AgentToolResult<{
+        status: "ok" | "failed";
+        data?: unknown;
+        error?: string;
+    }>>;
+} | {
+    name: string;
+    description: string;
+    label: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        siteId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>;
+    execute: (toolCallId: string, params: {
+        siteId?: string | undefined;
+    }, signal?: AbortSignal) => Promise<import("@mariozechner/pi-agent-core").AgentToolResult<{
+        status: "ok" | "failed";
+        data?: unknown;
+        error?: string;
+    }>>;
+})[];

package/dist/tools/site.js

@@ -0,0 +1,94 @@
+// Wix Sites + Site Properties tools (read-only).
+//
+// `wix_sites_list` and `wix_site_url_get` are account-scoped — they hit
+// the Site List API and Published Site URLs API and require the
+// `wix-account-id` header (siteScoped: false).
+// `wix_business_info_get` reads from the Site Properties API and is
+// site-scoped.
+//
+// Verified against:
+//   - https://dev.wix.com/docs/rest/account-level/sites/sites/query-sites
+//   - https://dev.wix.com/docs/api-reference/business-management/site-urls/published-site-urls/list-published-site-urls
+//   - https://dev.wix.com/docs/rest/business-management/site-properties/properties/get-site-properties
+import { Type } from "@sinclair/typebox";
+import { defineWixTool } from "./_factory.js";
+export function buildSiteTools(client) {
+    return [
+        defineWixTool({
+            name: "wix_sites_list",
+            description: "Query Wix sites under the configured account. Account-scoped — no site id required. Returns up to 1,000 sites.",
+            parameters: Type.Object({
+                paging: Type.Optional(Type.Object({
+                    limit: Type.Optional(Type.Number({ minimum: 1, maximum: 1000 })),
+                    offset: Type.Optional(Type.Number({ minimum: 0 })),
+                })),
+            }),
+            run: (params) => client.request("POST", "/site-list/v2/sites/query", {
+                siteScoped: false,
+                body: {
+                    query: {
+                        paging: params.paging
+                            ? {
+                                limit: params.paging.limit,
+                                offset: params.paging.offset,
+                            }
+                            : undefined,
+                    },
+                },
+            }),
+        }, client),
+        defineWixTool({
+            name: "wix_site_url_get",
+            description: "Get the published URL, editor URL, publish status and domain status for a site. " +
+                "Backed by the Site List API — needs the `Get Sites List` permission only.",
+            parameters: Type.Object({
+                siteId: Type.Optional(Type.String({
+                    description: "Site UUID. Optional — falls back to defaultSiteId.",
+                })),
+            }),
+            run: async (params) => {
+                // This call is account-scoped, so we cannot rely on the
+                // `wix-site-id` header to inject the default. Read it directly
+                // from the client instead.
+                const targetId = params.siteId ?? client.defaultSiteId;
+                if (!targetId) {
+                    throw new Error("wix_site_url_get requires a siteId. Set defaultSiteId in " +
+                        "the plugin config or pass siteId explicitly.");
+                }
+                const resp = await client.request("POST", "/site-list/v2/sites/query", {
+                    siteScoped: false,
+                    body: {
+                        query: {
+                            filter: { metaSiteId: targetId },
+                            paging: { limit: 1 },
+                        },
+                    },
+                });
+                const site = resp?.sites?.[0];
+                if (!site) {
+                    return { error: `Site ${targetId} not found in this account.` };
+                }
+                return {
+                    siteId: site.id,
+                    displayName: site.displayName,
+                    viewUrl: site.viewUrl,
+                    editUrl: site.editUrl,
+                    published: site.published,
+                    domainConnected: site.domainConnected,
+                    premium: site.premium,
+                };
+            },
+        }, client),
+        defineWixTool({
+            name: "wix_business_info_get",
+            description: "Read site properties (business profile, contact info, address, schedule, locale, time zone) for the configured site.",
+            parameters: Type.Object({
+                siteId: Type.Optional(Type.String()),
+            }),
+            run: (params) => client.request("GET", "/site-properties/v4/properties", {
+                siteId: params.siteId,
+            }),
+        }, client),
+    ];
+}
+//# sourceMappingURL=site.js.map

package/dist/tools/site.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Runtime configuration as it appears in
+ * `plugins.entries.wix-openclaw.config`. All fields are optional — defaults
+ * are applied in {@link resolveConfig}.
+ */
+export interface WixPluginConfig {
+    enabled?: boolean;
+    apiKey?: string;
+    accountId?: string;
+    allowedSiteIds?: string[];
+    defaultSiteId?: string;
+    approvalRequired?: string[];
+    logLevel?: WixLogLevel;
+}
+export type WixLogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Fully resolved plugin configuration after defaults and env substitution.
+ */
+export interface ResolvedWixConfig {
+    enabled: boolean;
+    apiKey: string;
+    accountId: string;
+    allowedSiteIds: string[];
+    defaultSiteId: string;
+    approvalRequired: Set<string>;
+    logLevel: WixLogLevel;
+}
+/**
+ * Options for a single Wix REST request through {@link WixClient.request}.
+ *
+ * - `siteScoped` (default `true`) injects the `wix-site-id` header. Set to
+ *   `false` for account-level endpoints (e.g. `/sites/v1/sites`).
+ * - `siteId` overrides the default site for this call. Must be present in
+ *   `allowedSiteIds`, otherwise the request is rejected before any network
+ *   round trip.
+ * - `query` is appended as URL search params after dropping `undefined`
+ *   values.
+ * - `body` is JSON-encoded automatically.
+ * - `signal` is forwarded to `fetch` for cancellation.
+ */
+export interface WixRequestOptions {
+    siteScoped?: boolean;
+    siteId?: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    signal?: AbortSignal;
+}
+/**
+ * Plugin logger surface — structurally compatible with `PluginLogger` from
+ * the SDK. `debug` is optional because the SDK's contract makes it
+ * optional too; helpers should guard with `logger.debug?.(...)`.
+ */
+export interface WixLogger {
+    debug?: (msg: string) => void;
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+// Type definitions for the wix-openclaw plugin.
+//
+// Kept separate from the entry point so that tools, hooks, and the HTTP
+// client can import them without pulling in the full plugin registration
+// code.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,EAAE;AACF,wEAAwE;AACxE,yEAAyE;AACzE,QAAQ"}

package/dist/wix-client.d.ts

@@ -0,0 +1,66 @@
+import type { ResolvedWixConfig, WixLogger, WixRequestOptions } from "./types.js";
+/**
+ * Thrown when the agent passes a `siteId` that is not in
+ * `config.allowedSiteIds`. The error never reaches the network — the check
+ * is performed before `fetch` is called.
+ */
+export declare class WixSiteNotAllowedError extends Error {
+    constructor(siteId: string, allowed: string[]);
+}
+/**
+ * Thrown for non-retryable HTTP errors (4xx other than 429). The message
+ * includes the response status and the first 300 chars of the body for
+ * easier debugging.
+ */
+export declare class WixApiError extends Error {
+    readonly status: number;
+    readonly bodyPreview: string;
+    constructor(status: number, bodyPreview: string, path: string);
+}
+/**
+ * Authenticated, site-aware Wix REST client.
+ *
+ * One instance per plugin registration — it captures the resolved config
+ * (api key, account id, whitelist) so callers can stay declarative.
+ */
+export declare class WixClient {
+    private readonly config;
+    private readonly logger;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(config: ResolvedWixConfig, logger: WixLogger, options?: {
+        baseUrl?: string;
+        fetchImpl?: typeof fetch;
+    });
+    /**
+     * Public read-only access to the configured default site id. Tools that
+     * make account-scoped calls but still need to target a single site (e.g.
+     * `wix_site_url_get` filtering the sites query by id) can read it here.
+     */
+    get defaultSiteId(): string;
+    /**
+     * Resolve the effective site id for a request and validate it against the
+     * whitelist. Throws {@link WixSiteNotAllowedError} on mismatch. Returns
+     * `null` for non-site-scoped requests.
+     */
+    resolveSiteId(opts: WixRequestOptions): string | null;
+    /**
+     * Build the headers for a single request.
+     *
+     * Wix docs: "you must also include one of the following headers,
+     * depending on the type of call: `wix-account-id` ... or `wix-site-id`".
+     * We pick exactly one — `wix-site-id` for site-scoped calls,
+     * `wix-account-id` for account-scoped calls. Sending both is technically
+     * tolerated by Wix but contradicts the docs and risks future tightening.
+     */
+    private buildHeaders;
+    /**
+     * Perform an authenticated request against the Wix REST API. Retries up
+     * to {@link MAX_RETRIES} times on 429/5xx with exponential backoff.
+     *
+     * Returns the parsed JSON response, or `null` for empty 2xx bodies (e.g.
+     * 204 No Content). Throws {@link WixApiError} on non-retryable failures
+     * and {@link WixSiteNotAllowedError} on whitelist violations.
+     */
+    request<TResponse = unknown>(method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE", path: string, opts?: WixRequestOptions): Promise<TResponse | null>;
+}

package/dist/wix-client.js

@@ -0,0 +1,194 @@
+// Wix REST API HTTP client.
+//
+// Centralises authentication, site whitelist enforcement, retry on 429, and
+// JSON serialisation so individual tools stay thin. Uses Node's native
+// `fetch` (Node 22+) — no axios, no node-fetch.
+//
+// Header conventions (verified against Wix REST docs):
+//   - `Authorization: <apiKey>`        (raw key, NOT prefixed with "Bearer ")
+//   - `wix-account-id: <accountId>`
+//   - `wix-site-id: <siteId>`          (only for site-scoped endpoints)
+const DEFAULT_BASE_URL = "https://www.wixapis.com";
+const RETRY_STATUSES = new Set([429, 502, 503, 504]);
+const MAX_RETRIES = 2;
+const INITIAL_BACKOFF_MS = 500;
+/**
+ * Thrown when the agent passes a `siteId` that is not in
+ * `config.allowedSiteIds`. The error never reaches the network — the check
+ * is performed before `fetch` is called.
+ */
+export class WixSiteNotAllowedError extends Error {
+    constructor(siteId, allowed) {
+        super(`Wix site "${siteId}" is not in the allowed list ` +
+            `(${allowed.length === 0 ? "<empty>" : allowed.join(", ")}). ` +
+            `Add it to plugins.entries.wix-openclaw.config.allowedSiteIds to enable.`);
+        this.name = "WixSiteNotAllowedError";
+    }
+}
+/**
+ * Thrown for non-retryable HTTP errors (4xx other than 429). The message
+ * includes the response status and the first 300 chars of the body for
+ * easier debugging.
+ */
+export class WixApiError extends Error {
+    status;
+    bodyPreview;
+    constructor(status, bodyPreview, path) {
+        super(`Wix API ${status} on ${path}: ${bodyPreview.slice(0, 300)}`);
+        this.name = "WixApiError";
+        this.status = status;
+        this.bodyPreview = bodyPreview;
+    }
+}
+/**
+ * Sleep for `ms` milliseconds. Extracted for testability.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Convert a record of query values to a URL-encoded search string. Drops
+ * `undefined` values and serialises booleans/numbers via `String()`.
+ */
+function buildQueryString(query) {
+    if (!query)
+        return "";
+    const entries = Object.entries(query).filter(([, v]) => v !== undefined && v !== null);
+    if (entries.length === 0)
+        return "";
+    const params = new URLSearchParams();
+    for (const [k, v] of entries) {
+        params.set(k, String(v));
+    }
+    return `?${params.toString()}`;
+}
+/**
+ * Authenticated, site-aware Wix REST client.
+ *
+ * One instance per plugin registration — it captures the resolved config
+ * (api key, account id, whitelist) so callers can stay declarative.
+ */
+export class WixClient {
+    config;
+    logger;
+    baseUrl;
+    fetchImpl;
+    constructor(config, logger, options = {}) {
+        this.config = config;
+        this.logger = logger;
+        this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    /**
+     * Public read-only access to the configured default site id. Tools that
+     * make account-scoped calls but still need to target a single site (e.g.
+     * `wix_site_url_get` filtering the sites query by id) can read it here.
+     */
+    get defaultSiteId() {
+        return this.config.defaultSiteId;
+    }
+    /**
+     * Resolve the effective site id for a request and validate it against the
+     * whitelist. Throws {@link WixSiteNotAllowedError} on mismatch. Returns
+     * `null` for non-site-scoped requests.
+     */
+    resolveSiteId(opts) {
+        if (opts.siteScoped === false)
+            return null;
+        const candidate = opts.siteId ?? this.config.defaultSiteId;
+        if (!candidate) {
+            throw new Error("Wix request requires a site id but none is configured. " +
+                "Set `defaultSiteId` in the plugin config or pass `siteId` " +
+                "explicitly in the tool call.");
+        }
+        if (!this.config.allowedSiteIds.includes(candidate)) {
+            throw new WixSiteNotAllowedError(candidate, this.config.allowedSiteIds);
+        }
+        return candidate;
+    }
+    /**
+     * Build the headers for a single request.
+     *
+     * Wix docs: "you must also include one of the following headers,
+     * depending on the type of call: `wix-account-id` ... or `wix-site-id`".
+     * We pick exactly one — `wix-site-id` for site-scoped calls,
+     * `wix-account-id` for account-scoped calls. Sending both is technically
+     * tolerated by Wix but contradicts the docs and risks future tightening.
+     */
+    buildHeaders(siteId) {
+        const headers = {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            Authorization: this.config.apiKey,
+        };
+        if (siteId) {
+            headers["wix-site-id"] = siteId;
+        }
+        else if (this.config.accountId) {
+            headers["wix-account-id"] = this.config.accountId;
+        }
+        return headers;
+    }
+    /**
+     * Perform an authenticated request against the Wix REST API. Retries up
+     * to {@link MAX_RETRIES} times on 429/5xx with exponential backoff.
+     *
+     * Returns the parsed JSON response, or `null` for empty 2xx bodies (e.g.
+     * 204 No Content). Throws {@link WixApiError} on non-retryable failures
+     * and {@link WixSiteNotAllowedError} on whitelist violations.
+     */
+    async request(method, path, opts = {}) {
+        const siteId = this.resolveSiteId(opts);
+        const url = this.baseUrl + path + buildQueryString(opts.query);
+        const headers = this.buildHeaders(siteId);
+        const body = opts.body !== undefined ? JSON.stringify(opts.body) : undefined;
+        if (this.config.logLevel === "debug") {
+            this.logger.debug?.(`wix: ${method} ${path}${siteId ? ` site=${siteId.slice(0, 8)}` : ""}` +
+                (body ? ` body=${body.slice(0, 200)}` : ""));
+        }
+        let attempt = 0;
+        let lastErrorBody = "";
+        let lastStatus = 0;
+        while (attempt <= MAX_RETRIES) {
+            const resp = await this.fetchImpl(url, {
+                method,
+                headers,
+                body,
+                signal: opts.signal,
+            });
+            if (resp.ok) {
+                // 204 No Content or any empty body — return null so callers can
+                // distinguish "succeeded with no payload" from "succeeded with
+                // empty object".
+                const text = await resp.text();
+                if (!text)
+                    return null;
+                try {
+                    return JSON.parse(text);
+                }
+                catch {
+                    // Wix sometimes returns text/plain for trivial endpoints — return
+                    // it raw rather than crashing.
+                    return text;
+                }
+            }
+            lastStatus = resp.status;
+            lastErrorBody = await resp.text();
+            if (!RETRY_STATUSES.has(resp.status) || attempt === MAX_RETRIES) {
+                throw new WixApiError(resp.status, lastErrorBody, path);
+            }
+            // Honour `Retry-After` if present, else exponential backoff.
+            const retryAfter = resp.headers.get("retry-after");
+            const backoff = retryAfter
+                ? parseInt(retryAfter, 10) * 1000
+                : INITIAL_BACKOFF_MS * Math.pow(2, attempt);
+            this.logger.warn(`wix: ${method} ${path} → ${resp.status}, retrying in ${backoff}ms (attempt ${attempt + 1}/${MAX_RETRIES})`);
+            await sleep(backoff);
+            attempt++;
+        }
+        // Defensive: should be unreachable since the loop either returns or
+        // throws on the last attempt.
+        throw new WixApiError(lastStatus, lastErrorBody, path);
+    }
+}
+//# sourceMappingURL=wix-client.js.map

package/dist/wix-client.js.map

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

package/openclaw.plugin.json

@@ -0,0 +1,95 @@
+{
+  "id": "wix-openclaw",
+  "name": "Wix",
+  "description": "Wix REST API plugin for OpenClaw — manage blog, CMS data, forms, bookings, contacts, events, FAQ on a single Wix site with site_id whitelist and approval gating on destructive ops",
+  "version": "0.1.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Master switch — disables all Wix tools when false"
+      },
+      "apiKey": {
+        "type": "string",
+        "description": "Wix API key sent raw as the `Authorization` header (NOT prefixed with 'Bearer '). Supports ${ENV_VAR} substitution."
+      },
+      "accountId": {
+        "type": "string",
+        "description": "Wix account UUID sent as the `wix-account-id` header. Supports ${ENV_VAR} substitution."
+      },
+      "allowedSiteIds": {
+        "type": "array",
+        "items": { "type": "string" },
+        "default": [],
+        "description": "Whitelist of Wix site UUIDs the plugin is allowed to operate on. Any tool call referencing a site outside this list is rejected before any HTTP request is made."
+      },
+      "defaultSiteId": {
+        "type": "string",
+        "description": "Default Wix site UUID injected as the `wix-site-id` header when a tool does not explicitly provide one. Must be present in `allowedSiteIds`. Supports ${ENV_VAR} substitution."
+      },
+      "approvalRequired": {
+        "type": "array",
+        "items": { "type": "string" },
+        "default": [
+          "wix_blog_publish_draft",
+          "wix_blog_unpublish",
+          "wix_blog_delete_draft",
+          "wix_data_remove_item",
+          "wix_contacts_delete",
+          "wix_bookings_reschedule",
+          "wix_bookings_cancel",
+          "wix_reviews_moderate",
+          "wix_faq_delete_question"
+        ],
+        "description": "Tool names that trigger an approval prompt via the `before_tool_call` hook before being executed. Defaults to every destructive operation."
+      },
+      "logLevel": {
+        "type": "string",
+        "enum": ["debug", "info", "warn", "error"],
+        "default": "info",
+        "description": "Plugin log verbosity. `debug` includes request bodies (be mindful of PII)."
+      }
+    },
+    "required": []
+  },
+  "uiHints": {
+    "enabled": {
+      "label": "Enable Wix tools",
+      "help": "Master switch — turn off to fully disable all wix_* tools without uninstalling"
+    },
+    "apiKey": {
+      "label": "Wix API Key",
+      "placeholder": "${WIX_API_KEY}",
+      "sensitive": true,
+      "help": "Wix REST API key. Sent raw in the `Authorization` header (no `Bearer ` prefix)."
+    },
+    "accountId": {
+      "label": "Wix Account ID",
+      "placeholder": "${WIX_ACCOUNT_ID}",
+      "sensitive": true,
+      "help": "Wix account UUID, sent as `wix-account-id` on every request"
+    },
+    "allowedSiteIds": {
+      "label": "Allowed Site IDs",
+      "help": "Whitelist of Wix site UUIDs. The plugin refuses to call any site outside this list."
+    },
+    "defaultSiteId": {
+      "label": "Default Site ID",
+      "placeholder": "${WIX_SITE_ID_ATARAXIS}",
+      "help": "Site UUID used when a tool does not specify one. Must appear in allowedSiteIds."
+    },
+    "approvalRequired": {
+      "label": "Tools requiring approval",
+      "advanced": true,
+      "help": "Tool names that trigger a `before_tool_call` approval prompt. Defaults cover every destructive operation."
+    },
+    "logLevel": {
+      "label": "Log level",
+      "advanced": true,
+      "help": "info (default), debug includes request bodies"
+    }
+  }
+}