@usethrottle/quotes 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,354 @@
+import { ThrottleError } from '@usethrottle/errors';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+type BuyerQuoteStatus = 'in_progress' | 'ready' | 'being_revised' | 'accepted' | 'ordered' | 'declined' | 'expired';
+type PaymentTerms = {
+    mode: 'pay_in_full';
+} | {
+    mode: 'net_terms';
+    netN: number;
+} | {
+    mode: 'deposit_balance';
+    deposit: {
+        type: 'percent' | 'fixed';
+        value: number;
+    };
+    balanceNetN: number;
+};
+interface QuoteItem {
+    id: string;
+    type: string;
+    sku: string | null;
+    name: string;
+    description: string | null;
+    unitPrice: number;
+    quantity: number;
+    subtotal: number;
+    taxAmount: number;
+    discountAmount: number;
+    total: number;
+    /** Buyer may deselect this line. */
+    optional: boolean;
+    optionalSelected: boolean;
+    /** Buyer may change the quantity. Reps lock volume-priced lines. */
+    qtyEditable: boolean;
+    imageUrl: string | null;
+    position: number;
+}
+interface QuoteRevision {
+    id: string;
+    revisionNumber: number;
+    issuedAt: string | null;
+    expiresAt: string | null;
+    subtotal: number;
+    taxTotal: number;
+    discountTotal: number;
+    shippingTotal: number;
+    total: number;
+    shippingMode: 'none' | 'flat' | 'checkout_calculated' | 'free';
+    shippingFlatAmount: number | null;
+    paymentTerms: PaymentTerms;
+    /** Frozen at issue time for deposit_balance terms. */
+    depositAmount: number | null;
+    buyerNote: string | null;
+    changeSummary: string | null;
+    leadTime: string | null;
+    items: QuoteItem[];
+}
+interface QuoteComment {
+    id: string;
+    authorType: 'buyer' | 'merchant' | 'system';
+    authorName: string | null;
+    body: string;
+    createdAt: string;
+}
+interface QuoteBranding {
+    displayName?: string | null;
+    logoUrl?: string | null;
+    brandColor?: string | null;
+}
+interface BuyerQuote {
+    quoteNumber: string;
+    status: BuyerQuoteStatus;
+    buyerReference: string | null;
+    currency: string;
+    expiresAt: string | null;
+    currentRevision: QuoteRevision | null;
+    revisionHistory: QuoteRevision[];
+    comments: QuoteComment[];
+    /** Present only once the quote has converted. */
+    orderId?: string | null;
+    branding?: QuoteBranding | null;
+}
+/** What the buyer chose: which optional lines they kept, at what quantities. */
+interface ItemSelection {
+    itemId: string;
+    selected?: boolean;
+    quantity?: number;
+}
+interface AcceptQuoteInput {
+    revisionId: string;
+    acceptedByName: string;
+    acceptedByEmail: string;
+    buyerReference?: string | null;
+    itemSelections?: ItemSelection[];
+}
+interface AcceptQuoteResult {
+    quote: BuyerQuote;
+    /** Hosted checkout URL — redirect the buyer here immediately. */
+    checkoutUrl: string;
+}
+interface RequestFormConfig {
+    title: string | null;
+    introText: string | null;
+    successMessage: string | null;
+    redirectUrl: string | null;
+    fields: {
+        companyName?: boolean;
+        phone?: boolean;
+        buyerReference?: boolean;
+        requireTurnstile?: boolean;
+    };
+    branding?: QuoteBranding | null;
+}
+interface SubmitQuoteRequestInput {
+    email: string;
+    message: string;
+    name?: string | null;
+    companyName?: string | null;
+    phone?: string | null;
+    buyerReference?: string | null;
+    /** Honeypot — leave empty. The component wires this for you. */
+    website?: string | null;
+    /** Client mount time in ms; the API enforces a minimum fill duration. */
+    formLoadedAt?: number;
+    turnstileToken?: string;
+}
+interface ThrottleEnvelope<T> {
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    meta?: {
+        requestId?: string;
+    };
+}
+interface QuotesClientOptions {
+    /**
+     * Where the public quote-link routes live. Defaults to Throttle's API.
+     * Point this at your own origin when proxying through `createQuoteProxyHandler`
+     * so the browser never talks to a third-party host.
+     */
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+}
+
+/**
+ * Headless client for the public quote surfaces. Everything is authorized by
+ * the capability token in the URL — there is no API key here, and there must
+ * not be: this runs in the buyer's browser.
+ */
+declare class QuotesClient {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(opts?: QuotesClientOptions);
+    private request;
+    /** Fetch the quote a buyer link points at. 404s for unknown/rotated tokens. */
+    getQuote(token: string): Promise<BuyerQuote>;
+    /**
+     * Tell the merchant the buyer opened the quote. Fire-and-forget: the server
+     * throttles the resulting webhook to one per revision per 6h, and a failed
+     * beacon must never break the page.
+     */
+    recordView(token: string): Promise<void>;
+    addComment(token: string, input: {
+        body: string;
+        authorName?: string;
+        authorEmail?: string;
+    }): Promise<QuoteComment>;
+    requestRevision(token: string, input?: {
+        message?: string;
+        authorName?: string;
+    }): Promise<BuyerQuote>;
+    decline(token: string, input?: {
+        reason?: string;
+        authorName?: string;
+    }): Promise<BuyerQuote>;
+    /**
+     * Accept and get the checkout URL to send the buyer to.
+     *
+     * Re-accepting the same revision is idempotent and replays the same URL.
+     * Accepting a superseded revision throws `revision_superseded` carrying
+     * `currentRevisionId`; an expired offer throws `quote_expired`.
+     */
+    accept(token: string, input: AcceptQuoteInput): Promise<AcceptQuoteResult>;
+    /** URL of the PDF for the revision the buyer is looking at (server 302s to signed storage). */
+    pdfUrl(token: string): string;
+    getRequestForm(formToken: string): Promise<RequestFormConfig>;
+    /**
+     * Submit an RFQ. The response is deliberately thin (`{ submitted: true }`) —
+     * anonymous callers learn no internal identifiers. A submission caught by
+     * the honeypot returns the same shape without creating anything, so a bot
+     * cannot tell it was detected; treat success as "accepted", not "created".
+     */
+    submitRequest(formToken: string, input: SubmitQuoteRequestInput): Promise<{
+        submitted: boolean;
+    }>;
+}
+declare function createQuotesClient(opts?: QuotesClientOptions): QuotesClient;
+/** Minor units → a display string, e.g. (104000, 'USD') → "$1,040.00". */
+declare function formatMoney(minorUnits: number, currency: string, locale?: string): string;
+/**
+ * Scale a line's quoted tax/discount to an edited quantity.
+ *
+ * MUST match `scaleLineCharges` in @commerce/quotes — the server recomputes
+ * the accepted total with this rule, and any divergence shows the buyer one
+ * total and charges another.
+ */
+declare function scaleLineCharges(item: {
+    quantity: number;
+    taxAmount: number;
+    discountAmount: number;
+}, quantity: number): {
+    taxAmount: number;
+    discountAmount: number;
+};
+/** Effective total for a selection, using the same math the server will apply. */
+declare function computeSelectionTotal(items: Array<{
+    id: string;
+    unitPrice: number;
+    quantity: number;
+    taxAmount: number;
+    discountAmount: number;
+    optional: boolean;
+}>, selections: Record<string, {
+    selected: boolean;
+    quantity: number;
+}>, shippingTotal?: number): number;
+
+/**
+ * Every failure from the quote-link routes surfaces as this. The `code` is the
+ * API's own error code, so callers can branch on the ones that matter to a
+ * buyer flow rather than parsing messages:
+ *
+ *   revision_superseded  — a newer revision was issued; `details.currentRevisionId`
+ *                          tells you what to reload
+ *   quote_expired        — the offer lapsed (HTTP 410)
+ *   invalid_item_selection — locked-line edit, non-optional deselect, or unknown item
+ *   accept_in_progress   — a concurrent accept won; retry shortly
+ *   not_found            — unknown/rotated token, or a draft/archived quote
+ */
+declare class ThrottleQuotesError extends ThrottleError {
+    constructor(args: {
+        code: string;
+        message: string;
+        statusCode: number;
+        details?: unknown;
+    });
+    /** The offer moved on — reload and show the buyer the current revision. */
+    get isSuperseded(): boolean;
+    get isExpired(): boolean;
+    /** Revision the server considers current, when it told us (spec §8.1). */
+    get currentRevisionId(): string | undefined;
+}
+
+interface UseQuoteResult {
+    quote: BuyerQuote | null;
+    loading: boolean;
+    error: ThrottleQuotesError | null;
+    /** Re-fetch — call after a `revision_superseded` to show the current offer. */
+    refresh: () => Promise<void>;
+    /** Buyer's current line choices, keyed by item id. */
+    selections: Record<string, {
+        selected: boolean;
+        quantity: number;
+    }>;
+    setSelected: (itemId: string, selected: boolean) => void;
+    setQuantity: (itemId: string, quantity: number) => void;
+    /** Live total for the current selections, using the server's own math. */
+    total: number;
+    accept: (input: Omit<AcceptQuoteInput, 'revisionId' | 'itemSelections'>) => Promise<{
+        checkoutUrl: string;
+    }>;
+    requestRevision: (message: string, authorName?: string) => Promise<void>;
+    decline: (reason?: string, authorName?: string) => Promise<void>;
+    addComment: (body: string, authorName?: string) => Promise<void>;
+    pdfUrl: string;
+    submitting: boolean;
+}
+/**
+ * Everything the buyer quote page needs.
+ *
+ * Fires the view beacon once per mount, keeps line selections in local state,
+ * and recomputes the total with the same rule the server applies at
+ * acceptance — so the number the buyer sees is the number they are charged.
+ */
+declare function useQuote(token: string, options?: QuotesClientOptions): UseQuoteResult;
+interface UseQuoteRequestFormResult {
+    config: RequestFormConfig | null;
+    loading: boolean;
+    error: ThrottleQuotesError | null;
+    submitting: boolean;
+    submitted: boolean;
+    submit: (input: SubmitQuoteRequestInput) => Promise<void>;
+    /** Mount time; pass through so the API's minimum-fill-time check passes. */
+    formLoadedAt: number;
+}
+/** Loads a hosted RFQ form's config and submits it, with bot fields handled. */
+declare function useQuoteRequestForm(formToken: string, options?: QuotesClientOptions): UseQuoteRequestFormResult;
+
+interface QuoteViewProps {
+    /** The `qtl_…` token from the buyer's link. */
+    token: string;
+    options?: QuotesClientOptions;
+    /**
+     * Where to send the buyer after acceptance. Defaults to assigning
+     * `window.location.href`, which is what the hosted page does.
+     */
+    onCheckout?: (checkoutUrl: string) => void;
+    /** Rendered instead of the built-in markup while loading. */
+    loadingFallback?: ReactNode;
+    className?: string;
+}
+/**
+ * Drop-in buyer quote page: line items with optional toggles and quantity
+ * editing, live totals, revision history, comment thread, and the
+ * accept / request-changes / decline actions.
+ *
+ * Intentionally unstyled beyond a readable default — it is meant to be
+ * restyled or replaced. `useQuote` carries all the behaviour if you want to
+ * build your own presentation.
+ */
+declare function QuoteView({ token, options, onCheckout, loadingFallback, className }: QuoteViewProps): react_jsx_runtime.JSX.Element;
+
+interface QuoteRequestFormProps {
+    /** The `qrf_…` token from the merchant's hosted form URL. */
+    formToken: string;
+    options?: QuotesClientOptions;
+    /**
+     * Turnstile token, when the form requires it. Render the widget yourself and
+     * pass its token through — this package deliberately pulls in no Cloudflare
+     * script. If `config.fields.requireTurnstile` is set and this is empty, the
+     * API fails the submission closed.
+     */
+    turnstileToken?: string;
+    onSubmitted?: () => void;
+    loadingFallback?: ReactNode;
+    className?: string;
+}
+/**
+ * Hosted RFQ intake form.
+ *
+ * Bot protection is wired in for you: the honeypot field and the mount-time
+ * anchor that feeds the API's minimum-fill-time check. A honeypot hit returns
+ * 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;
+
+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 };