@schedulespark/observability 0.0.2-beta-1-0-0

package/dist/cli/rollup.js

@@ -0,0 +1,24 @@
+import { parseArgs } from "node:util";
+import { closeStorage, initStorage, rollupMetrics } from "../storage/index.js";
+import { parseCommonOptions, valueAsString } from "./options.js";
+const DEFAULT_RAW_RETENTION_DAYS = 3;
+/**
+ * Runs the `rollup` CLI subcommand: aggregates raw metric points into hourly/daily
+ * buckets, then prunes raw points older than the retention window. Intended to be
+ * invoked on a schedule (e.g. a cron job), the same way `prune` is.
+ */
+export async function runRollup(argv) {
+    const common = parseCommonOptions(argv);
+    const { values } = parseArgs({
+        args: argv,
+        options: { "raw-older-than-days": { type: "string" } },
+        allowPositionals: true,
+        strict: false
+    });
+    const rawRetentionDays = Number(valueAsString(values["raw-older-than-days"]) ?? DEFAULT_RAW_RETENTION_DAYS);
+    const handle = await initStorage(common);
+    const result = await rollupMetrics(handle, { rawRetentionDays });
+    console.error(`[observability] rolled up ${String(result.rolledUpBuckets)} metric buckets`);
+    console.error(`[observability] pruned ${String(result.prunedRawPoints)} raw metric points older than ${String(rawRetentionDays)} days`);
+    await closeStorage(handle);
+}

package/dist/cli/serve.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `serve` subcommand: runs the dashboard as its own standalone HTTP server, for teams
+ * who'd rather view it on a separate page than mount it inside a host application.
+ */
+export declare function runServe(argv: string[]): Promise<void>;

package/dist/cli/serve.js

@@ -0,0 +1,72 @@
+import { parseArgs } from "node:util";
+import Fastify from "fastify";
+import { slackWebhookChannel, webhookChannel } from "../alerts/index.js";
+import { createDashboard, registerDashboard } from "../dashboard/index.js";
+import { initStorage } from "../storage/index.js";
+import { parseCommonOptions, valueAsString } from "./options.js";
+const DEFAULT_PORT = 4318;
+/**
+ * `serve` subcommand: runs the dashboard as its own standalone HTTP server, for teams
+ * who'd rather view it on a separate page than mount it inside a host application.
+ */
+export async function runServe(argv) {
+    const common = parseCommonOptions(argv);
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            port: { type: "string" },
+            token: { type: "string" },
+            "ingest-key": { type: "string" },
+            webhook: { type: "string" },
+            "slack-webhook": { type: "string" }
+        },
+        allowPositionals: true,
+        strict: false
+    });
+    const port = parsePort(valueAsString(values.port));
+    const token = valueAsString(values.token) ?? process.env.OBSERVABILITY_TOKEN;
+    const ingestKey = valueAsString(values["ingest-key"]) ?? process.env.OBSERVABILITY_INGEST_KEY;
+    const channels = buildChannels(values);
+    const handle = await initStorage(common);
+    const app = Fastify({ logger: true });
+    registerDashboard(app, createDashboard(handle, { channels }), {
+        authorize: (request) => authorizeStandalone(request, token),
+        ingestKey
+    });
+    await app.listen({ port, host: "0.0.0.0" });
+    console.error(`[observability] dashboard listening on http://localhost:${String(port)}`);
+}
+/**
+ * Builds the alert channel list from `--webhook`/`--slack-webhook` flags or their
+ * `OBSERVABILITY_*` environment variable equivalents.
+ */
+function buildChannels(values) {
+    const channels = [];
+    const webhookUrl = valueAsString(values.webhook) ?? process.env.OBSERVABILITY_WEBHOOK_URL;
+    const slackUrl = valueAsString(values["slack-webhook"]) ?? process.env.OBSERVABILITY_SLACK_WEBHOOK_URL;
+    if (webhookUrl) {
+        channels.push(webhookChannel(webhookUrl));
+    }
+    if (slackUrl) {
+        channels.push(slackWebhookChannel(slackUrl));
+    }
+    return channels;
+}
+/**
+ * Parses and validates the `--port` flag, falling back to the default port.
+ */
+function parsePort(raw) {
+    const port = Number(raw ?? DEFAULT_PORT);
+    if (!Number.isInteger(port) || port <= 0) {
+        throw new Error(`Invalid --port value: "${raw ?? ""}"`);
+    }
+    return port;
+}
+/**
+ * Simple bearer-token check for standalone mode. When no token is configured, every
+ * request is allowed — hosts embedding the dashboard via `registerDashboard` directly
+ * are expected to supply their own `authorize` hook instead.
+ */
+function authorizeStandalone(request, token) {
+    return !token || request.headers.authorization === `Bearer ${token}`;
+}

