@wix/agent-skills 1.21.0 → 1.22.0

package/skills/wix-app/references/data-collection/PERMISSIONS.md

@@ -0,0 +1,47 @@
+# Data Collection — permissions
+
+> The scaffolded `dataPermissions` are placeholders. Set them from this file before shipping.
+
+## Permissions
+
+Access levels control who can read, create, update, and delete items in collections.
+
+| Level                | Description                                        |
+| -------------------- | -------------------------------------------------- |
+| `UNDEFINED`          | Not set (inherits defaults)                        |
+| `ANYONE`             | Public access (including visitors)                 |
+| `SITE_MEMBER`        | Any signed-in user (members and collaborators)     |
+| `SITE_MEMBER_AUTHOR` | Signed-in users, but members only access own items |
+| `CMS_EDITOR`         | Site collaborators with CMS Access permission      |
+| `PRIVILEGED`         | CMS administrators and privileged users            |
+
+**Common patterns:**
+
+- Public content (default, recommended): `read: ANYONE, write: PRIVILEGED`
+- User-generated content: `read: SITE_MEMBER, write: SITE_MEMBER_AUTHOR`
+- Editorial workflow: `read: ANYONE, write: CMS_EDITOR`
+- Private/admin: `read: PRIVILEGED, write: PRIVILEGED`
+
+**Permission hierarchy** (most to least restrictive): `PRIVILEGED` > `CMS_EDITOR` > `SITE_MEMBER_AUTHOR` > `SITE_MEMBER` > `ANYONE` > `UNDEFINED`
+
+### Context-Based Permission Rules
+
+**CRITICAL: Permissions must match where and how the data is accessed.** The consumer of the data determines the minimum permission level — setting permissions more restrictive than the access context will cause runtime failures (empty results or permission-denied errors).
+
+**Determine permissions by asking: "Who interacts with this data, and from where?"**
+
+| Access Context | Who Sees / Uses It | Implication |
+|---|---|---|
+| **Custom element widget** (`CUSTOM_ELEMENT_WIDGET`) | Any site visitor (public) | Reads must be `ANYONE`. If the widget accepts input (e.g., reviews, submissions), inserts must also be `ANYONE` or `SITE_MEMBER`. |
+| **Embedded Script** | Any site visitor (public) | Same as custom element widget — reads must be `ANYONE`. Writes depend on whether visitors can submit data. |
+| **Dashboard Page** (`DASHBOARD_PAGE`) | Site owner / collaborators only | Can use `CMS_EDITOR` or `PRIVILEGED` for all operations since only authorized users access the dashboard. |
+| **Backend code (site-side)** | Runs in visitor context | If called from page code or site-side modules, the caller has visitor-level permissions — data must be readable/writable at the appropriate public level. |
+| **Backend code (elevated)** | Runs with `auth.elevate()` from `@wix/essentials` | Can bypass permissions, but the collection still needs correct defaults for any non-elevated callers. |
+
+Use `SITE_MEMBER_AUTHOR` on `itemUpdate` / `itemRemove` when members should only modify their **own** items (e.g., a member can edit only their own reviews).
+
+**How to apply this:**
+
+1. **Identify every place the collection is read or written** — custom element widgets, dashboard pages, embedded scripts, backend APIs.
+2. **Use the least restrictive context as the floor.** If a custom element widget reads the data AND a dashboard page also reads it, `itemRead` must be `ANYONE` (because the widget is public).
+3. **Apply per-operation.** A collection can have `itemRead: ANYONE` (widget displays it) but `itemInsert: CMS_EDITOR` (only dashboard users add items). Each operation is independent.

package/skills/wix-app/references/data-collection/SCHEMA.md

