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

package/dist/storage/rows.d.ts

@@ -0,0 +1,151 @@
+import type { Breadcrumb, CapturedEvent, Comment, EventContext, Issue, LogEntry, MetricPoint, MetricRollup, Project, RecordedSpan, SavedView, SavedViewFilters } from "../core/index.js";
+/**
+ * Raw shape of a row in the `issues` table.
+ */
+export interface IssueRow {
+    id: string;
+    project_id: string;
+    fingerprint: string;
+    title: string;
+    level: string;
+    status: string;
+    assignee: string | null;
+    event_count: number;
+    first_seen: Date;
+    last_seen: Date;
+}
+/**
+ * Raw shape of a row in the `projects` table.
+ */
+export interface ProjectRow {
+    id: string;
+    name: string;
+    api_key: string | null;
+    created_at: Date;
+}
+/**
+ * Raw shape of a row in the `comments` table.
+ */
+export interface CommentRow {
+    id: string;
+    issue_id: string;
+    author: string;
+    body: string;
+    created_at: Date;
+}
+/**
+ * Raw shape of a row in the `events` table.
+ */
+export interface EventRow {
+    id: string;
+    fingerprint: string;
+    level: string;
+    message: string;
+    error_type: string | null;
+    stack_trace: string | null;
+    context: EventContext;
+    breadcrumbs: Breadcrumb[];
+    captured_at: Date;
+}
+/**
+ * Converts a raw `issues` row into the public `Issue` shape.
+ */
+export declare function mapIssueRow(row: IssueRow): Issue;
+/**
+ * Converts a raw `comments` row into the public `Comment` shape.
+ */
+export declare function mapCommentRow(row: CommentRow): Comment;
+/**
+ * Converts a raw `events` row into the public `CapturedEvent` shape.
+ */
+export declare function mapEventRow(row: EventRow): CapturedEvent;
+/**
+ * Raw shape of a row in the `spans` table.
+ */
+export interface SpanRow {
+    id: string;
+    trace_id: string;
+    parent_id: string | null;
+    name: string;
+    status: string;
+    started_at: Date;
+    duration_ms: number;
+    tags: Record<string, string>;
+}
+/**
+ * Converts a raw `spans` row into the public `RecordedSpan` shape.
+ */
+export declare function mapSpanRow(row: SpanRow): RecordedSpan;
+/**
+ * Converts a raw `projects` row into the public `Project` shape.
+ */
+export declare function mapProjectRow(row: ProjectRow): Project;
+/**
+ * Raw shape of a row in the `saved_views` table.
+ */
+export interface SavedViewRow {
+    id: string;
+    name: string;
+    filters: SavedViewFilters;
+    created_at: Date;
+}
+/**
+ * Converts a raw `saved_views` row into the public `SavedView` shape.
+ */
+export declare function mapSavedViewRow(row: SavedViewRow): SavedView;
+/**
+ * Raw shape of a row in the `logs` table.
+ */
+export interface LogRow {
+    id: string;
+    level: string;
+    message: string;
+    context: Record<string, unknown>;
+    logged_at: Date;
+}
+/**
+ * Converts a raw `logs` row into the public `LogEntry` shape.
+ */
+export declare function mapLogRow(row: LogRow): LogEntry;
+/**
+ * Raw shape of a row in the `metric_points_raw` table.
+ */
+export interface MetricPointRow {
+    id: string;
+    name: string;
+    kind: string;
+    value: number;
+    tags: Record<string, string>;
+    recorded_at: Date;
+}
+/**
+ * Converts a raw `metric_points_raw` row into the public `MetricPoint` shape.
+ */
+export declare function mapMetricPointRow(row: MetricPointRow): MetricPoint;
+/**
+ * Raw shape of a row in the `metric_rollups` table.
+ */
+export interface MetricRollupRow {
+    id: string;
+    name: string;
+    kind: string;
+    bucket_start: Date;
+    bucket_size: string;
+    tags: Record<string, string>;
+    sum: number;
+    count: number;
+    min: number;
+    max: number;
+}
+/**
+ * Converts a raw `metric_rollups` row into the public `MetricRollup` shape,
+ * deriving `avg` (not stored) from `sum`/`count`.
+ */
+export declare function mapMetricRollupRow(row: MetricRollupRow): MetricRollup;
+/**
+ * Derives a short human-readable issue title from a capture input.
+ */
+export declare function deriveTitle(input: {
+    errorType?: string;
+    message: string;
+}): string;

