deadpipe 1.0.0

package/README.md

@@ -0,0 +1,179 @@
+# Deadpipe Node.js SDK
+
+Dead simple pipeline monitoring. Know when your pipelines die.
+
+## Installation
+
+```bash
+npm install deadpipe
+# or
+yarn add deadpipe
+# or
+pnpm add deadpipe
+```
+
+## Quick Start
+
+### Option 1: Wrapper (Recommended)
+
+```typescript
+import { Deadpipe } from 'deadpipe';
+
+const dp = new Deadpipe('your-api-key');
+
+// Wrap any async function
+await dp.run('daily-sales-etl', async () => {
+  await processData();
+  return { recordsProcessed: 1500 }; // Optional: track records
+});
+
+// Deadpipe automatically sends success/failed heartbeat when done
+```
+
+### Option 2: Create a Wrapped Function
+
+```typescript
+import { Deadpipe } from 'deadpipe';
+
+const dp = new Deadpipe('your-api-key');
+
+// Create a wrapped version of your function
+const myPipeline = dp.wrap('hourly-sync', async () => {
+  await syncData();
+});
+
+// Call it later
+await myPipeline();
+```
+
+### Option 3: Manual Ping
+
+```typescript
+import { Deadpipe } from 'deadpipe';
+
+const dp = new Deadpipe('your-api-key');
+
+try {
+  await runMyJob();
+  await dp.ping('my-job', { status: 'success', recordsProcessed: 1000 });
+} catch (error) {
+  await dp.ping('my-job', { status: 'failed' });
+  throw error;
+}
+```
+
+### Option 4: Environment Variable
+
+Set `DEADPIPE_API_KEY` and use module-level functions:
+
+```typescript
+import { run, ping } from 'deadpipe';
+
+// Uses DEADPIPE_API_KEY from environment
+await run('my-pipeline', async () => {
+  await doWork();
+});
+
+// Or manual ping
+await ping('my-pipeline', { status: 'success' });
+```
+
+## Express.js / API Routes
+
+```typescript
+import { Deadpipe } from 'deadpipe';
+
+const dp = new Deadpipe(process.env.DEADPIPE_API_KEY);
+
+// Wrap a cron job handler
+export const handler = dp.wrap('daily-report', async () => {
+  const report = await generateReport();
+  await sendReport(report);
+  return { recordsProcessed: report.rows.length };
+});
+```
+
+## Next.js API Routes
+
+```typescript
+import { Deadpipe } from 'deadpipe';
+
+const dp = new Deadpipe(process.env.DEADPIPE_API_KEY);
+
+export async function POST(request: Request) {
+  return dp.run('webhook-processor', async () => {
+    const data = await request.json();
+    await processWebhook(data);
+    return Response.json({ success: true });
+  });
+}
+```
+
+## GitHub Actions
+
+```yaml
+- name: Run ETL
+  env:
+    DEADPIPE_API_KEY: ${{ secrets.DEADPIPE_API_KEY }}
+  run: node scripts/etl.js
+```
+
+```javascript
+// scripts/etl.js
+import { run } from 'deadpipe';
+
+await run('github-actions-etl', async () => {
+  // Your ETL code
+});
+```
+
+## API Reference
+
+### `new Deadpipe(apiKey, options)`
+
+Create a client instance.
+
+- `apiKey`: Your API key (or set `DEADPIPE_API_KEY` env var)
+- `options.baseUrl`: Override for self-hosted (default: `https://www.deadpipe.com/api/v1`)
+- `options.timeout`: Request timeout in ms (default: 10000)
+
+### `dp.ping(pipelineId, options)`
+
+Send a heartbeat.
+
+- `pipelineId`: Unique identifier for this pipeline
+- `options.status`: `'success'` or `'failed'` (default: `'success'`)
+- `options.durationMs`: How long the run took
+- `options.recordsProcessed`: Number of records
+- `options.appName`: Group pipelines under an app
+
+Returns: `Promise<HeartbeatResponse | null>`
+
+### `dp.run(pipelineId, fn, options)`
+
+Run a function with automatic heartbeat.
+
+- `pipelineId`: Unique identifier for this pipeline
+- `fn`: Async function to run
+- `options.appName`: Group pipelines under an app
+
+Returns: `Promise<T>` (result of fn)
+
+### `dp.wrap(pipelineId, fn, options)`
+
+Create a wrapped version of a function.
+
+Returns: A new function that auto-sends heartbeats.
+
+## Zero Dependencies
+
+This SDK has zero runtime dependencies. It uses native `fetch` (Node 18+).
+
+## TypeScript
+
+Full TypeScript support with type definitions included.
+
+## License
+
+MIT
+

