@belvador/core 0.1.0 → 0.3.0

package/dist/aborts.d.ts

@@ -0,0 +1,12 @@
+/** Errors whose own name, or whose direct cause's name, is "AbortError". */
+export declare function isAbortError(error: unknown): boolean;
+/**
+ * Called by Belvador's server middleware and Worker wrapper when a request fails after its
+ * client went away (`request.signal.aborted`): whatever was thrown is then treated as an
+ * abort, even when it is not named AbortError (stream "terminated", "aborted", …).
+ */
+export declare function noteClientAbort(error: unknown, signal: AbortSignal | null | undefined): void;
+/** True for an AbortError or an error thrown while its request's client had gone. */
+export declare function isClientAbort(error: unknown): boolean;
+/** A DOMException (AbortError/InvalidStateError) with a standard View Transition message. */
+export declare function isViewTransitionSkip(error: unknown): boolean;

package/dist/aborts.js

@@ -0,0 +1,74 @@
+// Client-cancelled work is expected, not a failure (integration-health 05-decisions,
+// Supaclip finding): a user who closes the tab or navigates away aborts in-flight
+// requests, and the server code serving them throws. These are dropped by default;
+// `captureAborted: true` reports them again. Imports nothing (runs in every runtime).
+/** Errors whose own name, or whose direct cause's name, is "AbortError". */
+export function isAbortError(error) {
+    try {
+        if (nameOf(error) === "AbortError")
+            return true;
+        if (error !== null && typeof error === "object" && "cause" in error)
+            return nameOf(error.cause) === "AbortError";
+    }
+    catch {
+        /* a hostile getter: not an abort */
+    }
+    return false;
+}
+function nameOf(value) {
+    return value !== null && typeof value === "object" ? value.name : undefined;
+}
+const clientAborted = new WeakSet();
+/**
+ * Called by Belvador's server middleware and Worker wrapper when a request fails after its
+ * client went away (`request.signal.aborted`): whatever was thrown is then treated as an
+ * abort, even when it is not named AbortError (stream "terminated", "aborted", …).
+ */
+export function noteClientAbort(error, signal) {
+    try {
+        if (signal?.aborted === true && error !== null && typeof error === "object")
+            clientAborted.add(error);
+    }
+    catch {
+        /* never throws into the app */
+    }
+}
+/** True for an AbortError or an error thrown while its request's client had gone. */
+export function isClientAbort(error) {
+    if (isAbortError(error))
+        return true;
+    return error !== null && typeof error === "object" && clientAborted.has(error);
+}
+/**
+ * Messages browsers give a View Transition that was skipped or aborted on purpose
+ * (observability-1.0 spec 03 §8): the page was hidden, another transition started, the
+ * viewport changed, or `skipTransition()` was called. Exact texts of Chromium, WebKit and
+ * Gecko, matched whole — never a broad pattern.
+ */
+const VIEW_TRANSITION_MESSAGES = [
+    /^Transition was skipped$/,
+    /^Transition was aborted because of invalid state$/,
+    /^Skipped ViewTransition due to (?:document being hidden|another transition starting|hidden document|viewport size change)\.?$/,
+    /^Skipping view transition because (?:document visibility state has become hidden|viewport size changed|the document is hidden|another transition started)\.?$/,
+    /^The (?:previous|old) transition was skipped(?: because a new transition started)?\.?$/,
+    /^View transition was skipped because document visibility state is hidden\.?$/,
+];
+/** A DOMException (AbortError/InvalidStateError) with a standard View Transition message. */
+export function isViewTransitionSkip(error) {
+    try {
+        if (error === null || typeof error !== "object")
+            return false;
+        const name = error.name;
+        const message = error.message;
+        if (name !== "AbortError" && name !== "InvalidStateError")
+            return false;
+        if (typeof message !== "string")
+            return false;
+        if (typeof DOMException !== "undefined" && !(error instanceof DOMException))
+            return false;
+        return VIEW_TRANSITION_MESSAGES.some((re) => re.test(message.trim()));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,15 @@
+/** Reserved tag key; its value is the verification id. */
+export declare const VERIFICATION_TAG = "belvador.verification";
+/** Context the SDK adds to a verification event. */
+export declare const VERIFICATION_CONTEXT = "belvador_verification";
+/** Exception type a verification captures or throws. */
+export declare const VERIFICATION_ERROR_TYPE = "BelvadorVerificationError";
+/** `bv1_` + 32 lowercase hex. */
+export declare const VERIFICATION_ID_RE: RegExp;
+export declare const VERIFY_LIMITS: {
+    readonly timeoutDefaultMs: 20000;
+    readonly timeoutMaxMs: 30000;
+    readonly readbackMaxRequests: 10;
+    /** Waits between read-backs; the last value repeats. */
+    readonly readbackDelaysMs: readonly number[];
+};

package/dist/constants.js

@@ -0,0 +1,18 @@
+// Integration-health wire constants (build integration-health-1.0 spec 01/02), a copy
+// of `src/shared/contracts/integration-health.ts` that a root test keeps equal.
+// Imports nothing.
+/** Reserved tag key; its value is the verification id. */
+export const VERIFICATION_TAG = "belvador.verification";
+/** Context the SDK adds to a verification event. */
+export const VERIFICATION_CONTEXT = "belvador_verification";
+/** Exception type a verification captures or throws. */
+export const VERIFICATION_ERROR_TYPE = "BelvadorVerificationError";
+/** `bv1_` + 32 lowercase hex. */
+export const VERIFICATION_ID_RE = /^bv1_[0-9a-f]{32}$/;
+export const VERIFY_LIMITS = {
+    timeoutDefaultMs: 20000,
+    timeoutMaxMs: 30000,
+    readbackMaxRequests: 10,
+    /** Waits between read-backs; the last value repeats. */
+    readbackDelaysMs: [1000, 2000, 3000, 4000, 5000],
+};

package/dist/diagnostics.d.ts

@@ -0,0 +1,60 @@
+export declare const DIAGNOSTIC_CODES: readonly ["BLV_DSN_MISSING", "BLV_DSN_INVALID", "BLV_INIT_CONFLICT", "BLV_NOT_INITIALIZED", "BLV_SEND_UNAUTHORIZED", "BLV_SEND_RATE_LIMITED", "BLV_SEND_REJECTED", "BLV_SEND_NETWORK", "BLV_SEND_SERVER", "BLV_QUEUE_FULL", "BLV_EVENT_TOO_LARGE", "BLV_HOOK_MISSING", "BLV_DROPPED_BY_APP", "BLV_MONITOR_INVALID_SLUG", "BLV_MONITOR_INVALID_REASON", "BLV_MONITOR_CONFIG_INVALID", "BLV_CHECK_IN_DROPPED", "BLV_TRACE_TARGET_INVALID"];
+export type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[number];
+/** Public page explaining every code and the verification (one anchor per code). */
+export declare const VERIFY_DOCS_URL = "https://belvador.dev/en/docs/sdk/verify";
+/** One callback/console line per code per interval; repeats add to `count`. */
+export declare const DIAGNOSTIC_INTERVAL_MS = 60000;
+export type Diagnostic = {
+    code: DiagnosticCode;
+    /** Epoch ms of this report. */
+    at: number;
+    /** Occurrences since the previous report of this code (≥ 1). */
+    count: number;
+    /** HTTP status of the send, when there was one. */
+    status?: number;
+    /** Seconds the edge asked to wait (429). */
+    retryAfterS?: number;
+};
+export type DiagnosticsSnapshot = {
+    active: boolean;
+    sdk: {
+        name: string;
+        version: string;
+    };
+    /** Host, project and the first 4 characters of the key — never the whole DSN. */
+    dsn: {
+        host: string;
+        project: number;
+        keyHint: string;
+    } | null;
+    lastSend: {
+        status: number | "network";
+        at: number;
+    } | null;
+    counts: Partial<Record<DiagnosticCode, number>>;
+};
+type Config = {
+    onDiagnostic: ((d: Diagnostic) => void) | undefined;
+    debug: boolean;
+    sdk: {
+        name: string;
+        version: string;
+    };
+    dsn: DiagnosticsSnapshot["dsn"];
+};
+/** Anchor on the verification page for one code. */
+export declare function diagnosticDocsUrl(code: DiagnosticCode): string;
+export declare function diagnosticMessage(code: DiagnosticCode): string;
+/** Set by init (and by every Worker invocation). Never throws. */
+export declare function configureDiagnostics(next: Partial<Config>): void;
+/** Records one occurrence; reports at most once per code per minute (NOT_INITIALIZED once). */
+export declare function reportDiagnostic(code: DiagnosticCode, extra?: {
+    status?: number;
+    retryAfterS?: number;
+}, now?: number): void;
+export declare function noteSend(status: number | "network", now?: number): void;
+/** Fixed-size snapshot for support and AI agents; contains no event data. */
+export declare function snapshotDiagnostics(active: boolean): DiagnosticsSnapshot;
+/** Tests only: forget every count and setting. */
+export declare function resetDiagnostics(): void;
+export {};

package/dist/diagnostics.js

@@ -0,0 +1,139 @@
+// Local diagnostics (build integration-health-1.0 spec 02 §2): what went wrong in
+// this app, said once per minute per code, never sent anywhere. The code list is a
+// copy of `src/shared/contracts/integration-health.ts`; a root test keeps them equal.
+// Imports nothing.
+export const DIAGNOSTIC_CODES = [
+    "BLV_DSN_MISSING",
+    "BLV_DSN_INVALID",
+    "BLV_INIT_CONFLICT",
+    "BLV_NOT_INITIALIZED",
+    "BLV_SEND_UNAUTHORIZED",
+    "BLV_SEND_RATE_LIMITED",
+    "BLV_SEND_REJECTED",
+    "BLV_SEND_NETWORK",
+    "BLV_SEND_SERVER",
+    "BLV_QUEUE_FULL",
+    "BLV_EVENT_TOO_LARGE",
+    "BLV_HOOK_MISSING",
+    "BLV_DROPPED_BY_APP",
+    "BLV_MONITOR_INVALID_SLUG",
+    "BLV_MONITOR_INVALID_REASON",
+    "BLV_MONITOR_CONFIG_INVALID",
+    "BLV_CHECK_IN_DROPPED",
+    "BLV_TRACE_TARGET_INVALID",
+];
+/** Public page explaining every code and the verification (one anchor per code). */
+export const VERIFY_DOCS_URL = "https://belvador.dev/en/docs/sdk/verify";
+/** One callback/console line per code per interval; repeats add to `count`. */
+export const DIAGNOSTIC_INTERVAL_MS = 60000;
+const MESSAGES = {
+    BLV_DSN_MISSING: "no DSN — the SDK is off",
+    BLV_DSN_INVALID: "the DSN is not valid — the SDK is off",
+    BLV_INIT_CONFLICT: "another error-tracking client is already running — init skipped",
+    BLV_NOT_INITIALIZED: "capture called while the SDK is not running",
+    BLV_SEND_UNAUTHORIZED: "the DSN key was refused (revoked or wrong project) — sending stopped",
+    BLV_SEND_RATE_LIMITED: "rate limited by Belvador — events are dropped until the wait ends",
+    BLV_SEND_REJECTED: "an event was rejected (too large or not accepted)",
+    BLV_SEND_NETWORK: "Belvador could not be reached after retries (network, CSP or ad blocker)",
+    BLV_SEND_SERVER: "Belvador answered with a server error after retries",
+    BLV_QUEUE_FULL: "the send queue is full — an event was dropped",
+    BLV_EVENT_TOO_LARGE: "an event or attachment is over the size limit — dropped",
+    BLV_HOOK_MISSING: "this server code does not run inside Belvador's middleware or wrapper",
+    BLV_DROPPED_BY_APP: "the event was dropped before sending (beforeSend, ignoreErrors or sampleRate)",
+    BLV_MONITOR_INVALID_SLUG: "a monitor slug is not valid (lowercase letters, digits, - and _, at most 64) — no check-in was sent",
+    BLV_MONITOR_INVALID_REASON: "a run reason is not a short code (lowercase letters, digits, . - _, at most 64) — it was left out",
+    BLV_MONITOR_CONFIG_INVALID: "a monitor schedule or setting is not valid — the check-in was sent without it",
+    BLV_CHECK_IN_DROPPED: "a check-in was dropped (too many waiting, rate limited or not sent)",
+    BLV_TRACE_TARGET_INVALID: "a tracePropagation target is not a string or RegExp — it was ignored",
+};
+const config = {
+    onDiagnostic: undefined,
+    debug: false,
+    sdk: { name: "", version: "" },
+    dsn: null,
+};
+const perCode = new Map();
+let lastSend = null;
+/** Anchor on the verification page for one code. */
+export function diagnosticDocsUrl(code) {
+    return `${VERIFY_DOCS_URL}#${code.toLowerCase().replace(/_/g, "-")}`;
+}
+export function diagnosticMessage(code) {
+    return MESSAGES[code];
+}
+/** Set by init (and by every Worker invocation). Never throws. */
+export function configureDiagnostics(next) {
+    try {
+        Object.assign(config, next);
+    }
+    catch {
+        /* frozen input */
+    }
+}
+function emit(d) {
+    const cb = config.onDiagnostic;
+    if (cb) {
+        try {
+            cb({ ...d });
+        }
+        catch {
+            /* a failing callback never reaches the app or the SDK */
+        }
+    }
+    if (config.debug) {
+        try {
+            console.warn(`[belvador] ${d.code}: ${MESSAGES[d.code]} — ${diagnosticDocsUrl(d.code)}`);
+        }
+        catch {
+            /* no console */
+        }
+    }
+}
+/** Records one occurrence; reports at most once per code per minute (NOT_INITIALIZED once). */
+export function reportDiagnostic(code, extra = {}, now = Date.now()) {
+    try {
+        const s = perCode.get(code) ?? { last: -Infinity, pending: 0, total: 0 };
+        s.total++;
+        s.pending++;
+        perCode.set(code, s);
+        const once = code === "BLV_NOT_INITIALIZED";
+        if (once ? s.total > 1 : now - s.last < DIAGNOSTIC_INTERVAL_MS)
+            return;
+        const d = { code, at: now, count: s.pending };
+        if (extra.status !== undefined)
+            d.status = extra.status;
+        if (extra.retryAfterS !== undefined)
+            d.retryAfterS = extra.retryAfterS;
+        s.last = now;
+        s.pending = 0;
+        emit(d);
+    }
+    catch {
+        /* never throws */
+    }
+}
+export function noteSend(status, now = Date.now()) {
+    lastSend = { status, at: now };
+}
+/** Fixed-size snapshot for support and AI agents; contains no event data. */
+export function snapshotDiagnostics(active) {
+    const counts = {};
+    for (const [code, s] of perCode)
+        counts[code] = s.total;
+    return {
+        active,
+        sdk: { ...config.sdk },
+        dsn: config.dsn ? { ...config.dsn } : null,
+        lastSend: lastSend ? { ...lastSend } : null,
+        counts,
+    };
+}
+/** Tests only: forget every count and setting. */
+export function resetDiagnostics() {
+    perCode.clear();
+    lastSend = null;
+    config.onDiagnostic = undefined;
+    config.debug = false;
+    config.sdk = { name: "", version: "" };
+    config.dsn = null;
+}

package/dist/facade.d.ts

@@ -1,7 +1,10 @@
 import type { Breadcrumb, ExclusiveEventHintOrCaptureContext, Scope, SeverityLevel } from "@sentry/core";
+import { type DiagnosticsSnapshot } from "./diagnostics.js";
 export type { Scope, SeverityLevel };
 /** True when the current scope's client was set up by a Belvador `init`. */
 export declare function isActive(): boolean;
+/** Local diagnostics snapshot (integration-health spec 02 §2.2); no event data. */
+export declare function getDiagnostics(): DiagnosticsSnapshot;
 /** Returns the event id (not a delivery receipt); "" when the SDK is off. */
 export declare function captureException(error: unknown, context?: ExclusiveEventHintOrCaptureContext): string;
 export declare function captureMessage(message: string, level?: SeverityLevel): string;

package/dist/facade.js

@@ -2,6 +2,7 @@
 // function is a no-op returning a neutral value when no Belvador client is
 // active, and never throws into the app.
 import { addBreadcrumb as engineAddBreadcrumb, captureException as engineCaptureException, captureMessage as engineCaptureMessage, close as engineClose, flush as engineFlush, getClient, lastEventId as engineLastEventId, setContext as engineSetContext, setTag as engineSetTag, setTags as engineSetTags, setUser as engineSetUser, withScope as engineWithScope, } from "@sentry/core";
+import { reportDiagnostic, snapshotDiagnostics } from "./diagnostics.js";
 import { BELVADOR_MARKER } from "./options.js";
 /** True when the current scope's client was set up by a Belvador `init`. */
 export function isActive() {
@@ -13,6 +14,10 @@ export function isActive() {
         return false;
     }
 }
+/** Local diagnostics snapshot (integration-health spec 02 §2.2); no event data. */
+export function getDiagnostics() {
+    return snapshotDiagnostics(isActive());
+}
 function guard(fallback, fn) {
     if (!isActive())
         return fallback;
@@ -25,9 +30,13 @@ function guard(fallback, fn) {
 }
 /** Returns the event id (not a delivery receipt); "" when the SDK is off. */
 export function captureException(error, context) {
+    if (!isActive())
+        reportDiagnostic("BLV_NOT_INITIALIZED");
     return guard("", () => engineCaptureException(error, context));
 }
 export function captureMessage(message, level) {
+    if (!isActive())
+        reportDiagnostic("BLV_NOT_INITIALIZED");
     return guard("", () => engineCaptureMessage(String(message), level));
 }
 export function addBreadcrumb(crumb) {

package/dist/index.d.ts

@@ -1,6 +1,13 @@
 export { SDK_VERSION, ENGINE_VERSION } from "./version.js";
 export { checkDsn, type BelvadorDsn } from "./dsn.js";
+export { isAbortError, isClientAbort, isViewTransitionSkip, noteClientAbort } from "./aborts.js";
+export { INTERVAL_UNITS, MONITOR_CONFIG_LIMITS, MONITOR_CONTEXT, MONITOR_SLUG_RE, RUN_CONTEXT, RUN_REASON_RE, buildCheckIn, captureCheckIn, heartbeat, monitorConfigOf, runIdOf, withMonitor, type CheckInInput, type IntervalUnit, type MonitorConfigInput, type MonitorSchedule, type RunHandle, type WithMonitorOptions, } from "./monitor.js";
+export { TRACE_OPTION, installTracePropagation, sentryTraceFromTraceparent, traceConfigOf, urlMatches, withIncomingTraceparent, type TraceConfig, type TracePropagationOptions, } from "./trace.js";
 export { FILTERED, SENSITIVE_KEY_PARTS, isSensitiveKey, scrubBreadcrumb, scrubEvent, scrubParams, scrubText, scrubValue, } from "./privacy.js";
-export { SEND_LIMITS, SENT_ITEM_TYPES, filterEnvelope, makeBelvadorTransport, sendWithRetry, type FetchLike, type SendPolicy, type SendState, } from "./transport.js";
+export { MAX_QUEUED_CHECK_INS, SEND_LIMITS, SENT_ITEM_TYPES, filterEnvelope, makeBelvadorTransport, sendWithRetry, type FetchLike, type SendPolicy, type SendState, } from "./transport.js";
 export { BELVADOR_MARKER, DEFAULT_MAX_BREADCRUMBS, MAX_BREADCRUMBS, MAX_VALUE_LENGTH, buildEngineOptions, warnOnce, type BelvadorBreadcrumb, type BelvadorEvent, type BelvadorEventHint, type BelvadorOptions, type EngineOptions, type RuntimeName, } from "./options.js";
-export { addBreadcrumb, captureException, captureMessage, close, flush, isActive, lastEventId, setContext, setTag, setTags, setUser, withScope, type Scope, type SeverityLevel, } from "./facade.js";
+export { addBreadcrumb, captureException, captureMessage, close, flush, getDiagnostics, isActive, lastEventId, setContext, setTag, setTags, setUser, withScope, type Scope, type SeverityLevel, } from "./facade.js";
+export { DIAGNOSTIC_CODES, DIAGNOSTIC_INTERVAL_MS, VERIFY_DOCS_URL, configureDiagnostics, diagnosticDocsUrl, diagnosticMessage, reportDiagnostic, resetDiagnostics, type Diagnostic, type DiagnosticCode, type DiagnosticsSnapshot, } from "./diagnostics.js";
+export { BelvadorVerificationError, VERIFICATION_CONTEXT, VERIFICATION_ERROR_TYPE, VERIFICATION_ID_RE, VERIFICATION_TAG, currentHooks, markHooked, newVerificationId, verificationOf, type HookKind, type VerificationContext, type VerificationSurface, } from "./verification.js";
+export { VERIFY_LIMITS, runVerification, type CheckName, type CheckStatus, type VerificationResult, type VerifyOptions, type VerifyRuntime, } from "./verify.js";
+export { diagnosticForStatus } from "./transport.js";

package/dist/index.js

@@ -3,7 +3,14 @@
 // /tanstack-start instead. Importing this module has no side effects.
 export { SDK_VERSION, ENGINE_VERSION } from "./version.js";
 export { checkDsn } from "./dsn.js";
+export { isAbortError, isClientAbort, isViewTransitionSkip, noteClientAbort } from "./aborts.js";
+export { INTERVAL_UNITS, MONITOR_CONFIG_LIMITS, MONITOR_CONTEXT, MONITOR_SLUG_RE, RUN_CONTEXT, RUN_REASON_RE, buildCheckIn, captureCheckIn, heartbeat, monitorConfigOf, runIdOf, withMonitor, } from "./monitor.js";
+export { TRACE_OPTION, installTracePropagation, sentryTraceFromTraceparent, traceConfigOf, urlMatches, withIncomingTraceparent, } from "./trace.js";
 export { FILTERED, SENSITIVE_KEY_PARTS, isSensitiveKey, scrubBreadcrumb, scrubEvent, scrubParams, scrubText, scrubValue, } from "./privacy.js";
-export { SEND_LIMITS, SENT_ITEM_TYPES, filterEnvelope, makeBelvadorTransport, sendWithRetry, } from "./transport.js";
+export { MAX_QUEUED_CHECK_INS, SEND_LIMITS, SENT_ITEM_TYPES, filterEnvelope, makeBelvadorTransport, sendWithRetry, } from "./transport.js";
 export { BELVADOR_MARKER, DEFAULT_MAX_BREADCRUMBS, MAX_BREADCRUMBS, MAX_VALUE_LENGTH, buildEngineOptions, warnOnce, } from "./options.js";
-export { addBreadcrumb, captureException, captureMessage, close, flush, isActive, lastEventId, setContext, setTag, setTags, setUser, withScope, } from "./facade.js";
+export { addBreadcrumb, captureException, captureMessage, close, flush, getDiagnostics, isActive, lastEventId, setContext, setTag, setTags, setUser, withScope, } from "./facade.js";
+export { DIAGNOSTIC_CODES, DIAGNOSTIC_INTERVAL_MS, VERIFY_DOCS_URL, configureDiagnostics, diagnosticDocsUrl, diagnosticMessage, reportDiagnostic, resetDiagnostics, } from "./diagnostics.js";
+export { BelvadorVerificationError, VERIFICATION_CONTEXT, VERIFICATION_ERROR_TYPE, VERIFICATION_ID_RE, VERIFICATION_TAG, currentHooks, markHooked, newVerificationId, verificationOf, } from "./verification.js";
+export { VERIFY_LIMITS, runVerification, } from "./verify.js";
+export { diagnosticForStatus } from "./transport.js";

package/dist/monitor.d.ts

@@ -0,0 +1,89 @@
+import type { Client, SerializedCheckIn } from "@sentry/core";
+export declare const MONITOR_SLUG_RE: RegExp;
+export declare const RUN_REASON_RE: RegExp;
+export declare const RUN_CONTEXT = "belvador_run";
+export declare const MONITOR_CONTEXT = "monitor";
+export declare const MONITOR_CONFIG_LIMITS: {
+    readonly intervalValueMax: 1000;
+    readonly checkinMarginMax: 1440;
+    readonly maxRuntimeMax: 10080;
+    readonly thresholdMax: 720;
+    readonly environmentMax: 64;
+    readonly attemptMax: 1000;
+};
+export declare const INTERVAL_UNITS: readonly ["minute", "hour", "day", "week", "month", "year"];
+export type IntervalUnit = (typeof INTERVAL_UNITS)[number];
+export type MonitorSchedule = {
+    type: "crontab";
+    value: string;
+} | {
+    type: "interval";
+    value: number;
+    unit: IntervalUnit;
+};
+/** Settings sent as `monitor_config` (creates or updates the monitor from code). */
+export type MonitorConfigInput = {
+    schedule: MonitorSchedule;
+    /** IANA time zone of a crontab, default UTC. */
+    timezone?: string;
+    /** Minutes a check-in may be late before it counts as missed (default 5). */
+    checkinMargin?: number;
+    /** Minutes a run may take before it counts as timed out (default 30). */
+    maxRuntime?: number;
+    /** Failing runs in a row before an incident opens (default 1). */
+    failureIssueThreshold?: number;
+    /** Healthy runs in a row before it closes (default 1). */
+    recoveryThreshold?: number;
+};
+export type WithMonitorOptions = Partial<MonitorConfigInput> & {
+    environment?: string;
+    /** Your id of the logical run (e.g. a queue message id); retries with the same id form one run. */
+    runId?: string;
+    /** 1 for the first try. */
+    attempt?: number;
+    /** True (or a function of the error) when your queue will try again after this error. */
+    willRetry?: boolean | ((error: unknown) => boolean);
+};
+export type RunHandle = {
+    readonly checkInId: string;
+    readonly runId: string;
+    /** The run did nothing on purpose (healthy). `reason` is a short code. */
+    skip(reason: string): void;
+    /** The run ended but its effect is unknown (e.g. a provider timed out after a side effect). */
+    unknown(reason: string): void;
+};
+export type CheckInInput = {
+    monitorSlug: string;
+    status: "in_progress" | "ok" | "error";
+    /** The id of the start check-in this one finishes; omitted = a new attempt. */
+    checkInId?: string;
+    /** Seconds. */
+    duration?: number;
+    environment?: string;
+    runId?: string;
+    attempt?: number;
+    willRetry?: boolean;
+    outcome?: "skipped" | "unknown";
+    reason?: string;
+};
+/** A UUID as 32 lowercase hex; any other id maps to a stable UUID-shaped hash (grouping only). */
+export declare function runIdOf(value: string): string;
+/** Wire `monitor_config`, or null (with a diagnostic) when anything is invalid. */
+export declare function monitorConfigOf(input: Partial<MonitorConfigInput> | undefined): Record<string, unknown> | null;
+/** The check-in item exactly as sent (exported for the golden test). */
+export declare function buildCheckIn(input: CheckInInput, client: Pick<Client, "getOptions">, config: Record<string, unknown> | null, trace: {
+    trace_id: string;
+    span_id: string;
+} | null): SerializedCheckIn & Record<string, unknown>;
+/** Sends one check-in; returns its id ("" when the SDK is off or the slug is invalid). Never throws. */
+export declare function captureCheckIn(checkIn: CheckInInput, monitorConfig?: MonitorConfigInput): string;
+/** A healthy check-in for an interval monitor ("still alive"). */
+export declare function heartbeat(slug: string, options?: {
+    environment?: string;
+}): void;
+/**
+ * Runs `fn` as one monitored attempt: `in_progress` first, then `ok` (or skipped/unknown
+ * via the handle) when it returns, or the error captured as a normal issue and `error`
+ * when it throws — the same value or error goes back to the caller, unchanged.
+ */
+export declare function withMonitor<T>(slug: string, fn: (run: RunHandle) => T, options?: WithMonitorOptions): T;