@mushi-mushi/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,330 @@
+interface MushiConfig {
+    projectId: string;
+    apiKey: string;
+    apiEndpoint?: string;
+    sentry?: MushiSentryConfig;
+    widget?: MushiWidgetConfig;
+    capture?: MushiCaptureConfig;
+    proactive?: MushiProactiveConfig;
+    preFilter?: MushiPreFilterConfig;
+    integrations?: MushiIntegrationsConfig;
+    offline?: MushiOfflineConfig;
+    rewards?: MushiRewardsConfig;
+    debug?: boolean;
+    enabled?: boolean;
+}
+interface MushiSentryConfig {
+    dsn?: string;
+    consumeUserFeedback?: boolean;
+    enrichWithSeer?: boolean;
+    useReplay?: boolean;
+}
+interface MushiWidgetConfig {
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    theme?: 'auto' | 'light' | 'dark';
+    triggerText?: string;
+    expandedTitle?: string;
+    mode?: 'simple' | 'conversational';
+    locale?: string;
+    zIndex?: number;
+}
+interface MushiCaptureConfig {
+    console?: boolean;
+    network?: boolean;
+    performance?: boolean;
+    screenshot?: 'on-report' | 'auto' | 'off';
+    elementSelector?: boolean;
+    replay?: 'sentry' | 'rrweb' | 'lite' | 'off';
+}
+interface MushiProactiveConfig {
+    rageClick?: boolean;
+    errorBoundary?: boolean;
+    longTask?: boolean;
+    apiCascade?: boolean;
+    cooldown?: MushiCooldownConfig;
+}
+interface MushiCooldownConfig {
+    maxProactivePerSession?: number;
+    dismissCooldownHours?: number;
+    suppressAfterDismissals?: number;
+}
+interface MushiPreFilterConfig {
+    enabled?: boolean;
+    blockObviousSpam?: boolean;
+    minDescriptionLength?: number;
+    maxDescriptionLength?: number;
+}
+interface MushiIntegrationsConfig {
+    opentelemetry?: {
+        traceContext?: boolean;
+    };
+    vercel?: {
+        analyticsId?: string;
+    };
+    custom?: (report: MushiReportBuilder) => void;
+}
+interface MushiOfflineConfig {
+    enabled?: boolean;
+    maxQueueSize?: number;
+    syncOnReconnect?: boolean;
+}
+interface MushiRewardsConfig {
+    enabled?: boolean;
+    requireAuth?: boolean;
+    showNotifications?: boolean;
+    webhookOnReward?: string;
+}
+type MushiReportCategory = 'bug' | 'slow' | 'visual' | 'confusing' | 'other';
+type MushiReportStatus = 'pending' | 'submitted' | 'classified' | 'grouped' | 'fixing' | 'fixed' | 'dismissed';
+interface MushiReport {
+    id: string;
+    projectId: string;
+    category: MushiReportCategory;
+    description: string;
+    userIntent?: string;
+    environment: MushiEnvironment;
+    consoleLogs?: MushiConsoleEntry[];
+    networkLogs?: MushiNetworkEntry[];
+    performanceMetrics?: MushiPerformanceMetrics;
+    screenshotDataUrl?: string;
+    selectedElement?: MushiSelectedElement;
+    metadata?: Record<string, unknown>;
+    sessionId?: string;
+    reporterToken: string;
+    appVersion?: string;
+    proactiveTrigger?: string;
+    sentryEventId?: string;
+    sentryReplayId?: string;
+    queuedAt?: string;
+    createdAt: string;
+}
+interface MushiReportBuilder {
+    addMetadata(key: string, value: unknown): void;
+    setCategory(category: MushiReportCategory): void;
+    setDescription(description: string): void;
+}
+interface MushiEnvironment {
+    userAgent: string;
+    platform: string;
+    language: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    url: string;
+    referrer: string;
+    timestamp: string;
+    timezone: string;
+    connection?: {
+        effectiveType?: string;
+        downlink?: number;
+        rtt?: number;
+    };
+    deviceMemory?: number;
+    hardwareConcurrency?: number;
+}
+interface MushiConsoleEntry {
+    level: 'log' | 'warn' | 'error' | 'info' | 'debug';
+    message: string;
+    timestamp: number;
+    stack?: string;
+}
+interface MushiNetworkEntry {
+    method: string;
+    url: string;
+    status: number;
+    duration: number;
+    timestamp: number;
+    requestHeaders?: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    error?: string;
+}
+interface MushiPerformanceMetrics {
+    fcp?: number;
+    lcp?: number;
+    cls?: number;
+    fid?: number;
+    inp?: number;
+    ttfb?: number;
+    longTasks?: number;
+}
+interface MushiSelectedElement {
+    tagName: string;
+    id?: string;
+    className?: string;
+    textContent?: string;
+    xpath?: string;
+    rect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+type MushiEventType = 'report:submitted' | 'report:queued' | 'report:sent' | 'report:failed' | 'widget:opened' | 'widget:closed' | 'proactive:triggered' | 'proactive:dismissed';
+type MushiEventHandler = (event: {
+    type: MushiEventType;
+    data?: unknown;
+}) => void;
+interface MushiSDKInstance {
+    report(options?: {
+        category?: MushiReportCategory;
+    }): void;
+    on(event: MushiEventType, handler: MushiEventHandler): () => void;
+    setUser(user: {
+        id: string;
+        email?: string;
+        name?: string;
+    }): void;
+    setMetadata(key: string, value: unknown): void;
+    isOpen(): boolean;
+    open(): void;
+    close(): void;
+    destroy(): void;
+}
+interface MushiApiClient {
+    submitReport(report: MushiReport): Promise<MushiApiResponse<{
+        reportId: string;
+    }>>;
+    getReportStatus(reportId: string): Promise<MushiApiResponse<{
+        status: MushiReportStatus;
+    }>>;
+}
+interface MushiApiResponse<T> {
+    ok: boolean;
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+
+interface ApiClientOptions {
+    projectId: string;
+    apiKey: string;
+    apiEndpoint: string;
+    timeout?: number;
+    maxRetries?: number;
+}
+declare function createApiClient(options: ApiClientOptions): MushiApiClient;
+
+interface PreFilterResult {
+    passed: boolean;
+    reason?: string;
+}
+declare function createPreFilter(config?: MushiPreFilterConfig): {
+    check: (description: string) => PreFilterResult;
+    truncate: (description: string) => string;
+};
+
+interface OfflineQueue {
+    enqueue(report: MushiReport): Promise<void>;
+    flush(client: MushiApiClient): Promise<{
+        sent: number;
+        failed: number;
+    }>;
+    size(): Promise<number>;
+    clear(): Promise<void>;
+    startAutoSync(client: MushiApiClient): void;
+    stopAutoSync(): void;
+}
+declare function createOfflineQueue(config?: MushiOfflineConfig): OfflineQueue;
+
+declare function captureEnvironment(): MushiEnvironment;
+
+declare function getReporterToken(): string;
+
+declare function getSessionId(): string;
+
+interface RateLimiterConfig {
+    maxBurst?: number;
+    refillRate?: number;
+    refillIntervalMs?: number;
+}
+interface RateLimiter {
+    tryConsume(): boolean;
+    reset(): void;
+    availableTokens(): number;
+}
+declare function createRateLimiter(config?: RateLimiterConfig): RateLimiter;
+
+interface PiiScrubberConfig {
+    emails?: boolean;
+    phones?: boolean;
+    creditCards?: boolean;
+    ssns?: boolean;
+    ipAddresses?: boolean;
+}
+declare function createPiiScrubber(config?: PiiScrubberConfig): {
+    scrub: (text: string) => string;
+    scrubObject: <T extends Record<string, unknown>>(obj: T, keys: string[]) => T;
+};
+declare function scrubPii(text: string, config?: PiiScrubberConfig): string;
+
+/**
+ * FILE: logger.ts
+ * PURPOSE: Zero-dependency structured logger for the mushi-mushi SDK ecosystem.
+ *
+ * OVERVIEW:
+ * - Production-grade logging with levels, scoped namespaces, and child loggers
+ * - JSON output for server/production, pretty-formatted output for development
+ * - Automatic environment detection (browser vs Node vs Deno)
+ * - Structured metadata on every log entry
+ * - No external dependencies — safe to ship in any SDK bundle
+ *
+ * USAGE:
+ *   import { createLogger } from '@mushi-mushi/core'
+ *   const log = createLogger({ scope: 'mushi:api' })
+ *   log.info('Request received', { method: 'POST', path: '/v1/reports' })
+ *   const child = log.child('ingest', { reportId: 'abc' })
+ *   child.warn('Slow query', { latencyMs: 420 })
+ *
+ * TECHNICAL DETAILS:
+ * - Log levels: debug(10) < info(20) < warn(30) < error(40) < fatal(50) < silent(99)
+ * - Format auto-detected: JSON in production/server, pretty in development
+ * - Pretty format uses ANSI colors when supported (Node/Deno TTY)
+ * - Child loggers inherit parent scope + metadata, can override level
+ * - Timestamps are ISO 8601 with millisecond precision
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';
+type LogFormat = 'json' | 'pretty' | 'auto';
+interface LoggerOptions {
+    scope: string;
+    level?: LogLevel;
+    meta?: Record<string, unknown>;
+    format?: LogFormat;
+}
+interface Logger {
+    debug(msg: string, meta?: Record<string, unknown>): void;
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+    fatal(msg: string, meta?: Record<string, unknown>): void;
+    child(scope: string, meta?: Record<string, unknown>): Logger;
+    setLevel(level: LogLevel): void;
+}
+interface LogEntry {
+    ts: string;
+    level: LogLevel;
+    scope: string;
+    msg: string;
+    [key: string]: unknown;
+}
+/**
+ * Create a structured logger instance.
+ *
+ * @example
+ * const log = createLogger({ scope: 'mushi:api', level: 'info' })
+ * log.info('Server started', { port: 3000 })
+ *
+ * const child = log.child('auth', { userId: 'u-123' })
+ * child.warn('Token expired')
+ */
+declare function createLogger(options: LoggerOptions): Logger;
+/**
+ * Noop logger that discards all output.
+ * Useful when logging should be completely disabled.
+ */
+declare const noopLogger: Logger;
+
+export { type ApiClientOptions, type LogEntry, type LogFormat, type LogLevel, type Logger, type LoggerOptions, type MushiApiClient, type MushiApiResponse, type MushiCaptureConfig, type MushiConfig, type MushiConsoleEntry, type MushiCooldownConfig, type MushiEnvironment, type MushiEventHandler, type MushiEventType, type MushiIntegrationsConfig, type MushiNetworkEntry, type MushiOfflineConfig, type MushiPerformanceMetrics, type MushiPreFilterConfig, type MushiProactiveConfig, type MushiReport, type MushiReportBuilder, type MushiReportCategory, type MushiReportStatus, type MushiRewardsConfig, type MushiSDKInstance, type MushiSelectedElement, type MushiSentryConfig, type MushiWidgetConfig, type OfflineQueue, type PiiScrubberConfig, type PreFilterResult, type RateLimiter, type RateLimiterConfig, captureEnvironment, createApiClient, createLogger, createOfflineQueue, createPiiScrubber, createPreFilter, createRateLimiter, getReporterToken, getSessionId, noopLogger, scrubPii };