@peektravel/app-utilities 0.4.1 → 0.5.0

package/README.md

@@ -70,6 +70,34 @@ add-on pages for you.
 | `logger` | no-op | Inject a `Logger` for diagnostics |
 | `fetch` | global `fetch` | Custom fetch (e.g. for tests) |
 | `itemOptionsPageSize` | `50` | Add-on pagination page size |
+| `accessOptions` | `{ fullCustomerAccess: false }` | PII exposure — see [Access options / PII](#access-options--pii) |
+
+### Access options / PII
+
+Every access service accepts `accessOptions?: AccessOptions` — today a single
+flag, `fullCustomerAccess` (default `false`). It's an object so future cross-cutting
+flags can be added without breaking signatures.
+
+With `fullCustomerAccess` **off** (the default):
+
+- **Customer PII is never requested** (the GraphQL queries omit the fields, so
+  they come back `null`/empty): booking guest identity (name/email/phone/DOB/
+  postal code/GDPR + custom field responses — guests keep only ids and
+  participation/opt-in flags), booking custom question answers, the customer
+  `portalUrl`, and review reviewer `customerName`/`customerEmail`. Waiver
+  webhooks (a fixed payload with no query to trim) instead have `guestName` and
+  `fileUrl` redacted at parse time.
+- **Payment / booking-modification operations are disabled** —
+  `getPaymentsOnFile`, `makePayment`, `refund`, `createInvoiceLink`, `addAddon`,
+  and `removeAddon` throw `PiiAccessDisabledError`. `create` (including
+  `markAsPaid`) and non-payment reads/mutations remain available.
+
+```ts
+const peek = new PeekAccessService({
+  installId, jwtSecret, issuer, appId, gatewayKey,
+  accessOptions: { fullCustomerAccess: true }, // opt into PII + payment operations
+});
+```
 
 ### Errors
 
@@ -83,6 +111,9 @@ Two kinds of failures surface as exceptions:
   exhausted. Carries `.statusCode === 429`.
 - `PeekGraphQLError` — the response contained a GraphQL `errors` array, preserved
   on `.graphqlErrors`.
+- `PiiAccessDisabledError` — a payment / booking-modification operation was
+  called on an access service created without `fullCustomerAccess` (see [Access options
+  / PII](#access-options--pii)). Carries `.operation` (the blocked method name).
 
 **Plain `Error` validation/precondition failures** thrown by the service layer
 *before* any network call — e.g. an empty config field, a `bookingId` that
@@ -216,13 +247,16 @@ app.post("/booking-webhook", (req, res) => {
 });
 
 app.post("/waiver-webhook", (req, res) => {
-  const waiver: Waiver = parseWaiverWebhook(req.body);
+  // guestName/fileUrl are redacted unless you opt into PII:
+  const waiver: Waiver = parseWaiverWebhook(req.body, { fullCustomerAccess: true });
   res.sendStatus(200);
 });
 ```
 
 Both tolerate the delivery envelope / a bare node / a JSON string and never throw
-on malformed input. They differ on registration: a **booking** webhook's payload
+on malformed input. `parseWaiverWebhook` also takes an optional `AccessOptions`
+(`{ fullCustomerAccess }`) and redacts the participant `guestName` + document `fileUrl`
+by default — see [Access options / PII](#access-options--pii) below. They differ on registration: a **booking** webhook's payload
 shape is set by a GraphQL query configured **once in an external system** (the
 App Store `broadcast_to_url` config) — this package documents and drift-guards
 the exact query to paste there — whereas a **waiver** webhook has a fixed payload,

package/dist/index.cjs

@@ -203,6 +203,73 @@ var AvailabilityService = class {
   }
 };
 
+// src/access-options.ts
+function resolveAccessOptions(options) {
+  return { fullCustomerAccess: options?.fullCustomerAccess ?? false };
+}
+
+// src/errors.ts
+var AdminAccountRequiredError = class extends Error {
+  /** The HTTP status that triggered this error. */
+  statusCode = 418;
+  constructor(message = "Admin account required") {
+    super(message);
+    this.name = "AdminAccountRequiredError";
+  }
+};
+var RateLimitError = class extends Error {
+  /** The HTTP status that triggered this error. */
+  statusCode = 429;
+  constructor(message = "Rate limit exceeded") {
+    super(message);
+    this.name = "RateLimitError";
+  }
+};
+var PeekGraphQLError = class extends Error {
+  /** The raw `errors` array returned by the GraphQL endpoint. */
+  graphqlErrors;
+  constructor(graphqlErrors, message = "GraphQL request failed") {
+    super(message);
+    this.name = "PeekGraphQLError";
+    this.graphqlErrors = graphqlErrors;
+  }
+};
+var PiiAccessDisabledError = class extends Error {
+  /** The name of the operation that was blocked (e.g. `"makePayment"`). */
+  operation;
+  constructor(operation) {
+    super(
+      `"${operation}" is disabled because this access service was created without "fullCustomerAccess"; enable it to allow payment and booking-modification operations`
+    );
+    this.name = "PiiAccessDisabledError";
+    this.operation = operation;
+  }
+};
+var CngApiError = class extends Error {
+  /** The HTTP status that triggered this error. */
+  statusCode;
+  /** The raw response body (parsed JSON when possible, otherwise text). */
+  body;
+  constructor(statusCode, body, message) {
+    super(message ?? `CNG request failed with HTTP ${statusCode}`);
+    this.name = "CngApiError";
+    this.statusCode = statusCode;
+    this.body = body;
+  }
+};
+var AcmeApiError = class extends Error {
+  /** The HTTP status that triggered this error. */
+  statusCode;
+  /** The raw response body (parsed JSON when possible, otherwise text). */
+  body;
+  constructor(statusCode, body, message) {
+    super(message ?? `ACME request failed with HTTP ${statusCode}`);
+    this.name = "AcmeApiError";
+    this.statusCode = statusCode;
+    this.body = body;
+  }
+};
+
 // src/models/peek/product.ts
 var ACTIVITY_PRODUCT_TYPE = "ACTIVITY";
 var RENTAL_PRODUCT_TYPE = "RENTAL";
@@ -214,17 +281,8 @@ var SEARCH_BY_ACTIVITY_DATE = "activityDate";
 function normalizeBookingId(bookingId) {
   return bookingId.toLowerCase().replace(/-/g, "_");
 }
-var guestFields = `
-  id
-  name
-  country
-  dateOfBirth
-  email
-  isGdpr
-  isParticipant
-  optinSms
-  optinMarketing
-  phone
+var GUEST_IDENTITY_PII_FIELDS = "name country dateOfBirth email isGdpr";
+var GUEST_CONTACT_PII_FIELDS = `phone
   postalCode
   fieldResponses {
     id
@@ -234,9 +292,20 @@ var guestFields = `
         name
       }
     }
-  }
+  }`;
+function buildGuestFields(fullCustomerAccess) {
+  return `
+  id
+  ${fullCustomerAccess ? GUEST_IDENTITY_PII_FIELDS : ""}
+  isParticipant
+  optinSms
+  optinMarketing
+  ${fullCustomerAccess ? GUEST_CONTACT_PII_FIELDS : ""}
 `;
-var bookingGuestsFields = `
+}
+function buildBookingGuestsFields(fullCustomerAccess) {
+  const guestFields = buildGuestFields(fullCustomerAccess);
+  return `
   bookingGuests {
     ${guestFields}
   }
@@ -244,10 +313,9 @@ var bookingGuestsFields = `
     ${guestFields}
   }
 `;
-var bookingQueryFields = `
-  displayId
-  id
-  primaryGuest {
+}
+var bookingGuestsFields = buildBookingGuestsFields(true);
+var BOOKING_PRIMARY_GUEST_PII_FIELDS = `primaryGuest {
     name
     email
     phone
@@ -255,7 +323,26 @@ var bookingQueryFields = `
     optinSms
     isGdpr
     postalCode
