@gibs-dev/sdk

Official JavaScript/TypeScript SDK for the Gibs multi-regulation compliance API.

Gibs provides instant, source-cited compliance answers for EU regulations including the AI Act, GDPR, and DORA. Every claim is traced to a specific article in the legal corpus.

Installation

npm install @gibs-dev/sdk

Quick Start

import { GibsClient } from '@gibs-dev/sdk';

const client = new GibsClient({ apiKey: 'gbs_live_xxx' });

// Classify an AI system's risk level
const classification = await client.classify({
  description: 'Facial recognition system for airport security',
  sector: 'security',
  data_types: ['biometric'],
});

console.log(classification.risk_level);   // "high"
console.log(classification.reasoning);    // Detailed explanation with article references
console.log(classification.sources);      // [{article_id: "Article 6", ...}]

// Ask a compliance question
const answer = await client.check({
  question: 'What are the transparency requirements for chatbots under the AI Act?',
});

console.log(answer.answer);           // Detailed answer with article citations
console.log(answer.confidence);       // "high" | "medium" | "low"
console.log(answer.confidence_score); // 0.87
console.log(answer.sources);          // Source citations

// Get structured (machine-readable) response
const structured = await client.check({
  question: 'What are the risk management obligations for high-risk AI?',
  response_format: 'structured',
});

console.log(structured.structured?.summary);        // Direct answer
console.log(structured.structured?.requirements);   // ["Implement risk management...", ...]
console.log(structured.structured?.articles_cited); // ["Article 9", "Article 6", ...]
console.log(structured.confidence_score);           // 0.89

// DORA: ICT resilience for financial entities
const dora = await client.check({
  question: 'What are the ICT incident reporting timelines under DORA?',
});

console.log(dora.answer);       // Timeline with Article 19 citations

Requirements

• Node.js 18+ (uses native fetch)
• Also works in modern browsers, Deno, and Bun

API Reference

new GibsClient(options)

Create a new client instance.

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your API key (gbs_live_xxx or gbs_test_xxx) | | baseUrl | string | https://api.gibs.dev | API base URL | | timeout | number | 120000 | Request timeout in milliseconds | | maxRetries | number | 3 | Max retries on transient failures |

client.classify(request)

Classify an AI system under EU AI Act risk levels.

const result = await client.classify({
  description: 'CV screening tool that ranks job applicants',
  sector: 'employment',
  data_types: ['biometric'],
  decision_scope: 'hiring decisions',
});

// result.risk_level: "prohibited" | "high" | "limited" | "minimal"
// result.confidence: number (0.0 - 1.0)
// result.reasoning: string
// result.obligations: Obligation[]
// result.sources: SourceCitation[]
// result.corpus_version: string
// result.processing_time_ms: number

client.check(request)

Ask a compliance question and get a grounded answer with source citations. The API automatically detects which regulation(s) the question targets (AI Act, GDPR, DORA) and routes to the correct corpus.

const answer = await client.check({
  question: 'What are GDPR data subject rights?',
  system_context: {
    industry: 'healthcare',
    data_types: 'patient records',
  },
});

// answer.answer: string
// answer.confidence: "high" | "medium" | "low"
// answer.confidence_score: number (0.0–1.0)
// answer.sources: SourceCitation[]
// answer.should_abstain: boolean
// answer.abstention_reason: string | null
// answer.corpus_version: string
// answer.processing_time_ms: number

Structured response mode

Pass response_format: 'structured' to get machine-readable parsed sections:

const answer = await client.check({
  question: 'What are the transparency requirements for chatbots?',
  response_format: 'structured',
});

// answer.structured?.summary         — Direct 1-2 sentence answer
// answer.structured?.legal_basis     — Legal basis with article references
// answer.structured?.requirements    — ["Disclose AI interaction per Article 50(1)", ...]
// answer.structured?.timeline        — ["Applies from 2 August 2026"]
// answer.structured?.articles_cited  — ["Article 50", "Article 52"]

Confidence score

Every /check response includes a numeric confidence_score (0.0–1.0) for programmatic decisions:

| Score | Meaning | |-------|---------| | 0.8–1.0 | High confidence — well-sourced, specific answer | | 0.5–0.8 | Medium — partial sources or hedged language | | 0.0–0.5 | Low — limited sources, verify with legal counsel |

if (answer.confidence_score >= 0.7) {
  applyComplianceRules(answer.structured?.requirements);
} else {
  flagForHumanReview(answer);
}

client.health()

Check API health and component status. Does not require authentication.

const health = await client.health();
// health.status: "healthy" | "degraded" | "unhealthy"
// health.components: { api: "healthy", qdrant: "healthy", ... }

client.listKeys()

List all active API keys for your organization.

const keys = await client.listKeys();
// keys: KeyInfo[]

client.createKey(request?)

Create a new API key. The full key value is shown only once in the response.

const key = await client.createKey({ name: 'Production' });
console.log(key.api_key); // Store this securely -- cannot be retrieved again

client.deleteKey(keyId)

Revoke an API key.

await client.deleteKey(42);

Error Handling

The SDK provides a hierarchy of error classes for precise error handling:

import {
  GibsError,          // Base class for all SDK errors
  GibsAPIError,       // HTTP 4xx/5xx responses
  GibsAuthError,      // HTTP 401 (invalid/missing API key)
  GibsRateLimitError, // HTTP 429 (rate limit exceeded)
  GibsTimeoutError,   // Request timed out
  GibsConnectionError // Network connectivity issues
} from '@gibs-dev/sdk';

try {
  const result = await client.classify({
    description: 'My AI system',
  });
} catch (err) {
  if (err instanceof GibsAuthError) {
    // Invalid or missing API key
    console.error('Authentication failed:', err.message);
  } else if (err instanceof GibsRateLimitError) {
    // Rate limit exceeded -- check retryAfter
    console.error(`Rate limited. Retry after ${err.retryAfter} seconds`);
  } else if (err instanceof GibsTimeoutError) {
    // Request took too long
    console.error('Request timed out');
  } else if (err instanceof GibsConnectionError) {
    // Network issue
    console.error('Could not reach API:', err.message);
  } else if (err instanceof GibsAPIError) {
    // Other API error (404, 409, 500, etc.)
    console.error(`API error ${err.status}: ${err.message}`);
  }
}

Retries

The SDK automatically retries failed requests with exponential backoff for transient errors:

• Retried: 408, 429, 500, 502, 503, 504, network errors, timeouts
• Not retried: 401, 403, 404, 409, 422 (client errors)

For 429 responses, the SDK respects the Retry-After header.

Default: 3 retries with exponential backoff starting at 500ms.

TypeScript

The SDK is written in TypeScript with strict mode and exports all types:

import type {
  ClassifyRequest,
  ClassifyResponse,
  CheckRequest,
  CheckResponse,
  StructuredAnswer,
  HealthResponse,
  SourceCitation,
  Obligation,
  RiskLevel,
  ConfidenceLevel,
  ResponseFormat,
  KeyInfo,
} from '@gibs-dev/sdk';

License

MIT