TypeScript SDK

@opshift/sdk — zero dependencies, Web Crypto signing, ESM and CJS bundles.

Installation

bash

npm install @opshift/sdk
# or
yarn add @opshift/sdk
# or
pnpm add @opshift/sdk

Initialise the client

typescript

import { OpShift } from "@opshift/sdk";
 
export const opshift = new OpShift({
  secret: process.env.OPSHIFT_SECRET!,
});

Constructor options

Field	Type	Description
`secret`required	`string`	Team webhook secret (64-char hex). Find it in Settings → Webhook Secret.
`baseUrl`	`string`	Override the API root. Defaults to https://www.opshift.io. Useful for self-hosted or local development.
`fetch`	`typeof fetch`	Injectable fetch implementation. Defaults to the runtime's global fetch.

opshift.ping(pingToken, options?)

Send a heartbeat ping to a monitor.

typescript

await opshift.ping("payments-worker", {
  status: "up",
  metadata: { batchSize: 1247, durationMs: 832 },
});
 
await opshift.ping("payments-worker", {
  status: "down",
  reason: "stripe-timeout",
});

Options

Field	Type	Description
`status`	`"up" \| "down"`	Defaults to "up".
`reason`	`string`	Short reason string, max 200 chars. Drives down→down dedup.
`group_key`	`string`	Alert grouping key, max 200 chars.
`metadata`	`Record<string, unknown>`	Arbitrary metadata stored on the ping row.

Return value

typescript

interface PingResponse {
  message: string;
  monitor: { name: string; status: string; monitoringActive: boolean };
  pingStatus: "up" | "down";
}

opshift.alert(webhookUrl, options)

Trigger a webhook alert.

typescript

const res = await opshift.alert("deploy-failures", {
  title: "Deploy failed: api-gateway",
  description: "Migration step exited with code 137",
  severity: "sev1",
  metadata: { commit: "a1b2c3", environment: "production" },
  group_key: "deploy:api-gateway",
});
 
if (res.status === "filtered") {
  console.log("Suppressed by filter rule:", res.reason);
}

Options

Field	Type	Description
`title`required	`string`	Alert title, max 200 chars.
`description`	`string`	Long-form context, max 2000 chars.
`severity`	`"sev0" \| "sev1" \| "sev2" \| "sev3" \| "sev4"`	Falls back to the webhook default.
`metadata`	`Record<string, any>`	Max 100 KB, max 10 nesting levels.
`group_key`	`string`	Max 200 chars. Identical keys fold into one open alert.

Return value

typescript

interface AlertResponse {
  alertId?: string;
  status: "created" | "filtered" | "occurrence_added" | "reopened";
  message: string;
  occurrenceCount?: number;
  reason?: string;
}

Error handling

Every API failure throws OpShiftError. Network failures surface as statusCode: 0.

typescript

import { OpShift, OpShiftError } from "@opshift/sdk";
 
try {
  await opshift.ping("monitor-id");
} catch (error) {
  if (error instanceof OpShiftError) {
    console.error(error.statusCode); // 0, 401, 404, 429, ...
    console.error(error.message);    // human-readable
    console.error(error.body);       // parsed response body if available
  }
  throw error;
}

Runtime compatibility

Node.js 18+
Cloudflare Workers
Vercel Edge Functions
Deno
Bun

Signing uses the Web Crypto API, which is available natively in every runtime above.

Use one client per process

The client is cheap to construct but caches no per-call state, so you can share a single instance across your app. Avoid re-creating it on every request.

Notification policies Python