@gibs-dev/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gibbr AB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# @gibs/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 and GDPR. Every claim is traced to a specific article in the legal corpus.
+
+## Installation
+
+```bash
+npm install @gibs/sdk
+```
+
+## Quick Start
+
+```typescript
+import { GibsClient } from '@gibs/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.obligations);  // [{id: "risk_mgmt", ...}, ...]
+console.log(classification.sources);      // [{article_id: "ai_act_art6", ...}]
+
+// Ask a compliance question
+const answer = await client.check({
+  question: 'What are the transparency requirements for chatbots under the AI Act?',
+  regulation: 'ai_act',
+});
+
+console.log(answer.answer);     // Detailed answer with article citations
+console.log(answer.confidence); // "high" | "medium" | "low"
+console.log(answer.sources);    // Source 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: 0.0 - 1.0
+// result.reasoning: string
+// result.obligations: Obligation[]
+// result.sources: SourceCitation[]
+```
+
+### `client.check(request)`
+
+Ask a compliance question and get a grounded answer with source citations.
+
+```typescript
+const answer = await client.check({
+  question: 'What are GDPR data subject rights?',
+  regulation: 'gdpr',
+  system_context: {
+    industry: 'healthcare',
+    data_types: 'patient records',
+  },
+});
+
+// answer.answer: string
+// answer.confidence: "high" | "medium" | "low"
+// answer.sources: SourceCitation[]
+// answer.should_abstain: boolean
+// answer.abstention_reason: string | null
+```
+
+### `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/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,
+  HealthResponse,
+  SourceCitation,
+  Obligation,
+  RiskLevel,
+  ConfidenceLevel,
+  KeyInfo,
+} from '@gibs/sdk';
+```
+
+## License
+
+MIT

package/dist/cjs/client.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Gibs API client.
+ *
+ * Provides typed methods for all Gibs compliance API endpoints.
+ * Uses native `fetch` -- works in Node.js 18+, browsers, Deno, and Bun.
+ *
+ * @module client
+ */
+import type { CheckRequest, CheckResponse, ClassifyRequest, ClassifyResponse, CreateKeyRequest, GibsClientOptions, HealthResponse, KeyCreatedResponse, KeyDeletedResponse, KeyInfo } from './types.js';
+/**
+ * Official client for the Gibs multi-regulation compliance API.
+ *
+ * @example
+ * ```ts
+ * import { GibsClient } from '@gibs/sdk';
+ *
+ * const client = new GibsClient({ apiKey: 'gbs_live_xxx' });
+ *
+ * const result = await client.classify({
+ *   description: 'Facial recognition system for airport security',
+ * });
+ * console.log(result.risk_level);
+ * ```
+ */
+export declare class GibsClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    constructor(options: GibsClientOptions);
+    /**
+     * Classify an AI system under EU AI Act risk levels.
+     *
+     * Returns the risk classification, relevant obligations,
+     * and source citations from the legal corpus.
+     *
+     * @param request - Description of the AI system to classify.
+     * @returns Classification result with risk level and obligations.
+     *
+     * @example
+     * ```ts
+     * const result = await client.classify({
+     *   description: 'CV screening tool that ranks job applicants',
+     *   sector: 'employment',
+     *   data_types: ['biometric'],
+     * });
+     *
+     * console.log(result.risk_level);    // "high"
+     * console.log(result.obligations);   // [{id: "risk_mgmt", ...}, ...]
+     * ```
+     */
+    classify(request: ClassifyRequest): Promise<ClassifyResponse>;
+    /**
+     * Ask a compliance question and get a grounded answer with citations.
+     *
+     * Every claim in the answer is traceable to a specific article
+     * in the legal corpus. If the corpus doesn't cover the question,
+     * the response indicates abstention with a reason.
+     *
+     * @param request - The compliance question and optional context.
+     * @returns Answer with source citations and confidence level.
+     *
+     * @example
+     * ```ts
+     * const answer = await client.check({
+     *   question: 'What are the transparency requirements for chatbots under the AI Act?',
+     *   regulation: 'ai_act',
+     * });
+     *
+     * console.log(answer.answer);
+     * console.log(answer.sources);
+     * ```
+     */
+    check(request: CheckRequest): Promise<CheckResponse>;
+    /**
+     * Check API health and component status.
+     *
+     * Does not require authentication.
+     *
+     * @returns Health status with component details.
+     *
+     * @example
+     * ```ts
+     * const health = await client.health();
+     * console.log(health.status);        // "healthy"
+     * console.log(health.components);    // {api: "healthy", qdrant: "healthy", ...}
+     * ```
+     */
+    health(): Promise<HealthResponse>;
+    /**
+     * List all active API keys for your organization.
+     *
+     * Returns metadata only -- never includes the full key value.
+     *
+     * @returns Array of key metadata.
+     */
+    listKeys(): Promise<KeyInfo[]>;
+    /**
+     * Create a new API key for your organization.
+     *
+     * The full key value is returned exactly once in the response.
+     * Store it securely -- it cannot be retrieved again.
+     *
+     * Maximum 5 active keys per organization.
+     *
+     * @param request - Optional name for the key.
+     * @returns The created key including the full key value (shown once).
+     */
+    createKey(request?: CreateKeyRequest): Promise<KeyCreatedResponse>;
+    /**
+     * Revoke an API key.
+     *
+     * The key must belong to your organization. You cannot revoke
+     * the key that is currently being used for authentication.
+     *
+     * @param keyId - Database ID of the key to revoke.
+     * @returns Confirmation with status "revoked".
+     */
+    deleteKey(keyId: number): Promise<KeyDeletedResponse>;
+    /**
+     * Execute an HTTP request with retries, timeout, and error handling.
+     */
+    private _request;
+    /**
+     * Fetch with an AbortController-based timeout.
+     */
+    private _fetchWithTimeout;
+    /**
+     * Build the correct error class for a given HTTP status code.
+     */
+    private _buildError;
+    /**
+     * Calculate retry delay with exponential backoff and jitter.
+     *
+     * For rate limit errors, respects the Retry-After header.
+     */
+    private _retryDelay;
+    /**
+     * Extract response headers into a plain object.
+     */
+    private _extractHeaders;
+    /**
+     * Check if an error is a network-level error (no HTTP response received).
+     */
+    private _isNetworkError;
+    /**
+     * Sleep for a given number of milliseconds.
+     */
+    private _sleep;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/cjs/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,OAAO,EACR,MAAM,YAAY,CAAC;AAgBpB;;;;;;;;;;;;;;GAcG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,OAAO,EAAE,iBAAiB;IAiBtC;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAInE;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAI1D;;;;;;;;;;;;;OAaG;IACG,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;IAIvC;;;;;;OAMG;IACG,QAAQ,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAIpC;;;;;;;;;;OAUG;IACG,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIxE;;;;;;;;OAQG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAQ3D;;OAEG;YACW,QAAQ;IA4FtB;;OAEG;YACW,iBAAiB;IA2B/B;;OAEG;IACH,OAAO,CAAC,WAAW;IAenB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAenB;;OAEG;IACH,OAAO,CAAC,eAAe;IAQvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAgBvB;;OAEG;IACH,OAAO,CAAC,MAAM;CAGf"}