Skip to main content

SDK — TypeScript Client

The official @bleedwatch/sdk provides a typed wrapper around the BleedWatch REST API. Works with Node.js 18+, Deno, Bun, and any environment that supports the Fetch API.

Installation​

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

Quick Start​

import { BleedWatch } from "@bleedwatch/sdk";

const bw = new BleedWatch({
  apiKey: "bw_live_xxxxxxxxxxxxxxxxxxxx",
});

// List critical findings
const { data: findings } = await bw.findings.list({
  severity: "critical",
  status: "open",
});

console.log(`Found ${findings.length} critical open findings`);

Configuration​

const bw = new BleedWatch({
  // Required — your API key (generate at Settings → API Keys)
  apiKey: "bw_live_...",

  // Optional — defaults to https://api.bleedwatch.com
  baseUrl: "https://api.bleedwatch.com",

  // Optional — request timeout in ms (default: 30000)
  timeout: 15_000,

  // Optional — custom fetch implementation
  fetch: customFetch,
});

Resources​

Findings​

// List findings with filters
const { data, total, hasMore } = await bw.findings.list({
  severity: "high",
  status: "open",
  type: "exposed-secret",
  page: 1,
  limit: 50,
});

// Get a specific finding
const finding = await bw.findings.get("uuid-here");

// Update finding status
await bw.findings.updateStatus("uuid-here", "resolved");

Scans​

// Trigger a scan
const scan = await bw.scans.trigger("my-org/my-repo", "github");
console.log(`Scan ${scan.id} started: ${scan.status}`);

// Check scan status
const status = await bw.scans.get(scan.id);

// List recent scans
const { data: scans } = await bw.scans.list({ type: "npm", limit: 10 });

// Cancel a running scan
await bw.scans.cancel(scan.id);

Shield​

// Verify a package before installing
const result = await bw.shield.verify("lodash", "4.17.21");

if (!result.safe) {
  console.error("Package has findings:", result.findings);
  process.exit(1);
}

Alerts​

// List alert rules
const { data: rules } = await bw.alerts.listRules();

// List alert history
const { data: history } = await bw.alerts.listHistory({ limit: 20 });

// Acknowledge an alert
await bw.alerts.acknowledge("alert-uuid");

Assets​

// List monitored assets
const { data: assets } = await bw.assets.list({ type: "github-org" });

// Get asset details
const asset = await bw.assets.get("asset-uuid");

Compliance​

// List available frameworks
const { frameworks } = await bw.compliance.listFrameworks();
// ["soc2", "iso27001", "gdpr", "nis2", "pci_dss", "hipaa"]

// Generate compliance report
const report = await bw.compliance.report("soc2");
console.log(`SOC 2 coverage: ${report.coveragePercent}%`);

Hosts​

// List discovered hosts
const { data: hosts } = await bw.hosts.list();

// Get host details
const host = await bw.hosts.get("host-uuid");

Vulnerabilities​

// List CVE matches
const { data: vulns } = await bw.vulnerabilities.list({
  severity: "critical",
});

// Search by CVE ID
const { data } = await bw.vulnerabilities.list({
  cveId: "CVE-2024-1234",
});

Dashboard​

// Get dashboard KPIs
const metrics = await bw.dashboard.metrics();
console.log(`Risk score: ${metrics.riskScore}`);
console.log(`Open findings: ${metrics.openFindings}`);
console.log(`MTTR: ${metrics.mttr}h`);

Error Handling​

import { BleedWatch, BleedWatchError } from "@bleedwatch/sdk";

try {
  const finding = await bw.findings.get("invalid-id");
} catch (err) {
  if (err instanceof BleedWatchError) {
    console.error(`API error ${err.status}:`, err.body);
    // API error 404: { error: "Finding not found" }
  }
}

CI/CD Integration Examples​

GitHub Actions​

- name: Check for critical findings
  run: |
    npx tsx -e "
      import { BleedWatch } from '@bleedwatch/sdk';
      const bw = new BleedWatch({ apiKey: '${{ secrets.BLEEDWATCH_API_KEY }}' });
      const { data } = await bw.findings.list({ severity: 'critical', status: 'open' });
      if (data.length > 0) {
        console.error('Critical findings detected:', data.length);
        process.exit(1);
      }
      console.log('No critical findings.');
    "

GitLab CI​

security_check:
  script:
    - npx tsx -e "
        import { BleedWatch } from '@bleedwatch/sdk';
        const bw = new BleedWatch({ apiKey: '$BLEEDWATCH_API_KEY' });
        const { data } = await bw.findings.list({ severity: 'critical', status: 'open' });
        if (data.length > 0) process.exit(1);
      "

Jenkins​

stage('BleedWatch Check') {
  steps {
    sh '''
      npx tsx -e "
        import { BleedWatch } from '@bleedwatch/sdk';
        const bw = new BleedWatch({ apiKey: '${BLEEDWATCH_API_KEY}' });
        const m = await bw.dashboard.metrics();
        if (m.criticalFindings > 0) process.exit(1);
      "
    '''
  }
}

Types​

All types are exported for use in your TypeScript projects:

import type {
  Finding,
  Scan,
  Severity,
  FindingStatus,
  ScanType,
  PaginatedResponse,
  BleedWatchConfig,
} from "@bleedwatch/sdk";