@lacneu/wix-openclaw 0.1.0 → 0.2.0

package/dist/tools/_query.js

@@ -0,0 +1,240 @@
+// Shared query helpers for Wix tools.
+//
+// Wix exposes two distinct query styles:
+//
+//   1. POST `/.../query` endpoints — accept a JSON body shaped as
+//      `{ query: { filter, sort, paging | cursorPaging, fields } }`. The
+//      filter supports MongoDB-style operators
+//      (`$eq/$ne/$gt/$gte/$lt/$lte/$in/$nin/$exists/$startsWith/$hasSome
+//      /$hasAll/$contains/$matches/$and/$or/$not`) — see 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
+//
+//   2. Flat GET endpoints — accept named query string parameters plus
+//      `paging.limit` / `paging.offset` (or `paging.cursor` when the
+//      endpoint paginates by cursor). They do NOT accept the operator
+//      syntax above; trying to send `?filter={"$eq":...}` is silently
+//      ignored.
+//
+// To keep tools honest about what their backing endpoint actually
+// accepts, we expose two distinct envelopes:
+//
+//   - `WixQueryBodyEnvelope` for POST /query tools — full passthrough
+//     `filter`, `sort`, `paging`/`cursorPaging`, `fields` (projection)
+//   - `WixGetPagingEnvelope` for flat GET tools — `paging` only; named
+//     filters live as plain top-level params on each tool.
+//
+// The mappers (`buildQueryBody`, `buildGetPagingQuery`) are the single
+// source of truth for shape. Per-tool tests assert that
+// `tool.execute(...)` lands the right keys in the right place; the
+// mapper itself gets exhaustive coverage in a single test file.
+import { Type } from "@sinclair/typebox";
+// ---------------------------------------------------------------------------
+// POST /query envelope
+// ---------------------------------------------------------------------------
+/**
+ * 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 const WixSortEntrySchema = Type.Object({
+    fieldName: Type.String({
+        description: "Dotted path of the field to sort by, e.g. `createdDate`",
+    }),
+    order: Type.Optional(Type.Union([Type.Literal("ASC"), Type.Literal("DESC")], {
+        description: "Sort order — defaults to ASC when omitted",
+    })),
+});
+/**
+ * Offset paging — preferred form for POST /query endpoints that don't
+ * stream very large result sets. `limit` defaults to 50 server-side.
+ */
+export const WixOffsetPagingSchema = Type.Object({
+    limit: Type.Optional(Type.Number({
+        minimum: 1,
+        maximum: 1000,
+        description: "Items per page (default 50, capped per endpoint)",
+    })),
+    offset: Type.Optional(Type.Number({ minimum: 0, description: "Number of items to skip" })),
+});
+/**
+ * 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 const WixCursorPagingSchema = Type.Object({
+    limit: Type.Optional(Type.Number({ minimum: 1, maximum: 1000 })),
+    cursor: Type.Optional(Type.String({
+        description: "Opaque cursor returned by the previous page (`pagingMetadata.cursors.next`)",
+    })),
+});
+/**
+ * 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 const WixQueryBodyEnvelopeSchema = Type.Object({
+    filter: Type.Optional(Type.Unknown({
+        description: 'MongoDB-style filter, e.g. `{"status": {"$eq": "ACTIVE"}}` or ' +
+            '`{"$or": [{"a": {"$gt": 1}}, {"b": "x"}]}`. Operators: ' +
+            "$eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, " +
+            "$startsWith, $contains, $hasSome, $hasAll, $matches, $and, $or, $not.",
+    })),
+    sort: Type.Optional(Type.Array(WixSortEntrySchema, {
+        description: "List of sort entries, applied in order",
+    })),
+    paging: Type.Optional(WixOffsetPagingSchema),
+    cursorPaging: Type.Optional(WixCursorPagingSchema),
+    fields: Type.Optional(Type.Array(Type.String(), {
+        description: "Projection — list of field paths to include in the response (endpoint-specific support)",
+    })),
+});
+/**
+ * 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 function buildQueryBody(envelope, extraFilter) {
+    const env = envelope ?? {};
+    const filter = mergeFilter(env.filter, extraFilter);
+    const query = {};
+    if (filter !== undefined)
+        query.filter = filter;
+    if (env.sort && env.sort.length > 0)
+        query.sort = env.sort;
+    if (env.paging && Object.keys(env.paging).length > 0) {
+        query.paging = env.paging;
+    }
+    if (env.cursorPaging && Object.keys(env.cursorPaging).length > 0) {
+        query.cursorPaging = env.cursorPaging;
+    }
+    if (env.fields && env.fields.length > 0)
+        query.fields = env.fields;
+    return { query };
+}
+/**
+ * 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 function mergeFilter(base, extra) {
+    const hasExtra = extra && Object.keys(extra).length > 0;
+    if (base === undefined && !hasExtra)
+        return undefined;
+    if (base === undefined)
+        return extra;
+    if (!hasExtra)
+        return base;
+    // Both defined. If `base` is a plain object whose top-level keys are
+    // disjoint from `extra`, we can flatten the merge — Wix is happy with
+    // either flat or `$and`. If there's a key collision, drop the
+    // conflicting key from `base` so the shortcut wins, then `$and` the
+    // remainder.
+    if (base !== null &&
+        typeof base === "object" &&
+        !Array.isArray(base)) {
+        const baseObj = base;
+        const extraKeys = new Set(Object.keys(extra));
+        const reservedTopLevel = new Set(["$and", "$or", "$not"]);
+        const baseKeys = Object.keys(baseObj);
+        const baseHasTopLevelOperator = baseKeys.some((k) => reservedTopLevel.has(k));
+        if (!baseHasTopLevelOperator) {
+            // Field-level diff: keep the non-conflicting fields from base.
+            const filteredBase = {};
+            for (const [k, v] of Object.entries(baseObj)) {
+                if (!extraKeys.has(k))
+                    filteredBase[k] = v;
+            }
+            const filteredKeys = Object.keys(filteredBase);
+            if (filteredKeys.length === 0) {
+                // The agent's passthrough only contained collisions — every
+                // entry was overridden by the shortcut.
+                return extra;
+            }
+            // Non-collision fields remain. Combine extra (canonical) + the
+            // surviving subset of base. We use `$and` for clarity; Wix
+            // accepts either.
+            return { $and: [extra, filteredBase] };
+        }
+    }
+    // Base uses operator-level composition ($and/$or/$not) or is not a
+    // plain object — fall back to `$and` to keep the shortcut authoritative
+    // even when the passthrough is operator-rooted.
+    return { $and: [extra, base] };
+}
+// ---------------------------------------------------------------------------
+// Flat GET envelope
+// ---------------------------------------------------------------------------
+/**
+ * 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 const WixGetPagingEnvelopeSchema = Type.Object({
+    limit: Type.Optional(Type.Number({ minimum: 1, maximum: 1000 })),
+    offset: Type.Optional(Type.Number({ minimum: 0 })),
+    cursor: Type.Optional(Type.String()),
+});
+/**
+ * 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 function buildGetPagingQuery(paging) {
+    if (!paging)
+        return {};
+    const out = {};
+    if (paging.limit !== undefined)
+        out["paging.limit"] = paging.limit;
+    if (paging.offset !== undefined)
+        out["paging.offset"] = paging.offset;
+    if (paging.cursor !== undefined)
+        out["paging.cursor"] = paging.cursor;
+    return out;
+}
+/**
+ * Drop `undefined`, `null`, and empty-string entries from a query
+ * record so they don't end up as `?key=undefined` after serialisation.
+ */
+export function compactQuery(q) {
+    const out = {};
+    for (const [k, v] of Object.entries(q)) {
+        if (v === undefined || v === null || v === "")
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+//# sourceMappingURL=_query.js.map

package/dist/tools/_query.js.map

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

package/dist/tools/blog.d.ts

@@ -5,17 +5,25 @@ export declare function buildBlogTools(client: WixClient): ({
     label: string;
     parameters: import("@sinclair/typebox").TObject<{
         siteId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        status: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"UNPUBLISHED">, import("@sinclair/typebox").TLiteral<"PUBLISHED">, import("@sinclair/typebox").TLiteral<"SCHEDULED">, import("@sinclair/typebox").TLiteral<"IN_REVIEW">, import("@sinclair/typebox").TLiteral<"ALL">]>>;
+        sort: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"EDITING_DATE_ASC">, import("@sinclair/typebox").TLiteral<"EDITING_DATE_DESC">]>>;
+        fieldsets: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"URL">, import("@sinclair/typebox").TLiteral<"INTERNAL_ID">, import("@sinclair/typebox").TLiteral<"CONTENT">, import("@sinclair/typebox").TLiteral<"RICH_CONTENT">, import("@sinclair/typebox").TLiteral<"TRANSLATIONS">, import("@sinclair/typebox").TLiteral<"GENERATED_EXCERPT">, import("@sinclair/typebox").TLiteral<"COUNTERS">, import("@sinclair/typebox").TLiteral<"CONTENT_TEXT">]>>>;
         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>;
+            cursor: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         }>>;
     }>;
     execute: (toolCallId: string, params: {
+        sort?: "EDITING_DATE_ASC" | "EDITING_DATE_DESC" | undefined;
         siteId?: string | undefined;
         paging?: {
             limit?: number | undefined;
             offset?: number | undefined;
+            cursor?: string | undefined;
         } | undefined;
+        status?: "UNPUBLISHED" | "PUBLISHED" | "SCHEDULED" | "IN_REVIEW" | "ALL" | undefined;
+        fieldsets?: ("URL" | "INTERNAL_ID" | "CONTENT" | "RICH_CONTENT" | "TRANSLATIONS" | "GENERATED_EXCERPT" | "COUNTERS" | "CONTENT_TEXT")[] | undefined;
     }, signal?: AbortSignal) => Promise<import("@mariozechner/pi-agent-core").AgentToolResult<{
         status: "ok" | "failed";
         data?: unknown;
@@ -28,9 +36,11 @@ export declare function buildBlogTools(client: WixClient): ({
     parameters: import("@sinclair/typebox").TObject<{
         siteId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         draftPostId: import("@sinclair/typebox").TString;
+        fieldsets: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"URL">, import("@sinclair/typebox").TLiteral<"INTERNAL_ID">, import("@sinclair/typebox").TLiteral<"CONTENT">, import("@sinclair/typebox").TLiteral<"RICH_CONTENT">, import("@sinclair/typebox").TLiteral<"TRANSLATIONS">, import("@sinclair/typebox").TLiteral<"GENERATED_EXCERPT">, import("@sinclair/typebox").TLiteral<"COUNTERS">, import("@sinclair/typebox").TLiteral<"CONTENT_TEXT">]>>>;
     }>;
     execute: (toolCallId: string, params: {
         siteId?: string | undefined;
+        fieldsets?: ("URL" | "INTERNAL_ID" | "CONTENT" | "RICH_CONTENT" | "TRANSLATIONS" | "GENERATED_EXCERPT" | "COUNTERS" | "CONTENT_TEXT")[] | undefined;
         draftPostId: string;
     }, signal?: AbortSignal) => Promise<import("@mariozechner/pi-agent-core").AgentToolResult<{
         status: "ok" | "failed";
@@ -107,6 +117,58 @@ export declare function buildBlogTools(client: WixClient): ({
         data?: unknown;
         error?: string;
     }>>;
+} | {
+    name: string;
+    description: string;
+    label: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        siteId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        draftPostId: import("@sinclair/typebox").TString;
+    }>;
+    execute: (toolCallId: string, params: {
+        siteId?: string | undefined;
+        draftPostId: string;
+    }, 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>;
+        sort: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"PUBLISHED_DATE_ASC">, import("@sinclair/typebox").TLiteral<"PUBLISHED_DATE_DESC">, import("@sinclair/typebox").TLiteral<"VIEW_COUNT_ASC">, import("@sinclair/typebox").TLiteral<"VIEW_COUNT_DESC">, import("@sinclair/typebox").TLiteral<"LIKE_COUNT_ASC">, import("@sinclair/typebox").TLiteral<"LIKE_COUNT_DESC">]>>;
+        featured: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+        language: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        tagIds: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+        categoryIds: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+        fieldsets: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"URL">, import("@sinclair/typebox").TLiteral<"INTERNAL_ID">, import("@sinclair/typebox").TLiteral<"CONTENT">, import("@sinclair/typebox").TLiteral<"RICH_CONTENT">, import("@sinclair/typebox").TLiteral<"TRANSLATIONS">, import("@sinclair/typebox").TLiteral<"GENERATED_EXCERPT">, import("@sinclair/typebox").TLiteral<"COUNTERS">, import("@sinclair/typebox").TLiteral<"CONTENT_TEXT">]>>>;
+        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>;
+            cursor: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>>;
+    }>;
+    execute: (toolCallId: string, params: {
+        sort?: "PUBLISHED_DATE_ASC" | "PUBLISHED_DATE_DESC" | "VIEW_COUNT_ASC" | "VIEW_COUNT_DESC" | "LIKE_COUNT_ASC" | "LIKE_COUNT_DESC" | undefined;
+        siteId?: string | undefined;
+        paging?: {
+            limit?: number | undefined;
+            offset?: number | undefined;
+            cursor?: string | undefined;
+        } | undefined;
+        fieldsets?: ("URL" | "INTERNAL_ID" | "CONTENT" | "RICH_CONTENT" | "TRANSLATIONS" | "GENERATED_EXCERPT" | "COUNTERS" | "CONTENT_TEXT")[] | undefined;
+        tagIds?: string[] | undefined;
+        categoryIds?: string[] | undefined;
+        featured?: boolean | undefined;
+        language?: string | undefined;
+    }, signal?: AbortSignal) => Promise<import("@mariozechner/pi-agent-core").AgentToolResult<{
+        status: "ok" | "failed";
+        data?: unknown;
+        error?: string;
+    }>>;
 } | {
     name: string;
     description: string;
@@ -114,9 +176,11 @@ export declare function buildBlogTools(client: WixClient): ({
     parameters: import("@sinclair/typebox").TObject<{
         siteId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         postId: import("@sinclair/typebox").TString;
+        fieldsets: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"URL">, import("@sinclair/typebox").TLiteral<"INTERNAL_ID">, import("@sinclair/typebox").TLiteral<"CONTENT">, import("@sinclair/typebox").TLiteral<"RICH_CONTENT">, import("@sinclair/typebox").TLiteral<"TRANSLATIONS">, import("@sinclair/typebox").TLiteral<"GENERATED_EXCERPT">, import("@sinclair/typebox").TLiteral<"COUNTERS">, import("@sinclair/typebox").TLiteral<"CONTENT_TEXT">]>>>;
     }>;
     execute: (toolCallId: string, params: {
         siteId?: string | undefined;
+        fieldsets?: ("URL" | "INTERNAL_ID" | "CONTENT" | "RICH_CONTENT" | "TRANSLATIONS" | "GENERATED_EXCERPT" | "COUNTERS" | "CONTENT_TEXT")[] | undefined;
         postId: string;
     }, signal?: AbortSignal) => Promise<import("@mariozechner/pi-agent-core").AgentToolResult<{
         status: "ok" | "failed";
@@ -129,9 +193,37 @@ export declare function buildBlogTools(client: WixClient): ({
     label: string;
     parameters: import("@sinclair/typebox").TObject<{
         siteId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        postId: import("@sinclair/typebox").TString;
     }>;
     execute: (toolCallId: string, params: {
         siteId?: string | undefined;
+        postId: string;
+    }, 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>;
+        language: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        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>;
+            cursor: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>>;
+    }>;
+    execute: (toolCallId: string, params: {
+        siteId?: string | undefined;
+        paging?: {
+            limit?: number | undefined;
+            offset?: number | undefined;
+            cursor?: string | undefined;
+        } | undefined;
+        language?: string | undefined;
     }, signal?: AbortSignal) => Promise<import("@mariozechner/pi-agent-core").AgentToolResult<{
         status: "ok" | "failed";
         data?: unknown;

package/dist/tools/blog.js

@@ -5,11 +5,43 @@
 // (create/update/publish/unpublish/delete) are pattern-validated against
 // the published Wix Blog REST docs but were not exercised live to avoid
 // polluting the production blog.
+//
+// `wix_blog_list_drafts` and `wix_blog_list_published` are FLAT GET
+// endpoints — they accept named query params (`status`, `featured`,
+// `tagIds`, `categoryIds`, `language`, `sort`, `fieldsets`,
+// `paging.limit`, `paging.offset`) but NOT the MongoDB-style operator
+// passthrough used by POST `/query` endpoints. Hence no `filter`
+// passthrough here — exposing one would silently get dropped by Wix.
 import { Type } from "@sinclair/typebox";
 import { defineWixTool } from "./_factory.js";
+import { WixGetPagingEnvelopeSchema, buildGetPagingQuery, compactQuery, } from "./_query.js";
 const SiteIdParam = Type.Optional(Type.String({
     description: "Wix site UUID. Optional — falls back to defaultSiteId when omitted. Must be in allowedSiteIds.",
 }));
+// `fieldsets` enum — verified live on /blog/v3/draft-posts and
+// /blog/v3/posts. UNKNOWN exists in the schema but is a no-op.
+const FieldsetsParam = Type.Optional(Type.Array(Type.Union([
+    Type.Literal("URL"),
+    Type.Literal("INTERNAL_ID"),
+    Type.Literal("CONTENT"),
+    Type.Literal("RICH_CONTENT"),
+    Type.Literal("TRANSLATIONS"),
+    Type.Literal("GENERATED_EXCERPT"),
+    // Posts-only — Wix accepts COUNTERS / CONTENT_TEXT on /posts but
+    // rejects them on /draft-posts. We keep the union loose; bad
+    // values surface as a clean Wix 400 the model can react to.
+    Type.Literal("COUNTERS"),
+    Type.Literal("CONTENT_TEXT"),
+]), {
+    description: "Optional response projection. URL adds `url`, RICH_CONTENT adds Ricos body, COUNTERS/CONTENT_TEXT are posts-only. See https://dev.wix.com/docs/rest/business-management/blog",
+}));
+// Encode array params as comma-separated values — what Wix's GET
+// endpoints expect for `tagIds`, `categoryIds`, `fieldsets`.
+function csv(values) {
+    if (!values || values.length === 0)
+        return undefined;
+    return values.join(",");
+}
 export function buildBlogTools(client) {
     return [
         // -------------------------------------------------------------------
@@ -17,20 +49,44 @@ export function buildBlogTools(client) {
         // -------------------------------------------------------------------
         defineWixTool({
             name: "wix_blog_list_drafts",
-            description: "List blog draft posts (not yet published). Supports paging and basic filtering.",
+            description: "List blog draft posts. Supports filtering by status, sorting, " +
+                "field projection, and offset paging. Default behaviour returns " +
+                "drafts with all statuses (UNPUBLISHED, PUBLISHED-snapshots, " +
+                "SCHEDULED, IN_REVIEW) — pass `status` to narrow.",
             parameters: Type.Object({
                 siteId: SiteIdParam,
-                paging: Type.Optional(Type.Object({
-                    limit: Type.Optional(Type.Number({ minimum: 1, maximum: 100 })),
-                    offset: Type.Optional(Type.Number({ minimum: 0 })),
+                // Status enum verified live against Wix:
+                //   UNPUBLISHED, PUBLISHED, SCHEDULED, IN_REVIEW are accepted.
+                //   ALL is a CLIENT-SIDE convention — we map it to "no status
+                //   param" because Wix returns 400 for any unknown status value.
+                status: Type.Optional(Type.Union([
+                    Type.Literal("UNPUBLISHED"),
+                    Type.Literal("PUBLISHED"),
+                    Type.Literal("SCHEDULED"),
+                    Type.Literal("IN_REVIEW"),
+                    Type.Literal("ALL"),
+                ], {
+                    description: "Draft status filter. ALL (default) returns drafts with every status — same as omitting the parameter. PUBLISHED returns drafts that are also currently published (the live snapshot).",
                 })),
+                sort: Type.Optional(Type.Union([
+                    Type.Literal("EDITING_DATE_ASC"),
+                    Type.Literal("EDITING_DATE_DESC"),
+                ], {
+                    description: "Sort order. Defaults to EDITING_DATE_DESC (most recently edited first).",
+                })),
+                fieldsets: FieldsetsParam,
+                paging: Type.Optional(WixGetPagingEnvelopeSchema),
             }),
             run: (params) => client.request("GET", "/blog/v3/draft-posts", {
                 siteId: params.siteId,
-                query: {
-                    "paging.limit": params.paging?.limit,
-                    "paging.offset": params.paging?.offset,
-                },
+                query: compactQuery({
+                    // Map our `ALL` shortcut → omit the param so we get the
+                    // documented "all statuses" default.
+                    status: params.status === "ALL" ? undefined : params.status,
+                    sort: params.sort,
+                    fieldsets: csv(params.fieldsets),
+                    ...buildGetPagingQuery(params.paging),
+                }),
             }),
         }, client),
         defineWixTool({
@@ -39,8 +95,12 @@ export function buildBlogTools(client) {
             parameters: Type.Object({
                 siteId: SiteIdParam,
                 draftPostId: Type.String({ description: "Draft post id" }),
+                fieldsets: FieldsetsParam,
+            }),
+            run: (params) => client.request("GET", `/blog/v3/draft-posts/${encodeURIComponent(params.draftPostId)}`, {
+                siteId: params.siteId,
+                query: compactQuery({ fieldsets: csv(params.fieldsets) }),
             }),
-            run: (params) => client.request("GET", `/blog/v3/draft-posts/${encodeURIComponent(params.draftPostId)}`, { siteId: params.siteId }),
         }, client),
         defineWixTool({
             name: "wix_blog_create_draft",
@@ -131,20 +191,42 @@ export function buildBlogTools(client) {
         // -------------------------------------------------------------------
         defineWixTool({
             name: "wix_blog_list_published",
-            description: "List published blog posts. Supports paging.",
+            description: "List published blog posts. Supports sorting, language filter, " +
+                "tag/category filtering, field projection, and offset paging.",
             parameters: Type.Object({
                 siteId: SiteIdParam,
-                paging: Type.Optional(Type.Object({
-                    limit: Type.Optional(Type.Number({ minimum: 1, maximum: 100 })),
-                    offset: Type.Optional(Type.Number({ minimum: 0 })),
+                // Sort enum verified live: PUBLISHED_DATE_DESC works.
+                // Wix docs also list PUBLISHED_DATE_ASC and VIEW_COUNT_*.
+                sort: Type.Optional(Type.Union([
+                    Type.Literal("PUBLISHED_DATE_ASC"),
+                    Type.Literal("PUBLISHED_DATE_DESC"),
+                    Type.Literal("VIEW_COUNT_ASC"),
+                    Type.Literal("VIEW_COUNT_DESC"),
+                    Type.Literal("LIKE_COUNT_ASC"),
+                    Type.Literal("LIKE_COUNT_DESC"),
+                ])),
+                featured: Type.Optional(Type.Boolean({
+                    description: "If true, only featured posts. Default false (no filter).",
+                })),
+                language: Type.Optional(Type.String({
+                    description: "ISO 639-1 language code (e.g. `fr`, `en`). Wix returns 200 + empty list when language is not configured on the site.",
                 })),
+                tagIds: Type.Optional(Type.Array(Type.String())),
+                categoryIds: Type.Optional(Type.Array(Type.String())),
+                fieldsets: FieldsetsParam,
+                paging: Type.Optional(WixGetPagingEnvelopeSchema),
             }),
             run: (params) => client.request("GET", "/blog/v3/posts", {
                 siteId: params.siteId,
-                query: {
-                    "paging.limit": params.paging?.limit,
-                    "paging.offset": params.paging?.offset,
-                },
+                query: compactQuery({
+                    sort: params.sort,
+                    featured: params.featured,
+                    language: params.language,
+                    tagIds: csv(params.tagIds),
+                    categoryIds: csv(params.categoryIds),
+                    fieldsets: csv(params.fieldsets),
+                    ...buildGetPagingQuery(params.paging),
+                }),
             }),
         }, client),
         defineWixTool({
@@ -153,8 +235,12 @@ export function buildBlogTools(client) {
             parameters: Type.Object({
                 siteId: SiteIdParam,
                 postId: Type.String(),
+                fieldsets: FieldsetsParam,
+            }),
+            run: (params) => client.request("GET", `/blog/v3/posts/${encodeURIComponent(params.postId)}`, {
+                siteId: params.siteId,
+                query: compactQuery({ fieldsets: csv(params.fieldsets) }),
             }),
-            run: (params) => client.request("GET", `/blog/v3/posts/${encodeURIComponent(params.postId)}`, { siteId: params.siteId }),
         }, client),
         defineWixTool({
             name: "wix_blog_unpublish",
@@ -173,17 +259,33 @@ export function buildBlogTools(client) {
         defineWixTool({
             name: "wix_blog_list_categories",
             description: "List blog categories (used to classify posts).",
-            parameters: Type.Object({ siteId: SiteIdParam }),
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                language: Type.Optional(Type.String()),
+                paging: Type.Optional(WixGetPagingEnvelopeSchema),
+            }),
             run: (params) => client.request("GET", "/blog/v3/categories", {
                 siteId: params.siteId,
+                query: compactQuery({
+                    language: params.language,
+                    ...buildGetPagingQuery(params.paging),
+                }),
             }),
         }, client),
         defineWixTool({
             name: "wix_blog_list_tags",
             description: "List blog tags.",
-            parameters: Type.Object({ siteId: SiteIdParam }),
+            parameters: Type.Object({
+                siteId: SiteIdParam,
+                language: Type.Optional(Type.String()),
+                paging: Type.Optional(WixGetPagingEnvelopeSchema),
+            }),
             run: (params) => client.request("GET", "/blog/v3/tags", {
                 siteId: params.siteId,
+                query: compactQuery({
+                    language: params.language,
+                    ...buildGetPagingQuery(params.paging),
+                }),
             }),
         }, client),
     ];