@v-office/website-sdk 2.12.0 → 2.13.0

package/instructions/search.md

@@ -77,6 +77,28 @@ Common stable query keys:
 - Occupancy: `adults`, `children`, `childrenAges`, `babies`, `pets`, `petsCount`.
 - Filters: use `searchParameterQueryKey` values from `sdk.static.filter.getFilters(...)`.
 
+### Static Backend Capabilities
+
+Search capabilities that only depend on a backend name are available without
+constructing an SDK:
+
+```ts
+import {
+  getSupportedPeriodQueryKeys,
+  supportsFlexiblePeriodSearch,
+} from "@v-office/website-sdk/capabilities/search";
+
+supportsFlexiblePeriodSearch("v9"); // false
+supportsFlexiblePeriodSearch("v10"); // true
+
+getSupportedPeriodQueryKeys("v9").has("month"); // false
+getSupportedPeriodQueryKeys("v10").has("month"); // true
+```
+
+The returned read-only set contains the stable period query keys accepted by the
+selected backend, including aliases such as `from` and `till`. Key support does
+not replace validation of complete query combinations.
+
 ## Query Structure
 
 The `query` field is a URL query-string style value without a leading `?`.

package/instructions/versions/2.13.0/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog: 2.13.0
+
+This release adds static backend search capability discovery and replaces the
+ambiguous flat booking payment schedule with a shared, presentation-ready payment
+model for v9 and v10. It preserves every known remaining payment step, separates
+contractual steps from full-payment alternatives, and keeps backend credentials
+out of the public booking output.
+
+## Added
+
+- `@v-office/website-sdk/capabilities/search` exposes pure, instance-independent
+  helpers for checking flexible-period support and the supported period query keys
+  for a backend.
+- `BookingOutput.payment.schedule` contains the remaining contractual payment
+  steps known after booking.
+- `BookingOutput.payment.alternatives` contains optional ways to settle the
+  complete outstanding balance.
+- Schedule entries have a stable `kind`: `prepayment`, `remaining_payment`,
+  `installment`, or `deposit`.
+- Full-payment alternatives use `kind: "full_amount"`.
+- v10 booking output includes all remaining online, on-site, and external payment
+  steps instead of exposing only the next online step.
+- v10 schedule entries can include translated `paymentAt` text derived from the
+  backend payment location and recipient.
+- Legacy v9 now preserves its independently supplied remaining-payment amount and
+  deadline.
+
+## Changed
+
+- `dueOn` is now a complete translated, long-form display string such as
+  `Zahlbar bis zum 6. Februar 2027`.
+- Schedule and alternative amounts use the `amount` field and remain
+  locale-formatted display strings.
+- `paymentOptions` is present on a schedule entry only when the SDK can currently
+  perform that payment. Informational future, on-site, and external steps remain
+  visible without payment options.
+- A synthesized v9 full-payment alternative no longer copies the prepayment
+  deadline. An explicit backend total deadline can still be retained.
+- v10 initializes Adyen only for the next payable online step and the
+  full-outstanding alternative.
+- v9 initializes Stripe only for currently payable choices.
+- Post-booking insurance now receives the opaque booking result:
+
+  ```ts
+  await sdk.live.quote.bookInsurance({ quote, booking });
+  ```
+
+## Removed
+
+- `BookingOutput.paymentSchedules`
+- Public `BookingOutput.guestToken`
+- ISO-like or locale-short date assumptions for booking payment output
+
+The private v9 guest token remains attached to the live opaque booking object and
+is used internally when completing insurance. It is not enumerable or
+serializable.
+
+## Backend Mapping
+
+- v9 `prepayment` becomes `kind: "prepayment"`.
+- v9 `rest` becomes `kind: "remaining_payment"`.
+- v9 `total` becomes a `full_amount` alternative.
+- v10 `INSTALLMENT` becomes `kind: "installment"`.
+- v10 `DEPOSIT` becomes `kind: "deposit"`.
+- v10 `financials.outstanding` becomes a `full_amount` alternative when it is a
+  distinct payable choice.
+
+## Migration Impact
+
+This is a breaking output and insurance-input change. Consumers must:
+
+1. Replace reads of `paymentSchedules` with `payment.schedule` and
+   `payment.alternatives`.
+2. Read `amount` instead of the former schedule `total`.
+3. Treat schedule `paymentOptions` as optional.
+4. Render `dueOn`, `paymentAt`, labels, amounts, and line amounts directly without
+   reparsing or reformatting them.
+5. Pass the live `booking` object to `bookInsurance` instead of passing
+   `bookingNumber` and `guestToken`.
+6. Keep the booking object in memory until optional v9 insurance booking is
+   complete; private credentials do not survive JSON serialization.
+
+The search capability API is additive. Consumers with hardcoded backend period-key
+tables can replace them with the new helpers.
+
+See `versions/2.13.0/MIGRATION.md`, `../../search.md`, `../../booking.md`, and
+`../../quote.md`.

