@jskit-ai/connectors-catalog 0.2.2 → 0.2.4

package/src/server/wixStores.js

@@ -0,0 +1,296 @@
+import { ConnectorError } from "@jskit-ai/connectors-core/server";
+import { createSchema } from "json-rest-schema";
+import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
+import { requestPath, sameRecord, cursor, contactIdField, nativeJsonObjectField } from "./wixValues.js";
+import { isUuid } from "../shared/uuid.js";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+
+// Wix eCommerce and Stores operations: carts, products, catalog version, orders, fulfillments and business locations.
+
+function productReadOperation(version, action) {
+  const schema = createSchema(action === "get" ? {
+    productId: { type: "string", required: true, validator: value => isUuid(value) || "Use the Wix product ID." }
+  } : {
+    limit: { type: "integer", min: 1, max: 100, defaultTo: 20 },
+    ...(version === 1 ? { offset: { type: "integer", min: 0, max: 100000, defaultTo: 0 }, includeVariants: { type: "boolean", defaultTo: false } } :
+      { cursor: { type: "string", validator: value => cursor(value) || "Use the returned product cursor." } })
+  });
+  const validProduct = value => isUuid(value?.id) && typeof value.name === "string" && value.name.length > 0;
+  return {
+    scopes: [],
+    request(input) {
+      const value = validateSchemaPayload({ schema, mode: "replace" }, input, { statusCode: 422 });
+      const base = version === 1 ? "https://www.wixapis.com/stores-reader/v1/products" : "https://www.wixapis.com/stores/v3/products";
+      if (action === "get") return { method: "GET", url: `${base}/${value.productId}` };
+      const { includeVariants, ...paging } = value;
+      return { method: "POST", url: `${base}/query`,
+        body: version === 1 ? { query: { paging }, includeVariants } : { query: { cursorPaging: paging } } };
+    },
+    validateResult: (value, request) => action === "get" ? validProduct(value?.product) && sameRecord(value.product.id === requestPath(request, -1), "Wix returned a different product.", { messageCode: "connectors.wix.returnedDifferentProduct" }) : Array.isArray(value?.products) && value.products.length <= 100 && value.products.every(validProduct) &&
+      (version === 1 ? (value.totalResults === undefined || Number.isSafeInteger(value.totalResults) && value.totalResults >= 0) &&
+        (value.metadata === undefined || isRecord(value.metadata) &&
+          ["items", "offset"].every(key => value.metadata[key] === undefined || Number.isSafeInteger(value.metadata[key]) && value.metadata[key] >= 0)) :
+        (value.pagingMetadata === undefined || isRecord(value.pagingMetadata) &&
+          (value.pagingMetadata.cursors === undefined || isRecord(value.pagingMetadata.cursors) &&
+            ["next", "prev"].every(key => value.pagingMetadata.cursors[key] === undefined || cursor(value.pagingMetadata.cursors[key])))))
+  };
+}
+function locationWriteOperation(action) {
+  const schema = createSchema({
+    ...(action === "update" ? {
+      locationId: contactIdField,
+      revision: { type: "none", required: true, validator: value => typeof value === "string" && /^\d{1,19}$/u.test(value) && BigInt(value) <= 9223372036854775807n || "Use the current location revision string." }
+    } : {}),
+    name: { type: "string", required: true, minLength: 1, maxLength: 150 },
+    timeZone: { type: "string", required: true, maxLength: 150, validator: value => {
+      try { new Intl.DateTimeFormat("en", { timeZone: value }); return true; } catch { return "Use an IANA time zone."; }
+    } },
+    description: { type: "string", maxLength: 500 }, email: { type: "string", maxLength: 320 },
+    phone: { type: "string", maxLength: 100 }, fax: { type: "string", maxLength: 100 },
+    status: { type: "string", enum: ["ACTIVE"] },
+    locationTypes: { type: "array", validator: values => values.length <= 10 || "Use at most 10 location types.", items: { type: "string", enum: ["UNKNOWN", "BRANCH", "OFFICES", "RECEPTION", "HEADQUARTERS", "INVENTORY"] } },
+    businessSchedule: nativeJsonObjectField, extendedFields: nativeJsonObjectField,
+    address: { type: "object", required: true, schema: createSchema({
+      country: { type: "string", validator: value => /^[A-Z]{2}$/u.test(value) || "Use a two-letter country code." },
+      subdivision: { type: "string", maxLength: 100 }, city: { type: "string", maxLength: 1000 }, postalCode: { type: "string", maxLength: 20 },
+      formattedAddress: { type: "string", maxLength: 4000 }, hint: { type: "string", maxLength: 500 },
+      streetAddress: { type: "object", schema: createSchema({ number: { type: "string", maxLength: 100 }, name: { type: "string", maxLength: 1000 }, apt: { type: "string", maxLength: 100 } }) },
+      geocode: { type: "object", schema: createSchema({ latitude: { type: "number", required: true, min: -90, max: 90 }, longitude: { type: "number", required: true, min: -180, max: 180 } }) }
+    }) }
+  });
+  return {
+    scopes: [],
+    request(input) {
+      const { locationId, ...location } = validateSchemaPayload({ schema, mode: "replace" }, input, { statusCode: 422 });
+      if (!Object.keys(location.address).length) throw new ConnectorError("connector_input_invalid", "Provide the location address.", { statusCode: 422, messageCode: "connectors.wix.provideLocationAddress" });
+      if (location.businessSchedule && (["periods", "specialHourPeriod"].some(key => location.businessSchedule[key] !== undefined &&
+          (!Array.isArray(location.businessSchedule[key]) || location.businessSchedule[key].length > 100)) ||
+          Object.keys(location.businessSchedule).some(key => !["periods", "specialHourPeriod"].includes(key)))) {
+        throw new ConnectorError("connector_input_invalid", "Use native businessSchedule periods and specialHourPeriod arrays with at most 100 entries each.", { statusCode: 422, messageCode: "connectors.wix.businessScheduleLimits" });
+      }
+      return { method: action === "create" ? "POST" : "PUT", url: `https://www.wixapis.com/locations/v1/locations${locationId ? `/${locationId}` : ""}`,
+        body: { location: { ...(locationId ? { id: locationId } : {}), ...location } } };
+    },
+    validateResult: (value, request) => validLocation(value?.location) && typeof value.location.revision === "string" && /^\d{1,19}$/u.test(value.location.revision) &&
+      (action === "create" || sameRecord(value.location.id === requestPath(request, -1), "Wix returned a different business location.", { messageCode: "connectors.wix.returnedDifferentBusinessLocation" }))
+  };
+}
+function locationActionOperation(action) {
+  const schema = createSchema({ locationId: contactIdField });
+  return {
+    scopes: [],
+    request(input) {
+      const { locationId } = validateSchemaPayload({ schema, mode: "replace" }, input, { statusCode: 422 });
+      return { method: "POST", url: `https://www.wixapis.com/locations/v1/locations/${locationId}/${action}`,
+        body: {} };
+    },
+    validateResult: (value, request) => validLocation(value?.location) && sameRecord(value.location.id === requestPath(request, -2), "Wix returned a different business location.", { messageCode: "connectors.wix.returnedDifferentBusinessLocation" }) &&
+      (action === "archive" ? value.location.archived === true : value.location.default === true)
+  };
+}
+const locationQuerySchema = createSchema({
+  limit: { type: "integer", min: 1, max: 100, defaultTo: 20 }, offset: { type: "integer", min: 0, max: 100000, defaultTo: 0 },
+  archived: { type: "boolean", defaultTo: false }
+});
+const locationGetSchema = createSchema({ locationId: { type: "string", required: true, validator: value => isUuid(value) || "Use the returned location ID." } });
+const validLocation = value => isUuid(value?.id) && typeof value.name === "string" &&
+  (value.timeZone === undefined || typeof value.timeZone === "string") && (value.archived === undefined || typeof value.archived === "boolean");
+const productV1UpdateSchema = createSchema({
+  productId: { type: "string", required: true, validator: value => isUuid(value) || "Use the Wix product ID." },
+  name: { type: "string", minLength: 1, maxLength: 80 }, visible: { type: "boolean" },
+  price: { type: "none", validator: value => typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 999999999.99 || "Use a numeric Wix base price from 0 to 999999999.99." }
+});
+const productV3UpdateSchema = createSchema({
+  productId: { type: "string", required: true, validator: value => isUuid(value) || "Use the Wix product ID." },
+  revision: { type: "none", required: true, validator: value => typeof value === "string" && /^\d{1,19}$/u.test(value) && BigInt(value) <= 9223372036854775807n || "Use the current product revision string." },
+  name: { type: "string", minLength: 1, maxLength: 80 },
+  visible: { type: "boolean" }
+});
+const catalogVersionSchema = createSchema({});
+const orderSearchSchema = createSchema({
+  limit: { type: "integer", min: 1, max: 100, defaultTo: 20 },
+  cursor: { type: "string", validator: value => cursor(value) || "Use the returned order cursor." },
+  status: { type: "string", minLength: 1, maxLength: 100 },
+  contactId: { type: "string", validator: value => isUuid(value) || "Use the buyer's contact ID." }
+});
+const orderIdSchema = createSchema({ orderId: { type: "string", required: true, minLength: 1, maxLength: 100, validator: value => !/[\p{Cc}]/u.test(value) && ![".", ".."].includes(value) || "Use the returned order ID." } });
+const cartCreateSchema = createSchema({
+  note: { type: "string", maxLength: 1000 },
+  catalogItems: { type: "array", required: true, validator: values => values.length > 0 && values.length <= 300 || "Select 1–300 catalogue items.",
+    items: { type: "object", schema: createSchema({
+      quantity: { type: "integer", required: true, min: 1, max: 100000 },
+      catalogReference: { type: "object", required: true, schema: createSchema({
+        appId: { type: "string", required: true, validator: value => isUuid(value) || "Use the catalogue app ID." },
+        catalogItemId: { type: "string", required: true, minLength: 1, maxLength: 36, validator: value => !/[\p{Cc}]/u.test(value) || "Use the selected catalogue item ID." },
+        options: nativeJsonObjectField
+      }) }
+    }) } }
+});
+const cartIdSchema = createSchema({ cartId: { type: "string", required: true, validator: value => isUuid(value) || "Use the cart ID returned by Wix." } });
+const validOrder = value => typeof value?.id === "string" && value.id.length > 0 && value.id.length <= 100 &&
+  typeof value.status === "string" && value.status.length > 0 && (value.currency === undefined || typeof value.currency === "string") &&
+  (value.lineItems === undefined || Array.isArray(value.lineItems));
+function fulfillmentWriteOperation(update) {
+  const trackingSchema = createSchema({
+    trackingNumber: { type: "string", minLength: 1, maxLength: 100 },
+    shippingProvider: { type: "string", minLength: 1, maxLength: 100 },
+    trackingLink: { type: "string", minLength: 1, maxLength: 2048, validator: value => {
+      try { const url = new URL(value); return ["https:", "http:"].includes(url.protocol) && !url.username && !url.password || "Use a public tracking URL."; }
+      catch { return "Use a public tracking URL."; }
+    } }
+  });
+  const schema = createSchema({
+    orderId: { type: "string", required: true, minLength: 1, maxLength: 100, validator: value => !/[\p{Cc}]/u.test(value) && ![".", ".."].includes(value) || "Use the returned order ID." },
+    ...(update ? { fulfillmentId: contactIdField } : {}),
+    lineItems: { type: "array", required: !update, validator: values => values.length > 0 && values.length <= 300 && new Set(values.map(item => item?.id)).size === values.length || "Select 1–300 distinct order line items.",
+      items: { type: "object", schema: createSchema({ id: contactIdField, quantity: { type: "integer", required: true, min: 1, max: 100000 } }) } },
+    trackingInfo: { type: "object", schema: trackingSchema },
+    status: { type: "string", enum: ["Pending", "Accepted", "Ready", "In_Delivery", "Fulfilled"] },
+    completed: { type: "boolean" }
+  });
+  return {
+    scopes: [],
+    request(input) {
+      const { orderId, fulfillmentId, ...fulfillment } = validateSchemaPayload({ schema, mode: "replace" }, input, { statusCode: 422 });
+      if (!Object.keys(fulfillment).length || fulfillment.trackingInfo && !Object.keys(fulfillment.trackingInfo).length) {
+        throw new ConnectorError("connector_input_invalid", "Supply the fulfillment properties to write.", { statusCode: 422, messageCode: "connectors.wix.supplyFulfillmentPropertiesWrite" });
+      }
+      const tracking = fulfillment.trackingInfo;
+      if (!update && tracking && (!tracking.trackingNumber || !tracking.shippingProvider ||
+          !["fedex", "ups", "usps", "dhl", "canadaPost"].includes(tracking.shippingProvider) && !tracking.trackingLink)) {
+        throw new ConnectorError("connector_input_invalid", "Supply tracking number and provider; custom carriers also require a tracking URL.", { statusCode: 422, messageCode: "connectors.wix.supplyTrackingNumberProviderCustom" });
+      }
+      return { method: update ? "PATCH" : "POST", url: update
+        ? `https://www.wixapis.com/ecom/v1/fulfillments/${fulfillmentId}/orders/${encodeURIComponent(orderId)}`
+        : `https://www.wixapis.com/ecom/v1/fulfillments/orders/${encodeURIComponent(orderId)}/create-fulfillment`,
+        body: { fulfillment } };
+    },
+    validateResult: (value, request) => typeof value?.orderWithFulfillments?.orderId === "string" &&
+      sameRecord(value.orderWithFulfillments.orderId === requestPath(request, update ? -1 : -2), "Wix returned fulfillments for a different order.", { messageCode: "connectors.wix.returnedFulfillmentsDifferentOrder" }) &&
+      Array.isArray(value.orderWithFulfillments.fulfillments) &&
+      value.orderWithFulfillments.fulfillments.every(item => isUuid(item?.id) && Array.isArray(item.lineItems) && item.lineItems.length <= 300 &&
+        item.lineItems.every(line => isUuid(line?.id) && Number.isInteger(line.quantity) && line.quantity >= 1 && line.quantity <= 100000)) &&
+      (update ? sameRecord(value.orderWithFulfillments.fulfillments.some(item => item.id === requestPath(request, -3)),
+        "Wix did not return the updated fulfillment. Inspect the order before retrying.", { messageCode: "connectors.wix.didNotReturnUpdatedFulfillment" }) :
+        isUuid(value.fulfillmentId) && value.orderWithFulfillments.fulfillments.some(item => item.id === value.fulfillmentId))
+  };
+}
+const wixStoreOperations = {
+  "carts.create": {
+    scopes: [],
+    request(input) {
+      const { note, catalogItems } = validateSchemaPayload({ schema: cartCreateSchema, mode: "replace" }, input, { statusCode: 422 });
+      return { method: "POST", url: "https://www.wixapis.com/ecom/v2/carts",
+        body: { cart: { source: { channelType: "WEB" }, ...(note === undefined ? {} : { note }) }, catalogItems } };
+    },
+    validateResult: value => isUuid(value?.cart?.id) && Array.isArray(value.cart.lineItems) && value.cart.lineItems.length <= 300 &&
+      value.cart.lineItems.every(item => isUuid(item?.id))
+  },
+  "carts.getCheckoutUrl": {
+    scopes: [],
+    request(input) {
+      const { cartId } = validateSchemaPayload({ schema: cartIdSchema, mode: "replace" }, input, { statusCode: 422 });
+      return { method: "POST", url: `https://www.wixapis.com/ecom/v2/carts/${cartId}/get-checkout-url`, body: {} };
+    },
+    validateResult(value) {
+      if (typeof value?.checkoutUrl !== "string" || value.checkoutUrl.length > 8000 || /[\p{Cc}]/u.test(value.checkoutUrl)) return false;
+      try { const url = new URL(value.checkoutUrl); return url.protocol === "https:" && !url.username && !url.password; } catch { return false; }
+    }
+  },
+  "locations.archive": locationActionOperation("archive"),
+  "locations.setDefault": locationActionOperation("set-default"),
+  "locations.create": locationWriteOperation("create"),
+  "locations.update": locationWriteOperation("update"),
+  "locations.list": {
+    scopes: [],
+    request(input) {
+      const { archived, ...paging } = validateSchemaPayload({ schema: locationQuerySchema, mode: "replace" }, input, { statusCode: 422 });
+      return { method: "POST", url: "https://www.wixapis.com/locations/v1/locations/query",
+        body: { query: { filter: { archived }, paging }, filterAuthorizedLocationEntities: true } };
+    },
+    validateResult: value => Array.isArray(value?.locations) && value.locations.length <= 100 && value.locations.every(validLocation) &&
+      (value.pagingMetadata === undefined || isRecord(value.pagingMetadata) &&
+        ["count", "offset", "total"].every(key => value.pagingMetadata[key] === undefined || Number.isSafeInteger(value.pagingMetadata[key]) && value.pagingMetadata[key] >= 0))
+  },
+  "locations.get": {
+    scopes: [],
+    request(input) {
+      const { locationId } = validateSchemaPayload({ schema: locationGetSchema, mode: "replace" }, input, { statusCode: 422 });
+      return { method: "GET", url: `https://www.wixapis.com/locations/v1/locations/${locationId}` };
+    },
+    validateResult: (value, request) => validLocation(value?.location) && sameRecord(value.location.id === requestPath(request, -1), "Wix returned a different business location.", { messageCode: "connectors.wix.returnedDifferentBusinessLocation" })
+  },
+  "productsV1.list": productReadOperation(1, "list"),
+  "productsV1.get": productReadOperation(1, "get"),
+  "productsV1.update": {
+    scopes: [],
+    request(input) {
+      const { productId, price, ...changes } = validateSchemaPayload({ schema: productV1UpdateSchema, mode: "replace" }, input, { statusCode: 422 });
+      if (!Object.keys(changes).length && price === undefined) throw new ConnectorError("connector_input_invalid", "Provide a product name, visibility or base-price change.", { statusCode: 422, messageCode: "connectors.wix.provideProductNameVisibilityBase" });
+      return { method: "PATCH", url: `https://www.wixapis.com/stores/v1/products/${productId}`,
+        body: { product: { ...changes, ...(price === undefined ? {} : { priceData: { price } }) } } };
+    },
+    validateResult: (value, request) => isUuid(value?.product?.id) && typeof value.product.name === "string" && value.product.name.length > 0 &&
+      sameRecord(value.product.id === requestPath(request, -1), "Wix returned a different product.", { messageCode: "connectors.wix.returnedDifferentProduct" })
+  },
+  "productsV3.list": productReadOperation(3, "list"),
+  "productsV3.get": productReadOperation(3, "get"),
+  "productsV3.update": {
+    scopes: [],
+    request(input) {
+      const { productId, revision, ...changes } = validateSchemaPayload({ schema: productV3UpdateSchema, mode: "replace" }, input, { statusCode: 422 });
+      if (!Object.keys(changes).length) throw new ConnectorError("connector_input_invalid", "Provide a product name or visibility change.", { statusCode: 422, messageCode: "connectors.wix.provideProductNameVisibilityChange" });
+      return { method: "PATCH", url: `https://www.wixapis.com/stores/v3/products/${productId}`,
+        body: { product: { id: productId, revision, ...changes } } };
+    },
+    validateResult: (value, request) => isUuid(value?.product?.id) && typeof value.product.name === "string" && value.product.name.length > 0 &&
+      sameRecord(value.product.id === requestPath(request, -1), "Wix returned a different product.", { messageCode: "connectors.wix.returnedDifferentProduct" }) &&
+      typeof value.product.revision === "string" && /^\d{1,19}$/u.test(value.product.revision) && BigInt(value.product.revision) <= 9223372036854775807n
+  },
+  "catalog.version": {
+    scopes: [],
+    request(input) {
+      validateSchemaPayload({ schema: catalogVersionSchema, mode: "replace" }, input, { statusCode: 422 });
+      return { method: "GET", url: "https://www.wixapis.com/stores/v3/provision/version" };
+    }, validateResult: value => ["V1_CATALOG", "V3_CATALOG", "STORES_NOT_INSTALLED"].includes(value?.catalogVersion)
+  },
+  "orders.list": {
+    scopes: [],
+    request(input) {
+      const { status, contactId, ...cursorPaging } = validateSchemaPayload({ schema: orderSearchSchema, mode: "replace" }, input, { statusCode: 422 });
+      if (cursorPaging.cursor && (status || contactId)) throw new ConnectorError("connector_input_invalid", "Use only cursor and limit for the next order page.", { statusCode: 422, messageCode: "connectors.wix.useCursorLimitNextOrder" });
+      const filter = { ...(status ? { status } : {}), ...(contactId ? { "buyerInfo.contactId": contactId } : {}) };
+      return { method: "POST", url: "https://www.wixapis.com/ecom/v1/orders/search",
+        body: { search: { cursorPaging, ...(Object.keys(filter).length ? { filter } : {}) } } };
+    },
+    validateResult: value => Array.isArray(value?.orders) && value.orders.length <= 100 && value.orders.every(validOrder) &&
+      (value.metadata === undefined || isRecord(value.metadata) &&
+        (value.metadata.count === undefined || value.metadata.count === value.orders.length) &&
+        (value.metadata.hasNext === undefined || typeof value.metadata.hasNext === "boolean") &&
+        (value.metadata.cursors === undefined || isRecord(value.metadata.cursors) &&
+          ["next", "prev"].every(key => value.metadata.cursors[key] === undefined || cursor(value.metadata.cursors[key]))))
+  },
+  "orders.get": {
+    scopes: [],
+    request(input) {
+      const { orderId } = validateSchemaPayload({ schema: orderIdSchema, mode: "replace" }, input, { statusCode: 422 });
+      return { method: "GET", url: `https://www.wixapis.com/ecom/v1/orders/${encodeURIComponent(orderId)}` };
+    }, validateResult: (value, request) => validOrder(value?.order) && sameRecord(value.order.id === requestPath(request, -1), "Wix returned a different order.", { messageCode: "connectors.wix.returnedDifferentOrder" })
+  },
+  "orderFulfillments.create": fulfillmentWriteOperation(false),
+  "orderFulfillments.update": fulfillmentWriteOperation(true),
+  "orderFulfillments.list": {
+    scopes: [],
+    request(input) {
+      const { orderId } = validateSchemaPayload({ schema: orderIdSchema, mode: "replace" }, input, { statusCode: 422 });
+      return { method: "GET", url: `https://www.wixapis.com/ecom/v1/fulfillments/orders/${encodeURIComponent(orderId)}` };
+    },
+    validateResult: (value, request) => isUuid(value?.orderWithFulfillments?.orderId) &&
+      sameRecord(value.orderWithFulfillments.orderId === requestPath(request, -1), "Wix returned fulfillments for a different order.", { messageCode: "connectors.wix.returnedFulfillmentsDifferentOrder" }) &&
+      Array.isArray(value.orderWithFulfillments.fulfillments) &&
+      value.orderWithFulfillments.fulfillments.every(item => isUuid(item?.id) && Array.isArray(item.lineItems) && item.lineItems.length <= 300 &&
+        item.lineItems.every(line => isUuid(line?.id) && Number.isInteger(line.quantity) && line.quantity >= 1 && line.quantity <= 100000))
+  }
+};
+
+export { wixStoreOperations };

