@peektravel/app-utilities 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -156,6 +156,31 @@ declare class ProductService {
     private fetchAllItemOptionNodes;
 }
 
+/**
+ * Cross-cutting options that govern what data an access service will read and
+ * expose. Passed once when constructing an access service and threaded down to
+ * the resource services (and the webhook parsers) so a single object controls
+ * behaviour everywhere, rather than a boolean being passed hand-to-hand.
+ *
+ * Kept deliberately small — today it carries a single PII toggle, but new
+ * cross-cutting flags slot in here without changing any downstream signatures.
+ */
+/** Options controlling PII exposure across an access service's reads. */
+interface AccessOptions {
+    /**
+     * When `true`, customer PII (guest names/emails/phones, custom question
+     * answers, the customer booking-portal URL, waiver participant details, …) is
+     * requested and returned, and payment/booking-modification operations are
+     * available.
+     *
+     * When `false` (the default), those PII fields are never requested from the
+     * gateway and come back `null`/empty, and the payment/booking-modification
+     * operations that touch customer financial data are disabled (they throw a
+     * {@link PiiAccessDisabledError}).
+     */
+    fullCustomerAccess?: boolean;
+}
+
 /**
  * The clean, transport-agnostic data model for Peek Pro bookings.
  *
@@ -667,6 +692,8 @@ interface CancelBookingResult {
 interface BookingServiceOptions {
     /** Page size for cursor pagination. Default: 50. */
     pageSize?: number;