package/dist/cli/sourcemap.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `sourcemap` subcommand: resolves a minified browser stack trace's frames back to
+ * original source locations, using `.map` files already produced by a build with
+ * `sourcemap: true` (e.g. `apps/web`'s Vite config). CLI-only for this pass — there's
+ * no dashboard-side automatic resolution, since that would need a release-to-map
+ * mapping this package doesn't have yet.
+ */
+export declare function runSourcemap(argv: string[]): Promise<void>;

package/dist/cli/sourcemap.js

@@ -0,0 +1,113 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { originalPositionFor, TraceMap } from "@jridgewell/trace-mapping";
+import { closeStorage, getIssueWithEvents, initStorage } from "../storage/index.js";
+import { valueAsString } from "./options.js";
+// The trailing `)`/whitespace is a lookahead, not part of the match itself, so
+// replacing `match[0]` below doesn't eat the frame's closing paren.
+const FRAME_LOCATION_PATTERN = /([^\s()]+\.js):(\d+):(\d+)(?=\)?\s*$)/;
+/**
+ * `sourcemap` subcommand: resolves a minified browser stack trace's frames back to
+ * original source locations, using `.map` files already produced by a build with
+ * `sourcemap: true` (e.g. `apps/web`'s Vite config). CLI-only for this pass — there's
+ * no dashboard-side automatic resolution, since that would need a release-to-map
+ * mapping this package doesn't have yet.
+ */
+export async function runSourcemap(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            maps: { type: "string" },
+            "stack-file": { type: "string" },
+            issue: { type: "string" },
+            db: { type: "string" },
+            schema: { type: "string" }
+        },
+        allowPositionals: true,
+        strict: false
+    });
+    const mapsDir = valueAsString(values.maps);
+    if (!mapsDir) {
+        throw new Error("A source maps directory is required: pass --maps <dir>.");
+    }
+    const stackTrace = await readStackTrace(values);
+    console.error(resolveStackTrace(stackTrace, mapsDir));
+}
+/**
+ * Reads the stack trace to resolve, either from a local file (`--stack-file`) or by
+ * fetching an issue's most recent event from storage (`--issue` plus `--db`).
+ */
+async function readStackTrace(values) {
+    const stackFile = valueAsString(values["stack-file"]);
+    if (stackFile) {
+        return readFileSync(stackFile, "utf8");
+    }
+    const issueId = valueAsString(values.issue);
+    const connectionString = valueAsString(values.db) ?? process.env.OBSERVABILITY_DATABASE_URL;
+    if (!issueId || !connectionString) {
+        throw new Error("Provide either --stack-file <path>, or --issue <id> and --db <connectionString>.");
+    }
+    const handle = await initStorage({ connectionString, schema: valueAsString(values.schema) });
+    const detail = await getIssueWithEvents(handle, issueId);
+    await closeStorage(handle);
+    const stackTrace = detail?.events[0]?.stackTrace;
+    if (!stackTrace) {
+        throw new Error(`No stack trace found for issue "${issueId}".`);
+    }
+    return stackTrace;
+}
+/**
+ * Resolves every frame in a stack trace, leaving lines with no recognizable
+ * `file.js:line:col` frame (or no matching `.map` file) unchanged.
+ */
+function resolveStackTrace(stackTrace, mapsDir) {
+    const cache = new Map();
+    return stackTrace
+        .split("\n")
+        .map((line) => resolveStackLine(line, mapsDir, cache))
+        .join("\n");
+}
+/**
+ * Resolves a single stack trace line's `file.js:line:col` frame, if present, to its
+ * original source location.
+ */
+function resolveStackLine(line, mapsDir, cache) {
+    const match = FRAME_LOCATION_PATTERN.exec(line);
+    if (!match) {
+        return line;
+    }
+    const [frame, filePath, lineNumber, columnNumber] = match;
+    const traceMap = loadTraceMap(filePath, mapsDir, cache);
+    if (!traceMap) {
+        return line;
+    }
+    const original = originalPositionFor(traceMap, {
+        line: Number(lineNumber),
+        column: Number(columnNumber)
+    });
+    if (!original.source) {
+        return line;
+    }
+    return line.replace(frame, `${original.source}:${String(original.line)}:${String(original.column)}`);
+}
+/**
+ * Loads (and caches) the `.map` file matching a minified file's basename from the
+ * maps directory, or `undefined` if none exists.
+ */
+function loadTraceMap(filePath, mapsDir, cache) {
+    const basename = path.basename(filePath);
+    if (cache.has(basename)) {
+        return cache.get(basename);
+    }
+    try {
+        const raw = readFileSync(path.join(mapsDir, `${basename}.map`), "utf8");
+        const traceMap = new TraceMap(JSON.parse(raw));
+        cache.set(basename, traceMap);
+        return traceMap;
+    }
+    catch {
+        cache.set(basename, undefined);
+        return undefined;
+    }
+}

