npm package: @flowlogs/js
Description: Simple class-based logging SDK for Flowlog
Author: Andreas G. Hjarnø
Latest version: 0.1.9

# @flowlogs/js

Simple class-based logging SDK for Flowlog. Create a logger instance
and use it throughout your application.

## Installation

```bash
npm install @flowlogs/js
```

## Usage

### Basic Setup

```typescript
import { Flowlog } from "@flowlogs/js";

// Create a logger instance
const logger = new Flowlog({
  apiKey: "your-api-key",
  apiUrl: "https://flowlog.io/api/v1/logs",
  service: "frontend",
});

// Use it anywhere in your application
logger.info("Render", { extra: "tester" });
logger.error("Error", { error, extra: "tester" });
logger.warn("Warning", { extra: "tester" });
logger.critical("Critical", { extra: "Tester" });
```

### Configuration Options

```typescript
const logger = new Flowlog({
  apiKey: "your-api-key", // Required: Your Flowlog API key
  apiUrl: "https://flowlog.io/api/v1/logs", // Required: Flowlog API endpoint
  service: "my-service", // Optional: Service name (defaults to 'unknown')
  env: "production", // Optional: Environment (defaults to NODE_ENV or 'development')
  enableConsoleFallback: true, // Optional: Enable console fallback on API failure (default: true)
  iterationKey: "optional-key", // Optional: Iteration key for grouping related logs
});
```

### Logging Methods

- `logger.info(message, data?)` - Log an info message
- `logger.error(message, data?)` - Log an error message
- `logger.warn(message, data?)` - Log a warning message
- `logger.critical(message, data?)` - Log a critical message (mapped
  to error level for API)

### Console Logging

When not in production (i.e., `env !== 'production'`), logs are
automatically printed to the console for debugging. In production,
logs are only sent to the Flowlog API.

### Batching

Logs are automatically batched and sent to the API for efficiency:

- Maximum batch size: 50 logs or 64KB
- Flush interval: 5 seconds
- Automatic retry with exponential backoff (max 3 attempts)

### Manual Flush

You can manually flush pending logs:

```typescript
await logger.flush();
```

This is useful when you need to ensure logs are sent immediately, such
as before application shutdown.

## Examples

### In a Logger File

```typescript
// logger.ts
import { Flowlog } from "@flowlogs/js";

export const logger = new Flowlog({
  apiKey: process.env.FLOWLOG_API_KEY!,
  apiUrl: process.env.FLOWLOG_API_URL!,
  service: "my-app",
  env:
    process.env.NODE_ENV === "production"
      ? "production"
      : "development",
});
```

### Using the Logger

```typescript
// app.ts
import { logger } from "./logger";

logger.info("Application started");
logger.error("Failed to connect", {
  error: new Error("Connection failed"),
});
logger.warn("Deprecated API used", { endpoint: "/old-endpoint" });
logger.critical("System failure", { component: "database" });
```

## TypeScript Support

Full TypeScript support with type definitions included. All types are
exported:

```typescript
import {
  Flowlog,
  type FlowlogConfig,
  type LogLevel,
} from "@flowlogs/js";
```

## Browser and Node.js Support

Works in both browser and Node.js environments. In browsers, logs are
automatically flushed on page unload using the `keepalive` fetch
option.

## Error Handling

If the API is unavailable:

- Logs are queued for retry with exponential backoff
- After max retries, logs are sent to console (if
  `enableConsoleFallback` is true)
- In development mode, logs are always sent to console for debugging

## License

MIT