@buoy-gg/events 2.1.1

package/lib/module/utils/eventTransformers.js

@@ -0,0 +1,487 @@
+"use strict";
+
+/**
+ * Event Transformers
+ *
+ * Transform events from each source into the unified UnifiedEvent format.
+ *
+ * Note: These transformers use generic types to avoid hard dependencies
+ * on tool packages. The actual transformation logic is in autoDiscoverEventSources.ts.
+ * This file is kept for backwards compatibility and type exports.
+ */
+
+let eventIdCounter = 0;
+
+/**
+ * Generate a unique event ID
+ */
+function generateEventId(source) {
+  return `${source}-${Date.now()}-${++eventIdCounter}`;
+}
+
+// ============================================================================
+// Storage Event Types (for backwards compatibility)
+// ============================================================================
+
+/**
+ * AsyncStorage event action types
+ */
+
+/**
+ * Generic AsyncStorage event structure
+ */
+
+/**
+ * Generic Storage event (AsyncStorage or MMKV)
+ */
+
+/**
+ * Get human-readable action name for AsyncStorage events
+ */
+function getAsyncStorageActionLabel(action) {
+  switch (action) {
+    case "setItem":
+      return "Set Item";
+    case "removeItem":
+      return "Remove Item";
+    case "mergeItem":
+      return "Merge Item";
+    case "clear":
+      return "Clear All";
+    case "multiSet":
+      return "Multi Set";
+    case "multiRemove":
+      return "Multi Remove";
+    case "multiMerge":
+      return "Multi Merge";
+    default:
+      return action;
+  }
+}
+
+/**
+ * Get subtitle for AsyncStorage event
+ */
+function getAsyncStorageSubtitle(event) {
+  const {
+    action,
+    data
+  } = event;
+  switch (action) {
+    case "setItem":
+    case "removeItem":
+    case "mergeItem":
+      return data?.key || "unknown key";
+    case "multiSet":
+    case "multiMerge":
+      {
+        const pairCount = data?.pairs?.length || 0;
+        return `${pairCount} key${pairCount !== 1 ? "s" : ""}`;
+      }
+    case "multiRemove":
+      {
+        const keyCount = data?.keys?.length || 0;
+        return `${keyCount} key${keyCount !== 1 ? "s" : ""}`;
+      }
+    case "clear":
+      return "all keys";
+    default:
+      return "";
+  }
+}
+
+/**
+ * Get status for storage event based on action type
+ */
+function getStorageStatus(action) {
+  if (action.includes("set") || action.includes("Set") || action.includes("merge") || action.includes("Merge")) {
+    return "success";
+  }
+  if (action.includes("remove") || action.includes("Remove") || action === "clear" || action === "delete") {
+    return "neutral";
+  }
+  return "neutral";
+}
+
+/**
+ * Transform StorageEvent (AsyncStorage or MMKV) to UnifiedEvent
+ */
+export function transformStorageEvent(event) {
+  if (event.storageType === "async") {
+    const asyncEvent = event;
+    return {
+      id: generateEventId("async"),
+      source: "storage-async",
+      timestamp: asyncEvent.timestamp.getTime(),
+      title: getAsyncStorageActionLabel(asyncEvent.action),
+      subtitle: getAsyncStorageSubtitle(asyncEvent),
+      status: getStorageStatus(asyncEvent.action),
+      originalEvent: asyncEvent
+    };
+  } else {
+    const mmkvEvent = event;
+    return {
+      id: generateEventId("mmkv"),
+      source: "storage-mmkv",
+      timestamp: mmkvEvent.timestamp.getTime(),
+      title: mmkvEvent.action,
+      subtitle: mmkvEvent.data?.key || mmkvEvent.data?.instanceId || "unknown",
+      status: getStorageStatus(mmkvEvent.action),
+      originalEvent: mmkvEvent
+    };
+  }
+}
+
+/**
+ * Legacy export for backwards compatibility
+ */
+export function transformAsyncStorageEvent(event) {
+  return transformStorageEvent({
+    ...event,
+    storageType: "async"
+  });
+}
+
+// ============================================================================
+// Redux Event Types
+// ============================================================================
+
+/**
+ * Generic Redux action structure
+ */
+
+/**
+ * Get status for Redux action based on category
+ */
+function getReduxStatus(action) {
+  switch (action.category) {
+    case "fulfilled":
+      return "success";
+    case "rejected":
+      return "error";
+    case "pending":
+      return "pending";
+    default:
+      return action.hasStateChange ? "success" : "neutral";
+  }
+}
+
+/**
+ * Get subtitle for Redux action
+ */
+function getReduxSubtitle(action) {
+  if (action.payloadPreview) {
+    return action.payloadPreview;
+  }
+  if (action.hasStateChange && action.diffSummary) {
+    return action.diffSummary;
+  }
+  if (action.duration !== undefined) {
+    return `${action.duration.toFixed(1)}ms`;
+  }
+  return action.sliceName || "";
+}
+
+/**
+ * Transform ReduxAction to UnifiedEvent
+ */
+export function transformReduxAction(action) {
+  return {
+    id: generateEventId("redux"),
+    source: "redux",
+    timestamp: action.timestamp,
+    title: action.type,
+    subtitle: getReduxSubtitle(action),
+    status: getReduxStatus(action),
+    originalEvent: action
+  };
+}
+
+// ============================================================================
+// Network Event Types
+// ============================================================================
+
+/**
+ * Generic Network event structure
+ */
+
+/**
+ * Get status for network event based on HTTP status code
+ */
+function getNetworkStatus(event) {
+  if (event.status === undefined) {
+    return "pending";
+  }
+  if (event.error || event.status >= 400) {
+    return "error";
+  }
+  if (event.status >= 200 && event.status < 400) {
+    return "success";
+  }
+  return "neutral";
+}
+
+/**
+ * Get title for network event
+ */
+function getNetworkTitle(event) {
+  if (event.operationName) {
+    return event.operationName;
+  }
+  return `${event.method} ${event.path || event.url}`;
+}
+
+/**
+ * Get subtitle for network event
+ */
+function getNetworkSubtitle(event) {
+  const parts = [];
+  if (event.status !== undefined) {
+    parts.push(`${event.status}`);
+  } else if (event.error) {
+    parts.push("Error");
+  } else {
+    parts.push("Pending");
+  }
+  if (event.duration !== undefined) {
+    parts.push(`${event.duration.toFixed(0)}ms`);
+  }
+  if (event.host) {
+    parts.push(event.host);
+  }
+  return parts.join(" · ");
+}
+
+/**
+ * Transform NetworkEvent to UnifiedEvent
+ */
+export function transformNetworkEvent(event) {
+  return {
+    id: generateEventId("network"),
+    source: "network",
+    timestamp: event.timestamp,
+    title: getNetworkTitle(event),
+    subtitle: getNetworkSubtitle(event),
+    status: getNetworkStatus(event),
+    originalEvent: event
+  };
+}
+
+// ============================================================================
+// React Query Event Types
+// ============================================================================
+
+/**
+ * Generic React Query event structure
+ */
+
+/**
+ * Format query key for display
+ */
+function formatQueryKey(queryKey) {
+  if (!queryKey || queryKey.length === 0) return "unknown";
+  return queryKey.map(part => {
+    if (typeof part === "string") return part;
+    if (typeof part === "number") return String(part);
+    if (typeof part === "object" && part !== null) {
+      const obj = part;
+      const firstValue = Object.values(obj)[0];
+      if (typeof firstValue === "string" || typeof firstValue === "number") {
+        return String(firstValue);
+      }
+      return JSON.stringify(part).slice(0, 20);
+    }
+    return String(part);
+  }).join(" › ");
+}
+
+/**
+ * Get status for React Query event
+ */
+function getReactQueryStatus(event) {
+  switch (event.type) {
+    case "query-fetch-start":
+    case "mutation-start":
+      return "pending";
+    case "query-fetch-success":
+    case "mutation-success":
+      return "success";
+    case "query-fetch-error":
+    case "mutation-error":
+      return "error";
+    case "query-invalidated":
+      return "neutral";
+    default:
+      return "neutral";
+  }
+}
+
+/**
+ * Get title for React Query event
+ */
+function getReactQueryTitle(event) {
+  if (event.queryKey) {
+    return formatQueryKey(event.queryKey);
+  }
+  if (event.mutationKey) {
+    return formatQueryKey(event.mutationKey);
+  }
+  if (event.mutationId !== undefined) {
+    return `Mutation #${event.mutationId}`;
+  }
+  return event.type.replace(/-/g, " ");
+}
+
+/**
+ * Get subtitle for React Query event
+ */
+function getReactQuerySubtitle(event) {
+  const parts = [];
+  switch (event.type) {
+    case "query-fetch-start":
+      parts.push("Fetching");
+      break;
+    case "query-fetch-success":
+      parts.push("Success");
+      break;
+    case "query-fetch-error":
+      parts.push("Error");
+      break;
+    case "query-invalidated":
+      parts.push("Invalidated");
+      break;
+    case "mutation-start":
+      parts.push("Mutating");
+      break;
+    case "mutation-success":
+      parts.push("Success");
+      break;
+    case "mutation-error":
+      parts.push("Error");
+      break;
+  }
+  if (event.duration !== undefined) {
+    parts.push(`${event.duration.toFixed(0)}ms`);
+  }
+  return parts.join(" · ");
+}
+
+/**
+ * Get correlation ID for React Query event
+ */
+function getReactQueryCorrelationId(event) {
+  if (event.queryHash) {
+    return `rq-query-${event.queryHash}`;
+  }
+  if (event.mutationId !== undefined) {
+    return `rq-mutation-${event.mutationId}`;
+  }
+  return undefined;
+}
+
+/**
+ * Get sequence number within correlation group
+ */
+function getReactQuerySequence(event) {
+  switch (event.type) {
+    case "query-fetch-start":
+    case "mutation-start":
+      return 1;
+    case "query-fetch-success":
+    case "query-fetch-error":
+    case "mutation-success":
+    case "mutation-error":
+      return 2;
+    case "query-invalidated":
+      return 3;
+    default:
+      return 1;
+  }
+}
+
+/**
+ * Determine if a React Query event is a mutation
+ */
+function isReactQueryMutation(event) {
+  return event.type.startsWith("mutation-");
+}
+
+/**
+ * Transform ReactQueryEvent to UnifiedEvent
+ */
+export function transformReactQueryEvent(event) {
+  const isMutation = isReactQueryMutation(event);
+  return {
+    id: generateEventId(isMutation ? "react-query-mutation" : "react-query-query"),
+    source: isMutation ? "react-query-mutation" : "react-query-query",
+    timestamp: event.timestamp,
+    title: getReactQueryTitle(event),
+    subtitle: getReactQuerySubtitle(event),
+    status: getReactQueryStatus(event),
+    originalEvent: event,
+    correlationId: getReactQueryCorrelationId(event),
+    sequenceInGroup: getReactQuerySequence(event)
+  };
+}
+
+// ============================================================================
+// Route Event Types
+// ============================================================================
+
+/**
+ * Generic Route change event structure
+ */
+
+/**
+ * Get status for route event
+ */
+function getRouteStatus(event) {
+  if (event.pathname === "/") return "success";
+  if (Object.keys(event.params).length > 0) return "success";
+  return "neutral";
+}
+
+/**
+ * Get title for route event
+ */
+function getRouteTitle(event) {
+  return event.pathname || "/";
+}
+
+/**
+ * Get subtitle for route event
+ */
+function getRouteSubtitle(event) {
+  const parts = [];
+  const paramCount = Object.keys(event.params).length;
+  if (paramCount > 0) {
+    parts.push(`${paramCount} param${paramCount !== 1 ? "s" : ""}`);
+  }
+  if (event.timeSincePrevious !== undefined && event.timeSincePrevious > 0) {
+    if (event.timeSincePrevious < 1000) {
+      parts.push(`${event.timeSincePrevious}ms`);
+    } else {
+      parts.push(`${(event.timeSincePrevious / 1000).toFixed(1)}s`);
+    }
+  }
+  if (event.previousPathname && event.previousPathname !== event.pathname) {
+    parts.push(`from ${event.previousPathname}`);
+  }
+  return parts.join(" · ") || "navigation";
+}
+
+/**
+ * Transform RouteChangeEvent to UnifiedEvent
+ */
+export function transformRouteEvent(event) {
+  return {
+    id: generateEventId("route"),
+    source: "route",
+    timestamp: event.timestamp,
+    title: getRouteTitle(event),
+    subtitle: getRouteSubtitle(event),
+    status: getRouteStatus(event),
+    originalEvent: event
+  };
+}
+//# sourceMappingURL=eventTransformers.js.map

