Merge pull request #24 from peek-travel/feat/ticket-price-range

oskarbruening · web-flow · commit ed128e72442e · 2026-07-29T14:45:11.000-04:00
feat: add ticket price ranges and PricingMoney displayPrice
diff --git a/docs/external/pricing-api.md b/docs/external/pricing-api.md
@@ -58,10 +58,17 @@ const peek = new PeekAccessService({ /* installId, jwtSecret, issuer, appId, gat
 const activities = await peek.getProductService().getAllActivities();
 const activity = activities[0]!;
 // activity.productId → the activityId
-// activity.tickets   → [{ id, name }, ...]  (the resourceOption ids)
+// activity.tickets   → [{ id, name, minPrice, maxPrice }, ...]  (resourceOptions)
 // activity.currency  → "USD"  (use this for fixed-price overrides)
 ```
 
+Each ticket also carries its current price range as `minPrice` / `maxPrice`
+(a `PricingMoney`, or `null` when Peek reports no range) — handy for seeding a
+fixed-price override or showing "from $X". Every `PricingMoney` read back from
+the gateway includes a `displayPrice` string (e.g. `"$50.00"`) alongside the raw
+`amount`/`currency`; it is display-only, so you never set it when *building* an
+override.
+
 > **Money and percentages are strings, not numbers.** `"80.00"`, `"-25"` — never
 > `80` or `-25`. The API rejects floats, and strings avoid precision loss.
 
diff --git a/docs/internal/ARCHITECTURE.md b/docs/internal/ARCHITECTURE.md
@@ -139,6 +139,15 @@ models in `src/models/peek/`, CNG models in `src/models/cng/`.
 `Product` (empty string for add-ons, which have none) — the field pricing
 consumers need to set the currency on fixed-price overrides.
 
+Each `Product.tickets[]` (a `ProductTicket`) additionally carries `minPrice`
+and `maxPrice` (`PricingMoney | null`), mapped from the resourceOption's
+`priceRange { min max }`. They are `null` for add-on options (no range) and
+when Peek reports none. The shared, internal `toPricingMoney` helper
+(`src/internal/peek/money.ts`) maps a raw gateway money node
+(`{ amount, currency, formatted }`) into `PricingMoney`, carrying `formatted`
+across as the optional `displayPrice` display string; both the products and
+pricing converters reuse it so that mapping lives in one place.
+
 `pricing` is a **write-only, primitives-only** triad
 (`src/internal/peek/pricing/`, model `src/models/peek/pricing.ts`). It wraps the
 four Peek pricing mutations — `createPricingEngine`, `updatePricingEngine`,
diff --git a/llms.txt b/llms.txt
@@ -90,7 +90,10 @@ final authority and may still reject the request.
 
 - `getProductService()` — `getAllProducts()` (flat list of activities + add-ons;
   add-ons have `type === ADD_ON_PRODUCT_TYPE`); `Product.currency` carries the
-  activity's ISO currency (empty for add-ons)
+  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)`,
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@peektravel/app-utilities",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "GraphQL JS mapping utilities extracted from the Peek Pro Autopilot connector.",
   "license": "MIT",
   "repository": {
diff --git a/src/internal/peek/money.ts b/src/internal/peek/money.ts
@@ -0,0 +1,30 @@
+/**
+ * Shared, pure helper for mapping a raw gateway money node
+ * (`{ amount, currency, formatted }`) into the clean {@link PricingMoney} model.
+ *
+ * Internal only — never re-exported from `src/index.ts`. Converters across
+ * resources (products, pricing overrides) reuse this so the `formatted →
+ * displayPrice` mapping lives in exactly one place.
+ */
+import type { PricingMoney } from "../../models/peek/pricing.js";
+
+/** A raw money node as returned by the gateway. */
+export interface RawMoney {
+  amount: string;
+  currency: string;
+  /** Human-formatted display string (e.g. `"$50.00"`). */
+  formatted?: string | null;
+}
+
+/**
+ * Maps a raw money node into a {@link PricingMoney}, carrying the gateway's
+ * `formatted` string across as `displayPrice`. Returns `null` for an
+ * absent/`null` input so callers can pass an optional wire field straight
+ * through.
+ */
+export function toPricingMoney(raw?: RawMoney | null): PricingMoney | null {
+  if (!raw) return null;
+  const money: PricingMoney = { amount: raw.amount, currency: raw.currency };
+  if (raw.formatted != null) money.displayPrice = raw.formatted;
+  return money;
+}
diff --git a/src/internal/peek/pricing/pricing-converter.ts b/src/internal/peek/pricing/pricing-converter.ts
@@ -16,6 +16,7 @@ import type {
   ResolvedPricingOverride,
   ResolvedResourceOption,
 } from "../../../models/peek/pricing.js";
+import { toPricingMoney } from "../money.js";
 import {
   SPOTS_TAKEN_FILTER_TYPENAME,
   type RawActivityContext,
@@ -63,7 +64,7 @@ function fromResourceOption(
 
 function fromResolvedOverride(override: RawResolvedOverride): ResolvedOverride {
   return "price" in override
-    ? { mode: "fixed", price: override.price }
+    ? { mode: "fixed", price: toPricingMoney(override.price)! }
     : { mode: "percentage", percentageAdjustment: override.percentageAdjustment };
 }
 
diff --git a/src/internal/peek/pricing/pricing-queries.ts b/src/internal/peek/pricing/pricing-queries.ts
@@ -103,6 +103,7 @@ export const UPSERT_PRICING_OVERRIDES_MUTATION = `
                   price {
                     amount
                     currency
+                    formatted
                   }
                 }
                 ... on PricingOverridesActivityContextResourceOptionPercentageAdjustmentOverride {
@@ -206,7 +207,7 @@ export interface UpsertOverridesVariables {
 
 /** A single resolved resource-option override as returned by the API. */
 export type RawResolvedOverride =
-  | { price: { amount: string; currency: string } }
+  | { price: { amount: string; currency: string; formatted?: string } }
   | { percentageAdjustment: string };
 
 /** A single resolved filter as returned by the API (tagged by `__typename`). */
@@ -278,7 +279,11 @@ export function buildUpsertInput(input: UpsertOverridesInput): RawUpsertInput {
         order: override.order,
         resourceOptions: override.resourceOptions.map((option) =>
           option.mode === "fixed"
-            ? { id: option.id, price: option.price }
+            ? {
+                id: option.id,
+                // Send only the wire fields — `displayPrice` is read-only.
+                price: { amount: option.price.amount, currency: option.price.currency },
+              }
             : { id: option.id, percentageAdjustment: option.percentageAdjustment },
         ),
         filters: override.filters,
diff --git a/src/internal/peek/products/product-converter.ts b/src/internal/peek/products/product-converter.ts
@@ -3,6 +3,7 @@
  * model. No I/O — straightforward, testable transformations.
  */
 import { ADD_ON_PRODUCT_TYPE, type Product } from "../../../models/peek/product.js";
+import { toPricingMoney } from "../money.js";
 import type { ActivityNode, ItemOptionNode } from "./product-queries.js";
 
 /** Default display color applied to add-on products. */
@@ -25,6 +26,8 @@ function fromActivity(activity: ActivityNode): Product {
     tickets: (activity.resourceOptions ?? []).map((option) => ({
       id: option.id,
       name: option.name,
+      minPrice: toPricingMoney(option.priceRange?.min),
+      maxPrice: toPricingMoney(option.priceRange?.max),
     })),
   };
 }
@@ -54,7 +57,12 @@ export function fromItemOptionNodes(nodes: ItemOptionNode[]): Product[] {
       };
       grouped.set(itemId, product);
     }
-    product.tickets.push({ id: node.id, name: node.name });
+    product.tickets.push({
+      id: node.id,
+      name: node.name,
+      minPrice: null,
+      maxPrice: null,
+    });
   }
 
   return Array.from(grouped.values());
diff --git a/src/internal/peek/products/product-queries.ts b/src/internal/peek/products/product-queries.ts
@@ -18,11 +18,30 @@ export const PRODUCTS_QUERY = `
       resourceOptions {
         id
         name
+        priceRange {
+          min {
+            currency
+            amount
+            formatted
+          }
+          max {
+            currency
+            amount
+            formatted
+          }
+        }
       }
     }
   }
 `;
 
+/** A raw monetary value on the wire (a `PricingMoney` before conversion). */
+export interface RawMoneyNode {
+  currency: string;
+  amount: string;
+  formatted?: string;
+}
+
 /** A single activity node as returned by {@link PRODUCTS_QUERY}. */
 export interface ActivityNode {
   name: string;
@@ -32,7 +51,11 @@ export interface ActivityNode {
   type: string;
   colorHex: string;
   currency?: string;
-  resourceOptions: Array<{ id: string; name: string }>;
+  resourceOptions: Array<{
+    id: string;
+    name: string;
+    priceRange?: { min?: RawMoneyNode | null; max?: RawMoneyNode | null } | null;
+  }>;
 }
 
 /** The `data` payload of {@link PRODUCTS_QUERY}. */
diff --git a/src/models/peek/pricing.ts b/src/models/peek/pricing.ts
@@ -28,6 +28,16 @@ export interface PricingMoney {
   amount: string;
   /** ISO 4217 currency code (e.g. `"USD"`). */
   currency: string;
+  /**
+   * Human-formatted display string for the amount (e.g. `"$50.00"`), as
+   * rendered by the Peek gateway.
+   *
+   * Populated on values **read back** from the gateway (resolved overrides,
+   * product ticket price ranges). It is optional and purely informational —
+   * omit it when *building* an override input; the gateway derives it from
+   * `amount`/`currency`.
+   */
+  displayPrice?: string;
 }
 
 /** An `{ id, name }` reference to a Peek entity echoed back in a response. */
diff --git a/src/models/peek/product.ts b/src/models/peek/product.ts
@@ -5,6 +5,7 @@
  * decoupled from the underlying Peek GraphQL schema — the raw GraphQL types and
  * the conversion logic live inside the package and are never exposed here.
  */
+import type { PricingMoney } from "./pricing.js";
 
 /**
  * A bookable product in a Peek Pro account.
@@ -70,6 +71,20 @@ export interface ProductTicket {
   id: string;
   /** Human-readable name of the ticket / option. */
   name: string;
+  /**
+   * Lowest price this ticket can be sold at, across its price range.
+   *
+   * Populated for activity/rental resource options that expose a price range;
+   * `null` for add-on options (which carry no range) and when Peek reports none.
+   */
+  minPrice: PricingMoney | null;
+  /**
+   * Highest price this ticket can be sold at, across its price range.
+   *
+   * Populated for activity/rental resource options that expose a price range;
+   * `null` for add-on options (which carry no range) and when Peek reports none.
+   */
+  maxPrice: PricingMoney | null;
 }
 
 /** {@link Product.type} for standard bookable activities. */
diff --git a/test/peek/pricing/pricing-converter.test.ts b/test/peek/pricing/pricing-converter.test.ts
@@ -20,7 +20,9 @@ describe("fromActivityContexts", () => {
             resourceOptions: [
               {
                 resourceOption: { id: "r1", name: "Adult" },
-                override: { price: { amount: "80.00", currency: "USD" } },
+                override: {
+                  price: { amount: "80.00", currency: "USD", formatted: "$80.00" },
+                },
               },
             ],
             filters: [
@@ -60,7 +62,10 @@ describe("fromActivityContexts", () => {
             resourceOptions: [
               {
                 resourceOption: { id: "r1", name: "Adult" },
-                override: { mode: "fixed", price: { amount: "80.00", currency: "USD" } },
+                override: {
+                  mode: "fixed",
+                  price: { amount: "80.00", currency: "USD", displayPrice: "$80.00" },
+                },
               },
             ],
             filters: [
diff --git a/test/peek/pricing/pricing-service.test.ts b/test/peek/pricing/pricing-service.test.ts
@@ -312,6 +312,41 @@ describe("PricingService.upsertOverrides", () => {
     });
   });
 
+  it("strips a caller-supplied displayPrice from the fixed-price wire input", async () => {
+    const { fetchFn, calls } = makeFetch(() => upsertSuccess());
+
+    await new PricingService(buildClient(fetchFn)).upsertOverrides({
+      engineId: "eng-1",
+      dateRange: "[2025-07-04,2025-07-04]",
+      activities: [
+        {
+          activityId: "act-1",
+          overrides: [
+            {
+              order: 0,
+              resourceOptions: [
+                {
+                  id: "r1",
+                  mode: "fixed",
+                  price: { amount: "80.00", currency: "USD", displayPrice: "$80.00" },
+                },
+              ],
+              filters: [],
+            },
+          ],
+        },
+      ],
+    });
+
+    const sent = sentInput(calls) as {
+      activities: Array<{ overrides: Array<{ resourceOptions: unknown[] }> }>;
+    };
+    expect(sent.activities[0]!.overrides[0]!.resourceOptions[0]).toEqual({
+      id: "r1",
+      price: { amount: "80.00", currency: "USD" },
+    });
+  });
+
   it("returns the resolved activity contexts", async () => {
     const { fetchFn } = makeFetch(() =>
       upsertSuccess([
diff --git a/test/peek/products/product-converter.test.ts b/test/peek/products/product-converter.test.ts
diff --git a/test/peek/products/product-service.test.ts b/test/peek/products/product-service.test.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@peektravel/app-utilities",`
`3`		`- "version": "0.5.1",`
	`3`	`+ "version": "0.5.2",`
`4`	`4`	`"description": "GraphQL JS mapping utilities extracted from the Peek Pro Autopilot connector.",`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"repository": {`