eramba-sdk

Unofficial TypeScript/JavaScript client for the Eramba GRC REST API.

Disclaimer: This project is not affiliated with, endorsed by, or sponsored by Eramba Ltd / eramba.org. Validate endpoints and schemas against your instance Swagger docs — fields and paths vary by Eramba version, edition, and custom fields.

Features

• HTTP Basic Auth over TLS (Eramba’s required auth model)
• High-level module accessors (api.risks, api.projects, …)
• Generic CRUD helpers: list, listAll, get, create, update, updateMerge, delete
• Nested comments / attachments collections
• Pagination helpers (page / limit, listAll)
• Typed errors (ErambaError, ErambaConfigError)
• Works in Node.js and other runtimes with fetch (custom fetch injectable)

Requirements

• An Eramba instance with REST API enabled for the integration user
• HTTPS endpoint
• API user credentials with ACL permissions for the modules you call
• Node.js 18+ recommended (native fetch), or supply your own fetch

Enable REST APIs on the Eramba account, grant module permissions, and (optionally) add an “API Documentation” group so Swagger is available under each module’s API menu. Official overview: Eramba REST APIs.

Install

npm install eramba-sdk

Quick start

import { createEramba } from "eramba-sdk";

const { api, client } = createEramba({
  baseUrl: process.env.ERAMBA_URL!, // e.g. https://grc.example.com
  username: process.env.ERAMBA_USER!,
  password: process.env.ERAMBA_PASSWORD!,
});

// List all risks (auto-paginates)
const risks = await api.risks.listAll({ limit: 100 });

// Fetch one record
const risk = await api.risks.get(42);

// Create
const created = await api.risks.create({
  title: "New risk",
  // ...fields required by your instance
});

// Update — Eramba typically expects the full object
const current = await api.risks.get(42);
await api.risks.update(42, { ...current, title: "Updated title" });

// Or shallow-merge then PATCH
await api.risks.updateMerge(42, { title: "Updated title" });

// Comments
const comments = await api.risks.comments(42).listAll();
await api.risks.comments(42).create({ message: "Follow-up note" });

// Low-level client for custom paths
const raw = await client.get("risks/index", { page: 1, limit: 50 });

Store credentials in environment variables; never commit secrets.

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | baseUrl | string | — | Instance URL, with or without /api | | username | string | — | API user login | | password | string | — | API user password | | timeoutMs | number | 30000 | Request timeout | | defaultPageSize | number | 200 | Default page size for listAll | | fetch | typeof fetch | global fetch | Custom fetch (tests, proxies) | | headers | Record<string, string> | — | Extra headers on every request |

Module accessors

createEramba() returns { client, api }. Built-in api resources:

| Accessor | Path | |----------|------| | assets | assets | | assetReviews | asset-reviews | | businessUnits | business-units | | compliancePackages | compliance-packages | | complianceManagement | compliance-management | | groups | groups | | incidents | incidents | | projects | projects | | riskExceptions | risk-exceptions | | riskReviews | risk-reviews | | riskThreats | risk-threats | | risks | risks | | securityPolicies | security-policies | | securityPolicyReviews | security-policy-reviews | | securityServices | security-services | | thirdParties | third-parties | | thirdPartyRiskReviews | third-party-risk-reviews | | thirdPartyRisks | third-party-risks | | users | users | | vendorAssessments | vendor-assessments |

Any other module path:

const audits = api.resource("security-service-audits");
const page = await audits.list({ page: 1, limit: 50 });

Availability depends on your Eramba edition, ACL, and whether REST is enabled for that module.

Resource API

For each resource:

| Method | HTTP | Notes | |--------|------|--------| | list(params?) | GET /{resource}/index | One page (page, limit, extra query) | | listAll(params?) | paginated GETs | Stops when has_next_page is false | | get(id) | GET /{resource}/{id} | Single record | | create(data) | POST /{resource}/add | | | update(id, data) | PATCH /{resource}/{id} | Prefer full object | | updateMerge(id, patch) | get → merge → patch | Convenience; still sends a full body | | delete(id) | DELETE /{resource}/{id} | | | comments(foreignKey) | nested collection | list / create / delete | | attachments(foreignKey) | nested collection | | | statuses(foreignKey) | status labels | Path may vary by version |

Response envelope shape:

{ data: T | T[]; pagination?: { has_next_page?, current_page?, page_count?, count?, limit? } }

Eramba API notes

• Auth: Basic Auth over TLS only.
• PATCH: Eramba generally expects the entire object, not a partial patch. Load with get, change fields, then update (or use updateMerge).
• Pagination: ?page=&limit=; sorting support depends on your Eramba version.
• Custom fields / comments / attachments: Supported via the REST engine; exact schemas differ per instance — use Swagger.
• Status / comments endpoints: Often separate from the main item path; this SDK exposes helpers, but verify paths on your Swagger if a call fails.

Errors

import { ErambaError, ErambaConfigError } from "eramba-sdk";

try {
  await api.risks.get(999);
} catch (err) {
  if (err instanceof ErambaError) {
    console.error(err.status, err.method, err.path, err.body);
  }
}

• ErambaConfigError — missing/invalid client options
• ErambaError — HTTP or network failure (status, body, path, method)

Exports

import {
  createEramba,
  ErambaClient,
  ErambaApi,
  Resource,
  NestedCollection,
  ErambaResources,
  ErambaError,
  ErambaConfigError,
  LEGAL_NOTICE,
  AFFILIATION_DISCLAIMER,
} from "eramba-sdk";

Development

npm install
npm test
npm run build

License

Apache License 2.0. See LICENSE, LEGAL.md, and NOTICE.

This software is provided “AS IS”, without warranty of any kind. You are responsible for credentials, permissions, data protection, and validating request/response schemas against your Eramba instance.