@atzentis/booking-sdk 0.1.5 → 0.1.7

package/dist/index.d.cts

@@ -538,6 +538,478 @@ declare class AvailabilityService extends BaseService {
     getPricing(params: PricingParams): Promise<PricingResult>;
 }
 
+/**
+ * All supported booking types across the three verticals.
+ *
+ * - **Stays:** `stay`, `dayuse`
+ * - **Tables:** `table`
+ * - **Services:** `service`
+ * - **Universal:** `parking`, `desk`, `meeting`, `custom`
+ */
+type BookingType = "stay" | "table" | "service" | "parking" | "desk" | "meeting" | "dayuse" | "custom";
+/** All 8 booking types as a readonly tuple for runtime enumeration */
+declare const BOOKING_TYPES: readonly ["stay", "table", "service", "parking", "desk", "meeting", "dayuse", "custom"];
+/**
+ * Booking lifecycle statuses.
+ *
+ * State machine:
+ * ```
+ * pending ──→ confirmed ──→ checked_in ──→ checked_out
+ *    │             │              │
+ *    ├─→ cancelled ├─→ cancelled  ├─→ cancelled
+ *    ├─→ waitlist   └─→ no_show   └─→ no_show
+ *    └─→ no_show
+ * ```
+ */
+type BookingStatus = "pending" | "confirmed" | "checked_in" | "checked_out" | "cancelled" | "no_show" | "waitlist";
+/** All 7 booking statuses as a readonly tuple for runtime enumeration */
+declare const BOOKING_STATUSES: readonly ["pending", "confirmed", "checked_in", "checked_out", "cancelled", "no_show", "waitlist"];
+/** Guest summary embedded in a booking */
+interface BookingGuest {
+    /** Guest identifier */
+    id: string;
+    /** Guest first name */
+    firstName: string;
+    /** Guest last name */
+    lastName: string;
+    /** Guest email address */
+    email: string | null;
+    /** Guest phone number */
+    phone: string | null;
+}
+/** Space summary embedded in a booking */
+interface BookingSpace {
+    /** Space identifier */
+    id: string;
+    /** Display name of the space */
+    name: string;
+    /** Space type (room, table, service, etc.) */
+    type: SpaceType;
+    /** Category the space belongs to */
+    categoryId: string | null;
+    /** Floor the space is on */
+    floor: string | null;
+}
+/** Pricing breakdown for a booking */
+interface BookingPricing {
+    /** Total price in cents */
+    total: number;
+    /** Per-night rate in cents, null for non-Stays verticals */
+    perNight: number | null;
+    /** ISO 4217 currency code (e.g., "EUR", "USD") */
+    currency: string;
+    /** Tax amount in cents */
+    taxes: number;
+    /** Fee amount in cents */
+    fees: number;
+}
+/** A booking in the Atzentis Booking system */
+interface Booking {
+    /** Booking identifier */
+    id: string;
+    /** Human-readable confirmation code */
+    confirmationCode: string;
+    /** Property this booking belongs to */
+    propertyId: string;
+    /** Category for the booked space */
+    categoryId: string | null;
+    /** Guest who made the booking */
+    guestId: string;
+    /** Assigned space, null until assigned */
+    spaceId: string | null;
+    /** Booking type */
+    type: BookingType;
+    /** Current lifecycle status */
+    status: BookingStatus;
+    /** Check-in date in YYYY-MM-DD format */
+    checkIn: string;
+    /** Check-out date in YYYY-MM-DD format */
+    checkOut: string;
+    /** Number of guests */
+    guests: number;
+    /** Free-text notes */
+    notes: string | null;
+    /** Booking source (e.g., "website", "phone", "walk-in") */
+    source: string | null;
+    /** Rate plan identifier */
+    rateId: string | null;
+    /** Open bag for custom data */
+    metadata: Record<string, unknown> | null;
+    /** Guest summary */
+    guest: BookingGuest | null;
+    /** Assigned space summary */
+    space: BookingSpace | null;
+    /** Pricing breakdown */
+    pricing: BookingPricing | null;
+    /** When the booking was confirmed */
+    confirmedAt: string | null;
+    /** When the guest checked in */
+    checkedInAt: string | null;
+    /** When the guest checked out */
+    checkedOutAt: string | null;
+    /** When the booking was cancelled */
+    cancelledAt: string | null;
+    /** Cancellation reason, populated on cancel */
+    cancellationReason: string | null;
+    /** When the booking was marked as no-show */
+    noShowAt: string | null;
+    /** Record creation timestamp */
+    createdAt: string;
+    /** Record last-update timestamp */
+    updatedAt: string;
+}
+/** Input for creating a new booking */
+interface CreateBookingInput {
+    /** Property to create the booking for */
+    propertyId: string;
+    /** Category for the booked space */
+    categoryId: string;
+    /** Guest identifier */
+    guestId: string;
+    /** Check-in date in YYYY-MM-DD format */
+    checkIn: string;
+    /** Check-out date in YYYY-MM-DD format */
+    checkOut: string;
+    /** Booking type */
+    type: BookingType;
+    /** Number of guests */
+    guests?: number;
+    /** Assign a specific space */
+    spaceId?: string;
+    /** Free-text notes */
+    notes?: string;
+    /** Booking source */
+    source?: string;
+    /** Rate plan identifier */
+    rateId?: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+    /** Auto-confirm the booking on creation */
+    autoConfirm?: boolean;
+}
+/** Input for updating an existing booking — all fields optional */
+interface UpdateBookingInput {
+    /** Update the category */
+    categoryId?: string;
+    /** Update check-in date */
+    checkIn?: string;
+    /** Update check-out date */
+    checkOut?: string;
+    /** Update number of guests */
+    guests?: number;
+    /** Update notes */
+    notes?: string;
+    /** Update source */
+    source?: string;
+    /** Update rate plan */
+    rateId?: string;
+    /** Update metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Input for check-in operation */
+interface CheckInInput {
+    /** Actual arrival time in ISO 8601 format */
+    actualArrival?: string;
+    /** Check-in notes */
+    notes?: string;
+    /** Assign or change space at check-in */
+    spaceId?: string;
+}
+/** Input for check-out operation */
+interface CheckOutInput {
+    /** Actual departure time in ISO 8601 format */
+    actualDeparture?: string;
+    /** Check-out notes */
+    notes?: string;
+}
+/** Input for cancel operation */
+interface CancelBookingInput {
+    /** Cancellation reason (required) */
+    reason: string;
+    /** Who cancelled the booking */
+    cancelledBy?: string;
+    /** Whether a refund was requested */
+    refundRequested?: boolean;
+}
+/** Input for no-show operation */
+interface NoShowInput {
+    /** No-show notes */
+    notes?: string;
+    /** Whether to charge a no-show fee */
+    chargeNoShowFee?: boolean;
+}
+/** Input for space assignment */
+interface AssignSpaceInput {
+    /** Space to assign (required) */
+    spaceId: string;
+    /** Assignment notes */
+    notes?: string;
+}
+/** Sort configuration for booking list queries */
+interface BookingSort {
+    /** Field to sort by */
+    field: "checkIn" | "checkOut" | "createdAt" | "updatedAt" | "status";
+    /** Sort direction */
+    direction: "asc" | "desc";
+}
+/** Query parameters for listing bookings */
+interface ListBookingsParams {
+    /** Property to list bookings for (required) */
+    propertyId: string;
+    /** Filter by status (single or array) */
+    status?: BookingStatus | BookingStatus[];
+    /** Filter by type (single or array) */
+    type?: BookingType | BookingType[];
+    /** Filter by guest */
+    guestId?: string;
+    /** Filter by check-in date (from) */
+    checkInFrom?: string;
+    /** Filter by check-in date (to) */
+    checkInTo?: string;
+    /** Filter by check-out date (from) */
+    checkOutFrom?: string;
+    /** Filter by check-out date (to) */
+    checkOutTo?: string;
+    /** Search by confirmation code or guest name */
+    search?: string;
+    /** Sort configuration */
+    sort?: BookingSort;
+    /** Maximum results per page */
+    limit?: number;
+    /** Pagination cursor */
+    cursor?: string;
+}
+/** Paginated list of bookings */
+interface PaginatedBookings {
+    /** Bookings in this page */
+    data: Booking[];
+    /** Total number of matching bookings */
+    totalCount: number;
+    /** Cursor for next page, null if no more results */
+    cursor: string | null;
+    /** Whether more results are available */
+    hasMore: boolean;
+}
+
+/**
+ * Service for managing bookings in the Atzentis Booking API.
+ *
+ * Provides full CRUD operations and lifecycle management across all
+ * 8 booking types (stay, table, service, parking, desk, meeting, dayuse, custom)
+ * and 7 statuses (pending, confirmed, checked_in, checked_out, cancelled, no_show, waitlist).
+ *
+ * **Lifecycle state machine:**
+ * ```
+ * pending ──→ confirmed ──→ checked_in ──→ checked_out
+ *    │             │              │
+ *    ├─→ cancelled ├─→ cancelled  ├─→ cancelled
+ *    ├─→ waitlist   └─→ no_show   └─→ no_show
+ *    └─→ no_show
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const booking = new BookingClient({ apiKey: "atz_io_live_xxxxx" });
+ *
+ * // Create a stay booking
+ * const newBooking = await booking.bookings.create({
+ *   propertyId: "prop_abc123",
+ *   categoryId: "cat_deluxe",
+ *   guestId: "guest_42",
+ *   checkIn: "2025-07-01",
+ *   checkOut: "2025-07-05",
+ *   type: "stay",
+ * });
+ *
+ * // Lifecycle: confirm → check-in → check-out
+ * await booking.bookings.confirm(newBooking.id);
+ * await booking.bookings.checkIn(newBooking.id);
+ * await booking.bookings.checkOut(newBooking.id);
+ * ```
+ */
+declare class BookingsService extends BaseService {
+    protected readonly basePath = "/booking/v1/bookings";
+    /**
+     * Create a new booking.
+     *
+     * @example
+     * ```typescript
+     * const booking = await client.bookings.create({
+     *   propertyId: "prop_abc123",
+     *   categoryId: "cat_deluxe",
+     *   guestId: "guest_42",
+     *   checkIn: "2025-07-01",
+     *   checkOut: "2025-07-05",
+     *   type: "stay",
+     *   guests: 2,
+     *   autoConfirm: true,
+     * });
+     * ```
+     */
+    create(input: CreateBookingInput): Promise<Booking>;
+    /**
+     * Get a single booking by ID.
+     *
+     * @example
+     * ```typescript
+     * const booking = await client.bookings.get("bk_abc123");
+     * ```
+     */
+    get(bookingId: string): Promise<Booking>;
+    /**
+     * List bookings for a property with optional filters and cursor-based pagination.
+     *
+     * Supports filtering by status, type, guest, date ranges, search term,
+     * and custom sort order. Array values for `status` and `type` are serialized
+     * as comma-separated strings.
+     *
+     * @example
+     * ```typescript
+     * // List all confirmed stay bookings
+     * const page = await client.bookings.list({
+     *   propertyId: "prop_abc123",
+     *   status: "confirmed",
+     *   type: "stay",
+     * });
+     *
+     * // Multi-status filter with date range
+     * const page2 = await client.bookings.list({
+     *   propertyId: "prop_abc123",
+     *   status: ["confirmed", "checked_in"],
+     *   checkInFrom: "2025-07-01",
+     *   checkInTo: "2025-07-31",
+     *   sort: { field: "checkIn", direction: "asc" },
+     *   limit: 20,
+     * });
+     * ```
+     */
+    list(params: ListBookingsParams): Promise<PaginatedBookings>;
+    /**
+     * Update an existing booking.
+     *
+     * @example
+     * ```typescript
+     * const updated = await client.bookings.update("bk_abc123", {
+     *   guests: 3,
+     *   notes: "Extra bed requested",
+     * });
+     * ```
+     */
+    update(bookingId: string, input: UpdateBookingInput): Promise<Booking>;
+    /**
+     * Delete a booking.
+     *
+     * @example
+     * ```typescript
+     * await client.bookings.delete("bk_abc123");
+     * ```
+     */
+    delete(bookingId: string): Promise<void>;
+    /**
+     * Confirm a pending booking.
+     *
+     * Transitions: `pending` → `confirmed`
+     *
+     * @throws {ConflictError} 409 if the booking is not in `pending` status
+     *
+     * @example
+     * ```typescript
+     * const confirmed = await client.bookings.confirm("bk_abc123");
+     * // confirmed.status === "confirmed"
+     * // confirmed.confirmedAt is populated
+     * ```
+     */
+    confirm(bookingId: string): Promise<Booking>;
+    /**
+     * Check in a guest.
+     *
+     * Transitions: `confirmed` → `checked_in`
+     *
+     * @throws {ConflictError} 409 if the booking is not in `confirmed` status
+     *
+     * @example
+     * ```typescript
+     * const checkedIn = await client.bookings.checkIn("bk_abc123", {
+     *   actualArrival: "2025-07-01T14:30:00Z",
+     * });
+     * // checkedIn.status === "checked_in"
+     * // checkedIn.checkedInAt is populated
+     * ```
+     */
+    checkIn(bookingId: string, input?: CheckInInput): Promise<Booking>;
+    /**
+     * Check out a guest.
+     *
+     * Transitions: `checked_in` → `checked_out`
+     *
+     * @throws {ConflictError} 409 if the booking is not in `checked_in` status
+     *
+     * @example
+     * ```typescript
+     * const checkedOut = await client.bookings.checkOut("bk_abc123", {
+     *   actualDeparture: "2025-07-05T11:00:00Z",
+     * });
+     * // checkedOut.status === "checked_out"
+     * // checkedOut.checkedOutAt is populated
+     * ```
+     */
+    checkOut(bookingId: string, input?: CheckOutInput): Promise<Booking>;
+    /**
+     * Cancel a booking.
+     *
+     * Transitions: `pending` | `confirmed` | `checked_in` → `cancelled`
+     *
+     * @throws {ConflictError} 409 if the booking is already cancelled, checked out, or no-show
+     *
+     * @example
+     * ```typescript
+     * const cancelled = await client.bookings.cancel("bk_abc123", {
+     *   reason: "Guest requested cancellation",
+     *   refundRequested: true,
+     * });
+     * // cancelled.status === "cancelled"
+     * // cancelled.cancelledAt is populated
+     * // cancelled.cancellationReason === "Guest requested cancellation"
+     * ```
+     */
+    cancel(bookingId: string, input: CancelBookingInput): Promise<Booking>;
+    /**
+     * Mark a booking as no-show.
+     *
+     * Transitions: `pending` | `confirmed` | `checked_in` → `no_show`
+     *
+     * @throws {ConflictError} 409 if the booking is already checked out, cancelled, or no-show
+     *
+     * @example
+     * ```typescript
+     * const noShow = await client.bookings.noShow("bk_abc123", {
+     *   chargeNoShowFee: true,
+     * });
+     * // noShow.status === "no_show"
+     * // noShow.noShowAt is populated
+     * ```
+     */
+    noShow(bookingId: string, input?: NoShowInput): Promise<Booking>;
+    /**
+     * Assign or reassign a space to a booking.
+     *
+     * Can be called on any active booking (pending, confirmed, checked_in).
+     *
+     * @throws {ConflictError} 409 if the booking is in a terminal status
+     *
+     * @example
+     * ```typescript
+     * const assigned = await client.bookings.assignSpace("bk_abc123", {
+     *   spaceId: "spc_room101",
+     *   notes: "Upgraded to deluxe",
+     * });
+     * // assigned.spaceId === "spc_room101"
+     * // assigned.space is populated
+     * ```
+     */
+    assignSpace(bookingId: string, input: AssignSpaceInput): Promise<Booking>;
+}
+
 /** All supported property types in the v4.0 API */
 type PropertyType = "hotel" | "resort" | "villa" | "apartment" | "hostel" | "bnb" | "restaurant" | "cafe" | "bar" | "beach" | "spa" | "salon" | "custom";
 /** Property lifecycle status */
@@ -725,6 +1197,581 @@ declare class CategoriesService extends BaseService {
     delete(categoryId: string): Promise<void>;
 }
 
+/** Guest address */
+interface GuestAddress {
+    /** Street address */
+    street: string | null;
+    /** City */
+    city: string | null;
+    /** State or province */
+    state: string | null;
+    /** Postal/ZIP code */
+    postalCode: string | null;
+    /** ISO 3166-1 alpha-2 country code */
+    country: string | null;
+}
+/** A guest profile in the Atzentis system */
+interface Guest {
+    /** Guest identifier */
+    id: string;
+    /** First name */
+    firstName: string;
+    /** Last name */
+    lastName: string;
+    /** Email address */
+    email: string | null;
+    /** Phone number */
+    phone: string | null;
+    /** Date of birth in YYYY-MM-DD format */
+    dateOfBirth: string | null;
+    /** ISO 3166-1 alpha-2 nationality code */
+    nationality: string | null;
+    /** ISO 639-1 language code */
+    language: string | null;
+    /** Guest address */
+    address: GuestAddress | null;
+    /** Company name */
+    company: string | null;
+    /** Passport number */
+    passportNumber: string | null;
+    /** National ID number */
+    idNumber: string | null;
+    /** Free-text notes */
+    notes: string | null;
+    /** Tags for categorization */
+    tags: string[];
+    /** How the guest was acquired */
+    source: string | null;
+    /** Open bag for custom data */
+    metadata: Record<string, unknown> | null;
+    /** Record creation timestamp */
+    createdAt: string;
+    /** Record last-update timestamp */
+    updatedAt: string;
+    /** Soft-delete timestamp, null if active */
+    deletedAt: string | null;
+}
+/** Input for creating a new guest */
+interface CreateGuestInput {
+    /** First name (required) */
+    firstName: string;
+    /** Last name (required) */
+    lastName: string;
+    /** Email address */
+    email?: string;
+    /** Phone number */
+    phone?: string;
+    /** Date of birth in YYYY-MM-DD format */
+    dateOfBirth?: string;
+    /** ISO 3166-1 alpha-2 nationality code */
+    nationality?: string;
+    /** ISO 639-1 language code */
+    language?: string;
+    /** Guest address */
+    address?: GuestAddress;
+    /** Company name */
+    company?: string;
+    /** Passport number */
+    passportNumber?: string;
+    /** National ID number */
+    idNumber?: string;
+    /** Free-text notes */
+    notes?: string;
+    /** Tags for categorization */
+    tags?: string[];
+    /** How the guest was acquired */
+    source?: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Input for updating an existing guest — all fields optional */
+interface UpdateGuestInput {
+    /** Update first name */
+    firstName?: string;
+    /** Update last name */
+    lastName?: string;
+    /** Update email */
+    email?: string | null;
+    /** Update phone */
+    phone?: string | null;
+    /** Update date of birth */
+    dateOfBirth?: string | null;
+    /** Update nationality */
+    nationality?: string | null;
+    /** Update language */
+    language?: string | null;
+    /** Update address */
+    address?: GuestAddress | null;
+    /** Update company */
+    company?: string | null;
+    /** Update passport number */
+    passportNumber?: string | null;
+    /** Update ID number */
+    idNumber?: string | null;
+    /** Update notes */
+    notes?: string | null;
+    /** Update tags */
+    tags?: string[];
+    /** Update source */
+    source?: string | null;
+    /** Update metadata */
+    metadata?: Record<string, unknown> | null;
+}
+/** Sort configuration for guest list queries */
+interface GuestSort {
+    /** Field to sort by */
+    field: "firstName" | "lastName" | "email" | "createdAt" | "updatedAt";
+    /** Sort direction */
+    direction: "asc" | "desc";
+}
+/** Query parameters for listing guests */
+interface ListGuestsParams {
+    /** Filter by tags (guests matching any of these tags) */
+    tags?: string[];
+    /** Filter by source */
+    source?: string;
+    /** Filter by creation date (from) */
+    createdFrom?: string;
+    /** Filter by creation date (to) */
+    createdTo?: string;
+    /** Sort configuration */
+    sort?: GuestSort;
+    /** Maximum results per page */
+    limit?: number;
+    /** Pagination cursor */
+    cursor?: string;
+}
+/** Paginated list of guests */
+interface PaginatedGuests {
+    /** Guests in this page */
+    data: Guest[];
+    /** Total number of matching guests */
+    totalCount: number;
+    /** Cursor for next page, null if no more results */
+    cursor: string | null;
+    /** Whether more results are available */
+    hasMore: boolean;
+}
+/** Parameters for searching guests */
+interface SearchGuestsParams {
+    /** Maximum results to return */
+    limit?: number;
+    /** Fields to search in (e.g., ["firstName", "lastName", "email"]) */
+    fields?: string[];
+}
+/** A guest match from a search, includes relevance score */
+interface GuestMatch extends Guest {
+    /** Relevance score between 0 and 1 (1 = exact match) */
+    score: number;
+}
+/** Result of a guest search */
+interface GuestSearchResult {
+    /** Matching guests sorted by score (highest first) */
+    data: GuestMatch[];
+    /** Total number of matches */
+    totalCount: number;
+}
+/** A potential duplicate candidate */
+interface DuplicateCandidate {
+    /** The potential duplicate guest */
+    guest: Guest;
+    /** Confidence score between 0 and 1 (1 = certain duplicate) */
+    confidence: number;
+    /** Fields that matched (e.g., ["email", "phone"]) */
+    matchedFields: string[];
+}
+/** Result of duplicate detection */
+interface GuestDuplicateResult {
+    /** Potential duplicates sorted by confidence (highest first) */
+    data: DuplicateCandidate[];
+}
+/** Input for merging duplicate guests into a primary profile */
+interface MergeGuestsInput {
+    /** IDs of duplicate guests to merge into the primary (required, non-empty) */
+    duplicateIds: string[];
+}
+/**
+ * Guest preferences with typed common fields and a custom catch-all.
+ *
+ * Common fields cover typical hospitality preferences.
+ * Use `custom` for vertical-specific or property-specific data.
+ */
+interface GuestPreferences {
+    /** Preferred room type (e.g., "single", "double", "suite") */
+    roomType: string | null;
+    /** Preferred floor (e.g., "high", "low", "ground") */
+    floorPreference: string | null;
+    /** Preferred bed type (e.g., "king", "twin", "queen") */
+    bedType: string | null;
+    /** Dietary requirements (e.g., "vegetarian", "vegan", "gluten-free") */
+    dietary: string[];
+    /** Known allergies */
+    allergies: string[];
+    /** Preferred communication channel (e.g., "email", "sms", "whatsapp") */
+    communicationChannel: string | null;
+    /** Preferred language for communication */
+    language: string | null;
+    /** Smoking preference */
+    smoking: boolean | null;
+    /** Accessibility requirements */
+    accessibility: string[];
+    /** Free-text special requests */
+    specialRequests: string | null;
+    /** Catch-all for vertical-specific preferences */
+    custom: Record<string, unknown>;
+}
+/** Input for updating guest preferences — all fields optional, partial merge */
+interface UpdateGuestPreferences {
+    /** Update room type preference */
+    roomType?: string | null;
+    /** Update floor preference */
+    floorPreference?: string | null;
+    /** Update bed type preference */
+    bedType?: string | null;
+    /** Update dietary requirements */
+    dietary?: string[];
+    /** Update allergies */
+    allergies?: string[];
+    /** Update communication channel */
+    communicationChannel?: string | null;
+    /** Update language preference */
+    language?: string | null;
+    /** Update smoking preference */
+    smoking?: boolean | null;
+    /** Update accessibility requirements */
+    accessibility?: string[];
+    /** Update special requests */
+    specialRequests?: string | null;
+    /** Update custom preferences (merged, not replaced) */
+    custom?: Record<string, unknown>;
+}
+/** Parameters for guest history queries */
+interface GuestHistoryParams {
+    /** Maximum results per page */
+    limit?: number;
+    /** Pagination cursor */
+    cursor?: string;
+    /** Filter from date in YYYY-MM-DD format */
+    from?: string;
+    /** Filter to date in YYYY-MM-DD format */
+    to?: string;
+}
+/** Lightweight booking summary for guest history */
+interface GuestBookingSummary {
+    /** Booking identifier */
+    id: string;
+    /** Property identifier */
+    propertyId: string;
+    /** Property display name */
+    propertyName: string;
+    /** Booking type */
+    type: BookingType;
+    /** Booking status */
+    status: BookingStatus;
+    /** Check-in date */
+    checkIn: string;
+    /** Check-out date */
+    checkOut: string;
+    /** Total amount in cents */
+    totalAmount: number;
+    /** ISO 4217 currency code */
+    currency: string;
+}
+/** Lightweight folio summary for guest history */
+interface GuestFolioSummary {
+    /** Folio identifier */
+    id: string;
+    /** Associated booking ID */
+    bookingId: string;
+    /** Property identifier */
+    propertyId: string;
+    /** Folio status */
+    status: string;
+    /** Total charges in cents */
+    totalCharges: number;
+    /** Total payments in cents */
+    totalPayments: number;
+    /** Outstanding balance in cents */
+    balance: number;
+    /** ISO 4217 currency code */
+    currency: string;
+    /** When the folio was closed, null if open */
+    closedAt: string | null;
+}
+/** Lightweight order summary for guest history */
+interface GuestOrderSummary {
+    /** Order identifier */
+    id: string;
+    /** Property identifier */
+    propertyId: string;
+    /** Order type */
+    type: string;
+    /** Order status */
+    status: string;
+    /** Total amount in cents */
+    totalAmount: number;
+    /** ISO 4217 currency code */
+    currency: string;
+    /** Number of items in the order */
+    items: number;
+    /** Order creation timestamp */
+    createdAt: string;
+}
+/** Paginated list of guest booking summaries */
+interface PaginatedGuestBookings {
+    /** Booking summaries in this page */
+    data: GuestBookingSummary[];
+    /** Total number of bookings */
+    totalCount: number;
+    /** Cursor for next page, null if no more results */
+    cursor: string | null;
+    /** Whether more results are available */
+    hasMore: boolean;
+}
+/** Paginated list of guest folio summaries */
+interface PaginatedGuestFolios {
+    /** Folio summaries in this page */
+    data: GuestFolioSummary[];
+    /** Total number of folios */
+    totalCount: number;
+    /** Cursor for next page, null if no more results */
+    cursor: string | null;
+    /** Whether more results are available */
+    hasMore: boolean;
+}
+/** Paginated list of guest order summaries */
+interface PaginatedGuestOrders {
+    /** Order summaries in this page */
+    data: GuestOrderSummary[];
+    /** Total number of orders */
+    totalCount: number;
+    /** Cursor for next page, null if no more results */
+    cursor: string | null;
+    /** Whether more results are available */
+    hasMore: boolean;
+}
+
+/**
+ * Service for managing guest profiles in the Atzentis Booking API.
+ *
+ * Provides full CRUD, search with scoring, duplicate detection,
+ * profile merging, preferences management, and cross-domain history
+ * (bookings, folios, orders).
+ *
+ * @example
+ * ```typescript
+ * const booking = new BookingClient({ apiKey: "atz_io_live_xxxxx" });
+ *
+ * // Create a guest
+ * const guest = await booking.guests.create({
+ *   firstName: "John",
+ *   lastName: "Doe",
+ *   email: "john@example.com",
+ * });
+ *
+ * // Search for guests
+ * const results = await booking.guests.search("Doe");
+ *
+ * // Get booking history
+ * const history = await booking.guests.getBookings(guest.id);
+ * ```
+ */
+declare class GuestsService extends BaseService {
+    protected readonly basePath = "/guest/v1/profiles";
+    /**
+     * Create a new guest profile.
+     *
+     * @example
+     * ```typescript
+     * const guest = await client.guests.create({
+     *   firstName: "Maria",
+     *   lastName: "Papadopoulou",
+     *   email: "maria@example.com",
+     *   phone: "+30 210 1234567",
+     *   nationality: "GR",
+     * });
+     * ```
+     */
+    create(input: CreateGuestInput): Promise<Guest>;
+    /**
+     * Get a single guest by ID.
+     *
+     * @example
+     * ```typescript
+     * const guest = await client.guests.get("guest_42");
+     * ```
+     */
+    get(guestId: string): Promise<Guest>;
+    /**
+     * List guests with optional filters and cursor-based pagination.
+     *
+     * @example
+     * ```typescript
+     * const page = await client.guests.list({
+     *   tags: ["vip", "returning"],
+     *   sort: { field: "lastName", direction: "asc" },
+     *   limit: 20,
+     * });
+     * ```
+     */
+    list(params?: ListGuestsParams): Promise<PaginatedGuests>;
+    /**
+     * Update an existing guest profile.
+     *
+     * @example
+     * ```typescript
+     * const updated = await client.guests.update("guest_42", {
+     *   email: "maria.new@example.com",
+     *   tags: ["vip"],
+     * });
+     * ```
+     */
+    update(guestId: string, input: UpdateGuestInput): Promise<Guest>;
+    /**
+     * Delete a guest profile (soft-delete).
+     *
+     * @example
+     * ```typescript
+     * await client.guests.delete("guest_42");
+     * ```
+     */
+    delete(guestId: string): Promise<void>;
+    /**
+     * Search guests by name, email, phone, or passport number.
+     *
+     * Returns results sorted by relevance score (highest first).
+     *
+     * @param query - Search query string
+     * @param params - Optional search parameters (limit, fields)
+     *
+     * @example
+     * ```typescript
+     * // Search by name
+     * const results = await client.guests.search("Papadopoulos");
+     *
+     * // Search by email with field filter
+     * const results2 = await client.guests.search("maria@", {
+     *   fields: ["email"],
+     *   limit: 5,
+     * });
+     * ```
+     */
+    search(query: string, params?: SearchGuestsParams): Promise<GuestSearchResult>;
+    /**
+     * Find potential duplicate profiles for a guest.
+     *
+     * Returns candidates sorted by confidence score (highest first).
+     *
+     * @throws {NotFoundError} 404 if the guest is not found
+     *
+     * @example
+     * ```typescript
+     * const duplicates = await client.guests.findDuplicates("guest_42");
+     * for (const dup of duplicates.data) {
+     *   console.log(`${dup.guest.firstName} — ${dup.confidence} (${dup.matchedFields})`);
+     * }
+     * ```
+     */
+    findDuplicates(guestId: string): Promise<GuestDuplicateResult>;
+    /**
+     * Merge duplicate guest profiles into a primary profile.
+     *
+     * **Warning: This operation is irreversible.** All history from duplicate
+     * profiles is transferred to the primary. Duplicate profiles are soft-deleted.
+     *
+     * @throws {NotFoundError} 404 if primary or any duplicate is not found
+     * @throws {ConflictError} 409 if attempting to merge a guest into itself
+     * @throws {ValidationError} 400 if duplicateIds is empty
+     *
+     * @example
+     * ```typescript
+     * const merged = await client.guests.merge("guest_primary", {
+     *   duplicateIds: ["guest_dup1", "guest_dup2"],
+     * });
+     * ```
+     */
+    merge(primaryId: string, input: MergeGuestsInput): Promise<Guest>;
+    /**
+     * Get guest preferences.
+     *
+     * Returns default/empty preferences if none have been set (does not throw 404).
+     *
+     * @throws {NotFoundError} 404 if the guest is not found
+     *
+     * @example
+     * ```typescript
+     * const prefs = await client.guests.getPreferences("guest_42");
+     * console.log(prefs.dietary, prefs.roomType);
+     * ```
+     */
+    getPreferences(guestId: string): Promise<GuestPreferences>;
+    /**
+     * Update guest preferences (partial merge).
+     *
+     * Only provided fields are updated; unspecified fields retain their values.
+     *
+     * @throws {NotFoundError} 404 if the guest is not found
+     *
+     * @example
+     * ```typescript
+     * const updated = await client.guests.updatePreferences("guest_42", {
+     *   dietary: ["vegetarian"],
+     *   roomType: "suite",
+     *   custom: { pillow: "firm" },
+     * });
+     * ```
+     */
+    updatePreferences(guestId: string, input: UpdateGuestPreferences): Promise<GuestPreferences>;
+    /**
+     * Get a guest's booking history.
+     *
+     * Returns lightweight booking summaries with pagination support.
+     *
+     * @throws {NotFoundError} 404 if the guest is not found
+     *
+     * @example
+     * ```typescript
+     * const bookings = await client.guests.getBookings("guest_42", {
+     *   from: "2025-01-01",
+     *   to: "2025-12-31",
+     *   limit: 10,
+     * });
+     * ```
+     */
+    getBookings(guestId: string, params?: GuestHistoryParams): Promise<PaginatedGuestBookings>;
+    /**
+     * Get a guest's folio history.
+     *
+     * Returns lightweight folio summaries with pagination support.
+     *
+     * @throws {NotFoundError} 404 if the guest is not found
+     *
+     * @example
+     * ```typescript
+     * const folios = await client.guests.getFolios("guest_42");
+     * ```
+     */
+    getFolios(guestId: string, params?: GuestHistoryParams): Promise<PaginatedGuestFolios>;
+    /**
+     * Get a guest's order history.
+     *
+     * Returns lightweight order summaries with pagination support.
+     *
+     * @throws {NotFoundError} 404 if the guest is not found
+     *
+     * @example
+     * ```typescript
+     * const orders = await client.guests.getOrders("guest_42", {
+     *   limit: 5,
+     *   cursor: "next_page",
+     * });
+     * ```
+     */
+    getOrders(guestId: string, params?: GuestHistoryParams): Promise<PaginatedGuestOrders>;
+    /** Build query params from GuestHistoryParams, omitting undefined values */
+    private _buildHistoryQuery;
+}
+
 /**
  * Service for managing properties in the Atzentis Booking API.
  *
@@ -945,12 +1992,18 @@ declare class SpacesService extends BaseService {
 declare class BookingClient {
     readonly httpClient: HttpClient;
     private _availability?;
+    private _bookings?;
+    private _guests?;
     private _properties?;
     private _categories?;
     private _spaces?;
     constructor(config: BookingClientConfig);
     /** Availability service — lazy-initialized on first access */
     get availability(): AvailabilityService;
+    /** Bookings service — lazy-initialized on first access */
+    get bookings(): BookingsService;
+    /** Guests service — lazy-initialized on first access */
+    get guests(): GuestsService;
     /** Properties service — lazy-initialized on first access */
     get properties(): PropertiesService;
     /** Categories service — lazy-initialized on first access */
@@ -1039,4 +2092,4 @@ declare function firstPage<T>(fetcher: PageFetcher<T>, options?: PaginationOptio
 
 declare const VERSION = "0.1.0";
 
-export { AuthenticationError, type AvailabilityCheckParams, type AvailabilityPricing, type AvailabilityRestrictions, type AvailabilityResult, type AvailabilitySearchParams, type AvailabilitySearchResult, type AvailabilitySearchResultEntry, AvailabilityService, type AvailableSpace, BookingClient, type BookingClientConfig, BookingError, type BookingErrorOptions, type BulkUpdateSpaceInput, type CalendarDay, type CalendarParams, CategoriesService, ConflictError, type Coordinates, type CreateCategoryInput, type CreatePropertyInput, type CreateSpaceInput, DEFAULT_MODULES, ForbiddenError, HttpClient, type HttpClientOptions, type HttpMethod, type HttpResponse, type LinkPosTableInput, type ListCategoriesParams, type ListPropertiesParams, type ListSpacesParams, type Logger, NotFoundError, PROPERTY_MODULES, type PageFetcher, type Paginated, type PaginationOptions, PaymentError, type PriceRange, type PricingParams, type PricingResult, PropertiesService, type Property, type PropertyAddress, type PropertyModules, type PropertyStatus, type PropertyType, RateLimitError, type RequestOptions, type ResolvedBookingClientConfig, type RetryConfig, type RetryOptions, SPACE_STATUSES, SPACE_TYPES, ServerError, type ServiceSlotParams, type ServiceTimeSlot, type Space, type SpaceCategory, type SpaceStatus, type SpaceType, SpacesService, type TableSlotParams, type TimeSlot, TimeoutError, type UpdateCategoryInput, type UpdatePropertyInput, type UpdateSpaceInput, VERSION, ValidationError, bookingClientConfigSchema, createErrorFromResponse, firstPage, paginate };
+export { type AssignSpaceInput, AuthenticationError, type AvailabilityCheckParams, type AvailabilityPricing, type AvailabilityRestrictions, type AvailabilityResult, type AvailabilitySearchParams, type AvailabilitySearchResult, type AvailabilitySearchResultEntry, AvailabilityService, type AvailableSpace, BOOKING_STATUSES, BOOKING_TYPES, type Booking, BookingClient, type BookingClientConfig, BookingError, type BookingErrorOptions, type BookingGuest, type BookingPricing, type BookingSort, type BookingSpace, type BookingStatus, type BookingType, BookingsService, type BulkUpdateSpaceInput, type CalendarDay, type CalendarParams, type CancelBookingInput, CategoriesService, type CheckInInput, type CheckOutInput, ConflictError, type Coordinates, type CreateBookingInput, type CreateCategoryInput, type CreateGuestInput, type CreatePropertyInput, type CreateSpaceInput, DEFAULT_MODULES, type DuplicateCandidate, ForbiddenError, type Guest, type GuestAddress, type GuestBookingSummary, type GuestDuplicateResult, type GuestFolioSummary, type GuestHistoryParams, type GuestMatch, type GuestOrderSummary, type GuestPreferences, type GuestSearchResult, type GuestSort, GuestsService, HttpClient, type HttpClientOptions, type HttpMethod, type HttpResponse, type LinkPosTableInput, type ListBookingsParams, type ListCategoriesParams, type ListGuestsParams, type ListPropertiesParams, type ListSpacesParams, type Logger, type MergeGuestsInput, type NoShowInput, NotFoundError, PROPERTY_MODULES, type PageFetcher, type Paginated, type PaginatedBookings, type PaginatedGuestBookings, type PaginatedGuestFolios, type PaginatedGuestOrders, type PaginatedGuests, type PaginationOptions, PaymentError, type PriceRange, type PricingParams, type PricingResult, PropertiesService, type Property, type PropertyAddress, type PropertyModules, type PropertyStatus, type PropertyType, RateLimitError, type RequestOptions, type ResolvedBookingClientConfig, type RetryConfig, type RetryOptions, SPACE_STATUSES, SPACE_TYPES, type SearchGuestsParams, ServerError, type ServiceSlotParams, type ServiceTimeSlot, type Space, type SpaceCategory, type SpaceStatus, type SpaceType, SpacesService, type TableSlotParams, type TimeSlot, TimeoutError, type UpdateBookingInput, type UpdateCategoryInput, type UpdateGuestInput, type UpdateGuestPreferences, type UpdatePropertyInput, type UpdateSpaceInput, VERSION, ValidationError, bookingClientConfigSchema, createErrorFromResponse, firstPage, paginate };