@lacneu/wix-openclaw 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,82 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-04-29
+
+### Added
+- **Wix query envelope passthrough** — every POST `/query` tool now
+  accepts the full Wix Query Language envelope (`filter`, `sort`,
+  `paging`, `cursorPaging`, `fields`) as plain optional parameters.
+  Filters can use any MongoDB-style operator the Wix API supports
+  (`$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$exists`,
+  `$startsWith`, `$contains`, `$hasSome`, `$hasAll`, `$matches`, `$and`,
+  `$or`, `$not`). See https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language
+- **`wix_blog_list_drafts.status` filter** — new optional parameter
+  with values `UNPUBLISHED | PUBLISHED | SCHEDULED | IN_REVIEW | ALL`
+  (default `ALL` = previous behaviour, returns drafts with all
+  statuses by omitting the parameter).
+- **`wix_blog_list_drafts.sort`** — `EDITING_DATE_ASC` /
+  `EDITING_DATE_DESC` (verified live).
+- **`wix_blog_list_drafts.fieldsets`** — response projection,
+  e.g. `["URL"]`, `["RICH_CONTENT"]` (verified live).
+- **`wix_blog_list_published`** — added `sort`
+  (`PUBLISHED_DATE_*` / `VIEW_COUNT_*` / `LIKE_COUNT_*`),
+  `featured`, `language`, `tagIds`, `categoryIds`, `fieldsets`.
+- **`wix_blog_list_categories` / `wix_blog_list_tags`** — added
+  `language` and `paging` options.
+- **`wix_media_list.mediaTypes`** — restrict by `IMAGE | VIDEO | AUDIO
+  | DOCUMENT | ARCHIVE` and `paging.cursor` for cursor walks
+  (verified live).
+- **`wix_data_query_items`** — full Wix query envelope replaces the
+  ad-hoc filter/sort/paging fields.
+- **`wix_sites_list`** — full envelope (filter on `metaSiteId`,
+  `displayName`, `published`, `domainConnected`).
+- **`wix_forms_list_submissions`** — namespace pinning is now
+  `$and`-merged with passthrough filter so shortcuts can never be
+  silently overridden by the agent.
+- **`wix_events_list_guests`** — `eventId` is now `$and`-merged with
+  passthrough filter (same guarantee).
+- New shared module `src/tools/_query.ts` — single source of truth
+  for query envelope mapping (`buildQueryBody`, `mergeFilter`,
+  `buildGetPagingQuery`, `compactQuery`).
+- Smoke test now runs **two passes**: endpoint reachability (direct
+  `client.request()`) AND tool-execute scenarios
+  (`tool.execute(callId, params)`) covering at least one filter / sort
+  / paging case per installed-app tool family.
+- New per-family unit tests:
+  `test/tools/_query.test.ts` (mapper),
+  `test/tools/contacts.test.ts`, `test/tools/bookings.test.ts`,
+  `test/tools/forms.test.ts`, `test/tools/data.test.ts`,
+  `test/tools/media.test.ts` — assert that
+  `tool.execute(...)` lands the right keys in body/query.
+
+### Fixed
+- Manifest version mismatch — `openclaw.plugin.json` was `0.1.0` while
+  `package.json` was `0.1.1`. Both bumped to `0.2.0`.
+
+### Notes
+- **`wix_blog_list_drafts.status === "ALL"`** is a client-side
+  convention; it maps to "no `status` query param" because Wix returns
+  HTTP 400 for any unknown status value. Default behaviour is
+  unchanged — drafts with every status are returned.
+- **Multilingual `403`** observed on the smoke-test site is a key
+  permission issue (`Multilingual Translation Schema Read` not
+  granted), distinct from app-not-installed. Confirm the permission
+  on your API key if you need multilingual reads.
+- **Reachability baseline 12/20** matches v0.1.1: the 8 failures are
+  legitimate "app not installed on Ataraxis" responses (Events,
+  Reviews, FAQ, Multilingual permission, Velo not enabled).
+
+## [0.1.1] - 2026-04-29
+
+### Fixed
+- Move `@sinclair/typebox` from `devDependencies` to `dependencies` so the
+  plugin can resolve the import at runtime when installed via
+  `openclaw plugins install`. Without this, the plugin failed to load
+  with `Cannot find module '@sinclair/typebox'`.
+
+## [0.1.0] - 2026-04-29
+
 ### 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`

