@pl4yzonellc/empire-analytics 0.0.2

package/dist/testing/index.d.ts

@@ -0,0 +1,91 @@
+import { e as AnalyticsAdapter, A as AnalyticsClient, i as AnalyticsConfigBase } from '../types-Bzaq1v4t.js';
+
+interface MemoryAdapterEvent {
+    name: string;
+    properties?: Record<string, unknown>;
+}
+/**
+ * An in-memory {@link AnalyticsAdapter} that records everything and sends nothing.
+ * Use it to assert on what the SDK forwards to a provider, without loading Plausible.
+ */
+declare class MemoryAdapter implements AnalyticsAdapter {
+    readonly name = "memory";
+    events: MemoryAdapterEvent[];
+    pageViews: (string | undefined)[];
+    initializeCount: number;
+    destroyCount: number;
+    get initialized(): boolean;
+    initialize(): void;
+    track(name: string, properties?: Record<string, unknown>): void;
+    pageView(path?: string): void;
+    destroy(): void;
+    reset(): void;
+    /** Convenience: the most recent recorded event, or `undefined`. */
+    get lastEvent(): MemoryAdapterEvent | undefined;
+}
+
+interface RecordedEvent {
+    name: string;
+    properties?: Record<string, unknown>;
+}
+interface MockAnalyticsClient extends AnalyticsClient {
+    /** Every `track()` call, in order. */
+    readonly events: RecordedEvent[];
+    /** Every `pageView()` path, in order. */
+    readonly pageViews: (string | undefined)[];
+    /** Clear recorded calls and restore the initial enabled/initialized state. */
+    reset(): void;
+}
+/**
+ * `spy` wraps each method so matchers like `toHaveBeenCalledWith` work. Pass your
+ * test runner's spy factory, e.g. `{ spy: (fn) => vi.fn(fn) }`.
+ */
+type MockSpyFactory = (fn: (...args: any[]) => any) => (...args: any[]) => any;
+interface CreateMockAnalyticsClientOptions {
+    /** Initial `isEnabled()` value. Default `true`. */
+    enabled?: boolean;
+    /** Initial `isInitialized()` value. Default `true`. */
+    initialized?: boolean;
+    /** Optional spy wrapper (e.g. `vi.fn`) so call assertions work on the methods. */
+    spy?: MockSpyFactory;
+}
+/**
+ * A zero-dependency fake {@link AnalyticsClient} for consuming-app unit tests.
+ * Nothing is loaded or sent; calls are recorded on `events` / `pageViews`.
+ *
+ * ```ts
+ * import { createMockAnalyticsClient } from '@pl4yzonellc/empire-analytics/testing';
+ *
+ * const analytics = createMockAnalyticsClient({ spy: (fn) => vi.fn(fn) });
+ * render(<AnalyticsProvider config={config} client={analytics}><App /></AnalyticsProvider>);
+ * // ...
+ * expect(analytics.track).toHaveBeenCalledWith('checkout_started', expect.anything());
+ * expect(analytics.events).toContainEqual({ name: 'checkout_started', properties: { cartValue: 1 } });
+ * ```
+ */
+declare function createMockAnalyticsClient(options?: CreateMockAnalyticsClientOptions): MockAnalyticsClient;
+
+interface TestAnalyticsClient {
+    /** A real {@link AnalyticsClient} wired to an in-memory adapter. */
+    client: AnalyticsClient;
+    /** The adapter backing `client` — inspect `adapter.events` / `adapter.pageViews`. */
+    adapter: MemoryAdapter;
+}
+type TestConfigOverrides = Partial<Pick<AnalyticsConfigBase, 'environment' | 'enabled' | 'debug' | 'tenantKey' | 'includeTenantKey' | 'tenantPropertyName' | 'defaultProperties' | 'privacy' | 'onError' | 'onEvent'>>;
+/**
+ * Spin up a fully wired client that exercises the real core pipeline (privacy
+ * sanitization, tenant handling, enabled/disabled logic) but records events in
+ * memory instead of hitting a network.
+ *
+ * Defaults: `environment: 'test'`, `enabled: true`. Initialization is synchronous
+ * for practical purposes — the client is usable the moment this returns.
+ *
+ * ```ts
+ * const { client, adapter } = createTestAnalyticsClient();
+ * client.track('checkout_started', { cartValue: 125 });
+ * expect(adapter.lastEvent).toEqual({ name: 'checkout_started', properties: { cartValue: 125 } });
+ * ```
+ */
+declare function createTestAnalyticsClient(overrides?: TestConfigOverrides): TestAnalyticsClient;
+
+export { type CreateMockAnalyticsClientOptions, MemoryAdapter, type MemoryAdapterEvent, type MockAnalyticsClient, type MockSpyFactory, type RecordedEvent, type TestAnalyticsClient, createMockAnalyticsClient, createTestAnalyticsClient };

package/dist/testing/index.js

