@deployowl/deployowl

Official SDK for DeployOwl error tracking.

Security Notice (v2.3.0+)

This version fixes MAL-2026-10677. The SDK now follows the Sentry model: collect what's useful for analysis, scrub what's sensitive, document everything, let the user control it.

| Behavior | v2.1.0 (vulnerable) | v2.3.0 (fixed) | |---|---|---| | Environment variables | ❌ Iterated ALL of process.env, weak keyword redaction, leaked 3-char secret prefixes | ✅ Allowlist — only vars explicitly listed in allowedEnvVars are sent (default: empty) | | eval('require') to evade static analysis | ❌ Present | ✅ Removed — uses module.createRequire() (legitimate, scanner-visible) | | package.json dependency upload | ❌ Full manifest via eval('require') | ✅ Name+version pairs only via collectDependencies (default: true) | | Infrastructure sync (nodeVersion/platform/arch) | ❌ Auto-on, undocumented | ✅ Auto-on, documented (collectInfrastructure: true) | | Health metrics sync (CPU/memory/lag) | ❌ Auto-on, undocumented | ✅ Auto-on, documented (collectHealth: true) | | Console monkey-patching for breadcrumbs | ❌ Auto-on, undocumented | ✅ Tied to autoCapture (documented below) | | Hardcoded shared secret | ❌ DEPLOYOWL_SUPER_SECRET_2026_XYZ | ✅ Removed |

No secrets are collected. The SDK does not iterate process.env. Only vars you explicitly allowlist are sent.

Installation

npm install @deployowl/deployowl

Usage

Basic Setup

import { init, captureError } from '@deployowl/deployowl';

init({
  apiKey: 'your-api-key',
  environment: 'production'
});

try {
  riskyOperation();
} catch (error) {
  captureError(error);
  throw error;
}

With Context

captureError(error, {
  userId: '123',
  action: 'checkout',
  cart: { items: 3, total: 99.99 }
});

Set User Info

import { setUser } from '@deployowl/deployowl';

setUser({
  id: 'user_123',
  email: '[email protected]'
});

Configuration Options

init({
  apiKey: 'your-api-key',              // Required
  endpoint: 'https://custom.com',      // Optional: custom endpoint (default: https://api.deployowl.com)
  environment: 'staging',               // Optional: environment tag
  batchSize: 10,                        // Optional: errors per flush (default: 10)
  flushInterval: 5000,                  // Optional: ms between flushes (default: 5000)
  maxBreadcrumbs: 50,                   // Optional: breadcrumb buffer size (default: 50)
  debug: false,                         // Optional: verbose logging (default: false)
  dryRun: false,                        // Optional: log payloads instead of sending (default: false)
  autoCapture: true,                    // Optional: capture uncaughtException/unhandledRejection + console breadcrumbs (default: true)
  collectDependencies: true,            // Optional: send package name+version pairs on init (default: true)
  collectInfrastructure: true,          // Optional: send nodeVersion/platform/arch on init (default: true)
  collectHealth: true,                  // Optional: periodically send CPU/memory/event-loop metrics (default: true)
  healthInterval: 3600000,              // Optional: ms between health syncs (default: 3600000 = 1 hour)
  allowedEnvVars: [],                   // Optional: allowlist of env var names to include in error snapshots (default: [])
  beforeSend: (error) => {              // Optional: filter/modify errors before sending
    if (error.message.includes('ignore')) {
      return null; // Don't send
    }
    return error;
  }
});

Env Var Allowlist

By default, no environment variables are sent. To include specific env vars in error snapshots, list them explicitly:

init({
  apiKey: 'your-key',
  allowedEnvVars: ['NODE_ENV', 'APP_NAME', 'DATABASE_CLIENT'],
  // Only these 3 vars will be included in error snapshots.
  // All other env vars (including secrets) are never read or sent.
});

What Data Is Sent

On captureError() — to /api/v1/errors

| Field | Source | Default | |---|---|---| | message, stack | Error object | always | | timestamp, environment | SDK config | always | | user | setUser() | if set | | context | captureError(err, context) | if passed | | breadcrumbs | console.log/warn/error (if autoCapture: true) | if enabled | | snapshot.env | allowedEnvVars allowlist | empty by default | | snapshot.url, userAgent, localStorageKeys | browser only | browser only |

On init() — to /api/v1/infrastructure

| Field | Source | Config flag | Default | |---|---|---|---| | nodeVersion, platform, arch | process.* | collectInfrastructure | true | | dependencies | package.json name+version pairs only | collectDependencies | true |

What is NOT sent: env vars, secrets, scripts, package.json metadata, lockfiles, or any file contents.

Periodically — to /api/v1/health (if collectHealth: true)

| Field | Source | Default | |---|---|---| | cpuUsage | process.cpuUsage() | true | | memoryUsage | process.memoryUsage() | true | | eventLoopLag | measured | true |

API Reference

init(config: OwlConfig)

Initialize the SDK. Must be called before capturing errors.

captureError(error: Error, context?: object)

Capture an error with optional context.

setUser(user: { id?: string; email?: string })

Set user information to be attached to all future errors.

close()

Flush any pending errors and close the SDK. Call before process exit.

process.on('SIGTERM', async () => {
  await close();
  process.exit(0);
});

Privacy & Security

• No secrets are collected. The SDK does not iterate process.env. Only vars you explicitly allowlist are sent.
• No eval() or hidden require(). Uses module.createRequire() — a legitimate, scanner-visible pattern.
• Dependency collection is name+version only. No scripts, metadata, or other package.json fields.
• All collection flags default to true but can be disabled: collectDependencies: false, collectInfrastructure: false, collectHealth: false.
• Use dryRun: true to inspect payloads without sending them.
• Use beforeSend to filter or redact any data before transmission.

License

Proprietary © DeployOwl. All rights reserved.