@aranova/tracking-react 0.11.0 → 0.12.1

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>,
@@ -54,36 +54,22 @@ createRoot(document.getElementById('root')!).render(
 
 ### Multiple gtag IDs
 
-To install multiple Google Ads tags simultaneously (for example a production MCC and a test MCC for verifying conversion actions before they touch the live account), pass `gtagIds` instead of `gtagId`. Every entry fires `gtag('config', ...)` on every page — gtag natively supports multiple configured tags.
+Pass `gtagIds` (instead of `gtagId`) to install several Google Ads tags at once — e.g. a real
+account plus a test MCC. Each entry fires `gtag('config', …)` on every page; the labels surface in
+the dashboard's SDK table. Stamp events with `environment` to filter out test traffic.
 
 ```tsx
-<TrackingProvider
-  gtagIds={{
-    production: 'AW-111111111',  // real client account
-    test: 'AW-222222222',         // test MCC for development
-  }}
->
+<TrackingProvider gtagIds={{ production: "AW-111111111", test: "AW-222222222" }}>
   <App />
 </TrackingProvider>
 ```
 
-The labels are arbitrary and surface in the Aranova dashboard's SDK versions table. You can also stamp events with a deployment environment so the dashboard can filter out test traffic:
-
-```ts
-createTracking({
-  apiKey: import.meta.env.VITE_ARANOVA_TRACKING_API_KEY,
-  endpoint: import.meta.env.VITE_ARANOVA_TRACKING_ENDPOINT,
-  environment: import.meta.env.MODE,  // 'production' | 'development'
-  triggers: { /* ... */ },
-});
-```
-
 ## Manual Events
 
 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();
@@ -92,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",
           },
         ],
       },
@@ -115,20 +101,41 @@ 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",
 });
 ```
 
+## Phone Fields
+
+Bundled `libphonenumber-js`: parse/format utils + a React input. Display is configurable; the
+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";
+
+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)
+```
+
+Pure, isomorphic utils are also at `@aranova/tracking-react/phone` (no React). Full guide:
+[phone.md](https://github.com/AranovaIO/aranova_internal/blob/master/docs/tracking-package/phone.md).
+
 ## Recording Sales
 
 Record a sale / conversion (a first-class, mutable resource — not a fire-and-forget
@@ -139,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!,
@@ -162,12 +173,23 @@ export default async function handler(_req, res) {
 }
 ```
 
-`sales.summary({ range: '30d' })` returns currency-grouped aggregations (revenue and
-average order value per currency, distinct customers, by-service / by-currency /
-by-category breakdowns, and a revenue/count trend) — also a secret-key read.
+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)
+```
+
+`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`.
 
-A public-key client calling `list`/`summary`/`get`/`update`/`delete` gets a `403`
-telling it to use a secret key server-side.
+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**):
@@ -185,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:
@@ -200,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
 />
 ```
 
@@ -215,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();
@@ -244,7 +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 sales client — public key writes, secret key reads/CRUD) + money helpers (`toMinor`/`fromMinor`/`formatMoney`)
+- `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`
-