npm package: @rihacats/logfix
Description: LogFix Node.js SDK — 에러 추적 SDK
Author: LogFix Team
Latest version: 1.0.0

# LogFix Node.js SDK

[![npm version](https://badge.fury.io/js/logfix.svg)](https://www.npmjs.com/package/logfix)
[![Node Support](https://img.shields.io/badge/node-18+-blue.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)

Node.js errors, explained. The official SDK for LogFix — turn cryptic stack traces into actionable solutions in 30 seconds.

---

## Installation

```bash
npm install logfix
# or
yarn add logfix
```

---

## Quickstart

Call `logfix.init()` before your app starts handling requests.

```typescript
import logfix from "logfix";

logfix.init({
  apiKey: "logfix_api_key",
  appVersion: "1.2.3",
});

try {
  throw new Error("Something went wrong");
} catch (e) {
  logfix.captureError(e, { tags: { region: "ap-northeast-2" } });
}

// Make sure all queued events are sent before exiting
await logfix.flush();
```

---

## Configuration Options

| Option | Type | Default | Description |
|---|---|---|---|
| `apiKey` | `string` | **(Required)** | Your project's API Key. |
| `appVersion` | `string` | `"unknown"` | Your application's version tag. |
| `endpoint` | `string` | `https://api.logfix.xyz` | URL for self-hosted servers. |
| `maxBatchSize` | `number` | `50` | Maximum number of events sent in a single batch. |
| `flushInterval` | `number` | `5000` | Periodic flush interval (in **milliseconds**). |
| `queueSize` | `number` | `1000` | Internal event buffer size. |
| `maxRetries` | `number` | `3` | Maximum retry attempts for failed transmissions. |
| `overflowPolicy` | `string` | `"drop_newest"` | Behavior when the queue is full: `drop_newest`, `drop_oldest`, or `block`. |
| `debug` | `boolean` | `false` | Enable SDK internal debug logging. |
| `enabled` | `boolean` | `true` | Set to `false` to disable capturing (useful for testing/local dev). |

---

## Usage

### Capturing Errors & Messages

```typescript
// Basic error capture
logfix.captureError(err);

// Capture with custom level, tags, and extra context
logfix.captureError(err, {
  level: logfix.Level.WARNING,
  tags: { user_id: "usr_123" },
  extra: { plan: "enterprise" },
});

// Capture a text message directly
logfix.captureMessage("Deployment started", { level: logfix.Level.INFO });

// Automatically recover and capture panics
logfix.recoverAndCapture(() => riskyFunction());

// Async version
await logfix.recoverAndCaptureAsync(() => riskyAsyncFunction());
```

### Shorthand API

```typescript
logfix.debug("Query executed!", { extra: { sql: "SELECT ..." } });
logfix.log("서버가 시작됬어요.");
logfix.info("User logged in", { tags: { user_id: "123" } });
logfix.warn("Memory usage is high!");
logfix.error(new Error("Something failed"));  // Exception object
logfix.error("Something failed");             // String also works
logfix.fatal("Critical failure!");
```

---

## Framework Integrations

### Express

```typescript
import express from "express";
import {
  LogfixExpressMiddleware,
  LogfixExpressErrorHandler,
} from "logfix/middleware/express";

const app = express();

// 요청 컨텍스트 미들웨어 (선택)
app.use(LogfixExpressMiddleware());

// ... your routes ...

// 에러 핸들러는 반드시 라우터 이후에 등록!
app.use(LogfixExpressErrorHandler());
```

### Fastify

```typescript
import Fastify from "fastify";
import { logfixFastifyPlugin } from "logfix/middleware/fastify";

const app = Fastify();
await app.register(logfixFastifyPlugin);
```

---

## Testing Environment

```typescript
logfix.init({ apiKey: "lf_test", enabled: false });

// When enabled=false, all capture functions become safe no-ops.
```

---

## API Compatibility

| SDK Version | LogFix Core API |
|---|---|
| 1.x | v1 |

---

## License

[MIT](LICENSE)