package/src/server/wixValues.js

@@ -0,0 +1,35 @@
+import { ConnectorError } from "@jskit-ai/connectors-core/server";
+import { createSchema } from "json-rest-schema";
+import { isUuid } from "../shared/uuid.js";
+
+// The Wix value checks, fields and record checks the operation groups share.
+
+// Preserve native Wix JSON without silently dropping unsupported values.
+function serializeNativeJson(value) {
+  return JSON.stringify(value, (key, item) => {
+    if (["undefined", "function", "symbol", "bigint"].includes(typeof item) ||
+        typeof item === "number" && !Number.isFinite(item)) throw new Error("JSON required");
+    return item;
+  });
+}
+// Results are checked against the operation's own request; a different record is reported with what Wix got wrong.
+const requestPath = (request, index) => decodeURIComponent(new URL(request.url).pathname.split("/").at(index));
+function sameRecord(matches, message, codes) {
+  if (!matches) throw new ConnectorError("connector_response_invalid", message, { statusCode: 502, ...codes });
+  return true;
+}
+const cursor = (value) => typeof value === "string" && value.length > 0 && value.length <= 16000 && !/[\p{Cc}]/u.test(value);
+const querySchema = createSchema({
+  limit: { type: "integer", min: 1, max: 100, defaultTo: 20 },
+  cursor: { type: "string", minLength: 1, maxLength: 16000, noTrim: true, validator: (value) => cursor(value) || "Use the returned Wix page cursor." }
+});
+const contactIdField = { type: "string", required: true, validator: value => isUuid(value) || "Use the contact ID returned by Wix." };
+const nativeJsonObjectField = { type: "none", validator: value => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return "Use a native Wix JSON object.";
+  try {
+    const json = serializeNativeJson(value);
+    return Buffer.byteLength(json) <= 100000 || "Keep native Wix object data within 100KB.";
+  } catch { return "Use serializable native Wix JSON data."; }
+} };
+
+export { serializeNativeJson, requestPath, sameRecord, cursor, querySchema, contactIdField, nativeJsonObjectField };

