npm package: @gibs-dev/sdk
Description: Official JavaScript/TypeScript SDK for the Gibs multi-regulation compliance API
Author: Gibbr AB
Latest version: 0.3.0

# @gibs-dev/sdk

Official JavaScript/TypeScript SDK for the [Gibs](https://gibs.dev) 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

```bash
npm install @gibs-dev/sdk
```

## Quick Start

```typescript
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.

```typescript
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.

```typescript
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:

```typescript
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 |

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
await client.deleteKey(42);
```

## Error Handling

The SDK provides a hierarchy of error classes for precise error handling:

```typescript
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:

```typescript
import type {
  ClassifyRequest,
  ClassifyResponse,
  CheckRequest,
  CheckResponse,
  StructuredAnswer,
  HealthResponse,
  SourceCitation,
  Obligation,
  RiskLevel,
  ConfidenceLevel,
  ResponseFormat,
  KeyInfo,
} from '@gibs-dev/sdk';
```

## License

MIT