@aranova/tracking-next 0.11.0 → 0.12.1

package/README.md

@@ -14,12 +14,12 @@ Install the tracking middleware so `gclid`, `fbclid`, and UTM params are written
 
 ```ts
 // middleware.ts
-import { createTrackingMiddleware } from '@aranova/tracking-next/middleware';
+import { createTrackingMiddleware } from "@aranova/tracking-next/middleware";
 
 export default createTrackingMiddleware();
 
 export const config = {
-  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
+  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
 };
 ```
 
@@ -29,7 +29,7 @@ Create one shared tracking module and use its scoped exports throughout your app
 
 ```ts
 // lib/tracking.ts
-import { createTracking } from '@aranova/tracking-next';
+import { createTracking } from "@aranova/tracking-next";
 
 export const { TrackingProvider, useTracking } = createTracking({
   apiKey: process.env.NEXT_PUBLIC_ARANOVA_TRACKING_API_KEY!,
@@ -39,7 +39,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: {
@@ -48,7 +48,7 @@ export const { TrackingProvider, useTracking } = createTracking({
       cta_click: {},
     },
   },
-  debug: process.env.NODE_ENV !== 'production',
+  debug: process.env.NODE_ENV !== "production",
 });
 ```
 
@@ -56,8 +56,8 @@ Wrap the root layout.
 
 ```tsx
 // app/layout.tsx
-import { ConsentBanner, GoogleAdsTracking } from '@aranova/tracking-next';
-import { TrackingProvider } from '@/lib/tracking';
+import { ConsentBanner, GoogleAdsTracking } from "@aranova/tracking-next";
+import { TrackingProvider } from "@/lib/tracking";
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
@@ -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
@@ -112,9 +93,9 @@ createTracking({
 Import `useTracking` from your local `lib/tracking` module, not directly from the package.
 
 ```tsx
-'use client';
+"use client";
 
-import { useTracking } from '@/lib/tracking';
+import { useTracking } from "@/lib/tracking";
 
 export function LeadForm() {
   const tracking = useTracking();
@@ -127,22 +108,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",
               },
             ],
           },
@@ -158,16 +139,33 @@ 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.
 
 ```tsx
-import { getTrackingParamsServer } from '@aranova/tracking-next/server';
+import { getTrackingParamsServer } from "@aranova/tracking-next/server";
 
 export default function Page() {
   const { gclid, utm_source } = getTrackingParamsServer();
-  return gclid || utm_source === 'google' ? <GoogleLanding /> : <OrganicLanding />;
+  return gclid || utm_source === "google" ? <GoogleLanding /> : <OrganicLanding />;
 }
 ```
 
@@ -181,34 +179,43 @@ key may do is enforced by the backend, not by hiding methods. Browser write with
 your **public** key, from a client component:
 
 ```tsx
-'use client';
-import { createSalesClient, toMinor } from '@aranova/tracking-next';
+"use client";
+import { createSalesClient, toMinor } from "@aranova/tracking-next";
 
-const sales = createSalesClient({ apiKey: process.env.NEXT_PUBLIC_ARANOVA_TRACKING_API_KEY!, endpoint });
-await sales.record({ currency: 'CAD', amount_total_cents: toMinor(250, 'CAD'), service: 'tires' });
+const sales = createSalesClient({
+  apiKey: process.env.NEXT_PUBLIC_ARANOVA_TRACKING_API_KEY!,
+  endpoint,
+});
+await sales.record({ currency: "CAD", amount_total_cents: toMinor(250, "CAD"), service: "tires" });
 ```
 
-Full CRUD from a route handler / server action with your **secret** key (same
-import — keep the secret key in server env, never in client code):
+Full CRUD from a route handler / server action / **Server Component** with your
+**secret** key. Import from the **`/sales`** subpath — it's React-free, so it loads
+in an RSC or any server module without dragging the provider/components into the
+server graph (keep the secret key in server env, never in client code):
 
 ```ts
-import { createSalesClient } from '@aranova/tracking-next';
-import type { AranovaService } from './aranova-services'; // generated, see below
+import { createSalesClient } from "@aranova/tracking-next/sales";
+import type { AranovaService } from "./aranova-services"; // generated, see below
 
 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.
+The root entry (`@aranova/tracking-next`) 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.
 
-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**):
@@ -226,10 +233,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-next';
+import { ConsentBanner } from "@aranova/tracking-next";
 
 // Drop-in (already wired in the root layout example above)
-<ConsentBanner />
+<ConsentBanner />;
 ```
 
 All props are optional:
@@ -241,13 +248,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
 />
 ```
 
@@ -256,8 +263,8 @@ All props are optional:
 For a bespoke banner, skip the component and drive your own UI with the headless hook:
 
 ```tsx
-'use client';
-import { useConsent } from '@aranova/tracking-next';
+"use client";
+import { useConsent } from "@aranova/tracking-next";
 
 function CookieBar() {
   const { state, accept, decline, reset, isPending } = useConsent();
@@ -279,8 +286,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/sales`: **React-free** server-safe SDK — `createSalesClient`, money/date helpers, and all sale/customer/config types. Use this in Server Components, route handlers, and Node servers; the root entry re-exports the same symbols for back-compat.
 - `@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)
-