SDK overview

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i https://ospulse.app/openapi.json \
  -g typescript-fetch \
  -o /local/src/ospulse \
  --additional-properties=supportsES6=true,withoutRuntimeChecks=false

// ospulse.mjs — zero dependencies, Node 18+ (global fetch).
export class OSPulseError extends Error {
  constructor(problem, status) {
    super(problem?.detail || problem?.title || `HTTP ${status}`)
    this.name = 'OSPulseError'
    this.status = status
    this.type = problem?.type
    this.correlationId = problem?.correlationId
    this.errors = problem?.errors // validation errors: { field: [messages] }
  }
}
 
export class OSPulse {
  constructor({ token = process.env.OSPULSE_TOKEN, baseUrl = 'https://api.ospulse.app', maxRetries = 3 } = {}) {
    if (!token) throw new Error('OSPULSE_TOKEN is not set')
    this.token = token
    this.baseUrl = baseUrl.replace(/\/$/, '')
    this.maxRetries = maxRetries
  }
 
  async request(path, { method = 'GET', query, body, signal } = {}) {
    const url = new URL(`${this.baseUrl}/api/v1/${path.replace(/^\//, '')}`)
    for (const [k, v] of Object.entries(query ?? {})) {
      if (v !== undefined && v !== null) url.searchParams.set(k, String(v))
    }
 
    for (let attempt = 0; ; attempt++) {
      const res = await fetch(url, {
        method,
        signal,
        headers: {
          Authorization: `Bearer ${this.token}`,
          Accept: 'application/json',
          ...(body ? { 'Content-Type': 'application/json' } : {}),
        },
        body: body ? JSON.stringify(body) : undefined,
      })
 
      if (res.status === 204) return null
      if (res.ok) return res.json()
 
      // Retry throttling and transient server errors only.
      const retryable = res.status === 429 || res.status >= 500
      if (retryable && attempt < this.maxRetries) {
        const header = Number(res.headers.get('retry-after'))
        const wait = Number.isFinite(header) && header > 0 ? header * 1000 : 2 ** attempt * 500
        await new Promise((r) => setTimeout(r, wait + Math.random() * 250))
        continue
      }
 
      // Errors are problem+json; fall back gracefully if a proxy mangles it.
      const problem = await res.json().catch(() => null)
      throw new OSPulseError(problem, res.status)
    }
  }
 
  /** Async iterator over an offset-paginated collection. */
  async *paginate(path, { query = {}, pageSize = 100 } = {}) {
    let skip = 0
    for (;;) {
      const page = await this.request(path, { query: { ...query, take: pageSize, skip } })
      for (const item of page.items) yield item
      skip += page.items.length
      if (page.items.length === 0 || skip >= page.totalEstimate) return
    }
  }
}

import { OSPulse, OSPulseError } from './ospulse.mjs'
 
const client = new OSPulse()
 
try {
  for await (const pkg of client.paginate('packages', { query: { ecosystem: 'Npm' } })) {
    if (pkg.healthScore < 50) console.log(`${pkg.name} → ${pkg.healthScore}`)
  }
} catch (err) {
  if (err instanceof OSPulseError) {
    console.error(`${err.status} ${err.message} (correlationId ${err.correlationId})`)
  }
  throw err
}