package/dist/storage/rows.js

@@ -0,0 +1,134 @@
+/**
+ * Converts a raw `issues` row into the public `Issue` shape.
+ */
+export function mapIssueRow(row) {
+    return {
+        id: row.id,
+        projectId: row.project_id,
+        fingerprint: row.fingerprint,
+        title: row.title,
+        level: row.level,
+        status: row.status,
+        assignee: row.assignee,
+        eventCount: row.event_count,
+        firstSeen: row.first_seen.toISOString(),
+        lastSeen: row.last_seen.toISOString()
+    };
+}
+/**
+ * Converts a raw `comments` row into the public `Comment` shape.
+ */
+export function mapCommentRow(row) {
+    return {
+        id: row.id,
+        issueId: row.issue_id,
+        author: row.author,
+        body: row.body,
+        createdAt: row.created_at.toISOString()
+    };
+}
+/**
+ * Converts a raw `events` row into the public `CapturedEvent` shape.
+ */
+export function mapEventRow(row) {
+    return {
+        id: row.id,
+        fingerprint: row.fingerprint,
+        level: row.level,
+        message: row.message,
+        errorType: row.error_type,
+        stackTrace: row.stack_trace,
+        context: row.context,
+        breadcrumbs: row.breadcrumbs,
+        capturedAt: row.captured_at.toISOString()
+    };
+}
+/**
+ * Converts a raw `spans` row into the public `RecordedSpan` shape.
+ */
+export function mapSpanRow(row) {
+    return {
+        id: row.id,
+        traceId: row.trace_id,
+        parentId: row.parent_id,
+        name: row.name,
+        status: row.status,
+        startedAt: row.started_at.toISOString(),
+        durationMs: row.duration_ms,
+        tags: row.tags
+    };
+}
+/**
+ * Converts a raw `projects` row into the public `Project` shape.
+ */
+export function mapProjectRow(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        apiKey: row.api_key,
+        createdAt: row.created_at.toISOString()
+    };
+}
+/**
+ * Converts a raw `saved_views` row into the public `SavedView` shape.
+ */
+export function mapSavedViewRow(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        filters: row.filters,
+        createdAt: row.created_at.toISOString()
+    };
+}
+/**
+ * Converts a raw `logs` row into the public `LogEntry` shape.
+ */
+export function mapLogRow(row) {
+    return {
+        id: row.id,
+        level: row.level,
+        message: row.message,
+        context: row.context,
+        loggedAt: row.logged_at.toISOString()
+    };
+}
+/**
+ * Converts a raw `metric_points_raw` row into the public `MetricPoint` shape.
+ */
+export function mapMetricPointRow(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        kind: row.kind,
+        value: row.value,
+        tags: row.tags,
+        recordedAt: row.recorded_at.toISOString()
+    };
+}
+/**
+ * Converts a raw `metric_rollups` row into the public `MetricRollup` shape,
+ * deriving `avg` (not stored) from `sum`/`count`.
+ */
+export function mapMetricRollupRow(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        kind: row.kind,
+        bucketStart: row.bucket_start.toISOString(),
+        bucketSize: row.bucket_size,
+        tags: row.tags,
+        sum: row.sum,
+        count: row.count,
+        min: row.min,
+        max: row.max,
+        avg: row.count > 0 ? row.sum / row.count : 0
+    };
+}
+const MAX_TITLE_LENGTH = 200;
+/**
+ * Derives a short human-readable issue title from a capture input.
+ */
+export function deriveTitle(input) {
+    const title = input.errorType ? `${input.errorType}: ${input.message}` : input.message;
+    return title.length > MAX_TITLE_LENGTH ? `${title.slice(0, MAX_TITLE_LENGTH)}…` : title;
+}

