@mks2508/axon-sdk

Cliente HTTP tipado de los endpoints /api/governance/* de axon gateway-server. Browser-safe, fetch inyectable, API Result/no-throw.

El SDK nace contract-first: los write endpoints los define el contrato (U3b) y la implementación server-side los cubre (U3c).

Instalación

bun add @mks2508/axon-sdk

Uso

import { AxonSdk } from '@mks2508/axon-sdk';

const sdk = new AxonSdk({ baseUrl: 'https://governance.example.com' });

// Read
const model = await sdk.getModel('mks-agentics');
if (model.ok) console.log(model.value.nodes.length);

// Write — el flag GOVERNANCE_WRITE puede devolver write_disabled (variante esperada)
const r = await sdk.updateNodeStatus('mks-agentics', 'track/x/m1', 'in_progress');
if (!r.ok && r.error.code === 'SDK_WRITE_DISABLED') {
  console.warn('escrituras deshabilitadas server-side');
}

Endpoints

| Método SDK | HTTP | |---|---| | getModel(root?) | GET /api/governance/model | | getRoots() | GET /api/governance/roots | | getNodeArtifacts(root, nodeId) | GET /api/governance/node-artifacts | | getArtifact(root, path) | GET /api/governance/artifact | | getCommits(root, {grep?, hashes?}) | GET /api/governance/commits | | getSessions(root) | GET /api/governance/sessions | | updateNodeStatus(root, nodeId, status) | PATCH /api/governance/node | | addNode(root, spec) | POST /api/governance/node | | updateGateItem(root, nodeId, itemId, patch) | PATCH /api/governance/gate-item | | twAction(root, {uuid, action, annotation?}) | POST /api/governance/tw-action |

Errores

Todos los métodos devuelven Result<T, SdkError> (nunca lanzan). SdkErrorCode:

• SDK_NETWORK_ERROR — el fetch lanzó (sin conexión, DNS, timeout).
• SDK_HTTP_ERROR — respuesta non-2xx distinta de 403-write_disabled.
• SDK_WRITE_DISABLED — 403 write_disabled (flag GOVERNANCE_WRITE apagado). Variante esperada.
• SDK_BAD_RESPONSE — el body no es JSON válido.

Browser-safe

Cero imports node:* o Bun. fetch inyectable ({ baseUrl, fetch? } en el constructor), globalThis.fetch por defecto. Único runtime dep: @mks2508/no-throw.