Tham chiếu API của SDK

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#

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.

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. 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.

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. Từ 0.6.0.

lastEventId(): string#

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

Ngữ cảnh#

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:

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#

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.

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#