npm package: @logscout/node
Description: Official Node.js client for LogScout - Modern log management platform
Author: LogScout
Latest version: 1.0.0

# @logscout/node

Official Node.js client for [LogScout](https://logscout.dev) - Modern log management platform.

## Installation

```bash
npm install @logscout/node
# or
yarn add @logscout/node
# or
pnpm add @logscout/node
```

## Quick Start

```typescript
import { LogScout } from '@logscout/node';

const logger = new LogScout({
  apiKey: 'your-api-key',
});

// Log messages at different levels
await logger.info('Application started');
await logger.debug('Processing request', { metadata: { requestId: '123' } });
await logger.warn('High memory usage detected');
await logger.error('Failed to connect to database', { 
  source: 'database',
  metadata: { host: 'localhost', port: 5432 } 
});
await logger.fatal('Unrecoverable error, shutting down');
```

## Configuration

```typescript
import { LogScout } from '@logscout/node';

const logger = new LogScout({
  // Required
  apiKey: 'your-api-key',
  
  // Optional
  dev: false,              // Use development API (api.dev.logscout.dev)
  defaultSource: 'app',    // Default source for all logs
  defaultMetadata: {       // Default metadata included with all logs
    environment: 'production',
    version: '1.0.0',
  },
  timeout: 10000,          // Request timeout in ms
  retry: true,             // Retry failed requests
  maxRetries: 3,           // Maximum retry attempts
});
```

## API Reference

### Log Levels

- `DEBUG` - Detailed debug information
- `INFO` - Interesting events
- `WARN` - Exceptional occurrences that are not errors
- `ERROR` - Runtime errors
- `FATAL` - Critical errors causing shutdown

### Methods

#### `log(level, message, options?)`

Send a log entry with a specific level.

```typescript
await logger.log('ERROR', 'Something went wrong', {
  source: 'api',
  metadata: { userId: 123 },
});
```

#### `debug(message, options?)`
#### `info(message, options?)`
#### `warn(message, options?)`
#### `error(message, options?)`
#### `fatal(message, options?)`

Convenience methods for each log level.

```typescript
await logger.error('Connection failed', {
  source: 'database',
  metadata: { error: err.message },
});
```

### Options

```typescript
interface LogOptions {
  source?: string;                    // Override default source
  metadata?: Record<string, unknown>; // Additional metadata
}
```

### Response

All logging methods return a `LogResponse`:

```typescript
interface LogResponse {
  success: boolean;
  id?: string;      // Log entry ID on success
  error?: string;   // Error message on failure
}
```

## Development Mode

Use the `dev` flag to send logs to the development API:

```typescript
const logger = new LogScout({
  apiKey: 'your-dev-api-key',
  dev: true, // Sends to api.dev.logscout.dev
});
```

## Factory Function

You can also use the factory function:

```typescript
import { createLogScout } from '@logscout/node';

const logger = createLogScout({
  apiKey: 'your-api-key',
});
```

## TypeScript Support

This package includes TypeScript definitions. All types are exported:

```typescript
import type { 
  LogLevel, 
  LogScoutConfig, 
  LogPayload, 
  LogOptions, 
  LogResponse 
} from '@logscout/node';
```

## Error Handling

The client handles errors gracefully and returns them in the response:

```typescript
const result = await logger.error('Something failed');

if (!result.success) {
  console.error('Failed to send log:', result.error);
}
```

## Retry Logic

By default, failed requests are retried with exponential backoff:

- Attempt 1: Immediate
- Attempt 2: After 1 second
- Attempt 3: After 2 seconds

Disable retries:

```typescript
const logger = new LogScout({
  apiKey: 'your-api-key',
  retry: false,
});
```

## License

MIT