@grupolapa/desarrollos-sdk 0.1.0 → 0.3.1

package/README.md

@@ -13,18 +13,65 @@ npm install @grupolapa/desarrollos-sdk
 pnpm add @grupolapa/desarrollos-sdk
 ```
 
+## API Discovery Endpoints
+
 The public API base URL is:
 
 ```txt
 https://grupolapa.com/api/public/v1/desarrollos
 ```
 
-Agent-readable integration instructions are available at:
+Agents can fetch integration instructions, endpoint descriptions, auth rules,
+and copy-paste examples from:
 
 ```txt
 https://grupolapa.com/api/public/v1/desarrollos/agent.json
 ```
 
+OpenAPI metadata is available at:
+
+```txt
+https://grupolapa.com/api/public/v1/desarrollos/openapi.json
+```
+
+Building a partner website that hosts the configurable cotizador? Read this
+single self-contained guide; it needs no other document:
+
+```txt
+https://grupolapa.com/api/public/v1/desarrollos/partner-agent.json
+```
+
+It covers environment setup, the journey call order, every error code, the
+frozen UONDR embed protocol `1.0` contract, and the host page requirements.
+
+Maintaining UONDR itself uses the cross-project contract reference:
+
+```txt
+https://grupolapa.com/api/public/v1/desarrollos/uondr-agent.json
+```
+
+## Embed Protocol
+
+`@grupolapa/desarrollos-sdk/embed` carries the iframe contract shared with
+UONDR. `UONDR_EMBED_PROTOCOL_CONTRACT` is a frozen literal mirrored
+byte-for-byte in the UONDR repository and verified by contract tests in both;
+`UONDR_EMBED_PROTOCOL_CONTRACT_DIGEST` lets a consumer confirm it matches the
+deployed guide.
+
+```ts
+import {
+  createUondrCommand,
+  postUondrCommand,
+  UondrEventGuard,
+  UONDR_EMBED_PROTOCOL_CONTRACT,
+  UONDR_EMBED_PROTOCOL_CONTRACT_DIGEST,
+} from "@grupolapa/desarrollos-sdk/embed";
+```
+
+Never post to a wildcard target origin. Derive it from the `embedUrl` Lapa
+returns, and note that the configurator resolves its parent origin from
+`document.referrer`, so the host page must not send a strict `Referrer-Policy`.
+
 ## Browser Reads and Quotes
 
 ```ts
