# Configuration

This page covers all configuration options available for the Oops Widget.

## Widget Options

The `createOopsWidget` function accepts a configuration object with the following options:

| Option                   | Type                                                                 | Default              | Description                                              |
| ------------------------ | -------------------------------------------------------------------- | -------------------- | -------------------------------------------------------- |
| `statusUrl`              | `string`                                                             | _required_           | URL endpoint for polling system status                   |
| `alertComponent`         | `CustomElementConstructor`                                           | _required_           | Web Component class for rendering alerts                 |
| `i18nProvider`           | `I18nProvider`                                                       | _required_           | Provider for localized status messages                   |
| `placement`              | `'top-left'` \| `'top-right'` \| `'bottom-left'` \| `'bottom-right'` | `'bottom-right'`     | Screen placement of the alert                            |
| `interceptors`           | `Interceptor[]`                                                      | `[]`                 | Array of request interceptors                            |
| `mobile`                 | `object`                                                             | `{ enabled: false }` | Mobile-specific configuration                            |
| `logLevel`               | `LogLevel`                                                           | `LogLevel.NONE`      | Logging verbosity                                        |
| `alertClosureBehavior`   | `object`                                                             | —                    | Custom timing for alert close and status check intervals |
| `displayIncidentDetails` | `boolean`                                                            | `false`              | Whether to display incident details in alerts            |
| `useSandboxedFetch`      | `boolean`                                                            | `true`               | Use sandboxed fetch to avoid interceptor conflicts       |

### Example

```typescript
import { createOopsWidget, LogLevel } from '@upreport/oops-widget';
import { StatusAlert } from '@upreport/oops-widget/statusAlert';
import { createAutoDetectI18nProvider } from '@upreport/oops-widget/i18n';

const widget = createOopsWidget({
  statusUrl: 'YOUR_STATUS_URL_FROM_CONSOLE',
  alertComponent: StatusAlert,
  i18nProvider: createAutoDetectI18nProvider(),
  placement: 'bottom-right',
  logLevel: LogLevel.DEBUG,
  displayIncidentDetails: true,
});
```

---

## Interceptors

Interceptors monitor HTTP requests and can trigger alerts for errors or slow responses. Two interceptors are available:

- **FetchInterceptor** — Monitors `fetch()` API calls
- **XHRInterceptor** — Monitors `XMLHttpRequest` calls

### Interceptor Options

| Option                     | Type       | Default | Description                                      |
| -------------------------- | ---------- | ------- | ------------------------------------------------ |
| `timeoutMs`                | `number`   | `30000` | Milliseconds before a request is considered slow |
| `showSlowRequestAlerts`    | `boolean`  | `true`  | Show alerts for slow requests                    |
| `showErrorAlerts`          | `boolean`  | `true`  | Show alerts for non-2xx HTTP responses           |
| `monitoredServicePatterns` | `string[]` | `[]`    | URL patterns to monitor                          |
| `monitoredServiceOptions`  | `object`   | `{}`    | Options for pattern matching                     |

### Monitored Service Options

| Option                    | Type      | Default | Description                                             |
| ------------------------- | --------- | ------- | ------------------------------------------------------- |
| `requireExplicitPatterns` | `boolean` | `false` | Only monitor URLs matching explicit patterns            |
| `includeCurrentOrigin`    | `boolean` | `true`  | Include same-origin requests when no patterns specified |
| `treatRelativeAsInternal` | `boolean` | `true`  | Treat relative URLs as internal (same-origin)           |

### Example

```typescript
import { FetchInterceptor } from '@upreport/oops-widget/fetchInterceptor';
import { XHRInterceptor } from '@upreport/oops-widget/xhrInterceptor';

const interceptorConfig = {
  timeoutMs: 20000,
  showSlowRequestAlerts: true,
  showErrorAlerts: true,
  monitoredServicePatterns: ['/api/*', 'api.example.com'],
  monitoredServiceOptions: {
    requireExplicitPatterns: true,
    includeCurrentOrigin: true,
    treatRelativeAsInternal: true,
  },
};

const widget = createOopsWidget({
  // ... other options
  interceptors: [
    new FetchInterceptor(interceptorConfig),
    new XHRInterceptor(interceptorConfig),
  ],
});
```

---

## Internationalization (i18n)

The widget supports 18 languages out of the box. You can use automatic language detection or provide static translations.

### Auto-Detect Provider

Automatically detects the user's browser language:

```typescript
import { createAutoDetectI18nProvider } from '@upreport/oops-widget/i18n';

const widget = createOopsWidget({
  // ... other options
  i18nProvider: createAutoDetectI18nProvider(),
});
```

### Supported Languages

Arabic (ar), Czech (cs), German (de), English (en), Spanish (es), French (fr), Hindi (hi), Italian (it), Japanese (ja), Korean (ko), Norwegian Bokmål (nb), Dutch (nl), Polish (pl), Portuguese (pt), Swedish (sv), Turkish (tr), Ukrainian (uk), Chinese (zh)

### Static Provider

Provide custom translations for specific locales:

```typescript
import { createStaticI18nProvider } from '@upreport/oops-widget/i18n';

const widget = createOopsWidget({
  // ... other options
  i18nProvider: createStaticI18nProvider({
    en: {
      title: 'System Status',
      message: 'We are experiencing issues.',
    },
    es: {
      title: 'Estado del Sistema',
      message: 'Estamos experimentando problemas.',
    },
  }),
});
```

---

## Mobile Configuration

Configure how the widget behaves on mobile devices:

| Option       | Type                  | Default | Description                             |
| ------------ | --------------------- | ------- | --------------------------------------- |
| `enabled`    | `boolean`             | `false` | Enable mobile-specific behavior         |
| `placement`  | `'top'` \| `'bottom'` | —       | Alert placement on mobile               |
| `mediaQuery` | `string`              | —       | Custom media query for mobile detection |

### Example

```typescript
const widget = createOopsWidget({
  // ... other options
  placement: 'bottom-right', // Desktop placement
  mobile: {
    enabled: true,
    placement: 'top', // Mobile placement
  },
});
```

---

## Alert Closure Behavior

Customize how long alerts stay visible and how often status is rechecked after an alert is closed:

```typescript
import { SystemStatus } from '@upreport/oops-widget';

const widget = createOopsWidget({
  // ... other options
  alertClosureBehavior: {
    [SystemStatus.DegradedPerformance]: {
      closeDurationMs: 40000, // Alert stays closed for 40 seconds
      checkIntervalMs: 10000, // Recheck status every 10 seconds
    },
    [SystemStatus.MajorOutage]: {
      closeDurationMs: 60000,
      checkIntervalMs: 15000,
    },
  },
});
```

---

## Logging

Control the verbosity of console logging:

```typescript
import { LogLevel } from '@upreport/oops-widget';

const widget = createOopsWidget({
  // ... other options
  logLevel: LogLevel.DEBUG, // DEBUG | INFO | WARN | ERROR | NONE
});
```

| Level   | Description                                    |
| ------- | ---------------------------------------------- |
| `DEBUG` | All messages including detailed debugging info |
| `INFO`  | Informational messages and above               |
| `WARN`  | Warnings and errors only                       |
| `ERROR` | Errors only                                    |
| `NONE`  | No logging (default)                           |