@peektravel/app-utilities 0.1.1 → 0.1.2

package/dist/index.d.cts

@@ -922,6 +922,80 @@ declare class ResourcePoolService {
     getAll(mode?: ResourcePoolMode): Promise<ResourcePool[]>;
 }
 
+/**
+ * Clean data models for Peek activity reviews.
+ */
+/** A guide credited on a review. */
+interface Guide {
+    /** Guide id (e.g. `u_y6e4r`). */
+    id: string;
+    /** Guide display name. */
+    name: string;
+}
+/** A single customer review for an activity (product). */
+interface Review {
+    /** Review id (e.g. `rvw_359erv`). */
+    id: string;
+    /** Activity (product) id the review is for. */
+    productId: string;
+    /** Activity (product) name. */
+    productName: string;
+    /** Guides credited on the review. May be empty. */
+    guides: Guide[];
+    /** Customer name. May be null. */
+    customerName: string | null;
+    /** Customer email. May be null. */
+    customerEmail: string | null;
+    /** Activity date (`YYYY-MM-DD`), derived from `purchasedFor`. */
+    activityDate: string;
+    /** Review date (`YYYY-MM-DD`), derived from `reviewedAt`. */
+    reviewDate: string;
+    /** Star rating, 1–5. */
+    rating: number;
+    /** Free-text review. May be null. */
+    comment: string | null;
+}
+
+/**
+ * Reads activity reviews from the gateway, which returns them newest-first
+ * (descending `reviewedAt`). {@link ReviewService.getReviews} fetches a single
+ * page of up to `reviewCount` reviews, skipping the first `reviewOffset` of
+ * them via the connection cursor.
+ *
+ * Obtain an instance via {@link PeekAccessService.getReviewService}.
+ */
+declare class ReviewService {
+    private readonly client;
+    constructor(client: GraphQLClient);
+    /**
+     * Returns up to `reviewCount` reviews for an activity in **descending order
+     * by review date (newest first)**, skipping the `reviewOffset` newest reviews
+     * before collecting.
+     *
+     * The gateway cursor resumes *after* a given absolute offset, so to skip the
+     * first `reviewOffset` reviews the request is anchored on the review just
+     * before the window. A `reviewOffset` of 0 needs no cursor and is sent
+     * without one.
+     *
+     * @param productId - The activity (product) id to fetch reviews for.
+     * @param reviewCount - How many reviews to return (1–50). Default: 50.
+     * @param reviewOffset - How many of the newest reviews to skip first
+     *   (0-based). Default: 0 (start at the newest review).
+     *
+     * @throws {Error} when `productId` is empty, `reviewCount` is not an integer
+     * in 1–50, or `reviewOffset` is not a non-negative integer.
+     *
+     * @example
+     * ```ts
+     * const reviews = await peek
+     *   .getReviewService()
+     *   .getReviews("87cdf37f-1872-42cb-b0bd-518312624fc1", 25, 50);
+     * ```
+     */
+    getReviews(productId: string, reviewCount?: number, reviewOffset?: number): Promise<Review[]>;
+    private validate;
+}
+
 /**
  * The clean data model for Peek Pro timeslots and timeslot operations.
  */
