@nextsparkjs/plugin-amplitude 0.1.0-beta.1

package/tsconfig.json

@@ -0,0 +1,47 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "baseUrl": ".",
+    "moduleResolution": "node",
+    "paths": {
+      "@/*": ["../../../*"],
+      "@/core/*": ["../../../core/*"],
+      "@/contents/*": ["../../../contents/*"],
+      "~/*": ["./*"]
+    }
+  },
+  "watchOptions": {
+    "watchFile": "useFsEvents",
+    "watchDirectory": "useFsEvents",
+    "fallbackPolling": "dynamicPriority",
+    "synchronousWatchDirectory": false,
+    "excludeDirectories": [
+      "**/node_modules",
+      "**/.next",
+      "**/dist",
+      "**/build",
+      "**/.turbo",
+      "**/coverage",
+      "**/.git"
+    ]
+  },
+  "include": [
+    "**/*.ts",
+    "**/*.tsx",
+    "plugin.config.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    ".next",
+    "dist",
+    "build",
+    ".turbo",
+    "coverage",
+    ".git",
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/__tests__/**",
+    "**/tsconfig.tsbuildinfo"
+  ]
+}

package/types/amplitude.types.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+
+export type AmplitudeAPIKey = string & { __brand: 'AmplitudeAPIKey' };
+export type UserId = string & { __brand: 'UserId' };
+export type EventType = string & { __brand: 'EventType' };
+export type EventProperties = Record<string, any>;
+export type UserProperties = Record<string, any>;
+
+export const AmplitudeAPIKeySchema = z.string().regex(/^[a-zA-Z0-9]{32}$/).brand('AmplitudeAPIKey');
+export const UserIdSchema = z.string().min(1).brand('UserId');
+export const EventTypeSchema = z.string().min(1).brand('EventType');
+export const EventPropertiesSchema = z.record(z.string(), z.any());
+export const UserPropertiesSchema = z.record(z.string(), z.any());
+
+export interface AmplitudePluginConfig {
+  apiKey: string;
+  serverZone: 'US' | 'EU';
+  enableSessionReplay: boolean;
+  enableABTesting: boolean;
+  sampleRate: number;
+  enableConsentManagement: boolean;
+  batchSize: number;
+  flushInterval: number;
+  debugMode: boolean;
+  piiMaskingEnabled: boolean;
+  rateLimitEventsPerMinute: number;
+  errorRetryAttempts: number;
+  errorRetryDelayMs: number;
+}
+
+export interface AmplitudeCore {
+  init(apiKey: AmplitudeAPIKey, config: AmplitudePluginConfig): Promise<void>;
+  track(eventType: EventType, properties?: EventProperties): Promise<void>;
+  identify(userId: UserId, properties?: UserProperties): Promise<void>;
+  setUserProperties(properties: UserProperties): Promise<void>;
+  reset(): void;
+  isInitialized(): boolean;
+  shutdown(): void;
+}
+
+export interface UseAmplitudeResult {
+  track: (eventType: EventType, properties?: EventProperties) => Promise<void>;
+  identify: (userId: UserId, properties?: UserProperties) => Promise<void>;
+  setUserProperties: (properties: UserProperties) => Promise<void>;
+  reset: () => void;
+  isInitialized: boolean;
+  context: {
+    config: AmplitudePluginConfig | null;
+    consent: ConsentState;
+    error: Error | null;
+  };
+  lastError: Error | null;
+}
+
+export interface UseExperimentResult {
+  getVariant: (experimentId: string, userId: string) => string | null;
+  trackExposure: (experimentId: string, variantId?: string) => Promise<void>;
+  trackConversion: (experimentId: string, metricId?: string, value?: number) => Promise<void>;
+  isInExperiment: (experimentId: string, userId: string) => boolean;
+}
+
+export interface UseSessionReplayResult {
+  startRecording: () => Promise<boolean>;
+  stopRecording: () => Promise<void>;
+  pauseRecording: () => void;
+  resumeRecording: () => void;
+  isRecording: boolean;
+  canRecord: boolean;
+}
+
+export interface AmplitudePluginContext {
+  amplitude: AmplitudeCore | null;
+  isInitialized: boolean;
+  config: AmplitudePluginConfig | null;
+  consent: ConsentState;
+  updateConsent: (consent: ConsentState) => void;
+  error: Error | null;
+}
+
+export type ConsentCategory = 'analytics' | 'sessionReplay' | 'experiments' | 'performance';
+export type ConsentState = Record<ConsentCategory, boolean>;
+
+export interface ConsentManagerProps {
+  isOpen: boolean;
+  onClose: () => void;
+  onConsentChange: (consent: ConsentState) => void;
+  initialConsent?: Partial<ConsentState>;
+  showBadge?: boolean;
+  position?: 'bottom-left' | 'bottom-right' | 'center' | 'top';
+  theme?: 'light' | 'dark' | 'auto';
+  compactMode?: boolean;
+  persistUserChoice?: boolean;
+}
+
+export function isAmplitudeAPIKey(key: string): key is AmplitudeAPIKey {
+  return /^[a-zA-Z0-9]{32}$/.test(key);
+}
+
+export function isValidUserId(id: any): id is UserId {
+  return typeof id === 'string' && id.trim().length > 0;
+}
+
+export function isAmplitudeEvent(event: any): event is { eventType: EventType; properties?: EventProperties } {
+  return Boolean(event && typeof event.eventType === 'string' && event.eventType.length > 0);
+}