@@ -0,0 +1,108 @@
+import { createAnalyticsClient } from '../chunk-J5GXHJNU.js';
+
+// src/testing/MemoryAdapter.ts
+var MemoryAdapter = class {
+  name = "memory";
+  events = [];
+  pageViews = [];
+  initializeCount = 0;
+  destroyCount = 0;
+  get initialized() {
+    return this.initializeCount > this.destroyCount;
+  }
+  initialize() {
+    this.initializeCount += 1;
+  }
+  track(name, properties) {
+    this.events.push({ name, properties });
+  }
+  pageView(path) {
+    this.pageViews.push(path);
+  }
+  destroy() {
+    this.destroyCount += 1;
+  }
+  reset() {
+    this.events = [];
+    this.pageViews = [];
+    this.initializeCount = 0;
+    this.destroyCount = 0;
+  }
+  /** Convenience: the most recent recorded event, or `undefined`. */
+  get lastEvent() {
+    return this.events.at(-1);
+  }
+};
+
+// src/testing/createMockAnalyticsClient.ts
+function createMockAnalyticsClient(options = {}) {
+  const identity = (fn) => fn;
+  const wrap = options.spy ?? identity;
+  const defaults = {
+    enabled: options.enabled ?? true,
+    initialized: options.initialized ?? true
+  };
+  let enabled = defaults.enabled;
+  let initialized = defaults.initialized;
+  const events = [];
+  const pageViews = [];
+  const initialize = wrap((_config) => {
+    initialized = true;
+    return Promise.resolve();
+  });
+  const track = wrap((event, ...args) => {
+    const properties = args[0];
+    events.push({ name: event, properties });
+  });
+  const pageView = wrap((path) => {
+    pageViews.push(path);
+  });
+  const setEnabled = wrap((next) => {
+    enabled = next;
+  });
+  const destroy = wrap(() => {
+    initialized = false;
+  });
+  return {
+    events,
+    pageViews,
+    initialize,
+    track,
+    pageView,
+    setEnabled,
+    destroy,
+    isEnabled: () => enabled,
+    isInitialized: () => initialized,
+    getState: () => ({
+      initialized,
+      enabled,
+      environment: "test",
+      provider: "custom",
+      debug: false
+    }),
+    reset: () => {
+      events.length = 0;
+      pageViews.length = 0;
+      enabled = defaults.enabled;
+      initialized = defaults.initialized;
+    }
+  };
+}
+
+// src/testing/createTestAnalyticsClient.ts
+function createTestAnalyticsClient(overrides = {}) {
+  const adapter = new MemoryAdapter();
+  const client = createAnalyticsClient();
+  void client.initialize({
+    provider: "custom",
+    environment: "test",
+    enabled: true,
+    ...overrides,
+    adapter: () => adapter
+  });
+  return { client, adapter };
+}
+
+export { MemoryAdapter, createMockAnalyticsClient, createTestAnalyticsClient };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/testing/MemoryAdapter.ts","../../src/testing/createMockAnalyticsClient.ts","../../src/testing/createTestAnalyticsClient.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { AnalyticsAdapter } from '../providers/types';\n\nexport interface MemoryAdapterEvent {\n  name: string;\n  properties?: Record<string, unknown>;\n}\n\n/**\n * An in-memory {@link AnalyticsAdapter} that records everything and sends nothing.\n * Use it to assert on what the SDK forwards to a provider, without loading Plausible.\n */\nexport class MemoryAdapter implements AnalyticsAdapter {\n  readonly name = 'memory';\n\n  events: MemoryAdapterEvent[] = [];\n  pageViews: (string | undefined)[] = [];\n  initializeCount = 0;\n  destroyCount = 0;\n\n  get initialized(): boolean {\n    return this.initializeCount > this.destroyCount;\n  }\n\n  initialize(): void {\n    this.initializeCount += 1;\n  }\n\n  track(name: string, properties?: Record<string, unknown>): void {\n    this.events.push({ name, properties });\n  }\n\n  pageView(path?: string): void {\n    this.pageViews.push(path);\n  }\n\n  destroy(): void {\n    this.destroyCount += 1;\n  }\n\n  reset(): void {\n    this.events = [];\n    this.pageViews = [];\n    this.initializeCount = 0;\n    this.destroyCount = 0;\n  }\n\n  /** Convenience: the most recent recorded event, or `undefined`. */\n  get lastEvent(): MemoryAdapterEvent | undefined {\n    return this.events.at(-1);\n  }\n}\n","import type { AnalyticsClient, AnalyticsClientState, AnalyticsConfig } from '../core/types';\nimport type { AnalyticsEventName, TrackArgs } from '../events/types';\n\nexport interface RecordedEvent {\n  name: string;\n  properties?: Record<string, unknown>;\n}\n\nexport interface MockAnalyticsClient extends AnalyticsClient {\n  /** Every `track()` call, in order. */\n  readonly events: RecordedEvent[];\n  /** Every `pageView()` path, in order. */\n  readonly pageViews: (string | undefined)[];\n  /** Clear recorded calls and restore the initial enabled/initialized state. */\n  reset(): void;\n}\n\n/**\n * `spy` wraps each method so matchers like `toHaveBeenCalledWith` work. Pass your\n * test runner's spy factory, e.g. `{ spy: (fn) => vi.fn(fn) }`.\n */\nexport type MockSpyFactory = (fn: (...args: any[]) => any) => (...args: any[]) => any;\n\nexport interface CreateMockAnalyticsClientOptions {\n  /** Initial `isEnabled()` value. Default `true`. */\n  enabled?: boolean;\n  /** Initial `isInitialized()` value. Default `true`. */\n  initialized?: boolean;\n  /** Optional spy wrapper (e.g. `vi.fn`) so call assertions work on the methods. */\n  spy?: MockSpyFactory;\n}\n\n/**\n * A zero-dependency fake {@link AnalyticsClient} for consuming-app unit tests.\n * Nothing is loaded or sent; calls are recorded on `events` / `pageViews`.\n *\n * ```ts\n * import { createMockAnalyticsClient } from '@pl4yzonellc/empire-analytics/testing';\n *\n * const analytics = createMockAnalyticsClient({ spy: (fn) => vi.fn(fn) });\n * render(<AnalyticsProvider config={config} client={analytics}><App /></AnalyticsProvider>);\n * // ...\n * expect(analytics.track).toHaveBeenCalledWith('checkout_started', expect.anything());\n * expect(analytics.events).toContainEqual({ name: 'checkout_started', properties: { cartValue: 1 } });\n * ```\n */\nexport function createMockAnalyticsClient(\n  options: CreateMockAnalyticsClientOptions = {},\n): MockAnalyticsClient {\n  const identity = <F extends (...args: any[]) => any>(fn: F): F => fn;\n  const wrap = (options.spy ?? identity) as <F extends (...args: any[]) => any>(fn: F) => F;\n\n  const defaults = {\n    enabled: options.enabled ?? true,\n    initialized: options.initialized ?? true,\n  };\n\n  let enabled = defaults.enabled;\n  let initialized = defaults.initialized;\n  const events: RecordedEvent[] = [];\n  const pageViews: (string | undefined)[] = [];\n\n  const initialize = wrap((_config: AnalyticsConfig): Promise<void> => {\n    initialized = true;\n    return Promise.resolve();\n  });\n\n  const track = wrap(<K extends AnalyticsEventName>(event: K, ...args: TrackArgs<K>): void => {\n    const properties: Record<string, unknown> | undefined = args[0];\n    events.push({ name: event, properties });\n  });\n\n  const pageView = wrap((path?: string): void => {\n    pageViews.push(path);\n  });\n\n  const setEnabled = wrap((next: boolean): void => {\n    enabled = next;\n  });\n\n  const destroy = wrap((): void => {\n    initialized = false;\n  });\n\n  return {\n    events,\n    pageViews,\n    initialize,\n    track,\n    pageView,\n    setEnabled,\n    destroy,\n    isEnabled: () => enabled,\n    isInitialized: () => initialized,\n    getState: (): AnalyticsClientState => ({\n      initialized,\n      enabled,\n      environment: 'test',\n      provider: 'custom',\n      debug: false,\n    }),\n    reset: () => {\n      events.length = 0;\n      pageViews.length = 0;\n      enabled = defaults.enabled;\n      initialized = defaults.initialized;\n    },\n  };\n}\n","import { createAnalyticsClient } from '../core/AnalyticsClient';\nimport type { AnalyticsClient, AnalyticsConfigBase } from '../core/types';\nimport { MemoryAdapter } from './MemoryAdapter';\n\nexport interface TestAnalyticsClient {\n  /** A real {@link AnalyticsClient} wired to an in-memory adapter. */\n  client: AnalyticsClient;\n  /** The adapter backing `client` — inspect `adapter.events` / `adapter.pageViews`. */\n  adapter: MemoryAdapter;\n}\n\ntype TestConfigOverrides = Partial<\n  Pick<\n    AnalyticsConfigBase,\n    | 'environment'\n    | 'enabled'\n    | 'debug'\n    | 'tenantKey'\n    | 'includeTenantKey'\n    | 'tenantPropertyName'\n    | 'defaultProperties'\n    | 'privacy'\n    | 'onError'\n    | 'onEvent'\n  >\n>;\n\n/**\n * Spin up a fully wired client that exercises the real core pipeline (privacy\n * sanitization, tenant handling, enabled/disabled logic) but records events in\n * memory instead of hitting a network.\n *\n * Defaults: `environment: 'test'`, `enabled: true`. Initialization is synchronous\n * for practical purposes — the client is usable the moment this returns.\n *\n * ```ts\n * const { client, adapter } = createTestAnalyticsClient();\n * client.track('checkout_started', { cartValue: 125 });\n * expect(adapter.lastEvent).toEqual({ name: 'checkout_started', properties: { cartValue: 125 } });\n * ```\n */\nexport function createTestAnalyticsClient(\n  overrides: TestConfigOverrides = {},\n): TestAnalyticsClient {\n  const adapter = new MemoryAdapter();\n  const client = createAnalyticsClient();\n\n  void client.initialize({\n    provider: 'custom',\n    environment: 'test',\n    enabled: true,\n    ...overrides,\n    adapter: () => adapter,\n  });\n\n  return { client, adapter };\n}\n"]}