@archicore/sdk

Official TypeScript/JavaScript SDK for the ArchiCore Architecture Analysis API.

Installation

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

Quick Start

import { ArchiCore } from '@archicore/sdk';

// Initialize client
const client = new ArchiCore({ apiKey: 'your-api-key' });

// List projects
const projects = await client.projects.list();
console.log(projects);

// Search code semantically
const results = await client.projects.search('project-id', {
  query: 'authentication middleware'
});

// Ask AI assistant
const answer = await client.projects.ask('project-id', {
  question: 'How does the authentication system work?'
});
console.log(answer.response);

Features

• Full TypeScript Support: Complete type definitions included
• Projects: Create, list, delete, and manage projects
• Semantic Search: Search code using natural language
• AI Assistant: Ask questions about your codebase
• Impact Analysis: Analyze how changes affect your codebase
• Code Metrics: Get code quality metrics
• Security Scanning: Identify vulnerabilities
• Webhooks: Subscribe to events

API Reference

Projects

// List all projects
const projects = await client.projects.list();

// Get a specific project
const project = await client.projects.get('project-id');

// Create a project
const project = await client.projects.create({
  name: 'my-project',
  githubUrl: 'https://github.com/user/repo'
});

// Delete a project
await client.projects.delete('project-id');

// Trigger indexing
await client.projects.index('project-id', { force: true });

Search & AI

// Semantic search
const results = await client.projects.search('project-id', {
  query: 'error handling',
  limit: 20,
  threshold: 0.8
});

// Ask AI assistant
const answer = await client.projects.ask('project-id', {
  question: 'What design patterns are used?',
  context: 'Focus on the authentication module'
});

Analysis

// Get code metrics
const metrics = await client.projects.metrics('project-id');
console.log(`Total files: ${metrics.totalFiles}`);
console.log(`Total lines: ${metrics.totalLines}`);

// Get security scan results
const security = await client.projects.security('project-id');
for (const vuln of security.vulnerabilities) {
  console.log(`[${vuln.severity}] ${vuln.message}`);
}

// Impact analysis
const impact = await client.projects.analyze('project-id', {
  files: ['src/auth/login.ts', 'src/auth/middleware.ts']
});
console.log(`Affected files: ${impact.affectedFiles.length}`);

Webhooks

// List webhooks
const webhooks = await client.webhooks.list();

// Create a webhook
const webhook = await client.webhooks.create({
  url: 'https://example.com/webhook',
  events: ['project.indexed', 'analysis.complete'],
  secret: 'your-webhook-secret'
});

// Delete a webhook
await client.webhooks.delete('webhook-id');

Error Handling

import {
  ArchiCore,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
  ValidationError
} from '@archicore/sdk';

const client = new ArchiCore({ apiKey: 'your-api-key' });

try {
  const project = await client.projects.get('non-existent-id');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Project not found');
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof ValidationError) {
    console.log(`Invalid request: ${error.message}`);
  }
}

Configuration

Custom Base URL

For self-hosted instances:

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

Timeout

const client = new ArchiCore({
  apiKey: 'your-api-key',
  timeout: 60000 // milliseconds
});

Browser Support

This SDK works in both Node.js and browser environments. It uses the native fetch API.

For Node.js < 18, you may need to polyfill fetch:

import fetch from 'node-fetch';
globalThis.fetch = fetch;

TypeScript

Full TypeScript support is included. All types are exported:

import type {
  Project,
  SearchResult,
  AskResponse,
  Metrics,
  SecurityReport,
  ImpactAnalysis,
  Webhook,
  ArchiCoreConfig
} from '@archicore/sdk';

Requirements

• Node.js >= 16 (for native fetch) or polyfill
• Modern browsers with fetch support

License

MIT License - see LICENSE for details.

Links

• Documentation
• API Reference
• ArchiCore Website
• Report Issues