@peektravel/app-utilities 0.5.0 → 0.5.2

package/llms.txt

@@ -30,26 +30,81 @@ const peek = new PeekAccessService({
 });
 ```
 
-## Access options / PII
+## Access options / PII — `fullCustomerAccess`
 
-Every access service takes `accessOptions?: AccessOptions` (`{ fullCustomerAccess?: boolean }`,
-default `false`). With `fullCustomerAccess` off, customer PII is **not requested** at the
-GraphQL layer (booking guest identity + custom question answers + `portalUrl`,
-review reviewer name/email → `null`/empty), and `BookingService` **disables**
-`getPaymentsOnFile`/`makePayment`/`refund`/`createInvoiceLink`/`addAddon`/
-`removeAddon` (throw `PiiAccessDisabledError`). `create` (incl. `markAsPaid`) and
-non-payment reads/mutations stay available. Pass `{ fullCustomerAccess: true }` to opt in.
+**The most commonly-misunderstood option in this package. Read this before
+debugging "why is `customerName` null?" or "why did `makePayment` throw?".**
+
+Every access service takes `accessOptions?: AccessOptions`
+(`{ fullCustomerAccess?: boolean }`). It is passed **once at construction**, not
+per call, and applies to every service that access service hands out.
+
+```ts
+const peek = new PeekAccessService({
+  installId, jwtSecret, issuer, appId, gatewayKey,
+  accessOptions: { fullCustomerAccess: true },  // opt in to PII + payment ops
+});
+```
+
+- **Default is `false` (PII off).** Omitting `accessOptions`, passing `{}`, or
+  passing `undefined` are all identical to `{ fullCustomerAccess: false }`.
+- There is **no per-call override** by design — an install either has customer-
+  data entitlement or it doesn't. Need both modes? Construct two access services.
+- Consumed by `BookingService` and `ReviewService`; `parseWaiverWebhook(body,
+  options?)` takes the same object directly. `CngAccessService` /
+  `AcmeAccessService` accept the field but have no PII surface (inert).
+
+### With `fullCustomerAccess: false` (default) — two distinct effects
+
+**1. PII is never requested.** Filtering happens in the GraphQL selection, so the
+data never leaves the gateway; the fields simply arrive as `null`/empty in the
+clean models. There is no error and no warning — a missing name looks exactly
+like a customer who didn't provide one.
+
+| Surface | Redacted (→ `null`/empty) | Always present |
+| --- | --- | --- |
+| Booking | primary-guest `customerName`/`email`/`phone`/`postalCode`/`isGdpr`/opt-ins; per-guest identity (name, country, DOB, email, phone, postal code, `isGdpr`, custom `fieldResponses`) — guests keep only ids + participation/opt-in flags; booking- and ticket-level custom `questionAnswers`; the customer `portalUrl` | notes, Peek Pro operator deep link, money/price breakdown, resources, timeslot + structural ids |
+| Review | reviewer `customerName` / `customerEmail` | comment, rating, dates, credited guides |
+| Waiver webhook | participant `guestName`, signed-document `fileUrl` (redacted at parse time — the payload is fixed, so there is no selection to trim) | signature/agreement ids, timestamps, booking linkage |
+
+**2. Payment & booking-modification operations are disabled.** These throw
+`PiiAccessDisabledError` (exported; `.operation` names the blocked method)
+**before any network call**:
+
+`getPaymentsOnFile`, `makePayment`, `refund`, `createInvoiceLink`, `addAddon`,
+`removeAddon`.
+
+Still available without the flag: `create` (**including `markAsPaid`**),
+`getById`, `getGuests`, `searchByTimeRange`, `searchByTimeslot`, `listAddons`,
+`cancel`, `appendNote`, `setCheckinStatus`, and every other resource service.
+
+### Choosing a value
+
+Leave it `false` for operations/logistics tooling (manifests, check-in, guide
+assignment, notes, availability) — that surface is fully functional without PII.
+Set it `true` only when the app genuinely needs to contact customers or move
+money, and only when the install is entitled to that data; the gateway is the
+final authority and may still reject the request.
 
 ## Resources (accessor → methods)
 
 - `getProductService()` — `getAllProducts()` (flat list of activities + add-ons;
-  add-ons have `type === ADD_ON_PRODUCT_TYPE`)
+  add-ons have `type === ADD_ON_PRODUCT_TYPE`); `Product.currency` carries the
+  activity's ISO currency (empty for add-ons). Each `Product.tickets[]` entry
+  carries `minPrice`/`maxPrice` (`PricingMoney | null`, `null` for add-ons and
+  when Peek reports no range); every `PricingMoney` includes a `displayPrice`
+  string (e.g. `"$50.00"`) on values read back from the gateway.
 - `getAccountUserService()` — `getAll()`, `getById(userId)`
 - `getResourcePoolService()` — `getAll(mode?)`
 - `getTimeslotService()` — `getForDay(productId, date, filter?)`, `getById(id)`,
   `setAvailability(...)`, `setNotes(...)`, `assignGuide({timeslotIds, guideIds, action})`
 - `getResellerService()` — `getAllChannels(agentsPerChannel?)`
 - `getPromoCodeService()` — `getAll()`, `create(input)`
+- `getPricingService()` — `createEngine(input)`, `updateEngine(input)`,
+  `deleteEngine(id)` (idempotent), `upsertOverrides(input)`, `clearOverrides(input)`.
+  Primitives-only: caller builds the `UpsertOverridesInput` (segmentation,
+  override `order`, `spotsTaken` bounds are the caller's job); service sends it
+  as-is and returns the resolved `activityContexts`.
 - `getDailyNoteService()` — `getToday()`, `update(note)`
 - `getAvailabilityService()` — `getAvailabilityTimes({activityId, date, resourceOptionQuantities})`
 - `getMembershipService()` — `getAll()`, `purchase(input)`
@@ -60,6 +115,24 @@ non-payment reads/mutations stay available. Pass `{ fullCustomerAccess: true }`
   `listAddons(id)`, `addAddon(id, {addonOptionId, quantity})`,
   `removeAddon(id, {addonOptionId, quantity})`, `create(input)`
 
+## Sibling accessors (CNG, ACME — REST, not GraphQL)
+
+Two brand-parallel accessors sit alongside `PeekAccessService` and share the same
+auth/transport/UI plumbing. Both are **REST** and deliberately minimal today
+(products only). Construct one per install, same config shape **minus `gatewayKey`**
+(`installId`, `jwtSecret`, `issuer`, `appId`); both default the base URL to the
+app-registry installations API.
+
+- `CngAccessService` — `getProductService().getAllActivities()` (short-form
+  `getAllActivities()`) → `Activity[]` (`Activity`/`ActivityTicket` models).
+  Errors surface as `CngApiError`.
+- `AcmeAccessService` — `getProductService().getAllActivities()` (short-form
+  `getAllActivities()`) → `AcmeActivity[]` (`AcmeActivity`/`AcmeActivityTicket`
+  models). Errors surface as `AcmeApiError`.
+
+All are exported from the package root `.`; REST paths and raw response shapes
+stay internal.
+
 ## Input conventions (enforced in the service layer; violations throw plain Error)
 
 - Booking ids normalized (lowercased, `-`→`_`): `B-ABC123` == `b_abc123`.
@@ -77,7 +150,8 @@ non-payment reads/mutations stay available. Pass `{ fullCustomerAccess: true }`
 - `AdminAccountRequiredError` (HTTP 418), `RateLimitError` (HTTP 429 after
   retries), `PeekGraphQLError` (`.graphqlErrors` holds the raw array),
   `PiiAccessDisabledError` (a payment/booking-modification op was called without
-  `fullCustomerAccess`) — all importable; branch with `instanceof`.
+  `fullCustomerAccess`), and the REST-sibling `CngApiError` / `AcmeApiError` —
+  all importable; branch with `instanceof`.
 - Plain `Error` for validation/precondition failures thrown before any request.
 
 ## Webhooks (booking + waiver)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peektravel/app-utilities",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "GraphQL JS mapping utilities extracted from the Peek Pro Autopilot connector.",
   "license": "MIT",
   "repository": {