package/dist/storage/saved-views.d.ts

@@ -0,0 +1,15 @@
+import type { StorageHandle } from "./pool.js";
+import type { SavedView, SavedViewFilters } from "../core/index.js";
+/**
+ * Persists a named filter combination so it can be revisited later from the issues
+ * list.
+ */
+export declare function createSavedView(handle: StorageHandle, name: string, filters: SavedViewFilters): Promise<SavedView>;
+/**
+ * Lists every saved view, oldest first.
+ */
+export declare function listSavedViews(handle: StorageHandle): Promise<SavedView[]>;
+/**
+ * Deletes a saved view by id. A no-op if it doesn't exist.
+ */
+export declare function deleteSavedView(handle: StorageHandle, id: string): Promise<void>;

package/dist/storage/saved-views.js

@@ -0,0 +1,28 @@
+import { randomUUID } from "node:crypto";
+import { mapSavedViewRow } from "./rows.js";
+/**
+ * Persists a named filter combination so it can be revisited later from the issues
+ * list.
+ */
+export async function createSavedView(handle, name, filters) {
+    await handle.ready;
+    const { rows } = await handle.pool.query(`INSERT INTO ${handle.quotedSchema}.saved_views (id, name, filters, created_at)
+     VALUES ($1, $2, $3, now())
+     RETURNING *`, [randomUUID(), name, filters]);
+    return mapSavedViewRow(rows[0]);
+}
+/**
+ * Lists every saved view, oldest first.
+ */
+export async function listSavedViews(handle) {
+    await handle.ready;
+    const { rows } = await handle.pool.query(`SELECT * FROM ${handle.quotedSchema}.saved_views ORDER BY created_at ASC`);
+    return rows.map(mapSavedViewRow);
+}
+/**
+ * Deletes a saved view by id. A no-op if it doesn't exist.
+ */
+export async function deleteSavedView(handle, id) {
+    await handle.ready;
+    await handle.pool.query(`DELETE FROM ${handle.quotedSchema}.saved_views WHERE id = $1`, [id]);
+}

package/dist/storage/schema-ident.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Validates and double-quotes a Postgres schema name for safe interpolation into SQL.
+ * Schema names cannot be bind parameters in `pg`, so this is the only place a
+ * caller-supplied string is concatenated into a query — restricting the character set
+ * here rules out SQL injection via a malicious/misconfigured schema option.
+ */
+export declare function quoteSchemaIdentifier(schema: string): string;

package/dist/storage/schema-ident.js

@@ -0,0 +1,13 @@
+const VALID_IDENTIFIER = /^[a-z_][a-z0-9_]*$/;
+/**
+ * Validates and double-quotes a Postgres schema name for safe interpolation into SQL.
+ * Schema names cannot be bind parameters in `pg`, so this is the only place a
+ * caller-supplied string is concatenated into a query — restricting the character set
+ * here rules out SQL injection via a malicious/misconfigured schema option.
+ */
+export function quoteSchemaIdentifier(schema) {
+    if (!VALID_IDENTIFIER.test(schema)) {
+        throw new Error(`Invalid observability schema name "${schema}": must match ${VALID_IDENTIFIER.source}`);
+    }
+    return `"${schema}"`;
+}

package/dist/storage/spans.d.ts

@@ -0,0 +1,14 @@
+import type { StorageHandle } from "./pool.js";
+import type { RecordedSpan } from "../core/index.js";
+/**
+ * Persists a finished transaction or span.
+ */
+export declare function recordSpan(handle: StorageHandle, span: RecordedSpan): Promise<void>;
+/**
+ * Lists root transactions (spans with no parent) ordered by most recent first. Basic
+ * tracing only supports one level of nesting, so child spans aren't listed
+ * separately — they exist in storage but have no dashboard view yet.
+ */
+export declare function listTransactions(handle: StorageHandle, options?: {
+    limit?: number;
+}): Promise<RecordedSpan[]>;