@@ -0,0 +1,181 @@
+# Data Collection — declaring the schema
+
+> The `fields` and `indexes` you write inside a collection file.
+> [DATA_COLLECTION.md](../DATA_COLLECTION.md) owns scaffolding, the file shape and the CLI
+> constraints.
+
+## Field Types
+
+| Type              | Description                      | Use Case               |
+| ----------------- | -------------------------------- | ---------------------- |
+| `TEXT`            | Single-line text                 | Names, titles          |
+| `RICH_TEXT`       | Formatted HTML text              | Blog content           |
+| `RICH_CONTENT`    | Rich content with embedded media | Complex blog posts     |
+| `NUMBER`          | Decimal numbers                  | Prices, quantities     |
+| `BOOLEAN`         | True/false                       | Toggles, flags         |
+| `DATE`            | Date only                        | Birthdays              |
+| `DATETIME`        | Date with time                   | Timestamps             |
+| `TIME`            | Time only                        | Schedules              |
+| `IMAGE`           | Single image                     | Thumbnails             |
+| `DOCUMENT`        | File attachment                  | PDFs                   |
+| `VIDEO`           | Video file                       | Media                  |
+| `AUDIO`           | Audio file                       | Podcasts               |
+| `MEDIA_GALLERY`   | Multiple media                   | Galleries              |
+| `REFERENCE`       | Link to one item                 | Author → User          |
+| `MULTI_REFERENCE` | Link to many items               | Post → Tags            |
+| `ADDRESS`         | Structured address               | Locations              |
+| `URL`             | URL validation                   | Links                  |
+| `PAGE_LINK`       | Link to Wix page                 | Internal navigation    |
+| `LANGUAGE`        | Language code                    | Multi-language content |
+| `OBJECT`          | JSON object                      | Flexible data          |
+| `ARRAY`           | Array of values                  | Generic arrays         |
+| `ARRAY_STRING`    | Array of strings                 | Tags list              |
+| `ARRAY_DOCUMENT`  | Array of documents               | File collections       |
+| `ANY`             | Any type                         | Most flexible          |
+
+**CRITICAL: OBJECT fields require `objectOptions` with a `fields` array.** When using `type: "OBJECT"`, you MUST include `objectOptions: { fields: [] }` — the API will reject OBJECT fields without it. Use an empty `fields` array if you don't need a fixed schema (the object will still accept arbitrary JSON):
+
+```json
+{
+  "key": "settings",
+  "displayName": "Settings",
+  "type": "OBJECT",
+  "objectOptions": { "fields": [] }
+}
+```
+
+> ⚠️ `objectOptions: {}` (without the `fields` key) is **not valid** and will cause a runtime error. Always include `fields`, even as an empty array.
+
+For structured objects with a defined schema, list the nested fields inside `objectOptions.fields`:
+
+```json
+{
+  "key": "triggerRules",
+  "displayName": "Trigger Rules",
+  "type": "OBJECT",
+  "objectOptions": {
+    "fields": [
+      { "key": "url", "displayName": "URL Condition", "type": "TEXT" },
+      {
+        "key": "scrollDepth",
+        "displayName": "Scroll Depth %",
+        "type": "NUMBER"
+      },
+      { "key": "dateStart", "displayName": "Start Date", "type": "DATE" }
+    ]
+  }
+}
+```
+
+## Field Properties
+
+```ts
+{
+  key: 'email',                         // required, lowerCamelCase ASCII
+  type: 'TEXT',                         // required, see Field Types above
+  displayName: 'Email Address',         // optional, CMS label
+  description: "User's primary email",  // optional, help text
+  encrypted: false,                     // optional, encrypt value at rest
+  // arrayOptions / objectOptions / referenceOptions / multiReferenceOptions
+  // only when type is ARRAY / OBJECT / REFERENCE / MULTI_REFERENCE
+}
+```
+
+| Property      | Required | Description                          |
+| ------------- | -------- | ------------------------------------ |
+| `key`         | yes      | Field identifier (lowerCamelCase)    |
+| `type`        | yes      | Field data type (see Field Types)    |
+| `displayName` | no       | Label shown in CMS                   |
+| `description` | no       | Help text                            |
+| `encrypted`   | no       | Encrypt value at rest                |
+
+**There is no field-level `required`, `defaultValue`, or `unique`.** The `DevCenterDataCollectionField` type does not accept them and TypeScript will reject the build. Use these alternatives instead:
+
+- **Required values:** Validate in the dashboard form and/or service-plugin handler before inserting. Do not rely on the collection schema to enforce presence.
+- **Defaults:** Set defaults in the insert path (dashboard handler, service plugin) or via the collection's `initialData` for seeded rows.
+- **Uniqueness:** Declare a unique index in the collection's `indexes` array (see [Indexes](#indexes)). Uniqueness is an index-level concern, not a field-level one.
+
+## Indexes
+
+**Most collections need no index at all — ship `indexes: []` unless you can name the query that
+needs one.** `_id` and `_createdDate` are indexed automatically, and the budget is small: **3 regular
+indexes, 1 unique, 4 total** (the collection reports its own `capabilities.indexLimits`). "Index the
+field the table sorts by" is not a reason — it spends a slot for a page that would page fine without
+it.
+
+When you do add one, it is `{ fields: [{ path, order? }], unique? }` — and **nothing else**. In
+particular there is **no `name`**: the runtime Create Index API takes one, but the extension builder
+does not and the platform derives it (a `date` DESC index arrives as `date_DESC`). Read
+`DevCenterDataCollectionIndex` in the builders package if in doubt; a stray key is a compile error on
+the `satisfies DataCollection` literal.
+
+The `indexes` array on the collection accepts entries shaped like:
+
+```ts
+indexes: [
+  {
+    fields: [{ path: 'email', order: 'ASC' }],  // order is optional: 'ASC' | 'DESC'
+    unique: true,                                // optional, enforces uniqueness across items
+  },
+  {
+    fields: [
+      { path: 'category' },
+      { path: '_createdDate', order: 'DESC' },
+    ],
+  },
+],
+```
+
+| Property        | Required | Description                                            |
+| --------------- | -------- | ------------------------------------------------------ |
+| `fields`        | yes      | One or more `{ path, order? }` entries (composite index when more than one) |
+| `fields[].path` | yes      | Field key to index                                     |
+| `fields[].order`| no       | `'ASC'` (default) or `'DESC'`                          |
+| `unique`        | no       | Enforce uniqueness on the indexed field(s)             |
+
+Leave `indexes: []` when no custom indexing is needed; the `_id` index is created automatically.
+
+## Naming Conventions
+
+- **Field keys:** `lowerCamelCase`, ASCII only (e.g., `productName`, `isActive`, `createdAt`)
+- **Collection IDs (`idSuffix`):** `lower-kebab-case` or `lower_underscore` (e.g., `product-categories`, `blog_posts`)
+- **Display names:** Human-readable, can contain spaces (e.g., `"Product Name"`, `"Is Active"`)
+
+## System Fields (Automatic)
+
+Every collection includes: `_id`, `_createdDate`, `_updatedDate`, `_owner`
+
+## Relationships
+
+**One-to-One / Many-to-One (REFERENCE):**
+
+```json
+{
+  "key": "category",
+  "displayName": "Category",
+  "type": "REFERENCE",
+  "referenceOptions": {
+    "referencedCollectionId": "categories"
+  }
+}
+```
+
+**Many-to-Many (MULTI_REFERENCE):**
+
+```json
+{
+  "key": "tags",
+  "displayName": "Tags",
+  "type": "MULTI_REFERENCE",
+  "multiReferenceOptions": {
+    "referencedCollectionId": "tags"
+  }
+}
+```
+
+**CRITICAL Constraints:**
+
+- REFERENCE/MULTI_REFERENCE fields can ONLY link to other custom CMS collections defined in your app
+- The `referencedCollectionId` MUST be the `idSuffix` of another collection in the same plan
+- **NEVER use REFERENCE fields to link to Wix business entities** (Products, Orders, Contacts, Members, etc.)
+- Use Wix SDK APIs to access Wix business entities instead

