Merge pull request #22 from peek-travel/feat/full-customer-access-option

feat: add fullCustomerAccess option gating customer PII and payments

Author: oskarbruening

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,

docs/internal/ARCHITECTURE.md

@@ -68,7 +68,8 @@ GraphQL) and gateway routing (`cng_backoffice_api-v1` /
     resolution).
 - Optional config: `mode` (`"v2"` — see below), `baseUrl`, `tokenTtlSeconds` (3600), `tokenRefreshLeewaySeconds`
   (60), `retryDelaysMs` (`[1000, 2000, 4000]`), `logger` (no-op default),
-  `fetch` (global default), `itemOptionsPageSize` (50).
+  `fetch` (global default), `itemOptionsPageSize` (50), and `accessOptions`
+  (see "Access options / PII" below).
 - **v2 mode** (`mode: "v2"`): routes requests through the app-registry
   installations API. The endpoint URL becomes
   `baseUrl/appId/peek_backoffice_api-v1/endpointName` and the default `baseUrl`
@@ -229,15 +230,62 @@ Recurring patterns inside services:
   rejected. Validating pre-normalization is deliberate: normalization would
   erase the case/separator distinction the check relies on.
 
+### 4b. Access options / PII
+`src/access-options.ts`
+
+Every access service (`PeekAccessService`, `CngAccessService`, `AcmeAccessService`)
+accepts an optional `accessOptions` config object — the public `AccessOptions`
+type. Today it carries one flag, `fullCustomerAccess` (default `false`); it is an object
+rather than a bare boolean so future cross-cutting flags slot in without changing
+any downstream signatures. Each access service resolves it once
+(`resolveAccessOptions`, which fills defaults) and threads the resolved value
+into the resource services that read customer data.
+
+When `fullCustomerAccess` is `false` (the default), two things happen:
+
+1. **PII is never requested (filtered at the GraphQL layer, not in the
+   converters).** The query *builders* omit the PII fields entirely, so the
+   gateway never returns them and the pure converters map the now-absent fields
+   to `null`/empty — the converters stay PII-agnostic. Affected:
+   - **Bookings** (`booking-queries.ts`): `buildBookingQueryFields` /
+     `buildBookingGuestsFields` / `buildBookingGuestsQuery` /
+     `buildBookingsListingQuery` drop the primary-guest block
+     (`customerName`/`email`/`phone`), the guest identity fields
+     (name/country/DOB/email/phone/postalCode/`isGdpr`/`fieldResponses` — the
+     guest list keeps only ids + participation/opt-in flags), the custom
+     question answers (booking- and ticket-level), and the customer
+     `bookingPortalUrl`. Operator-facing fields (notes, the Peek Pro deep link,
+     money, resources) always stay.
+   - **Reviews** (`buildReviewsQuery`): drops the reviewer `name`/`email`; the
+     review `comment`, rating, dates, and credited guides always stay.
+   - **Waivers** (`parseWaiverWebhook`): the webhook delivers a *fixed* payload
+     with no GraphQL selection to trim, so this is the one place filtering is
+     applied at parse time — the participant `guestName` and the signed-document
+     `fileUrl` are nulled. `parseWaiverWebhook(body, options?)` takes the same
+     `AccessOptions`; `fromWaiverNode` stays a pure full mapping.
+
+2. **Payment / booking-modification operations are disabled.** `BookingService`
+   gates the operations that touch customer financial data —
+   `getPaymentsOnFile`, `makePayment`, `refund`, `createInvoiceLink`,
+   `addAddon`, `removeAddon` — throwing `PiiAccessDisabledError` (an exported
+   typed error) before any network call. Non-payment reads/mutations
+   (`getById`, `getGuests`, `cancel`, `appendNote`, `setCheckinStatus`) and
+   `create` (**including `markAsPaid`**) remain available.
+
+The webhook **registration** query (`BOOKING_WEBHOOK_GQL_QUERY`) is deliberately
+unaffected — it is the maximal selection built from the full field fragments and
+pinned by the drift-guard test; `fullCustomerAccess` governs only the runtime read path.
+
 ### 5. Public API surface
 `src/index.ts`
 
 The barrel re-exports only the public contract: `PeekAccessService` + its config,
-each resource service class (and the options/result types callers need), all
-data-model **types** (including `PeekAuthTokenClaims` and `PeekAuthTokenUser`),
-the `Logger` interface + `noopLogger`, and the typed error classes
-(`AdminAccountRequiredError`, `RateLimitError`, `PeekGraphQLError`,
-`CngApiError`, `AcmeApiError`). Query strings and raw response interfaces are deliberately kept
+the `AccessOptions` type (see §4b), each resource service class (and the
+options/result types callers need), all data-model **types** (including
+`PeekAuthTokenClaims` and `PeekAuthTokenUser`), the `Logger` interface +
+`noopLogger`, and the typed error classes (`AdminAccountRequiredError`,
+`RateLimitError`, `PeekGraphQLError`, `PiiAccessDisabledError`, `CngApiError`,
+`AcmeApiError`). Query strings and raw response interfaces are deliberately kept
 internal — including the booking-webhook registration query
 (`BOOKING_WEBHOOK_GQL_QUERY` stays internal, documented via `docs/webhooks.md`).
 The webhook-related public exports are the two parsers `parseBookingWebhook` and

docs/webhooks.md