package/dist/index.d.mts

@@ -0,0 +1,105 @@
+/**
+ * Deadpipe - Dead simple pipeline monitoring.
+ *
+ * @example
+ * import { Deadpipe } from 'deadpipe';
+ *
+ * const dp = new Deadpipe('your-api-key');
+ *
+ * // Option 1: Wrapper
+ * await dp.run('my-pipeline', async () => {
+ *   // your code here
+ * });
+ *
+ * // Option 2: Manual
+ * await dp.ping('my-pipeline', { status: 'success' });
+ */
+type Status = 'success' | 'failed';
+interface PingOptions {
+    status?: Status;
+    durationMs?: number;
+    recordsProcessed?: number;
+    appName?: string;
+}
+interface DeadpipeOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+interface HeartbeatResponse {
+    received: boolean;
+    pipeline_id: string;
+    timestamp: string;
+    freshness: 'fresh' | 'stale' | 'critical';
+    next_expected: string;
+    created?: boolean;
+    message?: string;
+}
+declare class Deadpipe {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    /**
+     * Create a Deadpipe client.
+     *
+     * @param apiKey - Your Deadpipe API key. Falls back to DEADPIPE_API_KEY env var.
+     * @param options - Configuration options.
+     */
+    constructor(apiKey?: string, options?: Omit<DeadpipeOptions, 'apiKey'>);
+    /**
+     * Send a heartbeat ping for a pipeline.
+     *
+     * @param pipelineId - Unique identifier for this pipeline.
+     * @param options - Ping options.
+     * @returns The heartbeat response, or null if the request failed.
+     */
+    ping(pipelineId: string, options?: PingOptions): Promise<HeartbeatResponse | null>;
+    /**
+     * Run a function with automatic heartbeat on completion.
+     *
+     * @param pipelineId - Unique identifier for this pipeline.
+     * @param fn - The function to run.
+     * @param options - Additional options.
+     * @returns The result of the function.
+     *
+     * @example
+     * const result = await dp.run('daily-etl', async () => {
+     *   const records = await processData();
+     *   return { recordsProcessed: records.length };
+     * });
+     */
+    run<T>(pipelineId: string, fn: () => T | Promise<T>, options?: {
+        appName?: string;
+    }): Promise<T>;
+    /**
+     * Create a wrapper function that auto-sends heartbeats.
+     *
+     * @param pipelineId - Unique identifier for this pipeline.
+     * @param fn - The function to wrap.
+     * @param options - Additional options.
+     * @returns A wrapped function.
+     *
+     * @example
+     * const myPipeline = dp.wrap('daily-etl', async () => {
+     *   await processData();
+     * });
+     *
+     * // Later...
+     * await myPipeline();
+     */
+    wrap<T extends (...args: unknown[]) => unknown>(pipelineId: string, fn: T, options?: {
+        appName?: string;
+    }): (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;
+}
+/**
+ * Send a heartbeat using DEADPIPE_API_KEY from environment.
+ */
+declare function ping(pipelineId: string, options?: PingOptions): Promise<HeartbeatResponse | null>;
+/**
+ * Run a function with automatic heartbeat using DEADPIPE_API_KEY from environment.
+ */
+declare function run<T>(pipelineId: string, fn: () => T | Promise<T>, options?: {
+    appName?: string;
+}): Promise<T>;
+
+export { Deadpipe, type DeadpipeOptions, type HeartbeatResponse, type PingOptions, type Status, Deadpipe as default, ping, run };

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Deadpipe - Dead simple pipeline monitoring.
+ *
+ * @example
+ * import { Deadpipe } from 'deadpipe';
+ *
+ * const dp = new Deadpipe('your-api-key');
+ *
+ * // Option 1: Wrapper
+ * await dp.run('my-pipeline', async () => {
+ *   // your code here
+ * });
+ *
+ * // Option 2: Manual
+ * await dp.ping('my-pipeline', { status: 'success' });
+ */
+type Status = 'success' | 'failed';
+interface PingOptions {
+    status?: Status;
+    durationMs?: number;
+    recordsProcessed?: number;
+    appName?: string;
+}
+interface DeadpipeOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+interface HeartbeatResponse {
+    received: boolean;
+    pipeline_id: string;
+    timestamp: string;
+    freshness: 'fresh' | 'stale' | 'critical';
+    next_expected: string;
+    created?: boolean;
+    message?: string;
+}
+declare class Deadpipe {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    /**
+     * Create a Deadpipe client.
+     *
+     * @param apiKey - Your Deadpipe API key. Falls back to DEADPIPE_API_KEY env var.
+     * @param options - Configuration options.
+     */
+    constructor(apiKey?: string, options?: Omit<DeadpipeOptions, 'apiKey'>);
+    /**
+     * Send a heartbeat ping for a pipeline.
+     *
+     * @param pipelineId - Unique identifier for this pipeline.
+     * @param options - Ping options.
+     * @returns The heartbeat response, or null if the request failed.
+     */
+    ping(pipelineId: string, options?: PingOptions): Promise<HeartbeatResponse | null>;
+    /**
+     * Run a function with automatic heartbeat on completion.
+     *
+     * @param pipelineId - Unique identifier for this pipeline.
+     * @param fn - The function to run.
+     * @param options - Additional options.
+     * @returns The result of the function.
+     *
+     * @example
+     * const result = await dp.run('daily-etl', async () => {
+     *   const records = await processData();
+     *   return { recordsProcessed: records.length };
+     * });
+     */
+    run<T>(pipelineId: string, fn: () => T | Promise<T>, options?: {
+        appName?: string;
+    }): Promise<T>;
+    /**
+     * Create a wrapper function that auto-sends heartbeats.
+     *
+     * @param pipelineId - Unique identifier for this pipeline.
+     * @param fn - The function to wrap.
+     * @param options - Additional options.
+     * @returns A wrapped function.
+     *
+     * @example
+     * const myPipeline = dp.wrap('daily-etl', async () => {
+     *   await processData();
+     * });
+     *
+     * // Later...
+     * await myPipeline();
+     */
+    wrap<T extends (...args: unknown[]) => unknown>(pipelineId: string, fn: T, options?: {
+        appName?: string;
+    }): (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;
+}
+/**
+ * Send a heartbeat using DEADPIPE_API_KEY from environment.
+ */
+declare function ping(pipelineId: string, options?: PingOptions): Promise<HeartbeatResponse | null>;
+/**
+ * Run a function with automatic heartbeat using DEADPIPE_API_KEY from environment.
+ */
+declare function run<T>(pipelineId: string, fn: () => T | Promise<T>, options?: {
+    appName?: string;
+}): Promise<T>;
+
+export { Deadpipe, type DeadpipeOptions, type HeartbeatResponse, type PingOptions, type Status, Deadpipe as default, ping, run };

package/dist/index.js

@@ -0,0 +1,164 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Deadpipe: () => Deadpipe,
+  default: () => index_default,
+  ping: () => ping,
+  run: () => run
+});
+module.exports = __toCommonJS(index_exports);
+var Deadpipe = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  /**
+   * Create a Deadpipe client.
+   *
+   * @param apiKey - Your Deadpipe API key. Falls back to DEADPIPE_API_KEY env var.
+   * @param options - Configuration options.
+   */
+  constructor(apiKey, options = {}) {
+    this.apiKey = apiKey || process.env.DEADPIPE_API_KEY || "";
+    if (!this.apiKey) {
+      throw new Error(
+        "API key required. Pass apiKey or set DEADPIPE_API_KEY environment variable."
+      );
+    }
+    this.baseUrl = (options.baseUrl || "https://www.deadpipe.com/api/v1").replace(/\/$/, "");
+    this.timeout = options.timeout || 1e4;
+  }
+  /**
+   * Send a heartbeat ping for a pipeline.
+   *
+   * @param pipelineId - Unique identifier for this pipeline.
+   * @param options - Ping options.
+   * @returns The heartbeat response, or null if the request failed.
+   */
+  async ping(pipelineId, options = {}) {
+    const { status = "success", durationMs, recordsProcessed, appName } = options;
+    const payload = {
+      pipeline_id: pipelineId,
+      status
+    };
+    if (durationMs !== void 0) payload.duration_ms = durationMs;
+    if (recordsProcessed !== void 0) payload.records_processed = recordsProcessed;
+    if (appName !== void 0) payload.app_name = appName;
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      const response = await fetch(`${this.baseUrl}/heartbeat`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-Key": this.apiKey
+        },
+        body: JSON.stringify(payload),
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        return null;
+      }
+      return await response.json();
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Run a function with automatic heartbeat on completion.
+   *
+   * @param pipelineId - Unique identifier for this pipeline.
+   * @param fn - The function to run.
+   * @param options - Additional options.
+   * @returns The result of the function.
+   *
+   * @example
+   * const result = await dp.run('daily-etl', async () => {
+   *   const records = await processData();
+   *   return { recordsProcessed: records.length };
+   * });
+   */
+  async run(pipelineId, fn, options = {}) {
+    const startTime = Date.now();
+    let status = "success";
+    let recordsProcessed;
+    try {
+      const result = await fn();
+      if (result && typeof result === "object" && "recordsProcessed" in result) {
+        recordsProcessed = result.recordsProcessed;
+      }
+      return result;
+    } catch (error) {
+      status = "failed";
+      throw error;
+    } finally {
+      const durationMs = Date.now() - startTime;
+      await this.ping(pipelineId, {
+        status,
+        durationMs,
+        recordsProcessed,
+        appName: options.appName
+      });
+    }
+  }
+  /**
+   * Create a wrapper function that auto-sends heartbeats.
+   *
+   * @param pipelineId - Unique identifier for this pipeline.
+   * @param fn - The function to wrap.
+   * @param options - Additional options.
+   * @returns A wrapped function.
+   *
+   * @example
+   * const myPipeline = dp.wrap('daily-etl', async () => {
+   *   await processData();
+   * });
+   *
+   * // Later...
+   * await myPipeline();
+   */
+  wrap(pipelineId, fn, options = {}) {
+    return async (...args) => {
+      return this.run(pipelineId, () => fn(...args), options);
+    };
+  }
+};
+var defaultClient = null;
+function getDefaultClient() {
+  if (!defaultClient) {
+    defaultClient = new Deadpipe();
+  }
+  return defaultClient;
+}
+async function ping(pipelineId, options = {}) {
+  return getDefaultClient().ping(pipelineId, options);
+}
+async function run(pipelineId, fn, options = {}) {
+  return getDefaultClient().run(pipelineId, fn, options);
+}
+var index_default = Deadpipe;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Deadpipe,
+  ping,
+  run
+});