package/instructions/versions/2.13.0/MIGRATION.md

@@ -0,0 +1,315 @@
+# Migration: 2.12.0 to 2.13.0
+
+2.13.0 introduces a breaking, shared booking-payment output for v9 and v10. The
+new model is intentionally presentation-oriented: labels, amounts, deadlines,
+payment locations, and breakdown lines are already translated and formatted for
+the booking locale.
+
+## 1. Replace the Flat Payment Schedule
+
+Before 2.13.0:
+
+```ts
+booking.paymentSchedules;
+```
+
+From 2.13.0:
+
+```ts
+booking.payment.schedule;
+booking.payment.alternatives;
+```
+
+`payment.schedule` contains contractual payment steps. `payment.alternatives`
+contains distinct alternatives such as paying the complete outstanding balance.
+
+Example:
+
+```json
+{
+  "bookingNumber": "B-2026-0001",
+  "payment": {
+    "schedule": [
+      {
+        "kind": "prepayment",
+        "label": "Anzahlung",
+        "amount": "76,00 €",
+        "dueOn": "Zahlbar bis zum 19. August 2026",
+        "paymentOptions": [
+          {
+            "kind": "bank_transfer",
+            "label": "Überweisung",
+            "holder": "Ferienvermietung Muster GmbH",
+            "iban": "DE02 1203 0000 0000 2020 51",
+            "remittanceText": "Buchungsnummer: B-2026-0001"
+          }
+        ]
+      },
+      {
+        "kind": "remaining_payment",
+        "label": "Restzahlung",
+        "amount": "304,00 €",
+        "dueOn": "Zahlbar bis zum 6. Februar 2027"
+      }
+    ],
+    "alternatives": [
+      {
+        "kind": "full_amount",
+        "label": "Gesamtzahlung",
+        "amount": "380,00 €",
+        "paymentOptions": [
+          {
+            "kind": "bank_transfer",
+            "label": "Überweisung",
+            "holder": "Ferienvermietung Muster GmbH",
+            "iban": "DE02 1203 0000 0000 2020 51",
+            "remittanceText": "Buchungsnummer: B-2026-0001"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## 2. Read `amount` Instead of `total`
+
+The old schedule-level `total` field has been renamed to `amount`:
+
+```ts
+for (const entry of booking.payment.schedule) {
+  renderAmount(entry.amount);
+}
+```
+
+The value remains a localized display string. Do not parse it for arithmetic or
+payment initiation.
+
+Optional `lines` continue to contain translated labels and formatted amounts:
+
+```ts
+for (const line of entry.lines ?? []) {
+  renderBreakdownLine(line.label, line.amount);
+}
+```
+
+## 3. Render Schedule and Alternative Entries
+
+To render every payment entry:
+
+```ts
+const paymentEntries = [...booking.payment.schedule, ...booking.payment.alternatives];
+
+for (const entry of paymentEntries) {
+  renderPaymentEntry(entry);
+}
+```
+
+Use the stable `kind` only for programmatic behavior. Use `label` for visible
+text.
+
+Schedule kinds:
+
+- `prepayment`: a named v9 down payment.
+- `remaining_payment`: a named v9 remaining payment.
+- `installment`: a v10 installment step.
+- `deposit`: a v10 deposit step.
+
+Alternative kinds:
+
+- `full_amount`: settle the complete currently outstanding balance.
+
+Do not infer v9 semantics from v10 step order. A v10 installment is not
+automatically a prepayment or remaining payment.
+
+## 4. Treat `paymentOptions` as Capability Data
+
+`paymentOptions` is optional on scheduled steps. Its absence means the entry is
+informational and is not currently payable through the SDK.
+
+```ts
+for (const option of entry.paymentOptions ?? []) {
+  if (option.kind === "bank_transfer") {
+    renderBankTransfer(option);
+  } else {
+    renderSubmitButton(() => sdk.live.booking.submitPaymentOption(option));
+  }
+}
+```
+
+Do not attach payment buttons to future, on-site, or external entries merely
+because they appear in `payment.schedule`.
+
+`full_amount` alternatives always contain a `paymentOptions` array. The array can
+be empty when the backend supplies no executable method.
+
+## 5. Render Dates and Payment Locations Directly
+
+Before 2.13.0, `dueOn` was locale-short text even though older documentation
+showed an ISO value. Consumers sometimes attempted to parse it as
+`YYYY-MM-DD`.
+
+From 2.13.0, `dueOn` is a complete localized phrase:
+
+```text
+Zahlbar bis zum 6. Februar 2027
+Payable until February 6, 2027
+```
+
+Render it directly:
+
+```ts
+if (entry.dueOn) renderSupportingText(entry.dueOn);
+if (entry.paymentAt) renderSupportingText(entry.paymentAt);
+```
+
+Do not prepend another due-date label and do not parse or reformat these fields.
+`paymentAt` is currently populated by v10 when payment-step location information
+is available.
+
+## 6. Account for the Corrected v9 Schedule
+
+Legacy v9 now emits both authoritative contractual steps:
+
+- `prepayment` with its own amount and deadline.
+- `remaining_payment` with its own amount and deadline.
+
+The `full_amount` alternative is separate. When the SDK synthesizes it from
+prepayment plus remaining payment, it has no deadline. The SDK no longer copies
+the prepayment deadline onto that alternative.
+
+Consequently, code must not derive a remaining-payment deadline from
+`payment.alternatives`.
+
+## 7. Account for the Expanded v10 Schedule
+
+v10 now preserves all remaining backend payment steps in
+`payment.schedule`, including:
+
+- `ONLINE`
+- `ON_SITE`
+- `EXTERN`
+
+Only the next eligible online step receives an initialized Adyen option. Later
+steps remain available as informational entries. The complete outstanding amount
+can appear separately under `payment.alternatives`.
+
+The alternative amount is the current outstanding balance, not necessarily the
+original booking total.
+
+## 8. Migrate Post-Booking Insurance
+
+Before 2.13.0:
+
+```ts
+await sdk.live.quote.bookInsurance({
+  quote,
+  bookingNumber: booking.bookingNumber,
+  guestToken: booking.guestToken,
+});
+```
+
+From 2.13.0:
+
+```ts
+await sdk.live.quote.bookInsurance({
+  quote,
+  booking,
+});
+```
+
+`guestToken` is no longer public. For v9, it is stored as private state on the
+opaque booking object and consumed internally by the SDK.
+
+Keep the same live booking object until insurance booking is complete:
+
+```ts
+const booking = await sdk.live.booking.book(input);
+
+// Do not JSON round-trip `booking` before this call.
+const insurance = await sdk.live.quote.bookInsurance({ quote, booking });
+```
+
+Spreading, serializing, reconstructing, or transferring the booking object loses
+its private backend context. If the application must cross a page reload or
+process boundary, complete insurance before that boundary.
+
+## 9. Update Payment-Option Selection
+
+Before 2.13.0:
+
+```ts
+const option = booking.paymentSchedules[0]?.paymentOptions.find(
+  (candidate) => candidate.kind !== "bank_transfer",
+);
+```
+
+From 2.13.0:
+
+```ts
+const option = [...booking.payment.schedule, ...booking.payment.alternatives]
+  .flatMap((entry) => entry.paymentOptions ?? [])
+  .find((candidate) => candidate.kind !== "bank_transfer");
+```
+
+Continue passing the selected structured option unchanged to
+`submitPaymentOption`.
+
+## 10. Handle Optional Insurance Output
+
+`insurancePaymentOptions` is omitted when no post-booking insurance payment is
+available:
+
+```ts
+for (const option of booking.insurancePaymentOptions ?? []) {
+  renderInsurancePaymentOption(option);
+}
+```
+
+This keeps v10 and bookings without selected insurance minimal.
+
+## 11. Replace Hardcoded Search Capability Tables
+
+This migration is optional and additive. Search UI that needs to decide which
+period controls to render can query backend support without constructing an SDK:
+
+```ts
+import {
+  getSupportedPeriodQueryKeys,
+  supportsFlexiblePeriodSearch,
+  type BackendKind,
+} from "@v-office/website-sdk/capabilities/search";
+
+const shouldRenderFlexiblePeriod = (backend: BackendKind) => supportsFlexiblePeriodSearch(backend);
+
+const supportedPeriodKeys = getSupportedPeriodQueryKeys("v9");
+supportedPeriodKeys.has("month"); // false
+```
+
+Remove local v9/v10 period-key tables in favor of these helpers. Both helpers are
+derived from the same core definitions used by SDK search parsing, so backend
+support changes do not require consumers to update a copied matrix.
+
+The returned `ReadonlySet` includes supported aliases such as `from`, `till`,
+`nights_min`, and `nights_max`. It describes individual key support; normal
+search validation still determines whether a complete combination of keys and
+values is executable.
+
+## Recommended Verification
+
+1. Book a v9 reservation with distinct prepayment and remaining-payment dates.
+2. Confirm both entries retain their own translated long-form deadline.
+3. Confirm a synthesized v9 `full_amount` alternative has no deadline.
+4. Confirm future v9 remaining payment has no payment button unless the SDK
+   supplies a payment option.
+5. Book a v10 reservation with multiple online and on-site/external payment steps.
+6. Confirm every remaining v10 step is rendered in backend order.
+7. Confirm only the next payable online step has an Adyen option.
+8. Confirm the full-payment alternative displays the outstanding balance without
+   an inferred deadline.
+9. Render both supported locales and verify all amounts, dates, locations, labels,
+   and breakdown lines are presentation-ready.
+10. Complete v9 insurance with the live booking object and verify the private
+    credential is not present in serialized output.
+11. If replacing a local search capability table, confirm flexible-period controls
+    remain hidden for v9 and visible for v10.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v-office/website-sdk",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "Website-facing SDK facade backed by @v-office/sdk-core",
   "bin": {
     "website-sdk": "./dist/cli.mjs"
@@ -33,6 +33,7 @@
   },
   "exports": {
     ".": "./dist/index.mjs",
+    "./capabilities/*": "./dist/capabilities/*.mjs",
     "./cli": "./dist/cli.mjs",
     "./package.json": "./package.json"
   },
@@ -41,7 +42,7 @@
   },
   "dependencies": {
     "@graphql-typed-document-node/core": "3.2.0",
-    "@v-office/sdk-core": "^1.12.0",
+    "@v-office/sdk-core": "^1.13.0",
     "effect": "4.0.0-beta.85",
     "graphql": "17.0.2",
     "yaml": "^2.9.0"