@atzentis/booking-sdk 0.1.5 → 0.1.7

package/dist/index.js

@@ -736,6 +736,244 @@ function minutesToTime(totalMinutes) {
   return `${String(hours).padStart(2, "0")}:${String(minutes).padStart(2, "0")}`;
 }
 
+// src/services/bookings.ts
+var BookingsService = class extends BaseService {
+  constructor() {
+    super(...arguments);
+    this.basePath = "/booking/v1/bookings";
+  }
+  // ---------------------------------------------------------------------------
+  // CRUD
+  // ---------------------------------------------------------------------------
+  /**
+   * 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) {
+    return this._post(this.basePath, input);
+  }
+  /**
+   * Get a single booking by ID.
+   *
+   * @example
+   * ```typescript
+   * const booking = await client.bookings.get("bk_abc123");
+   * ```
+   */
+  get(bookingId) {
+    return this._get(this._buildPath(bookingId));
+  }
+  /**
+   * 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) {
+    const query = {
+      propertyId: params.propertyId
+    };
+    if (params.status !== void 0) {
+      query.status = Array.isArray(params.status) ? params.status.join(",") : params.status;
+    }
+    if (params.type !== void 0) {
+      query.type = Array.isArray(params.type) ? params.type.join(",") : params.type;
+    }
+    if (params.guestId !== void 0) query.guestId = params.guestId;
+    if (params.checkInFrom !== void 0) query.checkInFrom = params.checkInFrom;
+    if (params.checkInTo !== void 0) query.checkInTo = params.checkInTo;
+    if (params.checkOutFrom !== void 0) query.checkOutFrom = params.checkOutFrom;
+    if (params.checkOutTo !== void 0) query.checkOutTo = params.checkOutTo;
+    if (params.search !== void 0) query.search = params.search;
+    if (params.sort !== void 0) {
+      query.sort = `${params.sort.field}:${params.sort.direction}`;
+    }
+    if (params.limit !== void 0) query.limit = params.limit;
+    if (params.cursor !== void 0) query.cursor = params.cursor;
+    return this._get(this.basePath, query);
+  }
+  /**
+   * Update an existing booking.
+   *
+   * @example
+   * ```typescript
+   * const updated = await client.bookings.update("bk_abc123", {
+   *   guests: 3,
+   *   notes: "Extra bed requested",
+   * });
+   * ```
+   */
+  update(bookingId, input) {
+    return this._patch(this._buildPath(bookingId), input);
+  }
+  /**
+   * Delete a booking.
+   *
+   * @example
+   * ```typescript
+   * await client.bookings.delete("bk_abc123");
+   * ```
+   */
+  delete(bookingId) {
+    return this._delete(this._buildPath(bookingId));
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle — happy path
+  // ---------------------------------------------------------------------------
+  /**
+   * 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) {
+    return this._post(this._buildPath(bookingId, "confirm"), {});
+  }
+  /**
+   * 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, input) {
+    return this._post(this._buildPath(bookingId, "check-in"), input ?? {});
+  }
+  /**
+   * 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, input) {
+    return this._post(this._buildPath(bookingId, "check-out"), input ?? {});
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle — alternate endings
+  // ---------------------------------------------------------------------------
+  /**
+   * 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, input) {
+    return this._post(this._buildPath(bookingId, "cancel"), input);
+  }
+  /**
+   * 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, input) {
+    return this._post(this._buildPath(bookingId, "no-show"), input ?? {});
+  }
+  /**
+   * 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, input) {
+    return this._post(this._buildPath(bookingId, "assign-space"), input);
+  }
+};
+
 // src/services/categories.ts
 var CategoriesService = class extends BaseService {
   constructor() {
@@ -801,6 +1039,285 @@ var CategoriesService = class extends BaseService {
   }
 };
 
+// src/services/guests.ts
+var GuestsService = class extends BaseService {
+  constructor() {
+    super(...arguments);
+    this.basePath = "/guest/v1/profiles";
+  }
+  // ---------------------------------------------------------------------------
+  // CRUD
+  // ---------------------------------------------------------------------------
+  /**
+   * 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) {
+    return this._post(this.basePath, input);
+  }
+  /**
+   * Get a single guest by ID.
+   *
+   * @example
+   * ```typescript
+   * const guest = await client.guests.get("guest_42");
+   * ```
+   */
+  get(guestId) {
+    return this._get(this._buildPath(guestId));
+  }
+  /**
+   * 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) {
+    if (!params) {
+      return this._get(this.basePath);
+    }
+    const query = {};
+    if (params.tags !== void 0 && params.tags.length > 0) {
+      query.tags = params.tags.join(",");
+    }
+    if (params.source !== void 0) query.source = params.source;
+    if (params.createdFrom !== void 0) query.createdFrom = params.createdFrom;
+    if (params.createdTo !== void 0) query.createdTo = params.createdTo;
+    if (params.sort !== void 0) {
+      query.sort = `${params.sort.field}:${params.sort.direction}`;
+    }
+    if (params.limit !== void 0) query.limit = params.limit;
+    if (params.cursor !== void 0) query.cursor = params.cursor;
+    return this._get(this.basePath, query);
+  }
+  /**
+   * Update an existing guest profile.
+   *
+   * @example
+   * ```typescript
+   * const updated = await client.guests.update("guest_42", {
+   *   email: "maria.new@example.com",
+   *   tags: ["vip"],
+   * });
+   * ```
+   */
+  update(guestId, input) {
+    return this._patch(this._buildPath(guestId), input);
+  }
+  /**
+   * Delete a guest profile (soft-delete).
+   *
+   * @example
+   * ```typescript
+   * await client.guests.delete("guest_42");
+   * ```
+   */
+  delete(guestId) {
+    return this._delete(this._buildPath(guestId));
+  }
+  // ---------------------------------------------------------------------------
+  // Search and Duplicate Detection
+  // ---------------------------------------------------------------------------
+  /**
+   * 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, params) {
+    const searchQuery = {
+      q: query
+    };
+    if (params?.limit !== void 0) searchQuery.limit = params.limit;
+    if (params?.fields !== void 0 && params.fields.length > 0) {
+      searchQuery.fields = params.fields.join(",");
+    }
+    return this._get(this._buildPath("search"), searchQuery);
+  }
+  /**
+   * 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) {
+    return this._get(this._buildPath(guestId, "duplicates"));
+  }
+  // ---------------------------------------------------------------------------
+  // Merge
+  // ---------------------------------------------------------------------------
+  /**
+   * 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, input) {
+    return this._post(this._buildPath(primaryId, "merge"), input);
+  }
+  // ---------------------------------------------------------------------------
+  // Preferences
+  // ---------------------------------------------------------------------------
+  /**
+   * 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) {
+    return this._get(this._buildPath(guestId, "preferences"));
+  }
+  /**
+   * 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, input) {
+    return this._patch(this._buildPath(guestId, "preferences"), input);
+  }
+  // ---------------------------------------------------------------------------
+  // Cross-Domain History
+  // ---------------------------------------------------------------------------
+  /**
+   * 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, params) {
+    return this._get(
+      this._buildPath(guestId, "bookings"),
+      params ? this._buildHistoryQuery(params) : void 0
+    );
+  }
+  /**
+   * 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, params) {
+    return this._get(
+      this._buildPath(guestId, "folios"),
+      params ? this._buildHistoryQuery(params) : void 0
+    );
+  }
+  /**
+   * 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, params) {
+    return this._get(
+      this._buildPath(guestId, "orders"),
+      params ? this._buildHistoryQuery(params) : void 0
+    );
+  }
+  /** Build query params from GuestHistoryParams, omitting undefined values */
+  _buildHistoryQuery(params) {
+    const query = {};
+    if (params.limit !== void 0) query.limit = params.limit;
+    if (params.cursor !== void 0) query.cursor = params.cursor;
+    if (params.from !== void 0) query.from = params.from;
+    if (params.to !== void 0) query.to = params.to;
+    return query;
+  }
+};
+
 // src/services/properties.ts
 var PropertiesService = class extends BaseService {
   constructor() {
@@ -1025,6 +1542,16 @@ var BookingClient = class {
     this._availability ?? (this._availability = new AvailabilityService(this.httpClient));
     return this._availability;
   }
+  /** Bookings service — lazy-initialized on first access */
+  get bookings() {
+    this._bookings ?? (this._bookings = new BookingsService(this.httpClient));
+    return this._bookings;
+  }
+  /** Guests service — lazy-initialized on first access */
+  get guests() {
+    this._guests ?? (this._guests = new GuestsService(this.httpClient));
+    return this._guests;
+  }
   /** Properties service — lazy-initialized on first access */
   get properties() {
     this._properties ?? (this._properties = new PropertiesService(this.httpClient));
@@ -1079,6 +1606,27 @@ async function firstPage(fetcher, options) {
   return fetcher({ ...options ?? {} });
 }
 
+// src/types/bookings.ts
+var BOOKING_TYPES = [
+  "stay",
+  "table",
+  "service",
+  "parking",
+  "desk",
+  "meeting",
+  "dayuse",
+  "custom"
+];
+var BOOKING_STATUSES = [
+  "pending",
+  "confirmed",
+  "checked_in",
+  "checked_out",
+  "cancelled",
+  "no_show",
+  "waitlist"
+];
+
 // src/types/properties.ts
 var PROPERTY_MODULES = [
   "booking",
@@ -1128,12 +1676,16 @@ var VERSION = "0.1.0";
 export {
   AuthenticationError,
   AvailabilityService,
+  BOOKING_STATUSES,
+  BOOKING_TYPES,
   BookingClient,
   BookingError,
+  BookingsService,
   CategoriesService,
   ConflictError,
   DEFAULT_MODULES,
   ForbiddenError,
+  GuestsService,
   HttpClient,
   NotFoundError,
   PROPERTY_MODULES,