package/lib/typescript/components/EventsCopySettingsView.d.ts

@@ -0,0 +1,16 @@
+/**
+ * EventsCopySettingsView
+ *
+ * Settings UI for configuring event export format and content.
+ * Based on NetworkCopySettingsView pattern.
+ */
+import type { UnifiedEvent } from "../types";
+import { type EventsCopySettings } from "../types/copySettings";
+interface EventsCopySettingsViewProps {
+    events?: UnifiedEvent[];
+    initialSettings?: EventsCopySettings;
+    onSettingsChange?: (settings: EventsCopySettings) => void;
+}
+export declare function EventsCopySettingsView({ events, initialSettings, onSettingsChange, }: EventsCopySettingsViewProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=EventsCopySettingsView.d.ts.map

package/lib/typescript/components/EventsModal.d.ts

@@ -0,0 +1,16 @@
+/**
+ * EventsModal
+ *
+ * Modal wrapper for the unified events timeline.
+ * Uses JsModal for consistent bottom sheet behavior.
+ */
+interface EventsModalProps {
+    visible: boolean;
+    onClose: () => void;
+    onBack?: () => void;
+    onMinimize?: (modalState: unknown) => void;
+    enableSharedModalDimensions?: boolean;
+}
+export declare function EventsModal({ visible, onClose, onBack, onMinimize, enableSharedModalDimensions, }: EventsModalProps): import("react").JSX.Element | null;
+export {};
+//# sourceMappingURL=EventsModal.d.ts.map

package/lib/typescript/components/ReactQueryEventDetail.d.ts

@@ -0,0 +1,15 @@
+/**
+ * ReactQueryEventDetail
+ *
+ * Detail view for React Query events in the Events DevTools.
+ * Styled similarly to the React Query DevTools detail view.
+ *
+ * Uses local type definitions to avoid hard dependency on @buoy-gg/react-query.
+ */
+import type { UnifiedEvent } from "../types";
+interface ReactQueryEventDetailProps {
+    event: UnifiedEvent;
+}
+export declare const ReactQueryEventDetail: import("react").NamedExoticComponent<ReactQueryEventDetailProps>;
+export {};
+//# sourceMappingURL=ReactQueryEventDetail.d.ts.map

package/lib/typescript/components/UnifiedEventDetail.d.ts

@@ -0,0 +1,15 @@
+/**
+ * UnifiedEventDetail
+ *
+ * Detail view for a single unified event.
+ * Uses shared detail components from other packages when available,
+ * falls back to generic DataViewer when packages aren't installed.
+ */
+import type { UnifiedEvent } from "../types";
+interface UnifiedEventDetailProps {
+    event: UnifiedEvent;
+    onBack?: () => void;
+}
+export declare const UnifiedEventDetail: import("react").NamedExoticComponent<UnifiedEventDetailProps>;
+export {};
+//# sourceMappingURL=UnifiedEventDetail.d.ts.map

package/lib/typescript/components/UnifiedEventFilters.d.ts

@@ -0,0 +1,21 @@
+/**
+ * UnifiedEventFilters
+ *
+ * Filter bar showing toggleable badges for each available event source.
+ * Badges are sorted: enabled first, disabled last.
+ * Toggling a badge enables/disables event listening for that source.
+ */
+import type { EventSource, SourceInfo } from "../types";
+interface UnifiedEventFiltersProps {
+    /** All available sources (already sorted: enabled first) */
+    availableSources: SourceInfo[];
+    /** Toggle a source on/off */
+    onToggleSource: (source: EventSource) => void;
+    /** Total event count */
+    totalCount: number;
+    /** Filtered event count */
+    filteredCount: number;
+}
+export declare const UnifiedEventFilters: import("react").NamedExoticComponent<UnifiedEventFiltersProps>;
+export {};
+//# sourceMappingURL=UnifiedEventFilters.d.ts.map

package/lib/typescript/components/UnifiedEventItem.d.ts

@@ -0,0 +1,26 @@
+/**
+ * UnifiedEventItem
+ *
+ * Renders a single event in the unified event timeline.
+ * Uses shared UI components from other packages when available,
+ * falls back to generic CompactRow when packages aren't installed.
+ */
+import type { UnifiedEvent } from "../types";
+interface UnifiedEventItemProps {
+    event: UnifiedEvent;
+    onPress: () => void;
+    isSelected?: boolean;
+    /** Whether this event is expanded (for route events) */
+    isExpanded?: boolean;
+    /** Called when navigating to a route */
+    onNavigate?: (pathname: string) => void;
+    /** Number of events in the correlation group */
+    correlationCount?: number;
+    /** Label showing position in group (e.g., "1/2") */
+    correlationLabel?: string | null;
+    /** Color for the correlation indicator */
+    correlationColor?: string;
+}
+export declare const UnifiedEventItem: import("react").NamedExoticComponent<UnifiedEventItemProps>;
+export {};
+//# sourceMappingURL=UnifiedEventItem.d.ts.map

package/lib/typescript/components/UnifiedEventList.d.ts

@@ -0,0 +1,27 @@
+/**
+ * UnifiedEventList
+ *
+ * Scrollable list of unified events with empty state handling.
+ */
+import type { UnifiedEvent } from "../types";
+interface UnifiedEventListProps {
+    /** Events to display */
+    events: UnifiedEvent[];
+    /** Currently selected event ID */
+    selectedEventId?: string;
+    /** Currently expanded event ID (for route events) */
+    expandedEventId?: string | null;
+    /** Called when an event is pressed */
+    onEventPress: (event: UnifiedEvent) => void;
+    /** Called when navigating to a route */
+    onNavigate?: (pathname: string) => void;
+    /** Whether events are being captured */
+    isCapturing: boolean;
+    /** Number of hidden events (for free tier limit) */
+    hiddenEventsCount?: number;
+    /** Called when upgrade banner is pressed */
+    onUpgradePress?: () => void;
+}
+export declare const UnifiedEventList: import("react").NamedExoticComponent<UnifiedEventListProps>;
+export {};
+//# sourceMappingURL=UnifiedEventList.d.ts.map

package/lib/typescript/components/UnifiedEventViewer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * UnifiedEventViewer
+ *
+ * Main component for the unified event timeline.
+ * Shows events from all sources with filtering and detail view.
+ */
+export declare function UnifiedEventViewer(): import("react").JSX.Element;
+//# sourceMappingURL=UnifiedEventViewer.d.ts.map

package/lib/typescript/hooks/useUnifiedEvents.d.ts

@@ -0,0 +1,30 @@
+/**
+ * useUnifiedEvents Hook
+ *
+ * Main hook for consuming unified events from all sources.
+ * Automatically discovers and subscribes to available event sources.
+ */
+import type { UnifiedEvent, EventSource, SourceInfo } from "../types";
+export interface UseUnifiedEventsResult {
+    events: UnifiedEvent[];
+    filteredEvents: UnifiedEvent[];
+    availableSources: SourceInfo[];
+    enabledSources: Set<EventSource>;
+    toggleSource: (source: EventSource) => void;
+    enableAllSources: () => void;
+    clearEvents: () => void;
+    totalCount: number;
+    filteredCount: number;
+    isCapturing: boolean;
+    startCapturing: () => void;
+    stopCapturing: () => void;
+    toggleCapturing: () => void;
+    /** Which sources are actually available (packages installed) */
+    discoveredSources: Set<EventSource>;
+    /** Number of events hidden due to free tier limit */
+    hiddenEventsCount: number;
+    /** Whether user is on Pro plan */
+    isPro: boolean;
+}
+export declare function useUnifiedEvents(): UseUnifiedEventsResult;
+//# sourceMappingURL=useUnifiedEvents.d.ts.map

package/lib/typescript/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @buoy-gg/events
+ *
+ * Unified event timeline for all DevTools sources.
+ * Shows events from Storage, Redux, Network, React Query, etc.
+ * in a single chronological view.
+ *
+ * PUBLIC API - Only these exports are supported for external use.
+ * Internal stores and subscription mechanisms are not exported to prevent
+ * bypassing the tool's intended usage patterns.
+ */
+export { eventsToolPreset, createEventsTool } from "./preset";
+export { UnifiedEventViewer } from "./components/UnifiedEventViewer";
+export { useUnifiedEvents } from "./hooks/useUnifiedEvents";
+export type { UseUnifiedEventsResult } from "./hooks/useUnifiedEvents";
+export type { UnifiedEvent, EventSource, EventStatus, EventFilter, SourceInfo, UnifiedEventListener, EventsCopySettings, CopyPresetName, } from "./types";
+export { DEFAULT_COPY_SETTINGS, COPY_PRESETS, PRESET_METADATA, detectActivePreset, } from "./types/copySettings";
+export { UnifiedEventItem } from "./components/UnifiedEventItem";
+export { UnifiedEventList } from "./components/UnifiedEventList";
+export { UnifiedEventFilters } from "./components/UnifiedEventFilters";
+export { UnifiedEventDetail } from "./components/UnifiedEventDetail";
+export { ReactQueryEventDetail } from "./components/ReactQueryEventDetail";
+export { EventsCopySettingsView } from "./components/EventsCopySettingsView";
+export { findRelatedEvents, hasRelatedEvents, getRelatedEventsCount, buildCorrelationCountMap, getCorrelationGroup, getCorrelationLabel, getCorrelationColor, } from "./utils/correlationUtils";
+export { generateExport, generateMarkdownExport, generateJsonExport, generatePlaintextExport, estimateExportSize, getExportSummary, filterEvents, } from "./utils/eventExportFormatter";
+export type { ExportSummary } from "./utils/eventExportFormatter";
+export { loadCopySettings, saveCopySettings, clearCopySettings, } from "./utils/copySettingsStorage";
+//# sourceMappingURL=index.d.ts.map