@wix/agent-skills 1.0.0

package/skills/wix-manage/references/events/list-events.md

@@ -0,0 +1,203 @@
+---
+name: "List Events"
+description: Queries events from Wix Events using Events API. Covers field sets (DETAILS, URLS, REGISTRATION), filtering by status/date, and pagination.
+---
+# List Events with Wix Events API
+
+This recipe demonstrates how to query and list events from Wix Events using the REST API.
+
+## Prerequisites
+
+- Wix Events app installed on the site
+- API access with events permissions
+
+## Required APIs
+
+- **Events API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/query-events)
+- **Filter and Sort Guidelines**: [Documentation](https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/filter-and-sort)
+
+---
+
+## Step 1: Verify Events App is Installed
+
+Before querying events, ensure Wix Events is installed on the site. If not, use the [Install Wix Apps](../app-installation/install-wix-apps.md) recipe to install it.
+
+---
+
+## Step 2: Query Events
+
+**Endpoint**: `POST https://www.wixapis.com/events/v3/events/query`
+
+**Request Body**:
+```json
+{
+  "query": {
+    "paging": {
+      "limit": 10
+    }
+  },
+  "fields": ["DETAILS", "URLS"]
+}
+```
+
+**Request**:
+```bash
+curl -X POST \
+  'https://www.wixapis.com/events/v3/events/query' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "query": {
+      "paging": {
+        "limit": 10
+      }
+    },
+    "fields": ["DETAILS", "URLS"]
+  }'
+```
+
+### Available Field Sets
+
+The `fields` parameter determines which data is returned. You MUST specify at least `"DETAILS"`.
+
+| Field Set | Description |
+|-----------|-------------|
+| `DETAILS` | Core event information (required) |
+| `URLS` | Event page URLs |
+| `CATEGORIES` | Event categories |
+| `AGENDA` | Event schedule/agenda |
+| `SEO_SETTINGS` | SEO metadata |
+| `REGISTRATION` | Registration settings |
+| `TEXTS` | Custom text content |
+| `FORM` | Registration form configuration |
+| `DASHBOARD` | Dashboard settings |
+| `FEED` | Social feed settings |
+| `ONLINE_CONFERENCING_SESSION` | Virtual event settings |
+
+### IMPORTANT NOTES:
+- I MUST specify at least `"DETAILS"` in the `fields` array
+- I MUST NEVER use `"FULL"` as a field value
+- If the user wants event links, I MUST include `"URLS"` in the fields
+- Follow the [Filter and Sort Guidelines](https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/filter-and-sort) for query filtering
+
+---
+
+## Step 3: Filter Events (Optional)
+
+Apply filters to narrow down results:
+
+**Filter by Status**:
+```json
+{
+  "query": {
+    "filter": {
+      "status": "UPCOMING"
+    },
+    "paging": {
+      "limit": 10
+    }
+  },
+  "fields": ["DETAILS"]
+}
+```
+
+> **Note:** Valid status values are: `UPCOMING`, `STARTED`, `ENDED`, `CANCELED`, `DRAFT`.
+
+**Filter by Date Range**:
+```json
+{
+  "query": {
+    "filter": {
+      "dateAndTimeSettings.startDate": {
+        "$gte": "2024-01-01T00:00:00Z",
+        "$lte": "2024-12-31T23:59:59Z"
+      }
+    },
+    "paging": {
+      "limit": 10
+    }
+  },
+  "fields": ["DETAILS"]
+}
+```
+
+---
+
+## Response Structure
+
+```json
+{
+  "events": [
+    {
+      "id": "event-id-123",
+      "title": "Event Title",
+      "shortDescription": "Event description",
+      "status": "UPCOMING",
+      "dateAndTimeSettings": {
+        "startDate": "2024-06-15T10:00:00Z",
+        "endDate": "2024-06-15T18:00:00Z",
+        "timeZoneId": "America/New_York",
+        "dateAndTimeTbd": false,
+        "recurrenceStatus": "ONE_TIME"
+      },
+      "location": {
+        "type": "VENUE",
+        "address": {}
+      },
+      "slug": "event-slug"
+    }
+  ],
+  "pagingMetadata": {
+    "count": 10,
+    "hasNext": true
+  }
+}
+```
+
+---
+
+## Common Use Cases
+
+### List Upcoming Events
+```json
+{
+  "query": {
+    "filter": {
+      "status": "UPCOMING",
+      "dateAndTimeSettings.startDate": {
+        "$gte": "2024-01-01T00:00:00Z"
+      }
+    },
+    "sort": [
+      {
+        "fieldName": "dateAndTimeSettings.startDate",
+        "order": "ASC"
+      }
+    ],
+    "paging": {
+      "limit": 20
+    }
+  },
+  "fields": ["DETAILS", "URLS"]
+}
+```
+
+### List Events with Registration Info
+```json
+{
+  "query": {
+    "paging": {
+      "limit": 10
+    }
+  },
+  "fields": ["DETAILS", "REGISTRATION", "FORM"]
+}
+```
+
+---
+
+## Next Steps
+
+- Create events using the [Create Event API](https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3/create-event)
+- Manage RSVPs and registrations
+- Configure event tickets and pricing

