{"_id":"@argorix/sdk","name":"@argorix/sdk","dist-tags":{"latest":"0.3.0"},"versions":{"0.3.0":{"name":"@argorix/sdk","version":"0.3.0","description":"Official Argorix SDK for Node.js and TypeScript runtimes","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc -p tsconfig.json","clean":"rimraf dist","prepublishOnly":"npm run clean && npm run build","pretest":"npm run build","test":"node --test test/*.test.mjs"},"keywords":["argorix","ai-governance","governance","ai","guardrails","agents","security","sdk"],"author":{"name":"Argorix"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/argorixlabs/argorix-node.git"},"homepage":"https://github.com/argorixlabs/argorix-node#readme","bugs":{"url":"https://github.com/argorixlabs/argorix-node/issues"},"publishConfig":{"access":"public"},"engines":{"node":">=18"},"devDependencies":{"rimraf":"^6.0.1","typescript":"^5.9.3"},"gitHead":"123533f467edeb13862b03211e48b26cd4340fb1","_id":"@argorix/sdk@0.3.0","_nodeVersion":"22.18.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-t+ycbzVy5qr6r2c0W+Gr6BW3L4sLGCQKvX7wu+KgHgy5FeOhlGc00/Fq1hFI2SqWAl2khtfvG+Om+osgMsZQog==","shasum":"82557ac101772c7b48d990520c0fdee538e86b3e","tarball":"https://registry.npmjs.org/@argorix/sdk/-/sdk-0.3.0.tgz","fileCount":18,"unpackedSize":56147,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEWaeOKJ2Nn3geSZT70EMnnf0yZShQYoNPOXTmrf/7wAAiEAmLMDUsAr/Uxds+Jy0g3IK5IN1K613R7pRU6Hn6vUZV4="}]},"_npmUser":{"name":"governanceai","email":"gustavo@gobiernoia.cl"},"directories":{},"maintainers":[{"name":"governanceai","email":"gustavo@gobiernoia.cl"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.3.0_1785649722746_0.3174125027418404"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-02T05:48:42.641Z","0.3.0":"2026-08-02T05:48:42.896Z","modified":"2026-08-02T05:48:43.067Z"},"maintainers":[{"name":"governanceai","email":"gustavo@gobiernoia.cl"}],"description":"Official Argorix SDK for Node.js and TypeScript runtimes","homepage":"https://github.com/argorixlabs/argorix-node#readme","keywords":["argorix","ai-governance","governance","ai","guardrails","agents","security","sdk"],"repository":{"type":"git","url":"git+https://github.com/argorixlabs/argorix-node.git"},"author":{"name":"Argorix"},"bugs":{"url":"https://github.com/argorixlabs/argorix-node/issues"},"license":"MIT","readme":"# Argorix SDK for JavaScript / TypeScript\n\nSDK oficial para Node.js, Next.js y TypeScript sobre el **Argorix Guardrails Runtime**.\n\n```bash\nnpm install @argorix/sdk\n```\n\n> **Rebranding.** Este paquete se llamaba `@governanceai/sdk`. Ese nombre sigue publicado\n> como shim de compatibilidad (depende de `@argorix/sdk` y lo reexporta), pero ya no\n> recibe features. Ver [Migración](#migración-desde-governanceaisdk).\n\nRequiere Node 18+ (usa `fetch` global). Funciona también en runtimes edge con `fetch` y\n`ReadableStream`.\n\n## API cubierta\n\n### Guardrails clásicos — `ArgorixClient`\n\n| Endpoint | Método |\n| --- | --- |\n| `POST /v1/guardrails/install` | `install()` |\n| `POST /v1/guardrails/heartbeat` | `heartbeat()` |\n| `POST /v1/guardrails/evaluate` | `evaluate()` (alias: `apply()`) |\n| `POST /v1/guardrails/evaluate/stream` | `evaluateStream()`, `evaluateStreamedDecision()` |\n| `POST /v1/guardrails/events` | `recordEvent()`, `reportRedteamProbe()` |\n\n### Guardrails de agentes — `ArgorixAgentsClient`\n\n| Endpoint | Método |\n| --- | --- |\n| `POST /v1/agent-guardrails/runtime/agents/init` | `initAgent()` |\n| `GET /v1/agent-guardrails/runtime/agents/{agent_name}/controls` | `listAgentControls()` |\n| `POST /v1/agent-guardrails/runtime/evaluate` | `evaluate()` |\n| `POST /v1/agent-guardrails/runtime/evaluate/stream` | `evaluateStream()`, `evaluateStreamedResult()` |\n| `POST /v1/agent-guardrails/runtime/events` | `recordEvent()` |\n\n`baseUrl` acepta tanto `https://api.argorix.com` como `https://api.argorix.com/v1`: el\nsufijo `/v1` se normaliza para no duplicar el prefijo.\n\n## Autenticación\n\n- `appNumber` en el body de cada request\n- `Authorization: Bearer <APP_API_KEY>` en cada header\n\n## Quick start\n\n```ts\nimport { ArgorixClient, ArgorixError } from \"@argorix/sdk\";\n\nconst client = new ArgorixClient({\n  baseUrl: \"https://api.argorix.com\",\n  appNumber: 123456,\n  appApiKey: \"ax_live_replace_me\",\n  timeoutMs: 10_000,\n  maxRetries: 2,\n});\n\ntry {\n  const state = await client.install({ mode: \"monitor\", metadata: { environment: \"production\" } });\n  console.log(state.mode, state.selectedValidators);\n\n  const decision = await client.evaluate(\"Summarize this support ticket\", { stage: \"input\" });\n  if (decision.blocked) {\n    throw new Error(`Blocked: ${decision.findings.map((f) => f.rule_id).join(\", \")}`);\n  }\n} catch (error) {\n  if (error instanceof ArgorixError) {\n    console.error(error.statusCode, error.message, error.responseBody);\n  }\n}\n```\n\n### Configuración por entorno\n\n```ts\nconst client = ArgorixClient.fromEnv();\n```\n\n| Variable | Uso | Fallback legado |\n| --- | --- | --- |\n| `ARGORIX_API_URL` | `baseUrl` | `ARGORIX_BASE_URL`, `GOVERNANCE_AI_URL` |\n| `ARGORIX_APP_NUMBER` | `appNumber` | `APP_NUMBER` |\n| `ARGORIX_APP_API_KEY` | `appApiKey` | `APP_API_KEY` |\n| `ARGORIX_POLICY_ID` | `defaultPolicyId` | — |\n\nLas opciones explícitas ganan sobre el entorno. En runtimes sin `process`, pasa los\nvalores a mano.\n\n## Flujo runtime clásico\n\n```ts\nconst inbound = await client.evaluate(userPrompt, { stage: \"input\" });\nif (inbound.blocked) {\n  return new Response(\"blocked\", { status: 403 });\n}\n\nconst reply = await llm.invoke(userPrompt);\n\nconst outbound = await client.evaluate(reply, { stage: \"output\" });\nreturn new Response(outbound.outputText);\n```\n\n### Tool calls\n\n```ts\nconst decision = await client.evaluate(\"Open the customer export\", {\n  stage: \"tool\",\n  toolCalls: [{ toolName: \"browser.fetch\", url: \"https://example.com/private-report\" }],\n});\n```\n\n## Streaming (SSE)\n\n```ts\nfor await (const event of client.evaluateStream(userPrompt, { stage: \"input\" })) {\n  if (event.event === \"result\") {\n    console.log(\"allowed:\", event.data.allowed);\n  } else if (event.event === \"error\") {\n    console.error(\"guardrail error:\", event.data.detail);\n  }\n}\n```\n\nSi solo te interesa la decisión final:\n\n```ts\nconst decision = await client.evaluateStreamedDecision(userPrompt, { stage: \"input\" });\n```\n\nRechaza con `ArgorixError` si el servidor emite `error` o si el stream cierra sin\n`result`. El stream es perezoso: no se envía nada hasta que empiezas a iterar. Los\nreintentos cubren la conexión y el status inicial; una vez abierto el stream no se\nreintenta.\n\n## Agent guardrails\n\n```ts\nimport { ArgorixAgentsClient } from \"@argorix/sdk\";\n\nconst agents = new ArgorixAgentsClient({ baseUrl, appNumber, appApiKey });\n\nawait agents.initAgent({\n  agentName: \"support_bot\",\n  steps: [{ type: \"tool\", name: \"lookup_booking\" }],\n});\n\nconst evaluation = await agents.evaluate({\n  agentName: \"support_bot\",\n  stage: \"pre\",\n  step: { type: \"tool\", name: \"lookup_booking\", input: { email: \"a@b.com\" } },\n});\n\nif (evaluation.denied) {\n  throw new Error(evaluation.matches[0].message ?? \"denied\");\n}\n```\n\nVer [`examples/agent-guardrails.ts`](./examples/agent-guardrails.ts).\n\n## Tipos de respuesta\n\n`GuardrailsDecision`: `allowed`, `blocked`, `outputText`, `mode`, `findings`,\n`evaluations`, `selectedValidators`, `effectiveScope`, `guardrailsConfig`,\n`guardrailsEngine`, `stage`, `applicationId`, `appNumber`, `repository`, `serverTime`,\n`raw`.\n\n`GuardrailsState`: `applicationId`, `appNumber`, `repository`, `installationConnected`,\n`guardrailsConfig`, `effectiveScope`, `selectedValidators`, `mode`, `enabled`,\n`serverTime`, `raw`.\n\n`AgentEvaluation`: `overallDecision`, `allowed`, `denied`, `requiresSteering`,\n`confidence`, `evaluatedControls`, `matches`, `nonMatches`, `errors`, `raw`.\n\n`ControlMatch`: `controlId`, `controlName`, `action`, `evaluatorName`, `selectorPath`,\n`matched`, `confidence`, `message`, `error`, `metadata`, `steeringMessage`.\n\nTodos exponen `raw` con el payload JSON sin tocar, así que campos nuevos del control\nplane quedan accesibles sin actualizar el SDK. El helper `highestSeverity(findings)`\ndevuelve la severidad máxima.\n\n## Telemetría\n\n`ArgorixClient` acumula `requests_total`, `blocked_total` y `avg_latency_ms`, y los\nadjunta a `evaluate()` y `heartbeat()` salvo que pases `includeTelemetry: false`.\n\n```ts\nconsole.log(client.telemetry);\nclient.resetTelemetry();\n```\n\n## Errores, timeout y retry\n\nAmbos clientes aceptan `timeoutMs`, `maxRetries`, `retryBackoffMs` y\n`retryStatusCodes`. Los fallos lanzan `ArgorixError` con `statusCode` y `responseBody`.\nSe reintentan errores de red y respuestas `408`, `429`, `500`, `502`, `503`, `504` con\nbackoff exponencial.\n\n## Migración desde `@governanceai/sdk`\n\n```bash\nnpm uninstall @governanceai/sdk\nnpm install @argorix/sdk\n```\n\n| Antes | Ahora |\n| --- | --- |\n| `GovernanceAIClient` | `ArgorixClient` |\n| `GovernanceGuardrailsClient` | `ArgorixClient` |\n| `GovernanceAIError` | `ArgorixError` |\n| `client.apply(...)` | `client.evaluate(...)` (`apply` sigue funcionando) |\n\nLos nombres viejos siguen exportados como alias, así que cambiar el especificador de\nimport alcanza para arrancar. Cambios de comportamiento a revisar:\n\n- `install()` y `heartbeat()` devuelven `GuardrailsState` en vez de un objeto sin tipar.\n  El payload original está en `state.raw`.\n- `GuardrailsDecision` gana `blocked`, `evaluations`, `guardrailsConfig`,\n  `guardrailsEngine`, `applicationId`, `appNumber`, `repository`, `serverTime` y `raw`.\n\n## Desarrollo\n\n```bash\nnpm install\nnpm run build\nnpm test\n```\n\n## Semver y changelog\n\n- Versión actual: `0.2.0`\n- Historial: [`CHANGELOG.md`](./CHANGELOG.md)\n- Licencia: [`LICENSE`](./LICENSE)\n\n## Referencias\n\n- [`sdk/README.md`](../README.md)\n- [`sdk/python/README.md`](../python/README.md)\n- [`sdk/python-agents/README.md`](../python-agents/README.md)\n- [`examples/basic.ts`](./examples/basic.ts)\n- [`examples/next-route-handler.ts`](./examples/next-route-handler.ts)\n- [`examples/agent-guardrails.ts`](./examples/agent-guardrails.ts)\n","readmeFilename":"README.md","_rev":"1-1e4d2b57f31fef881d0b71739a2213be"}