package/dist/storage/spans.js

@@ -0,0 +1,21 @@
+import { mapSpanRow } from "./rows.js";
+const DEFAULT_TRANSACTION_LIST_LIMIT = 100;
+/**
+ * Persists a finished transaction or span.
+ */
+export async function recordSpan(handle, span) {
+    await handle.ready;
+    await handle.pool.query(`INSERT INTO ${handle.quotedSchema}.spans
+       (id, trace_id, parent_id, name, status, started_at, duration_ms, tags)
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`, [span.id, span.traceId, span.parentId, span.name, span.status, span.startedAt, span.durationMs, span.tags]);
+}
+/**
+ * Lists root transactions (spans with no parent) ordered by most recent first. Basic
+ * tracing only supports one level of nesting, so child spans aren't listed
+ * separately — they exist in storage but have no dashboard view yet.
+ */
+export async function listTransactions(handle, options = {}) {
+    await handle.ready;
+    const { rows } = await handle.pool.query(`SELECT * FROM ${handle.quotedSchema}.spans WHERE parent_id IS NULL ORDER BY started_at DESC LIMIT $1`, [options.limit ?? DEFAULT_TRANSACTION_LIST_LIMIT]);
+    return rows.map(mapSpanRow);
+}

package/docs/standalone-example.md