package/README.md

@@ -8,6 +8,7 @@
 [![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)
+[![Plugin version](https://img.shields.io/badge/version-0.2.0-blue)](CHANGELOG.md)
 
 ---
 
@@ -266,30 +267,101 @@ flushes the previous credential.
 
 ---
 
+## Wix query envelope
+
+Every POST `/query` tool (`wix_contacts_query`, `wix_bookings_*_list`,
+`wix_forms_list_submissions`, `wix_events_*`, `wix_reviews_list`,
+`wix_multilingual_list_languages`, `wix_sites_list`,
+`wix_data_query_items`) accepts the standard Wix Query Language
+envelope as plain optional parameters:
+
+```jsonc
+{
+  // Optional — MongoDB-style filter, e.g.
+  //   { "status": { "$in": ["ACTIVE", "PENDING"] } }
+  //   { "$and": [{ "createdDate": { "$gt": "2026-01-01T00:00:00Z" } },
+  //              { "info.emails.email": { "$contains": "acme" } }] }
+  "filter": { /* ... */ },
+
+  // Optional — sort entries applied in order
+  "sort": [{ "fieldName": "createdDate", "order": "DESC" }],
+
+  // Optional — offset paging (most endpoints)
+  "paging": { "limit": 50, "offset": 0 },
+
+  // Optional — cursor paging (Site Media, some Bookings, ...)
+  "cursorPaging": { "limit": 50, "cursor": "<opaque>" },
+
+  // Optional — projection
+  "fields": ["id", "info.name"]
+}
+```
+
+Supported operators (per the [Wix Query Language docs](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language)):
+`$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`,
+`$exists`, `$startsWith`, `$contains`, `$hasSome`, `$hasAll`,
+`$matches`, `$and`, `$or`, `$not`.
+
+> **Live verification scope**
+> The plugin's smoke test currently exercises `$eq`, `$in`, `$exists`,
+> field equality, sort entries, offset paging, and free-text `search`
+> against the Ataraxis site. Other operators (`$ne`, `$gt`, `$gte`,
+> `$lt`, `$lte`, `$nin`, `$startsWith`, `$contains`, `$hasSome`,
+> `$hasAll`, `$matches`, `$or`, `$not`) and `cursorPaging` /
+> `fields` projection are exposed structurally and routed to the body
+> by the mapper, but per-operator live coverage on every endpoint is
+> not in v0.2.0's scope. Each Wix endpoint individually decides which
+> fields are filterable and which operators are accepted — Wix returns
+> a clean `400 UNSUPPORTED_QUERY_FILTER` when it disagrees, surfaced
+> as a tool failure to the model.
+
+Tools that have ergonomic shortcuts (e.g. `wix_blog_list_drafts.status`,
+`wix_forms_list_submissions.namespace`) **always merge** the shortcut
+into the filter via `$and`, so the agent can never silently override the
+shortcut by passing a competing `filter`.
+
+Flat GET endpoints (`wix_blog_list_drafts`, `wix_blog_list_published`,
+`wix_blog_list_categories`, `wix_blog_list_tags`,
+`wix_data_list_collections`, `wix_faq_list_*`, `wix_media_list`,
+`wix_multilingual_list_schemas`) accept named query string params plus
+`paging.{limit,offset,cursor}` — they do NOT support the operator
+passthrough above. Each tool's parameters are documented in its
+description.
+
+---
+
 ## Tools
 
+The `Validated` column reflects v0.2.0 verification on the Ataraxis
+Coaching site: `live` means hit by the smoke-test against a real Wix
+site; `app-not-installed` and `velo-not-enabled` mean the tool's
+endpoint exists but its backing Wix product is not active on the
+smoke-test site (the request still reaches Wix and the path/headers
+are correct); `docs` means write/destructive endpoints that we do not
+exercise live.
+
 ### 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 | — |
+| Tool | What it does | Approval | Validated |
+|---|---|---|---|
+| `wix_blog_list_drafts` | List drafts; supports `status` (`UNPUBLISHED \| PUBLISHED \| SCHEDULED \| IN_REVIEW \| ALL`), `sort`, `fieldsets`, `paging` | — | live |
+| `wix_blog_get_draft` | Fetch a draft by id; supports `fieldsets` | — | live |
+| `wix_blog_create_draft` | Create a new draft | — | docs |
+| `wix_blog_update_draft` | Patch a draft | — | docs |
+| `wix_blog_publish_draft` | Publish a draft | required | docs |
+| `wix_blog_list_published` | List published posts; supports `sort`, `featured`, `language`, `tagIds`, `categoryIds`, `fieldsets`, `paging` | — | live |
+| `wix_blog_get_post` | Fetch a published post; supports `fieldsets` | — | live |
+| `wix_blog_unpublish` | Move post to trash (reversible) | required | docs |
+| `wix_blog_delete_draft` | Permanently delete a draft | required | docs |
+| `wix_blog_list_categories` | List blog categories; supports `language`, `paging` | — | live |
+| `wix_blog_list_tags` | List blog tags; supports `language`, `paging` | — | live |
 
 ### 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 | — |
+| Tool | What it does | Approval | Validated |
+|---|---|---|---|
+| `wix_media_upload` | Import image into Site Media by URL | — | docs |
+| `wix_media_list` | List files; supports `parentFolderId`, `mediaTypes` (IMAGE/VIDEO/AUDIO/DOCUMENT/ARCHIVE), cursor paging via `paging.cursor` | — | live |
 
 The `wix_media_upload` tool returns the Wix file metadata, including the
 `id`. Pass that id back into `wix_blog_create_draft` as
@@ -298,90 +370,105 @@ 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) | — |
+| Tool | What it does | Approval | Validated |
+|---|---|---|---|
+| `wix_sites_list` | List sites under the account (account-scoped); accepts the standard Wix query envelope | — | live |
+| `wix_site_url_get` | Get published URL of a site | — | live |
+| `wix_business_info_get` | Read business info (name, address, hours) | — | live |
 
 ### 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 |
+Requires Velo / Wix Code to be enabled on the target site (Wix Editor →
+Velo → Enable Code). Without it, calls return HTTP 400 `WDE0110: Wix
+Code not enabled`.
+
+| Tool | What it does | Approval | Validated |
+|---|---|---|---|
+| `wix_data_list_collections` | List CMS collections + schemas | — | velo-not-enabled |
+| `wix_data_query_items` | Full Wix query envelope on a collection | — | velo-not-enabled |
+| `wix_data_get_item` | Fetch one item by id | — | velo-not-enabled |
+| `wix_data_insert_item` | Insert a new item | — | docs |
+| `wix_data_update_item` | Update an item | — | docs |
+| `wix_data_remove_item` | Delete an item | required | docs |
 
 ### Forms
 
-| Tool | What it does | Approval |
-|---|---|---|
-| `wix_forms_list_submissions` | List submissions / leads | — |
-| `wix_forms_get_submission` | Fetch a single submission | — |
+| Tool | What it does | Approval | Validated |
+|---|---|---|---|
+| `wix_forms_list_submissions` | Full Wix query envelope; `namespace` defaults to `wix.form_app.form` and is always `$and`-merged with passthrough filter | — | live |
+| `wix_forms_get_submission` | Fetch a single submission | — | docs |
 
 ### 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 |
+| Tool | What it does | Approval | Validated |
+|---|---|---|---|
+| `wix_contacts_query` | Full Wix query envelope + free-text `search` | — | live |
+| `wix_contacts_get` | Get one contact | — | docs |
+| `wix_contacts_create` | Create a contact | — | docs |
+| `wix_contacts_update` | Update a contact | — | docs |
+| `wix_contacts_label_add` | Add labels to a contact | — | docs |
+| `wix_contacts_delete` | Delete a contact | required | docs |
 
 ### 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 |
+| Tool | What it does | Approval | Validated |
+|---|---|---|---|
+| `wix_bookings_services_list` | List bookable services; standard query envelope | — | live |
+| `wix_bookings_query_bookings` | Query bookings with operators (e.g. `status: { $in: [...] }`); standard query envelope | — | live |
+| `wix_bookings_get_booking` | Fetch one booking | — | docs |
+| `wix_bookings_create` | Create a booking | — | docs |
+| `wix_bookings_reschedule` | Move to a different slot | required | docs |
+| `wix_bookings_cancel` | Cancel a booking | required | docs |
 
 ### 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 | — |
+Requires the Wix Events app (returns `428 WIX_EVENTS_APP_NOT_INSTALLED`
+otherwise).
+
+| Tool | What it does | Approval | Validated |
+|---|---|---|---|
+| `wix_events_list` | List events; standard query envelope | — | app-not-installed |
+| `wix_events_get` | Fetch one event | — | app-not-installed |
+| `wix_events_list_guests` | List guests / RSVPs; `eventId` is `$and`-merged with passthrough filter | — | app-not-installed |
 
 ### 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 |
+Requires the Wix Reviews app (returns `428 APP_NOT_INSTALLED` otherwise).
+
+| Tool | What it does | Approval | Validated |
+|---|---|---|---|
+| `wix_reviews_list` | List reviews; standard query envelope | — | app-not-installed |
+| `wix_reviews_get` | Fetch one review | — | docs |
+| `wix_reviews_moderate` | Approve / reject a pending review | required | docs |
 
 ### 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 |
+Requires the Wix FAQ app (returns `400 App is not installed` otherwise).
+
+| Tool | What it does | Approval | Validated |
+|---|---|---|---|
+| `wix_faq_list_categories` | List FAQ categories | — | app-not-installed |
+| `wix_faq_list_questions` | List questions (filterable by category) | — | app-not-installed |
+| `wix_faq_create_question` | Create a question | — | docs |
+| `wix_faq_update_question` | Update a question | — | docs |
+| `wix_faq_delete_question` | Delete a question | required | docs |
 
 ### 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 | — |
+Returns `403` on the Ataraxis smoke-test site — likely missing the
+`Multilingual Translation Schema Read` permission on the API key
+rather than an app-not-installed condition.
+
+| Tool | What it does | Approval | Validated |
+|---|---|---|---|
+| `wix_multilingual_list_languages` | List configured languages; standard query envelope | — | 403-permission |
+| `wix_multilingual_list_schemas` | List translation schemas | — | 403-permission |
 
 ### 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.** | — |
+| Tool | What it does | Approval | Validated |
+|---|---|---|---|
+| `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.** | — | n/a |
 
 ---
 

package/dist/tools/_query.d.ts

@@ -0,0 +1,117 @@
+import type { Static } from "@sinclair/typebox";
+/**
+ * Sort entry — `fieldName` is the dotted path (e.g.
+ * `info.emails.email`), `order` is `ASC` (default) or `DESC`. Maps 1:1
+ * to the Wix sort entry shape.
+ */
+export declare const WixSortEntrySchema: import("@sinclair/typebox").TObject<{
+    fieldName: import("@sinclair/typebox").TString;
+    order: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"ASC">, import("@sinclair/typebox").TLiteral<"DESC">]>>;
+}>;
+/**
+ * Offset paging — preferred form for POST /query endpoints that don't
+ * stream very large result sets. `limit` defaults to 50 server-side.
+ */
+export declare const WixOffsetPagingSchema: import("@sinclair/typebox").TObject<{
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    offset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+/**
+ * Cursor paging — used by endpoints that need stable iteration over
+ * large or fast-changing collections (e.g. Site Media, some Bookings
+ * queries). Pass back the `cursor` returned in `pagingMetadata.cursors.next`.
+ */
+export declare const WixCursorPagingSchema: import("@sinclair/typebox").TObject<{
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    cursor: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+/**
+ * Generic query body envelope shared by every POST /query tool.
+ *
+ * The `filter` is intentionally typed as `Type.Unknown()` — Wix accepts
+ * arbitrarily nested MongoDB-style operator trees that we don't try to
+ * model in TypeBox. The agent gets full operator richness; tools layer
+ * ergonomic shortcuts on top by merging into this filter.
+ *
+ * Per-tool ergonomic shortcuts (e.g. `wix_blog_list_drafts.status`)
+ * compose with `filter` via {@link mergeFilter}.
+ */
+export declare const WixQueryBodyEnvelopeSchema: import("@sinclair/typebox").TObject<{
+    filter: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+    sort: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        fieldName: import("@sinclair/typebox").TString;
+        order: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"ASC">, import("@sinclair/typebox").TLiteral<"DESC">]>>;
+    }>>>;
+    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>;
+    }>>;
+    cursorPaging: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        cursor: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>;
+    fields: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+}>;
+export type WixQueryBodyEnvelope = Static<typeof WixQueryBodyEnvelopeSchema>;
+/**
+ * Build the JSON body for a POST /query call.
+ *
+ * Returns `{ query: { ... } }` with only the populated keys — Wix
+ * rejects empty `paging: {}` and friends on some endpoints.
+ *
+ * `extraFilter` is merged into `envelope.filter` via {@link mergeFilter}.
+ * Use it when a tool layers ergonomic shortcuts on top of the raw
+ * passthrough (e.g. `wix_forms_list_submissions` always pins
+ * `namespace`).
+ */
+export declare function buildQueryBody(envelope: WixQueryBodyEnvelope | undefined, extraFilter?: Record<string, unknown>): {
+    query: Record<string, unknown>;
+};
+/**
+ * Merge a tool-level shortcut filter (`extra`) with a user-provided
+ * passthrough filter (`base`).
+ *
+ * Precedence rule: the SHORTCUT WINS on field-level collision.
+ *
+ * Why: shortcuts encode constraints Wix REQUIRES (e.g.
+ * `wix_forms_list_submissions.namespace` — Wix rejects the call without
+ * a namespace filter). If the agent's passthrough were to override a
+ * pinned namespace, the call would fail with "namespace required".
+ *
+ * Implementation:
+ *   - If only one side defines a key, that key is kept verbatim.
+ *   - If both sides define the SAME top-level key, the shortcut wins
+ *     and the passthrough's value for that key is dropped (logged
+ *     conceptually, but we don't have a logger here).
+ *   - Non-conflicting keys from both sides are combined with `$and`
+ *     when needed, otherwise spread into a flat object.
+ *
+ * - Both undefined → undefined (caller decides whether to omit the key)
+ * - Only one defined → returned as-is
+ */
+export declare function mergeFilter(base: unknown, extra: Record<string, unknown> | undefined): unknown;
+/**
+ * Paging shape for flat GET endpoints. Some Wix endpoints support
+ * offset paging (`paging.limit`/`paging.offset`), others use cursor
+ * paging (`paging.limit`/`paging.cursor`). We expose both — tools pick
+ * the right pair when calling {@link buildGetPagingQuery}.
+ */
+export declare const WixGetPagingEnvelopeSchema: import("@sinclair/typebox").TObject<{
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    offset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    cursor: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type WixGetPagingEnvelope = Static<typeof WixGetPagingEnvelopeSchema>;
+/**
+ * Map a `paging` envelope to flat `paging.limit` / `paging.offset` /
+ * `paging.cursor` query string keys (Wix's documented convention).
+ *
+ * Returns a partial query object the caller can spread into
+ * `client.request({ query: { ...buildGetPagingQuery(p), other: x } })`.
+ */
+export declare function buildGetPagingQuery(paging: WixGetPagingEnvelope | undefined): Record<string, string | number | boolean | undefined>;
+/**
+ * Drop `undefined`, `null`, and empty-string entries from a query
+ * record so they don't end up as `?key=undefined` after serialisation.
+ */
+export declare function compactQuery(q: Record<string, string | number | boolean | undefined | null>): Record<string, string | number | boolean | undefined>;