package/skills/wix-app/references/data-collection/WIX_DATA.md

@@ -1,39 +1,27 @@
 # Wix Data SDK Reference
 
-Complete reference for working with Wix Data collections.
-
 ## Installation
 
-**IMPORTANT**: The `@wix/data` package must be installed as a dependency before use.
-
-```bash
-npm install @wix/data
-```
-
-### Troubleshooting
-
-**If you encounter: `Cannot find module '@wix/data'`**
+`@wix/data` must be a dependency before use: `npm install @wix/data`.
 
-❌ **WRONG**: Do not create mock implementations or workarounds
-✅ **CORRECT**: Install the package using `npm install @wix/data`
-
-The `@wix/data` package is a real npm package that provides access to Wix Data collections.
-It must be installed before TypeScript compilation will succeed.
+`Cannot find module '@wix/data'` means it is not installed. Install it — never mock it.
 
 ## SDK Methods & Interfaces
 
-| Method Call | Import | TypeScript Signature | Description |
-| --- | --- | --- | --- |
-| `items.get()` | `import { items } from '@wix/data'` | `(collectionId: string, itemId: string, options?: WixDataGetOptions) => Promise<WixDataItem \| null>` | Get a single item by ID |
-| `items.query()` | `import { items } from '@wix/data'` | `(collectionId: string) => WixDataQuery` | Build a chainable query (call `.find()` to execute) |
-| `items.insert()` | `import { items } from '@wix/data'` | `(collectionId: string, item: Partial<WixDataItem>, options?: WixDataInsertOptions) => Promise<WixDataItem>` | Add a new item to a collection |
-| `items.update()` | `import { items } from '@wix/data'` | `(collectionId: string, item: WixDataItem, options?: WixDataUpdateOptions) => Promise<WixDataItem>` | Replace an existing item (item MUST include `_id`) |
-| `items.save()` | `import { items } from '@wix/data'` | `(collectionId: string, item: Partial<WixDataItem>, options?: WixDataSaveOptions) => Promise<WixDataItem>` | Insert or update (upsert) based on `_id` |
-| `items.remove()` | `import { items } from '@wix/data'` | `(collectionId: string, itemId: string, options?: WixDataRemoveOptions) => Promise<WixDataItem \| null>` | Remove an item by ID |
-| `items.bulkInsert()` | `import { items } from '@wix/data'` | `(collectionId: string, items: Partial<WixDataItem>[], options?: WixDataOptions) => Promise<WixDataBulkResult>` | Insert multiple items (max 1000) |
-| `items.bulkUpdate()` | `import { items } from '@wix/data'` | `(collectionId: string, items: WixDataItem[], options?: WixDataBulkUpdateOptions) => Promise<WixDataBulkResult>` | Update multiple items (max 1000) |
-| `items.bulkRemove()` | `import { items } from '@wix/data'` | `(collectionId: string, itemIds: string[], options?: WixDataBulkRemoveOptions) => Promise<WixDataBulkResult>` | Remove multiple items (max 1000) |
-| `items.filter()` | `import { items } from '@wix/data'` | `() => WixDataFilter` | Create a standalone filter (for use with `.or()`, `.and()`, `.not()`) |
+All of these come from `import { items } from '@wix/data'`.
+
+| Method Call | TypeScript Signature | Description |
+| --- | --- | --- |
+| `items.get()` | `(collectionId: string, itemId: string, options?: WixDataGetOptions) => Promise<WixDataItem \| null>` | Get a single item by ID |
+| `items.query()` | `(collectionId: string) => WixDataQuery` | Build a chainable query (call `.find()` to execute) |
+| `items.insert()` | `(collectionId: string, item: Partial<WixDataItem>, options?: WixDataInsertOptions) => Promise<WixDataItem>` | Add a new item to a collection |
+| `items.update()` | `(collectionId: string, item: WixDataItem, options?: WixDataUpdateOptions) => Promise<WixDataItem>` | Replace an existing item (item MUST include `_id`) |
+| `items.save()` | `(collectionId: string, item: Partial<WixDataItem>, options?: WixDataSaveOptions) => Promise<WixDataItem>` | Insert or update (upsert) based on `_id` |
+| `items.remove()` | `(collectionId: string, itemId: string, options?: WixDataRemoveOptions) => Promise<WixDataItem \| null>` | Remove an item by ID |
+| `items.bulkInsert()` | `(collectionId: string, items: Partial<WixDataItem>[], options?: WixDataOptions) => Promise<WixDataBulkResult>` | Insert multiple items (max 1000) |
+| `items.bulkUpdate()` | `(collectionId: string, items: WixDataItem[], options?: WixDataBulkUpdateOptions) => Promise<WixDataBulkResult>` | Update multiple items (max 1000) |
+| `items.bulkRemove()` | `(collectionId: string, itemIds: string[], options?: WixDataBulkRemoveOptions) => Promise<WixDataBulkResult>` | Remove multiple items (max 1000) |
+| `items.filter()` | `() => WixDataFilter` | Create a standalone filter (for use with `.or()`, `.and()`, `.not()`) |
 
 ## ⚠️ Common Wrong Method Names (DO NOT USE)
 