@@ -0,0 +1,110 @@
+# Standalone example: using this package outside the ScheduleSpark monorepo
+
+This package isn't published to npm yet (`private: true` in `package.json` — see the
+[README's Status section](../README.md#status)), so the commands below describe the
+intended experience once it is, plus how to try the same thing today from inside this
+monorepo via a workspace link. The application code itself (everything after
+`npm install`) doesn't change between the two.
+
+## The scenario
+
+A separate Node/Fastify service, outside this monorepo entirely, that wants:
+
+- Error capture with no extra service to run.
+- A dashboard mounted at `/observability` inside that same service.
+- Its own Postgres database (or a spare schema in an existing one) as the only new
+  piece of infrastructure.
+
+## Once published: real `npm install`
+
+```sh
+npm install @schedulespark/observability pg fastify
+```
+
+`pg` and `fastify` are peer dependencies — this package never bundles its own copy of
+either, so it always talks to the same Postgres/Fastify version your app already runs.
+
+`server.ts`:
+
+```ts
+import Fastify from "fastify";
+import { init, captureFastifyErrors } from "@schedulespark/observability/node";
+import { createDashboard, registerDashboard } from "@schedulespark/observability/dashboard";
+import { initStorage } from "@schedulespark/observability/storage";
+
+const app = Fastify();
+
+const client = init({ connectionString: process.env.OBSERVABILITY_DATABASE_URL! });
+captureFastifyErrors(app, client);
+
+const storage = await initStorage({ connectionString: process.env.OBSERVABILITY_DATABASE_URL! });
+registerDashboard(app, createDashboard(storage), {
+  prefix: "/observability",
+  // Replace with your own auth check before exposing this beyond localhost — an
+  // unconfigured `authorize` allows every request through by default.
+  authorize: (request) => request.headers["x-admin-token"] === process.env.ADMIN_TOKEN
+});
+
+app.get("/", (_request, reply) => reply.send({ ok: true }));
+
+await app.listen({ port: 3000 });
+```
+
+```sh
+export OBSERVABILITY_DATABASE_URL="postgresql://user:pass@localhost:5432/myapp"
+export ADMIN_TOKEN="pick-a-real-secret"
+npx tsx server.ts
+```
+
+Migrations run automatically on first `init()`/`initStorage()` call — no separate
+migration step needed for local dev. Then:
+
+- `curl localhost:3000/nonexistent-route-that-throws` to generate a test error.
+- Open `http://localhost:3000/observability` (with the `x-admin-token` header, or swap
+  `authorize` for a browser-friendly session check) to see it show up.
+
+For production, run migrations explicitly during deploy instead of relying on the
+implicit on-`init()` migration:
+
+```sh
+npx @schedulespark/observability migrate --db "$OBSERVABILITY_DATABASE_URL"
+```
+
+## Right now, from inside this monorepo: a workspace link
+
+Until this package is published, the same `server.ts` above works unmodified from a
+throwaway directory inside this monorepo by linking to the local package instead of
+installing from npm:
+
+```sh
+mkdir -p /tmp/observability-example && cd /tmp/observability-example
+npm init -y
+npm install fastify tsx
+npm link /path/to/schedulespark/packages/observability
+```
+
+Everything else — the `server.ts` content, the env vars, the `migrate`/`serve` CLI
+commands — is identical to the published-package version above. This is exactly what
+`apps/api`'s own dogfood integration does (via a `workspace:*` dependency instead of
+`npm link`), just outside the monorepo's build tooling.
+
+## Running fully standalone (no host app at all)
+
+If you don't want to write any server code, the CLI runs the same dashboard on its own
+port:
+
+```sh
+npx @schedulespark/observability serve --db "$OBSERVABILITY_DATABASE_URL" --port 4318 \
+  --token "$OBSERVABILITY_TOKEN" --ingest-key "$OBSERVABILITY_INGEST_KEY"
+```
+
+Point the Node SDK's `client.captureException(...)` calls (or the browser SDK's
+`init({ ingestUrl: "http://localhost:4318/ingest", apiKey: ... })`) at that same host
+and port — no code from this walkthrough's `server.ts` is needed in that mode.
+
+## What this walkthrough intentionally doesn't cover
+
+- A full example *application* (e.g. a sample Express/Next.js app committed to this
+  repo) — deferred; see the plan's Phase 5 notes. This doc is a copy-pasteable
+  quickstart, not a maintained sample app.
+- Non-Node ingestion (Python/Go/etc.) — out of scope for this package entirely.

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@schedulespark/observability",
+  "version": "0.0.2-beta-1-0-0",
+  "description": "Self-hosted, Sentry-style error tracking and dashboard that stores captured events in your own Postgres database.",
+  "license": "MIT",
+  "author": "Stephen M",
+  "type": "module",
+  "files": [
+    "CHANGELOG.md",
+    "dist",
+    "docs",
+    "README.md",
+    "SECURITY_REVIEW.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "schedulespark-observability": "./dist/cli/bin.js"
+  },
+  "exports": {
+    "./alerts": {
+      "types": "./dist/alerts/index.d.ts",
+      "import": "./dist/alerts/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
+    },
+    "./storage": {
+      "types": "./dist/storage/index.d.ts",
+      "import": "./dist/storage/index.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "import": "./dist/browser/index.js"
+    },
+    "./dashboard": {
+      "types": "./dist/dashboard/index.d.ts",
+      "import": "./dist/dashboard/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "import": "./dist/cli/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mstephenn/schedulespark.git",
+    "directory": "packages/observability"
+  },
+  "keywords": [
+    "observability",
+    "error-tracking",
+    "sentry",
+    "self-hosted",
+    "fastify",
+    "postgres"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "lint": "eslint src --max-warnings=0 && tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json"
+  },
+  "dependencies": {
+    "@jridgewell/trace-mapping": "^0.3.31",
+    "nodemailer": "^9.0.3",
+    "pg": "^8.16.3",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@prisma/client": "^7.8.0",
+    "fastify": "^5.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@prisma/client": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@jridgewell/gen-mapping": "^0.3.13",
+    "@types/jsdom": "^28.0.3",
+    "@types/node": "^26.0.1",
+    "@types/nodemailer": "^8.0.1",
+    "@types/pg": "^8.16.0",
+    "fastify": "^5.9.0",
+    "jsdom": "^29.1.1",
+    "pino": "^10.3.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}