@lacneu/wix-openclaw 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+- `wix_site_url_get` now reads `viewUrl` from the Site List API response
+  rather than calling the legacy `/urls-server/v2/published-site-urls`
+  endpoint, which returns 403 for headless API keys even when the
+  "Read Site URLs" permission is granted. The "Read Site URLs"
+  permission is no longer required.
+- Forms submission tools migrated from `/form-submissions/v1/...` to
+  `/form-submission-service/v4/submissions/namespace/query`. The query
+  filter now uses the canonical `{ namespace: { $eq: "..." } }` shape
+  enforced by Wix.
+- Multilingual tools migrated from `/multilingual/v1/sitetranslatables/...`
+  to the current `/locales/v2/locale/query` and
+  `/translation-schema/v1/schemas/site` endpoints. `wix_multilingual_get_translation`
+  removed in favour of `wix_multilingual_list_schemas`.
+- Sites + business info endpoints corrected:
+  `wix_sites_list` → `POST /site-list/v2/sites/query`,
+  `wix_business_info_get` → `GET /site-properties/v4/properties`.
+- Documented the per-app installation requirements that gate certain
+  tool families (Velo for `wix_data_*`, Wix Events / Reviews / FAQ /
+  Multilingual for their respective tool groups).
+
+### Added
+- `scripts/smoke-test.mjs` + `npm run smoke-test` — live read-only
+  endpoint validation against a real Wix account using `.env.smoketest`
+  credentials. Generates `smoke-test-report.md`.
+
+## [0.1.0] - 2026-04-28
+
+### Added
+- Initial release of `@lacneu/wix-openclaw`.
+- ~50 tools spanning Wix Blog, Site Media, Sites, CMS Data, Forms, Contacts,
+  Bookings, Events, Reviews, FAQ, and Multilingual (read-only).
+- `wix_design_brief` tool — pure prompt structurer that turns a loose textual
+  brief into a markdown artefact (palette, typography, recommended sections,
+  copy starters, prompts for image-generation tools). Does not call the Wix API.
+- Authenticated `WixClient` with the Wix-specific header convention
+  (`Authorization: <key>` raw — no `Bearer ` prefix), automatic injection of
+  `wix-account-id` and `wix-site-id`, retry on 429/5xx with exponential
+  backoff, and JSON serialisation.
+- **Site whitelist**: every site-scoped call is checked against
+  `allowedSiteIds` before any HTTP request is built. Calls to a site outside
+  the list throw `WixSiteNotAllowedError` and surface as a tool failure.
+- **Approval gating** via the `before_tool_call` hook: every destructive
+  operation (publish, delete, cancel, moderate) returns a `requireApproval`
+  directive with severity `critical`, 10-minute timeout, and `deny` as the
+  timeout fallback.
+- TypeScript build with strict mode (`noImplicitAny`, `noUnusedLocals`,
+  `noUnusedParameters`, `noImplicitReturns`, `noFallthroughCasesInSwitch`).
+- TypeBox-based parameter schemas — the agent sees fully typed params
+  consistent with the rest of the OpenClaw tool surface.
+- Test suite (`node:test`) covering the security-critical paths:
+  whitelist enforcement, header injection, 429 retry, approval matching,
+  and a smoke test on two blog tools.
+- CI workflow on Node.js 22 + 24.
+- Release workflow using **npm Trusted Publishing (OIDC)** — no `NPM_TOKEN`
+  secret required, provenance attached automatically.
+
+[Unreleased]: https://github.com/OlivierNeu/wix-openclaw-plugin/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/OlivierNeu/wix-openclaw-plugin/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OlivierNeu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,483 @@
+# wix-openclaw-plugin
+
+> **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 every
+> destructive operation.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![OpenClaw](https://img.shields.io/badge/OpenClaw-%E2%89%A5v2026.4.0-blue)](https://github.com/openclaw/openclaw)
+[![npm version](https://img.shields.io/npm/v/@lacneu/wix-openclaw.svg)](https://www.npmjs.com/package/@lacneu/wix-openclaw)
+
+---
+
+## Overview
+
+`wix-openclaw` is an OpenClaw plugin that lets your agent operate a Wix site
+through the official Wix REST API. It registers ~50 tools split across a dozen
+Wix products (Blog, CMS Data, Forms, Bookings, Contacts, Events, Reviews, FAQ,
+Multilingual, Sites, Site Media), plus a `wix_design_brief` helper that turns
+loose textual briefs into structured markdown artefacts.
+
+Every tool funnels through a single authenticated HTTP client that:
+
+1. Injects the correct headers (`Authorization`, `wix-account-id`,
+   `wix-site-id`)
+2. Refuses any call to a site UUID not in `allowedSiteIds` — **before** the
+   network round trip
+3. Retries on 429/5xx with exponential backoff
+4. Maps non-retryable errors to clean tool failures (`WixApiError`)
+
+Destructive operations (publish, delete, cancel, moderate) trigger a
+`before_tool_call` approval prompt that the operator must accept in the
+Control UI / Telegram before the call goes through.
+
+---
+
+## Why a whitelist?
+
+Wix accounts can host many sites. The `wix-site-id` header is the only thing
+between an agent and "we just published a draft on the wrong site".
+
+`allowedSiteIds` is enforced in the client itself, **before** any HTTP request
+is built. If the LLM hallucinates a site UUID, the call fails locally — no
+traffic is generated and no Wix logs are polluted. This is the same reason
+`google_workspace` enforces a domain allowlist: prompt injection should never
+reach the wrong tenant.
+
+---
+
+## Installation
+
+### Requirements
+
+- OpenClaw `>= v2026.4.0`
+- A Wix REST API key with the **minimum required permissions** (see
+  [Wix API Key permissions](#wix-api-key-permissions) below)
+- The Wix account UUID and at least one site UUID
+
+### Install via OpenClaw CLI
+
+```bash
+openclaw plugins install @lacneu/wix-openclaw
+openclaw plugins inspect @lacneu/wix-openclaw
+```
+
+### Configuration
+
+Add the entry to your `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "allow": ["wix-openclaw", "openclaw-knowledge", "telegram"],
+    "entries": {
+      "wix-openclaw": {
+        "enabled": true,
+        "config": {
+          "apiKey": "${WIX_API_KEY}",
+          "accountId": "${WIX_ACCOUNT_ID}",
+          "allowedSiteIds": ["${WIX_SITE_ID_ATARAXIS}"],
+          "defaultSiteId": "${WIX_SITE_ID_ATARAXIS}",
+          "logLevel": "info"
+        }
+      }
+    }
+  }
+}
+```
+
+Add the secrets to your `.env`:
+
+```dotenv
+WIX_API_KEY=<your-wix-api-key>
+WIX_ACCOUNT_ID=<your-wix-account-uuid>
+WIX_SITE_ID_ATARAXIS=<your-target-site-uuid>
+```
+
+Restart the gateway:
+
+```bash
+openclaw gateway restart
+```
+
+---
+
+## Configuration reference
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | boolean | `true` | Master switch — disables all `wix_*` tools when false |
+| `apiKey` | string | — | Wix REST API key. Sent **raw** in `Authorization` (no `Bearer ` prefix). Supports `${ENV_VAR}` |
+| `accountId` | string | — | Wix account UUID. Sent as `wix-account-id`. Supports `${ENV_VAR}` |
+| `allowedSiteIds` | string[] | `[]` | Whitelist of Wix site UUIDs. Calls to other sites are rejected before the network round trip |
+| `defaultSiteId` | string | first of `allowedSiteIds` | Site UUID injected when a tool does not explicitly specify one |
+| `approvalRequired` | string[] | (every destructive tool) | Tool names that trigger a `before_tool_call` approval prompt |
+| `logLevel` | enum | `info` | `debug` / `info` / `warn` / `error`. `debug` logs request bodies (mind PII) |
+
+---
+
+## Authentication header convention
+
+Wix REST APIs use a slightly non-standard auth pattern: the API key goes raw
+in the `Authorization` header — **without** the `Bearer ` prefix.
+
+```http
+Authorization: <wix-api-key>
+wix-account-id: <wix-account-uuid>
+wix-site-id: <wix-site-uuid>
+```
+
+This plugin handles that for you; you only need to provide the three values.
+
+---
+
+## Wix API Key permissions
+
+A Wix REST API key has **account-wide reach** by design — it can target any
+of the sites under the Wix account it belongs to. Wix does **not** let you
+scope a key to a single site at creation time. The plugin compensates with
+its `allowedSiteIds` whitelist (cf. [Why a whitelist?](#why-a-whitelist)),
+but the API key permission set itself remains your most important defense
+against accidental — or malicious — over-reach. Treat it as a
+least-privilege configuration exercise.
+
+> **Where to configure them**
+> Wix Dashboard → **Settings** → **Headless Settings** → **API Keys** →
+> click your key → **Edit API Key** → **Permissions**.
+
+### Minimum required (for the V1 toolset shipped here)
+
+Tick **only** the following permissions on your API key. Everything else
+should stay unticked.
+
+#### Basic permissions
+- [x] **Get Sites List** — required to discover and validate site UUIDs
+
+#### Site permissions
+- [x] **Wix Blog** — drafts, posts, categories, tags
+- [x] **Manage Site Media** — upload images for blog cover & rich content
+- [x] **Business Info** — name, address, hours, timezone
+- [x] **Wix Data** — custom CMS collections (read & write)
+- [x] **Wix Forms** — read submitted forms
+- [x] **Manage Form Submissions** — read leads / contact requests
+- [x] **Wix Contacts & Members** — CRM contacts + members
+- [x] **Wix Bookings** — services, sessions, bookings
+- [x] **Wix Events** — events, RSVPs, guests
+- [x] **Wix Reviews** — list & moderate reviews
+- [x] **Manage FAQ** — FAQ categories and questions
+- [x] **Multilingual Translation Schema Read** — read site translations
+- [x] **List Marketing Tags** — read-only marketing/analytics tags
+
+### Optional, depending on the business model
+
+Tick these only if the corresponding Wix product is actually in use on
+the target site:
+
+- [ ] **Pricing Plans** — if you sell subscription packages
+- [ ] **Wix Stores** + **Wix eCommerce** — if you sell physical/digital
+  products. Without these, the `wix_*` tools that touch e-commerce
+  resources (none in V1) cannot run.
+
+### Permissions to **never** tick (defense in depth)
+
+The plugin does **not** need any of the following, and granting them
+needlessly amplifies the blast radius if the key ever leaks. Audit your
+key periodically and keep these unticked:
+
+| Permission | Why it's dangerous |
+|---|---|
+| `Manage Sites` | Allows site **deletion** |
+| `Manage Domains` | Allows transferring your domain away |
+| `Publish Metasite` | Allows un-publishing the entire site |
+| `Manage Embedded Scripts` | Allows arbitrary JavaScript injection on every page |
+| `OAuth Apps` | Allows creating persistent OAuth apps that survive key revocation |
+| `Manage Functions` / `Manage Your App` | Arbitrary server-side code |
+| `Connect Wix Payments Account` / `Wix Payments` / `Wix Cashier` | Reroutes customer payments |
+| `Manage Email Marketing` / `Manage Email Subscriptions` | Mass-email spam & subscription tampering |
+| `Server Sign On for Members` | Lets the holder impersonate any member |
+| `Manage Roles` / `Manage Site Members` | Account take-over |
+| `Wix CLI - Git Integration` | Modify deployed code |
+| `Multilingual Translation Schema Write` | Tamper with on-site copy across languages |
+| `Manage Notifications` | Push spam to members |
+| `Invoke AI Models` | Bills your account for arbitrary LLM usage |
+| `Manage Wixel Projects` / `Manage Site Branches` | Layout/structure mutation |
+| Any **All account permissions** master toggle | Unties every account-wide capability above |
+
+### Mapping: tool group → required permission
+
+Use this table to figure out which permission a given group of tools
+relies on. If you want a slimmer key (e.g. blog-only first), drop entire
+columns and remove the matching tools from your agent's allow-list.
+
+| Tool group | Wix permission | Required if you use… |
+|---|---|---|
+| `wix_sites_list`, `wix_site_url_get` | Get Sites List | Always (used internally — `wix_site_url_get` reads `viewUrl` from the Site object, no separate "Read Site URLs" permission needed) |
+| `wix_business_info_get` | Business Info | `wix_business_info_get` |
+| `wix_blog_*` | Wix Blog | Any blog tool |
+| `wix_media_*` | Manage Site Media | Any media tool, **and** rich-content blog drafts |
+| `wix_data_*` | Wix Data | Any CMS collection tool |
+| `wix_forms_*` | Wix Forms + Manage Form Submissions | Lead reading |
+| `wix_contacts_*` | Wix Contacts & Members | CRM tooling |
+| `wix_bookings_*` | Wix Bookings | Booking tooling |
+| `wix_events_*` | Wix Events | Event tooling |
+| `wix_reviews_*` | Wix Reviews | Reviews moderation |
+| `wix_faq_*` | Manage FAQ | FAQ tooling |
+| `wix_multilingual_*` | Multilingual Translation Schema Read | Translation reads |
+| `wix_design_brief` | _(none — no API call)_ | Always |
+
+### Wix app installation requirements
+
+Some Wix REST endpoints only exist when the corresponding **Wix app** is
+installed on the target site. The plugin ships them all generically —
+they will simply return a clean error when the app is missing, and start
+working as soon as the app is installed (no plugin upgrade needed).
+
+| Tool group | Wix app required | Error returned when missing |
+|---|---|---|
+| `wix_blog_*` | Wix Blog | `404` |
+| `wix_data_*` | Velo / Wix Code (enable in Editor) | `400 WDE0110: Wix Code not enabled` |
+| `wix_forms_*` | Wix Forms | `404` |
+| `wix_bookings_*` | Wix Bookings | `404` |
+| `wix_events_*` | Wix Events | `428 WIX_EVENTS_APP_NOT_INSTALLED` |
+| `wix_reviews_*` | Wix Reviews | `428 APP_NOT_INSTALLED` |
+| `wix_faq_*` | Wix FAQ | `400 App is not installed` |
+| `wix_multilingual_*` | Wix Multilingual | `403` |
+| `wix_contacts_*`, `wix_media_*`, `wix_sites_list`, `wix_site_url_get`, `wix_business_info_get` | (always available) | — |
+
+To install a Wix app on your site: Wix Dashboard → **App Market** → search
+for the app → **Add to Site**. It is free in most cases and takes effect
+immediately for API calls.
+
+### Rotating the key
+
+Wix keys can be revoked at any time from the same **API Keys** page. If
+a key leaks, or if you need to ship a temporary smoke-test key with
+narrower scope:
+
+1. Generate a new key with the desired scope.
+2. Update `WIX_API_KEY` in your environment.
+3. Restart the OpenClaw gateway.
+4. Revoke the old key.
+
+The plugin reads the key on each request through the resolved config —
+no in-memory caching beyond the gateway lifecycle, so a restart fully
+flushes the previous credential.
+
+---
+
+## Tools
+
+### Blog
+
+| Tool | What it does | Approval |
+|---|---|---|
+| `wix_blog_list_drafts` | List draft posts | — |
+| `wix_blog_get_draft` | Fetch a draft by id | — |
+| `wix_blog_create_draft` | Create a new draft | — |
+| `wix_blog_update_draft` | Patch a draft | — |
+| `wix_blog_publish_draft` | Publish a draft | required |
+| `wix_blog_list_published` | List published posts | — |
+| `wix_blog_get_post` | Fetch a published post | — |
+| `wix_blog_unpublish` | Move post to trash (reversible) | required |
+| `wix_blog_delete_draft` | Permanently delete a draft | required |
+| `wix_blog_list_categories` | List blog categories | — |
+| `wix_blog_list_tags` | List blog tags | — |
+
+### Media
+
+| Tool | What it does | Approval |
+|---|---|---|
+| `wix_media_upload` | Import image into Site Media by URL | — |
+| `wix_media_list` | List files in the media library | — |
+
+The `wix_media_upload` tool returns the Wix file metadata, including the
+`id`. Pass that id back into `wix_blog_create_draft` as
+`coverMedia.imageId` or embed it into a Ricos rich-content node — see
+the tool description for the contract the LLM should follow.
+
+### Site
+
+| Tool | What it does | Approval |
+|---|---|---|
+| `wix_sites_list` | List sites under the account (account-scoped) | — |
+| `wix_site_url_get` | Get published URL of a site | — |
+| `wix_business_info_get` | Read business info (name, address, hours) | — |
+
+### CMS Data
+
+| Tool | What it does | Approval |
+|---|---|---|
+| `wix_data_list_collections` | List CMS collections + schemas | — |
+| `wix_data_query_items` | Mongo-style filter on a collection | — |
+| `wix_data_get_item` | Fetch one item by id | — |
+| `wix_data_insert_item` | Insert a new item | — |
+| `wix_data_update_item` | Update an item | — |
+| `wix_data_remove_item` | Delete an item | required |
+
+### Forms
+
+| Tool | What it does | Approval |
+|---|---|---|
+| `wix_forms_list_submissions` | List submissions / leads | — |
+| `wix_forms_get_submission` | Fetch a single submission | — |
+
+### Contacts
+
+| Tool | What it does | Approval |
+|---|---|---|
+| `wix_contacts_query` | Search contacts | — |
+| `wix_contacts_get` | Get one contact | — |
+| `wix_contacts_create` | Create a contact | — |
+| `wix_contacts_update` | Update a contact | — |
+| `wix_contacts_label_add` | Add labels to a contact | — |
+| `wix_contacts_delete` | Delete a contact | required |
+
+### Bookings
+
+| Tool | What it does | Approval |
+|---|---|---|
+| `wix_bookings_services_list` | List bookable services | — |
+| `wix_bookings_query_bookings` | Query existing bookings | — |
+| `wix_bookings_get_booking` | Fetch one booking | — |
+| `wix_bookings_create` | Create a booking | — |
+| `wix_bookings_reschedule` | Move to a different slot | required |
+| `wix_bookings_cancel` | Cancel a booking | required |
+
+### Events
+
+| Tool | What it does | Approval |
+|---|---|---|
+| `wix_events_list` | List events | — |
+| `wix_events_get` | Fetch one event | — |
+| `wix_events_list_guests` | List guests / RSVPs / orders | — |
+
+### Reviews
+
+| Tool | What it does | Approval |
+|---|---|---|
+| `wix_reviews_list` | List reviews | — |
+| `wix_reviews_get` | Fetch one review | — |
+| `wix_reviews_moderate` | Approve / reject a pending review | required |
+
+### FAQ
+
+| Tool | What it does | Approval |
+|---|---|---|
+| `wix_faq_list_categories` | List FAQ categories | — |
+| `wix_faq_list_questions` | List questions (filterable by category) | — |
+| `wix_faq_create_question` | Create a question | — |
+| `wix_faq_update_question` | Update a question | — |
+| `wix_faq_delete_question` | Delete a question | required |
+
+### Multilingual (read-only in V1)
+
+| Tool | What it does | Approval |
+|---|---|---|
+| `wix_multilingual_list_languages` | List configured languages | — |
+| `wix_multilingual_get_translation` | Read a translation by key | — |
+
+### Design
+
+| Tool | What it does | Approval |
+|---|---|---|
+| `wix_design_brief` | Turn a loose textual brief into a structured markdown artefact (palette, typography, sections, image-gen prompts). **Does NOT call the Wix API.** | — |
+
+---
+
+## Approval flow
+
+When the LLM calls a destructive tool, the plugin's `before_tool_call` hook
+fires and returns a `requireApproval` directive:
+
+```json
+{
+  "requireApproval": {
+    "title": "Wix: confirm wix_blog_publish_draft",
+    "description": "Tool `wix_blog_publish_draft` is about to run with the following parameters:\n\n```json\n{ \"draftPostId\": \"abc-123\" }\n```\n...",
+    "severity": "critical",
+    "timeoutMs": 600000,
+    "timeoutBehavior": "deny"
+  }
+}
+```
+
+OpenClaw surfaces this to whichever channel/UI the operator is using
+(Telegram inline buttons, Control UI badge, etc.). If no decision is made
+within 10 minutes, the call is denied automatically.
+
+You can override the gated set via `approvalRequired` in the plugin config —
+use an empty array to disable gating entirely (not recommended in production).
+
+---
+
+## Development
+
+### Project layout
+
+```
+wix-openclaw-plugin/
+├── src/
+│   ├── index.ts             # Entry point + tool collection
+│   ├── config.ts            # resolveEnv + default resolution
+│   ├── wix-client.ts        # Authenticated HTTP client + whitelist
+│   ├── types.ts             # Shared interfaces
+│   ├── hooks/
+│   │   └── approval.ts      # before_tool_call approval gating
+│   └── tools/
+│       ├── _factory.ts      # defineWixTool helper
+│       ├── blog.ts
+│       ├── media.ts
+│       ├── site.ts
+│       ├── data.ts
+│       ├── forms.ts
+│       ├── contacts.ts
+│       ├── bookings.ts
+│       ├── events.ts
+│       ├── reviews.ts
+│       ├── faq.ts
+│       ├── multilingual.ts
+│       └── design.ts
+├── test/
+│   ├── wix-client.test.ts
+│   ├── manifest.test.ts
+│   ├── hooks/approval.test.ts
+│   └── tools/blog.test.ts
+├── tsconfig.json
+├── tsconfig.test.json
+├── tsconfig.test-build.json
+├── openclaw.plugin.json
+└── package.json
+```
+
+### Build and test
+
+```bash
+npm install
+npm run typecheck     # strict TS check (src + test)
+npm test              # compile tests + run node:test
+npm run build         # compile src/ → dist/
+npm run clean         # remove dist + dist-test
+```
+
+### Release process
+
+1. Update `CHANGELOG.md` with a new `## [x.y.z] - YYYY-MM-DD` section
+2. Commit
+3. Tag and push:
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+4. GitHub Actions will:
+   - Run typecheck, tests, build on Node.js 24
+   - Stamp the version into `package.json` and `openclaw.plugin.json`
+   - Publish to npm via **Trusted Publishing (OIDC)** — no `NPM_TOKEN`
+     secret needed
+   - Create a GitHub Release with the changelog excerpt
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+import type { ResolvedWixConfig, WixPluginConfig } from "./types.js";
+/**
+ * Expand `${VAR_NAME}` patterns in a config string against `process.env`.
+ * Non-string values are returned untouched so the helper can be used on any
+ * raw config field without type narrowing at the call site. Missing env vars
+ * become empty strings to avoid leaking `undefined` into downstream code.
+ */
+export declare function resolveEnv<T>(value: T): T;
+/**
+ * Apply defaults and env substitution to the raw plugin config.
+ *
+ * - `enabled` is true unless explicitly set to `false`.
+ * - `defaultSiteId`, when blank, falls back to the first `allowedSiteIds`
+ *   entry. This keeps single-site setups (the typical case) one field
+ *   shorter without surprising whitelist behaviour.
+ * - `approvalRequired` defaults to every destructive operation; pass an
+ *   empty array to disable gating entirely.
+ */
+export declare function resolveConfig(cfg?: WixPluginConfig): ResolvedWixConfig;

package/dist/config.js

@@ -0,0 +1,60 @@
+// Plugin configuration helpers.
+//
+// These helpers are the only place that touches `process.env`, keeping the
+// rest of the plugin easy to test with deterministic values.
+/**
+ * Expand `${VAR_NAME}` patterns in a config string against `process.env`.
+ * Non-string values are returned untouched so the helper can be used on any
+ * raw config field without type narrowing at the call site. Missing env vars
+ * become empty strings to avoid leaking `undefined` into downstream code.
+ */
+export function resolveEnv(value) {
+    if (typeof value !== "string")
+        return value;
+    return value.replace(/\$\{(\w+)\}/g, (_, name) => {
+        return process.env[name] ?? "";
+    });
+}
+const DEFAULT_APPROVAL_REQUIRED = [
+    "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",
+];
+const VALID_LOG_LEVELS = ["debug", "info", "warn", "error"];
+/**
+ * Apply defaults and env substitution to the raw plugin config.
+ *
+ * - `enabled` is true unless explicitly set to `false`.
+ * - `defaultSiteId`, when blank, falls back to the first `allowedSiteIds`
+ *   entry. This keeps single-site setups (the typical case) one field
+ *   shorter without surprising whitelist behaviour.
+ * - `approvalRequired` defaults to every destructive operation; pass an
+ *   empty array to disable gating entirely.
+ */
+export function resolveConfig(cfg = {}) {
+    const apiKey = resolveEnv(cfg.apiKey ?? "");
+    const accountId = resolveEnv(cfg.accountId ?? "");
+    const allowedSiteIds = (cfg.allowedSiteIds ?? []).map((id) => resolveEnv(id));
+    const explicitDefault = resolveEnv(cfg.defaultSiteId ?? "");
+    const defaultSiteId = explicitDefault || (allowedSiteIds[0] ?? "");
+    const approvalRequired = cfg.approvalRequired ?? DEFAULT_APPROVAL_REQUIRED;
+    const logLevel = VALID_LOG_LEVELS.includes(cfg.logLevel)
+        ? cfg.logLevel
+        : "info";
+    return {
+        enabled: cfg.enabled !== false,
+        apiKey,
+        accountId,
+        allowedSiteIds,
+        defaultSiteId,
+        approvalRequired: new Set(approvalRequired),
+        logLevel,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,EAAE;AACF,2EAA2E;AAC3E,6DAA6D;AAQ7D;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAI,KAAQ;IACpC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,KAAK,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,EAAE,IAAY,EAAE,EAAE;QACvD,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACjC,CAAC,CAAiB,CAAC;AACrB,CAAC;AAED,MAAM,yBAAyB,GAAG;IAChC,wBAAwB;IACxB,oBAAoB;IACpB,uBAAuB;IACvB,sBAAsB;IACtB,qBAAqB;IACrB,yBAAyB;IACzB,qBAAqB;IACrB,sBAAsB;IACtB,yBAAyB;CAC1B,CAAC;AAEF,MAAM,gBAAgB,GAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAE3E;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAuB,EAAE;IAEzB,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IAClD,MAAM,cAAc,GAAG,CAAC,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9E,MAAM,eAAe,GAAG,UAAU,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC;IAC5D,MAAM,aAAa,GACjB,eAAe,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAE/C,MAAM,gBAAgB,GAAG,GAAG,CAAC,gBAAgB,IAAI,yBAAyB,CAAC;IAE3E,MAAM,QAAQ,GAAgB,gBAAgB,CAAC,QAAQ,CACrD,GAAG,CAAC,QAAuB,CAC5B;QACC,CAAC,CAAE,GAAG,CAAC,QAAwB;QAC/B,CAAC,CAAC,MAAM,CAAC;IAEX,OAAO;QACL,OAAO,EAAE,GAAG,CAAC,OAAO,KAAK,KAAK;QAC9B,MAAM;QACN,SAAS;QACT,cAAc;QACd,aAAa;QACb,gBAAgB,EAAE,IAAI,GAAG,CAAC,gBAAgB,CAAC;QAC3C,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/hooks/approval.d.ts

@@ -0,0 +1,29 @@
+import type { ResolvedWixConfig, WixLogger } from "../types.js";
+/**
+ * Shape of a `before_tool_call` event payload — only the fields we use.
+ * Mirrors `PluginHookBeforeToolCallEvent` from the SDK.
+ */
+export interface BeforeToolCallEvent {
+    toolName: string;
+    params: Record<string, unknown>;
+    runId?: string;
+    toolCallId?: string;
+}
+/**
+ * Subset of the SDK's `PluginHookBeforeToolCallResult` that we produce.
+ */
+export interface BeforeToolCallResult {
+    requireApproval?: {
+        title: string;
+        description: string;
+        severity?: "info" | "warning" | "critical";
+        timeoutMs?: number;
+        timeoutBehavior?: "allow" | "deny";
+    };
+}
+/**
+ * Build a `before_tool_call` handler bound to a resolved Wix config.
+ * Extracted as a factory so tests can exercise it without a full plugin
+ * registration.
+ */
+export declare function createApprovalHook(config: ResolvedWixConfig, logger: WixLogger): (event: BeforeToolCallEvent) => BeforeToolCallResult | undefined;