package/skills/wix-manage/references/forms/create-form.md

@@ -0,0 +1,260 @@
+---
+name: "Create Form"
+description: Creates a form with fields (name, email, etc.) using the Form Schemas API. Covers field configuration, layout, and post-submission triggers.
+---
+# RECIPE: Create a Wix Form
+
+Create a form on a Wix site that appears in the Forms & Submissions dashboard. The form collects visitor information (e.g., name, email) and can automatically upsert contacts on submission.
+
+---
+
+## Create the form
+
+Call the Create Form endpoint with the `wix.form_app.form` namespace. The Wix Forms app (appDefId: `14ce1214-b278-a7e4-1373-00cebd1bef7c`) is usually already installed on sites.
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/form-schema-service/v4/forms' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  -d '{
+    "form": {
+      "name": "Contact Form",
+      "namespace": "wix.form_app.form",
+      "enabled": true,
+      "spamFilterProtectionLevel": "ADVANCED",
+      "formFields": [
+        {
+          "id": "c1a2b3d4-0001-4a00-b000-000000000001",
+          "hidden": false,
+          "identifier": "CONTACTS_FIRST_NAME",
+          "fieldType": "INPUT",
+          "inputOptions": {
+            "target": "first_name_0001",
+            "pii": true,
+            "required": false,
+            "inputType": "STRING",
+            "readOnly": false,
+            "stringOptions": {
+              "validation": {
+                "format": "UNKNOWN_FORMAT",
+                "enum": []
+              },
+              "componentType": "TEXT_INPUT",
+              "textInputOptions": {
+                "label": "First name",
+                "showLabel": true
+              }
+            }
+          }
+        },
+        {
+          "id": "c1a2b3d4-0002-4a00-b000-000000000002",
+          "hidden": false,
+          "identifier": "CONTACTS_LAST_NAME",
+          "fieldType": "INPUT",
+          "inputOptions": {
+            "target": "last_name_0002",
+            "pii": true,
+            "required": false,
+            "inputType": "STRING",
+            "readOnly": false,
+            "stringOptions": {
+              "validation": {
+                "format": "UNKNOWN_FORMAT",
+                "enum": []
+              },
+              "componentType": "TEXT_INPUT",
+              "textInputOptions": {
+                "label": "Last name",
+                "showLabel": true
+              }
+            }
+          }
+        },
+        {
+          "id": "c1a2b3d4-0003-4a00-b000-000000000003",
+          "hidden": false,
+          "identifier": "CONTACTS_EMAIL",
+          "fieldType": "INPUT",
+          "inputOptions": {
+            "target": "email_0003",
+            "pii": true,
+            "required": true,
+            "inputType": "STRING",
+            "readOnly": false,
+            "stringOptions": {
+              "validation": {
+                "format": "EMAIL",
+                "enum": []
+              },
+              "componentType": "TEXT_INPUT",
+              "textInputOptions": {
+                "label": "Email",
+                "showLabel": true
+              }
+            }
+          }
+        },
+        {
+          "id": "c1a2b3d4-0004-4a00-b000-000000000004",
+          "hidden": false,
+          "identifier": "TEXT_INPUT",
+          "fieldType": "INPUT",
+          "inputOptions": {
+            "target": "message_0004",
+            "pii": false,
+            "required": false,
+            "inputType": "STRING",
+            "readOnly": false,
+            "stringOptions": {
+              "validation": {
+                "format": "UNKNOWN_FORMAT",
+                "enum": []
+              },
+              "componentType": "TEXT_INPUT",
+              "textInputOptions": {
+                "label": "Message",
+                "showLabel": true
+              }
+            }
+          }
+        },
+        {
+          "id": "c1a2b3d4-0005-4a00-b000-000000000005",
+          "hidden": false,
+          "identifier": "SUBMIT_BUTTON",
+          "fieldType": "DISPLAY",
+          "displayOptions": {
+            "displayFieldType": "PAGE_NAVIGATION",
+            "pageNavigationOptions": {
+              "nextPageText": "Next",
+              "previousPageText": "Back",
+              "submitText": "Submit"
+            }
+          }
+        }
+      ],
+      "steps": [
+        {
+          "id": "d1e2f3a4-0001-4b00-c000-000000000001",
+          "name": "Page 1",
+          "hidden": false,
+          "layout": {
+            "large": {
+              "items": [
+                { "fieldId": "c1a2b3d4-0001-4a00-b000-000000000001", "row": 0, "column": 0, "width": 6, "height": 1 },
+                { "fieldId": "c1a2b3d4-0002-4a00-b000-000000000002", "row": 0, "column": 6, "width": 6, "height": 1 },
+                { "fieldId": "c1a2b3d4-0003-4a00-b000-000000000003", "row": 1, "column": 0, "width": 12, "height": 1 },
+                { "fieldId": "c1a2b3d4-0004-4a00-b000-000000000004", "row": 2, "column": 0, "width": 12, "height": 1 },
+                { "fieldId": "c1a2b3d4-0005-4a00-b000-000000000005", "row": 3, "column": 6, "width": 6, "height": 1 }
+              ],
+              "sections": []
+            }
+          }
+        }
+      ],
+      "postSubmissionTriggers": {
+        "upsertContact": {
+          "fieldsMapping": {
+            "first_name_0001": { "contactField": "FIRST_NAME" },
+            "last_name_0002": { "contactField": "LAST_NAME" },
+            "email_0003": { "contactField": "EMAIL", "emailInfo": { "tag": "UNTAGGED" } }
+          },
+          "labels": []
+        }
+      },
+      "submitSettings": {
+        "submitSuccessAction": "THANK_YOU_MESSAGE",
+        "thankYouMessageOptions": {
+          "durationInSeconds": 8,
+          "richContent": {
+            "nodes": [
+              {
+                "type": "PARAGRAPH",
+                "id": "ty1",
+                "nodes": [
+                  {
+                    "type": "TEXT",
+                    "id": "",
+                    "nodes": [],
+                    "textData": {
+                      "text": "Thanks, we received your submission.",
+                      "decorations": []
+                    }
+                  }
+                ],
+                "paragraphData": {
+                  "textStyle": { "textAlignment": "CENTER" }
+                }
+              }
+            ],
+            "metadata": {
+              "version": 1,
+              "createdTimestamp": "2025-01-01T00:00:00.000Z",
+              "updatedTimestamp": "2025-01-01T00:00:00.000Z",
+              "id": "thank-you-msg-001"
+            }
+          }
+        }
+      }
+    }
+  }'
+```
+
+The response includes the created form with its `id`. Store this ID to manage the form later.
+
+Verify the form in the dashboard: `https://manage.wix.com/dashboard/{siteId}/forms`
+
+## Key Details
+
+### Field Configuration
+
+- All `id` fields (for `formFields`, `steps`) and all `fieldId` references in the layout **must be valid UUIDs**. Generate fresh UUIDs for each form you create — do not reuse the example UUIDs above.
+- Each field needs a unique `id` and a unique `target` value. The `target` is used to map submissions to contact fields.
+- **CRITICAL: The `identifier` must be a recognized Wix value.** Custom identifiers like `"product_name"` or `"color_preference"` will cause the field to be silently dropped from the form — no error is thrown. For any generic/custom text field, use `"TEXT_INPUT"` as the identifier and set the display name via the `label` property in `textInputOptions`.
+- For plain text fields, use `"format": "UNKNOWN_FORMAT"`. For email fields, use `"format": "EMAIL"`. For phone fields, use `"format": "PHONE"`. Valid format values: `UNKNOWN_FORMAT`, `DATE`, `TIME`, `DATE_TIME`, `EMAIL`, `URL`, `UUID`, `PHONE`, `URI`, `HOSTNAME`, `COLOR_HEX`, `CURRENCY`, `LANGUAGE`, `DATE_OPTIONAL_TIME`.
+- The submit button is a `DISPLAY` field with `identifier: "SUBMIT_BUTTON"`.
+
+### Field Types Reference
+
+| Identifier | componentType | format | Use case |
+|---|---|---|---|
+| `TEXT_INPUT` | `TEXT_INPUT` | `UNKNOWN_FORMAT` | Generic single-line text (use `label` for display name) |
+| `CONTACTS_FIRST_NAME` | `TEXT_INPUT` | `UNKNOWN_FORMAT` | Contact first name |
+| `CONTACTS_LAST_NAME` | `TEXT_INPUT` | `UNKNOWN_FORMAT` | Contact last name |
+| `CONTACTS_EMAIL` | `TEXT_INPUT` | `EMAIL` | Contact email |
+| `CONTACTS_PHONE` | `TEXT_INPUT` | `PHONE` | Contact phone |
+| `SUBMIT_BUTTON` | N/A (`DISPLAY` field) | N/A | Submit button |
+
+> **Note:** `LONG_TEXT_INPUT` is not supported as a `componentType` via REST — it throws `INVALID_ARGUMENT`. Use `TEXT_INPUT` for all text fields.
+
+### Layout
+
+The `steps[].layout.large.items` array controls how fields are positioned:
+- `row` and `column` set the position (0-based grid)
+- `width` sets the column span (max 12 for full width, 6 for half)
+- `height` is typically 1
+
+### Post-Submission Triggers
+
+The `postSubmissionTriggers.upsertContact` object maps form field targets to contact fields, so each submission automatically creates or updates a contact. The `fieldsMapping` keys must match the `target` values from the form fields.
+
+### Prerequisites
+
+The Wix Forms app (appDefId: `14ce1214-b278-a7e4-1373-00cebd1bef7c`) must be installed on the site. It is usually pre-installed, but if the API returns a "missing installed app" error, install it first using the [Install Wix Apps](../app-installation/install-wix-apps.md) recipe.
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|---|---|---|
+| `Unrecognized value passed for enum` | Invalid `componentType` value (e.g., `LONG_TEXT_INPUT`) | Use only `componentType` values from the schema: `TEXT_INPUT`, `RADIO_GROUP`, `DROPDOWN`, `DATE_TIME`, `PHONE_INPUT`, `DATE_INPUT`, `TIME_INPUT`, `DATE_PICKER`, `PASSWORD` |
+| Field silently missing from created form | Custom `identifier` value (e.g., `"product_name"`) | Use a recognized identifier like `TEXT_INPUT` and set display name via `label` |
+| `Permissions for given namespace not found` | `wix.form_app.form` namespace not active | Ensure the Wix Forms app is installed; try creating a form through the UI first to activate the namespace |
+| `missing installed app` | Wix Forms app not installed | Install app `14ce1214-b278-a7e4-1373-00cebd1bef7c` via the [Install Wix Apps](../app-installation/install-wix-apps.md) recipe |
+
+## Related Documentation
+
+- [Form Schemas API Introduction](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/introduction)
+- [Create Form API Reference](https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/create-form)
+- [Form Submissions API](https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/introduction)