@@ -1182,6 +1256,7 @@ declare class PeekAccessService {
     private availabilityService?;
     private membershipService?;
     private bookingService?;
+    private reviewService?;
     constructor(config: PeekAccessServiceConfig);
     /**
      * Returns the {@link ProductService} for this install, bound to the shared
@@ -1234,6 +1309,11 @@ declare class PeekAccessService {
      * authenticated transport. The instance is created lazily and reused.
      */
     getBookingService(): BookingService;
+    /**
+     * Returns the {@link ReviewService} for this install, bound to the shared
+     * authenticated transport. The instance is created lazily and reused.
+     */
+    getReviewService(): ReviewService;
 }
 
 /**
@@ -1269,4 +1349,4 @@ declare class PeekGraphQLError extends Error {
     constructor(graphqlErrors: unknown[], message?: string);
 }
 
-export { ADD_ON_PRODUCT_TYPE, type AccountUser, AccountUserService, type AccountUserServiceOptions, type AddAddonInput, AdminAccountRequiredError, type Agent, type AssignGuideResult, type AssignedActivity, type AssignedResource, type Availability, AvailabilityService, type AvailabilityTime, type AvailabilityTimesQuery, type Booking, type BookingAddon, type BookingAddonMoney, type BookingAddonOption, type BookingAddons, type BookingAddonsMutationResult, type BookingPaymentsOnFile, type BookingReadOptions, type BookingSearchBy, BookingService, type BookingServiceOptions, type BookingTimeRangeSearch, type CancelBookingResult, type Channel, type CreateBookingGuest, type CreateBookingInput, type CreateBookingTicket, type CreatePromoCodeInput, type CreatedBooking, type CreatedPromoCode, type CustomQuestionAnswer, type DailyNote, DailyNoteService, type Duration, type Guest, type GuestMetadata, type GuideAssignment, type InvoiceLinkResult, type Logger, type MakePaymentInput, type MakePaymentResult, type Membership, type MembershipPurchaseInput, MembershipService, type NoteMode, type Payment, type PaymentSource, PeekAccessService, type PeekAccessServiceConfig, PeekGraphQLError, type Price, type Product, ProductService, type ProductServiceOptions, type ProductTicket, type PromoCode, type PromoCodeFixedAmount, PromoCodeService, type PromoCodeServiceOptions, type PurchasedMembership, RateLimitError, type RefundInput, type RefundResult, ResellerService, type Resource, type ResourceOptionQuantity, type ResourcePool, type ResourcePoolAccountUser, type ResourcePoolAssignment, type ResourcePoolMode, ResourcePoolService, type Ticket, type Timeslot, type TimeslotFilter, TimeslotService, type UpdateTimeslotResult, noopLogger };
+export { ADD_ON_PRODUCT_TYPE, type AccountUser, AccountUserService, type AccountUserServiceOptions, type AddAddonInput, AdminAccountRequiredError, type Agent, type AssignGuideResult, type AssignedActivity, type AssignedResource, type Availability, AvailabilityService, type AvailabilityTime, type AvailabilityTimesQuery, type Booking, type BookingAddon, type BookingAddonMoney, type BookingAddonOption, type BookingAddons, type BookingAddonsMutationResult, type BookingPaymentsOnFile, type BookingReadOptions, type BookingSearchBy, BookingService, type BookingServiceOptions, type BookingTimeRangeSearch, type CancelBookingResult, type Channel, type CreateBookingGuest, type CreateBookingInput, type CreateBookingTicket, type CreatePromoCodeInput, type CreatedBooking, type CreatedPromoCode, type CustomQuestionAnswer, type DailyNote, DailyNoteService, type Duration, type Guest, type GuestMetadata, type Guide, type GuideAssignment, type InvoiceLinkResult, type Logger, type MakePaymentInput, type MakePaymentResult, type Membership, type MembershipPurchaseInput, MembershipService, type NoteMode, type Payment, type PaymentSource, PeekAccessService, type PeekAccessServiceConfig, PeekGraphQLError, type Price, type Product, ProductService, type ProductServiceOptions, type ProductTicket, type PromoCode, type PromoCodeFixedAmount, PromoCodeService, type PromoCodeServiceOptions, type PurchasedMembership, RateLimitError, type RefundInput, type RefundResult, ResellerService, type Resource, type ResourceOptionQuantity, type ResourcePool, type ResourcePoolAccountUser, type ResourcePoolAssignment, type ResourcePoolMode, ResourcePoolService, type Review, ReviewService, type Ticket, type Timeslot, type TimeslotFilter, TimeslotService, type UpdateTimeslotResult, noopLogger };

package/dist/index.d.ts

@@ -922,6 +922,80 @@ declare class ResourcePoolService {
     getAll(mode?: ResourcePoolMode): Promise<ResourcePool[]>;
 }
 
+/**
+ * Clean data models for Peek activity reviews.
+ */
+/** A guide credited on a review. */
+interface Guide {
+    /** Guide id (e.g. `u_y6e4r`). */
+    id: string;
+    /** Guide display name. */
+    name: string;
+}
+/** A single customer review for an activity (product). */
+interface Review {
+    /** Review id (e.g. `rvw_359erv`). */
+    id: string;
+    /** Activity (product) id the review is for. */
+    productId: string;
+    /** Activity (product) name. */
+    productName: string;
+    /** Guides credited on the review. May be empty. */
+    guides: Guide[];
+    /** Customer name. May be null. */
+    customerName: string | null;
+    /** Customer email. May be null. */
+    customerEmail: string | null;
+    /** Activity date (`YYYY-MM-DD`), derived from `purchasedFor`. */
+    activityDate: string;
+    /** Review date (`YYYY-MM-DD`), derived from `reviewedAt`. */
+    reviewDate: string;
+    /** Star rating, 1–5. */
+    rating: number;
+    /** Free-text review. May be null. */
+    comment: string | null;
+}
+
+/**
+ * Reads activity reviews from the gateway, which returns them newest-first
+ * (descending `reviewedAt`). {@link ReviewService.getReviews} fetches a single
+ * page of up to `reviewCount` reviews, skipping the first `reviewOffset` of
+ * them via the connection cursor.
+ *
+ * Obtain an instance via {@link PeekAccessService.getReviewService}.
+ */
+declare class ReviewService {
+    private readonly client;
+    constructor(client: GraphQLClient);
+    /**
+     * Returns up to `reviewCount` reviews for an activity in **descending order
+     * by review date (newest first)**, skipping the `reviewOffset` newest reviews
+     * before collecting.
+     *
+     * The gateway cursor resumes *after* a given absolute offset, so to skip the
+     * first `reviewOffset` reviews the request is anchored on the review just
+     * before the window. A `reviewOffset` of 0 needs no cursor and is sent
+     * without one.
+     *
+     * @param productId - The activity (product) id to fetch reviews for.
+     * @param reviewCount - How many reviews to return (1–50). Default: 50.
+     * @param reviewOffset - How many of the newest reviews to skip first
+     *   (0-based). Default: 0 (start at the newest review).
+     *
+     * @throws {Error} when `productId` is empty, `reviewCount` is not an integer
+     * in 1–50, or `reviewOffset` is not a non-negative integer.
+     *
+     * @example
+     * ```ts
+     * const reviews = await peek
+     *   .getReviewService()
+     *   .getReviews("87cdf37f-1872-42cb-b0bd-518312624fc1", 25, 50);
+     * ```
+     */
+    getReviews(productId: string, reviewCount?: number, reviewOffset?: number): Promise<Review[]>;
+    private validate;
+}
+
 /**
  * The clean data model for Peek Pro timeslots and timeslot operations.
  */
