shipherd-tools

Official Node.js library for Shipherd integration with zero-config health monitoring and lifecycle control. Requires Node.js 18+

Install

npm install shipherd-tools

Quick Start

const shipherd = require('shipherd-tools');

const tools = shipherd({
  logLevel: 'info'
});

await tools.ready();

tools.addHealthCheck('memory', () => {
  const usedMb = Math.round(process.memoryUsage().heapUsed / 1024 / 1024);
  return { ok: usedMb < 512, usedMb };
});

await tools.log('info', 'Application started');

Runtime Modes

In Shipherd environment

When run inside Shipherd, shipherd-tools enables full integration:

In this mode, the SDK:

• Calls GET /api/shipherd-tools/:id/config on startup
• Starts an authenticated health endpoint at GET /shipherd/health
• Sends logs and notifications to Shipherd
• Sends control actions (restart / shutdown) to Shipherd

Outside Shipherd environment

The SDK remains usable locally:

• tools.log(level, message) falls back to native console.*
• tools.notify(title, message, metadata) falls back to console.info
• tools.restart() and tools.stop() return an explicit local-fallback unsupported response and log a warning
• tools.isEnabled() returns false

This allows app code to always use tools.log() without branching by environment.

API

shipherd(options?)

Creates a tools instance.

Options:

• logLevel: error | warn | info | debug (default: error)
• maxRetries: retry count for safe HTTP methods (default: 3)
• retryDelaySeconds: delay between retries (default: 1)
• retryUnsafeRequests: if true, retries unsafe methods like POST (default: false)
• maxHealthCheckDurationSeconds: max duration for all health checks (default: 5)
• maxSingleCheckDurationSeconds: max duration per health check (default: 2)

await tools.ready()

Waits for startup initialization to complete.

tools.isEnabled()

Returns true when running in a valid Shipherd environment.

tools.addHealthCheck(name, fn)

Registers a custom health check.

• name: string
• fn: sync or async function returning optional details object

If fn throws, the check is reported as failed.

tools.removeHealthCheck(name)

Removes a previously registered health check.

await tools.log(level, message)

Sends a log line to Shipherd (or console fallback locally).

await tools.notify(title, message, metadata?)

Sends a custom notification through Shipherd (or console fallback locally).

await tools.restart()

Requests restart from Shipherd.

await tools.stop()

Requests shutdown from Shipherd.

await tools.shutdown()

Stops internal health server gracefully.

Health Endpoint Contract

When enabled, Shipherd polls:

• GET http://localhost:${SHIPHERD_HEALTH_CHECK_PORT}/shipherd/health
• Header: Authorization: Bearer ${SHIPHERD_TOKEN_SHP_TO_PRJ}

Retry Behavior

By default, retries apply only to safe methods (GET, HEAD, OPTIONS).

Unsafe side-effecting requests (POST control/logs/notify) are not retried unless retryUnsafeRequests: true is explicitly set.

Development

Run tests:

npm test

Examples:

• See examples/basic.js