@@ -79,6 +126,96 @@ const quote =
     : null;
 ```
 
+## Browser Journey Flow
+
+The journey client is browser-only and does not accept a Lapa API key. Create a
+journey with the integration's publishable key, then authenticate every
+journey-scoped call with the returned opaque token. The optional token on
+`createJourney` resumes the same journey when it is still valid.
+
+```ts
+import { createDesarrollosClient } from "@grupolapa/desarrollos-sdk";
+
+const client = createDesarrollosClient({
+  baseUrl: "https://grupolapa.com/api/public/v1/desarrollos",
+});
+
+const created = await client.createJourney({
+  integrationKey: "lapa_partner_public_key",
+});
+
+const journeyId = created.journey.id;
+const journeyToken = created.journeyToken;
+
+await client.updateJourneySelection({
+  journeyId,
+  journeyToken,
+  selection: { unitId: "unit_1" },
+});
+
+const { session } = await client.createJourneyConfiguratorSession({
+  journeyId,
+  journeyToken,
+});
+
+// Mount session.embedUrl in the UONDR iframe and wait for its completed event.
+await client.completeJourneyConfiguration({
+  journeyId,
+  journeyToken,
+  configuration: {
+    configurationId: "configuration_01",
+    revision: 1,
+    hash: "sha256-canonical-configuration-hash",
+  },
+});
+
+const quotedJourney = await client.createJourneyQuote({
+  journeyId,
+  journeyToken,
+});
+
+// Always render the authoritative quote returned by Lapa.
+const quote = quotedJourney.quote;
+
+await client.updateJourneyLead({
+  journeyId,
+  journeyToken,
+  lead: {
+    name: "Ada Lovelace",
+    phone: "+529991234567",
+    email: "ada@example.com",
+  },
+});
+
+const turnstileToken = "token-returned-by-the-turnstile-widget";
+const checkoutJourney = await client.createJourneyCheckout({
+  journeyId,
+  journeyToken,
+  checkout: {
+    idempotencyKey: crypto.randomUUID(),
+    turnstileToken,
+    payment: {
+      provider: "stripe",
+      returnUrl: "https://partner.example.com/confirmation",
+    },
+  },
+});
+
+if (checkoutJourney.checkout?.checkoutUrl) {
+  window.location.assign(checkoutJourney.checkout.checkoutUrl);
+}
+```
+
+Persist only the versioned opaque `journeyToken` in browser storage. Keep PII,
+configuration snapshots, quote amounts, and payment-provider data out of local
+storage. Visible step and unit state can live in URL search parameters; tokens
+and prices must not.
+
+Journey mutations return the authoritative aggregate journey state, including
+configuration, quote, hold, checkout, payment-conflict, and draft-operation
+status. Client quote helpers remain provisional and must not replace the Lapa
+quote returned by `createJourneyQuote`.
+
 ## Trusted Server Flow
 
 Keep `lapa_dev_<prefix>_<secret>` API keys on a server. Use the trusted server
@@ -145,7 +282,7 @@ if (map) {
 ## Exports
 
 - `@grupolapa/desarrollos-sdk`: browser-safe client, public types, and
-  `DesarrollosApiError`.
+  `DesarrollosApiError`, including the token-authenticated journey methods.
 - `@grupolapa/desarrollos-sdk/server`: trusted server API-key client.
 - `@grupolapa/desarrollos-sdk/quote`: quote, selection, payment, inventory,
   formatting, Entrada/action, and product helpers.

package/dist/calculate-quote.js

@@ -1,6 +1,7 @@
 import { getFinanceRulesRentalRateForUnit, getUnitEstimatedRentalAnnualMXN, getUnitEstimatedRentalMonthlyMXN, getUnitDeliveryMonths, getUnitListPriceMXN, isCashbackScheme, isInstallmentScheme, MAX_CASHBACK_MONTHS, } from "./payment-schemes.js";
 import { getInstallmentAllocation, getInstallmentDiscountPct, INSTALLMENT_DEFAULT_DOWN_PAYMENT_PCT, INSTALLMENT_DEFAULT_MONTHLY_PCT, } from "./installment-allocation.js";
 import { getEscalatedAnnualAmountMXN, isCorporateRentalUnit, } from "./corporate-rent.js";
+import { CASHBACK_PAYMENT_OPTION_STAGED, normalizeCashbackPaymentOptionId, UONDR_CASHBACK_STAGED_COMPLETED_RATE, UONDR_CASHBACK_STAGED_DELIVERY_PCT, UONDR_CASHBACK_STAGED_DOWN_PAYMENT_PCT, UONDR_CASHBACK_STAGED_INITIAL_RATE, UONDR_CASHBACK_STAGED_MONTHLY_COUNT, UONDR_CASHBACK_STAGED_MONTHLY_PAYMENT_PCT, UONDR_CASHBACK_STAGED_MONTHLY_PCT, } from "./cashback-payment-options.js";
 import { applyIvaModeMXN } from "./tax.js";
 function getVisibleTimelineRows(rows, deferredPaymentMonths, deliveryMonths, isCashback, cashbackMonths) {
     const visibleMonths = new Set([
@@ -35,33 +36,49 @@ export function calculateQuote(unit, input, scheme, rules) {
         ? Math.min(deliveryMonths, MAX_CASHBACK_MONTHS)
         : 0;
     const isCashbackCapped = isCashback && cashbackMonths < deliveryMonths;
+    const preDeliveryPaymentMonths = Math.max(deliveryMonths - 1, 0);
+    const cashbackPaymentOption = normalizeCashbackPaymentOptionId(input.cashbackPaymentOption);
+    const isStagedCashback = isCashback && cashbackPaymentOption === CASHBACK_PAYMENT_OPTION_STAGED;
+    const stagedCashbackMonthlyPaymentCount = isStagedCashback
+        ? Math.min(UONDR_CASHBACK_STAGED_MONTHLY_COUNT, preDeliveryPaymentMonths)
+        : 0;
+    const stagedCashbackMonthlyPaymentPct = stagedCashbackMonthlyPaymentCount *
+        UONDR_CASHBACK_STAGED_MONTHLY_PAYMENT_PCT;
+    const stagedCashbackMonthlyPctRolledToDelivery = isStagedCashback
+        ? UONDR_CASHBACK_STAGED_MONTHLY_PCT - stagedCashbackMonthlyPaymentPct
+        : 0;
     const installmentAllocation = isInstallmentScheme(scheme)
         ? getInstallmentAllocation(input.installmentDownPaymentPct ?? INSTALLMENT_DEFAULT_DOWN_PAYMENT_PCT, input.installmentMonthlyPct ?? INSTALLMENT_DEFAULT_MONTHLY_PCT)
         : null;
     const downPaymentPct = isCashback
-        ? input.downPaymentPct
+        ? isStagedCashback
+            ? UONDR_CASHBACK_STAGED_DOWN_PAYMENT_PCT
+            : input.downPaymentPct
         : (installmentAllocation?.downPaymentPct ?? 0);
     const downPaymentAmountMXN = listPriceMXN * (downPaymentPct / 100);
     const balanceAmountMXN = listPriceMXN - downPaymentAmountMXN;
-    const cashbackMonthlyMXN = isCashback
-        ? (downPaymentAmountMXN * scheme.cashbackRate) / 12
-        : 0;
-    const cashbackTotalMXN = cashbackMonthlyMXN * cashbackMonths;
     const rawMonthlyPaymentPct = installmentAllocation?.monthlyPct ?? 0;
     const rawDeferredPaymentPct = installmentAllocation?.deferredPct ?? 0;
-    const preDeliveryPaymentMonths = Math.max(deliveryMonths - 1, 0);
     const deferredPaymentsCount = installmentAllocation && rawDeferredPaymentPct > 0
         ? Math.floor(preDeliveryPaymentMonths / 12)
         : 0;
     const deferredPaymentMonths = Array.from({ length: deferredPaymentsCount }, (_, index) => (index + 1) * 12);
     const deferredPaymentMonthSet = new Set(deferredPaymentMonths);
-    const monthlyPaymentMonths = installmentAllocation && rawMonthlyPaymentPct > 0
-        ? Array.from({ length: preDeliveryPaymentMonths }, (_, index) => index + 1).filter((month) => !deferredPaymentMonthSet.has(month))
-        : [];
+    const monthlyPaymentMonths = isStagedCashback
+        ? Array.from({ length: stagedCashbackMonthlyPaymentCount }, (_, index) => index + 1)
+        : installmentAllocation && rawMonthlyPaymentPct > 0
+            ? Array.from({ length: preDeliveryPaymentMonths }, (_, index) => index + 1).filter((month) => !deferredPaymentMonthSet.has(month))
+            : [];
     const monthlyPaymentCount = monthlyPaymentMonths.length;
     const monthlyPaymentMonthSet = new Set(monthlyPaymentMonths);
-    const monthlyPaymentPct = monthlyPaymentCount > 0 ? rawMonthlyPaymentPct : 0;
-    const monthlyPctRolledToDelivery = rawMonthlyPaymentPct - monthlyPaymentPct;
+    const monthlyPaymentPct = isStagedCashback
+        ? stagedCashbackMonthlyPaymentPct
+        : monthlyPaymentCount > 0
+            ? rawMonthlyPaymentPct
+            : 0;
+    const monthlyPctRolledToDelivery = isStagedCashback
+        ? stagedCashbackMonthlyPctRolledToDelivery
+        : rawMonthlyPaymentPct - monthlyPaymentPct;
     const monthlyPaymentTotalMXN = listPriceMXN * (monthlyPaymentPct / 100);
     const monthlyPaymentAmountMXN = monthlyPaymentCount > 0 ? monthlyPaymentTotalMXN / monthlyPaymentCount : 0;
     const deferredPaymentPct = deferredPaymentsCount > 0 ? rawDeferredPaymentPct : 0;
@@ -74,10 +91,36 @@ export function calculateQuote(unit, input, scheme, rules) {
         ? installmentAllocation.deliveryPct +
             monthlyPctRolledToDelivery +
             deferredPctRolledToDelivery
-        : 100 - downPaymentPct;
+        : isStagedCashback
+            ? UONDR_CASHBACK_STAGED_DELIVERY_PCT + monthlyPctRolledToDelivery
+            : 100 - downPaymentPct;
     const deliveryPaymentAmountMXN = installmentAllocation
         ? listPriceMXN * (deliveryPaymentPct / 100)
-        : balanceAmountMXN;
+        : isStagedCashback
+            ? listPriceMXN * (deliveryPaymentPct / 100)
+            : balanceAmountMXN;
+    function getCashbackForMonthMXN(month) {
+        if (!isCashback || month < 1 || month > cashbackMonths) {
+            return 0;
+        }
+        if (isStagedCashback) {
+            const rate = month <= UONDR_CASHBACK_STAGED_MONTHLY_COUNT
+                ? UONDR_CASHBACK_STAGED_INITIAL_RATE
+                : UONDR_CASHBACK_STAGED_COMPLETED_RATE;
+            const basePct = month <= UONDR_CASHBACK_STAGED_MONTHLY_COUNT
+                ? UONDR_CASHBACK_STAGED_DOWN_PAYMENT_PCT
+                : UONDR_CASHBACK_STAGED_DOWN_PAYMENT_PCT +
+                    UONDR_CASHBACK_STAGED_MONTHLY_PCT;
+            return (listPriceMXN * (basePct / 100) * rate) / 12;
+        }
+        return (downPaymentAmountMXN * scheme.cashbackRate) / 12;
+    }
+    const cashbackMonthlyMXN = isCashback
+        ? Math.max(...Array.from({ length: cashbackMonths }, (_, index) => getCashbackForMonthMXN(index + 1)), 0)
+        : 0;
+    const cashbackTotalMXN = isCashback
+        ? Array.from({ length: cashbackMonths }, (_, index) => getCashbackForMonthMXN(index + 1)).reduce((total, amount) => total + amount, 0)
+        : 0;
     const installmentDiscountPct = installmentAllocation
         ? getInstallmentDiscountPct(installmentAllocation.downPaymentPct)
         : 0;
@@ -99,6 +142,10 @@ export function calculateQuote(unit, input, scheme, rules) {
     const milestones = {};
     if (isCashback) {
         milestones[1] = rules.milestones.cashbackStart;
+        if (isStagedCashback &&
+            cashbackMonths > UONDR_CASHBACK_STAGED_MONTHLY_COUNT) {
+            milestones[UONDR_CASHBACK_STAGED_MONTHLY_COUNT + 1] = "Cashback 6%";
+        }
         milestones[Math.round(deliveryMonths / 2)] = rules.milestones.midpoint;
         if (isCashbackCapped) {
             milestones[cashbackMonths] = "Último cashback";
@@ -137,13 +184,18 @@ export function calculateQuote(unit, input, scheme, rules) {
         const assetValueMXN = listPriceMXN * Math.pow(1 + plusvaliaMonthlyRate, month);
         const plusvaliaDeltaMXN = assetValueMXN - previousAssetValueMXN;
         accumulatedPlusvaliaMXN += plusvaliaDeltaMXN;
-        const cashbackForMonthMXN = isCashback && month <= cashbackMonths ? cashbackMonthlyMXN : 0;
+        const cashbackForMonthMXN = getCashbackForMonthMXN(month);
         let paymentMXN = 0;
         let paymentLabel = "—";
         if (isCashback) {
+            const hasMonthlyPaymentForMonth = monthlyPaymentPct > 0 && monthlyPaymentMonthSet.has(month);
+            if (hasMonthlyPaymentForMonth) {
+                paymentMXN += adjustedMonthlyAmountMXN;
+                paymentLabel = "Mensualidad cashback";
+            }
             if (month === deliveryMonths) {
-                paymentMXN = balanceAmountMXN;
-                paymentLabel = "Saldo contra entrega";
+                paymentMXN += deliveryPaymentAmountMXN;
+                paymentLabel = `Saldo contra entrega ${deliveryPaymentPct}%`;
             }
         }
         else if (installmentAllocation) {
@@ -228,9 +280,18 @@ export function calculateQuote(unit, input, scheme, rules) {
                 valueMXN: -downPaymentAmountMXN,
                 tone: "negative",
             },
+            ...(monthlyPaymentPct > 0
+                ? [
+                    {
+                        label: `Mensualidades (${monthlyPaymentPct}%)`,
+                        valueMXN: -monthlyPaymentTotalMXN,
+                        tone: "negative",
+                    },
+                ]
+                : []),
             {
-                label: `Saldo contra entrega (${100 - downPaymentPct}%)`,
-                valueMXN: -balanceAmountMXN,
+                label: `Contra entrega (${deliveryPaymentPct}%)`,
+                valueMXN: -deliveryPaymentAmountMXN,
                 tone: "negative",
             },
             {
@@ -342,7 +403,11 @@ export function calculateQuote(unit, input, scheme, rules) {
     return {
         unit,
         scheme,
-        input,
+        input: {
+            ...input,
+            downPaymentPct,
+            cashbackPaymentOption,
+        },
         listPriceMXN,
         deliveryMonths,
         isCashback,

package/dist/cashback-payment-options.d.ts

@@ -0,0 +1,28 @@
+import type { CashbackPaymentOptionId, CashbackPaymentScheme, RangeRule } from "./types.js";
+export declare const CASHBACK_PAYMENT_OPTION_DIRECT = "direct";
+export declare const CASHBACK_PAYMENT_OPTION_STAGED = "staged";
+export declare const UONDR_CASHBACK_DIRECT_DOWN_PAYMENT_PCT = 60;
+export declare const UONDR_CASHBACK_DIRECT_MIN_DOWN_PAYMENT_PCT = 60;
+export declare const UONDR_CASHBACK_STAGED_DOWN_PAYMENT_PCT = 30;
+export declare const UONDR_CASHBACK_STAGED_MONTHLY_PCT = 30;
+export declare const UONDR_CASHBACK_STAGED_MONTHLY_COUNT = 6;
+export declare const UONDR_CASHBACK_STAGED_MONTHLY_PAYMENT_PCT: number;
+export declare const UONDR_CASHBACK_STAGED_DELIVERY_PCT = 40;
+export declare const UONDR_CASHBACK_STAGED_INITIAL_RATE = 0.04;
+export declare const UONDR_CASHBACK_STAGED_COMPLETED_RATE = 0.06;
+export declare const CASHBACK_PAYMENT_OPTIONS: readonly [{
+    readonly id: "direct";
+    readonly label: "8% - 60/40";
+    readonly name: "Cashback directo";
+    readonly description: "60% de enganche y 40% contra entrega.";
+}, {
+    readonly id: "staged";
+    readonly label: "4-6% 30/30/40";
+    readonly name: "Cashback por etapas";
+    readonly description: "30% de enganche, 30% en 6 meses y 40% contra entrega.";
+}];
+export declare function isCashbackPaymentOptionId(value: unknown): value is CashbackPaymentOptionId;
+export declare function normalizeCashbackPaymentOptionId(value: unknown): CashbackPaymentOptionId;
+export declare function getUondrCashbackDirectDownPaymentRange(scheme: CashbackPaymentScheme): RangeRule;
+export declare function getUondrCashbackOptionDownPaymentPct(scheme: CashbackPaymentScheme, optionId: CashbackPaymentOptionId, requestedPct?: number): number;
+export declare function getUondrCashbackOptionMonthlyPct(optionId: CashbackPaymentOptionId): 0 | 30;

package/dist/cashback-payment-options.js

@@ -0,0 +1,53 @@
+import { clampToRange } from "./payment-schemes.js";
+export const CASHBACK_PAYMENT_OPTION_DIRECT = "direct";
+export const CASHBACK_PAYMENT_OPTION_STAGED = "staged";
+export const UONDR_CASHBACK_DIRECT_DOWN_PAYMENT_PCT = 60;
+export const UONDR_CASHBACK_DIRECT_MIN_DOWN_PAYMENT_PCT = 60;
+export const UONDR_CASHBACK_STAGED_DOWN_PAYMENT_PCT = 30;
+export const UONDR_CASHBACK_STAGED_MONTHLY_PCT = 30;
+export const UONDR_CASHBACK_STAGED_MONTHLY_COUNT = 6;
+export const UONDR_CASHBACK_STAGED_MONTHLY_PAYMENT_PCT = UONDR_CASHBACK_STAGED_MONTHLY_PCT / UONDR_CASHBACK_STAGED_MONTHLY_COUNT;
+export const UONDR_CASHBACK_STAGED_DELIVERY_PCT = 40;
+export const UONDR_CASHBACK_STAGED_INITIAL_RATE = 0.04;
+export const UONDR_CASHBACK_STAGED_COMPLETED_RATE = 0.06;
+export const CASHBACK_PAYMENT_OPTIONS = [
+    {
+        id: CASHBACK_PAYMENT_OPTION_DIRECT,
+        label: "8% - 60/40",
+        name: "Cashback directo",
+        description: "60% de enganche y 40% contra entrega.",
+    },
+    {
+        id: CASHBACK_PAYMENT_OPTION_STAGED,
+        label: "4-6% 30/30/40",
+        name: "Cashback por etapas",
+        description: "30% de enganche, 30% en 6 meses y 40% contra entrega.",
+    },
+];
+export function isCashbackPaymentOptionId(value) {
+    return (value === CASHBACK_PAYMENT_OPTION_DIRECT ||
+        value === CASHBACK_PAYMENT_OPTION_STAGED);
+}
+export function normalizeCashbackPaymentOptionId(value) {
+    return isCashbackPaymentOptionId(value)
+        ? value
+        : CASHBACK_PAYMENT_OPTION_DIRECT;
+}
+export function getUondrCashbackDirectDownPaymentRange(scheme) {
+    return {
+        min: UONDR_CASHBACK_DIRECT_MIN_DOWN_PAYMENT_PCT,
+        max: Math.max(scheme.downPaymentRange.max, UONDR_CASHBACK_DIRECT_DOWN_PAYMENT_PCT),
+        step: scheme.downPaymentRange.step,
+    };
+}
+export function getUondrCashbackOptionDownPaymentPct(scheme, optionId, requestedPct) {
+    if (optionId === CASHBACK_PAYMENT_OPTION_STAGED) {
+        return UONDR_CASHBACK_STAGED_DOWN_PAYMENT_PCT;
+    }
+    return clampToRange(requestedPct ?? UONDR_CASHBACK_DIRECT_DOWN_PAYMENT_PCT, getUondrCashbackDirectDownPaymentRange(scheme));
+}
+export function getUondrCashbackOptionMonthlyPct(optionId) {
+    return optionId === CASHBACK_PAYMENT_OPTION_STAGED
+        ? UONDR_CASHBACK_STAGED_MONTHLY_PCT
+        : 0;
+}

package/dist/embed-protocol-contract.d.ts

@@ -0,0 +1,124 @@
+export declare const UONDR_EMBED_PROTOCOL_CONTRACT: {
+    readonly version: "1.0";
+    readonly frozenOn: "2026-07-26";
+    readonly owner: "uondr";
+    readonly summary: "Bidirectional postMessage contract between a partner website (host) and the UONDR configurator iframe. The host never calls a UONDR HTTP API; this channel plus the Lapa journey API is the entire integration surface.";
+    readonly sources: {
+        readonly hostCommand: "lapa.partner";
+        readonly configuratorEvent: "uondr.configurator";
+    };
+    readonly commandTypes: readonly ["initialize", "restrict_designs", "restore", "complete", "cancel"];
+    readonly eventTypes: readonly ["ready", "changed", "completed", "cancelled", "resize", "error"];
+    readonly commandEnvelope: {
+        readonly requiredKeys: readonly ["source", "protocolVersion", "sessionId", "type"];
+        readonly optionalKeys: readonly ["requestId", "payload"];
+        readonly unknownKeysRejected: true;
+    };
+    readonly eventEnvelope: {
+        readonly requiredKeys: readonly ["source", "protocolVersion", "sessionId", "sequence", "type"];
+        readonly optionalKeys: readonly ["configuration", "payload", "requestId"];
+        readonly unknownKeysRejected: false;
+    };
+    readonly limits: {
+        readonly sessionIdMaxLength: 256;
+        readonly requestIdMaxLength: 128;
+        readonly commandFingerprintMaxLength: 16384;
+        readonly commandHistoryMax: 256;
+        readonly earlyCommandQueueMax: 32;
+    };
+    readonly commands: {
+        readonly initialize: {
+            readonly order: "First command. Sent once, only after the ready event.";
+            readonly payload: {
+                readonly allowedDesignIds: readonly ["<stable-design-id>"];
+                readonly externalMode: true;
+                readonly hidePricing: true;
+            };
+            readonly rules: readonly ["externalMode and hidePricing must both be literal true.", "allowedDesignIds must be a non-empty array of unique, non-empty strings with no leading or trailing whitespace, and a subset of the session scope.", "A second initialize is rejected."];
+        };
+        readonly restrict_designs: {
+            readonly order: "After initialize. Narrows the visible design set.";
+            readonly payload: {
+                readonly allowedDesignIds: readonly ["<stable-design-id>"];
+            };
+            readonly rules: readonly ["allowedDesignIds must be a subset of the session scope; the configurator intersects rather than widens."];
+        };
+        readonly restore: {
+            readonly order: "After initialize, when Lapa reports an active configuration.";
+            readonly payload: {
+                readonly configuration: {
+                    readonly configurationId: "<stable-configuration-id>";
+                    readonly hash: "<canonical-hash>";
+                    readonly revision: 1;
+                };
+            };
+            readonly rules: readonly ["revision must be a safe integer >= 1 and strictly greater than the last accepted restore revision.", "configurationId and hash must be strings."];
+        };
+        readonly complete: {
+            readonly order: "After initialize, when the buyer confirms the configuration.";
+            readonly payload: {};
+            readonly rules: readonly ["The configurator persists an immutable revision and answers with a completed event."];
+        };
+        readonly cancel: {
+            readonly order: "After initialize. Terminal.";
+            readonly payload: {};
+            readonly rules: readonly ["The configurator accepts no further commands on this session."];
+        };
+    };
+    readonly events: {
+        readonly ready: {
+            readonly order: "Emitted unprompted at sequence 0 as soon as the session validates. Wait for it before sending initialize.";
+            readonly payload: {
+                readonly allowedDesignIds: readonly ["<stable-design-id>"];
+                readonly capabilities: {
+                    readonly commands: readonly ["initialize", "restrict_designs", "restore", "complete", "cancel"];
+                    readonly externalMode: true;
+                    readonly hidePricing: true;
+                };
+            };
+        };
+        readonly changed: {
+            readonly order: "Emitted on every buyer selection change after initialize.";
+            readonly payload: {
+                readonly designId: "<stable-design-id>";
+                readonly materialSelectionCount: 0;
+                readonly modifierSelectionCount: 0;
+            };
+            readonly rules: readonly ["Carries no monetary value. Never derive a price or total from this event."];
+        };
+        readonly completed: {
+            readonly order: "Emitted once in response to complete.";
+            readonly configuration: {
+                readonly configurationId: "<stable-configuration-id>";
+                readonly hash: "<canonical-hash>";
+                readonly revision: 1;
+            };
+            readonly rules: readonly ["Carries only the stable reference. Submit those three fields to Lapa; Lapa fetches and validates the immutable snapshot server-to-server.", "No snapshot, no internal identifier, and no pricing is exposed to the host."];
+        };
+        readonly cancelled: {
+            readonly order: "Emitted in response to cancel. Terminal.";
+            readonly payload: {
+                readonly reason: "<optional-reason-code>";
+            };
+        };
+        readonly resize: {
+            readonly order: "Emitted whenever the configurator content height changes.";
+            readonly payload: {
+                readonly height: 720;
+            };
+            readonly rules: readonly ["Apply to the iframe height. The configurator never resizes itself."];
+        };
+        readonly error: {
+            readonly order: "Emitted on a recoverable configurator failure.";
+            readonly payload: {
+                readonly code: "external_configurator_error";
+                readonly message: "<safe-buyer-facing-message>";
+                readonly retryable: true;
+            };
+        };
+    };
+    readonly hostRules: readonly ["Mount the embedUrl returned by Lapa unchanged. Never construct a UONDR URL yourself.", "Derive the target origin with new URL(embedUrl).origin and pass it to every postMessage. Never use '*'.", "Accept an event only when event.origin equals that origin, event.source is the iframe contentWindow, source is 'uondr.configurator', protocolVersion is '1.0', sessionId matches, and sequence is strictly greater than the last accepted sequence.", "The configurator resolves the parent origin from document.referrer and fails closed when it is absent. The host page must send a referrer: do not set Referrer-Policy to no-referrer, same-origin, origin-when-cross-origin, or strict-origin on the page that mounts the iframe.", "Send each command at most once. Duplicate command bodies and duplicate requestIds are dropped.", "Treat completed and cancelled as terminal; request a new session to configure again."];
+    readonly configuratorRules: readonly ["Accept a command only when event.origin equals the session parentOrigin and event.source is the parent window.", "Reject every command that arrives before initialize.", "Emit one monotonically increasing sequence per session, starting at 0.", "Hide every monetary amount, currency label, and financing surface in external mode.", "Fail closed on expired, revoked, cross-session, malformed, stale, or replayed input."];
+};
+export declare const UONDR_EMBED_PROTOCOL_CONTRACT_DIGEST = "sha256:f8c00ed49a9364a2f5b35d9073779767b744639e1b7d943ac669e60473080316";
+export declare function canonicalProtocolContractJson(): string;