+  }`;
+var BOOKING_QUESTION_ANSWERS_PII_FIELDS = `questionAnswers {
+    answer
+    questionText
+    questionLocationSnapshot {
+      latitude
+      longitude
+    }
   }
+  tickets {
+    questionAnswers {
+      answer
+      questionText
+    }
+  }`;
+function buildBookingQueryFields(fullCustomerAccess) {
+  return `
+  displayId
+  id
+  ${fullCustomerAccess ? BOOKING_PRIMARY_GUEST_PII_FIELDS : ""}
   activitySnapshot {
     type
     name
@@ -285,7 +372,7 @@ var bookingQueryFields = `
   endsAt
   endsAtUtc
   availabilityTimeId
-  bookingPortalUrl
+  ${fullCustomerAccess ? "bookingPortalUrl" : ""}
   operatorNotes
   value {
     total {
@@ -327,20 +414,7 @@ var bookingQueryFields = `
       }
     }
   }
-  questionAnswers {
-    answer
-    questionText
-    questionLocationSnapshot {
-      latitude
-      longitude
-    }
-  }
-  tickets {
-    questionAnswers {
-      answer
-      questionText
-    }
-  }
+  ${fullCustomerAccess ? BOOKING_QUESTION_ANSWERS_PII_FIELDS : ""}
   resourcePoolAssignments {
     quantity
     resourcePool {
@@ -358,6 +432,8 @@ var bookingQueryFields = `
     }
   }
 `;
+}
+var bookingQueryFields = buildBookingQueryFields(true);
 var PRICE_BREAKDOWN_FIELDS = `
   convenienceFee { amount formatted }
   deposit { amount formatted }
@@ -376,9 +452,10 @@ var TICKET_VALUE_FIELDS = `
     total { amount formatted }
   }
 `;
-function buildBookingsListingQuery(includeGuests, includePriceBreakdown) {
-  const guestsSection = includeGuests ? bookingGuestsFields : "";
-  const fields = includePriceBreakdown ? bookingQueryFields.replace("value {", `value { ${PRICE_BREAKDOWN_FIELDS}`).replace("ticketQuantities {", `ticketQuantities { ${TICKET_VALUE_FIELDS}`) : bookingQueryFields;
+function buildBookingsListingQuery(includeGuests, includePriceBreakdown, fullCustomerAccess = true) {
+  const guestsSection = includeGuests ? buildBookingGuestsFields(fullCustomerAccess) : "";
+  const baseFields = buildBookingQueryFields(fullCustomerAccess);
+  const fields = includePriceBreakdown ? baseFields.replace("value {", `value { ${PRICE_BREAKDOWN_FIELDS}`).replace("ticketQuantities {", `ticketQuantities { ${TICKET_VALUE_FIELDS}`) : baseFields;
   return `
     query Sales($after: String, $first: Int, $filter: SalesFilter!, $orderBy: SalesOrdering) {
       sales(after: $after, first: $first, filter: $filter, orderBy: $orderBy) {
@@ -395,7 +472,8 @@ function buildBookingsListingQuery(includeGuests, includePriceBreakdown) {
     }
   `;
 }
-var BOOKING_GUESTS_QUERY = `
+function buildBookingGuestsQuery(fullCustomerAccess) {
+  return `
   query Sales($after: String, $first: Int, $filter: SalesFilter!, $orderBy: SalesOrdering) {
     sales(after: $after, first: $first, filter: $filter, orderBy: $orderBy) {
       pageInfo { endCursor hasNextPage }
@@ -404,13 +482,14 @@ var BOOKING_GUESTS_QUERY = `
           ... on Booking {
             displayId
             id
-            ${bookingGuestsFields}
+            ${buildBookingGuestsFields(fullCustomerAccess)}
           }
         }
       }
     }
   }
 `;
+}
 var BOOKING_PAYMENTS_ON_FILE_QUERY = `
   query Sales($after: String, $first: Int, $filter: SalesFilter!, $orderBy: SalesOrdering) {
     sales(after: $after, first: $first, filter: $filter, orderBy: $orderBy) {
@@ -996,10 +1075,23 @@ var BookingService = class {
     this.client = client;
     this.deps = deps;
     this.pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE2;
+    this.fullCustomerAccess = resolveAccessOptions(options.accessOptions).fullCustomerAccess;
   }
   client;
   deps;
   pageSize;
+  /** Whether customer PII is requested and payment operations are allowed. */
+  fullCustomerAccess;
+  /**
+   * Throws a {@link PiiAccessDisabledError} for `operation` when this service was
+   * created without `fullCustomerAccess` — used to gate payment and booking-modification
+   * operations that touch customer financial data.
+   */
+  assertPiiEnabled(operation) {
+    if (!this.fullCustomerAccess) {
+      throw new PiiAccessDisabledError(operation);
+    }
+  }
   /**
    * Returns a single booking by id, or null when not found. The `bookingId` is
    * normalized internally (lowercased, `-` → `_`), so `B-ABC123` and `b_abc123`
@@ -1021,7 +1113,7 @@ var BookingService = class {
     const includePriceBreakdown = options.includePriceBreakdown ?? false;
     const body = await this.client.request(
       SALES_ENDPOINT,
-      buildBookingsListingQuery(includeGuests, includePriceBreakdown),
+      buildBookingsListingQuery(includeGuests, includePriceBreakdown, this.fullCustomerAccess),
       buildBookingsVariables({
         pageSize: this.pageSize,
         after: null,
@@ -1039,7 +1131,7 @@ var BookingService = class {
     const includeGuests = input.includeGuests ?? false;
     const includePriceBreakdown = input.includePriceBreakdown ?? false;
     return this.fetchPaginated(
-      buildBookingsListingQuery(includeGuests, includePriceBreakdown),
+      buildBookingsListingQuery(includeGuests, includePriceBreakdown, this.fullCustomerAccess),
       {
         startDateTime: input.start,
         endDateTime: input.end,
@@ -1057,7 +1149,7 @@ var BookingService = class {
     const includeGuests = options.includeGuests ?? false;
     const includePriceBreakdown = options.includePriceBreakdown ?? false;
     return this.fetchPaginated(
-      buildBookingsListingQuery(includeGuests, includePriceBreakdown),
+      buildBookingsListingQuery(includeGuests, includePriceBreakdown, this.fullCustomerAccess),
       { timeslotId },
       includeGuests,
       includePriceBreakdown
@@ -1068,7 +1160,7 @@ var BookingService = class {
     assertBookingId(bookingId);
     const body = await this.client.request(
       SALES_ENDPOINT,
-      BOOKING_GUESTS_QUERY,
+      buildBookingGuestsQuery(this.fullCustomerAccess),
       buildBookingsVariables({
         pageSize: this.pageSize,
         after: null,
@@ -1079,6 +1171,7 @@ var BookingService = class {
   }
   /** Returns the payments on file for a booking, or null when not found. */
   async getPaymentsOnFile(bookingId) {
+    this.assertPiiEnabled("getPaymentsOnFile");
     assertBookingId(bookingId);
     const normalized = normalizeBookingId(bookingId);
     const body = await this.client.request(
@@ -1163,6 +1256,7 @@ ${note}`;
    * charge fails.
    */
   async makePayment(input) {
+    this.assertPiiEnabled("makePayment");
     this.validatePaymentInput(input);
     const normalized = normalizeBookingId(input.bookingId);
     const onFile = await this.getPaymentsOnFile(normalized);
@@ -1205,6 +1299,7 @@ ${note}`;
    * payments-on-file, then applies the refund.
    */
   async refund(input) {
+    this.assertPiiEnabled("refund");
     this.validateRefundInput(input);
     const normalized = normalizeBookingId(input.bookingId);
     const onFile = await this.getPaymentsOnFile(normalized);
@@ -1245,6 +1340,7 @@ ${note}`;
   }
   /** Creates an invoice link for a booking's order. */
   async createInvoiceLink(bookingId) {
+    this.assertPiiEnabled("createInvoiceLink");
     assertBookingId(bookingId);
     const normalized = normalizeBookingId(bookingId);
     const booking = await this.getById(normalized);
@@ -1300,6 +1396,7 @@ ${note}`;
    * the underlying quote/order mutations fail.
    */
   async addAddon(bookingId, input) {
+    this.assertPiiEnabled("addAddon");
     assertBookingId(bookingId);
     const addonOptionId = (input?.addonOptionId || input?.addonId || "").trim();
     if (!addonOptionId) {
@@ -1353,6 +1450,7 @@ ${note}`;
    * variables. Returns the booking's add-ons after the change.
    */
   async removeAddon(bookingId, input) {
+    this.assertPiiEnabled("removeAddon");
     assertBookingId(bookingId);
     const addonOptionId = (input?.addonOptionId || input?.addonId || "").trim();
     if (!addonOptionId) {
@@ -1842,57 +1940,6 @@ function createTokenManager(config) {
   });
 }
 
-// src/errors.ts
-var AdminAccountRequiredError = class extends Error {
-  /** The HTTP status that triggered this error. */
-  statusCode = 418;
-  constructor(message = "Admin account required") {
-    super(message);
-    this.name = "AdminAccountRequiredError";
-  }
-};
-var RateLimitError = class extends Error {
-  /** The HTTP status that triggered this error. */
-  statusCode = 429;
-  constructor(message = "Rate limit exceeded") {
-    super(message);
-    this.name = "RateLimitError";
-  }
-};
-var PeekGraphQLError = class extends Error {
-  /** The raw `errors` array returned by the GraphQL endpoint. */
-  graphqlErrors;
-  constructor(graphqlErrors, message = "GraphQL request failed") {
-    super(message);
-    this.name = "PeekGraphQLError";
-    this.graphqlErrors = graphqlErrors;
-  }
-};
-var CngApiError = class extends Error {
-  /** The HTTP status that triggered this error. */
-  statusCode;
-  /** The raw response body (parsed JSON when possible, otherwise text). */
-  body;
-  constructor(statusCode, body, message) {
-    super(message ?? `CNG request failed with HTTP ${statusCode}`);
-    this.name = "CngApiError";
-    this.statusCode = statusCode;
-    this.body = body;
-  }
-};
-var AcmeApiError = class extends Error {
-  /** The HTTP status that triggered this error. */
-  statusCode;
-  /** The raw response body (parsed JSON when possible, otherwise text). */
-  body;
-  constructor(statusCode, body, message) {
-    super(message ?? `ACME request failed with HTTP ${statusCode}`);
-    this.name = "AcmeApiError";
-    this.statusCode = statusCode;
-    this.body = body;
-  }
-};
-
 // src/internal/http-transport.ts
 var RATE_LIMIT_STATUS = 429;
 var ADMIN_ACCOUNT_REQUIRED_STATUS = 418;
@@ -2311,7 +2358,8 @@ function encodeCursor(offset, pageSize) {
 }
 
 // src/internal/peek/reviews/review-queries.ts
-var REVIEWS_QUERY = `
+function buildReviewsQuery(fullCustomerAccess) {
+  return `
   query Reviews($first: Int, $filter: ReviewFilter, $after: String) {
     reviews(first: $first, filter: $filter, after: $after) {
       edges {
@@ -2325,8 +2373,7 @@ var REVIEWS_QUERY = `
             name
           }
           id
-          name
-          email
+          ${fullCustomerAccess ? "name\n          email" : ""}
           rating
           comment
           reviewedAt
@@ -2337,6 +2384,7 @@ var REVIEWS_QUERY = `
     }
   }
 `;
+}
 function buildReviewsVariables(params) {
   return {
     first: params.first,
@@ -2353,10 +2401,13 @@ 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) {
+  constructor(client, accessOptions) {
     this.client = client;
+    this.fullCustomerAccess = resolveAccessOptions(accessOptions).fullCustomerAccess;
   }
   client;
+  /** Whether reviewer PII (name/email) is requested. */
+  fullCustomerAccess;
   /**
    * Returns up to `reviewCount` reviews for an activity in **descending order
    * by review date (newest first)**, skipping the `reviewOffset` newest reviews
@@ -2387,7 +2438,7 @@ var ReviewService = class {
     const after = reviewOffset > 0 ? encodeCursor(reviewOffset - 1, reviewCount) : null;
     const body = await this.client.request(
       SALES_ENDPOINT,
-      REVIEWS_QUERY,
+      buildReviewsQuery(this.fullCustomerAccess),
       buildReviewsVariables({ activityId: productId, first: reviewCount, after })
     );
     const edges = body.data?.reviews?.edges ?? [];
@@ -3029,6 +3080,7 @@ var PEEK_TOKEN_ISSUER = "app_registry_v2";
 var PeekAccessService = class {
   client;
   productServiceOptions;
+  accessOptions;
   jwtSecret;
   productService;
   accountUserService;
@@ -3065,6 +3117,7 @@ var PeekAccessService = class {
     this.productServiceOptions = {
       itemOptionsPageSize: config.itemOptionsPageSize
     };
+    this.accessOptions = resolveAccessOptions(config.accessOptions);
   }
   /**
    * Verifies a Peek auth token issued by the app registry and returns the
@@ -3205,9 +3258,11 @@ var PeekAccessService = class {
    */
   getBookingService() {
     if (!this.bookingService) {
-      this.bookingService = new BookingService(this.client, {
-        productService: this.getProductService()
-      });
+      this.bookingService = new BookingService(
+        this.client,
+        { productService: this.getProductService() },
+        { accessOptions: this.accessOptions }
+      );
     }
     return this.bookingService;
   }
@@ -3217,7 +3272,7 @@ var PeekAccessService = class {
    */
   getReviewService() {
     if (!this.reviewService) {
-      this.reviewService = new ReviewService(this.client);
+      this.reviewService = new ReviewService(this.client, this.accessOptions);
     }
     return this.reviewService;
   }
@@ -3710,8 +3765,13 @@ function hasPriceBreakdown(node) {
 
 // src/internal/peek/waivers/waiver-webhook.ts
 var PAYLOAD_WAIVER_KEY = "waiver";
-function parseWaiverWebhook(payload) {
-  return fromWaiverNode(extractWaiverNode(payload));
+function parseWaiverWebhook(payload, options) {
+  const waiver = fromWaiverNode(extractWaiverNode(payload));
+  if (!resolveAccessOptions(options).fullCustomerAccess) {
+    waiver.guestName = null;
+    waiver.fileUrl = "";
+  }
+  return waiver;
 }
 function fromWaiverNode(node) {
   const data = node ?? {};
@@ -3759,6 +3819,7 @@ exports.DailyNoteService = DailyNoteService;
 exports.MembershipService = MembershipService;
 exports.PeekAccessService = PeekAccessService;
 exports.PeekGraphQLError = PeekGraphQLError;
+exports.PiiAccessDisabledError = PiiAccessDisabledError;
 exports.ProductService = ProductService;
 exports.PromoCodeService = PromoCodeService;
 exports.RENTAL_PRODUCT_TYPE = RENTAL_PRODUCT_TYPE;