@lacneu/wix-openclaw 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -7,6 +7,102 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-05-03
+
+### Fixed — OpenClaw 2026.5.x compatibility
+
+OpenClaw 2026.5.2 introduced a manifest contract for plugin tool
+ownership: tools registered via `api.registerTool(...)` are
+**rejected at runtime** with the error
+`plugin must declare contracts.tools before registering agent tools`
+when the plugin manifest does not declare them.
+
+Without this release, `@lacneu/wix-openclaw` loads on 2026.5.x but
+all 50 of its `wix_*` tools are silently rejected at registration —
+the plugin runs hooks but exposes 0 tools to the agent.
+
+### Added — `contracts.tools` (50 entries)
+
+`openclaw.plugin.json` now declares every tool the plugin owns
+under `contracts.tools` as a flat array of strings. Mirrors the 50
+tools registered by `registerWixPlugin(api)`:
+
+- 11 blog tools (drafts CRUD, publish/unpublish, posts, categories, tags)
+- 6 bookings (services list, query, create, get, cancel, reschedule)
+- 1 business info
+- 6 contacts CRUD + label + query
+- 6 wix data CRUD (collections, items)
+- 1 design brief
+- 3 events (list, get, list_guests)
+- 5 FAQ (list categories/questions, create/update/delete question)
+- 2 forms (list submissions, get submission)
+- 2 media (list, upload)
+- 2 multilingual (list languages, list schemas)
+- 3 reviews (list, get, moderate)
+- 2 sites (list, url get)
+
+### Added — `activation.onStartup: true`
+
+Per the OpenClaw 2026.5.x manifest spec, external plugins should
+declare an explicit activation policy. `onStartup: true` ensures
+the plugin is loaded at gateway startup so its tools are
+discoverable when the agent resolves its tool inventory.
+
+### Added — `toolMetadata._default.configSignals`
+
+Tells OpenClaw's tool descriptor planner that every tool in this
+plugin requires both `apiKey` and `accountId` to be configured at
+`plugins.entries.wix-openclaw.config`. The platform skips loading
+the plugin runtime when these are missing — cheap availability
+check at reply startup.
+
+### Changed — compat aligned to 2026.5.0
+
+- `package.json#openclaw.compat`:
+  `pluginApi: ">=2026.4.0"` → `">=2026.5.0"`,
+  `minGatewayVersion: "2026.4.0"` → `"2026.5.0"`.
+- `peerDependencies.openclaw` and `devDependencies.openclaw`:
+  `">=2026.4.0"` → `">=2026.5.0"`.
+
+### Migration
+
+For instance owners on `@lacneu/wix-openclaw@0.2.1` running
+OpenClaw 2026.5.x:
+
+1. `openclaw plugins install @lacneu/wix-openclaw@0.2.2 --force`
+2. Restart the gateway container.
+3. Verify in the boot log:
+   `wix-openclaw: ready — 50 tool(s) registered`.
+4. Verify with `openclaw plugins inspect wix-openclaw --runtime --json`:
+   `"toolNames"` should list the 50 `wix_*` tools.
+
+### Note on agent tool inventory bug
+
+OpenClaw 2026.5.2 has a separate regression (issue #76598) that
+prevents plugin tools from appearing in the per-agent tool
+inventory even when the plugin is correctly installed and registered.
+Fixed in commit `a3b94f39109d` on 2026-05-03 — pending in 2026.5.3.
+Symptom: `tools.alsoAllow` listing the wix tools logs as
+`unknown entries` despite the plugin being loaded. No client-side
+workaround; await the upstream release.
+
+## [0.2.1] - 2026-04-29
+
+### Added
+- `examples/recommended-skill.md` — companion skill template that
+  operators can copy into agent workspaces
+  (`~/.openclaw/workspace-<agent>/skills/wix/SKILL.md`) to give the LLM
+  business context, recipes and guardrails for the plugin. Skills are
+  not part of the OpenClaw plugin SDK by design — they live in the
+  workspace — so the template ships as a static file and gets included
+  in the npm package via the `files` array.
+
+### Changed
+- Added `examples/` to the `files` array of `package.json` so the
+  template is shipped with the npm publish.
+- README now has a "Recommended companion skill" section linking to
+  the template.
+
 ## [0.2.0] - 2026-04-29
 
 ### Added

package/README.md

@@ -498,6 +498,31 @@ use an empty array to disable gating entirely (not recommended in production).
 
 ---
 
+## Recommended companion skill
+
+OpenClaw plugins ship code (tools, hooks); they do **not** ship skills.
+Skills live in agent workspaces and carry the business context that makes
+the LLM use the tools correctly (audience, tone, recipes, guardrails).
+
+To get an agent up and running with this plugin, copy
+[`examples/recommended-skill.md`](examples/recommended-skill.md) into the
+target workspace at `~/.openclaw/workspace-<agent>/skills/wix/SKILL.md`,
+then replace the `<PLACEHOLDER>` values with your own (organisation name,
+domain, contributors, tone). Duplicate the file for each agent that
+should benefit from the skill.
+
+The template covers:
+
+- Conversational triggers (encoded in the `description` frontmatter as
+  per OpenClaw skill convention)
+- 5 usage recipes (publish article, list real drafts, read leads,
+  manage bookings, design request)
+- Behavioural guardrails (approval recap before publish, app-not-installed
+  handling, PII rules)
+- Tool mapping (short reference; the README is the source of truth)
+
+---
+
 ## Development
 
 ### Project layout

package/examples/recommended-skill.md

@@ -0,0 +1,188 @@
+---
+name: wix
+description: Site officiel <YOUR_SITE_NAME> (<your-site.com>) sur Wix — articles de blog, brouillons, médias, formulaires/leads, RDV, services, FAQ, avis. Utilise ce skill quand l'utilisateur dit "publier un article", "brouillon de blog", "ajouter une image au site", "voir les leads", "soumissions de formulaire", "modifier les services", "répondre à un avis", "FAQ", "<your-site.com>", "site officiel".
+user-invocable: true
+---
+
+# Wix — Recommended skill template
+
+> **This is a template** — copy it to your workspace
+> (`~/.openclaw/workspace-<agent>/skills/wix/SKILL.md`), then replace every
+> `<PLACEHOLDER>` with values specific to your site and organisation.
+> Skills are loaded per workspace, so duplicate the file for each agent
+> that should benefit from it.
+
+This skill gives an OpenClaw agent the business context, recipes and
+behavioural guardrails it needs to operate the
+[`@lacneu/wix-openclaw`](https://www.npmjs.com/package/@lacneu/wix-openclaw)
+plugin correctly. The plugin itself ships generic tools; this skill wraps
+them into your specific site, voice and audience.
+
+## Business context (replace with yours)
+
+`<ORGANIZATION>` is `<short pitch — what you do, who you serve>`. The
+public site `<your-site.com>` runs on **Wix Editor classic** (the plugin
+also targets Wix Studio sites — adjust if relevant). It is locked at the
+plugin level to a single `siteId` (set in `allowedSiteIds`).
+
+**Tone for site content** — `<sober / playful / formal / informal>`,
+`<language>`, `<audience>`. Preserve the voice of the human contributors
+when they dictate or proofread; do not normalize their phrasing.
+
+**Site language** — `<fr / en / ...>`.
+
+**Human contributors / collaborators** — list them with their role:
+
+- `<Name 1>` — `<role>`
+- `<Name 2>` — `<role>`
+- `<...>`
+
+## Conversational triggers (when this skill is relevant)
+
+- "Publish an article about X" / "Publier un article sur X"
+- "Prepare a draft about Y" / "Prépare un brouillon sur Y"
+- "Add this image to the site" / "Ajoute cette image au site"
+- "How many leads this week?" / "Combien de leads cette semaine ?"
+- "Update this service" / "Mets à jour ce service"
+- "What appointments today?" / "Quels RDV aujourd'hui ?"
+- "Reply to this review" / "Réponds à cet avis"
+- "Add this FAQ entry" / "Ajoute cette question à la FAQ"
+- Any mention of `<your-site.com>`, "Wix", "official site", "site officiel"
+
+## When this skill does NOT apply
+
+The plugin **cannot** modify the site's design (Wix Editor classic does
+not expose this through any public API):
+
+- Colours, typography, page layout
+- Individual graphic components (buttons, sections, backgrounds)
+- Page structure (navigation, header, footer)
+
+Pure-design requests should be redirected to the **(e) Design request**
+recipe below.
+
+## Usage patterns
+
+### (a) Draft and publish a blog article
+
+1. **Cover image** — if the user provides a URL (or asks for an
+   AI-generated image): use `wix_media_upload` to push it into Wix Media
+   Manager. Capture the returned `id` for step 2.
+2. **Create draft** — `wix_blog_create_draft` with:
+   - `title`
+   - `richContent` (Wix Ricos format — Wix Blog's native rich-text)
+   - `coverMedia.imageId` from step 1
+   - `tagIds`, `categoryIds` if appropriate (look them up first via
+     `wix_blog_list_tags` / `wix_blog_list_categories`)
+3. **User-facing recap** — show this in plain business language, NEVER
+   mention tool names or HTTP details:
+
+   > Draft ready:
+   > **Title**: <title>
+   > **Lead paragraph**: <first ~80 words>
+   > **Cover image**: <displayName or short description>
+   > **Tags**: <readable list>
+   >
+   > Reply `publish` to go live, or tell me what to adjust.
+
+4. **Publish on explicit confirmation only** — `wix_blog_publish_draft`
+   with the draft id. OpenClaw approval-gates this call; the recap above
+   helps the human decide knowingly.
+
+### (b) List actual drafts (not the published-post snapshots)
+
+Wix Blog v3 quirk: `wix_blog_list_drafts` without filter returns mirror
+drafts for already-published posts (auto-snapshots).
+
+To see only **drafts being actively written**: pass `status: "UNPUBLISHED"`.
+Other useful values: `IN_REVIEW`, `SCHEDULED`.
+
+If the user asks "how many drafts do I have?" and the unfiltered count
+looks unexpectedly large, explain in plain words ("some are mirror
+copies of published articles") and re-query with `status: "UNPUBLISHED"`.
+
+### (c) Read form submissions / leads
+
+- `wix_forms_list_submissions` with:
+  - `namespace: "wix.form_app.form"` (default — keep unless using a
+    custom forms app)
+  - `paging.limit: 20` (or more)
+  - `sort` to put recent first when supported
+
+Present leads in business language (name, email, message, date). Do not
+expose technical `id`s.
+
+### (d) Manage bookings
+
+- `wix_bookings_services_list` — list bookable services
+- `wix_bookings_query_bookings` with a `startDate` filter (e.g.
+  `$gt: "2026-01-01T00:00:00Z"`) for upcoming bookings
+- `wix_bookings_cancel` / `wix_bookings_reschedule` — both gated; ask for
+  explicit confirmation before invoking.
+
+### (e) Design request (assumed limitation)
+
+If the user asks for a visual change (colour, layout, styled button…),
+respond along these lines:
+
+> I can't change the site's visual components directly (Wix Editor
+> classic doesn't expose that via API). I can however prepare a design
+> brief (palette, typography, suggested copy) and generate a mockup
+> image — you'll then apply it manually in the Wix editor. Want to go
+> that route?
+
+If yes: use `wix_design_brief` to structure the brief, then
+`image_generate` (or your preferred image-gen tool) for the mockup.
+
+## Behavioural guardrails
+
+1. **Before any publication** (`wix_blog_publish_draft`, modifying
+   `wix_bookings_*`, public review replies) — always show a business
+   recap and wait for explicit confirmation. OpenClaw gates the HTTP
+   call already; the recap helps the human decide.
+2. **"App not installed" / `428` / `404` / "Wix Code not enabled"** — do
+   not insist or retry. Explain in plain terms that the relevant Wix app
+   must be activated in the
+   [Wix App Market](https://www.wix.com/app-market). Apps concerned: Wix
+   Events, Wix Reviews, Wix FAQ, Wix Multilingual, Velo (for
+   `wix_data_*`).
+3. **Site whitelist** — the plugin is locked to `<your_site_id>`. Any
+   other `siteId` is rejected before reaching Wix. Do not try to bypass.
+4. **PII / sensitive data** — form submissions and contacts contain
+   names, emails, phone numbers, sometimes confidential messages. **Do
+   not log, do not embed in long-term knowledge stores** (vector DB,
+   shared memory) without explicit user consent. Surface only what is
+   asked.
+
+## Available tools (short mapping)
+
+- **Blog** — drafts (create, list, update, publish), posts, categories,
+  tags
+- **Media** — upload, list
+- **Site** — `sites_list`, `url_get`, `business_info`
+- **CMS / Wix Data** — collections, items CRUD (requires Velo enabled)
+- **Forms** — `submissions` (list, get)
+- **Contacts** — CRUD + labels + search
+- **Bookings** — services, bookings (CRUD, cancel, reschedule)
+- **Events** (requires Wix Events app)
+- **Reviews** (requires Wix Reviews app) — moderation, replies
+- **FAQ** (requires Wix FAQ app)
+- **Multilingual** (requires Wix Multilingual app)
+- **Design** — `wix_design_brief`
+
+Full reference and live signatures:
+<https://github.com/OlivierNeu/wix-openclaw-plugin#tools>
+
+## Operating rules
+
+1. **Voice of `<ORGANIZATION>` first** — preserve phrasings dictated by
+   `<contributors>`, do not normalize them.
+2. **No technical jargon to end-users** — never expose tool names
+   (`wix_*`), Wix object ids, or HTTP error codes. Rephrase in business
+   terms.
+3. **Explicit confirmation** before any public-facing publication or
+   modification.
+4. **Single source of truth** — the official site at `<your-site.com>`.
+   Do not attempt other `siteId`s.
+5. **Unexpected behaviour** — escalate to the operator (admin agent /
+   maintainer) in a separate session, not in the user-facing channel.

package/openclaw.plugin.json

@@ -2,7 +2,74 @@
   "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.2.0",
+  "version": "0.2.2",
+  "activation": {
+    "onStartup": true
+  },
+  "contracts": {
+    "tools": [
+      "wix_blog_create_draft",
+      "wix_blog_delete_draft",
+      "wix_blog_get_draft",
+      "wix_blog_get_post",
+      "wix_blog_list_categories",
+      "wix_blog_list_drafts",
+      "wix_blog_list_published",
+      "wix_blog_list_tags",
+      "wix_blog_publish_draft",
+      "wix_blog_unpublish",
+      "wix_blog_update_draft",
+      "wix_bookings_cancel",
+      "wix_bookings_create",
+      "wix_bookings_get_booking",
+      "wix_bookings_query_bookings",
+      "wix_bookings_reschedule",
+      "wix_bookings_services_list",
+      "wix_business_info_get",
+      "wix_contacts_create",
+      "wix_contacts_delete",
+      "wix_contacts_get",
+      "wix_contacts_label_add",
+      "wix_contacts_query",
+      "wix_contacts_update",
+      "wix_data_get_item",
+      "wix_data_insert_item",
+      "wix_data_list_collections",
+      "wix_data_query_items",
+      "wix_data_remove_item",
+      "wix_data_update_item",
+      "wix_design_brief",
+      "wix_events_get",
+      "wix_events_list",
+      "wix_events_list_guests",
+      "wix_faq_create_question",
+      "wix_faq_delete_question",
+      "wix_faq_list_categories",
+      "wix_faq_list_questions",
+      "wix_faq_update_question",
+      "wix_forms_get_submission",
+      "wix_forms_list_submissions",
+      "wix_media_list",
+      "wix_media_upload",
+      "wix_multilingual_list_languages",
+      "wix_multilingual_list_schemas",
+      "wix_reviews_get",
+      "wix_reviews_list",
+      "wix_reviews_moderate",
+      "wix_site_url_get",
+      "wix_sites_list"
+    ]
+  },
+  "toolMetadata": {
+    "_default": {
+      "configSignals": [
+        {
+          "rootPath": "plugins.entries.wix-openclaw.config",
+          "required": ["apiKey", "accountId"]
+        }
+      ]
+    }
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lacneu/wix-openclaw",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "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",
   "license": "MIT",
@@ -29,6 +29,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "examples",
     "openclaw.plugin.json",
     "README.md",
     "CHANGELOG.md",
@@ -51,8 +52,8 @@
       "./dist/index.js"
     ],
     "compat": {
-      "pluginApi": ">=2026.4.0",
-      "minGatewayVersion": "2026.4.0"
+      "pluginApi": ">=2026.5.0",
+      "minGatewayVersion": "2026.5.0"
     }
   },
   "dependencies": {
@@ -60,11 +61,11 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "openclaw": ">=2026.4.0",
+    "openclaw": ">=2026.5.0",
     "typescript": "^5.6.0"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.4.0"
+    "openclaw": ">=2026.5.0"
   },
   "peerDependenciesMeta": {
     "openclaw": {