package/src/server/wiz.js

@@ -6,8 +6,8 @@ import path from "node:path";
 import { ConnectorError } from "@jskit-ai/connectors-core/server";
 import { validateIntegrationConfiguration } from "@jskit-ai/connectors-core/shared/configuration";
 import { wizDefinition } from "../shared/wiz.js";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
 
-const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 const failure = (code, message, statusCode = 502, codes = {}) => new ConnectorError(code, message, { statusCode, ...codes });
 
 // This process belongs to the scanner, not the application's chat/agent runtime.
@@ -40,11 +40,25 @@ async function runCli(executable, args, options, signal, timeoutMs) {
   });
 }
 
+/**
+ * @param {object} options
+ * @param {Record<string, any>} options.configuration The integration configuration.
+ * @param {import("@jskit-ai/connectors-core/server/types").ConnectorAuthorize} options.authorize
+ * @param {import("@jskit-ai/connectors-core/server/types").ResolveReference} options.resolveReference Resolves the registration's client secret.
+ * @param {import("./types.js").WizScanTargetResolver} options.resolveScanTarget
+ * @param {string} options.executable The installed Wiz CLI's absolute path.
+ * @param {Record<string, string>} [options.environment] The scan worker's PATH, proxy and CA variables.
+ * @param {number} [options.timeoutMs]
+ * @param {number} [options.maxReportBytes]
+ */
 function createWizScanner({ configuration, authorize, resolveReference, resolveScanTarget, executable,
   environment = { PATH: process.env.PATH || "/usr/bin:/bin" }, timeoutMs = 600_000, maxReportBytes = 16 * 1024 * 1024 }) {
   if (!["linux", "darwin"].includes(process.platform)) throw new TypeError("Run Wiz in a Linux or macOS scan worker.");
   if (typeof executable !== "string" || !path.isAbsolute(executable) || executable.includes("\0")) throw new TypeError("Supply the installed Wiz CLI's absolute path.");
-  if (![authorize, resolveReference, resolveScanTarget].every((value) => typeof value === "function")) throw new TypeError("Wiz requires host authorization, secret resolution and source resolution.");
+  // readable-check: allow method-probe - input validation: the application passes its access policy, reference resolver and scan target resolver
+  if (typeof authorize !== "function" || typeof resolveReference !== "function" || typeof resolveScanTarget !== "function") {
+    throw new TypeError("Wiz requires host authorization, secret resolution and source resolution.");
+  }
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 3_600_000) throw new TypeError("Use a scan timeout between 1 and 3600000 milliseconds.");
   if (!Number.isSafeInteger(maxReportBytes) || maxReportBytes < 1 || maxReportBytes > 64 * 1024 * 1024) throw new TypeError("Use a positive report limit of at most 64 MiB.");
   const env = {};
