@wix/agent-skills 1.14.0 → 1.15.1

package/skills/wix-app/references/STORES_VERSIONING.md

@@ -1,4 +1,3 @@
-
 # Wix Stores Catalog Versioning (V1 / V3)
 
 Wix Stores has two catalog versions that are **NOT backwards compatible**. Apps **must support both** — single-version apps cannot list in the App Market and break on new sites.
@@ -82,214 +81,6 @@ Handle `STORES_NOT_INSTALLED` gracefully — return empty results, do not throw.
 
 ---
 
-## Copy-Paste Recipes
-
-Each recipe handles both versions. `V3Product` and V1 `Product` types are **not** re-exported from `@wix/stores` top-level — let TS infer or use structural types.
-
-### List products with pagination
-
-Both versions expose a fluent query builder, but the paging method differs:
-
-| Aspect | V1 (`products.queryProducts()`) | V3 (`productsV3.queryProducts()`) |
-|--------|--------------------------------|----------------------------------|
-| API style | Fluent builder: `.skip().limit().find()` | Fluent builder: `.skipTo(cursor).limit().find()` |
-| Pagination | Offset (`.skip(n)`) | Cursor (`.skipTo(cursor)`) |
-| Result `items` | `res.items` (V1 `Product[]`) | `res.items` (V3 `Product[]`) |
-| Total count | `res.totalCount` | **None** — V3 only has `cursors.next` + `hasNext()` |
-| `hasNext` | `res.hasNext()` (method) | `res.hasNext()` (method) |
-| Next cursor | n/a | `res.cursors.next` (string) |
-
-```typescript
-import { catalogVersioning, products, productsV3 } from '@wix/stores';
-
-export interface ProductsPage {
-  products: unknown[];        // narrow at call site
-  nextCursor: string | null;  // V3 only
-  hasNext: boolean;
-  totalCount: number | null;  // V1 only
-}
-
-export async function listProductsPage(
-  limit: number,
-  cursorOrSkip: string | number | undefined,
-): Promise<ProductsPage> {
-  const v = await getVersion();
-  if (v === 'STORES_NOT_INSTALLED') {
-    return { products: [], nextCursor: null, hasNext: false, totalCount: 0 };
-  }
-
-  if (v === 'V3_CATALOG') {
-    let builder = productsV3.queryProducts().limit(limit);
-    if (typeof cursorOrSkip === 'string') builder = builder.skipTo(cursorOrSkip);
-    // Do NOT chain a sort — see gotcha #10.
-    const res = await builder.find();
-    return {
-      products: res.items,
-      nextCursor: res.cursors.next ?? null,
-      hasNext: res.hasNext(),
-      totalCount: null,
-    };
-  }
-
-  const skip = typeof cursorOrSkip === 'number' ? cursorOrSkip : 0;
-  const res = await products.queryProducts().skip(skip).limit(limit).find();
-  return {
-    products: res.items,
-    nextCursor: null,
-    hasNext: res.hasNext(),
-    totalCount: res.totalCount ?? null,
-  };
-}
-```
-
-> **Two ways to call V3 `queryProducts`:** the canonical builder shown above, and a direct-call form `productsV3.queryProducts({ cursorPaging: { limit, cursor } })` returning a `Promise<{ products, pagingMetadata }>`. Both compile and run, but the builder is more idiomatic and matches V1's shape.
-
-### Display price/stock without fetching variants
-
-V3 `queryProducts` does not return variants. Read product-level rollup fields instead:
-
-```typescript
-function displayPrice(p: { actualPriceRange?: { minValue?: { amount?: string }; maxValue?: { amount?: string } } }): string {
-  const min = p.actualPriceRange?.minValue?.amount;
-  const max = p.actualPriceRange?.maxValue?.amount;
-  if (!min) return '—';
-  return max && max !== min ? `${min} – ${max}` : min;
-}
-
-function stockLabel(status: string | undefined): string {
-  switch (status) {
-    case 'IN_STOCK': return 'In Stock';
-    case 'OUT_OF_STOCK': return 'Out of Stock';
-    case 'PARTIALLY_OUT_OF_STOCK': return 'Limited';
-    case 'PREORDER': return 'Pre-order';
-    default: return '—';
-  }
-}
-// V1 path: product.stock.inventoryStatus  (same UPPER_SNAKE_CASE values)
-// V3 path: product.inventory.availabilityStatus (adds PREORDER)
-// SKU lives on the variant — show "—" in lists, or use Read-Only Variants API.
-```
-
-### Get a single product
-
-```typescript
-if (v === 'V3_CATALOG') {
-  const product = await productsV3.getProduct(id);  // returns Product directly
-  return product;
-}
-const { product } = await products.getProduct(id);  // V1 wraps in { product }
-return product;
-```
-
-### Create a product (single-variant, with price)
-
-```typescript
-if (v === 'V3_CATALOG') {
-  const product = await productsV3.createProduct({
-    name: 'My Product',
-    productType: 'PHYSICAL',                            // UPPER_CASE
-    variantsInfo: {
-      variants: [{
-        price: { actualPrice: { amount: '19.99' } },    // string, on the variant
-        sku: 'SKU-001',
-      }],
-    },
-  });
-  return product;
-}
-
-const { product } = await products.createProduct({
-  name: 'My Product',
-  productType: 'physical',                              // lower-case
-  priceData: { price: 19.99 },                          // number, on the product
-  sku: 'SKU-001',
-});
-return product;
-```
-
-### Update a product (V3 needs `revision`)
-
-```typescript
-if (v === 'V3_CATALOG') {
-  // Signature: updateProduct(_id, productFields). Returns Product directly.
-  const current = await productsV3.getProduct(id);
-  if (current.revision == null) throw new Error(`Product ${id} has no revision`);
-  return await productsV3.updateProduct(id, {
-    revision: current.revision,  // narrowed — required under exactOptionalPropertyTypes
-    name: 'New name',
-  });
-}
-// V1: updateProduct(id, productFields). Returns { product }.
-const { product } = await products.updateProduct(id, { name: 'New name' });
-return product;
-```
-
-### Delete a product
-
-```typescript
-if (v === 'V3_CATALOG') await productsV3.deleteProduct(id);
-else await products.deleteProduct(id);
-```
-
-### Inventory: increment stock
-
-```typescript
-import { inventory, inventoryItemsV3 } from '@wix/stores';
-
-if (v === 'V3_CATALOG') {
-  // Per-variant; flat shape.
-  await inventoryItemsV3.bulkIncrementInventoryItems([
-    { inventoryItemId, incrementBy: 5 },
-  ]);
-} else {
-  // Per-product (variant optional).
-  await inventory.incrementInventory([
-    { productId, variantId, incrementBy: 5 },
-  ]);
-}
-```
-
-To find a V3 inventory item ID, use `inventoryItemsV3.searchInventoryItems` filtered by `productId` / `variantId`.
-
-### Query inventory
-
-```typescript
-if (v === 'V3_CATALOG') {
-  const res = await inventoryItemsV3.queryInventoryItems().eq('productId', productId).find();
-  return res.items;
-}
-// V1: filter is a JSON-stringified expression.
-const res = await inventory.queryInventory({
-  query: { filter: JSON.stringify({ productId }) },
-});
-return res.inventoryItems;
-```
-
-### Collections (V1) ↔ Categories (V3)
-
-```typescript
-// V1 write ops (createCollection, updateCollection, addProductsToCollection, …)
-// live on the `products` namespace, NOT `collections`. The `collections` namespace is read-only.
-import { products } from '@wix/stores';
-import { categories } from '@wix/categories';
-
-if (v === 'V3_CATALOG') {
-  // V3 createCategory(category, options). treeReference is REQUIRED and goes in `options`.
-  // For Wix Stores categories: appNamespace MUST be the literal "@wix/stores", treeKey is null.
-  const category = await categories.createCategory(
-    { name: 'Sale' },
-    { treeReference: { appNamespace: '@wix/stores', treeKey: null } },
-  );
-  return category;
-}
-const { collection } = await products.createCollection({ name: 'Sale' });  // V1 returns { collection }
-return collection;
-```
-
-V3 categories are tree-structured. Reference them on a product via `directCategories[]`, not `collectionIds[]`. **All Stores category API calls must pass `treeReference: { appNamespace: '@wix/stores', treeKey: null }` in `options`** — applies to `createCategory`, `updateCategory`, `queryCategories`, etc.
-
----
-
 ## V1 → V3 Field Mapping (most common)
 
 For the full table see the [Catalog V1 to V3 Migration Guide](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/catalog-v1-to-v3-migration-guide?apiView=SDK).
