@aranova/tracking-next 0.10.0 → 0.12.0

package/README.md

@@ -80,31 +80,12 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 
 ### 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. Pass `environment` to the factory to tag events for dashboard filtering.
 
 ```tsx
-<GoogleAdsTracking
-  gtagIds={{
-    production: 'AW-111111111',  // real client account
-    test: 'AW-222222222',         // test MCC for development
-  }}
-/>
-```
-
-The labels are arbitrary and surface in the Aranova dashboard's SDK versions table. Also pass `environment` to the factory so events are tagged with the deployment context for dashboard filtering:
-
-```ts
-// lib/tracking.ts
-createTracking({
-  apiKey: process.env.NEXT_PUBLIC_ARANOVA_TRACKING_API_KEY!,
-  endpoint: process.env.NEXT_PUBLIC_ARANOVA_TRACKING_ENDPOINT!,
-  environment: process.env.NEXT_PUBLIC_TRACKING_ENVIRONMENT,  // 'production' | 'development'
-  gtagIds: {  // optional — reports the configured tags in heartbeat metadata
-    production: process.env.NEXT_PUBLIC_GTAG_PROD!,
-    test: process.env.NEXT_PUBLIC_GTAG_TEST!,
-  },
-  triggers: { /* ... */ },
-});
+<GoogleAdsTracking gtagIds={{ production: 'AW-111111111', test: 'AW-222222222' }} />
 ```
 
 ## Manual Events
@@ -158,6 +139,23 @@ export function LeadForm() {
 
 `fields[].value` can be any JSON value: string, number, boolean, null, array, or object. 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.
 
+## 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
+'use client';
+import { usePhoneField, PhoneField, toE164 } from '@aranova/tracking-next';
+
+const phone = usePhoneField();          // phone.value (display), phone.e164 (wire), .isValid, .error
+<input {...phone.inputProps} />;        // or the batteries-included <PhoneField name="phone" />
+```
+
+Pure, isomorphic utils (usable in Server Components / route handlers) are at
+`@aranova/tracking-next/phone`. Full guide:
+[phone.md](https://github.com/AranovaIO/aranova_internal/blob/master/docs/tracking-package/phone.md).
+
 ## Server Reads
 
 Read attribution cookies from Server Components or server actions.
@@ -199,16 +197,16 @@ const sales = createSalesClient<AranovaService>({
   apiKey: process.env.ARANOVA_TRACKING_SECRET_KEY!,
   endpoint: process.env.ARANOVA_TRACKING_ENDPOINT!,
 });
-const { items, next_cursor } = await sales.list({ limit: 50 });
-const summary = await sales.summary({ range: '30d' }); // currency-grouped aggregations
+await sales.list({ sort: 'amount_total_cents', want_total: true });            // → { items, total_count, … }
+await sales.summary({ range: 'mtd', timezone: 'America/Toronto', compare_to: 'previous_period' });
+await sales.customers.list({ segment: 'returning', sort: 'total_spent' });     // phone-keyed roster
+const cfg = await sales.business.config();                                     // tz / currencies / services
 ```
 
-`sales.summary({ range })` returns revenue and average order value per currency,
-distinct customers, by-service / by-currency / by-category breakdowns, and a
-revenue/count trend — a secret-key read scoped to the key's business.
-
-A public-key client calling `list`/`summary`/`get`/`update`/`delete` gets a `403`
-telling it to use a secret key server-side.
+Dashboard reads are all currency-grouped (never summed). `summary()` gains tz-aware calendar/custom
+ranges, `granularity`, and period-over-period `compare_to` (legacy `24h/7d/30d` unchanged); a
+**customer is their phone (E.164)**, so `customers.*` is a live roster with 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**):
@@ -279,8 +277,9 @@ The hook handles localStorage persistence, gtag sync, and cross-tab propagation
 
 ## Exports
 
-- Root package: `createTracking`, `TrackingProvider`, `useTracking`, `GoogleAdsTracking`, `ConsentBanner` (+ `ConsentBannerProps`), `useConsent` (+ `UseConsentResult`), `useConsentState`, `useGclid`, `useTrackingParams`, standalone consent helpers (`getConsentState`, `setConsentState`, `resetConsent`), event types, and `createSalesClient()` (isomorphic sales client — public key writes, secret key reads/CRUD) + money helpers (`toMinor`/`fromMinor`/`formatMoney`)
+- Root package: `createTracking`, `TrackingProvider`, `useTracking`, `GoogleAdsTracking`, `ConsentBanner` (+ `ConsentBannerProps`), consent hooks/helpers, attribution hooks, event types; `createSalesClient()` (isomorphic — public key writes; secret key reads/CRUD, `summary`, `customers.*`, `business.config`) + `toMinor`/`fromMinor`/`formatMoney`/`formatDateInTz`; phone (`parsePhone`/`toE164`/`formatPhone`/`phoneField`, `usePhoneField`, `PhoneField`)
 - `@aranova/tracking-next/middleware`: `createTrackingMiddleware()`
 - `@aranova/tracking-next/server`: `getTrackingParamsServer()`
+- `@aranova/tracking-next/phone`: isomorphic phone utils (no React)
 - Codegen: [`@aranova/tracking-cli`](https://www.npmjs.com/package/@aranova/tracking-cli) — `gen` typed service unions (devDependency)