package/skills/wix-manage/references/get-paid/create-payment-links.md

@@ -0,0 +1,212 @@
+---
+name: "Create Payment Links"
+description: Creates payment links for collecting payments without a checkout flow. Covers store products (catalog items), custom line items, variants, due dates, and sending links via email.
+---
+# Create Payment Links
+
+This recipe shows how to create and manage payment links using the current Payment Links REST API.
+
+## Prerequisites
+
+1. Site is premium.
+2. Site is published.
+3. Site is set up to accept payments (Wix Payments onboarding completed).
+4. App has payment-link permissions.
+5. Wix Stores is installed if you plan to charge for catalog products.
+
+## Required APIs
+
+- **Payment Links API**: [REST](https://dev.wix.com/docs/api-reference/business-management/get-paid/payment-links/payment-links/create-payment-link)
+- **Products API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v1/catalog/query-products)
+
+## Overview
+
+Payment links are created at:
+
+- `POST https://www.wixapis.com/payment-links/v1/payment-links`
+
+Use one of these payment-link types:
+
+- `ECOM`: charge for custom or catalog line items.
+- `ECOM_ORDER`: collect payment for an existing unpaid eCommerce order.
+
+## Step 1: Retrieve product details (optional)
+
+If you plan to use catalog items, fetch the product first.
+
+**Examples**:
+
+- Catalog V1: `GET https://www.wixapis.com/stores/v1/products/{productId}`
+- Catalog V1 query: `POST https://www.wixapis.com/stores/v1/products/query`
+
+```json
+{
+  "query": {
+    "paging": {
+      "limit": 50,
+      "offset": 0
+    }
+  }
+}
+```
+
+## Step 2: Create an `ECOM` payment link with custom line items
+
+```json
+{
+  "paymentLink": {
+    "title": "Business Listing Fee",
+    "description": "One-time listing fee",
+    "currency": "USD",
+    "type": "ECOM",
+    "ecomPaymentLink": {
+      "lineItems": [
+        {
+          "type": "CUSTOM",
+          "customItem": {
+            "name": "Listing Fee",
+            "quantity": 1,
+            "price": "200.00"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+## Step 3: Create an `ECOM` payment link with catalog items
+
+```json
+{
+  "paymentLink": {
+    "title": "Product Payment",
+    "currency": "USD",
+    "type": "ECOM",
+    "ecomPaymentLink": {
+      "lineItems": [
+        {
+          "type": "CATALOG",
+          "catalogItem": {
+            "quantity": 1,
+            "catalogReference": {
+              "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
+              "catalogItemId": "PRODUCT_ID",
+              "options": {
+                "variantId": "VARIANT_ID"
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+## Step 4: Create an `ECOM_ORDER` payment link for an existing order
+
+```json
+{
+  "paymentLink": {
+    "title": "Order Balance",
+    "currency": "USD",
+    "type": "ECOM_ORDER",
+    "paymentsLimit": 1,
+    "ecomOrderPaymentLink": {
+      "orderId": "ORDER_ID",
+      "amount": "50"
+    }
+  }
+}
+```
+
+## Step 5: Send payment link to recipients
+
+Use:
+
+- `POST https://www.wixapis.com/payment-links/v1/payment-links/{paymentLinkId}/send`
+
+Request body:
+
+```json
+{
+  "paymentLinkId": "PAYMENT_LINK_ID",
+  "recipients": [
+    {
+      "contactId": "CONTACT_ID",
+      "sendMethods": ["EMAIL_METHOD"]
+    }
+  ]
+}
+```
+
+## Step 6: Query and manage payment links
+
+Query:
+
+- `POST https://www.wixapis.com/payment-links/v1/payment-links/query`
+
+```json
+{
+  "query": {
+    "filter": {
+      "status": "ACTIVE"
+    },
+    "cursorPaging": {
+      "limit": 50
+    }
+  }
+}
+```
+
+Get one:
+
+- `GET https://www.wixapis.com/payment-links/v1/payment-links/{paymentLinkId}`
+
+Deactivate:
+
+- `POST https://www.wixapis.com/payment-links/v1/payment-links/{paymentLinkId}/deactivate`
+
+Activate:
+
+- `POST https://www.wixapis.com/payment-links/v1/payment-links/{paymentLinkId}/activate`
+
+Delete (only when no payments were received):
+
+- `DELETE https://www.wixapis.com/payment-links/v1/payment-links/{paymentLinkId}`
+
+## Payment Link Statuses
+
+| Status | Description |
+|--------|-------------|
+| `ACTIVE` | Link is active and can receive payments |
+| `INACTIVE` | Link is inactive and cannot receive payments |
+| `PAID` | Payment has been completed |
+| `EXPIRED` | Link has passed its expiration date |
+
+## Common Errors
+
+| Error Code | Meaning |
+|------------|---------|
+| `UNPUBLISHED_SITE` | Site must be published before creating payment links |
+| `MISSING_ACCEPT_PAYMENTS` | Site is not set up to accept payments |
+| `FAILED_TO_INSTALL_ECOM` | Required eCommerce capability is missing |
+| `RECIPIENT_NOT_FOUND` | Provided recipient contact does not exist |
+| `ORDER_NOT_FOUND` | Provided order ID does not exist |
+| `INVALID_PAYMENTS_LIMIT_FOR_ECOM_ORDER_PAYMENT_LINK` | `ECOM_ORDER` links require `paymentsLimit: 1` |
+
+## Best Practices
+
+1. Validate prerequisites first (premium, published, payments enabled).
+2. Use `ECOM` for line-item collection and `ECOM_ORDER` for existing unpaid orders.
+3. Use IDs from real entities (products, variants, contacts, orders).
+4. Keep currency aligned with your business/order currency rules.
+5. Persist payment-link IDs and monitor status via query/get methods.
+
+## Related Documentation
+
+- [Payment Links API Reference](https://dev.wix.com/docs/api-reference/business-management/get-paid/payment-links/payment-links/introduction)
+- [Payments Overview](https://dev.wix.com/docs/api-reference/business-management/get-paid/payment-links/introduction)
+- [Products API Reference](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v1/catalog/introduction)
+- [Send Payment Link](https://dev.wix.com/docs/api-reference/business-management/get-paid/payment-links/payment-links/send-payment-link)