@cohesionauth/sdk

Official TypeScript SDK for the COHESION Judgment Independence Score API. Measure and certify human oversight of AI-assisted decisions in real time, per EU AI Act Article 14, Colorado SB 205, and NYC Local Law 144.

npm: @cohesionauth/sdk
License: Apache-2.0
Requires: Node.js 20 or later
Base URL: https://api.cohesionauth.com (human-readable docs at https://cohesionauth.com/api)

Install

npm install @cohesionauth/sdk

Quickstart

import { Cohesion } from "@cohesionauth/sdk";

const client = new Cohesion({ apiKey: process.env.COHESION_API_KEY! });

const result = await client.score({
  session_id: "sess_2026_04_22_001",
  operator_id: "analyst-42",
  domain: "financial",
  interaction: {
    ai_recommendation_presented: true,
    time_to_decision_ms: 3400,
    decision: "modified",
    modification_extent: 0.25,
    ai_available: true,
    scenario_type: "standard",
    outcome_correct: null,
    hover_events: 4,
    scroll_depth: 0.9,
    alternative_views_checked: 1,
  },
});

console.log(`JIS ${result.jis} (${result.band})`);

Side-by-side

The same request in three forms.

cURL

curl https://api.cohesionauth.com/v1/score \
  -H "X-API-Key: $COHESION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d @payload.json

Python

from cohesion import Client

client = Client(api_key=os.environ["COHESION_API_KEY"])
result = client.score(
    session_id="sess_...",
    operator_id="analyst-42",
    domain="financial",
    interaction={...},
)

TypeScript

import { Cohesion } from "@cohesionauth/sdk";

const client = new Cohesion({ apiKey: process.env.COHESION_API_KEY! });
const result = await client.score({ /* ... */ });

Client options

new Cohesion({
  apiKey: string,                                  // required
  baseUrl?: string,        // default "https://api.cohesionauth.com"
  timeout?: number,        // default 30000 ms
  maxRetries?: number,     // default 3
  logger?: Logger,         // default createDefaultLogger()
  enableTelemetry?: boolean, // default false (opt-in Sentry)
});

Method reference

Method	HTTP	Notes
`client.score(req)`	`POST /v1/score`	Idempotency-Key auto-generated
`client.scoreBatch(req)`	`POST /v1/score/batch`	up to 100 interactions
`client.operatorProfile(operatorId)`	`GET /v1/operator/:id/profile`	includes JIS history
`client.organizationDashboard()`	`GET /v1/organization/dashboard`	aggregate metrics
`client.maintenanceRecommend(req)`	`POST /v1/maintenance/recommend`	judgment-maintenance exercises
`client.complianceReport()`	`GET /v1/compliance/report`	EU AI Act Article 14 rollup
`client.adminKeyRotate()`	`POST /v1/admin/key/rotate`	returns new key ONCE
`client.adminKeyRevoke()`	`POST /v1/admin/key/revoke`	sets org inactive
`client.adminAuditLog(opts?)`	`GET /v1/admin/audit-log`	own-org events only

AI-provider wrappers

Instrument OpenAI, Anthropic, Azure OpenAI, Vercel AI SDK, or LangChain.

import OpenAI from "openai";
import { Cohesion, wrapOpenAI } from "@cohesionauth/sdk";

const cohesion = new Cohesion({ apiKey: process.env.COHESION_API_KEY! });
const openai = wrapOpenAI(new OpenAI(), cohesion, {
  operatorId: "analyst-42",
  sessionId: "sess_...",
  domain: "financial",
});

const { response, recordDecision } = await openai.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Draft SAR narrative" }],
});

// Present `response` to the human. After they decide:
const score = await recordDecision({
  decision: "modified",
  modificationExtent: 0.3,
});

Equivalent helpers: wrapAnthropic, wrapAzureOpenAI, vercelAIMiddleware, langChainHandler.

Errors

Every SDK error carries requestId and nextStep.

Class	HTTP	Extra fields	`nextStep` example
`AuthenticationError`	401		"Check the 8-character prefix of your key matches the one in your dashboard at cohesionauth.com/dashboard/api-keys."
`RateLimitError`	429	`retryAfter: number`	"Retry after 7 seconds."
`ValidationError`	400, 413, 422	`field`, `allowedValues`	"scenario_type must be one of: standard, independent, trap, split."
`ServerError`	5xx		populated only when actionable
`NetworkError`	transport	`cause`	"Check connectivity to api.cohesionauth.com and ensure TLS 1.3 egress is permitted from your environment."
`CohesionError`	base		hierarchy root

import { RateLimitError } from "@cohesionauth/sdk";

try {
  await client.score(req);
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log(`Retry in ${err.retryAfter}s. Hint: ${err.nextStep}`);
  } else {
    throw err;
  }
}

CLI

npx cohesion score --operator-id analyst-42 --from-file payload.json
# or via stdin:
cat payload.json | npx cohesion score --operator-id analyst-42 --from-file -

Retry and idempotency

Exponential backoff with full jitter. Default max 3 retries.
Retries only on 429 and 5xx. All 4xx (except 429) fail fast.
Honors Retry-After header (integer seconds or HTTP-date).
Every POST auto-populates Idempotency-Key with a UUIDv4 so retries are safe to replay.

Environment variables

Name	Purpose
`COHESION_API_KEY`	API key. Required for the CLI.
`COHESION_BASE_URL`	Override the base URL (staging, self-hosted).
`COHESION_LOG_FORMAT`	Set to `json` for structured logs.
`COHESION_LOG_LEVEL`	`debug`, `info`, `warn`, or `error`.
`COHESION_TEST_API_KEY`	Enables the live integration test.
`COHESION_SENTRY_DSN` or `SENTRY_DSN`	Opt-in telemetry, only when `enableTelemetry: true`.

Logging and redaction

The default logger redacts API keys (ck_live_*) and operator_id values before emit. Set COHESION_LOG_FORMAT=json for structured output suitable for Datadog, Sentry, or Cloudflare Logpush.

License

Apache License 2.0. See LICENSE and NOTICE.

The COHESION Judgment Independence Score methodology, scoring engine, and intervention protocol are subject to the provisional patent filed 2026-04-13.