@wix/agent-skills 1.0.0

package/skills/wix-manage/references/bookings/multi-resource-service-creation.md

@@ -0,0 +1,231 @@
+---
+name: "Multi-Resource Service Creation"
+description: Creates resource types and individual resources using Resources API. Enables services that require multiple resources (rooms + equipment + staff) with automatic allocation.
+---
+# Technical Step-by-Step Instructions: Creating Multi-Resource Bookings Services (Rooms, Equipment, Staff) - Real-World, API-First
+
+## Description
+
+Below are the recommended steps to successfully create Wix Bookings services that require multiple resource types (e.g., Room + Equipment + Instructor). This recipe covers the **gaps** in individual API documentation: resource architecture planning, entity relationship patterns, availability dependencies, and real-world coordination challenges that aren't clear from reading individual API references.
+
+
+---
+
+## Prerequisites
+
+### Required App Installations
+
+Before creating multi-resource services, ensure the following requirements are met:
+
+1. **Wix Bookings** - Core app must be installed and configured
+2. **Premium Plan** - Advanced resource management typically requires premium features
+3. **Business Location** - At least one business location must be configured
+
+### App Installation Process
+
+If you encounter resource-related errors, install the required apps using the Apps Installer API.
+
+**For detailed app installation procedures, refer to:**
+- [Apps Installer API Documentation](https://dev.wix.com/docs/api-reference/business-management/app-installation/install-app)
+- Business setup recipes for comprehensive app installation workflows
+
+## Overview
+
+Multi-resource services allow businesses to create bookings that require multiple types of resources simultaneously. Common examples:
+- **Fitness Classes**: Room + Equipment + Instructor
+- **Meeting Services**: Conference Room + AV Equipment + Catering Staff
+- **Spa Treatments**: Treatment Room + Specialized Equipment + Therapist
+
+The system involves three independent entity types that can be connected:
+1. **Resource Types** - Category definitions (Room, Equipment, Staff) - independent entities
+2. **Resources** - Individual resource instances with their own schedules and availability - independent entities
+3. **Services** - Booking services that can optionally reference resource types - independent entities
+
+**Key Architecture Principle**: Resources and Services are **separate, independent entities**. Resources exist independently but their availability depends on business location hours (for non-staff resources) or working hour schedules (for staff resources). Services can optionally connect to resource types (not individual resources) to require resource allocation during booking, but this connection is loose and flexible.
+
+### CRITICAL API DISCOVERY
+
+**❌ COMMON ARCHITECTURE MISTAKES** (Not Clear in Individual Docs):
+- Creating resources without resource types first (creation sequence matters)
+- Assuming resources automatically inherit business hours (availability dependency isn't clear)
+- Thinking you can connect same resource to conflicting schedules
+
+**✅ CORRECT RESOURCE ARCHITECTURE**:
+- **Independent Creation**: Resource Types → Resources (both exist independently)
+- **Optional Service Connection**: Services can reference resource types when resource allocation is needed
+- **Loose Coupling**: Resources maintain their own schedules and availability regardless of service connections
+- **Type-Based References**: Services connect to `resourceType.id`, not individual resource IDs
+- **Resource Autonomy**: Resources function independently - services simply request allocation from available resources of specified types
+
+### Key Discovery: Resource Schedule Behavior
+
+**Resource Availability Behavior:**
+- Each resource automatically gets a dedicated `eventsSchedule` for tracking bookings
+- **Non-staff resources**: Availability depends on business location hours (not 24/7)
+- **Staff resources**: Have working hour schedules in addition to event schedules
+- **Working hours override**: When `workingHoursSchedules` is configured, it takes precedence over location hours
+
+**Schedule Sharing Patterns:**
+- `shared: false` = Dedicated schedule per resource (recommended for most cases)
+- `shared: true` = Multiple resources use same working hours schedule
+- Business schedule is always `shared: true` among staff
+
+### Key Discovery: Service-Resource Connection Pattern
+
+**Service Configuration Pattern:**
+```json
+"serviceResources": [
+  {"resourceType": {"id": "room-type-id"}},
+  {"resourceType": {"id": "equipment-type-id"}},
+  {"resourceType": {"id": "staff-type-id"}}
+]
+```
+**Critical**: Services specify resource **types**, not individual resources. This creates a **loose coupling** where:
+- Resources exist independently but availability follows business location hours (non-staff) or working hours (staff)
+- Services request allocation from available resources of specified types during booking
+- No direct binding between individual resources and services
+- Resource management (updates, working hours) is independent of service configuration
+
+### IMPORTANT NOTES
+
+* **Entity Independence**: Resources and Services are separate entities - you can create and manage resources without any services, and vice versa
+* **Optional Connection**: Services only need to reference resource types if they require resource allocation for bookings
+* **Location Complexity**: `availableInAllLocations: true` is simplest; specific location configuration is complex and often unnecessary
+* **Service Pricing**: Multi-resource services often justify higher pricing due to resource coordination complexity
+
+---
+
+## Steps
+
+### 1. Plan Resource Type Architecture
+
+Before creating anything, plan your resource type structure. Each type should represent a category of resources that can be substituted for each other in bookings.
+
+**Common Resource Type Patterns:**
+- **Physical Spaces**: Room, Studio, Meeting Room, Treatment Room
+- **Equipment Categories**: AV Equipment, Medical Equipment, Sports Equipment
+- **Human Resources**: Instructor, Therapist, Consultant, Technician
+
+**Design Principle**: If resources are interchangeable for a service, they belong to the same type.
+
+### 2. Create Resource Types
+
+Create resource types using `createResourceType` API (`POST https://www.wixapis.com/bookings/v2/resources/resource-types`) ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resource-types-v2/create-resource-type)):
+
+**Key Requirements:**
+- `name` must be unique across the site
+- Keep `name` descriptive but concise (appears in booking interface)
+- Save the returned `resourceType.id` for resource creation
+
+**Important**: Cannot change `name` after creation if conflicts occur - plan carefully.
+
+### 3. Create Individual Resources
+
+For each resource type, create the individual resource instances using `createResource` API (`POST https://www.wixapis.com/bookings/v2/resources`) ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resources-v2/create-resource)):
+
+**Gap Not in Docs**: The docs don't clearly explain that `availableInAllLocations: true` is the simplest approach and that specific location configuration is complex and often unnecessary.
+
+**Advanced Configuration (Gap):**
+- Custom working hours override business location hours (this behavior isn't clearly documented)
+- Specific locations: Use `specificLocationOptions` (complex - avoid unless required)
+
+**Critical**: Each resource automatically gets its own `eventsSchedule` for booking management (this is documented but the implications for multi-resource coordination aren't clear).
+
+### 4. Create Multi-Resource Service (Optional Connection)
+
+Create the service that optionally connects to multiple resource types using `bulkCreateServices` API ([REST](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/bulk-create-services)):
+
+**Service Resource Configuration:**
+```json
+"serviceResources": [
+  {"resourceType": {"id": "room-type-id"}},
+  {"resourceType": {"id": "equipment-type-id"}},
+  {"resourceType": {"id": "instructor-type-id"}}
+]
+```
+
+**Key Principle**: This creates a **loose connection** where the service requests resource allocation during booking, but resources remain independent entities with their own lifecycle and management.
+
+**Pricing Strategy**: Multi-resource services typically command premium pricing due to coordination complexity.
+
+### 5. Understand Resource Allocation Behavior (Gap in Docs)
+
+The docs don't explain how multi-resource allocation actually works during booking. Key behaviors to understand:
+- **Peak time conflicts**: When Room 1 is booked, Wix automatically tries Room 2 for the same resource type
+- **Equipment maintenance**: Blocking specific resources affects all services requiring that resource type
+- **Cross-resource dependencies**: If ANY required resource type has no availability, the entire booking fails
+
+**Architecture Implication**: Plan resource quantities based on expected concurrent demand across all services.
+
+### IMPORTANT NOTES
+
+* **Resource Allocation Logic**: Wix automatically handles resource selection during booking - you specify types, not individual resources
+* **Conflict Resolution**: If any required resource type has no available resources, the entire booking fails
+* **Service Modification**: Adding/removing resource type requirements from existing services may affect existing bookings
+* **Performance Consideration**: Complex multi-resource services may have slower booking availability calculation
+
+### Troubleshooting Common Issues
+
+**"Resource type not found" Error:**
+- Verify resource type was created successfully before creating resources
+- Check that `typeId` exactly matches the resource type `id`
+- Ensure you're not using resource type `name` when `id` is required
+
+**"Resource type name already exists" Error (409):**
+- Resource type names must be unique across the site
+- Query existing resource types to avoid duplicates
+- Consider using more specific names (e.g., "Meeting Room" vs "Room")
+
+**Service doesn't show resource requirements:**
+- Verify `serviceResources` array includes all required resource types
+- Check that resource type IDs are correct
+- Confirm service creation was successful with proper resource configuration
+
+**Resources showing as unavailable:**
+- Check if `workingHoursSchedules` is too restrictive
+- Verify `locationOptions` matches your business location setup
+- Test with `availableInAllLocations: true` to eliminate location issues
+
+**Resource updates failing:**
+- Handle revision conflicts with retry logic (revision requirement is documented but conflict handling strategies aren't)
+
+**Complex location availability issues:**
+- Start with `availableInAllLocations: true` for all resources
+- Only add location restrictions if absolutely necessary
+- Location configuration is complex and often causes more problems than it solves
+
+**Resource deletion concerns:**
+- Deleting resources with active bookings may cause issues (deletion cleanup is documented but impact on existing bookings isn't clear)
+- Consider disabling/hiding resources instead of deletion
+
+### Resource Architecture Best Practices
+
+**Resource Type Design:**
+- Keep types broad enough to allow flexibility but specific enough to be meaningful
+- Plan for growth - easier to split types later than merge them
+- Use clear, customer-facing names (they appear in booking interfaces)
+
+**Resource Naming:**
+- Include location/identifier in resource names for easy management
+- Be consistent with naming patterns across resource types
+- Consider how names appear in booking confirmations and staff interfaces
+
+**Availability Strategy:**
+- Default to 24/7 availability unless business rules require restrictions
+- Use working hours sparingly - they add complexity without always adding value
+- Test availability scenarios thoroughly before going live
+
+**Service Design:**
+- Start with simpler single-resource services before attempting multi-resource
+- Consider premium pricing for multi-resource services due to coordination complexity
+- Plan for resource substitution scenarios (what if preferred room is unavailable?)
+
+## API Documentation References
+
+* [Create Resource Type](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resource-types-v2/create-resource-type)
+* [Create Resource](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resources-v2/create-resource)
+* [Update Resource](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resources-v2/update-resource)
+* [Bulk Create Services](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/bulk-create-services)
+* [Query Resources](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resources-v2/query-resources)
+* [Calendar Schedules API](https://dev.wix.com/docs/api-reference/business-management/calendar/schedules-v3/introduction)
+* [Apps Installer API](https://dev.wix.com/docs/api-reference/business-management/app-installation/install-app)

package/skills/wix-manage/references/calendar/configure-default-business-hours.md

@@ -0,0 +1,226 @@
+---
+name: "Configure Default Business Hours"
+description: Uses Calendar Events API to create WORKING_HOURS events on the business schedule. Covers the critical distinction between Calendar Events API (correct) vs Site Properties API (incorrect) for setting base availability.
+---
+# Technical Step-by-Step Instructions: Setting Up Wix Bookings Default Business Hours (Real-World, API-First)
+
+## Description
+
+Below are the recommended steps to successfully configure default business hours for Wix Bookings, which control the base availability shown in the "Set default hours" dashboard. This recipe covers the correct API usage, common pitfalls, and cleanup procedures for managing business schedule events.
+
+---
+
+## Prerequisites
+
+- **Wix Bookings app installed** (App ID: `13d21c63-b5ec-5912-8397-c3a5ddb27a97`)
+
+> **Note:** If you receive errors from Bookings APIs, the Wix Bookings app may not be installed on the site. Use [List Installed Apps](../app-installation/list-installed-apps.md) to verify, and [Install Wix Apps](../app-installation/install-wix-apps.md) to install it if missing.
+
+## Overview
+
+Wix Bookings default business hours define the base availability for your booking system and appear in the Bookings dashboard under "Set default hours". These hours:
+
+- **Control base availability**: Set when your business is generally available for bookings
+- **Apply to new staff**: Default working hours that new staff members inherit
+- **Display in dashboard**: Show as time slots in the "Set default hours" interface
+
+### 🚨 CRITICAL: Default Hours Upon Installation
+
+**IMPORTANT**: When Wix Bookings is first installed on a site, it automatically creates DEFAULT business hours (typically 9 AM - 5 PM, Monday through Friday). You CANNOT simply create new hours without handling these existing default hours first.
+
+**You MUST either:**
+1. **Update the existing default hours** to your desired schedule, OR
+2. **Delete the existing default hours** and create new ones
+
+**Failure to handle existing hours will result in:**
+- Duplicate time slots in the dashboard
+- Conflicting availability schedules
+- Unexpected booking behavior
+
+### CRITICAL API DISCOVERY
+
+**❌ WRONG API**: Site Properties API (`/site-properties/v4/properties/business-schedule`)
+- This sets general site business schedule, NOT Bookings default hours
+
+**✅ CORRECT API**: Calendar Events V3 API (`/calendar/v3/events`)
+- Creates `WORKING_HOURS` events on the business schedule
+- Each `MASTER` event creates one time slot in the dashboard
+- Uses fixed business resource ID: `4e0579a5-491e-4e70-a872-d097eed6e520`
+
+### Key Discovery: Universal Business Schedule External ID
+
+**VERIFIED**: The business schedule external ID `"4e0579a5-491e-4e70-a872-d097eed6e520"` is **universal across all Wix sites**.
+
+This has been tested and confirmed on multiple different Wix sites:
+- All sites have a business schedule with this exact external ID
+- The schedule name is consistently `"business"`
+- While the internal schedule `id` varies per site, the `externalId` is constant
+- This makes the recipe reliable without requiring site-specific discovery
+
+### IMPORTANT NOTES
+
+* **Universal External ID**: The business schedule external ID `"4e0579a5-491e-4e70-a872-d097eed6e520"` is verified to work across all Wix sites
+* **Default Hours Always Exist**: Every Wix Bookings installation creates default hours automatically
+* **Event Scheduling Flexibility**: Businesses can create multiple time slots per day or complex schedules as needed - there are no restrictions on number of events per day
+* **MASTER vs INSTANCE Events**: Based on observed behavior, MASTER events appear to generate INSTANCE events automatically, but always verify current event state when working with recurring events
+* **Query Patterns**: Use `"recurrenceType": ["MASTER"]` to focus on the primary recurring event definitions
+* **Revision Numbers**: Calendar events require current revision numbers for updates - always get fresh revision before bulk operations
+
+---
+
+## Steps
+
+### 1. Find Business Schedule
+
+Query the business schedule that controls default hours using the fixed external ID.
+
+**Endpoint**: `POST https://www.wixapis.com/calendar/v3/schedules/query`
+
+Use `querySchedules` API ([REST](https://dev.wix.com/docs/api-reference/business-management/calendar/schedules-v3/query-schedules)) with filter:
+- `externalId`: `"4e0579a5-491e-4e70-a872-d097eed6e520"`
+
+Keep the returned `schedule.id` for creating events.
+
+### 2. Query Existing Working Hours (MANDATORY)
+
+**🚨 CRITICAL STEP**: You MUST query for existing `WORKING_HOURS` events because Wix Bookings automatically creates default hours upon installation.
+
+**Endpoint**: `POST https://www.wixapis.com/calendar/v3/events/query`
+
+Use `queryEvents` API ([REST](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/query-events)):
+
+Query pattern:
+```json
+{
+    "recurrenceType": ["MASTER"],
+    "query": {
+        "filter": {
+            "scheduleId": "business-schedule-id",
+            "type": "WORKING_HOURS"
+        }
+    }
+}
+```
+
+**Important**: Always query for MASTER events specifically to see actual recurring schedules.
+
+**Expected Result**: You will typically find 5 existing MASTER events (Monday through Friday, 9 AM - 5 PM) from the default Bookings installation.
+
+### 3. Choose Your Strategy: Update OR Replace
+
+Based on the existing hours found in Step 2, choose one approach:
+
+#### Strategy A: Update Existing Hours (Recommended)
+If you want to modify the times but keep the same days, update the existing events.
+
+#### Strategy B: Replace All Hours
+If you want completely different days/times, delete existing events and create new ones.
+
+### 4A. Update Existing Business Hours (Strategy A)
+
+**Endpoint**: `POST https://www.wixapis.com/calendar/v3/bulk/events/update`
+
+Use `bulkUpdateEvents` API ([REST](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-update-event)) with `fieldmask` pattern:
+
+Update fields:
+- `start`/`end`: New times
+- `revision`: Current revision number (from Step 2 query)
+- `fieldmask`: `"start,end"`
+
+**Example**: Change Monday hours from 9 AM-5 PM to 12 AM-4 PM:
+```json
+{
+  "events": [{
+    "event": {
+      "id": "existing-monday-event-id",
+      "start": {"localDate": "2025-06-16T00:00:00"},
+      "end": {"localDate": "2025-06-16T16:00:00"},
+      "revision": "current-revision-number"
+    }
+  }],
+  "fieldmask": "start,end"
+}
+```
+
+### 4B. Replace All Business Hours (Strategy B)
+
+#### Step 4B.1: Delete Existing Hours
+Cancel existing MASTER events using `bulkCancelEvents` API (`POST https://www.wixapis.com/calendar/v3/bulk/events/cancel`) ([REST](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-cancel-event)):
+
+```json
+{
+  "eventIds": ["event-id-1", "event-id-2", "event-id-3", "event-id-4", "event-id-5"]
+}
+```
+
+#### Step 4B.2: Create New Business Hours
+Create `WORKING_HOURS` events for each day using `bulkCreateEvents` API (`POST https://www.wixapis.com/calendar/v3/bulk/events/create`) ([REST](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-create-event)).
+
+**Each event pattern**:
+- `type`: `"WORKING_HOURS"`
+- `scheduleId`: Business schedule ID from step 1
+- `scheduleOwnerId`: `"4e0579a5-491e-4e70-a872-d097eed6e520"`
+- `externalScheduleId`: `"4e0579a5-491e-4e70-a872-d097eed6e520"`
+- `recurrenceRule`: Weekly recurring with single day
+- `start`/`end`: Business hours times
+
+**Note**: Create separate events for each day of the week (Monday, Tuesday, etc.).
+
+### 5. Verify Final Configuration
+
+Query the business schedule events again to confirm:
+1. No duplicate time slots exist
+2. Each desired day has exactly one MASTER event
+3. Times match your requirements
+
+### IMPORTANT NOTES
+
+* **Future dates required**: Recurring events must start today or in the future
+* **Revision management**: Always use current revision numbers when updating events
+* **MASTER vs INSTANCE**: Based on observed behavior, MASTER events appear to control recurring patterns while INSTANCE events are auto-generated, but always verify current event state
+* **Default Hours Impact**: Remember that these hours will be inherited by any new staff members created after this configuration
+
+### Troubleshooting Common Issues
+
+**"App not installed" Error (428):**
+- Install Wix Bookings app using Apps Installer API
+- Verify installation by querying existing services
+
+**Duplicate time slots in dashboard:**
+- **Root Cause**: You created new events without handling existing default hours
+- **Solution**: Query MASTER events to find duplicates and cancel unwanted ones
+- Each day should have only one MASTER event unless split hours are needed
+
+**Updates not reflecting in dashboard:**
+- Verify you're updating MASTER events, not INSTANCE events
+- Check that revision numbers are current
+- Confirm `fieldmask` includes the fields you're changing
+
+**Cannot create events in the past:**
+- Set `start.localDate` to current date or future
+- Recurring events automatically generate past INSTANCE events
+
+**Business schedule not found:**
+- Query schedules using the fixed external ID: `4e0579a5-491e-4e70-a872-d097eed6e520`
+- Ensure Wix Bookings is installed (schedule is created when Bookings is installed)
+
+**Working hours not affecting staff/services:**
+- Default hours only apply to staff using `usesDefaultWorkingHours: true`
+- Services with custom schedules ignore default business hours
+- Staff with assigned custom schedules override default hours
+
+### Common Gotchas
+
+1. **Skipping the Query Step**: Never assume no hours exist - always query first
+2. **Creating Without Cleaning**: Adding new hours without removing defaults creates duplicates
+3. **Wrong Event Type**: Using INSTANCE instead of MASTER events for queries/updates
+4. **Missing Revision Numbers**: Updates require current revision numbers from the query response
+
+## API Documentation References
+
+* [Query Schedules](https://dev.wix.com/docs/api-reference/business-management/calendar/schedules-v3/query-schedules)
+* [Query Events](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/query-events)
+* [Bulk Create Events](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-create-event)
+* [Bulk Update Events](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-update-event)
+* [Bulk Cancel Events](https://dev.wix.com/docs/api-reference/business-management/calendar/events-v3/bulk-cancel-event)
+* [Apps Installer API](https://dev.wix.com/docs/api-reference/business-management/app-installation/install-app)