package/dist/core/breadcrumbs.d.ts

@@ -0,0 +1,21 @@
+import type { Breadcrumb } from "./types.js";
+/**
+ * The fields a caller supplies to `addBreadcrumb()` — `timestamp` is stamped
+ * automatically by the buffer, never provided by the caller.
+ */
+export type BreadcrumbInput = Omit<Breadcrumb, "timestamp">;
+/**
+ * A bounded, drop-oldest ring buffer of recent breadcrumbs, snapshotted onto the next
+ * captured error/message rather than cleared afterward (a burst of related errors
+ * benefits from overlapping context, matching Sentry's own default).
+ */
+export interface BreadcrumbBuffer {
+    add: (breadcrumb: BreadcrumbInput) => void;
+    snapshot: () => Breadcrumb[];
+}
+/**
+ * Creates a breadcrumb ring buffer. Pure array operations only, no Node- or
+ * browser-only APIs, so unlike `fingerprint.ts` this is safe to use from — and export
+ * directly out of — the shared `core` barrel.
+ */
+export declare function createBreadcrumbBuffer(maxSize?: number): BreadcrumbBuffer;

package/dist/core/breadcrumbs.js

@@ -0,0 +1,20 @@
+const DEFAULT_MAX_BREADCRUMBS = 25;
+/**
+ * Creates a breadcrumb ring buffer. Pure array operations only, no Node- or
+ * browser-only APIs, so unlike `fingerprint.ts` this is safe to use from — and export
+ * directly out of — the shared `core` barrel.
+ */
+export function createBreadcrumbBuffer(maxSize = DEFAULT_MAX_BREADCRUMBS) {
+    const buffer = [];
+    return {
+        add(breadcrumb) {
+            buffer.push({ ...breadcrumb, timestamp: new Date().toISOString() });
+            if (buffer.length > maxSize) {
+                buffer.shift();
+            }
+        },
+        snapshot() {
+            return [...buffer];
+        }
+    };
+}

package/dist/core/fingerprint.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Computes a stable fingerprint used to group events into the same issue. Prefers the
+ * error type plus the top stack frames when available, falling back to the raw message
+ * for events without a stack trace (e.g. `captureMessage`).
+ */
+export declare function computeFingerprint(input: {
+    errorType?: string;
+    message: string;
+    stackTrace?: string;
+}): string;

package/dist/core/fingerprint.js