@@ -69,7 +83,7 @@ function createWizScanner({ configuration, authorize, resolveReference, resolveS
     // The browser supplies no filesystem path. The trusted host selects an immutable
     // source snapshot and revision after checking the requesting principal's access.
     const target = await resolveScanTarget({ ...owner }, { integrationId, signal });
-    if (!object(target) || typeof target.directory !== "string" || !path.isAbsolute(target.directory) ||
+    if (!isRecord(target) || typeof target.directory !== "string" || !path.isAbsolute(target.directory) ||
       target.directory.includes("\0") || typeof target.revision !== "string" || !target.revision.trim() || target.revision.length > 512) {
       throw failure("connector_source_invalid", "The host must supply an absolute source directory and revision.", 422, { messageCode: "connectors.wiz.hostMustSupplyAbsoluteSource" });
     }
@@ -103,7 +117,7 @@ function createWizScanner({ configuration, authorize, resolveReference, resolveS
         } finally { await file.close(); }
       } catch { throw failure("connector_response_invalid", "Wiz did not produce a readable report within the configured size limit.", 502, { messageCode: "connectors.wiz.didNotProduceReadableReport" }); }
       const verdict = report?.status?.verdict;
-      if (!object(report) || report.status?.state !== "SUCCESS" || !object(report.result) || !["PASSED_BY_POLICY", "WARN_BY_POLICY", "FAILED_BY_POLICY"].includes(verdict) ||
+      if (!isRecord(report) || report.status?.state !== "SUCCESS" || !isRecord(report.result) || !["PASSED_BY_POLICY", "WARN_BY_POLICY", "FAILED_BY_POLICY"].includes(verdict) ||
         (exitCode === 4 && verdict !== "FAILED_BY_POLICY")) {
         throw failure("connector_response_invalid", "Wiz returned an unsupported or inconsistent scan report.", 502, { messageCode: "connectors.wiz.returnedUnsupportedInconsistentScanReport" });
       }

package/src/server/woocommerce.js

@@ -242,7 +242,7 @@ function refundOperation(action) {
     scopes: [],
     request(input, settings) {
       if (action === "create" && (typeof input?.amount !== "string" || typeof input.api_refund !== "boolean" || typeof input.api_restock !== "boolean" ||
-          input.line_items?.some?.(line => typeof line?.refund_total !== "string"))) {
+          Array.isArray(input.line_items) && input.line_items.some(line => typeof line?.refund_total !== "string"))) {
         throw new ConnectorError("connector_input_invalid", "Choose explicit refund/restock flags and decimal-string amounts.", { statusCode: 422, messageCode: "connectors.woocommerce.chooseExplicitRefundRestockFlags" });
       }
       const { order_id, id, ...fields } = validateSchemaPayload({ schema, mode: "replace" }, input, { statusCode: 422 });

package/src/server/wordpress-com.js

@@ -3,6 +3,7 @@ import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
 import { ConnectorError } from "@jskit-ai/connectors-core/server";
 import { wordpressComDefinition } from "../shared/wordpress-com.js";
 import { jsonOperation } from "./jsonOperation.js";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
 
 const postsSchema = createSchema({
   siteId: { type: "integer", required: true, min: 1, max: Number.MAX_SAFE_INTEGER },
@@ -131,7 +132,7 @@ const wordpressComProvider = Object.freeze({
         }
         return { method: "GET", url: url.href };
       },
-      validateResult: value => value !== null && typeof value === "object" && !Array.isArray(value) &&
+      validateResult: value => isRecord(value) &&
         Object.keys(value).length > 0 && Object.values(value).every(entry => entry !== null && typeof entry === "object")
     },
     "stats.read": siteOperation("", {}, {

package/src/server/workday.js

@@ -3,21 +3,21 @@ import { jsonOperation } from "./jsonOperation.js";
 import { createSchema } from "json-rest-schema";
 import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
 import { ConnectorError } from "@jskit-ai/connectors-core/server";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
 
 function workersUrl(settings) {
   const { host, prefix = "", tenant } = workdayRestEndpoint(settings.restApiEndpoint);
   return `https://${host}${prefix}/api/staffing/v7/${tenant}/workers`;
 }
-const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
-const worker = (value) => object(value) && /^[a-f0-9]{32}$/u.test(value.id) && typeof value.descriptor === "string" &&
+const worker = (value) => isRecord(value) && /^[a-f0-9]{32}$/u.test(value.id) && typeof value.descriptor === "string" &&
   (value.workerId === undefined || typeof value.workerId === "string");
 const pageFields = {
   limit: { type: "integer", min: 1, max: 100, defaultTo: 20 },
   offset: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER, defaultTo: 0 }
 };
-const organizationRecord = (value) => object(value) && typeof value.id === "string" && value.id.length > 0 &&
+const organizationRecord = (value) => isRecord(value) && typeof value.id === "string" && value.id.length > 0 &&
   typeof value.descriptor === "string";
-const organizationPage = (value) => object(value) && !value.error && !value.errors && Number.isSafeInteger(value.total) && value.total >= 0 &&
+const organizationPage = (value) => isRecord(value) && !value.error && !value.errors && Number.isSafeInteger(value.total) && value.total >= 0 &&
   Array.isArray(value.data) && value.data.length <= 100 && value.data.every(organizationRecord);
 function organizationRead(part) {
   const schema = createSchema({
@@ -68,10 +68,10 @@ function absenceRead(kind) {
       return { method: "GET", url: url.href };
     },
     validateResult(value) {
-      return object(value) && !value.error && !value.errors && Number.isSafeInteger(value.total) && value.total >= 0 &&
+      return isRecord(value) && !value.error && !value.errors && Number.isSafeInteger(value.total) && value.total >= 0 &&
         Array.isArray(value.data) && value.data.length <= 100 && value.data.every(row =>
-          kind === "statuses" ? organizationRecord(row) : object(row) && Number.isFinite(row.quantity) && object(row.unit) &&
-            (kind === "balances" ? object(row.absencePlan) : typeof row.date === "string" && object(row.status)));
+          kind === "statuses" ? organizationRecord(row) : isRecord(row) && Number.isFinite(row.quantity) && isRecord(row.unit) &&
+            (kind === "balances" ? isRecord(row.absencePlan) : typeof row.date === "string" && isRecord(row.status)));
     }
   };
 }
@@ -112,7 +112,7 @@ const workdayProvider = Object.freeze({
         if (url.href.length > 16384) throw new ConnectorError("connector_input_invalid", "Use a smaller report prompt request.", { statusCode: 422, messageCode: "connectors.workday.useSmallerReportPromptRequest" });
         return { method: "GET", url: url.href };
       },
-      validateResult: result => object(result) && !result.error && !result.errors && Array.isArray(result.Report_Entry) && result.Report_Entry.every(object)
+      validateResult: result => isRecord(result) && !result.error && !result.errors && Array.isArray(result.Report_Entry) && result.Report_Entry.every(isRecord)
     },
     "timeOff.balances": absenceRead("balances"),
     "timeOff.details": absenceRead("details"),
@@ -129,7 +129,7 @@ const workdayProvider = Object.freeze({
       offset: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER, defaultTo: 0 },
       search: { type: "string", minLength: 1, maxLength: 512, noTrim: true },
       includeTerminatedWorkers: { type: "boolean" }, filterByOrgVisibility: { type: "boolean" }
-    }, (result) => object(result) && !result.error && !result.errors && Number.isSafeInteger(result.total) && result.total >= 0 &&
+    }, (result) => isRecord(result) && !result.error && !result.errors && Number.isSafeInteger(result.total) && result.total >= 0 &&
       Array.isArray(result.data) && result.data.length <= 100 && result.data.every(worker))
   }
 });

package/src/server/x-twitter.js

@@ -2,6 +2,7 @@ import { createSchema } from "json-rest-schema";
 import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
 import { ConnectorError } from "@jskit-ai/connectors-core/server";
 import { xTwitterDefinition } from "../shared/x-twitter.js";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
 
 const validId = (value) => typeof value === "string" && /^[0-9]{1,19}$/u.test(value);
 const validUsername = (value) => typeof value === "string" && /^[A-Za-z0-9_]{1,15}$/u.test(value);
@@ -21,7 +22,7 @@ const searchSchema = createSchema({
   nextToken: { type: "string", noTrim: true, validator: (value) => validCursor(value) || "Use the returned next token." }
 });
 
-const validEnvelope = (value) => value && typeof value === "object" && !Array.isArray(value) && (value.errors === undefined || Array.isArray(value.errors));
+const validEnvelope = (value) => isRecord(value) && (value.errors === undefined || Array.isArray(value.errors));
 // The profile must be the username the request asked for.
 const validUser = (value, request) => validEnvelope(value) && validId(value.data?.id) && validUsername(value.data?.username) &&
   typeof value.data.name === "string" && value.data.username.toLowerCase() === new URL(request.url).pathname.split("/").at(-1).toLowerCase();