@pantree/js

Official JavaScript / Node.js SDK for Pantree — lightweight error monitoring and encrypted health reporting.

Works in Node.js 18+, modern browsers, Cloudflare Workers, and any runtime that exposes the Web Crypto API.

Table of Contents

• Installation
• Quick Start
• Configuration
• Capturing Errors
• Health Reporting
• Framework Guides
• API Reference
• Changelog

Installation

npm install @pantree/js
# or
pnpm add @pantree/js
# or
yarn add @pantree/js

Package Layout

• index.js - SDK runtime and exports
• docs/ - API, setup, migration, and health reporting docs
• examples/ - Node, Next.js, and browser integration examples
• CHANGELOG.md - release history

Quick Start

Grab your DSN from Project → Settings in the Pantree dashboard.

import Pantree from "@pantree/js";

Pantree.init({
  dsn: "https://API_KEY:[email protected]/api/ingest",
  environment: "production",
  healthReporting: true,   // send encrypted health reports every 30 min
});

// Capture an error
try {
  riskyOperation();
} catch (err) {
  Pantree.captureException(err);
}

// Capture a message
Pantree.captureMessage("User hit rate limit", { level: "warning" });

Configuration

| Option | Type | Default | Description | |---|---|---|---| | dsn | string | required | Project DSN from the Pantree dashboard | | environment | string | "production" | Deployment environment tag | | release | string | null | Release / version string | | debug | boolean | false | Log SDK activity to the console | | healthReporting | boolean \| { interval?: number } | false | Enable periodic encrypted health reports. Pass { interval: ms } to customise the interval (default 30 min) |

DSN format

https://<apiKey>:<ingestSecret>@<host>/api/ingest

Capturing Errors

captureException(err, extra?)

import Pantree from "@pantree/js";

Pantree.captureException(new Error("Payment failed"), {
  level: "error",
  user: { id: "usr_123", email: "[email protected]" },
  context: { orderId: "ord_456", amount: 99.99 },
});

captureMessage(message, extra?)

Pantree.captureMessage("Slow query detected", {
  level: "warning",
  context: { queryMs: 4200 },
});

Event fields

| Field | Type | Description | |---|---|---| | message | string | Human-readable description | | title | string | Short error title / name | | stack | string | Stack trace string | | level | "error" \| "warning" \| "info" \| "debug" | Severity | | environment | string | Override the global environment | | runtime | string | e.g. "node", "browser", "edge" | | url | string | URL where the error occurred | | commit | object | { message, author, hash } | | user | object | { id, email, name } | | breadcrumbs | array | Ordered list of events leading up to the error | | context | object | Any additional key-value pairs |

Health Reporting

When healthReporting: true is set in init(), the SDK sends an AES-256-GCM encrypted system snapshot to /api/health-report every 30 minutes. Only super-admins on your Pantree instance can decrypt and read it.

What is collected (Node.js):

| Category | Fields | |---|---| | OS | platform, release, arch, hostname, uptime | | Memory | total GB, free GB, used % | | Disk | total GB, free GB, used % | | Network | local IP, public IP (from your own /api/ip), MAC address, interface name | | Machine | machine ID, container/VM detection | | Git | username, email, commit hash, branch, tag, repo URL | | Meta | SDK version, Node version, timestamp |

// Manual one-off report
await Pantree.sendHealthReport();

// Custom interval — every 15 minutes
Pantree.init({
  dsn: "...",
  healthReporting: { interval: 15 * 60 * 1000 },
});

// Stop the reporter (e.g. on graceful shutdown)
Pantree.stopHealthReporter();

Privacy note: No data is stored in plain text. The entire payload is encrypted client-side before leaving the machine.

Framework Guides

Next.js

See examples/next-js.js for a full instrumentation.ts + error boundary setup.

Express / Node HTTP

See examples/node-express.js.

Browser (vanilla)

See examples/browser.html.

API Reference

Full API reference: docs/api-reference.md

Changelog

See CHANGELOG.md.

License

MIT