package/dist/index.mjs

@@ -0,0 +1,137 @@
+// src/index.ts
+var Deadpipe = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  /**
+   * Create a Deadpipe client.
+   *
+   * @param apiKey - Your Deadpipe API key. Falls back to DEADPIPE_API_KEY env var.
+   * @param options - Configuration options.
+   */
+  constructor(apiKey, options = {}) {
+    this.apiKey = apiKey || process.env.DEADPIPE_API_KEY || "";
+    if (!this.apiKey) {
+      throw new Error(
+        "API key required. Pass apiKey or set DEADPIPE_API_KEY environment variable."
+      );
+    }
+    this.baseUrl = (options.baseUrl || "https://www.deadpipe.com/api/v1").replace(/\/$/, "");
+    this.timeout = options.timeout || 1e4;
+  }
+  /**
+   * Send a heartbeat ping for a pipeline.
+   *
+   * @param pipelineId - Unique identifier for this pipeline.
+   * @param options - Ping options.
+   * @returns The heartbeat response, or null if the request failed.
+   */
+  async ping(pipelineId, options = {}) {
+    const { status = "success", durationMs, recordsProcessed, appName } = options;
+    const payload = {
+      pipeline_id: pipelineId,
+      status
+    };
+    if (durationMs !== void 0) payload.duration_ms = durationMs;
+    if (recordsProcessed !== void 0) payload.records_processed = recordsProcessed;
+    if (appName !== void 0) payload.app_name = appName;
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      const response = await fetch(`${this.baseUrl}/heartbeat`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-Key": this.apiKey
+        },
+        body: JSON.stringify(payload),
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        return null;
+      }
+      return await response.json();
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Run a function with automatic heartbeat on completion.
+   *
+   * @param pipelineId - Unique identifier for this pipeline.
+   * @param fn - The function to run.
+   * @param options - Additional options.
+   * @returns The result of the function.
+   *
+   * @example
+   * const result = await dp.run('daily-etl', async () => {
+   *   const records = await processData();
+   *   return { recordsProcessed: records.length };
+   * });
+   */
+  async run(pipelineId, fn, options = {}) {
+    const startTime = Date.now();
+    let status = "success";
+    let recordsProcessed;
+    try {
+      const result = await fn();
+      if (result && typeof result === "object" && "recordsProcessed" in result) {
+        recordsProcessed = result.recordsProcessed;
+      }
+      return result;
+    } catch (error) {
+      status = "failed";
+      throw error;
+    } finally {
+      const durationMs = Date.now() - startTime;
+      await this.ping(pipelineId, {
+        status,
+        durationMs,
+        recordsProcessed,
+        appName: options.appName
+      });
+    }
+  }
+  /**
+   * Create a wrapper function that auto-sends heartbeats.
+   *
+   * @param pipelineId - Unique identifier for this pipeline.
+   * @param fn - The function to wrap.
+   * @param options - Additional options.
+   * @returns A wrapped function.
+   *
+   * @example
+   * const myPipeline = dp.wrap('daily-etl', async () => {
+   *   await processData();
+   * });
+   *
+   * // Later...
+   * await myPipeline();
+   */
+  wrap(pipelineId, fn, options = {}) {
+    return async (...args) => {
+      return this.run(pipelineId, () => fn(...args), options);
+    };
+  }
+};
+var defaultClient = null;
+function getDefaultClient() {
+  if (!defaultClient) {
+    defaultClient = new Deadpipe();
+  }
+  return defaultClient;
+}
+async function ping(pipelineId, options = {}) {
+  return getDefaultClient().ping(pipelineId, options);
+}
+async function run(pipelineId, fn, options = {}) {
+  return getDefaultClient().run(pipelineId, fn, options);
+}
+var index_default = Deadpipe;
+export {
+  Deadpipe,
+  index_default as default,
+  ping,
+  run
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "deadpipe",
+  "version": "1.0.0",
+  "description": "Dead simple pipeline monitoring. Know when your pipelines die.",
+  "keywords": [
+    "monitoring",
+    "pipelines",
+    "etl",
+    "observability",
+    "heartbeat",
+    "dead-mans-switch",
+    "alerting"
+  ],
+  "homepage": "https://deadpipe.com",
+  "bugs": {
+    "url": "https://github.com/deadpipe/deadpipe-node/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deadpipe/deadpipe-node.git"
+  },
+  "license": "MIT",
+  "author": "Deadpipe <hello@deadpipe.com>",
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "module": "dist/index.mjs"
+}