@@ -67,8 +55,8 @@ interface WixDataItem {
 ```ts
 interface WixDataResult {
   readonly items: WixDataItem[];
-  readonly totalCount: number | undefined;  // only when returnTotalCount: true
-  readonly totalPages: number | undefined;  // only when returnTotalCount: true
+  readonly totalCount: number | undefined;  // both only when returnTotalCount: true
+  readonly totalPages: number | undefined;
   readonly pageSize: number | undefined;
   readonly currentPage: number | undefined;
   readonly length: number;
@@ -81,7 +69,7 @@ interface WixDataResult {
 
 ### WixDataQuery (returned by `items.query()`)
 
-Chainable query builder. Build filters, then call `.find()`, `.count()`, or `.distinct()`.
+Chainable. Build filters, then `.find()`, `.count()` or `.distinct()`.
 
 ```ts
 interface WixDataQuery {
@@ -149,25 +137,9 @@ interface WixDataGetOptions extends WixDataReadOptions {
   includeFieldGroups?: string[];
 }
 
-interface WixDataInsertOptions extends WixDataOptions {}
-
-interface WixDataUpdateOptions extends WixDataOptions {
-  condition?: WixDataFilter; // only update if condition is met
-}
-
-interface WixDataSaveOptions extends WixDataOptions {}
-
-interface WixDataRemoveOptions extends WixDataOptions {
-  condition?: WixDataFilter; // only remove if condition is met
-}
-
-interface WixDataBulkUpdateOptions extends WixDataOptions {
-  condition?: WixDataFilter;
-}
-
-interface WixDataBulkRemoveOptions extends WixDataOptions {
-  condition?: WixDataFilter;
-}
+// Insert/Save options add nothing to WixDataOptions.
+// Update/Remove/BulkUpdate/BulkRemove options add an optional guard:
+//   condition?: WixDataFilter  — only apply when the condition is met
 ```
 
 ### WixDataBulkResult (returned by bulk operations)
@@ -184,12 +156,8 @@ interface WixDataBulkResult {
   removedItemIds: string[];
 }
 
-interface WixDataBulkError extends Error {
-  message: string;
-  code: string;
-  originalIndex: number;      // index in the request array
-  item: WixDataItem | string; // the failed item or ID
-}
+// WixDataBulkError extends Error with `code`, `originalIndex` (position in the
+// request array) and `item` (the failed item or its id).
 ```
 
 ## Usage Examples
@@ -211,12 +179,18 @@ const result = await items.query("MyCollection")
 // result.items: WixDataItem[]
 
 // --- Compound query with or/and ---
-const filter1 = items.filter().eq("status", "pending");
-const filter2 = items.filter().eq("status", "active");
-const result = await items.query("MyCollection")
-  .or(filter1)
-  .or(filter2)
-  .find();
+// `or()` COMBINES two filters; it is not a condition. Called on a query or
+// filter that holds no condition yet, it contributes an empty `{}` branch, and
+// `{} OR x` matches the whole collection. Seed with the first condition, `or()`
+// the rest onto it, then `and()` the result onto the query.
+const pendingOrActive = items.filter().eq("status", "pending")
+  .or(items.filter().eq("status", "active"));
+const result = await items.query("MyCollection").and(pendingOrActive).find();
+
+// ❌ WRONG — or() onto a query holding no condition: matches every row
+items.query("MyCollection").or(filter1).or(filter2);
+// ❌ WRONG — or() onto the query itself: `country` is dropped from branch two
+items.query("MyCollection").eq("country", "IL").contains("name", t).or(filter2);
 
 // --- Insert ---
 const created = await items.insert("MyCollection", {
@@ -249,10 +223,8 @@ const bulkResult = await items.bulkInsert("MyCollection", [
 
 ## Collection Schema Rules
 
-- Always use the exact field keys defined in your collection schema
-- Use the collection ID exactly as defined in the schema
-- Use the schema's exact field types for all operations
-- Custom fields are stored in the `[key: string]: any` part of `WixDataItem`
+Use the collection id, field keys and field types exactly as the schema defines them. Custom fields
+live in the `[key: string]: any` part of `WixDataItem`.
 
 ## Permissions