SDKs

Archyl ofrece SDKs oficiales para Node.js y Python. Ambos son capas ligeras sobre la API REST que se encargan por ti de la autenticación, la serialización y la gestión de errores.

Instalación

Node.js

npm install @archyl/sdk

Python

pip install archyl-sdk

Inicio rápido

Node.js

import { ArchylClient } from "@archyl/sdk";

const client = new ArchylClient({
  apiKey: process.env.ARCHYL_API_KEY,
  organizationId: "your-org-id",
});

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

// Get C4 model
const model = await client.projects.getC4Model("project-id");

// Compute drift score
const drift = await client.governance.computeDrift("project-id");

// Create an ADR
const adr = await client.docs.createADR("project-id", {
  title: "Use PostgreSQL for persistence",
  status: "accepted",
  context: "We need a relational database for transactional data.",
  decision: "Adopt PostgreSQL 16 as the primary datastore.",
  consequences: "Team must learn PostgreSQL-specific features.",
});

Python

from archyl import ArchylClient

client = ArchylClient(
    api_key=os.environ["ARCHYL_API_KEY"],
    organization_id="your-org-id",
)

# List projects
projects = client.projects.list()

# Get C4 model
model = client.projects.get_c4_model("project-id")

# Compute drift score
drift = client.governance.compute_drift("project-id")

# Create an ADR
adr = client.docs.create_adr("project-id",
    title="Use PostgreSQL for persistence",
    status="accepted",
    context="We need a relational database for transactional data.",
    decision="Adopt PostgreSQL 16 as the primary datastore.",
    consequences="Team must learn PostgreSQL-specific features.",
)

Referencia de la API

Proyectos

Método	Descripción
`projects.list()`	Lista todos los proyectos de la organización
`projects.get(projectId)`	Obtiene un proyecto por su ID
`projects.create(data)`	Crea un proyecto nuevo
`projects.getC4Model(projectId)`	Obtiene el modelo C4 completo de un proyecto
`projects.getAgentContext(projectId)`	Obtiene el contexto arquitectónico (reglas, radar tecnológico, decisiones)

Modelo C4

Método	Descripción
`c4.createSystem(projectId, data)`	Crea un sistema
`c4.updateSystem(projectId, systemId, data)`	Actualiza un sistema
`c4.createContainer(projectId, systemId, data)`	Crea un contenedor
`c4.updateContainer(projectId, containerId, data)`	Actualiza un contenedor
`c4.createComponent(projectId, containerId, data)`	Crea un componente
`c4.createRelationship(projectId, data)`	Crea una relación entre elementos
`c4.listRelationships(projectId)`	Lista todas las relaciones

Gobernanza

Método	Descripción
`governance.runConformanceCheck(projectId, data)`	Ejecuta las reglas de conformidad sobre un conjunto de archivos
`governance.getReport(checkId)`	Obtiene el informe completo de una verificación
`governance.listRules()`	Lista todas las reglas de conformidad
`governance.createRule(data)`	Crea una regla de conformidad
`governance.getStats(projectId?)`	Obtiene las estadísticas de conformidad
`governance.computeDrift(projectId)`	Calcula la puntuación de deriva de un proyecto
`governance.getDriftScore(projectId)`	Obtiene la última puntuación de deriva
`governance.getDriftHistory(projectId)`	Obtiene el historial de la puntuación de deriva a lo largo del tiempo

Métricas DORA

Método	Descripción
`dora.getMetrics(projectId)`	Obtiene las métricas DORA actuales
`dora.getTrend(projectId)`	Obtiene la tendencia de las métricas DORA a lo largo del tiempo

Documentación

Método	Descripción
`docs.listADRs(projectId)`	Lista los Architecture Decision Records
`docs.createADR(projectId, data)`	Crea un ADR
`docs.listReleases(projectId)`	Lista las releases
`docs.createRelease(projectId, data)`	Crea una release
`docs.listChangeRequests(projectId)`	Lista las solicitudes de cambio
`docs.createChangeRequest(projectId, data)`	Crea una solicitud de cambio

Gestión de errores

Ambos SDKs lanzan errores tipados con el código de estado HTTP y los detalles del error devueltos por la API.

Node.js

import { ArchylError } from "@archyl/sdk";

try {
  await client.projects.get("nonexistent-id");
} catch (error) {
  if (error instanceof ArchylError) {
    console.error(error.status); // 404
    console.error(error.code); // "NOT_FOUND"
    console.error(error.message); // "Project not found"
  }
}

Python

from archyl import ArchylError

try:
    client.projects.get("nonexistent-id")
except ArchylError as e:
    print(e.status)   # 404
    print(e.code)     # "NOT_FOUND"
    print(e.message)  # "Project not found"

Códigos de estado habituales:

Código	Significado
400	Bad Request - Parámetros no válidos
401	Unauthorized - Clave API no válida o ausente
403	Forbidden - Permisos insuficientes
404	Not Found - El recurso no existe
429	Too Many Requests - Límite de peticiones superado
500	Internal Server Error

Configuración

URL base personalizada

Para instancias autoalojadas de Archyl, pasa una baseUrl personalizada:

const client = new ArchylClient({
  apiKey: "your-api-key",
  organizationId: "your-org-id",
  baseUrl: "https://archyl.your-company.com/api/v1",
});

client = ArchylClient(
    api_key="your-api-key",
    organization_id="your-org-id",
    base_url="https://archyl.your-company.com/api/v1",
)

Código fuente

Ambos SDKs son de código abierto:

github.com/archyl-com/sdk

Próximos pasos

Visión general de la API - Documentación completa de la API REST
Autenticación - Gestión de claves API
Servidor MCP - Integración con asistentes de IA