@@ -112,7 +112,8 @@ config. Leave `output_fields_gql_query` null; the `output_format` is
 import { parseWaiverWebhook, type Waiver } from "@peektravel/app-utilities";
 
 app.post("/waiver-webhook", (req, res) => {
-  const waiver: Waiver = parseWaiverWebhook(req.body);
+  // PII (guestName, fileUrl) is redacted unless you opt in:
+  const waiver: Waiver = parseWaiverWebhook(req.body, { fullCustomerAccess: true });
   // waiver.bookingId, waiver.templateId, waiver.fileUrl, waiver.signedAt,
   // waiver.guestName, waiver.isSignedByGuardian, …
   res.sendStatus(200);
@@ -125,6 +126,13 @@ bare node / a JSON string, maps the raw `snake_case` payload to the clean
 camelCase [`Waiver`](#waiver-webhooks) model, and never throws on malformed input
 (missing fields become `""` / `null` / `false`).
 
+**PII:** `parseWaiverWebhook(body, options?)` takes the same `AccessOptions` as
+the access services. By **default** (`fullCustomerAccess` unset/`false`) the participant
+`guestName` and the signed-document `fileUrl` are redacted (`null`/`""`); pass
+`{ fullCustomerAccess: true }` to keep them. The booking parser
+`parseBookingWebhook(body)` is unaffected — a booking webhook carries whatever
+its registered selection includes.
+
 The resulting `Waiver` is flat:
 
 | Field | Type | From |

llms.txt

@@ -25,10 +25,21 @@ const peek = new PeekAccessService({
   appId,       // gateway path segment
   gatewayKey,  // pk-api-key header
   // optional: baseUrl, tokenTtlSeconds, tokenRefreshLeewaySeconds,
-  // retryDelaysMs, logger, fetch, itemOptionsPageSize
+  // retryDelaysMs, logger, fetch, itemOptionsPageSize,
+  // accessOptions: { fullCustomerAccess: false }  // default — see "Access options / PII"
 });
 ```
 
+## Access options / PII
+
+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.
+
 ## Resources (accessor → methods)
 
 - `getProductService()` — `getAllProducts()` (flat list of activities + add-ons;
@@ -64,8 +75,9 @@ const peek = new PeekAccessService({
 ## Errors
 
 - `AdminAccountRequiredError` (HTTP 418), `RateLimitError` (HTTP 429 after
-  retries), `PeekGraphQLError` (`.graphqlErrors` holds the raw array) — all
-  importable; branch with `instanceof`.
+  retries), `PeekGraphQLError` (`.graphqlErrors` holds the raw array),
+  `PiiAccessDisabledError` (a payment/booking-modification op was called without
+  `fullCustomerAccess`) — all importable; branch with `instanceof`.
 - Plain `Error` for validation/precondition failures thrown before any request.
 
 ## Webhooks (booking + waiver)
@@ -80,9 +92,11 @@ external system** (App Store config), not from code.
   the canonical maximal selection into `output_fields_gql_query`. That string is
   documented in `docs/webhooks.md` and pinned by a drift-guard test — it is NOT a
   runtime export.
-- `parseWaiverWebhook(body): Waiver` — maps the fixed `snake_case`
+- `parseWaiverWebhook(body, options?): Waiver` — maps the fixed `snake_case`
   `waiver_webhook_data` payload to the clean `Waiver` model. **No query to
-  register** — just subscribe to the `agreement_signature_created` event.
+  register** — just subscribe to the `agreement_signature_created` event. Takes
+  the same `AccessOptions`; by default (`fullCustomerAccess` off) `guestName` and
+  `fileUrl` are redacted — pass `{ fullCustomerAccess: true }` to keep them.
 
 **Full guide + booking query-to-register: `docs/webhooks.md` (shipped).**
 

package-lock.json

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

package.json

@@ -0,0 +1,36 @@
+/**
+ * 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. */
+export 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;
+}
+
+/** A fully-resolved {@link AccessOptions} with every flag defaulted. */
+export type ResolvedAccessOptions = Required<AccessOptions>;
+
+/**
+ * Resolves a possibly-absent {@link AccessOptions} into a concrete object with
+ * every flag defaulted. `fullCustomerAccess` defaults to `false` (PII off).
+ */
+export function resolveAccessOptions(options?: AccessOptions): ResolvedAccessOptions {
+  return { fullCustomerAccess: options?.fullCustomerAccess ?? false };
+}

src/access-options.ts

@@ -8,6 +8,7 @@
  * plumbing is written once.
  */
 import { TokenManager } from "./internal/token-manager.js";
+import type { AccessOptions } from "./access-options.js";
 import type { Logger } from "./logger.js";
 
 /** Fields common to every access service's config. */
@@ -33,6 +34,13 @@ export 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;
 }
 
 /** Default JWT lifetime (1 hour). */

src/access-service-config.ts

@@ -51,6 +51,27 @@ export class PeekGraphQLError extends Error {
   }
 }
 
+/**
+ * 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.
+ */
+export class PiiAccessDisabledError extends Error {
+  /** The name of the operation that was blocked (e.g. `"makePayment"`). */
+  public readonly operation: string;
+
+  constructor(operation: string) {
+    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;
+  }
+}
+
 /**
  * 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

src/errors.ts

@@ -8,6 +8,9 @@
 export { PeekAccessService } from "./peek-access-service.js";
 export type { PeekAccessServiceConfig } from "./peek-access-service.js";
 
+// ─── Cross-cutting access options (PII exposure, …) ──────────────────────────
+export type { AccessOptions } from "./access-options.js";
+
 // ─── CNG (REST) — sibling accessor sharing this package's auth/transport/UI ──
 export { CngAccessService } from "./cng-access-service.js";
 export type { CngAccessServiceConfig } from "./cng-access-service.js";
@@ -141,5 +144,6 @@ export {
   AdminAccountRequiredError,
   CngApiError,
   PeekGraphQLError,
+  PiiAccessDisabledError,
   RateLimitError,
 } from "./errors.js";