@aranova/tracking-react 0.12.0 → 0.12.2

package/README.md

@@ -14,7 +14,7 @@ Create one shared tracking module and import the scoped `TrackingProvider` / `us
 
 ```ts
 // src/lib/tracking.ts
-import { createTracking } from '@aranova/tracking-react';
+import { createTracking } from "@aranova/tracking-react";
 
 export const { TrackingProvider, useTracking } = createTracking({
   apiKey: import.meta.env.VITE_ARANOVA_TRACKING_API_KEY,
@@ -24,7 +24,7 @@ export const { TrackingProvider, useTracking } = createTracking({
       page_view: {},
       time_on_site: { thresholdSeconds: 60 },
       specific_page_visit: {
-        pages: [{ name: 'contact_page', pathPattern: /^\/(contact|book|get-started)/ }],
+        pages: [{ name: "contact_page", pathPattern: /^\/(contact|book|get-started)/ }],
       },
     },
     manual: {
@@ -33,7 +33,7 @@ export const { TrackingProvider, useTracking } = createTracking({
       cta_click: {},
     },
   },
-  debug: import.meta.env.MODE !== 'production',
+  debug: import.meta.env.MODE !== "production",
 });
 ```
 
@@ -41,11 +41,11 @@ Mount the provider at the root of your React tree.
 
 ```tsx
 // src/main.tsx
-import { createRoot } from 'react-dom/client';
-import { App } from './App';
-import { TrackingProvider } from './lib/tracking';
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+import { TrackingProvider } from "./lib/tracking";
 
-createRoot(document.getElementById('root')!).render(
+createRoot(document.getElementById("root")!).render(
   <TrackingProvider gtagId={import.meta.env.VITE_GTAG_ID}>
     <App />
   </TrackingProvider>,
@@ -59,7 +59,7 @@ account plus a test MCC. Each entry fires `gtag('config', …)` on every page; t
 the dashboard's SDK table. Stamp events with `environment` to filter out test traffic.
 
 ```tsx
-<TrackingProvider gtagIds={{ production: 'AW-111111111', test: 'AW-222222222' }}>
+<TrackingProvider gtagIds={{ production: "AW-111111111", test: "AW-222222222" }}>
   <App />
 </TrackingProvider>
 ```
@@ -69,7 +69,7 @@ the dashboard's SDK table. Stamp events with `environment` to filter out test tr
 Manual events must be registered under `triggers.manual` before `trackEvent()` accepts them.
 
 ```tsx
-import { useTracking } from './lib/tracking';
+import { useTracking } from "./lib/tracking";
 
 export function LeadForm() {
   const tracking = useTracking();
@@ -78,22 +78,22 @@ export function LeadForm() {
     const form = event.currentTarget;
     const data = new FormData(form);
 
-    tracking.trackEvent('form_submit', {
+    tracking.trackEvent("form_submit", {
       form: {
         id: form.id,
-        action: form.getAttribute('action'),
+        action: form.getAttribute("action"),
         fields: [
           {
-            name: 'service_interest',
-            type: 'select',
-            label: 'Service interest',
-            value: String(data.get('service_interest') ?? ''),
+            name: "service_interest",
+            type: "select",
+            label: "Service interest",
+            value: String(data.get("service_interest") ?? ""),
           },
           {
-            name: 'is_existing_patient',
-            type: 'checkbox',
-            label: 'Existing patient',
-            value: data.get('is_existing_patient') === 'on',
+            name: "is_existing_patient",
+            type: "checkbox",
+            label: "Existing patient",
+            value: data.get("is_existing_patient") === "on",
           },
         ],
       },
@@ -101,17 +101,21 @@ export function LeadForm() {
     });
   }
 
-  return <form id="lead-form" action="/api/lead" onSubmit={handleSubmit}>{/* fields */}</form>;
+  return (
+    <form id="lead-form" action="/api/lead" onSubmit={handleSubmit}>
+      {/* fields */}
+    </form>
+  );
 }
 ```
 
 `fields[].value` can be any JSON value: string, number, boolean, null, array, or object. Values must be JSON-serializable because events are stored as JSONB. Only send reviewed, allowlisted, non-sensitive values; do not send names, emails, phone numbers entered by the visitor, addresses, payment data, medical details, passwords, file contents, or free-text messages.
 
 ```tsx
-tracking.trackEvent('phone_click', {
-  phone_number: '+14165550199',
+tracking.trackEvent("phone_click", {
+  phone_number: "+14165550199",
   page: { path: window.location.pathname },
-  section: 'header',
+  section: "header",
 });
 ```
 
@@ -121,12 +125,12 @@ Bundled `libphonenumber-js`: parse/format utils + a React input. Display is conf
 value sent to the backend is **always E.164**. Configure once via `createTracking({ phone: { defaultCountry: 'CA', display: 'national' } })`.
 
 ```tsx
-import { usePhoneField, PhoneField, toE164 } from '@aranova/tracking-react';
+import { usePhoneField, PhoneField, toE164 } from "@aranova/tracking-react";
 
-const phone = usePhoneField();          // phone.value (display), phone.e164 (wire), .isValid, .error
-<input {...phone.inputProps} />;        // or the batteries-included <PhoneField name="phone" />
+const phone = usePhoneField(); // phone.value (display), phone.e164 (wire), .isValid, .error
+<input {...phone.inputProps} />; // or the batteries-included <PhoneField name="phone" />
 
-toE164('416-555-0199');                  // '+14165550199' (null if invalid)
+toE164("416-555-0199"); // '+14165550199' (null if invalid)
 ```
 
 Pure, isomorphic utils are also at `@aranova/tracking-react/phone` (no React). Full guide:
@@ -142,19 +146,23 @@ key may do is enforced by the backend, not by hiding methods. Browser write with
 your **public** key:
 
 ```tsx
-import { createSalesClient, toMinor } from '@aranova/tracking-react';
+import { createSalesClient, toMinor } from "@aranova/tracking-react";
 
-const sales = createSalesClient({ apiKey: import.meta.env.VITE_ARANOVA_TRACKING_API_KEY, endpoint });
-await sales.record({ currency: 'CAD', amount_total_cents: toMinor(250, 'CAD'), service: 'tires' });
+const sales = createSalesClient({
+  apiKey: import.meta.env.VITE_ARANOVA_TRACKING_API_KEY,
+  endpoint,
+});
+await sales.record({ currency: "CAD", amount_total_cents: toMinor(250, "CAD"), service: "tires" });
 ```
 
 Reads / full CRUD require a **secret** key and must run server-side — never ship a
 secret key in the browser bundle. In a Vite + Vercel app, hold it in a serverless
-function (same import, secret key):
+function. Import from the **`/sales`** subpath — it's React-free, so the server
+bundle never pulls in the provider/components:
 
 ```ts
 // api/sales.ts  (Vercel serverless function — runs on the server)
-import { createSalesClient } from '@aranova/tracking-react';
+import { createSalesClient } from "@aranova/tracking-react/sales";
 
 const sales = createSalesClient({
   apiKey: process.env.ARANOVA_TRACKING_SECRET_KEY!,
@@ -168,17 +176,21 @@ export default async function handler(_req, res) {
 Secret-key reads power dashboards (all currency-grouped — never summed across currencies):
 
 ```ts
-await sales.summary({ range: 'mtd', timezone: 'America/Toronto', compare_to: 'previous_period' });
-await sales.list({ sort: 'amount_total_cents', want_total: true });   // → { items, total_count, … }
-await sales.customers.list({ segment: 'returning', sort: 'total_spent' });   // phone-keyed roster
-await sales.customers.summary({ range: 'mtd' });
-const cfg = await sales.business.config();   // tz / currencies / services (pk or sk)
+await sales.summary({ range: "mtd", timezone: "America/Toronto", compare_to: "previous_period" });
+await sales.list({ sort: "amount_total_cents", want_total: true }); // → { items, total_count, … }
+await sales.customers.list({ segment: "returning", sort: "total_spent" }); // phone-keyed roster
+await sales.customers.summary({ range: "mtd" });
+const cfg = await sales.business.config(); // tz / currencies / services (pk or sk)
 ```
 
 `summary()` gains tz-aware calendar/custom ranges, `granularity`, and period-over-period
 `compare_to`; legacy `24h/7d/30d` are unchanged. A **customer is their phone (E.164)** — `customers.*`
 is a live roster, no separate table. A public-key client calling any read gets a `403`.
 
+The root entry (`@aranova/tracking-react`) still re-exports `createSalesClient` and the
+money/date helpers for back-compat, so existing imports keep working — but prefer `/sales`
+in server code so the React surface never reaches your server bundle.
+
 Generate the typed `AranovaService` union from your dashboard services with the CLI
 (install it as a **devDependency**):
 
@@ -195,10 +207,10 @@ and the CLI reference: [cli.md](https://github.com/AranovaIO/aranova_internal/bl
 The bundled `<ConsentBanner />` renders a non-blocking bottom-docked banner while consent is `pending`, persists the visitor's choice to `localStorage`, and propagates it to Google Consent Mode v2 when gtag is loaded. **Inline-styled** — no Tailwind or CSS imports required at the consumer.
 
 ```tsx
-import { ConsentBanner } from '@aranova/tracking-react';
+import { ConsentBanner } from "@aranova/tracking-react";
 
 // Drop-in, defaults work everywhere
-<ConsentBanner />
+<ConsentBanner />;
 ```
 
 All props are optional:
@@ -210,13 +222,13 @@ All props are optional:
   acceptLabel="Sure"
   declineLabel="No thanks"
   policyHref="/privacy"
-  policyLabel="Privacy policy"          // default: "Learn more"
-  onAccept={() => track('consent_accepted')}
-  onDecline={() => track('consent_declined')}
-  position="bottom"                      // or "top"
-  theme="light"                          // "light" | "dark" | "auto"
+  policyLabel="Privacy policy" // default: "Learn more"
+  onAccept={() => track("consent_accepted")}
+  onDecline={() => track("consent_declined")}
+  position="bottom" // or "top"
+  theme="light" // "light" | "dark" | "auto"
   className="my-extra-classes"
-  style={{ background: '#fafafa' }}      // wins over the theme defaults
+  style={{ background: "#fafafa" }} // wins over the theme defaults
 />
 ```
 
@@ -225,7 +237,7 @@ All props are optional:
 For a bespoke banner, skip the component and drive your own UI with the headless hook:
 
 ```tsx
-import { useConsent } from '@aranova/tracking-react';
+import { useConsent } from "@aranova/tracking-react";
 
 function CookieBar() {
   const { state, accept, decline, reset, isPending } = useConsent();
@@ -254,8 +266,7 @@ The hook handles localStorage persistence, gtag sync, and cross-tab propagation
 - Consent hooks: `useConsent()` + `UseConsentResult` (headless); `useConsentState()` (read-only alias)
 - Standalone consent helpers: `getConsentState()`, `setConsentState()`, `resetConsent()`
 - Attribution hooks: `useTrackingParams()`, `useGclid()`
-- `createSalesClient()` (isomorphic — public key writes; secret key reads/CRUD, `summary`, `customers.*`, `business.config`) + money/date helpers (`toMinor`/`fromMinor`/`formatMoney`/`formatDateInTz`)
+- `createSalesClient()` (isomorphic — public key writes; secret key reads/CRUD, `summary`, `customers.*`, `business.config`) + money/date helpers (`toMinor`/`fromMinor`/`formatMoney`/`formatDateInTz`). Also available React-free at **`@aranova/tracking-react/sales`** (with all sale/customer/config types) — the recommended import for server/serverless code.
 - Phone: `parsePhone`/`toE164`/`formatPhone`/`formatPhoneAsTyped`/`phoneField`, `usePhoneField`, `PhoneField` (utils also at `/phone`)
 - Codegen: [`@aranova/tracking-cli`](https://www.npmjs.com/package/@aranova/tracking-cli) — `gen` typed service unions (devDependency)
 - Event metadata/config types such as `FormSubmitMetadata`, `PhoneClickMetadata`, and `JsonValue`
-