@northgale/sdk

Official Node.js / TypeScript SDK for the Northgale Explainable AI API

Northgale sits between your application and your AI models. Every AI recommendation your app makes — scoring, ranking, approving, flagging — goes through Northgale and comes back as a Decision Card: a structured, auditable explanation of why the AI said what it said.

Your App → AI Model → Northgale SDK → Decision Card → Your Users

Installation

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

Requires Node.js 18+.

Quick Start

Get your API key from northgale.io/dashboard.

import Northgale from '@northgale/sdk';

const northgale = new Northgale({ apiKey: 'ng_live_your_key_here' });

// Wrap your AI model output in an explainable Decision Card
const result = await northgale.explain({
  input_text: 'Account scored 91/100. High purchase intent based on recent engagement.',
  workflow_type: 'sales',
  confidence: 0.91,
  evidence: [
    { source: 'CRM activity', text: 'Opened 14 emails in last 30 days', weight: 0.6 },
    { source: 'Intent data',  text: 'Visited pricing page 3x this week', weight: 0.4 },
  ],
  risk_factors: [
    { severity: 'low', description: 'No confirmed technical buyer identified yet' },
  ],
});

console.log(result.decision_card.recommendation);
// → "Account scored 91/100."

console.log(result.decision_card.confidence);
// → { score: 0.91, label: 'high' }

console.log(result.decision_card.next_action);
// → "Prioritize this account — confidence is high. Schedule outreach within 48 hours."

Usage

northgale.explain(params) — Single Decision Card

const card = await northgale.explain({
  input_text: 'Approve refund exception for Acme Health.',  // required
  workflow_type: 'support',
  confidence: 0.82,
  reasoning: 'Contract allows exception under clause 4.2.',
  evidence: [
    { source: 'MSA',  text: 'Premium customers receive service-credit exceptions.', weight: 1.0 },
    { source: 'Tickets', text: '#4831 and #4920 cite delayed AI triage responses.', weight: 0.8 },
  ],
  risk_factors: [
    { severity: 'medium', description: 'Refund amount not validated against finance policy.' },
  ],
  next_action: 'Approve, route to finance, and send CSM follow-up.',
  application_id: 'support-portal-v2',
  input_model: 'gpt-4o',
});

Response:

{
  id: 'dc_01HZR7...',
  object: 'decision_card',
  created_at: '2026-05-20T00:00:00.000Z',
  workflow_type: 'support',
  decision_card: {
    recommendation: 'Approve refund exception for Acme Health.',
    confidence: { score: 0.82, label: 'high' },
    reasoning: 'Contract allows exception under clause 4.2.',
    evidence_trail: [...],
    risk_flags: [...],
    next_action: 'Approve, route to finance, and send CSM follow-up.',
  },
  audit: { request_id: 'req_abc123', tier: 'pro' }
}

northgale.explainBatch(params) — Up to 10 at once

const batch = await northgale.explainBatch({
  workflow_type: 'sales',
  input_model: 'gpt-4o',
  items: [
    { input_text: 'Account A scored 88/100.', confidence: 0.88 },
    { input_text: 'Account B scored 51/100.', confidence: 0.51 },
  ],
});

console.log(batch.count);      // 2
console.log(batch.results[0]); // full decision card

northgale.listDecisionCards(params?) — Query your history

const history = await northgale.listDecisionCards({
  limit: 20,
  workflow_type: 'sales',
  since: '2026-05-01T00:00:00Z',
});
// → { data: [...], pagination: { total: 142, limit: 20, offset: 0 } }

northgale.me() — Account & usage

const account = await northgale.me();
console.log(account.tier);               // 'pro'
console.log(account.usage.remaining);    // 98_732

Workflows — Save reusable configs

// Create a named workflow template
const workflow = await northgale.createWorkflow({
  name: 'Enterprise Sales Scoring',
  workflow_type: 'sales',
  description: 'High-stakes account prioritization with conservative thresholds.',
  config: { min_confidence: 0.7, require_evidence: true },
});

// Use it in explain calls
await northgale.explain({
  input_text: '...',
  workflow_id: workflow.id,
});

Audit Logs (Pro+)

// Paginated audit log
const logs = await northgale.getAuditLogs({ limit: 50 });

// CSV export (for SOC 2, EU AI Act compliance)
const csv = await northgale.exportAuditLogs({
  since: '2026-05-01T00:00:00Z',
  format: 'csv',
}) as string;

Error Handling

All errors throw a NorthgaleError with a .status (HTTP status code) and .message:

import Northgale, { NorthgaleError } from '@northgale/sdk';

try {
  await northgale.explain({ input_text: '' });
} catch (err) {
  if (err instanceof NorthgaleError) {
    console.error(err.status);  // 400
    console.error(err.message); // "input_text is required..."
  }
}

| Status | Meaning | |--------|---------| | 400 | Bad request — check your params | | 401 | Invalid API key | | 402 | Subscription issue — update payment | | 403 | Feature not on your plan | | 429 | Monthly quota exceeded | | 500 | Server error — retry with backoff |

TypeScript

The SDK is written in TypeScript and ships full type declarations. Every method, param, and response is typed — no any.

import Northgale, {
  ExplainParams,
  ExplainResponse,
  DecisionCard,
  NorthgaleError,
} from '@northgale/sdk';

Workflow Types

| Type | Use case | |------|----------| | sales | Account scoring, lead prioritization | | support | Response QA, ticket routing, refund decisions | | underwriting | Credit & risk review | | hr | Candidate screening | | legal | Document review, compliance checks | | custom | Anything else |

Plans

| | Starter | Pro | Ultra | Enterprise | |---|---|---|---|---| | Requests/month | 10K | 100K | 1M | Unlimited | | Audit logs | ❌ | ✅ 90 days | ✅ 1 year | ✅ Unlimited | | Batch API | ✅ | ✅ | ✅ | ✅ | | Workflows | ✅ | ✅ | ✅ | ✅ |

See pricing →

License

MIT © Northgale