@@ -0,0 +1,35 @@
+import { createHash } from "node:crypto";
+const STACK_FRAMES_FOR_FINGERPRINT = 5;
+/**
+ * Strips file paths, line numbers, and column numbers from a stack trace line so that
+ * fingerprints stay stable across deploys where absolute paths or line numbers shift.
+ */
+function normalizeStackLine(line) {
+    return line
+        .trim()
+        .replace(/\(.*\)$/, "")
+        .replace(/:\d+:\d+$/, "")
+        .replace(/\s+/g, " ");
+}
+/**
+ * Extracts the top N normalized frames from a raw stack trace string, skipping the
+ * first line (the error message itself, not a stack frame).
+ */
+function topFrames(stackTrace) {
+    return stackTrace
+        .split("\n")
+        .slice(1, STACK_FRAMES_FOR_FINGERPRINT + 1)
+        .map(normalizeStackLine)
+        .filter((line) => line.length > 0);
+}
+/**
+ * Computes a stable fingerprint used to group events into the same issue. Prefers the
+ * error type plus the top stack frames when available, falling back to the raw message
+ * for events without a stack trace (e.g. `captureMessage`).
+ */
+export function computeFingerprint(input) {
+    const parts = input.stackTrace
+        ? [input.errorType ?? "Error", ...topFrames(input.stackTrace)]
+        : [input.errorType ?? "Message", input.message];
+    return createHash("sha1").update(parts.join("|")).digest("hex");
+}

package/dist/core/index.d.ts

@@ -0,0 +1,4 @@
+export { createBreadcrumbBuffer } from "./breadcrumbs.js";
+export { captureInputSchema, DEFAULT_PROJECT_ID } from "./types.js";
+export type { BreadcrumbBuffer, BreadcrumbInput } from "./breadcrumbs.js";
+export type { Breadcrumb, CaptureInput, CapturedEvent, Comment, EventContext, EventLevel, Issue, IssueStatus, LogEntry, LogLevel, MetricBucketSize, MetricKind, MetricPoint, MetricRollup, Project, RecordedSpan, SavedView, SavedViewFilters, SpanStatus } from "./types.js";

package/dist/core/index.js

@@ -0,0 +1,4 @@
+// `./fingerprint` is deliberately not re-exported here: it uses `node:crypto`, and
+// this barrel is imported by the browser SDK too. Storage imports it directly instead.
+export { createBreadcrumbBuffer } from "./breadcrumbs.js";
+export { captureInputSchema, DEFAULT_PROJECT_ID } from "./types.js";

package/dist/core/types.d.ts

