@usethrottle/quotes 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -108,13 +108,36 @@ interface RequestFormConfig {
         companyName?: boolean;
         phone?: boolean;
         buyerReference?: boolean;
+        lineItems?: boolean;
+        targetPrice?: boolean;
         requireTurnstile?: boolean;
     };
     branding?: QuoteBranding | null;
 }
+/**
+ * A line the buyer wants quoted.
+ *
+ * `targetUnitPrice` (minor units) is what they are hoping to pay. It is
+ * recorded as part of the request and shown to the rep; it never becomes the
+ * quoted price. Nothing sent from a browser can set what you charge.
+ */
+interface QuoteRequestItem {
+    name: string;
+    sku?: string | null;
+    /** Your own product id, echoed back on the quote line. */
+    referenceId?: string | null;
+    quantity?: number;
+    /** The buyer's spec for this line — size, finish, delivery date. */
+    note?: string | null;
+    targetUnitPrice?: number | null;
+    imageUrl?: string | null;
+}
 interface SubmitQuoteRequestInput {
     email: string;
-    message: string;
+    /** Free text. Optional when `items` carries at least one line. */
+    message?: string | null;
+    /** Lines to quote. Optional when `message` is written. */
+    items?: QuoteRequestItem[];
     name?: string | null;
     companyName?: string | null;
     phone?: string | null;
@@ -257,6 +280,61 @@ declare class ThrottleQuotesError extends ThrottleError {
     get currentRevisionId(): string | undefined;
 }
 
+/**
+ * A quote cart: the buyer's running list of things to be quoted, built up
+ * while they browse.
+ *
+ * Throttle stores no catalog, so the storefront owns product data and hands
+ * lines in — the same arrangement as the shopping cart. Nothing here is sent
+ * until `read()` is submitted through `QuotesClient.submitRequest`, and the
+ * amounts a storefront attaches are the buyer's TARGET price, never a price
+ * we will honour.
+ *
+ * Lines are keyed by `sku ?? referenceId ?? name`, so adding the same product
+ * twice increases its quantity instead of stacking duplicate rows.
+ */
+interface QuoteCartLine extends QuoteRequestItem {
+    /** Stable identity for updates and removals. */
+    key: string;
+    quantity: number;
+}
+interface QuoteCartStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+interface QuoteCartOptions {
+    /** Namespacing key, so two storefronts on one origin cannot collide. */
+    storageKey?: string;
+    /**
+     * Where the cart survives page navigation. Defaults to `localStorage` in a
+     * browser and to memory everywhere else (SSR, tests) — a cart that throws
+     * during server rendering would take the whole page down.
+     */
+    storage?: QuoteCartStorage | null;
+    /** Refuse to grow past this many distinct lines. The API caps at 100. */
+    maxLines?: number;
+}
+interface QuoteCart {
+    /** Current lines, oldest first. */
+    read(): QuoteCartLine[];
+    /** Total quantity across lines — what a header badge should show. */
+    count(): number;
+    /** Add a line, merging quantities into an existing one with the same key. */
+    add(item: QuoteRequestItem): QuoteCartLine[];
+    /** Add several at once (a "quote this whole cart" button). */
+    addMany(items: QuoteRequestItem[]): QuoteCartLine[];
+    /** Change any field of a line. A quantity below 1 removes it. */
+    update(key: string, patch: Partial<Omit<QuoteCartLine, 'key'>>): QuoteCartLine[];
+    remove(key: string): QuoteCartLine[];
+    clear(): void;
+    /** Subscribe to every change. Returns an unsubscribe function. */
+    subscribe(listener: (lines: QuoteCartLine[]) => void): () => void;
+    /** The `items` payload for `QuotesClient.submitRequest`. */
+    toRequestItems(): QuoteRequestItem[];
+}
+declare function createQuoteCart(options?: QuoteCartOptions): QuoteCart;
+
 interface UseQuoteResult {
     quote: BuyerQuote | null;
     loading: boolean;
@@ -302,6 +380,28 @@ interface UseQuoteRequestFormResult {
 /** Loads a hosted RFQ form's config and submits it, with bot fields handled. */
 declare function useQuoteRequestForm(formToken: string, options?: QuotesClientOptions): UseQuoteRequestFormResult;
 
+interface UseQuoteCartResult {
+    lines: QuoteCartLine[];
+    /** Total quantity across lines — for a header badge. */
+    count: number;
+    add: (item: QuoteRequestItem) => void;
+    addMany: (items: QuoteRequestItem[]) => void;
+    update: (key: string, patch: Partial<Omit<QuoteCartLine, 'key'>>) => void;
+    remove: (key: string) => void;
+    clear: () => void;
+    /** The underlying cart, for use outside React (an Add to Quote button in plain JS). */
+    cart: QuoteCart;
+}
+/**
+ * A quote cart the buyer fills while browsing, then submits as one request.
+ *
+ * The cart persists across page views, so an Add to Quote button on a product
+ * page and a Request quote page elsewhere on the site see the same lines.
+ * Pass the result of `toRequestItems()` (or `lines`) to
+ * `useQuoteRequestForm().submit` as `items`.
+ */
+declare function useQuoteCart(options?: QuoteCartOptions): UseQuoteCartResult;
+
 interface QuoteViewProps {
     /** The `qtl_…` token from the buyer's link. */
     token: string;
@@ -337,6 +437,12 @@ interface QuoteRequestFormProps {
      * API fails the submission closed.
      */
     turnstileToken?: string;
+    /**
+     * Lines to submit with the request — typically `useQuoteCart().lines` after
+     * the buyer has been adding products while browsing. When present, the
+     * written message is optional.
+     */
+    items?: QuoteRequestItem[];
     onSubmitted?: () => void;
     loadingFallback?: ReactNode;
     className?: string;
@@ -349,6 +455,6 @@ interface QuoteRequestFormProps {
  * a success-shaped response and creates nothing, so `onSubmitted` fires either
  * way — by design, a bot must not learn it was caught.
  */
-declare function QuoteRequestForm({ formToken, options, turnstileToken, onSubmitted, loadingFallback, className, }: QuoteRequestFormProps): react_jsx_runtime.JSX.Element;
+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 QuoteComment, type QuoteItem, QuoteRequestForm, type QuoteRequestFormProps, type QuoteRevision, QuoteView, type QuoteViewProps, QuotesClient, type QuotesClientOptions, type RequestFormConfig, type SubmitQuoteRequestInput, type ThrottleEnvelope, ThrottleQuotesError, type UseQuoteRequestFormResult, type UseQuoteResult, computeSelectionTotal, createQuotesClient, formatMoney, scaleLineCharges, useQuote, 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, 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 };

package/dist/index.d.ts

@@ -108,13 +108,36 @@ interface RequestFormConfig {
         companyName?: boolean;
         phone?: boolean;
         buyerReference?: boolean;
+        lineItems?: boolean;
+        targetPrice?: boolean;
         requireTurnstile?: boolean;
     };
     branding?: QuoteBranding | null;
 }
+/**
+ * A line the buyer wants quoted.
+ *
+ * `targetUnitPrice` (minor units) is what they are hoping to pay. It is
+ * recorded as part of the request and shown to the rep; it never becomes the
+ * quoted price. Nothing sent from a browser can set what you charge.
+ */
+interface QuoteRequestItem {
+    name: string;
+    sku?: string | null;
+    /** Your own product id, echoed back on the quote line. */
+    referenceId?: string | null;
+    quantity?: number;
+    /** The buyer's spec for this line — size, finish, delivery date. */
+    note?: string | null;
+    targetUnitPrice?: number | null;
+    imageUrl?: string | null;
+}
 interface SubmitQuoteRequestInput {
     email: string;
-    message: string;
+    /** Free text. Optional when `items` carries at least one line. */
+    message?: string | null;
+    /** Lines to quote. Optional when `message` is written. */
+    items?: QuoteRequestItem[];
     name?: string | null;
     companyName?: string | null;
     phone?: string | null;
@@ -257,6 +280,61 @@ declare class ThrottleQuotesError extends ThrottleError {
     get currentRevisionId(): string | undefined;
 }
 
+/**
+ * A quote cart: the buyer's running list of things to be quoted, built up
+ * while they browse.
+ *
+ * Throttle stores no catalog, so the storefront owns product data and hands
+ * lines in — the same arrangement as the shopping cart. Nothing here is sent
+ * until `read()` is submitted through `QuotesClient.submitRequest`, and the
+ * amounts a storefront attaches are the buyer's TARGET price, never a price
+ * we will honour.
+ *
+ * Lines are keyed by `sku ?? referenceId ?? name`, so adding the same product
+ * twice increases its quantity instead of stacking duplicate rows.
+ */
+interface QuoteCartLine extends QuoteRequestItem {
+    /** Stable identity for updates and removals. */
+    key: string;
+    quantity: number;
+}
+interface QuoteCartStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+interface QuoteCartOptions {
+    /** Namespacing key, so two storefronts on one origin cannot collide. */
+    storageKey?: string;
+    /**
+     * Where the cart survives page navigation. Defaults to `localStorage` in a
+     * browser and to memory everywhere else (SSR, tests) — a cart that throws
+     * during server rendering would take the whole page down.
+     */
+    storage?: QuoteCartStorage | null;
+    /** Refuse to grow past this many distinct lines. The API caps at 100. */
+    maxLines?: number;
+}
+interface QuoteCart {
+    /** Current lines, oldest first. */
+    read(): QuoteCartLine[];
+    /** Total quantity across lines — what a header badge should show. */
+    count(): number;
+    /** Add a line, merging quantities into an existing one with the same key. */
+    add(item: QuoteRequestItem): QuoteCartLine[];
+    /** Add several at once (a "quote this whole cart" button). */
+    addMany(items: QuoteRequestItem[]): QuoteCartLine[];
+    /** Change any field of a line. A quantity below 1 removes it. */
+    update(key: string, patch: Partial<Omit<QuoteCartLine, 'key'>>): QuoteCartLine[];
+    remove(key: string): QuoteCartLine[];
+    clear(): void;
+    /** Subscribe to every change. Returns an unsubscribe function. */
+    subscribe(listener: (lines: QuoteCartLine[]) => void): () => void;
+    /** The `items` payload for `QuotesClient.submitRequest`. */
+    toRequestItems(): QuoteRequestItem[];
+}
+declare function createQuoteCart(options?: QuoteCartOptions): QuoteCart;
+
 interface UseQuoteResult {
     quote: BuyerQuote | null;
     loading: boolean;
@@ -302,6 +380,28 @@ interface UseQuoteRequestFormResult {
 /** Loads a hosted RFQ form's config and submits it, with bot fields handled. */
 declare function useQuoteRequestForm(formToken: string, options?: QuotesClientOptions): UseQuoteRequestFormResult;
 
+interface UseQuoteCartResult {
+    lines: QuoteCartLine[];
+    /** Total quantity across lines — for a header badge. */
+    count: number;
+    add: (item: QuoteRequestItem) => void;
+    addMany: (items: QuoteRequestItem[]) => void;
+    update: (key: string, patch: Partial<Omit<QuoteCartLine, 'key'>>) => void;
+    remove: (key: string) => void;
+    clear: () => void;
+    /** The underlying cart, for use outside React (an Add to Quote button in plain JS). */
+    cart: QuoteCart;
+}
+/**
+ * A quote cart the buyer fills while browsing, then submits as one request.
+ *
+ * The cart persists across page views, so an Add to Quote button on a product
+ * page and a Request quote page elsewhere on the site see the same lines.
+ * Pass the result of `toRequestItems()` (or `lines`) to
+ * `useQuoteRequestForm().submit` as `items`.
+ */
+declare function useQuoteCart(options?: QuoteCartOptions): UseQuoteCartResult;
+
 interface QuoteViewProps {
     /** The `qtl_…` token from the buyer's link. */
     token: string;
@@ -337,6 +437,12 @@ interface QuoteRequestFormProps {
      * API fails the submission closed.
      */
     turnstileToken?: string;
+    /**
+     * Lines to submit with the request — typically `useQuoteCart().lines` after
+     * the buyer has been adding products while browsing. When present, the
+     * written message is optional.
+     */
+    items?: QuoteRequestItem[];
     onSubmitted?: () => void;
     loadingFallback?: ReactNode;
     className?: string;
@@ -349,6 +455,6 @@ interface QuoteRequestFormProps {
  * a success-shaped response and creates nothing, so `onSubmitted` fires either
  * way — by design, a bot must not learn it was caught.
  */
-declare function QuoteRequestForm({ formToken, options, turnstileToken, onSubmitted, loadingFallback, className, }: QuoteRequestFormProps): react_jsx_runtime.JSX.Element;
+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 QuoteComment, type QuoteItem, QuoteRequestForm, type QuoteRequestFormProps, type QuoteRevision, QuoteView, type QuoteViewProps, QuotesClient, type QuotesClientOptions, type RequestFormConfig, type SubmitQuoteRequestInput, type ThrottleEnvelope, ThrottleQuotesError, type UseQuoteRequestFormResult, type UseQuoteResult, computeSelectionTotal, createQuotesClient, formatMoney, scaleLineCharges, useQuote, 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, 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 };

package/dist/index.js

@@ -161,6 +161,125 @@ function computeSelectionTotal(items, selections, shippingTotal = 0) {
 
 // src/hooks.ts
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+// src/quote-cart.ts
+var DEFAULT_KEY = "throttle:quote-cart";
+var DEFAULT_MAX_LINES = 100;
+function memoryStorage() {
+  const map = /* @__PURE__ */ new Map();
+  return {
+    getItem: (key) => map.get(key) ?? null,
+    setItem: (key, value) => void map.set(key, value),
+    removeItem: (key) => void map.delete(key)
+  };
+}
+function defaultStorage() {
+  try {
+    if (typeof globalThis !== "undefined" && globalThis.localStorage) {
+      return globalThis.localStorage;
+    }
+  } catch {
+  }
+  return memoryStorage();
+}
+function lineKey(item) {
+  const raw = item.sku?.trim() || item.referenceId?.trim() || item.name.trim();
+  return raw.toLowerCase();
+}
+function normalizeQuantity(value) {
+  const n = Math.floor(Number(value ?? 1));
+  return Number.isFinite(n) && n > 0 ? n : 1;
+}
+function createQuoteCart(options = {}) {
+  const storageKey = options.storageKey ?? DEFAULT_KEY;
+  const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+  const storage = options.storage === null ? memoryStorage() : options.storage ?? defaultStorage();
+  const listeners = /* @__PURE__ */ new Set();
+  function load() {
+    try {
+      const raw = storage.getItem(storageKey);
+      if (!raw) return [];
+      const parsed = JSON.parse(raw);
+      if (!Array.isArray(parsed)) return [];
+      return parsed.filter((line) => line && typeof line.name === "string" && line.name.trim()).map((line) => ({
+        ...line,
+        key: typeof line.key === "string" && line.key ? line.key : lineKey(line),
+        quantity: normalizeQuantity(line.quantity)
+      })).slice(0, maxLines);
+    } catch {
+      return [];
+    }
+  }
+  function save(lines) {
+    try {
+      storage.setItem(storageKey, JSON.stringify(lines));
+    } catch {
+    }
+    for (const listener of listeners) listener(lines);
+    return lines;
+  }
+  return {
+    read: load,
+    count() {
+      return load().reduce((sum, line) => sum + line.quantity, 0);
+    },
+    add(item) {
+      return this.addMany([item]);
+    },
+    addMany(items) {
+      const lines = load();
+      for (const item of items) {
+        if (!item?.name?.trim()) continue;
+        const key = lineKey(item);
+        const existing = lines.find((line) => line.key === key);
+        if (existing) {
+          existing.quantity += normalizeQuantity(item.quantity);
+          if (item.note) existing.note = item.note;
+          if (item.targetUnitPrice != null) existing.targetUnitPrice = item.targetUnitPrice;
+          continue;
+        }
+        if (lines.length >= maxLines) break;
+        lines.push({ ...item, key, quantity: normalizeQuantity(item.quantity) });
+      }
+      return save(lines);
+    },
+    update(key, patch) {
+      const lines = load();
+      const index = lines.findIndex((line) => line.key === key);
+      if (index === -1) return lines;
+      if (patch.quantity != null && Math.floor(Number(patch.quantity)) < 1) {
+        lines.splice(index, 1);
+        return save(lines);
+      }
+      lines[index] = {
+        ...lines[index],
+        ...patch,
+        key,
+        quantity: normalizeQuantity(patch.quantity ?? lines[index].quantity)
+      };
+      return save(lines);
+    },
+    remove(key) {
+      return save(load().filter((line) => line.key !== key));
+    },
+    clear() {
+      try {
+        storage.removeItem(storageKey);
+      } catch {
+      }
+      for (const listener of listeners) listener([]);
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => void listeners.delete(listener);
+    },
+    toRequestItems() {
+      return load().map(({ key: _key, ...item }) => item);
+    }
+  };
+}
+
+// src/hooks.ts
 function useQuote(token, options = {}) {
   const client = useMemo(
     () => new QuotesClient(options),
@@ -353,6 +472,31 @@ function useQuoteRequestForm(formToken, options = {}) {
   );
   return { config, loading, error, submitting, submitted, submit, formLoadedAt };
 }
+function useQuoteCart(options = {}) {
+  const cart = useMemo(
+    () => createQuoteCart(options),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [options.storageKey, options.maxLines]
+  );
+  const [lines, setLines] = useState([]);
+  useEffect(() => {
+    setLines(cart.read());
+    return cart.subscribe(setLines);
+  }, [cart]);
+  return {
+    lines,
+    count: lines.reduce((sum, line) => sum + line.quantity, 0),
+    add: useCallback((item) => void cart.add(item), [cart]),
+    addMany: useCallback((items) => void cart.addMany(items), [cart]),
+    update: useCallback(
+      (key, patch) => void cart.update(key, patch),
+      [cart]
+    ),
+    remove: useCallback((key) => void cart.remove(key), [cart]),
+    clear: useCallback(() => cart.clear(), [cart]),
+    cart
+  };
+}
 
 // src/QuoteView.tsx
 import { useState as useState2 } from "react";
@@ -595,11 +739,13 @@ function QuoteRequestForm({
   formToken,
   options,
   turnstileToken,
+  items,
   onSubmitted,
   loadingFallback,
   className
 }) {
   const f = useQuoteRequestForm(formToken, options ?? {});
+  const lines = items ?? [];
   const [values, setValues] = useState3({
     email: "",
     name: "",
@@ -629,7 +775,8 @@ function QuoteRequestForm({
         e.preventDefault();
         void f.submit({
           email: values.email,
-          message: values.message,
+          message: values.message || null,
+          ...lines.length > 0 ? { items: lines } : {},
           name: values.name || null,
           companyName: fields.companyName ? values.companyName || null : null,
           phone: fields.phone ? values.phone || null : null,
@@ -663,9 +810,23 @@ function QuoteRequestForm({
           "Your reference #",
           /* @__PURE__ */ jsx2("input", { value: values.buyerReference, onChange: set("buyerReference") })
         ] }) : null,
+        lines.length > 0 ? /* @__PURE__ */ jsx2("ul", { "aria-label": "Items on this request", children: lines.map((line, index) => /* @__PURE__ */ jsxs2("li", { children: [
+          line.quantity ?? 1,
+          " \xD7 ",
+          line.name,
+          line.sku ? ` (${line.sku})` : "",
+          line.note ? ` \u2014 ${line.note}` : ""
+        ] }, line.sku ?? line.referenceId ?? `${line.name}-${index}`)) }) : null,
         /* @__PURE__ */ jsxs2("label", { children: [
-          "What do you need?",
-          /* @__PURE__ */ jsx2("textarea", { value: values.message, onChange: set("message"), required: true })
+          lines.length > 0 ? "Anything else we should know?" : "What do you need?",
+          /* @__PURE__ */ jsx2(
+            "textarea",
+            {
+              value: values.message,
+              onChange: set("message"),
+              required: lines.length === 0
+            }
+          )
         ] }),
         /* @__PURE__ */ jsx2("div", { style: honeypotStyle, "aria-hidden": "true", children: /* @__PURE__ */ jsxs2("label", { children: [
           "Website",
@@ -680,7 +841,14 @@ function QuoteRequestForm({
             }
           )
         ] }) }),
-        /* @__PURE__ */ jsx2("button", { type: "submit", disabled: f.submitting || !values.email || !values.message, children: f.submitting ? "Sending\u2026" : "Request a quote" })
+        /* @__PURE__ */ jsx2(
+          "button",
+          {
+            type: "submit",
+            disabled: f.submitting || !values.email || !values.message && lines.length === 0,
+            children: f.submitting ? "Sending\u2026" : "Request a quote"
+          }
+        )
       ]
     }
   );
@@ -691,10 +859,12 @@ export {
   QuotesClient,
   ThrottleQuotesError,
   computeSelectionTotal,
+  createQuoteCart,
   createQuotesClient,
   formatMoney,
   scaleLineCharges,
   useQuote,
+  useQuoteCart,
   useQuoteRequestForm
 };
 //# sourceMappingURL=index.js.map