@wix/auto_sdk_seatings_seating-reservation 1.0.13 → 1.0.14

package/build/es/index.typings.d.mts

@@ -1,132 +1,139 @@
 import { NonNullablePaths } from '@wix/sdk-types';
 
+/**
+ * A seating reservation represents a booking for one or more places within a seating plan.
+ *
+ * Seating reservations track specific seat assignments or area capacity allocations for events. Each reservation can include multiple places across different sections of a venue, with individual capacity requirements for each place. The system maintains referential integrity through both internal Wix identifiers and external system references, enabling seamless integration with third-party ticketing platforms.
+ */
 interface SeatingReservation {
     /**
-     * The id of the reservation
+     * Reservation ID.
      * @format GUID
      * @readonly
      */
     _id?: string | null;
     /**
-     * The seating plan id
+     * Seating plan ID.
      * @format GUID
      * @readonly
      */
     seatingPlanId?: string | null;
     /**
-     * The external seating plan id
+     * External seating plan ID used for integration with third-party venue systems.
      * @minLength 1
      * @maxLength 100
      * @readonly
      */
     externalSeatingPlanId?: string | null;
     /**
-     * Reserved places
+     * Places reserved in this reservation. Each place can have its own capacity requirements.
      * @minSize 1
      * @maxSize 100
      */
     reservedPlaces?: PlaceReservation[];
     /**
-     * A client defined external id for cross referencing.
-     * Can reference external entities.
-     * Format: "{fqdn}:{entity guid}"
+     * External reference ID for cross-system integration. Format: `{fqdn}:{entity guid}`. For example, `wix.events.v1.ticket:12345678-1234-1234-1234-123456789012`.
      * @minLength 1
      * @maxLength 100
      */
     externalId?: string | null;
     /**
-     * Revision number, which increments by 1 each time the reservation is updated.
+     * Revision number, which increments by 1 each time the reservation is updated. To prevent conflicting changes, the current revision must be passed when updating the reservation. Ignored when creating a reservation.
      * @readonly
      */
     revision?: string | null;
 }
+/** Individual place reservation within a seating arrangement. */
 interface PlaceReservation {
     /**
-     * The place id.
+     * Place ID. For example, `A1-1-5` for section A, row 1, seat 5.
      * @minLength 5
      * @maxLength 11
      */
     _id?: string;
     /**
-     * Number of places in the spot. If not provided - defaults to 1.
-     * Used to reserve for more that one place in areas.
+     * Number of people to be seated at this place. Used for area seating where multiple guests can occupy a single reservable location.
+     *
+     * Default: `1`
      * @min 1
      * @max 50
      */
     capacity?: number | null;
     /**
-     * Optional section label.
+     * Section name within the venue. For example, `Orchestra` or `Balcony`.
      * @readonly
      */
     sectionLabel?: string | null;
     /**
-     * Area label.
+     * Area name within a section. Used for general admission or standing areas.
      * @readonly
      */
     areaLabel?: string | null;
     /**
-     * Table label.
+     * Table identifier for table-based seating arrangements.
      * @readonly
      */
     tableLabel?: string | null;
     /**
-     * Row label.
+     * Row identifier within a section or area.
      * @readonly
      */
     rowLabel?: string | null;
     /**
-     * Seat label in a row or table.
+     * Individual seat identifier within a row or at a table.
      * @readonly
      */
     seatLabel?: string | null;
 }
+/** Triggers when seating plan category summaries are updated. */
 interface SeatingPlanCategoriesSummaryUpdated {
     /**
-     * Seating plan id
+     * Seating plan ID.
      * @format GUID
      */
     seatingPlanId?: string;
-    /** External seating plan id */
+    /** External seating plan ID. */
     externalSeatingPlanId?: string | null;
     /**
-     * Ticket counts by category
+     * Updated category capacity and reservation counts.
      * @maxSize 100
      */
     categories?: CategoryDetails[];
     /**
-     * Summary revision.
+     * Summary revision number for cache invalidation.
      * @readonly
      */
     revision?: string | null;
 }
