@aranova/tracking-react 0.11.0 → 0.12.0

package/README.md

@@ -54,30 +54,16 @@ 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.
@@ -129,6 +115,23 @@ tracking.trackEvent('phone_click', {
 });
 ```
 
+## 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
@@ -162,12 +165,19 @@ 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)
+```
 
-A public-key client calling `list`/`summary`/`get`/`update`/`delete` gets a `403`
-telling it to use a secret key server-side.
+`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`.
 
 Generate the typed `AranovaService` union from your dashboard services with the CLI
 (install it as a **devDependency**):
@@ -244,7 +254,8 @@ 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`)
+- 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`