+    /** Cross-cutting access options (PII exposure). Default: PII off. */
+    accessOptions?: AccessOptions;
 }
 /** Dependencies the {@link BookingService} composes for add-on resolution. */
 interface BookingServiceDeps {
@@ -688,7 +715,15 @@ declare class BookingService {
     private readonly client;
     private readonly deps;
     private readonly pageSize;
+    /** Whether customer PII is requested and payment operations are allowed. */
+    private readonly fullCustomerAccess;
     constructor(client: GraphQLClient, deps: BookingServiceDeps, options?: BookingServiceOptions);
+    /**
+     * 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.
+     */
+    private assertPiiEnabled;
     /**
      * Returns a single booking by id, or null when not found. The `bookingId` is
      * normalized internally (lowercased, `-` → `_`), so `B-ABC123` and `b_abc123`
@@ -1226,6 +1261,12 @@ interface BaseAccessServiceConfig {
     logger?: Logger;
     /** Custom `fetch` implementation. Default: the global `fetch`. */
     fetch?: typeof fetch;
+    /**
+     * Cross-cutting access options (PII exposure, …). When omitted, defaults are
+     * used ({@link AccessOptions.fullCustomerAccess} `false`). Threaded down to the
+     * resource services that read customer data.
+     */
+    accessOptions?: AccessOptions;
 }
 
 declare class MembershipService {
@@ -1335,7 +1376,9 @@ interface Review {
  */
 declare class ReviewService {
     private readonly client;
-    constructor(client: GraphQLClient);
+    /** Whether reviewer PII (name/email) is requested. */
+    private readonly fullCustomerAccess;
+    constructor(client: GraphQLClient, accessOptions?: AccessOptions);
     /**
      * Returns up to `reviewCount` reviews for an activity in **descending order
      * by review date (newest first)**, skipping the `reviewOffset` newest reviews
@@ -1506,6 +1549,7 @@ interface PeekAccessServiceConfig extends BaseAccessServiceConfig {
 declare class PeekAccessService {
     private readonly client;
     private readonly productServiceOptions;
+    private readonly accessOptions;
     private readonly jwtSecret;
     private productService?;
     private accountUserService?;
@@ -2001,8 +2045,13 @@ interface Waiver {
  * Accepts the raw request body — either the `{ waiver: … }` envelope or a bare
  * waiver node, and a JSON string is parsed first. Never throws on malformed
  * input: a missing/garbled body yields a {@link Waiver} with empty fields.
+ *
+ * Because a waiver webhook has no GraphQL selection to trim (Peek delivers a
+ * fixed payload), the PII fields — the participant `guestName` and the signed
+ * document `fileUrl` — are instead redacted here at parse time when `options`
+ * does not enable PII. Pass `{ fullCustomerAccess: true }` to keep them.
  */
-declare function parseWaiverWebhook(payload: unknown): Waiver;
+declare function parseWaiverWebhook(payload: unknown, options?: AccessOptions): Waiver;
 
 /**
  * Typed errors thrown by the package. Each mirrors a failure mode of the Peek
@@ -2040,6 +2089,18 @@ declare class PeekGraphQLError extends Error {
     readonly graphqlErrors: unknown[];
     constructor(graphqlErrors: unknown[], message?: string);
 }
+/**
+ * Thrown when a payment or booking-modification operation is called on an
+ * access service that was constructed without `fullCustomerAccess` (PII access
+ * disabled). These operations — pulling payment sources, charging/refunding,
+ * creating invoice links, and adding/removing add-ons — touch customer
+ * financial data, so they are gated behind the same flag as customer PII.
+ */
+declare class PiiAccessDisabledError extends Error {
+    /** The name of the operation that was blocked (e.g. `"makePayment"`). */
+    readonly operation: string;
+    constructor(operation: string);
+}
 /**
  * Thrown when the CNG REST gateway returns a non-2xx response that is not one
  * of the specifically-handled statuses (418/429). The offending status is
@@ -2068,4 +2129,4 @@ declare class AcmeApiError extends Error {
     constructor(statusCode: number, body: unknown, message?: string);
 }
 
-export { ACTIVITY_PRODUCT_TYPE, ADD_ON_PRODUCT_TYPE, type AccountUser, AccountUserService, type AccountUserServiceOptions, AcmeAccessService, type AcmeAccessServiceConfig, type AcmeActivity, type AcmeActivityTicket, AcmeApiError, AcmeProductService, type Activity, type ActivityTicket, 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, CngAccessService, type CngAccessServiceConfig, CngApiError, CngProductService, 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, type PeekAuthTokenClaims, type PeekAuthTokenUser, PeekGraphQLError, type PeekPlatform, type Price, type Product, ProductService, type ProductServiceOptions, type ProductTicket, type PromoCode, type PromoCodeFixedAmount, PromoCodeService, type PromoCodeServiceOptions, type PurchasedMembership, RENTAL_PRODUCT_TYPE, 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, type Waiver, noopLogger, parseBookingWebhook, parseWaiverWebhook };
+export { ACTIVITY_PRODUCT_TYPE, ADD_ON_PRODUCT_TYPE, type AccessOptions, type AccountUser, AccountUserService, type AccountUserServiceOptions, AcmeAccessService, type AcmeAccessServiceConfig, type AcmeActivity, type AcmeActivityTicket, AcmeApiError, AcmeProductService, type Activity, type ActivityTicket, 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, CngAccessService, type CngAccessServiceConfig, CngApiError, CngProductService, 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, type PeekAuthTokenClaims, type PeekAuthTokenUser, PeekGraphQLError, type PeekPlatform, PiiAccessDisabledError, type Price, type Product, ProductService, type ProductServiceOptions, type ProductTicket, type PromoCode, type PromoCodeFixedAmount, PromoCodeService, type PromoCodeServiceOptions, type PurchasedMembership, RENTAL_PRODUCT_TYPE, 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, type Waiver, noopLogger, parseBookingWebhook, parseWaiverWebhook };

package/dist/index.d.ts

@@ -156,6 +156,31 @@ declare class ProductService {
     private fetchAllItemOptionNodes;
 }
 
+/**
+ * Cross-cutting options that govern what data an access service will read and
+ * expose. Passed once when constructing an access service and threaded down to
+ * the resource services (and the webhook parsers) so a single object controls
+ * behaviour everywhere, rather than a boolean being passed hand-to-hand.
+ *
+ * Kept deliberately small — today it carries a single PII toggle, but new
+ * cross-cutting flags slot in here without changing any downstream signatures.
+ */
+/** Options controlling PII exposure across an access service's reads. */
+interface AccessOptions {
+    /**
+     * When `true`, customer PII (guest names/emails/phones, custom question
+     * answers, the customer booking-portal URL, waiver participant details, …) is
+     * requested and returned, and payment/booking-modification operations are
+     * available.
+     *
+     * When `false` (the default), those PII fields are never requested from the
+     * gateway and come back `null`/empty, and the payment/booking-modification
+     * operations that touch customer financial data are disabled (they throw a
+     * {@link PiiAccessDisabledError}).
+     */
+    fullCustomerAccess?: boolean;
+}
+
 /**
  * The clean, transport-agnostic data model for Peek Pro bookings.
  *
@@ -667,6 +692,8 @@ interface CancelBookingResult {
 interface BookingServiceOptions {
     /** Page size for cursor pagination. Default: 50. */
     pageSize?: number;
+    /** Cross-cutting access options (PII exposure). Default: PII off. */
+    accessOptions?: AccessOptions;
 }
 /** Dependencies the {@link BookingService} composes for add-on resolution. */
 interface BookingServiceDeps {
@@ -688,7 +715,15 @@ declare class BookingService {
     private readonly client;
     private readonly deps;
     private readonly pageSize;
+    /** Whether customer PII is requested and payment operations are allowed. */
+    private readonly fullCustomerAccess;
     constructor(client: GraphQLClient, deps: BookingServiceDeps, options?: BookingServiceOptions);
+    /**
+     * 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.
+     */
+    private assertPiiEnabled;
     /**
      * Returns a single booking by id, or null when not found. The `bookingId` is
      * normalized internally (lowercased, `-` → `_`), so `B-ABC123` and `b_abc123`
@@ -1226,6 +1261,12 @@ interface BaseAccessServiceConfig {
     logger?: Logger;
     /** Custom `fetch` implementation. Default: the global `fetch`. */
     fetch?: typeof fetch;
+    /**
+     * Cross-cutting access options (PII exposure, …). When omitted, defaults are
+     * used ({@link AccessOptions.fullCustomerAccess} `false`). Threaded down to the
+     * resource services that read customer data.
+     */
+    accessOptions?: AccessOptions;
 }
 
 declare class MembershipService {
@@ -1335,7 +1376,9 @@ interface Review {
  */
 declare class ReviewService {
     private readonly client;
-    constructor(client: GraphQLClient);
+    /** Whether reviewer PII (name/email) is requested. */
+    private readonly fullCustomerAccess;
+    constructor(client: GraphQLClient, accessOptions?: AccessOptions);
     /**
      * Returns up to `reviewCount` reviews for an activity in **descending order
      * by review date (newest first)**, skipping the `reviewOffset` newest reviews
@@ -1506,6 +1549,7 @@ interface PeekAccessServiceConfig extends BaseAccessServiceConfig {
 declare class PeekAccessService {
     private readonly client;
     private readonly productServiceOptions;
+    private readonly accessOptions;
     private readonly jwtSecret;
     private productService?;
     private accountUserService?;
@@ -2001,8 +2045,13 @@ interface Waiver {
  * Accepts the raw request body — either the `{ waiver: … }` envelope or a bare
  * waiver node, and a JSON string is parsed first. Never throws on malformed
  * input: a missing/garbled body yields a {@link Waiver} with empty fields.
+ *
+ * Because a waiver webhook has no GraphQL selection to trim (Peek delivers a
+ * fixed payload), the PII fields — the participant `guestName` and the signed
+ * document `fileUrl` — are instead redacted here at parse time when `options`
+ * does not enable PII. Pass `{ fullCustomerAccess: true }` to keep them.
  */
-declare function parseWaiverWebhook(payload: unknown): Waiver;
+declare function parseWaiverWebhook(payload: unknown, options?: AccessOptions): Waiver;
 
 /**
  * Typed errors thrown by the package. Each mirrors a failure mode of the Peek
@@ -2040,6 +2089,18 @@ declare class PeekGraphQLError extends Error {
     readonly graphqlErrors: unknown[];
     constructor(graphqlErrors: unknown[], message?: string);
 }
+/**
+ * Thrown when a payment or booking-modification operation is called on an
+ * access service that was constructed without `fullCustomerAccess` (PII access
+ * disabled). These operations — pulling payment sources, charging/refunding,
+ * creating invoice links, and adding/removing add-ons — touch customer
+ * financial data, so they are gated behind the same flag as customer PII.
+ */
+declare class PiiAccessDisabledError extends Error {
+    /** The name of the operation that was blocked (e.g. `"makePayment"`). */
+    readonly operation: string;
+    constructor(operation: string);
+}
 /**
  * Thrown when the CNG REST gateway returns a non-2xx response that is not one
  * of the specifically-handled statuses (418/429). The offending status is
@@ -2068,4 +2129,4 @@ declare class AcmeApiError extends Error {
     constructor(statusCode: number, body: unknown, message?: string);
 }
 
-export { ACTIVITY_PRODUCT_TYPE, ADD_ON_PRODUCT_TYPE, type AccountUser, AccountUserService, type AccountUserServiceOptions, AcmeAccessService, type AcmeAccessServiceConfig, type AcmeActivity, type AcmeActivityTicket, AcmeApiError, AcmeProductService, type Activity, type ActivityTicket, 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, CngAccessService, type CngAccessServiceConfig, CngApiError, CngProductService, 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, type PeekAuthTokenClaims, type PeekAuthTokenUser, PeekGraphQLError, type PeekPlatform, type Price, type Product, ProductService, type ProductServiceOptions, type ProductTicket, type PromoCode, type PromoCodeFixedAmount, PromoCodeService, type PromoCodeServiceOptions, type PurchasedMembership, RENTAL_PRODUCT_TYPE, 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, type Waiver, noopLogger, parseBookingWebhook, parseWaiverWebhook };
+export { ACTIVITY_PRODUCT_TYPE, ADD_ON_PRODUCT_TYPE, type AccessOptions, type AccountUser, AccountUserService, type AccountUserServiceOptions, AcmeAccessService, type AcmeAccessServiceConfig, type AcmeActivity, type AcmeActivityTicket, AcmeApiError, AcmeProductService, type Activity, type ActivityTicket, 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, CngAccessService, type CngAccessServiceConfig, CngApiError, CngProductService, 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, type PeekAuthTokenClaims, type PeekAuthTokenUser, PeekGraphQLError, type PeekPlatform, PiiAccessDisabledError, type Price, type Product, ProductService, type ProductServiceOptions, type ProductTicket, type PromoCode, type PromoCodeFixedAmount, PromoCodeService, type PromoCodeServiceOptions, type PurchasedMembership, RENTAL_PRODUCT_TYPE, 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, type Waiver, noopLogger, parseBookingWebhook, parseWaiverWebhook };