@grupolapa/desarrollos-sdk 0.1.0

package/README.md

@@ -0,0 +1,154 @@
+# Desarrollos SDK
+
+Framework-agnostic TypeScript helpers for third-party websites that integrate
+with Grupo LAPA developments through the public API.
+
+## Installation
+
+```bash
+npm install @grupolapa/desarrollos-sdk
+```
+
+```bash
+pnpm add @grupolapa/desarrollos-sdk
+```
+
+The public API base URL is:
+
+```txt
+https://grupolapa.com/api/public/v1/desarrollos
+```
+
+Agent-readable integration instructions are available at:
+
+```txt
+https://grupolapa.com/api/public/v1/desarrollos/agent.json
+```
+
+## Browser Reads and Quotes
+
+```ts
+import { createDesarrollosClient } from "@grupolapa/desarrollos-sdk";
+import {
+  calculateQuote,
+  getResolvedSchemeForUnit,
+} from "@grupolapa/desarrollos-sdk/quote";
+import {
+  getSelectableUnitHotspots,
+  resolveInitialSitemapMap,
+} from "@grupolapa/desarrollos-sdk/sitemap";
+
+const client = createDesarrollosClient({
+  baseUrl: "https://grupolapa.com/api/public/v1/desarrollos",
+});
+
+const desarrolloKey = "viamare";
+const [{ snapshot }, inventory, sitemap, paymentMethods] = await Promise.all([
+  client.getSnapshot({ desarrolloKey }),
+  client.getInventory({ desarrolloKey }),
+  client.getSitemap({ desarrolloKey }),
+  client.getPaymentMethods({ desarrolloKey }),
+]);
+
+const map = resolveInitialSitemapMap(sitemap);
+const hotspots = map ? getSelectableUnitHotspots(map) : [];
+const unit = inventory.inventory.find(
+  (item) => item.id === hotspots[0]?.unitId,
+);
+const scheme = unit
+  ? getResolvedSchemeForUnit(unit, snapshot.content.paymentSchemes, null)
+  : null;
+
+const quote =
+  unit && scheme
+    ? calculateQuote(
+        unit,
+        {
+          unitId: unit.id,
+          scheme: scheme.id,
+          plusvaliaAnnualPct:
+            snapshot.content.financeRules.defaults.plusvaliaAnnualPct,
+          postDeliveryYears:
+            snapshot.content.financeRules.defaults.postDeliveryYears,
+          downPaymentPct: snapshot.content.financeRules.defaults.downPaymentPct,
+          includeIva: false,
+        },
+        scheme,
+        snapshot.content.financeRules,
+      )
+    : null;
+```
+
+## Trusted Server Flow
+
+Keep `lapa_dev_<prefix>_<secret>` API keys on a server. Use the trusted server
+client to list allowed developments and mint short-lived browser session tokens.
+Browser reservation writes should use only those session tokens.
+
+```ts
+import { createDesarrollosServerClient } from "@grupolapa/desarrollos-sdk/server";
+
+const serverClient = createDesarrollosServerClient({
+  baseUrl: "https://grupolapa.com/api/public/v1/desarrollos",
+  apiKey: process.env.LAPA_DESARROLLOS_API_KEY!,
+});
+
+export async function createBrowserSession(origin: string) {
+  return await serverClient.createBrowserSession({
+    desarrolloKey: "viamare",
+    origin,
+  });
+}
+```
+
+```ts
+import { createDesarrollosClient } from "@grupolapa/desarrollos-sdk";
+
+const browserClient = createDesarrollosClient({
+  baseUrl: "https://grupolapa.com/api/public/v1/desarrollos",
+});
+
+await browserClient.createReservation({
+  desarrolloKey: "viamare",
+  sessionToken,
+  request: {
+    items: [{ unitId: "unit_1" }],
+    payment: {
+      provider: "stripe",
+      returnUrl: "https://partner.example.com/return",
+    },
+  },
+});
+```
+
+## Sitemap Rendering
+
+The API returns image and overlay asset URLs plus SVG-native shape metadata.
+The SDK does not mutate the DOM. Use the sitemap helpers to choose maps and
+resolve unit hotspots, then render the overlay with the frontend framework of
+your choice.
+
+```ts
+import {
+  getShapeForUnit,
+  getSitemapMapAssetPlan,
+  resolveInitialSitemapMap,
+} from "@grupolapa/desarrollos-sdk/sitemap";
+
+const map = resolveInitialSitemapMap(sitemap);
+if (map) {
+  const assets = getSitemapMapAssetPlan(map);
+  const shape = getShapeForUnit(map, selectedUnitId);
+}
+```
+
+## Exports
+
+- `@grupolapa/desarrollos-sdk`: browser-safe client, public types, and
+  `DesarrollosApiError`.
+- `@grupolapa/desarrollos-sdk/server`: trusted server API-key client.
+- `@grupolapa/desarrollos-sdk/quote`: quote, selection, payment, inventory,
+  formatting, Entrada/action, and product helpers.
+- `@grupolapa/desarrollos-sdk/sitemap`: sitemap asset, hotspot, and shape
+  helpers.
+- `@grupolapa/desarrollos-sdk/types`: domain and public REST TypeScript types.

