npm package: @olimpo/capture-client
Description: Cliente de captura de errores e interacciones para aplicaciones Olimpo.
Latest version: 1.0.6

# @olimpo/capture-client

Cliente de captura de errores e interacciones para aplicaciones Olimpo.

## Instalación

```bash
npm install @olimpo/capture-client
# o
pnpm add @olimpo/capture-client
```

## Uso

### Inicialización

```typescript
import { OlimpoCaptureClient } from "@olimpo/capture-client";
import { SessionManager } from "@calimaco/base_v2";
import cfg from "./utils/Config";

// Inicializar con SessionManager (opcional)
const session = new SessionManager(cfg);
OlimpoCaptureClient.init({
  sessionProvider: session,
  apiUrl: "https://api.example.com/api", // opcional
  projectSlug: "my-project",
  environmentName: "production",
  token: "your-auth-token",
  country: "PE",
});
```

### Captura de Errores

```typescript
import { OlimpoCaptureClient } from "@olimpo/capture-client";

// Captura manual
OlimpoCaptureClient.captureException({
  event_type: "error",
  message: "Error description",
  level: "error",
  fingerprint: "unique-error-id",
  stack_trace: [
    {
      file: "component.tsx",
      line: 42,
      function: "handleClick",
    },
  ],
});

// Captura segura (no lanza excepciones)
OlimpoCaptureClient.captureExceptionSafe({
  event_type: "error",
  message: "Error description",
  level: "warning",
});
```

### Hook de Captura de Errores

```typescript
import { useCaptureError } from "@olimpo/capture-client";

function MyComponent() {
  const { captureError } = useCaptureError();

  const handleAction = () => {
    try {
      // código que puede fallar
    } catch (error) {
      captureError(error, {
        event_type: "user_action_error",
        level: "error",
        tags: { action: "submit_form" },
      });
    }
  };
}
```

### Captura de Interacciones

```typescript
import { OlimpoCaptureClient } from "@olimpo/capture-client";

// Captura manual
OlimpoCaptureClient.captureInteraction({
  event_type: "click",
  component_name: "LoginButton",
  action: "click",
  metadata: {
    page: "/login",
    element: "submit-btn",
  },
});

// Captura segura
OlimpoCaptureClient.captureInteractionSafe({
  event_type: "page_view",
  component_name: "HomePage",
});
```

### Hook de Captura de Interacciones

```typescript
import { useCaptureInteraction } from "@olimpo/capture-client";

function MyComponent() {
  const captureInteraction = useCaptureInteraction();

  const handleClick = () => {
    captureInteraction({
      event_type: "click",
      component_name: "ProductCard",
      action: "add_to_cart",
      metadata: { productId: "123" },
    });
  };
}
```

### ErrorBoundary

```typescript
import { ErrorBoundary } from "@olimpo/capture-client";

function App() {
  return (
    <ErrorBoundary>
      <YourApp />
    </ErrorBoundary>
  );
}
```

## API

### OlimpoCaptureClient

#### `init(options)`

Inicializa el cliente.

**Opciones:**

- `sessionProvider?: SessionProvider` - Proveedor de sesión de usuario
- `apiUrl?: string` - URL base de la API (por defecto usa `REACT_APP_OLIMPO_API`)
- `projectSlug: string` - Slug del proyecto (obligatorio o usar `REACT_APP_OLIMPO_CAPTURE_ERROR_PROJECT_SLUG`)
- `environmentName: string` - Nombre del entorno (obligatorio o usar `REACT_APP_OLIMPO_CAPTURE_ERROR_ENVIRONMENT_NAME`)
- `token: string` - Token de autenticación (obligatorio o usar `REACT_APP_OLIMPO_CAPTURE_ERROR_TOKEN`)
- `country?: string` - Código de país (opcional, por defecto usa `REACT_APP_COUNTRY`)

#### `isInitialized(): boolean`

Verifica si el cliente está inicializado.

#### `captureException(payload): Promise<ErrorEventResponse>`

Captura un error de forma asíncrona.

#### `captureExceptionSafe(payload): void`

Captura un error de forma segura (no lanza excepciones).

#### `captureInteraction(payload): Promise<void>`

Captura una interacción de usuario.

#### `captureInteractionSafe(payload): void`

Captura una interacción de forma segura.

#### `isPWA(): boolean`

Detecta si la aplicación se ejecuta como PWA.

#### `getPlatformInfo()`

Obtiene información de la plataforma (OS, navegador, tipo de dispositivo).

## Variables de Entorno

```env
REACT_APP_OLIMPO_API=https://api.example.com/api
REACT_APP_OLIMPO_CAPTURE_ERROR_PROJECT_SLUG=my-project
REACT_APP_OLIMPO_CAPTURE_ERROR_ENVIRONMENT_NAME=production
REACT_APP_OLIMPO_CAPTURE_ERROR_TOKEN=your-auth-token
REACT_APP_COUNTRY=PE
```

## Tipos

```typescript
interface SessionProvider {
  getUser: () => UserContext | undefined;
}

interface UserContext {
  user?: string;
  alias?: string;
  email?: string;
  mobile?: string;
  national_id?: string;
}
```

## Licencia

Privado - Olimpo