@wix/agent-skills 1.0.0

package/skills/wix-manage/references/restaurants/wix-restaurants-setup.md

@@ -0,0 +1,336 @@
+---
+name: "Wix Restaurants Setup"
+description: Configures restaurant menus, sections, and items using Menus API. Covers menu structure (Menu → Section → Item), modifiers, pricing, availability schedules, and ordering settings.
+---
+# Wix Restaurants Setup API Reference
+
+This recipe covers setting up and configuring Wix Restaurants using the REST API, including menus, items, and ordering configuration.
+
+## Prerequisites
+
+1. Wix Restaurants app installed on the site
+2. API access with restaurant management permissions
+
+## Required APIs
+
+- **Menus API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/menus/create-menu)
+- **Menu Items API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/items/create-item)
+- **Menu Sections API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/sections/create-section)
+- **Item Modifier Groups API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/item-modifier-groups/create-modifier-group)
+- **Item Variants API**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/item-variants/bulk-create-variants)
+
+## Overview
+
+Wix Restaurants uses a hierarchical structure:
+- **Menus** (e.g., Breakfast, Lunch, Dinner)
+  - **Sections** (e.g., Appetizers, Main Courses, Desserts)
+    - **Items** (e.g., Caesar Salad, Grilled Salmon)
+
+## Step 1: Create a Menu
+
+**Endpoint**: `POST https://www.wixapis.com/restaurants/menus-menu/v1/menus`
+
+**Request Body**:
+```json
+{
+  "menu": {
+    "name": "Dinner Menu",
+    "description": "Our evening dining selections",
+    "visible": true
+  }
+}
+```
+
+**Response**:
+```json
+{
+  "menu": {
+    "id": "menu-id-123",
+    "name": "Dinner Menu",
+    "description": "Our evening dining selections",
+    "visible": true,
+    "createdDate": "2024-01-15T10:00:00.000Z"
+  }
+}
+```
+
+## Step 2: Create Menu Sections
+
+**Endpoint**: `POST https://www.wixapis.com/restaurants/menus-section/v1/sections`
+
+**Request Body**:
+```json
+{
+  "section": {
+    "name": "Appetizers",
+    "description": "Start your meal with our delicious starters",
+    "visible": true,
+    "sortOrder": 1
+  }
+}
+```
+
+Create multiple sections:
+```json
+// Section 1: Appetizers
+{
+  "section": {
+    "name": "Appetizers",
+    "sortOrder": 1
+  }
+}
+
+// Section 2: Main Courses
+{
+  "section": {
+    "name": "Main Courses",
+    "sortOrder": 2
+  }
+}
+
+// Section 3: Desserts
+{
+  "section": {
+    "name": "Desserts",
+    "sortOrder": 3
+  }
+}
+```
+
+## Step 3: Create Menu Items
+
+**Endpoint**: `POST https://www.wixapis.com/restaurants/menus-item/v1/items`
+
+**Request Body**:
+```json
+{
+  "item": {
+    "name": "Caesar Salad",
+    "description": "Fresh romaine lettuce with house-made Caesar dressing, croutons, and parmesan",
+    "priceInfo": { "price": "14.99" },
+    "visible": true,
+    "labels": [],
+    "modifierGroups": []
+  }
+}
+```
+
+## Step 4: Add Items to Sections
+
+**Endpoint**: `PATCH https://www.wixapis.com/restaurants/menus-section/v1/sections/{sectionId}`
+
+Each section update requires the latest section `revision`.
+
+```json
+{
+  "section": {
+    "id": "<SECTION_ID>",
+    "revision": "<SECTION_REVISION>",
+    "itemIds": ["item-id-1", "item-id-2", "item-id-3"]
+  }
+}
+```
+
+## Step 5: Configure Item Options and Modifiers
+
+Create modifiers for customization (e.g., cooking temperature, add-ons):
+
+**Endpoint**: `POST https://www.wixapis.com/restaurants/item-modifier-group/v1/modifier-groups`
+
+```json
+{
+  "modifier": {
+    "name": "Cooking Temperature",
+    "required": true,
+    "minSelections": 1,
+    "maxSelections": 1,
+    "options": [
+      {
+        "name": "Rare",
+        "price": {
+          "amount": "0",
+          "currency": "USD"
+        }
+      },
+      {
+        "name": "Medium Rare",
+        "price": {
+          "amount": "0",
+          "currency": "USD"
+        }
+      },
+      {
+        "name": "Medium",
+        "price": {
+          "amount": "0",
+          "currency": "USD"
+        }
+      },
+      {
+        "name": "Well Done",
+        "price": {
+          "amount": "0",
+          "currency": "USD"
+        }
+      }
+    ]
+  }
+}
+```
+
+Add-on modifier with pricing:
+```json
+{
+  "modifier": {
+    "name": "Add-ons",
+    "required": false,
+    "minSelections": 0,
+    "maxSelections": 5,
+    "options": [
+      {
+        "name": "Extra Cheese",
+        "price": {
+          "amount": "2.00",
+          "currency": "USD"
+        }
+      },
+      {
+        "name": "Bacon",
+        "price": {
+          "amount": "3.00",
+          "currency": "USD"
+        }
+      },
+      {
+        "name": "Avocado",
+        "price": {
+          "amount": "2.50",
+          "currency": "USD"
+        }
+      }
+    ]
+  }
+}
+```
+
+## Step 6: Set Menu Structure (Attach Sections to Menu)
+
+Attach section IDs to a menu. This call requires the latest menu `revision`.
+
+**Endpoint**: `PATCH https://www.wixapis.com/restaurants/menus-menu/v1/menus/{menuId}`
+
+```json
+{
+  "menu": {
+    "id": "<MENU_ID>",
+    "revision": "<MENU_REVISION>",
+    "sectionIds": ["<SECTION_ID_1>", "<SECTION_ID_2>"]
+  }
+}
+```
+
+## Step 7: Bulk Operations for Large Menus
+
+For restaurant setup flows with many sections/items, use bulk endpoints:
+
+- **Bulk Create Sections**: `POST https://www.wixapis.com/restaurants/menus-section/v1/bulk/sections/create`
+- **Bulk Create Items**: `POST https://www.wixapis.com/restaurants/menus-item/v1/bulk/items/create`
+- **Bulk Create Variants**: `POST https://www.wixapis.com/restaurants/item-variants/v1/bulk/variants/create`
+
+```json
+{
+  "sections": [
+    { "name": "Appetizers", "visible": true },
+    { "name": "Main Courses", "visible": true }
+  ],
+  "returnEntity": true
+}
+```
+
+## Step 8: Query Menus / Sections / Items
+
+Use query APIs for retrieval and UI display flows.
+
+- **Query Menus**: `POST https://www.wixapis.com/restaurants/menus-menu/v1/menus/query`
+- **Query Sections**: `POST https://www.wixapis.com/restaurants/menus-section/v1/sections/query`
+- **Query Items**: `POST https://www.wixapis.com/restaurants/menus-item/v1/items/query`
+
+```json
+{
+  "query": {
+    "cursorPaging": {
+      "limit": 50
+    }
+  }
+}
+```
+
+## Query Menus
+
+**Endpoint**: `GET https://www.wixapis.com/restaurants/menus-menu/v1/menus`
+
+**Response**:
+```json
+{
+  "menus": [
+    {
+      "id": "menu-1",
+      "name": "Breakfast Menu",
+      "visible": true,
+      "sections": [...]
+    },
+    {
+      "id": "menu-2",
+      "name": "Lunch Menu",
+      "visible": true,
+      "sections": [...]
+    }
+  ]
+}
+```
+
+## Recommended Setup Order
+
+For complex restaurant menus, use this order to avoid dependency issues:
+
+1. Create variants (sizes/options) if needed.
+2. Create items (single or bulk).
+3. Create sections (single or bulk).
+4. Update each section with `itemIds`.
+5. Update menu with `sectionIds`.
+
+## Item Labels
+
+Common dietary labels:
+- `vegetarian`
+- `vegan`
+- `gluten-free`
+- `gluten-free-option`
+- `dairy-free`
+- `nut-free`
+- `spicy`
+- `chef-recommendation`
+
+## Best Practices
+
+1. **High-Quality Images**: Use appetizing food photography
+2. **Clear Descriptions**: Include ingredients and preparation methods
+3. **Accurate Pricing**: Keep prices up-to-date
+4. **Stock Management**: Update availability in real-time
+5. **Modifier Organization**: Group related customizations logically
+6. **Menu Structure**: Organize sections in logical dining order
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `MENU_NOT_FOUND` | Invalid menu ID | Verify menu exists |
+| `ITEM_NOT_FOUND` | Invalid item ID | Verify item exists |
+| `INVALID_PRICE` | Negative price | Use positive amounts |
+
+## Related Documentation
+
+- [Menus API Reference](https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/menus/introduction)
+- [Menu Items API Reference](https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/items/items/introduction)
+- [Menu Sections API Reference](https://dev.wix.com/docs/api-reference/business-solutions/restaurants/menus/sections/introduction)
+- [Restaurant Orders API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/introduction)

package/skills/wix-manage/references/rich-content/ricos-converter-service.md

@@ -0,0 +1,295 @@
+---
+name: "Ricos Converter Service"
+description: Validates and converts content between Ricos documents and HTML/Markdown/plain text using the Ricos Documents API. Covers plugin configuration, format conversion in both directions, and document validation.
+---
+# Rich Content (Ricos) Converter Service
+
+This recipe covers how to validate and convert content between Ricos documents (Wix's rich content format) and other formats like HTML, Markdown, and plain text.
+
+## Overview
+
+Ricos is Wix's rich content format used across various Wix applications (Blog, Stores, etc.). The [Ricos Documents API](https://dev.wix.com/docs/api-reference/assets/rich-content/ricos-documents/introduction) provides:
+- **Validation**: Check if a document conforms to the Ricos format
+- **Convert to Ricos**: Transform HTML, Markdown, or plain text into a Ricos document
+- **Convert from Ricos**: Transform a Ricos document back to HTML, Markdown, or plain text
+
+Learn more about [Rich Content](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-rich-content) and [Ricos document structure](https://dev.wix.com/docs/ricos/getting-started/introduction).
+
+## Required API Endpoints
+
+| Method | Endpoint | Docs |
+|--------|----------|------|
+| Validate Document | `POST https://www.wixapis.com/ricos/v1/ricos-document/validate` | [Schema](https://dev.wix.com/docs/api-reference/assets/rich-content/ricos-documents/validate-document) |
+| Convert To Ricos | `POST https://www.wixapis.com/ricos/v1/ricos-document/convert/to-ricos` | [Schema](https://dev.wix.com/docs/api-reference/assets/rich-content/ricos-documents/convert-to-ricos-document) |
+| Convert From Ricos | `POST https://www.wixapis.com/ricos/v1/ricos-document/convert/from-ricos` | [Schema](https://dev.wix.com/docs/api-reference/assets/rich-content/ricos-documents/convert-from-ricos-document) |
+
+---
+
+## Available Plugins
+
+Plugins determine which content types are recognized when validating or converting. Specify them as uppercase enum values:
+
+| Plugin Enum | Description |
+|-------------|-------------|
+| `ACTION_BUTTON` | Call-to-action buttons |
+| `AUDIO` | Audio content |
+| `CODE_BLOCK` | Code snippets |
+| `COLLAPSIBLE_LIST` | Expandable/collapsible lists |
+| `DIVIDER` | Section dividers |
+| `EMOJI` | Emoji support |
+| `FILE` | File attachments |
+| `FONT_FAMILY` | Font family selection |
+| `GALLERY` | Image galleries |
+| `GIPHY` | GIF integration |
+| `HASHTAG` | Hashtag support |
+| `HEADING` | Headings (h1-h6) |
+| `HTML` | Raw HTML blocks |
+| `IMAGE` | Images |
+| `INDENT` | Text indentation |
+| `LAYOUT` | Layout containers |
+| `LINE_SPACING` | Line spacing control |
+| `LINK` | Hyperlinks |
+| `LINK_BUTTON` | Link buttons |
+| `LINK_PREVIEW` | Link previews |
+| `MENTIONS` | @mentions |
+| `POLL` | Polls |
+| `SPOILER` | Spoiler/hidden content |
+| `TABLE` | Tables |
+| `TEXT_COLOR` | Text color |
+| `TEXT_HIGHLIGHT` | Text highlighting |
+| `VERTICAL_EMBED` | Vertical embeds |
+| `VIDEO` | Video content |
+
+### IMPORTANT NOTES:
+- Plugin values must be **UPPERCASE** enum strings (e.g., `"HEADING"`, not `"heading"`)
+- Content using unsupported plugins will result in validation violations
+- When converting HTML, only elements matching your plugins are converted
+
+---
+
+## Step 1: Validate a Ricos Document
+
+Check if a document conforms to the Ricos format and optionally fix issues.
+
+**Endpoint**: `POST https://www.wixapis.com/ricos/v1/ricos-document/validate` ([docs](https://dev.wix.com/docs/api-reference/assets/rich-content/ricos-documents/validate-document))
+
+**Request Body**:
+```json
+{
+  "document": {
+    "nodes": [
+      {
+        "type": "PARAGRAPH",
+        "id": "p1",
+        "nodes": [
+          {
+            "type": "TEXT",
+            "id": "t1",
+            "textData": {
+              "text": "Hello World",
+              "decorations": []
+            }
+          }
+        ],
+        "paragraphData": {}
+      }
+    ]
+  },
+  "plugins": ["HEADING", "LINK", "IMAGE", "TEXT_COLOR"],
+  "fixDocument": true
+}
+```
+
+**Response**:
+```json
+{
+  "valid": true,
+  "violations": [],
+  "validDocument": {
+    "nodes": [
+      {
+        "type": "PARAGRAPH",
+        "id": "p1",
+        "nodes": [
+          {
+            "type": "TEXT",
+            "id": "t1",
+            "textData": {
+              "text": "Hello World",
+              "decorations": []
+            }
+          }
+        ],
+        "paragraphData": {}
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Step 2: Convert HTML to Ricos
+
+Transform HTML content into Ricos document format.
+
+**Endpoint**: `POST https://www.wixapis.com/ricos/v1/ricos-document/convert/to-ricos` ([docs](https://dev.wix.com/docs/api-reference/assets/rich-content/ricos-documents/convert-to-ricos-document))
+
+**Request Body**:
+```json
+{
+  "html": "<h1>Welcome</h1><p>This is a <strong>bold</strong> paragraph with a <a href=\"https://example.com\">link</a>.</p>",
+  "options": {
+    "plugins": ["HEADING", "LINK", "TEXT_COLOR", "TEXT_HIGHLIGHT"]
+  }
+}
+```
+
+**Response**:
+```json
+{
+  "document": {
+    "nodes": [
+      {
+        "type": "HEADING",
+        "id": "",
+        "headingData": { "level": 1 },
+        "nodes": [
+          { "type": "TEXT", "textData": { "text": "Welcome", "decorations": [] } }
+        ]
+      },
+      {
+        "type": "PARAGRAPH",
+        "id": "",
+        "nodes": [
+          { "type": "TEXT", "textData": { "text": "This is a ", "decorations": [] } },
+          { "type": "TEXT", "textData": { "text": "bold", "decorations": [{ "type": "BOLD", "fontWeightValue": 700 }] } },
+          { "type": "TEXT", "textData": { "text": " paragraph with a ", "decorations": [] } },
+          { "type": "TEXT", "textData": { "text": "link", "decorations": [{ "type": "LINK", "linkData": { "link": { "url": "https://example.com", "target": "SELF" } } }] } },
+          { "type": "TEXT", "textData": { "text": ".", "decorations": [] } }
+        ]
+      }
+    ],
+    "metadata": { "version": 1 }
+  }
+}
+```
+
+---
+
+## Step 3: Convert Markdown to Ricos
+
+Uses the same endpoint as HTML conversion, with `markdown` instead of `html`.
+
+**Request Body**:
+```json
+{
+  "markdown": "# Welcome\n\nThis is a **bold** paragraph with a [link](https://example.com).",
+  "options": {
+    "plugins": ["HEADING", "LINK", "CODE_BLOCK"]
+  }
+}
+```
+
+---
+
+## Step 4: Convert Plain Text to Ricos
+
+**Request Body**:
+```json
+{
+  "plainText": "This is plain text content.\n\nIt will be converted to paragraphs.",
+  "options": {
+    "plugins": []
+  }
+}
+```
+
+---
+
+## Step 5: Convert Ricos to HTML / Markdown / Plain Text
+
+Convert a Ricos document back to another format.
+
+**Endpoint**: `POST https://www.wixapis.com/ricos/v1/ricos-document/convert/from-ricos` ([docs](https://dev.wix.com/docs/api-reference/assets/rich-content/ricos-documents/convert-from-ricos-document))
+
+**Request Body (to HTML)**:
+```json
+{
+  "document": {
+    "nodes": [
+      {
+        "type": "HEADING",
+        "id": "h1",
+        "headingData": { "level": 1 },
+        "nodes": [
+          { "type": "TEXT", "id": "t1", "textData": { "text": "Welcome", "decorations": [] } }
+        ]
+      },
+      {
+        "type": "PARAGRAPH",
+        "id": "p1",
+        "nodes": [
+          { "type": "TEXT", "id": "t2", "textData": { "text": "Hello world with ", "decorations": [] } },
+          { "type": "TEXT", "id": "t3", "textData": { "text": "bold", "decorations": [{ "type": "BOLD", "fontWeightValue": 700 }] } }
+        ],
+        "paragraphData": {}
+      }
+    ]
+  },
+  "targetFormat": "HTML"
+}
+```
+
+**Response**:
+```json
+{
+  "html": "<h1>Welcome</h1><p>Hello world with <span style=\"font-weight: 700\">bold</span></p>"
+}
+```
+
+**Target format options**: `"HTML"`, `"MARKDOWN"`, `"PLAIN_TEXT"`
+
+For plain text, you can include optional settings:
+```json
+{
+  "document": { "nodes": [...] },
+  "targetFormat": "PLAIN_TEXT",
+  "plainTextOptions": {
+    "includeLinks": true,
+    "includeMediaLinks": true
+  }
+}
+```
+
+---
+
+## Common Use Cases
+
+### Blog Post Content Import
+When importing blog content from external sources:
+1. Convert HTML/Markdown to Ricos format using Convert To Ricos
+2. Validate the converted document with `fixDocument: true`
+3. Use the validated document in the Blog Posts API
+
+### Rich Content Validation Before Saving
+Before saving rich content:
+1. Validate with `fixDocument: true`
+2. Use the returned `validDocument` for saving
+3. Check `violations` array for any issues
+
+### Round-Trip Conversion
+Convert between formats for editing workflows:
+1. Convert Ricos to Markdown for a Markdown editor
+2. Convert edited Markdown back to Ricos for storage
+3. See [Sample Flows](https://dev.wix.com/docs/api-reference/assets/rich-content/ricos-documents/sample-flows) for a detailed example
+
+---
+
+## Gotchas & Troubleshooting
+- Maximum content length: 10,000 characters for HTML, Markdown, or plain text
+- Plugin limits: Maximum 100 plugins per request
+- Plugin name max length: 30 characters
+- If converting HTML with images but `IMAGE` plugin not specified, images are silently dropped
+- Always validate converted content before using in production
+- The plain text `convert/from-ricos` response concatenates text without separators between nodes — use `includeLinks: true` in `plainTextOptions` if you need link URLs preserved

package/skills/wix-manage/references/site-properties/change-payment-currency-site-properties.md

@@ -0,0 +1,59 @@
+---
+name: "RECIPE: Change a Site's Payment (Store) Currency via Site Properties API"
+description: "Updates the site-level payment currency (store billing currency) using Site Properties API, including the required request body shape and field mask."
+---
+
+# RECIPE: Change a Site's Payment (Store) Currency via Site Properties API
+
+## Goal
+Update a Wix site's **payment currency** (the ISO-4217 currency code used to bill customers) programmatically.
+
+## When to use
+- You need to switch a site's store/payment currency (for example, from `USD` to `EUR`).
+- You want to automate regional/business setup for sites.
+
+## Important notes before you start
+- The `paymentCurrency` field is part of **Site Properties** (often shown in the dashboard under regional/business info).
+- A successful update increments the Site Properties `version`.
+- Use a **field mask** (`fields.paths`) to indicate which fields you're updating.
+
+## Step 1 — (Optional) Read current site properties version
+This is useful to understand the current snapshot version and other regional fields.
+
+```bash
+curl -X GET 'https://www.wixapis.com/site-properties/v4/properties' \
+  -H 'Authorization: <AUTH>'
+```
+
+## Step 2 — Update the payment currency
+Use the `PATCH /site-properties/v4/properties` endpoint: put the new currency under `properties.paymentCurrency` and include a `fields.paths` mask.
+
+```bash
+curl -X PATCH 'https://www.wixapis.com/site-properties/v4/properties' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  --data-binary '{
+    "properties": {
+      "paymentCurrency": "EUR"
+    },
+    "fields": {
+      "paths": ["paymentCurrency"]
+    }
+  }'
+```
+
+### Expected response
+A successful call returns an updated Site Properties snapshot version, for example:
+
+```json
+{ "version": "123" }
+```
+
+## Gotchas & troubleshooting
+- **Always send a field mask**: omitting `fields.paths` will fail with `400` and `"Illegal request - No updates on request body"`.
+- Currency must be a **3-letter ISO-4217** code (for example, `USD`, `CAD`, `EUR`, `GBP`).
+
+## Related APIs
+- **Site Properties API**: [REST](https://dev.wix.com/docs/api-reference/business-management/site-properties/properties/introduction)
+- Stores Currency Converter (conversion utilities, not for setting the site currency):
+  - `POST https://www.wixapis.com/currency_converter/v1/currencies/amounts/{from}/convert/{to}`