G8KEPR TypeScript SDK

Official TypeScript/JavaScript SDK for the G8KEPR API Security Platform. Provides type-safe access to all platform endpoints with full IntelliSense support.

Installation

npm install @g8kepr/sdk

yarn add @g8kepr/sdk

pnpm add @g8kepr/sdk

Quick Start

import { G8KEPRClient } from '@g8kepr/sdk';

// Initialize with API key
const client = new G8KEPRClient({
  baseUrl: 'https://api.g8kepr.com',
  apiKey: 'your-api-key',
});

// Or authenticate with email/password
const { data } = await client.auth.login({
  email: '[email protected]',
  password: 'your-password',
});

// List AI agents
const agents = await client.agents.list();

// Get recent threats
const threats = await client.threats.list({ limit: 10, severity: 'critical' });

// Dashboard overview
const overview = await client.dashboard.overview();

Configuration

import { G8KEPRClient, type G8KEPRClientConfig } from '@g8kepr/sdk';

const config: G8KEPRClientConfig = {
  /** Base URL for the G8KEPR API */
  baseUrl: 'https://api.g8kepr.com',

  /** API key authentication */
  apiKey: 'gk_live_...',

  /** Bearer token authentication (alternative to API key) */
  accessToken: 'eyJhbGci...',

  /** Organization ID for multi-tenant deployments */
  organizationId: 'org_abc123',

  /** Request timeout in milliseconds (default: 30000) */
  timeout: 30000,

  /** Custom fetch implementation (e.g., for Node.js < 18) */
  fetch: customFetch,
};

const client = new G8KEPRClient(config);

Updating Credentials at Runtime

// Refresh the access token
client.setAccessToken('new-token');

// Rotate API key
client.setApiKey('new-api-key');

Direct API Access

For endpoints not covered by the convenience methods, use the raw client:

const { data, error } = await client.raw.GET('/api/custom/endpoint', {
  params: { query: { foo: 'bar' } },
});

Features

Authentication

// Login with email and password
const { data, error } = await client.auth.login({
  email: '[email protected]',
  password: 'secure-password',
});

// Register a new user
await client.auth.register({
  email: '[email protected]',
  password: 'secure-password',
  name: 'Jane Doe',
});

// Get current user profile
const { data: user } = await client.auth.me();

// Refresh access token
await client.auth.refresh({ refresh_token: 'your-refresh-token' });

// Logout
await client.auth.logout();

Threat Detection

// List threats with filters
const { data: threats } = await client.threats.list({
  limit: 100,
  offset: 0,
  severity: 'critical',
});

// Get a specific threat
const { data: threat } = await client.threats.get('threat-id-123');

// Acknowledge a threat
await client.threats.acknowledge('threat-id-123');

// Resolve a threat with notes
await client.threats.resolve('threat-id-123', {
  resolution_notes: 'False positive - internal scanner traffic',
});

// Get threat statistics
const { data: stats } = await client.threats.stats();

Compliance

// Get compliance status overview
const { data: status } = await client.compliance.status();

// List all compliance frameworks
const { data: frameworks } = await client.compliance.frameworks();

// Get SOC2-specific compliance status
const { data: soc2 } = await client.compliance.framework('soc2');

// List controls filtered by framework
const { data: controls } = await client.compliance.controls({ framework: 'hipaa' });

// Get specific control details
const { data: control } = await client.compliance.control('ctrl-001');

// Generate compliance evidence for a framework
await client.compliance.evidence('iso27001');

AI Gateway

// Get gateway status
const { data: status } = await client.gateway.status();

// Check gateway health
const { data: health } = await client.gateway.health();

// List configured AI providers
const { data: providers } = await client.gateway.providers();

// Get a specific provider's config
const { data: provider } = await client.gateway.provider('openai');

// View rate limits
const { data: limits } = await client.gateway.rateLimits();

// Circuit breaker status
const { data: breakers } = await client.gateway.circuitBreakers();

// Gateway performance metrics
const { data: metrics } = await client.gateway.metrics();

AI Agents

// List all agents
const { data: agents } = await client.agents.list();

// List agents filtered by status
const { data: activeAgents } = await client.agents.list({ status: 'active' });

// Get a specific agent
const { data: agent } = await client.agents.get('agent-id-123');

// Create a new agent
const { data: newAgent } = await client.agents.create({
  name: 'SecurityScanner',
  description: 'Automated security scanning agent',
  capabilities: ['tool_use', 'memory'],
  tools: ['read_file', 'scan_endpoint'],
  config: { max_iterations: 10 },
});

// Update an agent
await client.agents.update('agent-id-123', {
  status: 'inactive',
  config: { max_iterations: 20 },
});

// Execute an agent action
const { data: result } = await client.agents.execute('agent-id-123', {
  action: 'scan',
  parameters: { target: 'https://api.example.com' },
});

// Delete an agent
await client.agents.delete('agent-id-123');

MCP (Model Context Protocol) Security

// List registered MCP tools
const { data: tools } = await client.mcp.tools();

// List tools for a specific server
const { data: serverTools } = await client.mcp.tools({ server_id: 'server-abc' });

// List permission rules
const { data: permissions } = await client.mcp.permissions();

// Filter permissions by type
const { data: userPerms } = await client.mcp.permissions({ permission_type: 'user' });

// List active sessions
const { data: sessions } = await client.mcp.sessions({ status: 'active' });

// Get a specific session
const { data: session } = await client.mcp.session('session-id-456');

// List execution contexts
const { data: contexts } = await client.mcp.contexts();

Dashboard

// Get dashboard overview with key metrics
const { data: overview } = await client.dashboard.overview();

// Get platform health summary
const { data: health } = await client.dashboard.health();

// Get security posture summary
const { data: posture } = await client.dashboard.securityPosture();