package/dist/bundle-payment-schedule.calc.d.ts

@@ -0,0 +1,2 @@
+import type { QuoteResult } from "./types.js";
+export declare function aggregateQuoteResults(quotes: QuoteResult[]): QuoteResult;

package/dist/bundle-payment-schedule.calc.js

@@ -0,0 +1,160 @@
+function sumBy(items, getValue) {
+    return items.reduce((total, item) => total + getValue(item), 0);
+}
+function roundPct(value) {
+    return Math.round(value * 100) / 100;
+}
+function getTimelineRowAtOrAfterDelivery(quote, month) {
+    return (quote.timelineRows[month] ??
+        quote.timelineRows.at(-1) ??
+        quote.timelineRows[0]);
+}
+function joinLabels(labels) {
+    const uniqueLabels = [...new Set(labels.filter(Boolean))];
+    if (uniqueLabels.length === 0) {
+        return "—";
+    }
+    if (uniqueLabels.length === 1) {
+        return uniqueLabels[0];
+    }
+    return uniqueLabels.join(" + ");
+}
+function aggregateTimelineRows(quotes) {
+    const maxDeliveryMonths = Math.max(...quotes.map((quote) => quote.deliveryMonths));
+    return Array.from({ length: maxDeliveryMonths + 1 }, (_, month) => {
+        const exactRows = quotes
+            .map((quote) => quote.timelineRows[month] ?? null)
+            .filter((row) => Boolean(row));
+        const accumulatedRows = quotes.map((quote) => getTimelineRowAtOrAfterDelivery(quote, month));
+        const paymentLabels = exactRows
+            .filter((row) => row.paymentMXN > 0.005)
+            .map((row) => row.paymentLabel);
+        const milestoneLabels = exactRows
+            .filter((row) => row.isMilestone)
+            .map((row) => row.milestoneLabel);
+        return {
+            month,
+            paymentMXN: sumBy(exactRows, (row) => row.paymentMXN),
+            paymentLabel: joinLabels(paymentLabels),
+            cashbackMXN: sumBy(exactRows, (row) => row.cashbackMXN),
+            plusvaliaDeltaMXN: sumBy(exactRows, (row) => row.plusvaliaDeltaMXN),
+            accumulatedCashbackMXN: sumBy(accumulatedRows, (row) => row.accumulatedCashbackMXN),
+            accumulatedPlusvaliaMXN: sumBy(accumulatedRows, (row) => row.accumulatedPlusvaliaMXN),
+            assetValueMXN: sumBy(accumulatedRows, (row) => row.assetValueMXN),
+            isMilestone: milestoneLabels.length > 0,
+            milestoneLabel: joinLabels(milestoneLabels),
+        };
+    });
+}
+function aggregateProjectionPoints(quotes) {
+    const maxYearOffset = Math.max(...quotes.map((quote) => quote.projectionPoints.at(-1)?.yearOffset ?? 0));
+    return Array.from({ length: maxYearOffset + 1 }, (_, yearOffset) => {
+        const points = quotes.map((quote) => quote.projectionPoints.find((point) => point.yearOffset === yearOffset) ??
+            quote.projectionPoints.at(-1) ??
+            quote.projectionPoints[0]);
+        return {
+            yearOffset,
+            label: yearOffset === 0 ? "Entrega" : `Año +${yearOffset}`,
+            assetValueMXN: sumBy(points, (point) => point.assetValueMXN),
+            rentalAccumulatedMXN: sumBy(points, (point) => point.rentalAccumulatedMXN),
+            valueWithRentMXN: sumBy(points, (point) => point.valueWithRentMXN),
+        };
+    });
+}
+function aggregateBreakdownItems(items) {
+    const itemMap = new Map();
+    for (const item of items) {
+        const existing = itemMap.get(item.label);
+        if (existing) {
+            existing.valueMXN += item.valueMXN;
+        }
+        else {
+            itemMap.set(item.label, { ...item });
+        }
+    }
+    return [...itemMap.values()];
+}
+function countTimelineRows(rows, matchesLabel) {
+    return rows.filter((row) => row.paymentMXN > 0.005 && matchesLabel(row.paymentLabel)).length;
+}
+function sumTimelinePayments(rows, matchesLabel) {
+    return sumBy(rows.filter((row) => row.paymentMXN > 0.005 && matchesLabel(row.paymentLabel)), (row) => row.paymentMXN);
+}
+function labelIncludes(label, search) {
+    return label.toLocaleLowerCase("es-MX").includes(search);
+}
+export function aggregateQuoteResults(quotes) {
+    if (quotes.length === 0) {
+        throw new Error("At least one quote is required to aggregate a schedule.");
+    }
+    const [representativeQuote] = quotes;
+    const timelineRows = aggregateTimelineRows(quotes);
+    const projectionPoints = aggregateProjectionPoints(quotes);
+    const listPriceMXN = sumBy(quotes, (quote) => quote.listPriceMXN);
+    const downPaymentAmountMXN = sumBy(quotes, (quote) => quote.downPaymentAmountMXN);
+    const balanceAmountMXN = sumBy(quotes, (quote) => quote.balanceAmountMXN);
+    const cashbackTotalMXN = sumBy(quotes, (quote) => quote.cashbackTotalMXN);
+    const installmentDiscountMXN = sumBy(quotes, (quote) => quote.installmentDiscountMXN);
+    const netCostMXN = sumBy(quotes, (quote) => quote.netCostMXN);
+    const monthlyPaymentCount = countTimelineRows(timelineRows, (label) => labelIncludes(label, "mensualidad"));
+    const monthlyPaymentTotalMXN = sumTimelinePayments(timelineRows, (label) => labelIncludes(label, "mensualidad"));
+    const deferredPaymentsCount = countTimelineRows(timelineRows, (label) => labelIncludes(label, "anualidad"));
+    const deferredPaymentsTotalMXN = sumTimelinePayments(timelineRows, (label) => labelIncludes(label, "anualidad"));
+    const deliveryPaymentAmountMXN = sumTimelinePayments(timelineRows, (label) => labelIncludes(label, "contra entrega"));
+    const finalTimelineRow = timelineRows.at(-1);
+    const finalProjectionPoint = projectionPoints.at(-1);
+    return {
+        ...representativeQuote,
+        listPriceMXN,
+        deliveryMonths: finalTimelineRow.month,
+        cashbackMonths: Math.max(...quotes.map((quote) => quote.cashbackMonths)),
+        isCashbackCapped: quotes.some((quote) => quote.isCashbackCapped),
+        downPaymentPct: listPriceMXN > 0
+            ? roundPct((downPaymentAmountMXN / listPriceMXN) * 100)
+            : 0,
+        downPaymentAmountMXN,
+        balanceAmountMXN,
+        cashbackMonthlyMXN: sumBy(quotes, (quote) => quote.cashbackMonthlyMXN),
+        cashbackTotalMXN,
+        installmentDiscountPct: listPriceMXN > 0
+            ? roundPct((installmentDiscountMXN / listPriceMXN) * 100)
+            : 0,
+        installmentDiscountMXN,
+        monthlyPaymentPct: listPriceMXN > 0
+            ? roundPct((monthlyPaymentTotalMXN / listPriceMXN) * 100)
+            : 0,
+        monthlyPaymentCount,
+        monthlyPaymentAmountMXN: monthlyPaymentCount > 0
+            ? monthlyPaymentTotalMXN / monthlyPaymentCount
+            : 0,
+        deferredPaymentPct: listPriceMXN > 0
+            ? roundPct((deferredPaymentsTotalMXN / listPriceMXN) * 100)
+            : 0,
+        deferredPaymentsTotalMXN,
+        deferredPaymentsCount,
+        deferredPaymentMonths: timelineRows
+            .filter((row) => row.paymentMXN > 0.005 &&
+            labelIncludes(row.paymentLabel, "anualidad"))
+            .map((row) => row.month),
+        deferredPaymentAmountMXN: deferredPaymentsCount > 0
+            ? deferredPaymentsTotalMXN / deferredPaymentsCount
+            : 0,
+        deliveryPaymentPct: listPriceMXN > 0
+            ? roundPct((deliveryPaymentAmountMXN / listPriceMXN) * 100)
+            : 0,
+        deliveryPaymentAmountMXN,
+        netCostMXN,
+        plusvaliaAtDeliveryMXN: finalTimelineRow.accumulatedPlusvaliaMXN,
+        plusvaliaPostDeliveryMXN: sumBy(quotes, (quote) => quote.plusvaliaPostDeliveryMXN),
+        totalGainMXN: sumBy(quotes, (quote) => quote.totalGainMXN),
+        finalAssetValueMXN: finalTimelineRow.assetValueMXN,
+        projectedAssetValueMXN: finalProjectionPoint.assetValueMXN,
+        rentalMonthlyMXN: sumBy(quotes, (quote) => quote.rentalMonthlyMXN),
+        rentalAccumulatedMXN: finalProjectionPoint.rentalAccumulatedMXN,
+        projectionPoints,
+        timelineRows,
+        visibleTimelineRows: timelineRows.filter((row) => row.paymentMXN > 0.005 || row.isMilestone),
+        costBreakdown: aggregateBreakdownItems(quotes.flatMap((quote) => quote.costBreakdown)),
+        gainBreakdown: aggregateBreakdownItems(quotes.flatMap((quote) => quote.gainBreakdown)),
+    };
+}

package/dist/calculate-quote.d.ts

@@ -0,0 +1,2 @@
+import type { FinanceRules, InventoryUnit, PaymentSchemeDefinition, QuoteInput, QuoteResult } from "./types.js";
+export declare function calculateQuote(unit: InventoryUnit, input: QuoteInput, scheme: PaymentSchemeDefinition, rules: FinanceRules): QuoteResult;