rusty-replay 1.0.10 → 1.0.12

package/README.md

@@ -1,26 +1,165 @@
+# 🦀 rusty-replay
+
+웹 클라이언트에서 발생한 오류를 수집하고, 직전 사용자 활동을 리플레이 형태로 함께 전송하는 경량 오류 추적 도구입니다.
+
+`rrweb` 기반의 사용자 행동 리플레이 기능과 `axios` 에러 자동 전송까지 지원합니다.
+
+## 📦 설치
+
+```bash
+npm install rusty-replay
+```
+
+---
+
+## ⚙️ 초기화
+
+Next.js에서 `rusty-replay`는 일반적으로 `app/providers.tsx` 또는 `layout.tsx`에서 초기화합니다.
+
+```ts
+import { init } from 'rusty-replay';
+
+init({
+  endpoint: 'https://your-api.com/batch-events',
+  apiKey: 'YOUR_PUBLIC_API_KEY',
+  flushIntervalMs: 10000, // 버퍼가 찰 때까지 최대 대기 시간 (ms)
+  maxBufferSize: 2000000, // 전송 전 최대 버퍼 사이즈 (bytes)
+  beforeErrorSec: 10, // 에러 발생 전 몇 초간의 이벤트를 리플레이로 남길지
+});
+```
+
+---
+
+## 🧠 글로벌 에러 자동 캡처
+
+```ts
+import { setupGlobalErrorHandler } from 'rusty-replay';
+
+setupGlobalErrorHandler();
+```
+
+- `window.onerror`
+- `window.onunhandledrejection`
+  을 자동 감지하여 오류를 서버로 전송합니다.
+
+---
+
+## 🔧 Axios 에러 자동 전송
+
+```ts
+import axios from 'axios';
+import { captureException, AdditionalInfo } from 'rusty-replay';
+
+axios.interceptors.response.use(
+  (res) => res,
+  (error) => {
+    if (axios.isAxiosError(error)) {
+      const additionalInfo: Partial<AdditionalInfo> = {
+        pageUrl: window.location.href,
+        request: {
+          url: error.config?.url ?? '',
+          method: error.config?.method ?? '',
+          headers: error.config?.headers ?? {},
+        },
+        response: {
+          status: error.response?.status ?? 0,
+          statusText: error.response?.statusText ?? '',
+          data: {
+            message: error.response?.data?.message ?? '',
+            errorCode: error.response?.data?.errorCode ?? '',
+          },
+        },
+      };
+
+      captureException(
+        error instanceof Error ? error : new Error('API 요청 실패'),
+        additionalInfo
+      );
+    }
+
+    return Promise.reject(error);
+  }
+);
+```
+
+---
+
+## 🖥️ React Error Boundary 통합
+
 ```tsx
-// layout.tsx or RootLayout.tsx
-useEffect(() => {
-  init({
-    endpoint: 'http://localhost:8080/batch-errors', // endpoint
-    apiKey: 'proj_c08cd1b02c9449c9a0d41f084ee92db9', // project id
-    flushIntervalMs: 5000, // 5초마다 한번씩 전송
-    maxBufferSize: 200, // 큐에 최대 200건까지
-    beforeErrorSec: 30, // 에러 전 30초 리플레이 이벤트 포함
-  });
-}, []);
-
-<button
-  onClick={() => {
-    captureException(new Error('의도적으로 발생시킨 수동 에러'), {
-      additionalInfo: {
-        context: '수동 에러 리포팅 테스트',
-        button: '수동 에러 버튼',
-      },
-    });
+import { ErrorBoundary } from 'react-error-boundary';
+import { captureException } from 'rusty-replay';
+
+<ErrorBoundaryFallbackComponent={() => <div>오류가 발생했습니다.</div>}
+  onError={(error, info) => {
+    captureException(error);
   }}
-  className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
 >
-  수동 에러 발생 및 리포트
-</button>;
+  <App />
+</ErrorBoundary>
+
 ```
+
+---
+
+## 🔁 리플레이 재생 (rrweb-player)
+
+```tsx
+import { decompressFromBase64 } from 'rusty-replay';
+import 'rrweb-player/dist/style.css';
+
+const events = decompressFromBase64(error.replay);
+
+new Player({
+  target: document.getElementById('player')!,
+  props: {
+    events,
+    width: 1000,
+    height: 600,
+    autoPlay: false,
+    showController: true,
+    skipInactive: true,
+  },
+});
+```
+
+---
+
+## 📋 서버로 전송되는 데이터 Payload
+
+```ts
+{
+  message: 'Uncaught TypeError: ...',
+  stacktrace: 'TypeError: ...',
+  replay: 'compressedBase64Data',
+  environment: 'production',
+  browser: 'Chrome 123.0',
+  os: 'macOS 14',
+  userAgent: '...',
+  appVersion: '1.0.0',
+  apiKey: 'YOUR_API_KEY',
+  additionalInfo: {
+    request: {...},
+    response: {...},
+    pageUrl: 'https://your.site/path'
+  },
+  userId: 123
+}
+
+```
+
+---
+
+## 📎 API 참고
+
+### `init(options: InitOptions)`
+
+옵션 설명:
+
+| 옵션              | 타입   | 설명                                   |
+| ----------------- | ------ | -------------------------------------- |
+| `endpoint`        | string | 에러 수집 서버의 엔드포인트            |
+| `apiKey`          | string | 프로젝트 식별용 API Key                |
+| `flushIntervalMs` | number | 에러 전송 간격 (기본: 10초)            |
+| `maxBufferSize`   | number | 최대 전송 버퍼 크기                    |
+| `beforeErrorSec`  | number | 리플레이 수집 구간 (기본: 10초 전까지) |

package/package.json

@@ -1,14 +1,31 @@
 {
   "name": "rusty-replay",
-  "version": "1.0.10",
-  "description": "",
+  "version": "1.0.12",
+  "description": "Lightweight error tracking and replay system for React apps using rrweb and Rust-powered backend integration.",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "type": "module",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
+  "keywords": [
+    "rrweb",
+    "replay",
+    "error-tracking",
+    "frontend",
+    "typescript",
+    "react",
+    "cli",
+    "monitoring"
+  ],
+  "author": "Jaeha Lee <wogkdkrm112@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rusty-replay/replay"
+  },
   "scripts": {
     "build": "tsup",
     "prepublishOnly": "npm run build"