@arthurfiddich/analytics-service

Provider-agnostic analytics service for mobile apps and backend services.

Goals

• Keep event tracking API stable across providers.
• Support frontend and backend with one package.
• Start with no-op or console providers, then plug Firebase or Mixpanel.

Quick Start

import {
  AnalyticsService,
  ConsoleAnalyticsProvider,
} from "@arthurfiddich/analytics-service";

const analytics = new AnalyticsService({
  providers: [new ConsoleAnalyticsProvider()],
  globalContext: { app: "natupicks-frontend", env: "development" },
});

await analytics.track("product_viewed", {
  productId: "abc123",
  source: "product-detail",
});

Core API

• track(eventName, properties?, context?)
• identify(userId, traits?, context?)
• setUserProperties(userId, properties, context?)
• flush()

Built-in Providers

• NoopAnalyticsProvider
• ConsoleAnalyticsProvider

Shared Event Dedupe Utility

Use the package-level dedupe utility to prevent duplicate event emissions across frontend and backend.

import { createEventDedupe } from "@arthurfiddich/analytics-service";

const dedupe = createEventDedupe();

const onceKey = "purchase_completed:pay_abc123";
if (dedupe.shouldTrackOnce(onceKey)) {
  await analytics.track("purchase_completed", { paymentId: "pay_abc123" });
}

const throttleKey = "search_performed:organic honey";
if (dedupe.shouldTrackThrottled(throttleKey, 1500)) {
  await analytics.track("search_performed", { query: "organic honey" });
}

Recommended dedupe key patterns:

• Payment success: purchase_completed:<paymentId>
• Order creation: order_created:<orderId>
• Refund initiated: refund_initiated:<orderId>:<source>
• Search action: search_performed:<normalizedQuery>

Tip: Use dedupe.clear(key) when a flow is intentionally retried, or dedupe.clear() to reset all in-memory keys for a new app/session lifecycle.