# Tham chiếu API của SDK

> Mọi hàm, component và kiểu công khai của các gói @belvador/*, theo từng đường import.

Mọi export công khai của các gói `@belvador/*`, phiên bản 0.6.1, theo đường import. Những gì không có ở đây — `@belvador/core`, các đường `/internal` và hàm hỗ trợ dùng giữa các gói — là nội bộ và có thể đổi mà không báo trước.

## Mỗi đường import có hàm nào

| Hàm | `browser` | `react` | `cloudflare` | `tanstack-start/client` | `tanstack-start/server` |
|---|---|---|---|---|---|
| `init` | ✓ | ✓ | — | ✓ | — |
| `withBelvador` | — | — | ✓ | — | ✓ |
| `captureException`, `captureMessage` | ✓ | ✓ | ✓ | ✓ | ✓ |
| `setUser`, `setTag`, `setTags`, `setContext` | ✓ | ✓ | ✓ | ✓ | ✓ |
| `addBreadcrumb`, `withScope`, `flush` | ✓ | ✓ | ✓ | ✓ | ✓ |
| `close`, `lastEventId` | ✓ | ✓ | ✓ | ✓ | — |
| `ErrorBoundary`, `withErrorBoundary`, `reactErrorHandler` | — | ✓ | — | ✓ | — |
| `withBelvadorRouter`, `belvadorOnCatch` | — | — | — | ✓ | — |
| `verifyIntegration` | ✓ | ✓ | ✓ | ✓ | ✓ |
| `captureResult` | ✓ | ✓ | ✓ | ✓ | ✓ |
| `privacyPolicy` | ✓ | ✓ | ✓ | ✓ | ✓ |
| `withMonitor`, `captureCheckIn`, `heartbeat` | — | — | ✓ | — | ✓ |
| `SDK_VERSION` | ✓ | ✓ | ✓ | ✓ | ✓ |

Export gốc `@belvador/tanstack-start` chứa middleware: `belvadorRequestMiddleware`, `belvadorFunctionMiddleware`, `withBelvadorRouter`, `belvadorOnCatch`, `isExpectedError` và `SDK_VERSION`.

## Khởi động SDK

### `init(options): boolean`

Có trong `@belvador/browser`, `@belvador/react` và `@belvador/tanstack-start/client`. Bắt đầu theo dõi lỗi trên trình duyệt và trả về việc SDK có đang chạy hay không. Hàm không bao giờ ném lỗi: DSN sai chỉ ghi một cảnh báo và để SDK tắt. Gọi lần hai với cùng DSN thì không làm gì; DSN khác không thay được client đang chạy. Tuỳ chọn: [Tuỳ chọn SDK](https://belvador.dev/vi/docs/sdk/configuration).

### `withBelvador(options, handler): handler`

Có trong `@belvador/cloudflare` và `@belvador/tanstack-start/server`. `options` là một hàm `(env) => WorkerOptions | undefined`, được gọi với biến môi trường của Worker. Trả về một handler cùng dạng, báo lỗi từ `fetch`, `scheduled`, `queue`, `email` và `tail`, ném lại lỗi và giữ nguyên response. Cần `nodejs_compat`.

### `privacyPolicy(json): BelvadorPrivacyPolicy | null`

Kiểm tra chính sách sao chép từ trang Quyền riêng tư của project (**Sao chép dạng code**) và chuẩn bị nó cho `init({ privacyPolicy })`. Trả về `null` và báo `BLV_PRIVACY_POLICY_INVALID` khi không hợp lệ; không bao giờ ném lỗi. Xem [Bảo vệ dữ liệu](https://belvador.dev/vi/docs/privacy). Từ 0.6.0.

## Gửi lỗi

### `captureException(error, context?): string`

Báo một lỗi. `context` có thể chứa `tags`, `extra`, `contexts`, `level`, `user` hoặc `fingerprint` chỉ cho event này. Trả về event ID, hoặc `""` khi SDK đang tắt.

```ts
captureException(error, { tags: { feature: "import" }, level: "warning" });
```

### `captureMessage(message, level?): string`

Báo một thông điệp không kèm exception, ví dụ một trạng thái lẽ ra không bao giờ xảy ra. `level` là một trong `fatal`, `error`, `warning`, `log`, `info`, `debug`.

### `captureResult(result, { operation, expected? }): result`

Báo `error` của một kết quả `{ data, error }` — Supabase, PostgREST hay client nào trả lỗi thay vì ném — thành một event có kiểu theo mã cơ sở dữ liệu, gom theo kiểu và thao tác, rồi trả lại `result` y nguyên. Không bao giờ gửi câu SQL, `details` hay `hint`. Xem [Lỗi cơ sở dữ liệu](https://belvador.dev/vi/docs/sdk/database-errors). Từ 0.6.0.

### `lastEventId(): string`

ID của event cuối cùng trang này đã gửi, hoặc `""`.

> [!NOTE]
> Event ID được tạo ngay trong ứng dụng. Nhận được ID **không** chứng minh event đã tới node — event vẫn có thể bị bỏ do giới hạn, mạng hoặc edge. Hãy kiểm tra project trong Belvador.

## Ngữ cảnh

| Hàm | Tác dụng |
|---|---|
| `setUser({ id } \| null)` | Đặt người dùng hiện tại. Chỉ giữ `id` (tối đa 128 ký tự); email, tên và IP bị xoá. `null` để xoá. |
| `setTag(key, value)` | Một cặp khoá/giá trị tìm được, gắn vào mọi event sau đó. |
| `setTags({ … })` | Nhiều tag một lúc. |
| `setContext(name, { … } \| null)` | Một khối dữ liệu có cấu trúc, hiện trong mục **Ngữ cảnh**. |
| `addBreadcrumb({ message, category, level, data })` | Ghi lại một bước đã xảy ra trước lỗi. Breadcrumb thủ công chạy được mà không cần bật breadcrumb tự động. |

Mọi thứ bạn đặt đều đi qua cùng bước lọc như event. Trên Workers và máy chủ TanStack Start, mỗi request có phạm vi riêng nên ngữ cảnh không bao giờ lẫn sang request khác.

### `withScope(callback)`

Chạy `callback(scope)` với một phạm vi tạm, cho ngữ cảnh chỉ áp dụng cho một lần gửi:

```ts
import { captureException, withScope } from "@belvador/browser";

withScope((scope) => {
  scope.setTag("job", "nightly-sync");
  scope.setFingerprint(["nightly-sync", "{{ default }}"]);
  captureException(error);
});
```

`scope` là object scope của engine. Khi SDK tắt, callback vẫn chạy nhưng không có scope dùng được — đừng dựa vào nó trong trường hợp đó.

## Gửi đi

### `flush(timeoutMs = 2000): Promise<boolean>`

Chờ tới khi các event trong hàng đợi được gửi hoặc hết thời gian. Trả về `true` khi mọi thứ đang chờ đã xong kịp. Hữu ích ở cuối một script. Trên Workers không cần gọi — `withBelvador` đã chờ trong `waitUntil`.

### `close(timeoutMs = 2000): Promise<boolean>`

Gửi nốt rồi tắt SDK. Sau đó không gửi gì nữa.

## React

### `ErrorBoundary`

Component báo lỗi render từ các component con một lần, kèm component stack, và hiện `fallback` — một element hoặc `({ error, componentStack, eventId, resetError }) => element`. Hỗ trợ `onError`, `onReset`, `onMount`, `onUnmount` và `beforeCapture` như boundary của Sentry React. Không có các prop của hộp thoại phản hồi người dùng.

### `withErrorBoundary(Component, props)`

Bọc một component trong `ErrorBoundary` với các prop đã cho.

### `reactErrorHandler(callback?)`

Trả về handler cho các tuỳ chọn root `onUncaughtError`, `onCaughtError` và `onRecoverableError` của React 19. `callback(error, errorInfo, eventId)` tuỳ chọn chạy sau khi đã báo.

## TanStack Start

| Export | Từ | Dùng |
|---|---|---|
| `withBelvadorRouter(options)` | `@belvador/tanstack-start/client` (cả gốc) | `createRouter(withBelvadorRouter({ routeTree, ... }))`: báo lỗi route, giữ `defaultOnCatch` của bạn, thêm `ErrorComponent` của TanStack khi bạn chưa đặt `defaultErrorComponent` (0.5.0) |
| `belvadorOnCatch(error, errorInfo?)` | `@belvador/tanstack-start/client` (cả gốc) | Hàm báo lỗi bên trong helper; `createRouter({ defaultOnCatch: belvadorOnCatch })` chỉ chạy ở nơi có error component |
| `belvadorRequestMiddleware` | `@belvador/tanstack-start` | Phần tử cuối của `requestMiddleware` trong `createStart` |
| `belvadorFunctionMiddleware` | `@belvador/tanstack-start` | Phần tử cuối của `functionMiddleware` trong `createStart` |
| `isExpectedError(error)` | `@belvador/tanstack-start` | `true` với redirect, `notFound()` và lỗi hoặc response có mã dưới 500 — những trường hợp middleware không báo |

## Monitor

Chỉ có ở gói phía máy chủ (`@belvador/cloudflare`, `@belvador/tanstack-start/server`), từ 0.3.0. Không hàm nào ném lỗi. Cách dùng: [Gắn monitor bằng SDK](https://belvador.dev/vi/docs/monitors/setup).

### `withMonitor(slug, fn, options?): ReturnType<fn>`

Chạy `fn(run)` như một lần thử có theo dõi và trả về đúng giá trị `fn` trả (hoặc ném đúng lỗi nó ném). `run.skip(reason)` đánh dấu lượt là Bỏ qua, `run.unknown(reason)` đánh dấu Chưa rõ kết quả; `run.checkInId` và `run.runId` là các id đã gửi. `options`: `schedule`, `timezone`, `checkinMargin`, `maxRuntime`, `failureIssueThreshold`, `recoveryThreshold` (tạo hoặc cập nhật monitor từ code), `environment`, `runId`, `attempt`, `willRetry`.

### `captureCheckIn(checkIn, monitorConfig?): string`

Gửi một check-in `{ monitorSlug, status: "in_progress" | "ok" | "error", checkInId?, duration?, environment?, runId?, attempt?, willRetry?, outcome?: "skipped" | "unknown", reason? }` và trả về id của nó (`""` khi SDK tắt hoặc slug không hợp lệ).

### `heartbeat(slug, options?): void`

Gửi một check-in `ok`, cho monitor theo chu kỳ. `options.environment` thay cho môi trường của SDK.

## Kiểu dữ liệu

| Kiểu | Từ |
|---|---|
| `BrowserOptions` | `@belvador/browser` |
| `ReactOptions`, `ErrorBoundaryProps`, `FallbackRender` | `@belvador/react` (`ReactOptions`, `ErrorBoundaryProps` cũng có ở `tanstack-start/client`) |
| `WorkerOptions`, `BelvadorEnv` | `@belvador/cloudflare`, `@belvador/tanstack-start/server` |
| `BelvadorEvent`, `BelvadorEventHint`, `BelvadorBreadcrumb`, `Scope`, `SeverityLevel` | `browser`, `react`, `cloudflare` |