package/utils/debounce.ts

@@ -0,0 +1,133 @@
+export function debounce<T extends (...args: any[]) => any>(
+  func: T,
+  waitMs: number,
+  options: {
+    leading?: boolean;
+    trailing?: boolean;
+    maxWait?: number;
+  } = {}
+): T & { cancel: () => void; flush: () => ReturnType<T> } {
+  let timeoutId: NodeJS.Timeout | null = null;
+  let maxTimeoutId: NodeJS.Timeout | null = null;
+  let lastCallTime: number | undefined;
+  let lastInvokeTime = 0;
+  let lastArgs: Parameters<T> | undefined;
+  let lastThis: any;
+  let result: ReturnType<T>;
+
+  const { leading = false, trailing = true, maxWait } = options;
+
+  function invokeFunc(time: number) {
+    const args = lastArgs!;
+    const thisArg = lastThis;
+
+    lastArgs = undefined;
+    lastThis = undefined;
+    lastInvokeTime = time;
+    result = func.apply(thisArg, args);
+    return result;
+  }
+
+  function startTimer(pendingFunc: () => void, wait: number) {
+    return setTimeout(pendingFunc, wait);
+  }
+
+  function cancelTimer(id: NodeJS.Timeout) {
+    clearTimeout(id);
+  }
+
+  function leadingEdge(time: number) {
+    lastInvokeTime = time;
+    timeoutId = startTimer(timerExpired, waitMs);
+    return leading ? invokeFunc(time) : result;
+  }
+
+  function remainingWait(time: number) {
+    const timeSinceLastCall = time - lastCallTime!;
+    const timeSinceLastInvoke = time - lastInvokeTime;
+    const timeWaiting = waitMs - timeSinceLastCall;
+
+    return maxWait !== undefined
+      ? Math.min(timeWaiting, maxWait - timeSinceLastInvoke)
+      : timeWaiting;
+  }
+
+  function shouldInvoke(time: number) {
+    const timeSinceLastCall = time - lastCallTime!;
+    const timeSinceLastInvoke = time - lastInvokeTime;
+
+    return (
+      lastCallTime === undefined ||
+      timeSinceLastCall >= waitMs ||
+      timeSinceLastCall < 0 ||
+      (maxWait !== undefined && timeSinceLastInvoke >= maxWait)
+    );
+  }
+
+  function timerExpired() {
+    const time = Date.now();
+    if (shouldInvoke(time)) {
+      return trailingEdge(time);
+    }
+    timeoutId = startTimer(timerExpired, remainingWait(time));
+    return undefined;
+  }
+
+  function trailingEdge(time: number) {
+    timeoutId = null;
+
+    if (trailing && lastArgs) {
+      return invokeFunc(time);
+    }
+    lastArgs = undefined;
+    lastThis = undefined;
+    return result;
+  }
+
+  function cancel() {
+    if (timeoutId !== null) {
+      cancelTimer(timeoutId);
+    }
+    if (maxTimeoutId !== null) {
+      cancelTimer(maxTimeoutId);
+    }
+    lastInvokeTime = 0;
+    lastArgs = undefined;
+    lastCallTime = undefined;
+    lastThis = undefined;
+    timeoutId = null;
+    maxTimeoutId = null;
+  }
+
+  function flush() {
+    return timeoutId === null ? result : trailingEdge(Date.now());
+  }
+
+  function debounced(this: any, ...args: Parameters<T>): ReturnType<T> {
+    const time = Date.now();
+    const isInvoking = shouldInvoke(time);
+
+    lastArgs = args;
+    lastThis = this;
+    lastCallTime = time;
+
+    if (isInvoking) {
+      if (timeoutId === null) {
+        return leadingEdge(lastCallTime);
+      }
+      if (maxWait !== undefined) {
+        maxTimeoutId = startTimer(timerExpired, maxWait);
+        return invokeFunc(lastCallTime);
+      }
+    }
+    if (timeoutId === null) {
+      timeoutId = startTimer(timerExpired, waitMs);
+    }
+    return result;
+  }
+
+  debounced.cancel = cancel;
+  debounced.flush = flush;
+
+  return debounced as T & { cancel: () => void; flush: () => ReturnType<T> };
+}