@wix/agent-skills 1.14.0 → 1.15.0

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).

package/skills/wix-auth/references/device-flow.md

@@ -0,0 +1,140 @@
+# Device Flow
+
+Implements the OAuth 2.0 Device Authorization Grant (RFC 8628). The user approves in a browser while the agent polls for tokens.
+
+Produces two kinds of token:
+- **Account token** — works for account-level APIs (e.g. list sites). Expires in ~4 hours.
+- **Site token** — required for any site-specific API (contacts, products, bookings, …). Derived on demand from the account `refreshToken` + a `siteId`. Expires in ~15 minutes.
+
+## Constants
+
+```
+BASE_URL  = https://manage.wix.com
+CLIENT_ID = 6f95cec8-3e98-48b9-b4e5-1fb92fcd9973
+```
+
+Required headers on every request:
+
+```
+X-XSRF-TOKEN: nocheck
+Cookie: XSRF-TOKEN=nocheck
+User-Agent: wix-cli
+Content-Type: application/json   (on POST requests)
+```
+
+## Step 1 — Request a device code
+
+```
+GET /oauth2/device/code?clientId=CLIENT_ID
+```
+
+Response:
+
+```json
+{ "deviceCode": "…", "userCode": "XXXXXXXX", "verificationUri": "https://users.wix.com/login/device-login", "expiresIn": 600 }
+```
+
+## Step 2 — Ask the user to authorize
+
+Show the user this URL and code:
+
+```
+URL:  {verificationUri}?color=developer&studio=true
+Code: {userCode}
+```
+
+Make sure the user has copied or noted the code **before** opening the link — they'll need to enter it on the page. Present the URL as a clickable link that opens in a new tab if your interface supports it.
+
+## Step 3 — Poll for the token
+
+Every 3 seconds, POST:
+
+```
+POST /oauth2/token
+{ "clientId": "CLIENT_ID", "grantType": "urn:ietf:params:oauth:grant-type:device_code", "scope": "offline_access", "deviceCode": "{deviceCode}" }
+```
+
+- While waiting: server returns `400` with `{ "error": "authorization_pending" }` or `{ "message": "Device code is not yet verified" }` — keep polling.
+- On approval: `200` with `{ "access_token": "…", "refresh_token": "…", "expires_in": 14400 }`.
+- Stop polling after `expiresIn` seconds total.
+
+## Step 4 — Fetch user info
+
+```
+GET /_serverless/wix-cli-userinfo/userinfo
+Authorization: Bearer {access_token}
+```
+
+Response: `{ "userId": "…", "email": "…" }`
+
+## Step 5 — Persist
+
+At this point you already hold all the values in memory — store them securely to whatever credential store your platform provides (file, secrets manager, environment variables, etc.), without asking the user to enter them manually. **Treat these as secrets: never print them in the conversation, never include them in logs, and never send them to any service other than the Wix APIs.**
+
+```
+accessToken   string
+refreshToken  string
+expiresIn     number  (seconds)
+issuedAt      number  (Unix timestamp in seconds, recorded at the moment tokens were received)
+userInfo      { userId, email }
+```
+
+## Getting a valid token on subsequent calls
+
+**Account token**
+
+1. Load stored credentials. If missing → run the device flow above.
+2. Check validity: `issuedAt + expiresIn - 600 > now` (10-min buffer).
+3. If expired → refresh silently:
+
+```
+POST /oauth2/token
+{ "clientId": "CLIENT_ID", "grantType": "refresh_token", "refreshToken": "{refreshToken}" }
+```
+
+Same response shape as Step 3. Persist the new tokens with a fresh `issuedAt`.
+
+4. If refresh returns `400 invalid_grant` → session revoked; run the device flow again.
+
+**Site token**
+
+The account token returns `403` on site-level endpoints. Derive a site token on demand:
+
+```
+POST /oauth2/token
+{ "clientId": "CLIENT_ID", "grantType": "refresh_token", "refreshToken": "{refreshToken}", "siteId": "{siteId}" }
+```
+
+Response: `{ "access_token": "…", "refresh_token": "…", "expires_in": 900 }`
+
+Re-derive on each use rather than caching — it expires in 15 minutes.
+
+## Examples
+
+**List sites (account token)**
+
+```
+POST https://www.wixapis.com/site-list/v2/sites/query
+Authorization: Bearer {accountToken}
+{ "query": { "filter": { "namespace": { "$in": ["WIX", "HEADLESS"] } }, "cursorPaging": { "limit": 100 } } }
+```
+
+Returns `{ sites: [{ id, displayName, namespace, … }] }` — the `id` is the `siteId` for site-scoped calls.
+
+> Without the `namespace` filter, headless sites are silently excluded from results.
+
+**List contacts (site token)**
+
+```
+POST https://www.wixapis.com/contacts/v4/contacts/query
+Authorization: Bearer {siteToken}
+{ "query": { "paging": { "limit": 10 } } }
+```
+
+Returns `{ contacts: […] }`.
+
+---
+
+For the full Wix REST API reference — endpoints, request/response shapes, and field details — see [https://www.wix.com/skills/docs](https://www.wix.com/skills/docs).
+
+For REST API recipes covering common management operations (stores, bookings, contacts, CMS, and more) — see [https://www.wix.com/skills/manage](https://www.wix.com/skills/manage).