@@ -1182,6 +1256,7 @@ declare class PeekAccessService {
     private availabilityService?;
     private membershipService?;
     private bookingService?;
+    private reviewService?;
     constructor(config: PeekAccessServiceConfig);
     /**
      * Returns the {@link ProductService} for this install, bound to the shared
@@ -1234,6 +1309,11 @@ declare class PeekAccessService {
      * authenticated transport. The instance is created lazily and reused.
      */
     getBookingService(): BookingService;
+    /**
+     * Returns the {@link ReviewService} for this install, bound to the shared
+     * authenticated transport. The instance is created lazily and reused.
+     */
+    getReviewService(): ReviewService;
 }
 
 /**
@@ -1269,4 +1349,4 @@ declare class PeekGraphQLError extends Error {
     constructor(graphqlErrors: unknown[], message?: string);
 }
 
-export { ADD_ON_PRODUCT_TYPE, type AccountUser, AccountUserService, type AccountUserServiceOptions, type AddAddonInput, AdminAccountRequiredError, type Agent, type AssignGuideResult, type AssignedActivity, type AssignedResource, type Availability, AvailabilityService, type AvailabilityTime, type AvailabilityTimesQuery, type Booking, type BookingAddon, type BookingAddonMoney, type BookingAddonOption, type BookingAddons, type BookingAddonsMutationResult, type BookingPaymentsOnFile, type BookingReadOptions, type BookingSearchBy, BookingService, type BookingServiceOptions, type BookingTimeRangeSearch, type CancelBookingResult, type Channel, type CreateBookingGuest, type CreateBookingInput, type CreateBookingTicket, type CreatePromoCodeInput, type CreatedBooking, type CreatedPromoCode, type CustomQuestionAnswer, type DailyNote, DailyNoteService, type Duration, type Guest, type GuestMetadata, type GuideAssignment, type InvoiceLinkResult, type Logger, type MakePaymentInput, type MakePaymentResult, type Membership, type MembershipPurchaseInput, MembershipService, type NoteMode, type Payment, type PaymentSource, PeekAccessService, type PeekAccessServiceConfig, PeekGraphQLError, type Price, type Product, ProductService, type ProductServiceOptions, type ProductTicket, type PromoCode, type PromoCodeFixedAmount, PromoCodeService, type PromoCodeServiceOptions, type PurchasedMembership, RateLimitError, type RefundInput, type RefundResult, ResellerService, type Resource, type ResourceOptionQuantity, type ResourcePool, type ResourcePoolAccountUser, type ResourcePoolAssignment, type ResourcePoolMode, ResourcePoolService, type Ticket, type Timeslot, type TimeslotFilter, TimeslotService, type UpdateTimeslotResult, noopLogger };
+export { ADD_ON_PRODUCT_TYPE, type AccountUser, AccountUserService, type AccountUserServiceOptions, type AddAddonInput, AdminAccountRequiredError, type Agent, type AssignGuideResult, type AssignedActivity, type AssignedResource, type Availability, AvailabilityService, type AvailabilityTime, type AvailabilityTimesQuery, type Booking, type BookingAddon, type BookingAddonMoney, type BookingAddonOption, type BookingAddons, type BookingAddonsMutationResult, type BookingPaymentsOnFile, type BookingReadOptions, type BookingSearchBy, BookingService, type BookingServiceOptions, type BookingTimeRangeSearch, type CancelBookingResult, type Channel, type CreateBookingGuest, type CreateBookingInput, type CreateBookingTicket, type CreatePromoCodeInput, type CreatedBooking, type CreatedPromoCode, type CustomQuestionAnswer, type DailyNote, DailyNoteService, type Duration, type Guest, type GuestMetadata, type Guide, type GuideAssignment, type InvoiceLinkResult, type Logger, type MakePaymentInput, type MakePaymentResult, type Membership, type MembershipPurchaseInput, MembershipService, type NoteMode, type Payment, type PaymentSource, PeekAccessService, type PeekAccessServiceConfig, PeekGraphQLError, type Price, type Product, ProductService, type ProductServiceOptions, type ProductTicket, type PromoCode, type PromoCodeFixedAmount, PromoCodeService, type PromoCodeServiceOptions, type PurchasedMembership, RateLimitError, type RefundInput, type RefundResult, ResellerService, type Resource, type ResourceOptionQuantity, type ResourcePool, type ResourcePoolAccountUser, type ResourcePoolAssignment, type ResourcePoolMode, ResourcePoolService, type Review, ReviewService, type Ticket, type Timeslot, type TimeslotFilter, TimeslotService, type UpdateTimeslotResult, noopLogger };

package/dist/index.js

@@ -2129,6 +2129,132 @@ var ResourcePoolService = class {
   }
 };
 
+// src/internal/reviews/review-converter.ts
+var ISO_DATE_LENGTH = 10;
+function toDateOnly(isoDateTime) {
+  return isoDateTime.slice(0, ISO_DATE_LENGTH);
+}
+function fromReviewNode(node) {
+  const guides = (node.guides ?? []).map((guide) => ({
+    id: guide.id,
+    name: guide.name
+  }));
+  return {
+    id: node.id,
+    productId: node.activity?.id ?? "",
+    productName: node.activity?.name ?? "",
+    guides,
+    customerName: node.name ?? null,
+    customerEmail: node.email ?? null,
+    activityDate: toDateOnly(node.purchasedFor),
+    reviewDate: toDateOnly(node.reviewedAt),
+    rating: node.rating,
+    comment: node.comment ?? null
+  };
+}
+
+// src/internal/reviews/review-cursor.ts
+function encodeCursor(offset, pageSize) {
+  const start = Math.max(0, offset - pageSize + 1);
+  return Buffer.from(`range:${start}..${offset},${offset}`).toString("base64");
+}
+
+// src/internal/reviews/review-queries.ts
+var REVIEWS_QUERY = `
+  query Reviews($first: Int, $filter: ReviewFilter, $after: String) {
+    reviews(first: $first, filter: $filter, after: $after) {
+      edges {
+        node {
+          activity {
+            id
+            name
+          }
+          guides {
+            id
+            name
+          }
+          id
+          name
+          email
+          rating
+          comment
+          reviewedAt
+          purchasedFor
+        }
+        cursor
+      }
+    }
+  }
+`;
+function buildReviewsVariables(params) {
+  return {
+    first: params.first,
+    filter: { activityIds: [params.activityId] },
+    after: params.after
+  };
+}
+
+// src/internal/reviews/review-service.ts
+var DEFAULT_REVIEW_COUNT = 50;
+var MIN_REVIEW_COUNT = 1;
+var MAX_REVIEW_COUNT = 50;
+var ERROR_PRODUCT_ID_REQUIRED = "productId is required";
+var ERROR_INVALID_REVIEW_COUNT = `reviewCount must be an integer between ${MIN_REVIEW_COUNT} and ${MAX_REVIEW_COUNT}`;
+var ERROR_INVALID_REVIEW_OFFSET = "reviewOffset must be a non-negative integer";
+var ReviewService = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Returns up to `reviewCount` reviews for an activity in **descending order
+   * by review date (newest first)**, skipping the `reviewOffset` newest reviews
+   * before collecting.
+   *
+   * The gateway cursor resumes *after* a given absolute offset, so to skip the
+   * first `reviewOffset` reviews the request is anchored on the review just
+   * before the window. A `reviewOffset` of 0 needs no cursor and is sent
+   * without one.
+   *
+   * @param productId - The activity (product) id to fetch reviews for.
+   * @param reviewCount - How many reviews to return (1–50). Default: 50.
+   * @param reviewOffset - How many of the newest reviews to skip first
+   *   (0-based). Default: 0 (start at the newest review).
+   *
+   * @throws {Error} when `productId` is empty, `reviewCount` is not an integer
+   * in 1–50, or `reviewOffset` is not a non-negative integer.
+   *
+   * @example
+   * ```ts
+   * const reviews = await peek
+   *   .getReviewService()
+   *   .getReviews("87cdf37f-1872-42cb-b0bd-518312624fc1", 25, 50);
+   * ```
+   */
+  async getReviews(productId, reviewCount = DEFAULT_REVIEW_COUNT, reviewOffset = 0) {
+    this.validate(productId, reviewCount, reviewOffset);
+    const after = reviewOffset > 0 ? encodeCursor(reviewOffset - 1, reviewCount) : null;
+    const body = await this.client.request(
+      SALES_ENDPOINT,
+      REVIEWS_QUERY,
+      buildReviewsVariables({ activityId: productId, first: reviewCount, after })
+    );
+    const edges = body.data?.reviews?.edges ?? [];
+    return edges.map((edge) => fromReviewNode(edge.node));
+  }
+  validate(productId, reviewCount, reviewOffset) {
+    if (!productId) {
+      throw new Error(ERROR_PRODUCT_ID_REQUIRED);
+    }
+    if (!Number.isInteger(reviewCount) || reviewCount < MIN_REVIEW_COUNT || reviewCount > MAX_REVIEW_COUNT) {
+      throw new Error(ERROR_INVALID_REVIEW_COUNT);
+    }
+    if (!Number.isInteger(reviewOffset) || reviewOffset < 0) {
+      throw new Error(ERROR_INVALID_REVIEW_OFFSET);
+    }
+  }
+};
+
 // src/internal/timeslots/timeslot-converter.ts
 function fromTimeslotNodes(nodes, productId) {
   if (!Array.isArray(nodes) || nodes.length === 0) {
@@ -2776,6 +2902,7 @@ var PeekAccessService = class {
   availabilityService;
   membershipService;
   bookingService;
+  reviewService;
   constructor(config) {
     requireNonEmpty(config.installId, "installId");
     requireNonEmpty(config.jwtSecret, "jwtSecret");
@@ -2912,6 +3039,16 @@ var PeekAccessService = class {
     }
     return this.bookingService;
   }
+  /**
+   * Returns the {@link ReviewService} for this install, bound to the shared
+   * authenticated transport. The instance is created lazily and reused.
+   */
+  getReviewService() {
+    if (!this.reviewService) {
+      this.reviewService = new ReviewService(this.client);
+    }
+    return this.reviewService;
+  }
 };
 function requireNonEmpty(value, name) {
   if (!value) {
@@ -2919,6 +3056,6 @@ function requireNonEmpty(value, name) {
   }
 }
 
-export { ADD_ON_PRODUCT_TYPE, AccountUserService, AdminAccountRequiredError, AvailabilityService, BookingService, DailyNoteService, MembershipService, PeekAccessService, PeekGraphQLError, ProductService, PromoCodeService, RateLimitError, ResellerService, ResourcePoolService, TimeslotService, noopLogger };
+export { ADD_ON_PRODUCT_TYPE, AccountUserService, AdminAccountRequiredError, AvailabilityService, BookingService, DailyNoteService, MembershipService, PeekAccessService, PeekGraphQLError, ProductService, PromoCodeService, RateLimitError, ResellerService, ResourcePoolService, ReviewService, TimeslotService, noopLogger };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map