@usethrottle/quotes 0.1.0

package/README.md

@@ -0,0 +1,150 @@
+# @usethrottle/quotes
+
+Buyer-facing React components, hooks and a same-origin server proxy for
+[Throttle](https://usethrottle.dev) B2B quotes — the hosted quote link and the
+RFQ request form.
+
+This is the **buyer** half of quotes. Merchant-side operations (create, price,
+issue, revise, record acceptance) live in
+[`@usethrottle/api-client`](https://www.npmjs.com/package/@usethrottle/api-client)'s
+`QuotesService`, which needs a secret key and must stay server-side.
+
+```bash
+npm install @usethrottle/quotes
+```
+
+## The buyer quote page
+
+A quote link is `/(your route)/:token`, where the token is the `qtl_…` value
+from the buyer's email. The token is the only credential — there is no API key
+in the browser.
+
+```tsx
+import { QuoteView } from '@usethrottle/quotes';
+
+export default function QuotePage({ params }: { params: { token: string } }) {
+  return <QuoteView token={params.token} />;
+}
+```
+
+`QuoteView` renders line items with optional toggles and editable quantities,
+live totals, revision history, the comment thread, and the accept /
+request-changes / decline actions. On acceptance it sends the buyer to Throttle
+hosted checkout.
+
+The default markup is intentionally plain. For your own presentation, use the
+hook and render whatever you like:
+
+```tsx
+import { useQuote, formatMoney } from '@usethrottle/quotes';
+
+function MyQuote({ token }: { token: string }) {
+  const { quote, total, selections, setQuantity, setSelected, accept, error } = useQuote(token);
+  if (!quote) return null;
+
+  return (
+    <>
+      {quote.currentRevision?.items.map((item) => (
+        <Row
+          key={item.id}
+          item={item}
+          state={selections[item.id]}
+          onQty={(q) => setQuantity(item.id, q)}
+          onToggle={(on) => setSelected(item.id, on)}
+        />
+      ))}
+      <strong>{formatMoney(total, quote.currency)}</strong>
+      <button onClick={() => accept({ acceptedByName: 'Ada', acceptedByEmail: 'ada@example.com' })}>
+        Accept
+      </button>
+    </>
+  );
+}
+```
+
+`useQuote` fires the view beacon once per mount, seeds selections from the
+revision's own defaults, and computes `total` with **the same rule the server
+applies at acceptance** — including scaling a line's tax and discount pro-rata
+when the buyer changes its quantity. Keep using `total` rather than summing the
+lines yourself, or the number you show may not be the number charged.
+
+## Errors worth handling
+
+Everything throws `ThrottleQuotesError` carrying the API's own `code`:
+
+| code | meaning |
+| --- | --- |
+| `revision_superseded` | A newer revision was issued. `error.currentRevisionId` names it; `useQuote` auto-refreshes. |
+| `quote_expired` | The offer lapsed. Show "request updated pricing". |
+| `invalid_item_selection` | A locked line's quantity was changed, a required line deselected, or an unknown item sent. |
+| `accept_in_progress` | A concurrent accept won the race; retry shortly. |
+| `not_found` | Unknown or rotated token, or a draft/archived quote. |
+
+```ts
+import { ThrottleQuotesError } from '@usethrottle/quotes';
+
+try {
+  await accept({ acceptedByName, acceptedByEmail });
+} catch (e) {
+  if (e instanceof ThrottleQuotesError && e.isExpired) showExpiredNotice();
+}
+```
+
+## RFQ request form
+
+```tsx
+import { QuoteRequestForm } from '@usethrottle/quotes';
+
+<QuoteRequestForm formToken={params.formToken} />;
+```
+
+Bot protection is wired in: 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 — by design, so a bot cannot learn
+it was caught. Treat submission success as "accepted", not "created".
+
+If the form requires Cloudflare Turnstile, render the widget yourself and pass
+its token — this package pulls in no third-party script:
+
+```tsx
+<QuoteRequestForm formToken={token} turnstileToken={turnstileToken} />
+```
+
+## Same-origin proxy (optional)
+
+Quote links work fine calling Throttle directly. Proxy through your own origin
+if you'd rather not have a third-party host in the address bar or CSP:
+
+```ts
+// app/api/throttle/[...path]/route.ts
+import { createQuoteProxyHandler } from '@usethrottle/quotes/server';
+
+const handler = createQuoteProxyHandler();
+export { handler as GET, handler as POST };
+```
+
+```tsx
+<QuoteView token={token} options={{ baseUrl: 'https://yourshop.com/api/throttle' }} />
+```
+
+The proxy forwards no API key — the buyer's token is the only credential. It
+allow-lists the public quote paths, so it cannot be pointed at a merchant
+endpoint, and forwards `x-forwarded-for` so acceptance evidence and per-IP
+limits attribute to the real buyer.
+
+## Payment terms
+
+A quote carries one of three terms, on `currentRevision.paymentTerms`:
+
+- `pay_in_full` — card at checkout
+- `net_terms` — invoice due in `netN` days
+- `deposit_balance` — `depositAmount` charged today by card, the remainder
+  invoiced `balanceNetN` days out
+
+`depositAmount` is frozen when the rep issues the quote, so it does not move
+when the buyer edits quantities. Selections that would drop the total to or
+below the deposit are rejected with `invalid_item_selection`.
+
+## License
+
+MIT