@wix/agent-skills 1.14.0 → 1.15.1

package/skills/wix-app/references/stores/INVENTORY.md

@@ -0,0 +1,37 @@
+# Stores — 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;
+```

package/skills/wix-app/references/stores/QUERY.md

@@ -0,0 +1,87 @@
+# Stores — Query / List Products
+
+## 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 OVERVIEW.md 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.
+```

package/skills/wix-app/references/stores/WRITE.md

@@ -0,0 +1,55 @@
+# Stores — Write Operations (Create / Update / Delete)
+
+## 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);
+```

package/skills/wix-app/scripts/generate-auto-patterns.js

@@ -0,0 +1,510 @@
+#!/usr/bin/env node
+
+/**
+ * Auto Patterns Generator Script
+ *
+ * Generates patterns.json and the page component for @wix/auto-patterns dashboard pages.
+ * Replicates the deterministic logic from AutoPatternsGenerator.ts.
+ *
+ * The page component is written as `<folder>.tsx` (the basename of --output) to
+ * match — and overwrite — the stub the Wix CLI scaffolds and registers in
+ * `<folder>.extension.ts`. This wires the wrapper up with no manual edit.
+ *
+ * Usage:
+ *   node <SKILL_ROOT>/scripts/generate-auto-patterns.js --input <path-to-input.json> --output <target-directory>
+ *   node <SKILL_ROOT>/scripts/generate-auto-patterns.js --help
+ *
+ * <SKILL_ROOT> is the absolute path to the wix-app skill bundle (the folder containing SKILL.md).
+ * The script is not installed in the user's app repo — invoke it by absolute path from the project directory.
+ *
+ * Input JSON shape:
+ * {
+ *   "collection": {
+ *     "idSuffix": "additional-fees",
+ *     "fields": [{ "key": "feeTitle", "displayName": "Fee Title", "type": "TEXT" }, ...]
+ *   },
+ *   "schema": {
+ *     "content": { "collectionRouteId": "...", ... (20 string fields) },
+ *     "layout": { "main": [...], "sidebar": [...] },
+ *     "columns": [{ "id": "feeTitle", "displayName": "Title" }],
+ *     "gridItem": null | { "titleFieldId": "...", ... }
+ *   },
+ *   "relevantCollectionId": "my-namespace/additional-fees",
+ *   "extensionName": "Additional Fees Manager"
+ * }
+ *
+ * Output:
+ *   Writes patterns.json and <folder>.tsx to the specified output directory.
+ *   Prints JSON result to stdout: { "files": ["patterns.json", "<folder>.tsx"] }
+ *
+ * Exit codes:
+ *   0 - Success
+ *   1 - Invalid arguments or missing required fields
+ *   2 - File system error
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { basename, join, resolve } from 'path';
+
+// --- Argument parsing ---
+
+const args = process.argv.slice(2);
+
+function getArg(name) {
+  const idx = args.indexOf(`--${name}`);
+  if (idx === -1 || idx + 1 >= args.length) return null;
+  return args[idx + 1];
+}
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`Auto Patterns Generator
+
+Usage:
+  node <SKILL_ROOT>/scripts/generate-auto-patterns.js --input <path> --output <dir>
+
+<SKILL_ROOT> is the absolute path to the wix-app skill bundle (the folder containing SKILL.md).
+
+Options:
+  --input   Path to input JSON file (required)
+  --output  Target directory for generated files (required)
+  --help    Show this help message
+
+Input JSON shape:
+  {
+    "collection": {
+      "idSuffix": "string",
+      "fields": [{ "key": "string", "displayName": "string", "type": "string" }]
+    },
+    "schema": {
+      "content": { "collectionRouteId": "string", ... },
+      "layout": { "main": [...], "sidebar": [...] },
+      "columns": [{ "id": "string", "displayName": "string" }],
+      "gridItem": null | { "titleFieldId": "string", ... }
+    },
+    "relevantCollectionId": "string",
+    "extensionName": "string"
+  }
+
+Output:
+  Writes patterns.json and <folder>.tsx to the output directory.
+  Prints JSON to stdout: { "files": ["patterns.json", "<folder>.tsx"] }`);
+  process.exit(0);
+}
+
+const inputPath = getArg('input');
+const outputDir = getArg('output');
+
+if (!inputPath) {
+  console.error('Error: --input is required. Use --help for usage.');
+  process.exit(1);
+}
+if (!outputDir) {
+  console.error('Error: --output is required. Use --help for usage.');
+  process.exit(1);
+}
+
+// --- Read and validate input ---
+
+let input;
+try {
+  const raw = readFileSync(resolve(inputPath), 'utf-8');
+  input = JSON.parse(raw);
+} catch (err) {
+  console.error(`Error: Failed to read input file: ${err.message}`);
+  process.exit(1);
+}
+
+const { collection, schema, relevantCollectionId } = input;
+
+if (!collection || !collection.idSuffix || !Array.isArray(collection.fields)) {
+  console.error(
+    'Error: Input must include "collection" with "idSuffix" and "fields" array.',
+  );
+  process.exit(1);
+}
+if (
+  !schema ||
+  !schema.content ||
+  !schema.layout ||
+  !Array.isArray(schema.columns)
+) {
+  console.error(
+    'Error: Input must include "schema" with "content", "layout", and "columns".',
+  );
+  process.exit(1);
+}
+
+// --- Generator logic (mirrors AutoPatternsGenerator.ts) ---
+
+function generatePatternsConfig(collection, schema) {
+  const collectionRouteId = schema.content.collectionRouteId;
+  const singularEntityName = schema.content.singularEntityName;
+
+  // Build field map
+  const fieldMap = new Map();
+  for (const field of collection.fields) {
+    if (field.key && field.displayName) {
+      fieldMap.set(field.key, field);
+    }
+  }
+
+  const sortableFieldTypes = ['TEXT', 'DATE', 'NUMBER', 'BOOLEAN', 'URL'];
+
+  // Generate columns
+  const columns = schema.columns
+    .map((columnConfig) => {
+      const field = fieldMap.get(columnConfig.id);
+      if (!field || !field.key || !field.type) return null;
+
+      let width = '200px';
+      if (['BOOLEAN', 'IMAGE', 'NUMBER'].includes(field.type)) width = '100px';
+      if (field.type === 'URL') width = '300px';
+
+      return {
+        id: field.key,
+        name: columnConfig.displayName || field.displayName || 'Field',
+        width,
+        sortable: sortableFieldTypes.includes(field.type || ''),
+      };
+    })
+    .filter(Boolean);
+
+  // Generate filters
+  const filterableFieldTypes = ['DATE', 'NUMBER', 'BOOLEAN'];
+  const filters = columns
+    .map((column) => {
+      const field = fieldMap.get(column.id);
+      if (
+        !field ||
+        !field.key ||
+        !filterableFieldTypes.includes(field.type || '')
+      )
+        return null;
+
+      const baseFilter = {
+        id: `${field.key}-filter`,
+        fieldId: field.key,
+        displayName: field.displayName || '',
+        tagLabel: field.displayName || '',
+      };
+
+      if (field.type === 'DATE') {
+        return {
+          ...baseFilter,
+          dateConfig: {
+            mode: 'COMBINE',
+            presets: [
+              'TODAY',
+              'SEVEN_DAYS',
+              'MONTH',
+              'NEXT_SEVEN_DAYS',
+              'NEXT_THIRTY_DAYS',
+            ],
+            includeTime: false,
+          },
+        };
+      }
+      if (field.type === 'NUMBER') {
+        return {
+          ...baseFilter,
+          numberConfig: { allowedDecimals: true },
+        };
+      }
+      if (field.type === 'BOOLEAN') {
+        return baseFilter;
+      }
+      return null;
+    })
+    .filter(Boolean);
+
+  // Generate layout (Table + optional Grid)
+  const layout = [
+    {
+      type: 'Table',
+      table: {
+        columns,
+        customColumns: { enabled: true },
+      },
+    },
+  ];
+
+  if (schema.gridItem) {
+    layout.push({
+      type: 'Grid',
+      grid: {
+        item: {
+          titleFieldId: schema.gridItem.titleFieldId,
+          ...(schema.gridItem.subtitleFieldId
+            ? { subtitleFieldId: schema.gridItem.subtitleFieldId }
+            : {}),
+          ...(schema.gridItem.imageFieldId
+            ? { imageFieldId: schema.gridItem.imageFieldId }
+            : {}),
+          cardContentMode: schema.gridItem.subtitleFieldId ? 'full' : 'title',
+        },
+      },
+    });
+  }
+
+  // Generate entity page layout
+  function generateEntityPageLayout(layoutData) {
+    if (!layoutData) return { main: [] };
+
+    const main = layoutData.main.map((section) => ({
+      type: 'card',
+      card: {
+        title: { text: section.title },
+        subtitle: { text: section.subtitle },
+        children: section.fields.map((fieldKey) => ({
+          type: 'field',
+          field: { span: 12, fieldId: fieldKey },
+        })),
+      },
+    }));
+
+    const sidebar = layoutData.sidebar.map((section) => ({
+      type: 'card',
+      card: {
+        title: { text: section.title },
+        subtitle: { text: section.subtitle },
+        children: section.fields.map((fieldKey) => ({
+          type: 'field',
+          field: { span: 12, fieldId: fieldKey },
+        })),
+      },
+    }));
+
+    return {
+      main,
+      ...(sidebar.length > 0 ? { sidebar } : {}),
+    };
+  }
+
+  // Use relevantCollectionId for the collection reference in the config
+  const collectionId = relevantCollectionId || collection.idSuffix;
+
+  return {
+    pages: [
+      {
+        id: `${collectionRouteId}-collection`,
+        type: 'collectionPage',
+        appMainPage: true,
+        collectionPage: {
+          route: { path: '/' },
+          title: {
+            text: schema.content.pageTitle || '',
+            hideTotal: false,
+          },
+          subtitle: {
+            text: schema.content.pageSubtitle || '',
+          },
+          actions: {
+            primaryActions: {
+              type: 'action',
+              action: {
+                item: {
+                  id: `create-${collectionRouteId}`,
+                  type: 'create',
+                  label: schema.content.actionButtonLabel,
+                  collection: {
+                    collectionId,
+                    entityTypeSource: 'cms',
+                  },
+                  create: {
+                    mode: 'page',
+                    page: { id: `${collectionRouteId}-entity` },
+                  },
+                },
+              },
+            },
+          },
+          components: [
+            {
+              type: 'collection',
+              layout,
+              entityPageId: `${collectionRouteId}-entity`,
+              collection: {
+                collectionId,
+                entityTypeSource: 'cms',
+              },
+              toolbarTitle: {
+                title: schema.content.toolbarTitle || '',
+                subtitle: {
+                  text: schema.content.toolbarSubtitle || '',
+                },
+                showTotal: true,
+              },
+              filters: { items: filters },
+              emptyState: {
+                title: schema.content.emptyStateTitle,
+                subtitle: schema.content.emptyStateSubtitle,
+                addNewCta: {
+                  id: `create-${collectionRouteId}`,
+                  text: schema.content.emptyStateButtonText,
+                },
+              },
+              actionCell: {
+                primaryAction: {
+                  item: {
+                    id: `edit-${collectionRouteId}`,
+                    type: 'update',
+                    update: {
+                      mode: 'page',
+                      page: { id: `${collectionRouteId}-entity` },
+                    },
+                  },
+                },
+                secondaryActions: {
+                  items: [
+                    {
+                      id: `delete-${collectionRouteId}`,
+                      type: 'delete',
+                      label: 'Delete',
+                      delete: {
+                        mode: 'modal',
+                        modal: {
+                          title: {
+                            text: schema.content.deleteModalTitle || '',
+                          },
+                          description: {
+                            text: schema.content.deleteModalDescription || '',
+                          },
+                          feedback: {
+                            successToast: {
+                              text: schema.content.deleteSuccessToast || '',
+                            },
+                            errorToast: {
+                              text: schema.content.deleteErrorToast || '',
+                            },
+                          },
+                        },
+                      },
+                    },
+                  ],
+                },
+              },
+              bulkActionToolbar: {
+                primaryActions: [
+                  {
+                    type: 'action',
+                    action: {
+                      item: {
+                        id: `bulk-delete-${collectionRouteId}`,
+                        type: 'bulkDelete',
+                        bulkDelete: {
+                          mode: 'modal',
+                          modal: {
+                            title: {
+                              text: schema.content.bulkDeleteModalTitle || '',
+                            },
+                            description: {
+                              text:
+                                schema.content.bulkDeleteModalDescription || '',
+                            },
+                            feedback: {
+                              successToast: {
+                                text:
+                                  schema.content.bulkDeleteSuccessToast || '',
+                              },
+                              errorToast: {
+                                text: schema.content.bulkDeleteErrorToast || '',
+                              },
+                            },
+                          },
+                        },
+                      },
+                    },
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      },
+      {
+        id: `${collectionRouteId}-entity`,
+        type: 'entityPage',
+        entityPage: {
+          route: {
+            path: `/${singularEntityName}/:entityId`,
+            params: { id: 'entityId' },
+          },
+          title: { text: schema.content.entityPageTitle || '' },
+          subtitle: { text: schema.content.entityPageSubtitle },
+          parentPageId: `${collectionRouteId}-collection`,
+          layout: generateEntityPageLayout(schema.layout),
+          collectionId,
+          entityTypeSource: 'cms',
+        },
+      },
+    ],
+  };
+}
+
+function generatePageTsx() {
+  return `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);
+`;
+}
+
+// --- Generate and write output ---
+
+const resolvedOutput = resolve(outputDir);
+
+try {
+  if (!existsSync(resolvedOutput)) {
+    mkdirSync(resolvedOutput, { recursive: true });
+  }
+} catch (err) {
+  console.error(`Error: Failed to create output directory: ${err.message}`);
+  process.exit(2);
+}
+
+const patternsConfig = generatePatternsConfig(collection, schema);
+const pageTsx = generatePageTsx();
+
+// The Wix CLI scaffolds the page component as `<folder>.tsx` and registers THAT
+// file in the generated `<folder>.extension.ts`. Write the auto-patterns wrapper
+// to the same filename so it overwrites the CLI stub and is wired up with no
+// manual edit to the builder file. (Writing `page.tsx` would leave the wrapper
+// unregistered next to the empty stub the CLI registered.)
+const componentFileName = `${basename(resolvedOutput)}.tsx`;
+
+try {
+  writeFileSync(
+    join(resolvedOutput, 'patterns.json'),
+    JSON.stringify(patternsConfig, null, 2),
+  );
+  writeFileSync(join(resolvedOutput, componentFileName), pageTsx);
+} catch (err) {
+  console.error(`Error: Failed to write output files: ${err.message}`);
+  process.exit(2);
+}
+
+// Print structured result to stdout
+console.log(
+  JSON.stringify({
+    success: true,
+    files: ['patterns.json', componentFileName],
+    outputDir: resolvedOutput,
+  }),
+);

package/skills/wix-auth/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: wix-auth
+description: "Authenticate with Wix to obtain an access token for calling Wix APIs. Use when an agent needs a valid Wix access token and has none, or when the stored token is expired."
+---
+
+# Wix Auth
+
+Wix supports multiple authentication flows. This skill currently covers:
+
+- [Device Flow](references/device-flow.md) — interactive login via browser, no client secret required. Use when the agent is acting on behalf of a logged-in Wix user.
+
+Other flows (OAuth authorization code, API key) are documented at [https://www.wix.com/skills/docs](https://www.wix.com/skills/docs).