Beta— The SDK package is usable today, but real-world usage is still lighter than the CLI. Build first around audit and Harmony.

SDK

Embed Nerviq in your own tooling.

The SDK is the cleanest way to bring Nerviq into internal developer platforms, CI jobs, onboarding portals, or agent-control planes. Treat audit and Harmony as the stable product primitives. Treat Synergy exports as experimental research helpers.

@nerviq/sdkTypeScript definitionsLocal-first Node API

Maturity boundary

Build production workflows around audit, harmonyAudit, detectPlatforms, and getCatalog first. Use synergyReport and routeTask as advisory surfaces until the routing model has broader validation.

Install

The SDK ships as a standalone package so product teams can call Nerviq without shelling out to the CLI.

Node

Runtime

Designed for Node-based services, CLIs, internal dashboards, and automation.

Typed

`index.d.ts` ships with the package, so TypeScript consumers can import result interfaces directly.

Primary exports

Four stable integration primitives and two experimental advisory helpers.

bash

npm install @nerviq/sdk

Export Surface

Every top-level export answers a practical operator question: what is configured, what drifts, what should be fixed, and which platform should handle a task next?

Export	Stability	What it does
`audit(dir, platform?)`	Stable	Run a single-platform audit and return score, findings, top-next-actions, and convenience aliases like `passing` and `total`.
`harmonyAudit(dir)`	Stable	Run cross-platform alignment and drift analysis for the repo.
`detectPlatforms(dir)`	Stable	Detect which supported agent platforms are active in the target repository.
`getCatalog()`	Stable	Return the full Nerviq check catalog with `sourceUrl` and `confidence` metadata.
`synergyReport(dir)`	Experimental	Return research-phase multi-platform lift analysis and rendered report text.
`routeTask(description, platforms?)`	Experimental	Suggest a platform mix for a task description using the current static routing model.

JavaScript Example

A production-safe integration should wrap the SDK in explicit error handling and treat the returned data as JSON-friendly structured output.

javascript

const { audit, harmonyAudit, detectPlatforms } = require("@nerviq/sdk");

async function inspectRepo(dir) {
  try {
    const platforms = detectPlatforms(dir);
    const auditResult = await audit(dir, "claude");
    const harmony = await harmonyAudit(dir);

    return {
      platforms,
      auditScore: auditResult.score,
      harmonyScore: harmony.harmonyScore,
      topAction: auditResult.topNextActions[0] || null,
    };
  } catch (error) {
    if (error instanceof Error) {
      throw new Error(`Nerviq SDK error: ${error.message}`);
    }
    throw new Error("Nerviq SDK error: unknown failure");
  }
}

TypeScript Example

The SDK exports result interfaces as well as runtime functions, so you can model automation flows without inventing your own types first.

typescript

import {
  audit,
  harmonyAudit,
  routeTask,
  type AuditResult,
  type HarmonyResult,
  type RoutingResult,
} from "@nerviq/sdk";

export async function buildRepoDigest(dir: string): Promise<{
  audit: AuditResult;
  harmony: HarmonyResult;
  routing: RoutingResult;
}> {
  const auditResult = await audit(dir, "claude");
  const harmony = await harmonyAudit(dir);
  const routing = routeTask(
    "Review trust boundaries and MCP posture",
    ["claude", "codex", "cursor"]
  );

  return {
    audit: auditResult,
    harmony,
    routing,
  };
}

Error Handling

The SDK throws regular `Error` instances with messages intended for operators, CI logs, and wrapper services.

Situation	Example message
Missing or invalid dir	`dir is required and must be a string. Pass a valid directory path.`
Directory does not exist	`Directory not found: /abs/path. Pass an existing directory path.`
Unsupported platform	`Unsupported platform 'foo'. Use one of: claude, codex, ...`
Empty routing description	`description is required and must be a non-empty string.`

Pattern

Recommended wrapper

javascript

try {
  const result = await audit("/repo", "claude");
  console.log(result.score);
} catch (error) {
  if (error instanceof Error) {
    console.error(error.message);
  } else {
    console.error("Unknown SDK failure");
  }
}

Boundary

Operational note

Input validation errors come from the SDK wrapper itself. Runtime failures from the underlying audit or Harmony engines also surface as normal Error instances, so one catch path usually handles both.

Integration Patterns

Most teams wire the SDK into one of three workflows first.

Stable

CI quality gate

Use audit() to block merges below a score threshold and print the top few next actions into CI logs.

Stable

Cross-platform digest

Use harmonyAudit() to feed internal dashboards, repo-health summaries, and drift alerts without parsing terminal output.

Stable

Catalog-backed UI

Use getCatalog() to power internal search, score explainers, confidence views, and check dictionaries.

When to Use the REST API Instead

Use the SDK when you are already in Node and want direct imports. Use the local HTTP surface when you need tool-agnostic integrations.

SDK vs serve

If your integration is already a Node service or CLI, the SDK is the shortest path. If you need generated clients, Swagger imports, or language-agnostic access, run nerviq serve and use /api/openapi.json as the contract source.