react-request-trail 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,222 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { AxiosResponse, AxiosInstance } from 'axios';
+import React$1, { Component } from 'react';
+
+type TrailMode = 'production' | 'test' | 'development';
+interface TrailStep {
+    id: string;
+    index: number;
+    timestamp: string;
+    duration: number;
+    scope?: string;
+    request: {
+        method: string;
+        url: string;
+        baseURL?: string;
+        headers?: Record<string, string>;
+        params?: Record<string, unknown>;
+        body?: unknown;
+    };
+    response: {
+        status: number;
+        statusText: string;
+        headers?: Record<string, string>;
+        data?: unknown;
+        error?: boolean;
+    };
+    error?: {
+        message: string;
+        code?: string;
+        isCustomError?: boolean;
+        backendMessage?: string;
+    };
+    /** Stack trace'den çıkarılan çağıran dosya bilgisi (component, hook veya service) */
+    callerComponent?: string;
+    /** Çağıran dosyanın dizin yolu (src/... kısmı) */
+    callerFilePath?: string;
+    /** API çağrısı yapıldığı andaki sayfa URL'i (window.location.pathname) */
+    callerPage?: string;
+}
+interface TrailScopeEntry {
+    name: string;
+    path: string;
+    openedAt: string;
+    closedAt?: string;
+    duration?: number;
+    status: 'open' | 'closed';
+}
+interface TrailUser {
+    id?: string;
+    username?: string;
+    roles?: string[];
+    [key: string]: unknown;
+}
+interface TrailTokenInfo {
+    sub?: string;
+    exp?: number;
+    iat?: number;
+    preferred_username?: string;
+    realm_access?: {
+        roles: string[];
+    };
+    expiresIn?: string;
+    isExpired?: boolean;
+    [key: string]: unknown;
+}
+interface TrailTokenConfig {
+    getToken: () => string | null;
+    extractFields?: string[];
+}
+interface TrailSession {
+    sessionId: string;
+    startedAt: string;
+    user?: TrailUser;
+    token?: TrailTokenInfo;
+    environment?: TrailEnvironment;
+}
+interface TrailEnvironment {
+    browser: string;
+    screenWidth: number;
+    screenHeight: number;
+    timezone: string;
+    url: string;
+    language: string;
+}
+interface TrailPDFOptions {
+    language?: 'tr' | 'en';
+    title?: string;
+    logo?: string;
+    headerColor?: string;
+    fontSize?: number;
+    /** Hata anında ekran görüntüsü alsın mı? (default: true) */
+    captureScreenshot?: boolean;
+}
+interface TrailErrorPayload {
+    error: Error;
+    steps: TrailStep[];
+    pdfBlob: Blob;
+    session: TrailSession;
+    mode: TrailMode;
+    scopes: TrailScopeEntry[];
+    /** Hata anında alınan ekran görüntüsü (base64 data URL) */
+    screenshotDataUrl?: string;
+}
+interface TrailConfig {
+    maxSteps?: number;
+    captureRequestBody?: boolean;
+    captureResponseBody?: boolean;
+    captureHeaders?: boolean;
+    sensitiveHeaders?: string[];
+    sensitiveFields?: string[];
+    excludeUrls?: (string | RegExp)[];
+    includeUrls?: (string | RegExp)[];
+    isCustomError?: (response: AxiosResponse) => boolean;
+    extractErrorMessage?: (response: AxiosResponse) => string | undefined;
+    autoGenerateOnError?: boolean;
+    onError?: (payload: TrailErrorPayload) => void | Promise<void>;
+    pdfOptions?: TrailPDFOptions;
+    tokenConfig?: TrailTokenConfig;
+    debug?: boolean;
+}
+interface TrailContextValue {
+    steps: TrailStep[];
+    scopes: TrailScopeEntry[];
+    session: TrailSession;
+    mode: TrailMode;
+    setUser: (user: TrailUser) => void;
+    reportError: (error: Error) => Promise<void>;
+    generatePDF: () => Promise<Blob>;
+    clearTrail: () => void;
+    addScope: (name: string, path: string) => string;
+    removeScope: (scopeId: string) => void;
+    getActiveScope: () => string | undefined;
+}
+interface TrailProviderProps {
+    axios: AxiosInstance;
+    config?: TrailConfig;
+    children: React.ReactNode;
+}
+interface TrailScopeProps {
+    name: string;
+    path: string;
+    children: React.ReactNode;
+}
+interface TrailErrorBoundaryProps {
+    fallback?: React.ReactNode | ((error: Error) => React.ReactNode);
+    children: React.ReactNode;
+}
+
+declare function TrailProvider({ axios, config, children }: TrailProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Pencere/panel bazli izleme componenti.
+ * Mount oldugunda 'acildi', unmount oldugunda 'kapandi' kaydi duser.
+ * React Router kullanilmayan projelerde sayfa navigasyonu yerine kullanilir.
+ */
+declare function TrailScope({ name, path, children }: TrailScopeProps): react_jsx_runtime.JSX.Element;
+
+interface State {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * React component render hatalarini yakalar ve trail'e ekler.
+ * Hata olustugunda otomatik olarak reportError cagirir.
+ */
+declare class TrailErrorBoundary extends Component<TrailErrorBoundaryProps, State> {
+    static contextType: React$1.Context<TrailContextValue | null>;
+    context: TrailContextValue | null;
+    constructor(props: TrailErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, errorInfo: React$1.ErrorInfo): void;
+    render(): string | number | boolean | Iterable<React$1.ReactNode> | react_jsx_runtime.JSX.Element | null | undefined;
+}
+
+declare function useTrail(): TrailContextValue;
+
+/**
+ * Component adini ve dosya yolunu otomatik kaydeder.
+ * Mount oldugunda scope acar, unmount oldugunda kapatir.
+ */
+declare function useTrailMark(componentName: string, filePath?: string): void;
+
+/**
+ * PDF Blob'unu browser'da indirir.
+ */
+declare function downloadPdf(blob: Blob, filename?: string): void;
+
+/**
+ * PDF Blob'unu ve metadata'yi backend endpoint'e POST eder.
+ */
+declare function postToEndpoint(url: string, pdfBlob: Blob, metadata?: Record<string, unknown>): Promise<Response>;
+
+/**
+ * Blob'u base64 string'e cevirir.
+ */
+declare function blobToBase64(blob: Blob): Promise<string>;
+
+/**
+ * Hata aninda sayfanin ekran goruntusunu alir.
+ * html2canvas kullanarak DOM'u canvas'a render eder, ardindan base64 data URL'e donusturur.
+ *
+ * @param targetElement - Goruntu alinacak element (default: document.body)
+ * @param options - Ek ayarlar
+ * @returns Base64 data URL (image/png) veya null (basarisiz olursa)
+ */
+declare function captureScreenshot(targetElement?: HTMLElement, options?: {
+    /** Kalite (0-1 arasi, default: 0.8) */
+    quality?: number;
+    /** Maksimum genislik (px, default: 1400) */
+    maxWidth?: number;
+    /** Timeout (ms, default: 5000) */
+    timeout?: number;
+}): Promise<string | null>;
+
+declare const helpers: {
+    downloadPdf: typeof downloadPdf;
+    postToEndpoint: typeof postToEndpoint;
+    blobToBase64: typeof blobToBase64;
+    captureScreenshot: typeof captureScreenshot;
+};
+
+export { type TrailConfig, type TrailContextValue, type TrailEnvironment, TrailErrorBoundary, type TrailErrorBoundaryProps, type TrailErrorPayload, type TrailMode, type TrailPDFOptions, TrailProvider, type TrailProviderProps, TrailScope, type TrailScopeEntry, type TrailScopeProps, type TrailSession, type TrailStep, type TrailTokenConfig, type TrailTokenInfo, type TrailUser, helpers, useTrail, useTrailMark };

package/dist/index.d.ts

@@ -0,0 +1,222 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { AxiosResponse, AxiosInstance } from 'axios';
+import React$1, { Component } from 'react';
+
+type TrailMode = 'production' | 'test' | 'development';
+interface TrailStep {
+    id: string;
+    index: number;
+    timestamp: string;
+    duration: number;
+    scope?: string;
+    request: {
+        method: string;
+        url: string;
+        baseURL?: string;
+        headers?: Record<string, string>;
+        params?: Record<string, unknown>;
+        body?: unknown;
+    };
+    response: {
+        status: number;
+        statusText: string;
+        headers?: Record<string, string>;
+        data?: unknown;
+        error?: boolean;
+    };
+    error?: {
+        message: string;
+        code?: string;
+        isCustomError?: boolean;
+        backendMessage?: string;
+    };
+    /** Stack trace'den çıkarılan çağıran dosya bilgisi (component, hook veya service) */
+    callerComponent?: string;
+    /** Çağıran dosyanın dizin yolu (src/... kısmı) */
+    callerFilePath?: string;
+    /** API çağrısı yapıldığı andaki sayfa URL'i (window.location.pathname) */
+    callerPage?: string;
+}
+interface TrailScopeEntry {
+    name: string;
+    path: string;
+    openedAt: string;
+    closedAt?: string;
+    duration?: number;
+    status: 'open' | 'closed';
+}
+interface TrailUser {
+    id?: string;
+    username?: string;
+    roles?: string[];
+    [key: string]: unknown;
+}
+interface TrailTokenInfo {
+    sub?: string;
+    exp?: number;
+    iat?: number;
+    preferred_username?: string;
+    realm_access?: {
+        roles: string[];
+    };
+    expiresIn?: string;
+    isExpired?: boolean;
+    [key: string]: unknown;
+}
+interface TrailTokenConfig {
+    getToken: () => string | null;
+    extractFields?: string[];
+}
+interface TrailSession {
+    sessionId: string;
+    startedAt: string;
+    user?: TrailUser;
+    token?: TrailTokenInfo;
+    environment?: TrailEnvironment;
+}
+interface TrailEnvironment {
+    browser: string;
+    screenWidth: number;
+    screenHeight: number;
+    timezone: string;
+    url: string;
+    language: string;
+}
+interface TrailPDFOptions {
+    language?: 'tr' | 'en';
+    title?: string;
+    logo?: string;
+    headerColor?: string;
+    fontSize?: number;
+    /** Hata anında ekran görüntüsü alsın mı? (default: true) */
+    captureScreenshot?: boolean;
+}
+interface TrailErrorPayload {
+    error: Error;
+    steps: TrailStep[];
+    pdfBlob: Blob;
+    session: TrailSession;
+    mode: TrailMode;
+    scopes: TrailScopeEntry[];
+    /** Hata anında alınan ekran görüntüsü (base64 data URL) */
+    screenshotDataUrl?: string;
+}
+interface TrailConfig {
+    maxSteps?: number;
+    captureRequestBody?: boolean;
+    captureResponseBody?: boolean;
+    captureHeaders?: boolean;
+    sensitiveHeaders?: string[];
+    sensitiveFields?: string[];
+    excludeUrls?: (string | RegExp)[];
+    includeUrls?: (string | RegExp)[];
+    isCustomError?: (response: AxiosResponse) => boolean;
+    extractErrorMessage?: (response: AxiosResponse) => string | undefined;
+    autoGenerateOnError?: boolean;
+    onError?: (payload: TrailErrorPayload) => void | Promise<void>;
+    pdfOptions?: TrailPDFOptions;
+    tokenConfig?: TrailTokenConfig;
+    debug?: boolean;
+}
+interface TrailContextValue {
+    steps: TrailStep[];
+    scopes: TrailScopeEntry[];
+    session: TrailSession;
+    mode: TrailMode;
+    setUser: (user: TrailUser) => void;
+    reportError: (error: Error) => Promise<void>;
+    generatePDF: () => Promise<Blob>;
+    clearTrail: () => void;
+    addScope: (name: string, path: string) => string;
+    removeScope: (scopeId: string) => void;
+    getActiveScope: () => string | undefined;
+}
+interface TrailProviderProps {
+    axios: AxiosInstance;
+    config?: TrailConfig;
+    children: React.ReactNode;
+}
+interface TrailScopeProps {
+    name: string;
+    path: string;
+    children: React.ReactNode;
+}
+interface TrailErrorBoundaryProps {
+    fallback?: React.ReactNode | ((error: Error) => React.ReactNode);
+    children: React.ReactNode;
+}
+
+declare function TrailProvider({ axios, config, children }: TrailProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Pencere/panel bazli izleme componenti.
+ * Mount oldugunda 'acildi', unmount oldugunda 'kapandi' kaydi duser.
+ * React Router kullanilmayan projelerde sayfa navigasyonu yerine kullanilir.
+ */
+declare function TrailScope({ name, path, children }: TrailScopeProps): react_jsx_runtime.JSX.Element;
+
+interface State {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * React component render hatalarini yakalar ve trail'e ekler.
+ * Hata olustugunda otomatik olarak reportError cagirir.
+ */
+declare class TrailErrorBoundary extends Component<TrailErrorBoundaryProps, State> {
+    static contextType: React$1.Context<TrailContextValue | null>;
+    context: TrailContextValue | null;
+    constructor(props: TrailErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, errorInfo: React$1.ErrorInfo): void;
+    render(): string | number | boolean | Iterable<React$1.ReactNode> | react_jsx_runtime.JSX.Element | null | undefined;
+}
+
+declare function useTrail(): TrailContextValue;
+
+/**
+ * Component adini ve dosya yolunu otomatik kaydeder.
+ * Mount oldugunda scope acar, unmount oldugunda kapatir.
+ */
+declare function useTrailMark(componentName: string, filePath?: string): void;
+
+/**
+ * PDF Blob'unu browser'da indirir.
+ */
+declare function downloadPdf(blob: Blob, filename?: string): void;
+
+/**
+ * PDF Blob'unu ve metadata'yi backend endpoint'e POST eder.
+ */
+declare function postToEndpoint(url: string, pdfBlob: Blob, metadata?: Record<string, unknown>): Promise<Response>;
+
+/**
+ * Blob'u base64 string'e cevirir.
+ */
+declare function blobToBase64(blob: Blob): Promise<string>;
+
+/**
+ * Hata aninda sayfanin ekran goruntusunu alir.
+ * html2canvas kullanarak DOM'u canvas'a render eder, ardindan base64 data URL'e donusturur.
+ *
+ * @param targetElement - Goruntu alinacak element (default: document.body)
+ * @param options - Ek ayarlar
+ * @returns Base64 data URL (image/png) veya null (basarisiz olursa)
+ */
+declare function captureScreenshot(targetElement?: HTMLElement, options?: {
+    /** Kalite (0-1 arasi, default: 0.8) */
+    quality?: number;
+    /** Maksimum genislik (px, default: 1400) */
+    maxWidth?: number;
+    /** Timeout (ms, default: 5000) */
+    timeout?: number;
+}): Promise<string | null>;
+
+declare const helpers: {
+    downloadPdf: typeof downloadPdf;
+    postToEndpoint: typeof postToEndpoint;
+    blobToBase64: typeof blobToBase64;
+    captureScreenshot: typeof captureScreenshot;
+};
+
+export { type TrailConfig, type TrailContextValue, type TrailEnvironment, TrailErrorBoundary, type TrailErrorBoundaryProps, type TrailErrorPayload, type TrailMode, type TrailPDFOptions, TrailProvider, type TrailProviderProps, TrailScope, type TrailScopeEntry, type TrailScopeProps, type TrailSession, type TrailStep, type TrailTokenConfig, type TrailTokenInfo, type TrailUser, helpers, useTrail, useTrailMark };