@usethrottle/quotes 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { ThrottleError } from '@usethrottle/errors';
+import { ThrottleError, ThrottleErrorArgs } from '@usethrottle/errors';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 
@@ -16,6 +16,18 @@ 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;
+}
 interface QuoteItem {
     id: string;
     type: string;
@@ -35,6 +47,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 +275,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 +302,9 @@ declare function computeSelectionTotal(items: Array<{
     taxAmount: number;
     discountAmount: number;
     optional: boolean;
+    recurring?: {
+        trialDays?: number | null;
+    } | null;
 }>, selections: Record<string, {
     selected: boolean;
     quantity: number;
@@ -292,6 +328,7 @@ declare class ThrottleQuotesError extends ThrottleError {
         message: string;
         statusCode: number;
         details?: unknown;
+        responseHeaders?: ThrottleErrorArgs['responseHeaders'];
     });
     /** The offer moved on — reload and show the buyer the current revision. */
     get isSuperseded(): boolean;
@@ -482,4 +519,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

@@ -1,4 +1,4 @@
-import { ThrottleError } from '@usethrottle/errors';
+import { ThrottleError, ThrottleErrorArgs } from '@usethrottle/errors';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 
@@ -16,6 +16,18 @@ 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;
+}
 interface QuoteItem {
     id: string;
     type: string;
@@ -35,6 +47,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 +275,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 +302,9 @@ declare function computeSelectionTotal(items: Array<{
     taxAmount: number;
     discountAmount: number;
     optional: boolean;
+    recurring?: {
+        trialDays?: number | null;
+    } | null;
 }>, selections: Record<string, {
     selected: boolean;
     quantity: number;
@@ -292,6 +328,7 @@ declare class ThrottleQuotesError extends ThrottleError {
         message: string;
         statusCode: number;
         details?: unknown;
+        responseHeaders?: ThrottleErrorArgs['responseHeaders'];
     });
     /** The offer moved on — reload and show the buyer the current revision. */
     get isSuperseded(): boolean;
@@ -482,4 +519,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

@@ -48,7 +48,8 @@ var QuotesClient = class {
           code: json.error?.code ?? "unknown_error",
           message: json.error?.message ?? `HTTP ${res.status}`,
           statusCode: res.status,
-          details: json.error?.details
+          details: json.error?.details,
+          responseHeaders: res.headers
         });
       }
       return json.data;
@@ -163,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;
 }
@@ -521,6 +528,44 @@ 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/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, each) {
+  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 };
@@ -540,6 +585,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);
@@ -598,7 +644,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, formatMoney(item.unitPrice * state.quantity, currency))
+            ] }) : null
           ] }),
           /* @__PURE__ */ jsx("td", { align: "right", children: formatMoney(item.unitPrice, currency) }),
           /* @__PURE__ */ jsx("td", { align: "right", children: item.qtyEditable && canAct ? /* @__PURE__ */ jsx(
@@ -613,18 +663,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, formatMoney(i.unitPrice * (q.selections[i.id]?.quantity ?? i.quantity), 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: ",
@@ -897,6 +952,8 @@ export {
   createQuoteCart,
   createQuotesClient,
   formatMoney,
+  isFreeTrialLine,
+  lineDueAtAcceptance,
   scaleLineCharges,
   useQuote,
   useQuoteCart,