@wix/agent-skills 1.0.0

package/skills/wix-manage/references/app-installation/list-installed-apps.md

@@ -0,0 +1,124 @@
+---
+name: "List Installed Apps"
+description: Lists all apps installed on a site using Apps Installer API. Useful for verifying app installations before making API calls and diagnosing authorization errors.
+---
+# List Installed Apps on a Site
+
+This recipe guides you through listing all installed apps on a Wix site using the Apps Installer REST API. This is useful for verifying app installations before making API calls that require specific apps.
+
+## Prerequisites
+
+- Site ID for the site you want to check
+
+## Required APIs
+
+- **Apps Installer API**: [Get Installed Apps](https://dev.wix.com/docs/api-reference/business-management/app-installation/app-installation/get-installed-apps)
+
+---
+
+## Step 1: Query Installed Apps
+
+Use the Get Installed Apps endpoint to retrieve all apps installed on a site.
+
+**Endpoint**: `GET https://www.wixapis.com/apps-installer-service/v1/app-instances`
+
+**Request**:
+```bash
+curl -X GET \
+  'https://www.wixapis.com/apps-installer-service/v1/app-instances' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json'
+```
+
+**Response**:
+```json
+{
+  "appInstances": [
+    {
+      "id": "instance-id-1",
+      "appDefId": "1380b703-ce81-ff05-f115-39571d94dfcd",
+      "version": "^0.0.0",
+      "enabled": true,
+      "status": "UNKNOWN"
+    },
+    {
+      "id": "instance-id-2",
+      "appDefId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97",
+      "enabled": true,
+      "status": "UNKNOWN"
+    }
+  ]
+}
+```
+
+---
+
+## Step 2: Identify Apps by Definition ID
+
+Match the `appDefId` values from the response against known Wix app IDs.
+
+### Common Wix App Definition IDs
+
+| App | appDefId |
+|-----|----------|
+| Wix Stores | `1380b703-ce81-ff05-f115-39571d94dfcd` |
+| Wix Bookings | `13d21c63-b5ec-5912-8397-c3a5ddb27a97` |
+| Wix Blog | `14bcded7-0066-7c35-14d7-466cb3f09103` |
+| Wix Events | `140603ad-af8d-84a5-2c80-a0f60cb47351` |
+| Wix Pricing Plans | `1522827f-c56c-a5c9-2ac9-00f9e6ae12d3` |
+| Wix Restaurants | `13e8d036-5516-6f75-e025-2aca3b5d7930` |
+
+For a complete list, see [Apps Created by Wix](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix).
+
+---
+
+## Use Cases
+
+### Verify App Before API Calls
+
+Before calling APIs that require specific apps (e.g., Bookings, Stores), check if the app is installed:
+
+```javascript
+// Pseudocode example
+const installedApps = await getInstalledApps(siteId);
+const bookingsAppId = "13d21c63-b5ec-5912-8397-c3a5ddb27a97";
+
+const hasBookings = installedApps.appInstances.some(
+  app => app.appDefId === bookingsAppId
+);
+
+if (!hasBookings) {
+  // Install Bookings app first
+  // See: Install Wix Apps recipe
+}
+```
+
+### Diagnose Authorization Errors
+
+If you receive `401 Unauthorized` or `403 Forbidden` errors from Wix APIs:
+
+1. **List installed apps** using this recipe
+2. **Check if the required app** is in the response
+3. **If missing**: Install the app using the [Install Wix Apps](install-wix-apps.md) recipe
+4. **Retry the original API call**
+
+---
+
+## Error Handling
+
+### 401 Unauthorized
+- Verify your authentication token is valid
+- Check that the token has `APP-MARKET.VIEW-INSTALLED-APP` permission
+
+### Empty Response
+- The site may have no additional apps installed beyond core Wix functionality
+- This is normal for new or minimal sites
+
+---
+
+## Next Steps
+
+After checking installed apps:
+- **If app is missing**: Use the [Install Wix Apps](install-wix-apps.md) recipe to install required apps
+- **If app is installed but API fails**: Check API permissions and authentication
+- **For Bookings APIs**: See [Bookings recipes](../../SKILL.md) for service setup

package/skills/wix-manage/references/blog/how-to-create-blog-posts.md

@@ -0,0 +1,226 @@
+---
+name: "How to Create Blog Posts"
+description: Creates and publishes blog posts using Blog Posts API. Covers Ricos rich content format, image upload via Media Manager, category/tag assignment, and bulk post creation.
+---
+
+**Article: Create and Publish Blog Posts with Rich Content and Images**
+
+---
+
+## Description
+
+This article demonstrates how to create and immediately publish blog posts using Wix Blog REST API, including handling external images, rich content formatting, and proper media management workflow.
+
+### Part 0: Get an Author/Member ID (Required for 3rd-Party Apps)
+
+**IMPORTANT**: When calling the Blog API as a 3rd-party app (not as the site owner), `draftPost.memberId` is **required**. The API will reject requests with "Missing post owner information" if omitted.
+
+1. Query site members to get a valid member ID using [List Members](https://dev.wix.com/docs/api-reference/crm/members-contacts/members/member-management/members/list-members):
+
+   ```bash
+   curl -X GET "https://www.wixapis.com/members/v1/members?fieldsets=PUBLIC&paging.limit=1" \
+     -H "Authorization: <AUTH>"
+   ```
+
+2. Use the `id` field from the response as `draftPost.memberId` when creating the blog post. This member will be the post author.
+
+   > **Note**: The member ID must belong to an existing site member or collaborator. If the members query returns no results, you may need to create a member first or use the site owner's member ID.
+
+### Part 1: Import External Images to Wix Media Manager
+
+1. Identify external image URLs from user input for cover images and embedded content images.
+
+2. Import each external image using [Import File](https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/import-file). This converts external URLs to Wix Media IDs required for blog posts.
+
+   ```bash
+   curl -X POST "https://www.wixapis.com/site-media/v1/files/import" \
+     -H "Authorization: <AUTH>" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "url": "https://example.com/image.jpg",
+       "mediaType": "IMAGE",
+       "displayName": "Cover Image.jpg"
+     }'
+   ```
+
+   The response will include a `file.id` field. Use this ID in blog post creation. Images with `operationStatus: "PENDING"` can be used immediately.
+
+3. Store the returned file IDs for use in blog post creation.
+
+### Part 2: Create Blog Post with Rich Content
+
+1. Create blog post using [Create Draft Post](https://dev.wix.com/docs/api-reference/business-solutions/blog/draft-posts/create-draft-post) for single posts, or [Bulk Create Draft Posts](https://dev.wix.com/docs/api-reference/business-solutions/blog/draft-posts/bulk-create-draft-posts) for multiple posts.
+
+   ```bash
+   curl -X POST "https://www.wixapis.com/blog/v3/draft-posts" \
+     -H "Authorization: <AUTH>" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "draftPost": {
+         "title": "My Blog Post",
+         "memberId": "author-member-id",
+         "richContent": {
+           "nodes": [
+             {
+               "type": "PARAGRAPH",
+               "nodes": [{
+                 "type": "TEXT",
+                 "textData": {
+                   "text": "This is a paragraph with some content.",
+                   "decorations": []
+                 }
+               }],
+               "paragraphData": {}
+             }
+           ]
+         },
+         "media": {
+           "wixMedia": {
+             "image": { "id": "mediaId" }
+           },
+           "displayed": true,
+           "custom": true
+         }
+       },
+       "publish": true
+     }'
+   ```
+
+2. Structure rich content using Ricos JSON format. Reference [Ricos documentation](https://dev.wix.com/docs/api-reference/assets/rich-content/ricos-documents/introduction) for complete node structure. Common node types:
+   - `PARAGRAPH` for text content
+   - `HEADING` for section headers
+   - `IMAGE` for embedded images (requires Wix Media ID)
+   - `ORDERED_LIST` and `BULLETED_LIST` for lists
+   - `BLOCKQUOTE` for quoted text
+   - `LIST_ITEM` for individual list items
+
+   **CRITICAL**: All TEXT nodes MUST be wrapped in PARAGRAPH nodes within their parent containers.
+
+   **Correct Ricos structure example:**
+
+   ```json
+   {
+     "nodes": [
+       {
+         "type": "PARAGRAPH",
+         "nodes": [
+           {
+             "type": "TEXT",
+             "textData": {
+               "text": "This is a paragraph with some content.",
+               "decorations": []
+             }
+           }
+         ],
+         "paragraphData": {}
+       }
+     ]
+   }
+   ```
+
+   **Correct BLOCKQUOTE structure:**
+
+   ```json
+   {
+     "type": "BLOCKQUOTE",
+     "nodes": [
+       {
+         "type": "PARAGRAPH",
+         "nodes": [
+           {
+             "type": "TEXT",
+             "textData": { "text": "Quote text here", "decorations": [] }
+           }
+         ],
+         "paragraphData": {}
+       }
+     ],
+     "blockquoteData": { "indentation": 1 }
+   }
+   ```
+
+   **Correct LIST_ITEM structure:**
+
+   ```json
+   {
+     "type": "LIST_ITEM",
+     "nodes": [
+       {
+         "type": "PARAGRAPH",
+         "nodes": [
+           {
+             "type": "TEXT",
+             "textData": { "text": "List item text", "decorations": [] }
+           }
+         ],
+         "paragraphData": {}
+       }
+     ]
+   }
+   ```
+
+3. For embedded images in rich content, use IMAGE nodes with Wix Media IDs:
+
+   ```json
+   {
+     "type": "IMAGE",
+     "nodes": [],
+     "imageData": {
+       "containerData": {
+         "width": { "size": "CONTENT" },
+         "alignment": "CENTER"
+       },
+       "image": {
+         "src": { "id": "mediaId" },
+         "width": 900,
+         "height": 600
+       },
+       "altText": "Descriptive alt text"
+     }
+   }
+   ```
+
+4. Set `publish: true` to immediately publish the post rather than saving as draft.
+
+### Part 3: Handle Categories and Tags (Optional)
+
+1. Resolve category IDs using [List Categories](https://dev.wix.com/docs/api-reference/business-solutions/blog/category/list-categories) if user provides category names.
+
+2. Resolve tag IDs using [Query Tags](https://dev.wix.com/docs/api-reference/business-solutions/blog/tags/query-tags) if user provides tag labels.
+
+3. Include resolved IDs in `categoryIds` and `tagIds` arrays in the draft post object.
+
+### IMPORTANT NOTES:
+
+- Never mock blog posts or media IDs - always use the APIs to import images and create posts
+- Always read the full documentation of methods before implementation
+- External images MUST be imported via Import File API before use in blog posts - direct external URLs will not work
+- For 3rd-party app integrations, `memberId` is mandatory - use the [List Members](https://dev.wix.com/docs/api-reference/crm/members-contacts/members/member-management/members/list-members) API if needed to get member ID
+- Use ONLY the file ID (without `wix:image://v1/` prefix) for both cover images and embedded images
+- Rich content IMAGE nodes require both `width` and `height` properties in the `image` object
+- Images with `"operationStatus": "PENDING"` from import can be used immediately in blog posts
+- Set `publish: true` in the request to publish immediately rather than save as draft
+- For multiple posts, use Bulk Create Draft Posts API with `draftPosts` array
+- Include `fieldsets: ['URL']` to get post URLs in the response
+- Handle image import failures gracefully - continue without images if import fails
+- Provide meaningful `displayName` values during image import for better organization
+- Use appropriate Ricos node types (PARAGRAPH, HEADING, LIST, etc.) for semantic content structure
+- Consider batching image imports when creating multiple posts with many images
+
+### CRITICAL RICOS JSON STRUCTURE RULES:
+
+- **NEVER place TEXT nodes directly in BLOCKQUOTE, LIST_ITEM, or other container nodes**
+- **ALL TEXT nodes MUST be wrapped in PARAGRAPH nodes within their parent containers**
+- **BLOCKQUOTE nodes must contain PARAGRAPH nodes, which contain TEXT nodes**
+- **LIST_ITEM nodes must contain PARAGRAPH nodes, which contain TEXT nodes**
+- **Failure to follow proper nesting will result in parsing errors: "Expected a paragraph node but found TEXT"**
+- **Always validate Ricos structure before sending to ensure TEXT nodes are properly nested**
+
+### Troubleshooting
+
+| Error                                      | Cause                       | Solution                                                            |
+| ------------------------------------------ | --------------------------- | ------------------------------------------------------------------- |
+| "Missing post owner information"           | `memberId` not provided     | Add `draftPost.memberId` - see Part 0 for how to get one            |
+| "memberIds ... do not exist"               | Invalid member ID           | Query members first using List Members API to get valid IDs         |
+| "Expected a paragraph node but found TEXT" | Invalid Ricos structure     | Wrap TEXT nodes in PARAGRAPH nodes (see structure rules above)      |
+| Image not displaying                       | Using external URL directly | Import image via Media Manager first, then use the returned file ID |

package/skills/wix-manage/references/bookings/booking-service-policy-setup.md

@@ -0,0 +1,95 @@
+---
+name: "Booking Service Policy Setup"
+description: Sets up booking policies, cancellation rules, and waitlist configuration using the Services API policy fields. Covers bookingPolicy, cancellationPolicy, and waitlist settings.
+---
+
+# Technical Step-by-Step Instructions: Configuring Wix Bookings Service Policies (Real-World, API-First)
+
+## Description
+
+Below are the recommended steps to successfully configure booking, cancellation, and waitlist policies for Wix Bookings services. This recipe covers policy inheritance, service-specific overrides, and common policy configurations for different business models.
+
+---
+
+## Overview
+
+Wix Bookings policy configuration allows businesses to set rules for:
+
+- **Booking policies**: When customers can book, how far in advance, booking deadlines
+- **Cancellation policies**: Cancellation deadlines, refund rules, fees
+- **Waitlist policies**: When waitlists are enabled, capacity handling
+- **Group booking policies**: Maximum participants per booking
+
+Policies can be configured at two levels:
+
+- **Site-wide (business) policies**: Default rules that apply to all services
+- **Service-specific policies**: Override rules for individual services
+
+### IMPORTANT NOTES
+
+- Services inherit from site-wide booking policies by default
+- Service policies only override fields you explicitly specify - unspecified fields keep site defaults
+- Policy options available may vary based on service type (APPOINTMENT, CLASS, COURSE)
+- All policy configurations support the same core features across service types
+
+---
+
+## Steps
+
+### 1. Configure Site-Wide Business Policy (Optional)
+
+Set default policies that will apply to all services unless overridden. Use the Business Policy API to configure booking deadlines, cancellation rules, waitlist settings, and group booking limits.
+
+### 2. Create or Update Service with Policy Overrides
+
+When creating or updating a service, specify policy fields that should differ from business defaults. Only include the policy fields you want to override - unspecified fields will inherit from business defaults.
+
+### 3. Configure Course-Specific Policies
+
+Courses may have additional policy options such as `bookUntilXMinutesAfterStart` which allows customers to join courses even after they've started.
+
+### 4. Verify Policy Application
+
+Query the service to confirm policies are applied correctly. The service should show explicitly set policy fields with your specified values and unspecified fields inheriting from business defaults.
+
+### IMPORTANT NOTES
+
+- **Policy inheritance**: Only specify fields you want to override - leave others undefined to inherit business defaults
+- **Partial updates**: When updating service policies, only include fields you want to change
+- **Capacity requirements**: Waitlist policies require service capacity settings to be configured
+- **Group booking considerations**: `maxParticipantsPerBooking` works with all service types
+- **Time calculations**: Policy deadlines are calculated from booking start time in business timezone
+- **Course flexibility**: Course services support additional policy options like `bookUntilXMinutesAfterStart`
+
+### Troubleshooting Common Issues
+
+**Policies not applying:**
+
+- Verify you're setting policies on the service object, not as separate policy entities
+- Check that policy fields are properly nested under `service.policy`
+- Ensure you're updating the correct service ID
+
+**Waitlist not working:**
+
+- Confirm service has `maxParticipants` capacity set
+- Verify `waitingListPolicy.enabled` is `true`
+- Check that `waitingListPolicy.capacity` is set if you want limited waitlist size
+
+**Cancellation policies not enforced:**
+
+- Ensure `cancelRescheduleUpToInMinutes` is set to appropriate value
+- Verify `cancelationAllowed` is `true` if cancellations should be permitted
+- Check that payment and booking flow supports the configured policy
+
+**Group booking limits not working:**
+
+- Confirm `maxParticipantsPerBooking` is set to desired limit
+- Verify service type supports group bookings (all types do)
+- Check that booking UI respects the participant limit
+
+## API Documentation References
+
+- [Booking Policies API](https://dev.wix.com/docs/api-reference/business-solutions/bookings/policies/introduction)
+- [Bulk Create Services](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/bulk-create-services) — `POST https://www.wixapis.com/bookings/v2/bulk/services/create`
+- [Update Service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/update-service) — `PATCH https://www.wixapis.com/bookings/v2/services/<SERVICE_ID>`
+- [Query Services](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services) — `POST https://www.wixapis.com/bookings/v2/services/query`