@@ -311,6 +102,7 @@ For the full table see the [Catalog V1 to V3 Migration Guide](https://dev.wix.co
 | `collectionIds[i]` | `directCategories[i].id` |
 | `ribbon`, `brand` (string) | `ribbon.name`, `brand.name` (managed via `ribbonsV3` / `brandsV3`) |
 | `media.mainMedia.image.url` (main image URL) | `media.main.image ?? media.main.url` — in V3, `ProductMedia.image` is a `string` (Wix-hosted URL), `url` is a `string` (external URL); check both |
+| `lastUpdated` | `updatedDate` |
 
 **Pricing model** — V1 had a `discount` object; V3 removed it. Discounts are now expressed by the relationship between two fields on the variant: `actualPrice` (required, what the customer pays) vs `compareAtPrice` (optional, original price shown struck through). With discount: V1 `price`/`discountedPrice` → V3 `compareAtPrice`/`actualPrice`. Without discount: V1 `price` → V3 `actualPrice`, leave `compareAtPrice` empty.
 
@@ -330,6 +122,12 @@ Payload changes: V1 `changedFields` → V3 `modifiedFields`. Top-level `entityId
 
 ---
 
-## Falling back to MCP
+## Detailed references
+
+- [stores/QUERY.md](stores/QUERY.md) — list/query products, pagination, price and stock display
+- [stores/GET_PRODUCT.md](stores/GET_PRODUCT.md) — getProduct, options/choices, modifiers, variant choices
+- [stores/WRITE.md](stores/WRITE.md) — create, update, delete products
+- [stores/INVENTORY.md](stores/INVENTORY.md) — inventory read and write operations
+- [stores/CATEGORIES.md](stores/CATEGORIES.md) — collections (V1) ↔ categories (V3)
 
-This file covers the common 80%. For methods not listed (subscriptions, brands, ribbons, etc.) or full request schemas, use `SearchWixSDKDocumentation` then `ReadFullDocsArticle`. Always return the required permission scopes to the user.
+For methods not listed here, use `SearchWixSDKDocumentation` then `ReadFullDocsArticle`. Always return the required permission scopes to the user.

package/skills/wix-app/references/auto-patterns-dashboard/action-cell.md

@@ -0,0 +1,115 @@
+# ActionCell Rules
+
+## Type Definitions
+```typescript
+interface ActionCellConfig {
+  primaryAction?: SinglePrimary | MultiplePrimary;
+  secondaryActions?: {
+    items: (ActionCellItem | DividerItem)[];
+    inlineCount?: number;
+    inlineAlwaysVisible?: boolean;
+  };
+}
+
+interface SinglePrimary {
+  item: ActionCellItem;
+  alwaysVisible?: boolean;
+}
+
+interface MultiplePrimary {
+  items: ActionCellItem[];
+  alwaysVisible?: boolean;
+}
+
+interface ActionCellItem {
+  id: string; // Matches resolver if custom
+  type: 'update' | 'delete' | 'custom';
+  label?: string;
+  biName: string; // MANDATORY
+  skin?: 'standard' | 'inverted' | 'premium' | 'dark' | 'destructive';
+  update?: { mode: 'page'; page: { id: string } };
+  delete?: { mode: 'modal'; modal: ModalConfig };
+}
+
+interface DividerItem {
+  type: 'divider';
+}
+
+// Primary cell action resolver — primary actions don't accept `icon`; use `prefixIcon`/`suffixIcon`.
+type CustomActionCellPrimaryActionResolver = (params: {
+  actionParams: { item: any };
+  sdk: AutoPatternsSDK;
+}) => ResolvedActionCellPrimaryAction;
+// ResolvedActionCellPrimaryAction = Omit<ResolvedAction, 'icon'> & { prefixIcon?: IconElement; suffixIcon?: IconElement }
+
+// Secondary cell action resolver — uses standard ResolvedAction (with `icon`).
+type CustomActionCellSecondaryActionResolver = (params: {
+  actionParams: { item: any };
+  sdk: AutoPatternsSDK;
+}) => ResolvedAction;
+```
+
+## Validation Logic
+- **IF** `type: 'update'` **THEN** `update` config with `page.id` is **REQUIRED**.
+- **IF** `type: 'delete'` **THEN** `delete.mode: 'modal'` is **REQUIRED**.
+- **IF** `type: 'custom'` **THEN** resolver implementation is **REQUIRED**.
+- **IF** `type: 'custom'` **THEN** resolver MUST be registered via override pattern (see **custom_actions_override**).
+- **IF** using `secondaryActions.inlineCount` **THEN** value MUST be <= items count.
+
+## Implementation Rules
+- **MUST** include `biName` for every action (`{action-purpose}-action`).
+- **MUST** place `actionCell` at component level (sibling to `collection`), NOT inside `table`/`grid`.
+- **MUST** implement custom resolvers using `CustomActionCellPrimaryActionResolver` (for primary actions) or `CustomActionCellSecondaryActionResolver` (for secondary actions).
+- **MUST** use `errorHandler` for Wix API calls in resolvers.
+- **SHOULD** use `multiplePrimary` for 2-3 equally important actions.
+- **NEVER** use `primaryAction` inside `secondaryActions`.
+- **NEVER** use `actionResolvers` prop on `AutoPatternsApp` - this prop does not exist.
+- **NEVER** create resolver files outside `components/actions/` folder.
+
+## Canonical Example
+```typescript
+// Config
+actionCell: {
+  primaryAction: {
+    item: {
+      id: 'editItem',
+      type: 'update',
+      label: 'Edit',
+      biName: 'edit-action',
+      skin: 'standard',
+      update: { mode: 'page', page: { id: 'edit-page' } }
+    },
+    alwaysVisible: true
+  },
+  secondaryActions: {
+    items: [
+      {
+        id: 'deleteItem',
+        type: 'delete',
+        label: 'Delete',
+        biName: 'delete-action',
+        skin: 'destructive',
+        delete: { mode: 'modal', modal: {} }
+      }
+    ]
+  }
+}
+
+// Resolvers (if custom) - see custom_actions_override for full registration pattern
+
+// Primary action resolver: use prefixIcon (icon is not allowed on primary cell actions)
+export const myPrimaryAction: CustomActionCellPrimaryActionResolver = ({ actionParams }) => ({
+  label: 'Custom',
+  prefixIcon: <MyIcon />,
+  biName: 'custom-action',
+  onClick: () => console.log(actionParams.item)
+});
+
+// Secondary action resolver: uses icon
+export const mySecondaryAction: CustomActionCellSecondaryActionResolver = ({ actionParams }) => ({
+  label: 'Custom',
+  icon: <MyIcon />,
+  biName: 'custom-action',
+  onClick: () => console.log(actionParams.item)
+});
+```

package/skills/wix-app/references/auto-patterns-dashboard/app-config-structure.md

@@ -0,0 +1,264 @@
+# AppConfig Rules
+
+## Type Definitions
+```typescript
+export interface AppConfig {
+  pages: PageConfig[];
+}
+
+type PageConfig = CollectionPageConfig | EntityPageConfig;
+
+interface PageBase {
+  id: string; // Unique across app
+  appMainPage?: boolean; // ONE page must be true
+}
+
+interface CollectionPageConfig extends PageBase {
+  type: 'collectionPage';
+  collectionPage: {
+    route: { path: string };
+    title: { text: string; hideTotal?: boolean };
+    subtitle?: { text: string };
+    actions?: PageActions;
+    components: [CollectionComponent | CustomComponent]; // EXACTLY ONE component with layout
+  };
+}
+
+interface EntityPageConfig extends PageBase {
+  type: 'entityPage';
+  entityPage: {
+    mode?: 'edit' | 'view'; // Default 'edit'
+    route: { path: string; params: { id: string } };
+    title?: { text: string; badges?: { id?: string } };
+    subtitle?: { text: string; id?: string };
+    actions?: EntityPageActions;
+    parentPageId?: string; // ID of parent collection page
+    collectionId: string;
+    entityTypeSource: 'cms' | 'custom';
+    custom?: { id: string }; // REQUIRED if entityTypeSource='custom'
+    layout?: {
+      main: CardLayout[];
+      sidebar?: CardLayout[];
+    };
+  };
+}
+
+// Action Types
+interface PageActions {
+  primaryActions?: ActionGroup;
+  secondaryActions?: ActionGroup;
+}
+
+interface EntityPageActions {
+  primaryActions?: ActionGroup; // View mode only
+  secondaryActions?: ActionGroup; // View mode only
+  moreActions?: CustomAction[]; // Both modes
+}
+
+type ActionGroup = { type: 'action'; action?: { item: ActionItem } } | { type: 'menu'; menu?: { label: string; items: ActionItem[] } };
+
+interface ActionItem {
+  id: string;
+  type: 'create' | 'update' | 'delete' | 'custom' | 'bulkDelete';
+  label?: string;
+  biName: string; // MANDATORY
+  skin?: string;
+  disabled?: boolean;
+  tooltip?: string;
+  collection?: CollectionSource; // For create action
+  create?: { mode: 'page'; page: { id: string } };
+  update?: { mode: 'page'; page: { id: string } };
+  delete?: { mode: 'modal'; modal: ModalConfig };
+  bulkDelete?: { mode: 'modal'; modal: ModalConfig };
+}
+
+// Component Types
+interface CollectionComponent {
+  type: 'collection';
+  entityPageId?: string;
+  collection: CollectionSettings;
+  filters?: FilterConfig;
+  actionCell?: ActionCellConfig;
+  bulkActionToolbar?: BulkActionToolbar;
+  toolbarTitle?: ToolbarTitle;
+  views?: ViewsConfig;
+  search?: { shown?: boolean };
+  emptyState?: EmptyStateConfig;
+  dragAndDrop?: { enabled: boolean; dragAndDropCancel?: { id?: string } };
+  layout: [TableLayout, GridLayout];
+}
+
+interface CustomComponent {
+  type: 'custom';
+  id: string;
+}
+
+// Sub-Types
+interface CollectionSource {
+  collectionId: string;
+  entityTypeSource: 'cms' | 'custom';
+  custom?: { id: string };
+}
+
+interface CollectionSettings extends CollectionSource {
+  reflectQueryInUrl?: boolean;
+  selectAllScope?: 'page' | 'all';
+  selectionUpdateMode?: 'preserve' | 'clear';
+  paginationMode?: 'cursor' | 'offset';
+}
+
+interface TableLayout {
+  type: 'Table';
+  table?: {
+    columns: ColumnConfig[];
+    customColumns?: { enabled: boolean };
+    dataExtension?: { enabled: boolean };
+    stickyColumns?: number;
+    showTitleBar?: boolean;
+  };
+}
+
+interface GridLayout {
+  type: 'Grid';
+  grid?: {
+    item: {
+      titleFieldId: string;
+      subtitleFieldId?: string;
+      imageFieldId?: string;
+      cardContentMode?: 'full' | 'title' | 'empty';
+      imagePlacement?: 'top' | 'side';
+    };
+  };
+}
+```
+
+## Validation Logic
+- **IF** `entityTypeSource` is `'custom'` **THEN** `custom: { id: "..." }` is **REQUIRED**.
+- **IF** `type: 'collectionPage'` **THEN** `collectionPage` object is **REQUIRED**, `entityPage` object is **FORBIDDEN**.
+- **IF** `type: 'entityPage'` **THEN** `entityPage` object is **REQUIRED**, `collectionPage` object is **FORBIDDEN**.
+- **IF** `type: 'action'` **THEN** `action` property is **REQUIRED**.
+- **IF** `type: 'menu'` **THEN** `menu` property is **REQUIRED**.
+- **IF** action type is `'create'` **THEN** `create` config is **REQUIRED**.
+- **IF** action type is `'update'` **THEN** `update` config is **REQUIRED**.
+- **IF** action type is `'delete'` **THEN** `delete` config is **REQUIRED**.
+
+## Implementation Rules
+- **MUST** include `biName` in EVERY action configuration (format: kebab-case, `{action-purpose}-action`).
+- **MUST** designate exactly ONE page as `appMainPage: true`.
+- **MUST** use TypeScript for configuration.
+- **NEVER** fill optional fields unless explicitly requested.
+- **NEVER** mix page types in a single configuration.
+- **NEVER** set `stickyColumns` to negative, zero, or > column count.
+- **NEVER** invent enum values; ASK user for values.
+
+## page.tsx Structure
+```tsx
+import React from 'react';
+import { WixDesignSystemProvider } from '@wix/design-system';
+import '@wix/design-system/styles.global.css';
+import { WixPatternsProvider } from '@wix/patterns/provider';
+import { PatternsWizardOverridesProvider, AutoPatternsApp, type AppConfig } from '@wix/auto-patterns';
+import { withDashboard } from '@wix/patterns';
+import config from './patterns.json';
+
+const Index: React.FC = () => {
+  return (
+    <WixDesignSystemProvider features={{ newColorsBranding: true }}>
+      <WixPatternsProvider>
+        <PatternsWizardOverridesProvider value={{}}>
+          <AutoPatternsApp configuration={config as AppConfig} />
+        </PatternsWizardOverridesProvider>
+      </WixPatternsProvider>
+    </WixDesignSystemProvider>
+  );
+};
+
+export default withDashboard(Index);
+```
+
+## Canonical Example
+```typescript
+export const config: AppConfig = {
+  pages: [
+    {
+      id: "product-list",
+      type: "collectionPage",
+      appMainPage: true,
+      collectionPage: {
+        route: { path: "/" },
+        title: { text: "Products" },
+        actions: {
+          primaryActions: {
+            type: "action",
+            action: {
+              item: {
+                id: "create-product",
+                type: "create",
+                label: "Add Product",
+                biName: "create-product-action",
+                collection: {
+                  collectionId: "products",
+                  entityTypeSource: "cms"
+                },
+                create: {
+                  mode: "page",
+                  page: { id: "product-details" }
+                }
+              }
+            }
+          }
+        },
+        components: [
+          {
+            type: "collection",
+            entityPageId: "product-details",
+            collection: {
+              collectionId: "products",
+              entityTypeSource: "cms"
+            },
+            layout: [
+              {
+                type: "Table",
+                table: {
+                  columns: [
+                    { id: "name", name: "Name", width: "200px" },
+                    { id: "price", name: "Price", width: "100px" }
+                  ]
+                }
+              },
+              {
+                type: "Grid",
+                grid: {
+                  item: { titleFieldId: "name" }
+                }
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      id: "product-details",
+      type: "entityPage",
+      entityPage: {
+        route: { path: "/product/:id", params: { id: "id" } },
+        collectionId: "products",
+        entityTypeSource: "cms",
+        layout: {
+          main: [
+            {
+              type: "card",
+              card: {
+                title: { text: "Basic Info" },
+                children: [
+                  { type: "field", field: { fieldId: "name" } }
+                ]
+              }
+            }
+          ]
+        }
+      }
+    }
+  ]
+};
+```

package/skills/wix-app/references/auto-patterns-dashboard/app-context.md

@@ -0,0 +1,37 @@
+# AppContext Rules
+
+## Type Definitions
+```typescript
+interface AppContext {
+  items: any[];
+  refreshCollection: () => void;
+}
+```
+
+## Validation Logic
+- **IF** using `useAppContext` **THEN** component MUST be inside `AutoPatternsApp` (as children).
+
+## Implementation Rules
+- **MUST** wrap child components (modals, panels) with `<AutoPatternsApp>`.
+- **MUST** use `useAppContext` to access shared collection data/refresh.
+- **MUST** use `refreshCollection` after data mutations in external components.
+- **NEVER** use `useAppContext` outside of the `AutoPatternsApp` tree.
+
+## Canonical Example
+```typescript
+// 1. Child Component
+const MyModal = () => {
+  const { items, refreshCollection } = useAppContext();
+  return (
+    <Modal>
+      <Text>Count: {items.length}</Text>
+      <Button onClick={refreshCollection}>Refresh</Button>
+    </Modal>
+  );
+};
+
+// 2. Integration
+<AutoPatternsApp configuration={config}>
+  <MyModal />
+</AutoPatternsApp>
+```