@@ -0,0 +1,219 @@
+import { z } from "zod";
+/**
+ * Severity of a captured event.
+ */
+export type EventLevel = "error" | "warning" | "info";
+declare const eventContextSchema: z.ZodObject<{
+    method: z.ZodOptional<z.ZodString>;
+    route: z.ZodOptional<z.ZodString>;
+    statusCode: z.ZodOptional<z.ZodNumber>;
+    environment: z.ZodOptional<z.ZodString>;
+    release: z.ZodOptional<z.ZodString>;
+    userId: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    extra: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/**
+ * Contextual metadata attached to a captured event.
+ */
+export type EventContext = z.infer<typeof eventContextSchema>;
+declare const breadcrumbSchema: z.ZodObject<{
+    timestamp: z.ZodString;
+    category: z.ZodString;
+    message: z.ZodString;
+    level: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+        info: "info";
+    }>>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/**
+ * A single recorded action ("clicked X", "GET /api/foo → 200") leading up to a
+ * captured error.
+ */
+export type Breadcrumb = z.infer<typeof breadcrumbSchema>;
+export declare const captureInputSchema: z.ZodObject<{
+    level: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+        info: "info";
+    }>>;
+    message: z.ZodString;
+    errorType: z.ZodOptional<z.ZodString>;
+    stackTrace: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodObject<{
+        method: z.ZodOptional<z.ZodString>;
+        route: z.ZodOptional<z.ZodString>;
+        statusCode: z.ZodOptional<z.ZodNumber>;
+        environment: z.ZodOptional<z.ZodString>;
+        release: z.ZodOptional<z.ZodString>;
+        userId: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        extra: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    breadcrumbs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        timestamp: z.ZodString;
+        category: z.ZodString;
+        message: z.ZodString;
+        level: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            warning: "warning";
+            info: "info";
+        }>>;
+        data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/**
+ * Shape of a validated payload accepted from an SDK or the HTTP ingestion endpoint.
+ */
+export type CaptureInput = z.infer<typeof captureInputSchema>;
+/**
+ * A single event as persisted in storage, after fingerprinting.
+ */
+export interface CapturedEvent {
+    id: string;
+    fingerprint: string;
+    level: EventLevel;
+    message: string;
+    errorType: string | null;
+    stackTrace: string | null;
+    context: EventContext;
+    breadcrumbs: Breadcrumb[];
+    capturedAt: string;
+}
+/**
+ * Workflow status of a grouped issue.
+ */
+export type IssueStatus = "unresolved" | "resolved" | "ignored";
+/**
+ * A group of one or more events sharing the same fingerprint.
+ */
+export interface Issue {
+    id: string;
+    projectId: string;
+    fingerprint: string;
+    title: string;
+    level: EventLevel;
+    status: IssueStatus;
+    assignee: string | null;
+    eventCount: number;
+    firstSeen: string;
+    lastSeen: string;
+}
+/**
+ * A free-text note left on an issue.
+ */
+export interface Comment {
+    id: string;
+    issueId: string;
+    author: string;
+    body: string;
+    createdAt: string;
+}
+export declare const DEFAULT_PROJECT_ID = "default";
+/**
+ * A named grouping of issues/events, identified to ingestion clients by its own API
+ * key. Every install has at least the auto-created `"default"` project.
+ */
+export interface Project {
+    id: string;
+    name: string;
+    apiKey: string | null;
+    createdAt: string;
+}
+/**
+ * Outcome of a finished transaction or span.
+ */
+export type SpanStatus = "ok" | "error";
+/**
+ * A single timed operation: either a root transaction (`parentId: null`) or a span
+ * nested directly under one. Basic tracing only supports one level of nesting.
+ */
+export interface RecordedSpan {
+    id: string;
+    traceId: string;
+    parentId: string | null;
+    name: string;
+    status: SpanStatus;
+    startedAt: string;
+    durationMs: number;
+    tags: Record<string, string>;
+}
+/**
+ * The filter combination a saved view persists — the same shape as the issues list's
+ * own filters, so "apply a view" is just a link built from these fields.
+ */
+export interface SavedViewFilters {
+    status?: IssueStatus;
+    q?: string;
+    projectId?: string;
+}
+/**
+ * A named, persisted filter combination on the issues list (e.g. "Unresolved mobile
+ * errors"), shared across everyone with dashboard access — there's no per-user
+ * scoping, matching the rest of the dashboard's no-user-directory design.
+ */
+export interface SavedView {
+    id: string;
+    name: string;
+    filters: SavedViewFilters;
+    createdAt: string;
+}
+/**
+ * A structured log line's severity — pino's own level names, since that's what this
+ * feature forwards from.
+ */
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+/**
+ * A single structured log line, stored separately from `events`/`issues` — log lines
+ * don't share the "same bug, many occurrences" fingerprint-grouping semantics errors
+ * do, so they get their own table rather than a bolted-on second grouping scheme.
+ */
+export interface LogEntry {
+    id: string;
+    level: LogLevel;
+    message: string;
+    context: Record<string, unknown>;
+    loggedAt: string;
+}
+/**
+ * The kind of a single metric point — StatsD-shaped, matching the Node SDK's
+ * `client.metrics.increment/gauge/histogram()` API.
+ */
+export type MetricKind = "counter" | "gauge" | "histogram";
+/**
+ * A single raw metric data point. Tags directly multiply row count (one row per
+ * unique tag combination per point) — keep them to bounded-cardinality dimensions
+ * (e.g. `route`, `statusCode`), not free-form values like a user ID or request ID.
+ */
+export interface MetricPoint {
+    id: string;
+    name: string;
+    kind: MetricKind;
+    value: number;
+    tags: Record<string, string>;
+    recordedAt: string;
+}
+/**
+ * The rollup granularity a `MetricRollup` bucket was aggregated at.
+ */
+export type MetricBucketSize = "hour" | "day";
+/**
+ * A single aggregated bucket of raw metric points, sharing a name/tags combination
+ * and time window. `avg` is derived (`sum / count`), not stored.
+ */
+export interface MetricRollup {
+    id: string;
+    name: string;
+    kind: MetricKind;
+    bucketStart: string;
+    bucketSize: MetricBucketSize;
+    tags: Record<string, string>;
+    sum: number;
+    count: number;
+    min: number;
+    max: number;
+    avg: number;
+}
+export {};

package/dist/core/types.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+const eventLevelSchema = z.enum(["error", "warning", "info"]);
+const eventContextSchema = z.object({
+    method: z.string().max(16).optional(),
+    route: z.string().max(500).optional(),
+    statusCode: z.number().int().optional(),
+    environment: z.string().max(100).optional(),
+    release: z.string().max(200).optional(),
+    userId: z.string().max(200).optional(),
+    tags: z.record(z.string(), z.string()).optional(),
+    extra: z.record(z.string(), z.unknown()).optional()
+});
+const MAX_BREADCRUMBS_PER_EVENT = 100;
+const breadcrumbSchema = z.object({
+    timestamp: z.string(),
+    category: z.string().max(50),
+    message: z.string().max(500),
+    level: eventLevelSchema.optional(),
+    data: z.record(z.string(), z.unknown()).optional()
+});
+export /**
+        * Validated payload accepted from an SDK or the HTTP ingestion endpoint.
+        */ const captureInputSchema = z.object({
+    level: eventLevelSchema.default("error"),
+    message: z.string().min(1).max(2000),
+    errorType: z.string().max(200).optional(),
+    stackTrace: z.string().max(20000).optional(),
+    context: eventContextSchema.optional(),
+    breadcrumbs: z.array(breadcrumbSchema).max(MAX_BREADCRUMBS_PER_EVENT).optional()
+});
+export /**
+        * The `projectId` every issue/event belongs to when no multi-project setup
+        * has been configured — a fresh single-project install behaves identically to
+        * before multi-project support existed.
+        */ const DEFAULT_PROJECT_ID = "default";

package/dist/dashboard/core.d.ts

@@ -0,0 +1,67 @@
+import type { NotificationChannel } from "../alerts/index.js";
+import type { CapturedEvent, Comment, Issue, IssueStatus, LogEntry, LogLevel, MetricBucketSize, MetricRollup, Project, RecordedSpan, SavedView, SavedViewFilters } from "../core/index.js";
+import type { StorageHandle } from "../storage/index.js";
+/**
+ * Result of attempting to ingest a single capture payload.
+ */
+export type IngestResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Filters accepted by `Dashboard.listIssues`.
+ */
+export interface ListIssuesOptions {
+    status?: IssueStatus;
+    q?: string;
+    projectId?: string;
+}
+/**
+ * Framework-agnostic dashboard operations: ingestion plus the read/update queries
+ * the UI needs. Kept independent of any HTTP framework so a new server adapter
+ * (Fastify, Express, a future Next.js route) only has to translate requests/responses,
+ * never reimplement this logic.
+ */
+export interface Dashboard {
+    ingest: (payload: unknown, projectId?: string) => Promise<IngestResult>;
+    listIssues: (options?: ListIssuesOptions) => Promise<Issue[]>;
+    getIssue: (id: string) => Promise<{
+        issue: Issue;
+        events: CapturedEvent[];
+        comments: Comment[];
+    } | null>;
+    updateIssueStatus: (id: string, status: IssueStatus) => Promise<Issue | null>;
+    assignIssue: (id: string, assignee: string | null) => Promise<Issue | null>;
+    addComment: (id: string, input: {
+        author: string;
+        body: string;
+    }) => Promise<Comment>;
+    listTransactions: () => Promise<RecordedSpan[]>;
+    listProjects: () => Promise<Project[]>;
+    resolveProjectId: (apiKey: string | undefined) => Promise<string>;
+    listSavedViews: () => Promise<SavedView[]>;
+    createSavedView: (name: string, filters: SavedViewFilters) => Promise<SavedView>;
+    deleteSavedView: (id: string) => Promise<void>;
+    listLogs: (options?: {
+        level?: LogLevel;
+        projectId?: string;
+    }) => Promise<LogEntry[]>;
+    listMetricRollups: (options?: {
+        bucketSize?: MetricBucketSize;
+        projectId?: string;
+    }) => Promise<MetricRollup[]>;
+}
+/**
+ * Options for building the dashboard operations.
+ */
+export interface DashboardOptions {
+    channels?: NotificationChannel[];
+}
+/**
+ * Builds the dashboard operations bound to a storage handle. Ingested events notify
+ * any configured alert channels the same way the Node SDK does, so alerts fire
+ * regardless of whether an event arrived in-process or over HTTP.
+ */
+export declare function createDashboard(storage: StorageHandle, options?: DashboardOptions): Dashboard;