SDKs

O Archyl oferece SDKs oficiais para Node.js e Python. Ambos são camadas leves sobre a API REST que cuidam da autenticação, da serialização e do tratamento de erros para você.

Instalação

Node.js

npm install @archyl/sdk

Python

pip install archyl-sdk

Início 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.",
)

Referência da API

Projetos

Método Descrição
projects.list() Lista todos os projetos da organização
projects.get(projectId) Obtém um projeto pelo ID
projects.create(data) Cria um novo projeto
projects.getC4Model(projectId) Obtém o modelo C4 completo de um projeto
projects.getAgentContext(projectId) Obtém o contexto arquitetural (regras, radar de tecnologias, decisões)

Modelo C4

Método Descrição
c4.createSystem(projectId, data) Cria um sistema
c4.updateSystem(projectId, systemId, data) Atualiza um sistema
c4.createContainer(projectId, systemId, data) Cria um contêiner
c4.updateContainer(projectId, containerId, data) Atualiza um contêiner
c4.createComponent(projectId, containerId, data) Cria um componente
c4.createRelationship(projectId, data) Cria um relacionamento entre elementos
c4.listRelationships(projectId) Lista todos os relacionamentos

Governança

Método Descrição
governance.runConformanceCheck(projectId, data) Executa as regras de conformidade sobre arquivos
governance.getReport(checkId) Obtém o relatório completo de uma verificação
governance.listRules() Lista todas as regras de conformidade
governance.createRule(data) Cria uma regra de conformidade
governance.getStats(projectId?) Obtém estatísticas de conformidade
governance.computeDrift(projectId) Calcula a pontuação de desvio de um projeto
governance.getDriftScore(projectId) Obtém a pontuação de desvio mais recente
governance.getDriftHistory(projectId) Obtém o histórico da pontuação de desvio ao longo do tempo

Métricas DORA

Método Descrição
dora.getMetrics(projectId) Obtém as métricas DORA atuais
dora.getTrend(projectId) Obtém a tendência das métricas DORA ao longo do tempo

Documentação

Método Descrição
docs.listADRs(projectId) Lista os Registros de Decisão de Arquitetura
docs.createADR(projectId, data) Cria um ADR
docs.listReleases(projectId) Lista as releases
docs.createRelease(projectId, data) Cria uma release
docs.listChangeRequests(projectId) Lista as solicitações de mudança
docs.createChangeRequest(projectId, data) Cria uma solicitação de mudança

Tratamento de Erros

Os dois SDKs lançam erros tipados com o código de status HTTP e os detalhes do erro retornados pela 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 status comuns:

Código Significado
400 Bad Request - Parâmetros inválidos
401 Unauthorized - Chave de API inválida ou ausente
403 Forbidden - Permissões insuficientes
404 Not Found - O recurso não existe
429 Too Many Requests - Limite de requisições excedido
500 Internal Server Error

Configuração

URL Base Personalizada

Para instâncias self-hosted do Archyl, informe uma 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-Fonte

Os dois SDKs são open source:

Próximos Passos