@aranova/tracking-next 0.12.0 → 0.12.2

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 (
@@ -85,7 +85,7 @@ account plus a test MCC. Each entry fires `gtag('config', …)` on every page; t
 the dashboard's SDK table. Pass `environment` to the factory to tag events for dashboard filtering.
 
 ```tsx
-<GoogleAdsTracking gtagIds={{ production: 'AW-111111111', test: 'AW-222222222' }} />
+<GoogleAdsTracking gtagIds={{ production: "AW-111111111", test: "AW-222222222" }} />
 ```
 
 ## Manual Events
@@ -93,9 +93,9 @@ the dashboard's SDK table. Pass `environment` to the factory to tag events for d
 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();
@@ -108,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",
               },
             ],
           },
@@ -145,11 +145,11 @@ 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
-'use client';
-import { usePhoneField, PhoneField, toE164 } from '@aranova/tracking-next';
+"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" />
+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
@@ -161,11 +161,11 @@ Pure, isomorphic utils (usable in Server Components / route handlers) are at
 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 />;
 }
 ```
 
@@ -179,30 +179,39 @@ 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!,
 });
-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
+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
 ```
 
+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.
+
 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.
@@ -224,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:
@@ -239,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
 />
 ```
 
@@ -254,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();
@@ -278,8 +287,8 @@ The hook handles localStorage persistence, gtag sync, and cross-tab propagation
 ## Exports
 
 - 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)
-