@rovela-ai/sdk 0.4.3 → 0.5.0

package/dist/analytics/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @rovela-ai/sdk/analytics
+ *
+ * Storefront analytics module — internal GA4-shaped event tracker. See
+ * CLAUDE.md §46 for architecture.
+ *
+ * Public entry points:
+ *
+ *  - `<AnalyticsProvider>` — mount inside the customer branch of
+ *    LayoutContent.tsx. Auto-fires page_view + session_start, gates on
+ *    cookie consent, excludes admin sessions.
+ *  - `useAnalytics()` — storefront-component hook for manual events
+ *    (add_to_cart, begin_checkout, etc.).
+ *  - `<AnalyticsDashboard>` — admin dashboard UI, mount at
+ *    app/admin/(dashboard)/analytics/page.tsx.
+ *
+ * Sub-paths:
+ *  - `@rovela-ai/sdk/analytics/server` — recordEvent, getAnalyticsDashboard,
+ *    getTrafficSummary7d (server-only).
+ *  - `@rovela-ai/sdk/analytics/api/track` — POST handler.
+ *  - `@rovela-ai/sdk/analytics/api/dashboard` — GET handler.
+ */
+export { AnalyticsProvider, useAnalytics } from './components/AnalyticsProvider';
+export type { AnalyticsProviderProps } from './components/AnalyticsProvider';
+export { AnalyticsTabNav } from './components/AnalyticsTabNav';
+export type { AnalyticsTabNavProps } from './components/AnalyticsTabNav';
+export { AnalyticsPeriodProvider, useAnalyticsPeriod, } from './components/AnalyticsPeriodContext';
+export type { AnalyticsPeriodProviderProps } from './components/AnalyticsPeriodContext';
+export { DashboardsView } from './views/DashboardsView';
+export type { DashboardsViewProps } from './views/DashboardsView';
+export { EventsView } from './views/EventsView';
+export type { EventsViewProps } from './views/EventsView';
+export { VisitorsView } from './views/VisitorsView';
+export type { VisitorsViewProps } from './views/VisitorsView';
+export { AnalyticsDashboard } from './components/AnalyticsDashboard';
+export { useAnalyticsDashboard } from './hooks/useAnalyticsDashboard';
+export type { UseAnalyticsDashboardReturn } from './hooks/useAnalyticsDashboard';
+export { useEventsLog } from './hooks/useEventsLog';
+export type { UseEventsLogOptions, UseEventsLogReturn, } from './hooks/useEventsLog';
+export { useVisitorsList } from './hooks/useVisitorsList';
+export type { UseVisitorsListOptions, UseVisitorsListReturn, } from './hooks/useVisitorsList';
+export { emitEvent, getVisitorId, getSessionId } from './client/tracker';
+export type { AnalyticsEventKind, AnalyticsPayload, AnalyticsWireEvent, AnalyticsCommon, AnalyticsIdentity, AnalyticsPeriod, AnalyticsSortDir, AnalyticsOverview, AnalyticsOverviewWithDeltas, AnalyticsTrendPoint, AnalyticsTopPage, AnalyticsTopProduct, AnalyticsSourceBucket, AnalyticsDeviceBucket, AnalyticsDashboardPayload, AnalyticsTrafficSummary, AnalyticsEventLogRow, AnalyticsEventsLogPage, AnalyticsVisitorRow, AnalyticsVisitorsPage, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/analytics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analytics/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAA;AAChF,YAAY,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AAG5E,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAA;AAC9D,YAAY,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAA;AAExE,OAAO,EACL,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,qCAAqC,CAAA;AAC5C,YAAY,EAAE,4BAA4B,EAAE,MAAM,qCAAqC,CAAA;AAEvF,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACvD,YAAY,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AAEjE,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC/C,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAEzD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACnD,YAAY,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAI7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAA;AAEpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAA;AACrE,YAAY,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAA;AAEhF,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACnD,YAAY,EACV,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AACzD,YAAY,EACV,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,yBAAyB,CAAA;AAGhC,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAGxE,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,2BAA2B,EAC3B,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,EACzB,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,SAAS,CAAA"}

package/dist/analytics/index.js

@@ -0,0 +1,39 @@
+/**
+ * @rovela-ai/sdk/analytics
+ *
+ * Storefront analytics module — internal GA4-shaped event tracker. See
+ * CLAUDE.md §46 for architecture.
+ *
+ * Public entry points:
+ *
+ *  - `<AnalyticsProvider>` — mount inside the customer branch of
+ *    LayoutContent.tsx. Auto-fires page_view + session_start, gates on
+ *    cookie consent, excludes admin sessions.
+ *  - `useAnalytics()` — storefront-component hook for manual events
+ *    (add_to_cart, begin_checkout, etc.).
+ *  - `<AnalyticsDashboard>` — admin dashboard UI, mount at
+ *    app/admin/(dashboard)/analytics/page.tsx.
+ *
+ * Sub-paths:
+ *  - `@rovela-ai/sdk/analytics/server` — recordEvent, getAnalyticsDashboard,
+ *    getTrafficSummary7d (server-only).
+ *  - `@rovela-ai/sdk/analytics/api/track` — POST handler.
+ *  - `@rovela-ai/sdk/analytics/api/dashboard` — GET handler.
+ */
+// Client surface
+export { AnalyticsProvider, useAnalytics } from './components/AnalyticsProvider';
+// Tab shell + views (route-per-tab pattern)
+export { AnalyticsTabNav } from './components/AnalyticsTabNav';
+export { AnalyticsPeriodProvider, useAnalyticsPeriod, } from './components/AnalyticsPeriodContext';
+export { DashboardsView } from './views/DashboardsView';
+export { EventsView } from './views/EventsView';
+export { VisitorsView } from './views/VisitorsView';
+// Back-compat: legacy single-page dashboard (now a thin shell over the
+// tab nav + DashboardsView).
+export { AnalyticsDashboard } from './components/AnalyticsDashboard';
+export { useAnalyticsDashboard } from './hooks/useAnalyticsDashboard';
+export { useEventsLog } from './hooks/useEventsLog';
+export { useVisitorsList } from './hooks/useVisitorsList';
+// Low-level client primitives (rare; useful for non-React surfaces)
+export { emitEvent, getVisitorId, getSessionId } from './client/tracker';
+//# sourceMappingURL=index.js.map

package/dist/analytics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/analytics/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,iBAAiB;AACjB,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAA;AAGhF,4CAA4C;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAA;AAG9D,OAAO,EACL,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,qCAAqC,CAAA;AAG5C,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAGvD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAG/C,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAGnD,uEAAuE;AACvE,6BAA6B;AAC7B,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAA;AAEpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAA;AAGrE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAMnD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAMzD,oEAAoE;AACpE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/analytics/server/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @rovela-ai/sdk/analytics/server
+ *
+ * Server-only entry point. Re-exports the read/write helpers + normalizers.
+ * Safe to import from API routes, webhook handlers, and platform-side code.
+ */
+export { recordEvent, getAnalyticsDashboard, getTrafficSummary7d, getEventsLog, getVisitorsList, periodToDays, } from './queries';
+export type { GetEventsLogOptions, GetVisitorsListOptions, } from './queries';
+export { isBotUserAgent, deviceFromUserAgent, referrerHost, normalizePath, clip, safeCountry, } from './normalize';
+//# sourceMappingURL=index.d.ts.map

package/dist/analytics/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/analytics/server/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,mBAAmB,EACnB,YAAY,EACZ,eAAe,EACf,YAAY,GACb,MAAM,WAAW,CAAA;AAElB,YAAY,EACV,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,IAAI,EACJ,WAAW,GACZ,MAAM,aAAa,CAAA"}

package/dist/analytics/server/index.js

@@ -0,0 +1,9 @@
+/**
+ * @rovela-ai/sdk/analytics/server
+ *
+ * Server-only entry point. Re-exports the read/write helpers + normalizers.
+ * Safe to import from API routes, webhook handlers, and platform-side code.
+ */
+export { recordEvent, getAnalyticsDashboard, getTrafficSummary7d, getEventsLog, getVisitorsList, periodToDays, } from './queries';
+export { isBotUserAgent, deviceFromUserAgent, referrerHost, normalizePath, clip, safeCountry, } from './normalize';
+//# sourceMappingURL=index.js.map

package/dist/analytics/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/analytics/server/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,mBAAmB,EACnB,YAAY,EACZ,eAAe,EACf,YAAY,GACb,MAAM,WAAW,CAAA;AAOlB,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,IAAI,EACJ,WAAW,GACZ,MAAM,aAAa,CAAA"}

package/dist/analytics/server/normalize.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @rovela-ai/sdk/analytics/server/normalize
+ *
+ * Server-side normalizers for analytics event ingest. All pure functions —
+ * no I/O, no DB, no side effects. The track endpoint pipes the incoming
+ * request through these before INSERT to:
+ *
+ *  - Strip PII (raw UA never stored, only device family)
+ *  - Bound cardinality (referrer to host only, path to pathname only)
+ *  - Reject bot traffic (cheap UA-pattern check)
+ */
+export declare function isBotUserAgent(ua: string | null | undefined): boolean;
+/** Derive coarse device family from UA. Returns null if UA is empty. */
+export declare function deviceFromUserAgent(ua: string | null | undefined): 'mobile' | 'desktop' | 'tablet' | null;
+/** Strip a URL to its host. Returns null for empty / unparsable input. */
+export declare function referrerHost(referrer: string | null | undefined): string | null;
+/** Drop query string + hash; keep pathname only. Cardinality-bounded. */
+export declare function normalizePath(path: string | null | undefined): string;
+/** Truncate any free-text field to a safe upper bound. */
+export declare function clip(s: string | null | undefined, max?: number): string | null;
+/** ISO-3166-1 alpha-2 sanity check. Returns null for anything else. */
+export declare function safeCountry(c: string | null | undefined): string | null;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/analytics/server/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../../src/analytics/server/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAGrE;AAED,wEAAwE;AACxE,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC5B,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,IAAI,CAQxC;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAQ/E;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAarE;AAED,0DAA0D;AAC1D,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,SAAM,GAAG,MAAM,GAAG,IAAI,CAG3E;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAIvE"}

package/dist/analytics/server/normalize.js

@@ -0,0 +1,75 @@
+/**
+ * @rovela-ai/sdk/analytics/server/normalize
+ *
+ * Server-side normalizers for analytics event ingest. All pure functions —
+ * no I/O, no DB, no side effects. The track endpoint pipes the incoming
+ * request through these before INSERT to:
+ *
+ *  - Strip PII (raw UA never stored, only device family)
+ *  - Bound cardinality (referrer to host only, path to pathname only)
+ *  - Reject bot traffic (cheap UA-pattern check)
+ */
+/** Conservative UA regex — catches the long-tail without being aggressive
+ *  enough to false-positive on real visitors. We accept some noise rather
+ *  than miss real merchants browsing on niche mobile browsers. */
+const BOT_UA = /bot|crawler|spider|HeadlessChrome|Lighthouse|preview|monitor|pingdom|gtmetrix/i;
+export function isBotUserAgent(ua) {
+    if (!ua)
+        return true; // empty UA is almost always a bot
+    return BOT_UA.test(ua);
+}
+/** Derive coarse device family from UA. Returns null if UA is empty. */
+export function deviceFromUserAgent(ua) {
+    if (!ua)
+        return null;
+    // Order matters — iPad UA contains "Mobile" historically, so tablet must win.
+    if (/iPad|Tablet|PlayBook|(?:Android(?!.*Mobile))/i.test(ua))
+        return 'tablet';
+    if (/Mobile|iP(hone|od)|Android|BlackBerry|IEMobile|Kindle|Silk|Opera M(ob|in)i/i.test(ua)) {
+        return 'mobile';
+    }
+    return 'desktop';
+}
+/** Strip a URL to its host. Returns null for empty / unparsable input. */
+export function referrerHost(referrer) {
+    if (!referrer || referrer.length === 0)
+        return null;
+    try {
+        const url = new URL(referrer);
+        return url.host || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Drop query string + hash; keep pathname only. Cardinality-bounded. */
+export function normalizePath(path) {
+    if (!path)
+        return '/';
+    try {
+        // URL parser is more permissive than splitting on '?' — handles cases like
+        // accidentally-included full URLs.
+        const url = new URL(path, 'http://_');
+        return url.pathname || '/';
+    }
+    catch {
+        // Manual split fallback for malformed strings.
+        const noQuery = path.split('?')[0];
+        const noHash = noQuery.split('#')[0];
+        return noHash || '/';
+    }
+}
+/** Truncate any free-text field to a safe upper bound. */
+export function clip(s, max = 500) {
+    if (!s)
+        return null;
+    return s.length > max ? s.slice(0, max) : s;
+}
+/** ISO-3166-1 alpha-2 sanity check. Returns null for anything else. */
+export function safeCountry(c) {
+    if (!c || c.length !== 2)
+        return null;
+    const up = c.toUpperCase();
+    return /^[A-Z]{2}$/.test(up) ? up : null;
+}
+//# sourceMappingURL=normalize.js.map

package/dist/analytics/server/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../../src/analytics/server/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;kEAEkE;AAClE,MAAM,MAAM,GAAG,gFAAgF,CAAA;AAE/F,MAAM,UAAU,cAAc,CAAC,EAA6B;IAC1D,IAAI,CAAC,EAAE;QAAE,OAAO,IAAI,CAAA,CAAC,kCAAkC;IACvD,OAAO,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;AACxB,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,mBAAmB,CACjC,EAA6B;IAE7B,IAAI,CAAC,EAAE;QAAE,OAAO,IAAI,CAAA;IACpB,8EAA8E;IAC9E,IAAI,+CAA+C,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,QAAQ,CAAA;IAC7E,IAAI,6EAA6E,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QAC3F,OAAO,QAAQ,CAAA;IACjB,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,YAAY,CAAC,QAAmC;IAC9D,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACnD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAA;QAC7B,OAAO,GAAG,CAAC,IAAI,IAAI,IAAI,CAAA;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,aAAa,CAAC,IAA+B;IAC3D,IAAI,CAAC,IAAI;QAAE,OAAO,GAAG,CAAA;IACrB,IAAI,CAAC;QACH,2EAA2E;QAC3E,mCAAmC;QACnC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;QACrC,OAAO,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAA;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,+CAA+C;QAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;QAClC,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;QACpC,OAAO,MAAM,IAAI,GAAG,CAAA;IACtB,CAAC;AACH,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,IAAI,CAAC,CAA4B,EAAE,GAAG,GAAG,GAAG;IAC1D,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAA;IACnB,OAAO,CAAC,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAC7C,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,WAAW,CAAC,CAA4B;IACtD,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACrC,MAAM,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,CAAA;IAC1B,OAAO,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;AAC1C,CAAC"}

package/dist/analytics/server/queries.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @rovela-ai/sdk/analytics/server/queries
+ *
+ * Per-store analytics read + write helpers. Reads from the store's own Neon
+ * branch via `getDb()` (no tenant filtering). Each read returns a typed
+ * payload ready for the dashboard.
+ *
+ * Writes are best-effort: `recordEvent` swallows failures so an analytics
+ * outage NEVER breaks customer flows (checkout, cart, browse). The endpoint
+ * + webhook callers rely on that contract.
+ */
+import { type SdkDb } from '../../core/db/client';
+import type { AnalyticsDashboardPayload, AnalyticsEventsLogPage, AnalyticsPeriod, AnalyticsSortDir, AnalyticsTrafficSummary, AnalyticsVisitorsPage, AnalyticsWireEvent } from '../types';
+export declare function periodToDays(period: AnalyticsPeriod): number;
+interface RecordEventInput {
+    event: AnalyticsWireEvent;
+    device: string | null;
+    country: string | null;
+}
+/**
+ * Insert a single event. Never throws — analytics MUST NEVER break the
+ * customer flow. The caller is the track endpoint OR the Stripe webhook
+ * wrapper; both have a "don't fail the user request on analytics failure"
+ * contract.
+ *
+ * For `purchase` / `refund` events, the partial unique index on `order_id`
+ * absorbs Stripe at-least-once webhook redelivery via ON CONFLICT.
+ */
+export declare function recordEvent(input: RecordEventInput): Promise<void>;
+/**
+ * Dashboard payload. Period-scoped current + prior windows for delta-vs-prior
+ * KPIs. All seven panels fan out in one Promise.all (~150ms warm Neon).
+ *
+ * @param db Optional Drizzle client. Default: `getDb()` (env DATABASE_URL).
+ *           Platform-side passes `createDb(project.databaseUrl)` to read
+ *           from a merchant's branch.
+ */
+export declare function getAnalyticsDashboard(period: AnalyticsPeriod, db?: SdkDb): Promise<AnalyticsDashboardPayload>;
+/**
+ * 7-day visitor + conversion summary for the Rovela platform's per-store
+ * Traffic card. Fast (3 small aggregates) — the platform fan-outs across
+ * every store the user can see, so we keep this tight.
+ */
+export declare function getTrafficSummary7d(db?: SdkDb): Promise<AnalyticsTrafficSummary>;
+/** Sort columns allowed on the events log. Tightly bounded — anything else
+ *  is treated as the default 'ts'. */
+type EventLogSortColumn = 'ts' | 'event' | 'path' | 'referrer' | 'country';
+export interface GetEventsLogOptions {
+    period: AnalyticsPeriod;
+    /** Page cursor. Encoded as a stringified bigint (the previous page's last
+     *  row id). null/undefined = first page. */
+    cursor?: string | null;
+    /** Page size. Default 50, capped at 200. */
+    limit?: number;
+    sortBy?: EventLogSortColumn;
+    sortDir?: AnalyticsSortDir;
+    /** When true, exclude `session_heartbeat` rows. Default false. The admin
+     *  EventsView passes true by default with a toggle to flip. */
+    hideHeartbeats?: boolean;
+}
+export declare function getEventsLog(options: GetEventsLogOptions, db?: SdkDb): Promise<AnalyticsEventsLogPage>;
+type VisitorSortColumn = 'last_seen' | 'first_seen' | 'sessions' | 'pageviews' | 'country';
+export interface GetVisitorsListOptions {
+    period: AnalyticsPeriod;
+    /** Offset cursor (stringified integer). null/undefined = first page. */
+    cursor?: string | null;
+    /** Page size. Default 50, capped at 200. */
+    limit?: number;
+    sortBy?: VisitorSortColumn;
+    sortDir?: AnalyticsSortDir;
+}
+export declare function getVisitorsList(options: GetVisitorsListOptions, db?: SdkDb): Promise<AnalyticsVisitorsPage>;
+export {};
+//# sourceMappingURL=queries.d.ts.map

package/dist/analytics/server/queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../../src/analytics/server/queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAS,KAAK,KAAK,EAAE,MAAM,sBAAsB,CAAA;AAExD,OAAO,KAAK,EACV,yBAAyB,EAGzB,sBAAsB,EAGtB,eAAe,EACf,gBAAgB,EAIhB,uBAAuB,EAGvB,qBAAqB,EACrB,kBAAkB,EACnB,MAAM,UAAU,CAAA;AAwBjB,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAE5D;AAWD,UAAU,gBAAgB;IACxB,KAAK,EAAE,kBAAkB,CAAA;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsDxE;AA+JD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,eAAe,EACvB,EAAE,CAAC,EAAE,KAAK,GACT,OAAO,CAAC,yBAAyB,CAAC,CAkDpC;AAMD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,CAAC,EAAE,KAAK,GACT,OAAO,CAAC,uBAAuB,CAAC,CAoBlC;AAMD;sCACsC;AACtC,KAAK,kBAAkB,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAA;AAU1E,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,eAAe,CAAA;IACvB;gDAC4C;IAC5C,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,OAAO,CAAC,EAAE,gBAAgB,CAAA;IAC1B;mEAC+D;IAC/D,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAmBD,wBAAsB,YAAY,CAChC,OAAO,EAAE,mBAAmB,EAC5B,EAAE,CAAC,EAAE,KAAK,GACT,OAAO,CAAC,sBAAsB,CAAC,CAiGjC;AAMD,KAAK,iBAAiB,GAClB,WAAW,GACX,YAAY,GACZ,UAAU,GACV,WAAW,GACX,SAAS,CAAA;AAUb,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,eAAe,CAAA;IACvB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,iBAAiB,CAAA;IAC1B,OAAO,CAAC,EAAE,gBAAgB,CAAA;CAC3B;AAmBD,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,EAC/B,EAAE,CAAC,EAAE,KAAK,GACT,OAAO,CAAC,qBAAqB,CAAC,CA4FhC"}