AEGIS SDK — TypeScript (aegis-platform-sdk)

Typed TypeScript client for the AEGIS HTTPS API (Safe-Core Technologies). Mirrors the Python SDK (aegis-platform-sdk on PyPI) — same resource layout, same error hierarchy, same auth model.

• Zero runtime dependencies — platform fetch (Node ≥ 18, browsers, edge runtimes).
• ESM + CJS with full .d.ts types.
• Same surface as Python: client.iam.users.list() ⇄ client.iam.users.list().

Install

npm install aegis-platform-sdk

Programmatic auth (OSDK Application)

Issue a token in the AEGIS UI: Governance → OSDK Applications. The plaintext appears once; stash it like any other secret.

import { AegisClient } from "aegis-platform-sdk";

const client = new AegisClient({
  baseUrl: "https://aegis.example.com",
  token: "osdk_xK9pQzR2L8mYvN4w...",
});

const me = await client.auth.me();
console.log(me.username, me.permissions);

Env fallbacks (AEGIS_API_URL, AEGIS_TOKEN) let you construct new AegisClient() with no arguments in server-side code.

Human auth (login)

const client = new AegisClient({ baseUrl: "https://aegis.example.com" });
await client.auth.login("operador", "senha", { totpCode: "123456" }); // JWT attaches automatically
const tree = await client.iam.nav.tree();

Error handling

import { AegisAPIError, PermissionDeniedError } from "aegis-platform-sdk";

try {
  await client.iam.users.list();
} catch (err) {
  if (err instanceof PermissionDeniedError) console.error("missing perm:", err.detail);
  else if (err instanceof AegisAPIError) console.error(err.statusCode, err.detail, err.payload);
}

401 → AuthError · 403 → PermissionDeniedError · 404 → NotFoundError · everything else → AegisAPIError.

Resources

| Resource | Surface | |----------|---------| | client.auth | login, me, enableDevMode | | client.iam | users, roles, groups (CRUD + members), permissions, nav.tree | | client.osdk | OSDK token lifecycle: list/get/create/rotate/revoke | | client.operator.tasks | NL task queue: list/get/create/cancel/retry/reprioritize | | client.ontology | objects (CRUD, bulk, links, history, timeseries), graph.expand, explorer (histogram/timeline), objectTypes, linkTypes, osdkManifest/osdkFunctions/osdkGenerate | | client.aip | flows, agents, models (catalog/defaults), budget | | client.functions | Code Functions: CRUD, invoke, tests, publish, versions, pull requests + CI | | client.codeRepositories | repos, branches, CI, merge | | client.datasets | datasets, branches, transactions (begin/commit/abort), merges, classification, markings | | client.geo / mapTemplates / media / docs / pages / dossier / timeseries | reading & consumption surfaces | | client.alerts / alarms / events / connectors / pipelines / chat / notepad | operational surfaces | | client.lineage / accessAudit / markings / resourceMarkings / propertyMarkings / rowPolicies / erasure / retention / guestTokens | governance surfaces | | client.workshop / compute / inference / codegen / correlation / situational / merge | platform surfaces | | client.atlas / briefing / cctv / edge / video / comunicados / campaign | domain surfaces | | client.forms / appShell / groups / projects / organizations / spaces / solutions / workspaces / workspaceUpdates / marketplace | collaboration & apps | | client.platformV22 … client.platformV26 | versioned platform surfaces | | client.stream(path) | SSE async iterator (task progress, AIP streaming) | | NAV_PERMISSIONS / CAPABILITY_PERMISSIONS / APPLICATIONS | static permission + OSDK app catalogs |

Anything not wrapped yet is reachable via the escape hatch:

const rows = await client.request("GET", "/entities/aggregate", {
  params: { property: "kind" },
});

Hardening (1.0)

• Typed results: client.geo.nodes<GeoNodesOut>() — every direct method takes a type parameter (default Json).
• Retry/backoff: transient failures (network, timeout, 429/5xx-gateway) retried on GET/HEAD with jittered exponential backoff — tune via retry: { retries, baseDelayMs, maxDelayMs, retryPost }.
• Auto JWT refresh: after auth.login, a 401 rotates the refresh token and retries once, transparently.

OSDK codegen CLI

npx aegis-osdk generate --lang typescript   # typed module from the LIVE ontology
npx aegis-osdk manifest                     # raw manifest JSON

Auth via AEGIS_API_URL/AEGIS_TOKEN or --base-url/--token. Wire the generated module with asOsdkClient(client).

Proxy mode (cookie-auth frontends)

const aegis = new AegisClient({
  baseUrl: "/api", // relative — resolved against the browser origin
  fetchInit: { credentials: "include", cache: "no-store" },
});

Claude Code skill

The npm package ships a Claude Code skill under skills/aegis-sdk/. In an external project that consumes this SDK, copy it into the project's .claude/skills/ so Claude Code knows the SDK surface and conventions:

mkdir -p .claude/skills
cp -r node_modules/aegis-platform-sdk/skills/aegis-sdk .claude/skills/aegis-sdk

Development

npm install
npm run typecheck && npm test && npm run build

Releases: see PUBLISHING.md. Roadmap and extension plan: docs/PLAN.md.

License

Proprietary — Safe-Core Technologies. See LICENSE.