+/** Category capacity and reservation summary. */
 interface CategoryDetails {
     /**
-     * Seating plan id
+     * Seating Plan ID.
      * @format GUID
      * @readonly
      */
     seatingPlanId?: string | null;
     /**
-     * External seating plan id
+     * External Seating Plan ID used for integration with third-party systems.
      * @minLength 1
      * @maxLength 100
      * @readonly
      */
     externalSeatingPlanId?: string | null;
     /**
-     * External category id
+     * External Category ID used for mapping to venue-specific category names. For example, `VIP` or `ORCHESTRA`.
      * @minLength 1
      * @maxLength 100
      * @readonly
      */
     externalCategoryId?: string | null;
     /**
-     * Total capacity in the category
+     * Total seating capacity available in category.
      * @readonly
      */
     totalCapacity?: number | null;
     /**
-     * Already reserved capacity
+     * Number of seats currently reserved in category.
      * @readonly
      */
     reserved?: number | null;
@@ -246,57 +253,65 @@ interface CustomTag {
      */
     tag?: string;
 }
+/** Request to create a seating reservation. */
 interface CreateSeatingReservationRequest {
-    /** A reservation to create */
+    /** Reservation to create. */
     reservation?: SeatingReservation;
 }
+/** Response after creating a seating reservation. */
 interface CreateSeatingReservationResponse {
-    /** Created reservation */
+    /** Created reservation. */
     reservation?: SeatingReservation;
 }
+/** Details about specific places, used for error reporting. */
 interface Places {
     /**
-     * Places
+     * List of place identifiers. For example, `A1-1-5` or `VIP-12`.
      * @minSize 1
      * @maxSize 100
      */
     places?: string[];
 }
+/** Details about places that are unavailable, including capacity conflicts. */
 interface UnavailablePlaces {
     /**
-     * Places that cannot be reserved
+     * List of place identifiers that are unavailable. For example, `A1-1-5` or `VIP-12`.
      * @minSize 1
      * @maxSize 100
      */
     unavailablePlaces?: string[];
     /**
-     * Reservation error details
+     * Detailed capacity information for each unavailable place.
      * @minSize 1
      * @maxSize 100
      */
     reservationErrorDetails?: ReservationErrorDetails[];
 }
+/** Capacity conflict details for a given place. */
 interface ReservationErrorDetails {
-    /** Place */
+    /** ID of the place with a capacity conflict. */
     _id?: string;
-    /** Available capacity */
+    /** Currently available capacity at this place. */
     available?: number;
-    /** Requested capacity */
+    /** Requested capacity that exceeds the available capacity. */
     requested?: number;
 }
+/** Request to retrieve a specific seating reservation. */
 interface GetReservationRequest {
     /**
-     * The id of the reservation to return
+     * Reservation ID.
      * @format GUID
      */
     _id: string | null;
 }
+/** Response containing the requested seating reservation. */
 interface GetReservationResponse {
-    /** Created reservation */
+    /** Retrieved reservation. */
     reservation?: SeatingReservation;
 }
+/** Request to query seating reservations. */
 interface QuerySeatingReservationRequest {
-    /** A query object */
+    /** Query object with filter criteria and pagination settings. */
     query: QueryV2;
 }
 interface QueryV2 extends QueryV2PagingMethodOneOf {
@@ -364,10 +379,11 @@ interface CursorPaging {
      */
     cursor?: string | null;
 }
+/** Response containing matching seating reservations. */
 interface QuerySeatingReservationResponse {
-    /** Found reservations */
+    /** Found reservations matching the query criteria. */
     reservations?: SeatingReservation[];
-    /** Paging meta data */
+    /** Paging metadata for result navigation. */
     metadata?: PagingMetadataV2;
 }
 interface PagingMetadataV2 {
@@ -394,129 +410,145 @@ interface Cursors {
      */
     prev?: string | null;
 }
+/** Request to delete a seating reservation. */
 interface DeleteSeatingReservationRequest {
     /**
-     * The id of the reservation to delete
+     * Reservation ID.
      * @format GUID
      */
     _id: string | null;
 }
+/** Response after deleting a seating reservation. */
 interface DeleteSeatingReservationResponse {
-    /** The deleted reservation */
+    /** Deleted reservation. */
     reservation?: SeatingReservation;
 }
+/** Request to delete a specific place reservation. */
 interface DeleteSeatingPlaceReservationRequest {
-    /** The id of the place reservation to delete */
+    /** Place reservation ID. */
     _id?: string | null;
     /**
-     * The id of the place reservation's reservation
+     * Seating reservation ID that contains the place reservation.
      * @format GUID
      */
     reservationId?: string | null;
 }
 interface Empty {
 }
+/** Request to cancel specific place reservations. */
 interface CancelSeatingPlaceReservationsRequest {
     /**
-     * The id of the place reservations' reservation
+     * Seating reservation ID containing the places to cancel.
      * @format GUID
      */
     reservationId?: string | null;
     /**
-     * The place reservations to cancel
+     * Place reservations to cancel with their reduced capacity.
      * @minSize 1
      * @maxSize 100
      */
     placeReservations?: PlaceReservationDetails[];
 }
+/** Occupancy details for a specific place in a seating plan. */
 interface PlaceReservationDetails {
+    /** Place ID. */
     placeId?: string;
+    /** Number of occupied seats or capacity units at this place. */
     occupied?: number;
 }
+/** Response after canceling place reservations. */
 interface CancelSeatingPlaceReservationsResponse {
-    /** The reservation with canceled place reservations */
+    /** Reservation with canceled place reservations. */
     reservation?: SeatingReservation;
 }
+/** Request to update a seating reservation. */
 interface UpdateSeatingReservationRequest {
-    /** A reservation to update */
+    /** Reservation to update with modified capacity values. */
     reservation?: SeatingReservation;
 }
+/** Response after updating a seating reservation. */
 interface UpdateSeatingReservationResponse {
-    /** The updated reservation */
+    /** Updated reservation. */
     reservation?: SeatingReservation;
 }
+/** Request to retrieve all reserved places for a seating plan. */
 interface GetReservedPlacesRequest {
     /**
-     * Seating plan id
+     * Seating plan ID.
      * @format GUID
      */
     _id?: string | null;
 }
+/** Response containing all reserved places for a seating plan. */
 interface GetReservedPlacesResponse {
-    /** Reserved places of the plan */
+    /** Reserved places in the seating plan. */
     placeReservations?: PlaceReservation[];
 }
+/** Request to list reserved places with optional filtering. */
 interface ListReservedPlacesRequest {
     /**
-     * Seating plan id
+     * Seating plan ID.
      * @format GUID
      */
     planId?: string | null;
     /**
-     * Optional filter by reservation id
+     * Optional filter by reservation ID.
      * @format GUID
      */
     reservationId?: string | null;
     /**
-     * Optional filter by seat id
+     * Optional filter by specific seat IDs.
      * @maxSize 50
      * @maxLength 20
      */
     seatId?: string[];
-    /** Paging */
+    /** Paging configuration. */
     paging?: Paging;
 }
+/** Response containing filtered reserved places. */
 interface ListReservedPlacesResponse {
-    /** Seating plan id */
+    /** Reserved places matching the filter criteria. */
     reservedPlaces?: ReservedPlace[];
-    /** Paging */
+    /** Paging metadata for result navigation. */
     pagingMetadata?: PagingMetadata;
 }
+/** Internal representation of a place reservation. */
 interface SeatReservation {
     /**
-     * Place reservation id
+     * Place reservation ID.
      * @maxLength 72
      */
     seatReservationId?: string | null;
     /**
-     * Seat id
+     * Place ID.
      * @maxLength 20
      */
     seatId?: string | null;
     /**
-     * Seating plan id
+     * Seating plan ID.
      * @format GUID
      */
     planId?: string | null;
     /**
-     * Seating reservation id
+     * Seating reservation ID.
      * @format GUID
      */
     reservationId?: string | null;
     /**
-     * Spots size
+     * Number of occupied spots at this place.
      * @max 50000
      */
     spots?: number | null;
-    /** Is area */
+    /** Whether this is an area-based reservation (true) or individual seat (false). */
     area?: boolean | null;
 }
+/** Individual reserved place with full context. */
 interface ReservedPlace {
-    /** Place reservation */
+    /** Place reservation details. */
     seatReservation?: SeatReservation;
-    /** Occupied count */
+    /** Parent reservation (active). */
     reservation?: SeatingReservation;
-    /** Occupied count */
+    /** Parent reservation (deleted, for audit trail). */
     reservationFromTrashBin?: SeatingReservation;
 }
 interface PagingMetadata {
@@ -529,32 +561,40 @@ interface PagingMetadata {
     /** Flag that indicates the server failed to calculate the `total` field. */
     tooManyToCount?: boolean | null;
 }
+/** Request to retrieve category-level capacity summary. */
 interface GetSeatingCategorySummaryRequest {
     /**
-     * Seating plan external id
+     * External seating plan ID.
      * @minLength 1
      * @maxLength 100
      */
     externalId?: string;
 }
+/** Response containing capacity summary by category. */
 interface GetSeatingCategorySummaryResponse {
     /**
-     * Ticket counts by category
+     * Capacity and reservation counts by category.
      * @maxSize 50000
      */
     categories?: CategoryDetails[];
 }
+/** Request to retrieve detailed place-level occupancy data. */
 interface GetSeatingReservationSummaryRequest {
     /**
-     * Seating plan external id
+     * External seating plan ID.
      * @minLength 1
      * @maxLength 100
      */
     externalId: string;
 }
+/** Response containing complete seating plan and occupancy data. */
 interface GetSeatingReservationSummaryResponse {
+    /** Complete seating plan structure. */
     plan?: SeatingPlan;
-    /** @maxSize 50000 */
+    /**
+     * Occupancy details for each place in the plan.
+     * @maxSize 50000
+     */
     places?: PlaceReservationDetails[];
 }
 /** A seating plan represents the layout and organization of seats within a venue. It defines the physical arrangement of seating areas, pricing categories, and individual places where attendees can be seated or positioned during an event. */
@@ -1183,20 +1223,30 @@ interface ElementGroupUiProperties {
      */
     rotationAngle?: number | null;
 }
+/** Request to regenerate cached summaries. */
 interface RegenerateSummariesRequest {
     /**
-     * Seating plan id
+     * Seating plan ID.
      * @format GUID
      */
     planId?: string | null;
 }
+/** Response after regenerating summaries. */
 interface RegenerateSummariesResponse {
+    /** Regenerated place-level occupancy summary. */
     seatingReservationsSummary?: SeatingReservationsSummary;
-    /** @maxSize 50000 */
+    /**
+     * Regenerated category-level summaries.
+     * @maxSize 50000
+     */
     categories?: CategoryDetails[];
 }
+/** Aggregated occupancy data for all places in a seating plan. */
 interface SeatingReservationsSummary {
-    /** @maxSize 50000 */
+    /**
+     * Occupancy details for each place.
+     * @maxSize 50000
+     */
     places?: PlaceReservationDetails[];
 }
 interface DomainEvent extends DomainEventBodyOneOf {
@@ -1414,35 +1464,35 @@ interface SeatingReservationDeletedEnvelope {
  */
 declare function onSeatingReservationDeleted(handler: (event: SeatingReservationDeletedEnvelope) => void | Promise<void>): void;
 /**
- * Creates a seating reservation
+ * Creates a seating reservation for one or more places within a seating plan.
  * @public
  * @documentationMaturity preview
  * @permissionId SEATING_PLANS.MANAGE_RESERVATIONS
  * @applicableIdentity APP
- * @returns Created reservation
+ * @returns Created reservation.
  * @fqn com.wixpress.seating.SeatingReservationService.CreateSeatingReservation
  */
 declare function createSeatingReservation(options?: CreateSeatingReservationOptions): Promise<NonNullablePaths<SeatingReservation, `reservedPlaces` | `reservedPlaces.${number}._id`, 4> & {
     __applicationErrorsType?: CreateSeatingReservationApplicationErrors;
 }>;
 interface CreateSeatingReservationOptions {
-    /** A reservation to create */
+    /** Reservation to create. */
     reservation?: SeatingReservation;
 }
 /**
- * Returns seating reservation
- * @param _id - The id of the reservation to return
+ * Retrieves a seating reservation by ID.
+ * @param _id - Reservation ID.
  * @public
  * @documentationMaturity preview
  * @requiredField _id
  * @permissionId SEATING_PLANS.READ_RESERVATIONS
  * @applicableIdentity APP
- * @returns Created reservation
+ * @returns Retrieved reservation.
  * @fqn com.wixpress.seating.SeatingReservationService.GetReservation
  */
 declare function getReservation(_id: string): Promise<NonNullablePaths<SeatingReservation, `reservedPlaces` | `reservedPlaces.${number}._id`, 4>>;
 /**
- * Lists seating reservations by query request
+ * Retrieves seating reservations that match specified criteria.
  * @public
  * @documentationMaturity preview
  * @permissionId SEATING_PLANS.READ_RESERVATIONS
@@ -1476,37 +1526,44 @@ interface ReservationsQueryBuilder {
     find: () => Promise<ReservationsQueryResult>;
 }
 /**
- * Deletes the seating reservation
- * @param _id - The id of the reservation to delete
+ * Deletes a seating reservation and releases all reserved places.
+ * @param _id - Reservation ID.
  * @public
  * @documentationMaturity preview
  * @requiredField _id
  * @permissionId SEATING_PLANS.MANAGE_RESERVATIONS
  * @applicableIdentity APP
+ * @returns Response after deleting a seating reservation.
  * @fqn com.wixpress.seating.SeatingReservationService.DeleteSeatingReservation
  */
 declare function deleteSeatingReservation(_id: string): Promise<NonNullablePaths<DeleteSeatingReservationResponse, `reservation.reservedPlaces` | `reservation.reservedPlaces.${number}._id`, 5>>;
-/** @public
+/**
+ * Retrieves capacity and reservation summary by seating category.
+ * @public
  * @documentationMaturity preview
  * @permissionId SEATING_PLANS.READ_SEATING_PLANS
  * @applicableIdentity APP
+ * @returns Response containing capacity summary by category.
  * @fqn com.wixpress.seating.SeatingReservationService.GetSeatingCategorySummary
  */
 declare function getSeatingCategorySummary(options?: GetSeatingCategorySummaryOptions): Promise<NonNullablePaths<GetSeatingCategorySummaryResponse, `categories`, 2>>;
 interface GetSeatingCategorySummaryOptions {
     /**
-     * Seating plan external id
+     * External seating plan ID.
      * @minLength 1
      * @maxLength 100
      */
     externalId?: string;
 }
-/** @param externalId - Seating plan external id
+/**
+ * Retrieves detailed place-level occupancy data for a seating plan.
+ * @param externalId - External seating plan ID.
  * @public
  * @documentationMaturity preview
  * @requiredField externalId
  * @permissionId SEATING_PLANS.READ_SEATING_PLANS
  * @applicableIdentity APP
+ * @returns Response containing complete seating plan and occupancy data.
  * @fqn com.wixpress.seating.SeatingReservationService.GetSeatingReservationSummary
  */
 declare function getSeatingReservationSummary(externalId: string): Promise<NonNullablePaths<GetSeatingReservationSummaryResponse, `plan.sections` | `plan.sections.${number}._id` | `plan.sections.${number}.default` | `plan.categories` | `plan.categories.${number}._id` | `plan.categories.${number}.title` | `plan.uncategorizedPlaces` | `plan.elementGroups` | `plan.elementGroups.${number}._id` | `places` | `places.${number}.placeId` | `places.${number}.occupied`, 5>>;