// Get recent alerts
const { data: alerts } = await client.dashboard.recentAlerts({ limit: 20 });

Security Posture

// Get overall security posture
const { data: posture } = await client.posture.status();

// Get security score
const { data: score } = await client.posture.score();

// Get recommendations
const { data: recs } = await client.posture.recommendations();

// List vulnerabilities
const { data: vulns } = await client.posture.vulnerabilities();

// Risk assessment
const { data: risks } = await client.posture.risks();

Audit Logs

// List audit logs
const { data: logs } = await client.audit.list({
  limit: 50,
  start_date: '2025-01-01',
  end_date: '2025-01-31',
  action: 'user.login',
});

// Get a specific log entry
const { data: log } = await client.audit.get('log-id-789');

// Export audit logs as CSV
const { data: csv } = await client.audit.export({
  format: 'csv',
  start_date: '2025-01-01',
  end_date: '2025-01-31',
});

Analytics

// Get analytics overview
const { data: overview } = await client.analytics.overview();

// Get usage metrics by period
const { data: usage } = await client.analytics.usage({ period: 'week' });

// Get performance metrics
const { data: perf } = await client.analytics.performance();

// Get trend data
const { data: trends } = await client.analytics.trends({
  metric: 'threats_blocked',
  period: '30d',
});

API Keys

// List API keys
const { data: keys } = await client.keys.list();

// Create a new key with scopes
const { data: newKey } = await client.keys.create({
  name: 'CI/CD Pipeline Key',
  scopes: ['threats:read', 'compliance:read'],
  expires_at: '2026-01-01T00:00:00Z',
});

// Rotate a key
const { data: rotated } = await client.keys.rotate('key-id-123');

// Revoke a key
await client.keys.revoke('key-id-123');

Reports

// List report templates
const { data: templates } = await client.reports.templates();

// Generate a PDF report
const { data: report } = await client.reports.generate({
  template_id: 'monthly-security-summary',
  format: 'pdf',
});

// Check report generation status
const { data: status } = await client.reports.status('report-id-123');

// Download the report
const { data: file } = await client.reports.download('report-id-123');

Health Checks

// Basic health check
const { data: health } = await client.health.check();

// Detailed health status
const { data: detailed } = await client.health.detailed();

// Kubernetes-style probes
const { data: ready } = await client.health.ready();
const { data: live } = await client.health.live();

Error Handling

All methods return { data, error, response } following the openapi-fetch pattern. Errors are returned as values rather than thrown exceptions, making error handling explicit and type-safe.

import { G8KEPRClient } from '@g8kepr/sdk';

const client = new G8KEPRClient({
  baseUrl: 'https://api.g8kepr.com',
  apiKey: 'your-api-key',
});

// Pattern 1: Check for errors inline
const { data, error } = await client.threats.list();

if (error) {
  console.error('Failed to fetch threats:', error);
  // error is typed based on the OpenAPI schema
  return;
}

// data is fully typed and narrowed to the success type
console.log(`Found ${data.length} threats`);

// Pattern 2: Handle specific HTTP status codes
const { data, error, response } = await client.agents.get('nonexistent-id');

if (error) {
  switch (response.status) {
    case 401:
      console.error('Authentication failed - check your API key');
      break;
    case 403:
      console.error('Insufficient permissions');
      break;
    case 404:
      console.error('Agent not found');
      break;
    case 429:
      const retryAfter = response.headers.get('Retry-After');
      console.error(`Rate limited. Retry after ${retryAfter} seconds`);
      break;
    default:
      console.error(`Unexpected error (${response.status}):`, error);
  }
}

// Pattern 3: Wrapper for throw-on-error behavior
async function fetchOrThrow<T>(promise: Promise<{ data?: T; error?: unknown; response: Response }>) {
  const { data, error, response } = await promise;
  if (error) {
    throw new Error(`API Error ${response.status}: ${JSON.stringify(error)}`);
  }
  return data as T;
}

// Usage
try {
  const threats = await fetchOrThrow(client.threats.list());
  console.log(threats);
} catch (err) {
  console.error('Request failed:', err);
}

TypeScript Types

The SDK exports full OpenAPI-generated types for request and response schemas:

import type { paths, components, Schemas } from '@g8kepr/sdk';

// Access response types via the paths interface
type ThreatsResponse = paths['/api/threats']['get']['responses']['200']['content']['application/json'];

// Access schema types via the Schemas helper
type Threat = Schemas['Threat'];
type Agent = Schemas['Agent'];
type ComplianceFramework = Schemas['ComplianceFramework'];

// Use in your application
function renderThreat(threat: Threat) {
  console.log(`${threat.type} - Severity: ${threat.severity}`);
}

Requirements

• TypeScript 5.0+ (for type-safe usage)
• Node.js 18+ or any environment with a global fetch implementation
• openapi-fetch ^0.13.0 (included as a dependency)

Releasing a new version

Tagged-release workflow is .github/workflows/sdk-release.yml. It is tag-gated: nothing publishes from a plain main merge.

# 1. Bump the version in package.json
npm version 1.2.3 --no-git-tag-version

# 2. Verify the build locally (same dry-run the workflow runs)
npm run typecheck
npm run build
npm run publish:dry

# 3. Commit the bump, push, and tag with the SDK-prefix
git commit -am "chore(sdk-ts): bump to 1.2.3"
git tag sdk-ts-v1.2.3
git push && git push --tags

The workflow's dry-run job runs first. If the git tag and package.json version disagree, it fails before touching npm. On green dry-run, the publish job runs gated behind the sdk-release GitHub environment and pushes with --provenance for supply-chain attestation.

License

Copyright (c) 2024-2025 Wesley Ellis. All Rights Reserved.