@v-office/website-sdk 2.11.0 → 2.13.0

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/instructions/versions/2.5.0/MIGRATION.md

@@ -124,6 +124,9 @@ The public output type is unchanged, but v10 search cards now reflect the REST p
 Starting with 2.11.0, priced v10 items and alternative periods may also include
 optional localized `discount` details. See `../../search.md`.
 
+Starting with 2.12.0, legacy v9 maps the same optional shape from its aggregated
+original total and discount name when the original total exceeds the final total.
+
 ## Backend Behavior
 
 - Fixed-period and flexible searches are priced by the REST backend; occupancy is required for priced searches.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v-office/website-sdk",
-  "version": "2.11.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,21 +42,23 @@
   },
   "dependencies": {
     "@graphql-typed-document-node/core": "3.2.0",
-    "@v-office/sdk-core": "^1.11.0",
+    "@v-office/sdk-core": "^1.13.0",
     "effect": "4.0.0-beta.85",
-    "graphql": "16.14.2",
+    "graphql": "17.0.2",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@effect/language-service": "0.86.2",
-    "@graphql-codegen/cli": "7.1.3",
-    "@graphql-codegen/client-preset": "6.0.1",
-    "@types/node": "26.0.0",
-    "@typescript/native-preview": "7.0.0-dev.20260622.1",
-    "oxfmt": "0.55.0",
-    "oxlint": "1.70.0",
-    "tsdown": "0.22.3",
-    "typescript": "6.0.3"
+    "@effect/tsgo": "0.31.0",
+    "@graphql-codegen/cli": "7.2.0",
+    "@graphql-codegen/client-preset": "6.1.1",
+    "@types/node": "26.1.2",
+    "oxfmt": "0.62.0",
+    "oxlint": "1.77.0",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2"
+  },
+  "engines": {
+    "node": "^22.0.0 || ^24.0.0 || ^25.0.0 || >=26.0.0"
   },
   "scripts": {
     "p": "pnpm run playground:json",
@@ -72,7 +75,7 @@
     "lint:fix": "oxlint --fix .",
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
-    "check": "pnpm run typecheck && pnpm run lint",
+    "check": "pnpm run typecheck && pnpm run lint && pnpm run fmt:check",
     "test": "pnpm run build && node --test test/*.test.mjs",
     "playground:custom-attributes": "pnpm run build && node --env-file=.env playground/custom-attributes.ts"
   }