@usethrottle/quotes 0.4.1 → 0.6.0

package/dist/index.d.cts

@@ -16,6 +16,28 @@ type PaymentTerms = {
     };
     balanceNetN: number;
 };
+/** A subscription line's terms (Throttle creates one subscription per line when the quote is paid). */
+interface QuoteItemRecurring {
+    plan: string;
+    planName: string | null;
+    interval: string;
+    intervalUnit: string;
+    intervalCount: number;
+    /** Set on an installment plan: exactly this many payments. */
+    totalPayments: number | null;
+    /** 0 when there is no free trial. A free-trial line charges nothing at acceptance. */
+    trialDays: number;
+    /**
+     * Custom installment schedule: payments that differ in amount (per unit, minor
+     * units) and in the gap before each one. Present only on a schedule line, where
+     * `totalPayments` equals its length. Row 0 has no gap.
+     */
+    schedule?: Array<{
+        amount: number;
+        intervalUnit: string | null;
+        intervalCount: number | null;
+    }>;
+}
 interface QuoteItem {
     id: string;
     type: string;
@@ -35,6 +57,8 @@ interface QuoteItem {
     qtyEditable: boolean;
     imageUrl: string | null;
     position: number;
+    /** Subscription terms, or null for a one-time line. `unitPrice` is the per-period price per seat. */
+    recurring: QuoteItemRecurring | null;
 }
 interface QuoteRevision {
     id: string;
@@ -261,6 +285,25 @@ declare function scaleLineCharges(item: {
     taxAmount: number;
     discountAmount: number;
 };
+/** A subscription line with a free trial: nothing is charged for it at acceptance. */
+declare function isFreeTrialLine(item: {
+    recurring?: {
+        trialDays?: number | null;
+    } | null;
+}): boolean;
+/**
+ * What one line charges at acceptance, at `quantity`. MUST match
+ * `lineDueAtAcceptance` in @commerce/quotes (shared test vectors).
+ */
+declare function lineDueAtAcceptance(item: {
+    unitPrice: number;
+    quantity: number;
+    taxAmount: number;
+    discountAmount: number;
+    recurring?: {
+        trialDays?: number | null;
+    } | null;
+}, quantity: number): number;
 /** Effective total for a selection, using the same math the server will apply. */
 declare function computeSelectionTotal(items: Array<{
     id: string;
@@ -269,6 +312,9 @@ declare function computeSelectionTotal(items: Array<{
     taxAmount: number;
     discountAmount: number;
     optional: boolean;
+    recurring?: {
+        trialDays?: number | null;
+    } | null;
 }>, selections: Record<string, {
     selected: boolean;
     quantity: number;
@@ -483,4 +529,4 @@ interface QuoteRequestFormProps {
  */
 declare function QuoteRequestForm({ formToken, options, turnstileToken, items, onSubmitted, loadingFallback, className, }: QuoteRequestFormProps): react_jsx_runtime.JSX.Element;
 
-export { type AcceptQuoteInput, type AcceptQuoteResult, type BuyerQuote, type BuyerQuoteStatus, type ItemSelection, type PaymentTerms, type QuoteBranding, type QuoteCart, type QuoteCartLine, type QuoteCartOptions, type QuoteCartStorage, type QuoteComment, type QuoteItem, QuoteRequestForm, type QuoteRequestFormProps, type QuoteRequestItem, type QuoteRevision, QuoteView, type QuoteViewProps, QuotesClient, type QuotesClientOptions, type RequestFormConfig, type SubmitQuoteRequestInput, type ThrottleEnvelope, ThrottleQuotesError, type UseQuoteCartResult, type UseQuoteRequestFormResult, type UseQuoteResult, computeSelectionTotal, createQuoteCart, createQuotesClient, formatMoney, scaleLineCharges, useQuote, useQuoteCart, useQuoteRequestForm };
+export { type AcceptQuoteInput, type AcceptQuoteResult, type BuyerQuote, type BuyerQuoteStatus, type ItemSelection, type PaymentTerms, type QuoteBranding, type QuoteCart, type QuoteCartLine, type QuoteCartOptions, type QuoteCartStorage, type QuoteComment, type QuoteItem, type QuoteItemRecurring, QuoteRequestForm, type QuoteRequestFormProps, type QuoteRequestItem, type QuoteRevision, QuoteView, type QuoteViewProps, QuotesClient, type QuotesClientOptions, type RequestFormConfig, type SubmitQuoteRequestInput, type ThrottleEnvelope, ThrottleQuotesError, type UseQuoteCartResult, type UseQuoteRequestFormResult, type UseQuoteResult, computeSelectionTotal, createQuoteCart, createQuotesClient, formatMoney, isFreeTrialLine, lineDueAtAcceptance, scaleLineCharges, useQuote, useQuoteCart, useQuoteRequestForm };

package/dist/index.d.ts

@@ -16,6 +16,28 @@ type PaymentTerms = {
     };
     balanceNetN: number;
 };
+/** A subscription line's terms (Throttle creates one subscription per line when the quote is paid). */
+interface QuoteItemRecurring {
+    plan: string;
+    planName: string | null;
+    interval: string;
+    intervalUnit: string;
+    intervalCount: number;
+    /** Set on an installment plan: exactly this many payments. */
+    totalPayments: number | null;
+    /** 0 when there is no free trial. A free-trial line charges nothing at acceptance. */
+    trialDays: number;
+    /**
+     * Custom installment schedule: payments that differ in amount (per unit, minor
+     * units) and in the gap before each one. Present only on a schedule line, where
+     * `totalPayments` equals its length. Row 0 has no gap.
+     */
+    schedule?: Array<{
+        amount: number;
+        intervalUnit: string | null;
+        intervalCount: number | null;
+    }>;
+}
 interface QuoteItem {
     id: string;
     type: string;
@@ -35,6 +57,8 @@ interface QuoteItem {
     qtyEditable: boolean;
     imageUrl: string | null;
     position: number;
+    /** Subscription terms, or null for a one-time line. `unitPrice` is the per-period price per seat. */
+    recurring: QuoteItemRecurring | null;
 }
 interface QuoteRevision {
     id: string;
@@ -261,6 +285,25 @@ declare function scaleLineCharges(item: {
     taxAmount: number;
     discountAmount: number;
 };
+/** A subscription line with a free trial: nothing is charged for it at acceptance. */
+declare function isFreeTrialLine(item: {
+    recurring?: {
+        trialDays?: number | null;
+    } | null;
+}): boolean;
+/**
+ * What one line charges at acceptance, at `quantity`. MUST match
+ * `lineDueAtAcceptance` in @commerce/quotes (shared test vectors).
+ */
+declare function lineDueAtAcceptance(item: {
+    unitPrice: number;
+    quantity: number;
+    taxAmount: number;
+    discountAmount: number;
+    recurring?: {
+        trialDays?: number | null;
+    } | null;
+}, quantity: number): number;
 /** Effective total for a selection, using the same math the server will apply. */
 declare function computeSelectionTotal(items: Array<{
     id: string;
@@ -269,6 +312,9 @@ declare function computeSelectionTotal(items: Array<{
     taxAmount: number;
     discountAmount: number;
     optional: boolean;
+    recurring?: {
+        trialDays?: number | null;
+    } | null;
 }>, selections: Record<string, {
     selected: boolean;
     quantity: number;
@@ -483,4 +529,4 @@ interface QuoteRequestFormProps {
  */
 declare function QuoteRequestForm({ formToken, options, turnstileToken, items, onSubmitted, loadingFallback, className, }: QuoteRequestFormProps): react_jsx_runtime.JSX.Element;
 
-export { type AcceptQuoteInput, type AcceptQuoteResult, type BuyerQuote, type BuyerQuoteStatus, type ItemSelection, type PaymentTerms, type QuoteBranding, type QuoteCart, type QuoteCartLine, type QuoteCartOptions, type QuoteCartStorage, type QuoteComment, type QuoteItem, QuoteRequestForm, type QuoteRequestFormProps, type QuoteRequestItem, type QuoteRevision, QuoteView, type QuoteViewProps, QuotesClient, type QuotesClientOptions, type RequestFormConfig, type SubmitQuoteRequestInput, type ThrottleEnvelope, ThrottleQuotesError, type UseQuoteCartResult, type UseQuoteRequestFormResult, type UseQuoteResult, computeSelectionTotal, createQuoteCart, createQuotesClient, formatMoney, scaleLineCharges, useQuote, useQuoteCart, useQuoteRequestForm };
+export { type AcceptQuoteInput, type AcceptQuoteResult, type BuyerQuote, type BuyerQuoteStatus, type ItemSelection, type PaymentTerms, type QuoteBranding, type QuoteCart, type QuoteCartLine, type QuoteCartOptions, type QuoteCartStorage, type QuoteComment, type QuoteItem, type QuoteItemRecurring, QuoteRequestForm, type QuoteRequestFormProps, type QuoteRequestItem, type QuoteRevision, QuoteView, type QuoteViewProps, QuotesClient, type QuotesClientOptions, type RequestFormConfig, type SubmitQuoteRequestInput, type ThrottleEnvelope, ThrottleQuotesError, type UseQuoteCartResult, type UseQuoteRequestFormResult, type UseQuoteResult, computeSelectionTotal, createQuoteCart, createQuotesClient, formatMoney, isFreeTrialLine, lineDueAtAcceptance, scaleLineCharges, useQuote, useQuoteCart, useQuoteRequestForm };

package/dist/index.js

@@ -164,14 +164,20 @@ function scaleLineCharges(item, quantity) {
     discountAmount: Math.round(item.discountAmount * ratio)
   };
 }
+function isFreeTrialLine(item) {
+  return (item.recurring?.trialDays ?? 0) > 0;
+}
+function lineDueAtAcceptance(item, quantity) {
+  const { taxAmount, discountAmount } = scaleLineCharges(item, quantity);
+  return (isFreeTrialLine(item) ? 0 : item.unitPrice * quantity) + taxAmount - discountAmount;
+}
 function computeSelectionTotal(items, selections, shippingTotal = 0) {
   let total = shippingTotal;
   for (const item of items) {
     const state = selections[item.id];
     if (item.optional && state && !state.selected) continue;
     const qty = state?.quantity ?? item.quantity;
-    const { taxAmount, discountAmount } = scaleLineCharges(item, qty);
-    total += item.unitPrice * qty + taxAmount - discountAmount;
+    total += lineDueAtAcceptance(item, qty);
   }
   return total;
 }
@@ -522,6 +528,54 @@ function useQuoteCart(options = {}) {
 
 // src/QuoteView.tsx
 import { useState as useState2 } from "react";
+
+// ../core-cadence/src/cadence.ts
+var INTERVAL_UNITS = ["hour", "day", "week", "month"];
+var NAMED_INTERVALS = ["weekly", "biweekly", "monthly", "quarterly", "yearly"];
+var INTERVAL_VALUES = [...NAMED_INTERVALS, "custom"];
+var HOUR_MS = 36e5;
+var DAY_MS = 24 * HOUR_MS;
+var WEEK_MS = 7 * DAY_MS;
+function isNamedInterval(value) {
+  return typeof value === "string" && NAMED_INTERVALS.includes(value);
+}
+function isIntervalUnit(value) {
+  return typeof value === "string" && INTERVAL_UNITS.includes(value);
+}
+
+// ../core-cadence/src/schedule.ts
+function scheduleUnitTotal(schedule) {
+  return schedule.reduce((sum, row2) => sum + row2.amount, 0);
+}
+
+// ../core-cadence/src/labels.ts
+var NAMED_NOUN = {
+  weekly: "week",
+  biweekly: "2 weeks",
+  monthly: "month",
+  quarterly: "quarter",
+  yearly: "year"
+};
+function cadenceNoun(cadence) {
+  if (isNamedInterval(cadence.interval)) return NAMED_NOUN[cadence.interval];
+  if (isIntervalUnit(cadence.intervalUnit) && cadence.intervalCount != null) {
+    return cadence.intervalCount === 1 ? cadence.intervalUnit : `${cadence.intervalCount} ${cadence.intervalUnit}s`;
+  }
+  return cadence.interval;
+}
+function recurringTermsLabel(terms, price, money) {
+  const quantity = price.quantity ?? 1;
+  if (terms.schedule && terms.schedule.length > 0) {
+    return `${money(scheduleUnitTotal(terms.schedule) * quantity)} total \xB7 ${terms.schedule.length} payments`;
+  }
+  const each = money(price.unitPrice * quantity);
+  const noun = cadenceNoun(terms);
+  const trialDays = terms.trialDays ?? 0;
+  if (trialDays > 0) return `Free for ${trialDays} day${trialDays === 1 ? "" : "s"}, then ${each} / ${noun}`;
+  return `${each} / ${noun}` + (terms.totalPayments != null ? ` \xB7 ${terms.totalPayments} payments` : "");
+}
+
+// src/QuoteView.tsx
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 var row = { display: "flex", justifyContent: "space-between", gap: 16, padding: "8px 0" };
 var muted = { color: "#666", fontSize: 13 };
@@ -541,6 +595,7 @@ function QuoteView({ token, options, onCheckout, loadingFallback, className }) {
   const ordered = quote.status === "ordered";
   const accepted = quote.status === "accepted";
   const canAct = quote.status === "ready";
+  const recurringKept = rev ? rev.items.filter((i) => i.recurring && (!i.optional || (q.selections[i.id]?.selected ?? true))) : [];
   const handleResume = async () => {
     const { checkoutUrl } = await q.resumeCheckout();
     if (onCheckout) onCheckout(checkoutUrl);
@@ -599,7 +654,11 @@ function QuoteView({ token, options, onCheckout, loadingFallback, className }) {
               " ",
               /* @__PURE__ */ jsx("span", { style: muted, children: "optional" })
             ] }) : item.name,
-            item.description ? /* @__PURE__ */ jsx("div", { style: muted, children: item.description }) : null
+            item.description ? /* @__PURE__ */ jsx("div", { style: muted, children: item.description }) : null,
+            item.recurring ? /* @__PURE__ */ jsxs("div", { style: muted, children: [
+              "Subscription \xB7 ",
+              recurringTermsLabel(item.recurring, { unitPrice: item.unitPrice, quantity: state.quantity }, (m) => formatMoney(m, currency))
+            ] }) : null
           ] }),
           /* @__PURE__ */ jsx("td", { align: "right", children: formatMoney(item.unitPrice, currency) }),
           /* @__PURE__ */ jsx("td", { align: "right", children: item.qtyEditable && canAct ? /* @__PURE__ */ jsx(
@@ -614,18 +673,23 @@ function QuoteView({ token, options, onCheckout, loadingFallback, className }) {
               style: { width: 64 }
             }
           ) : state.quantity }),
-          /* @__PURE__ */ jsx("td", { align: "right", children: included ? formatMoney(
-            item.unitPrice * state.quantity + item.taxAmount - item.discountAmount,
-            currency
-          ) : formatMoney(0, currency) })
+          /* @__PURE__ */ jsx("td", { align: "right", children: formatMoney(included ? lineDueAtAcceptance(item, state.quantity) : 0, currency) })
         ] }, item.id);
       }) })
     ] }) : null,
     rev ? /* @__PURE__ */ jsxs("section", { children: [
       /* @__PURE__ */ jsxs("div", { style: row, children: [
-        /* @__PURE__ */ jsx("strong", { children: "Total" }),
+        /* @__PURE__ */ jsx("strong", { children: recurringKept.length > 0 ? "Due at acceptance" : "Total" }),
         /* @__PURE__ */ jsx("strong", { children: formatMoney(q.total, currency) })
       ] }),
+      recurringKept.length > 0 ? /* @__PURE__ */ jsxs("div", { children: [
+        /* @__PURE__ */ jsx("p", { style: muted, children: "Recurring after" }),
+        recurringKept.map((i) => /* @__PURE__ */ jsxs("p", { style: muted, children: [
+          i.name,
+          ": ",
+          recurringTermsLabel(i.recurring, { unitPrice: i.unitPrice, quantity: q.selections[i.id]?.quantity ?? i.quantity }, (m) => formatMoney(m, currency))
+        ] }, i.id))
+      ] }) : null,
       /* @__PURE__ */ jsx("p", { style: muted, children: termsLabel(rev.paymentTerms, rev.depositAmount, currency) }),
       rev.leadTime ? /* @__PURE__ */ jsxs("p", { style: muted, children: [
         "Lead time: ",
@@ -898,6 +962,8 @@ export {
   createQuoteCart,
   createQuotesClient,
   formatMoney,
+  isFreeTrialLine,
+  lineDueAtAcceptance,
   scaleLineCharges,
   useQuote,
   useQuoteCart,