aegis-platform-sdk 0.1.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aegis-platform-sdk",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "AEGIS Ontology SDK — typed TypeScript client for the AEGIS HTTPS API (Safe-Core Technologies)",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Safe-Core Technologies",
@@ -8,6 +8,9 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "aegis-osdk": "./dist/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -31,6 +34,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
+    "docs": "typedoc src/index.ts --out docs/api",
     "prepublishOnly": "npm run typecheck && npm run test && npm run build"
   },
   "repository": {
@@ -47,6 +51,7 @@
   "devDependencies": {
     "@types/node": "^22.10.0",
     "tsup": "^8.3.5",
+    "typedoc": "^0.28.20",
     "typescript": "^5.7.2",
     "vitest": "^3.0.0"
   }

package/skills/aegis-sdk/SKILL.md

@@ -48,7 +48,41 @@ const client = new AegisClient({
 Server-side only for secrets: in browser apps, never embed an `osdk_…`
 token — proxy through your backend or use the login flow.
 
-## Resource surface (v0.1)
+**Proxy mode** (cookie-auth frontends — e.g. a Next.js app whose `/api/*`
+routes inject the Bearer from an httpOnly cookie): relative `baseUrl` +
+`fetchInit`, no token in JS:
+
+```ts
+export const aegis = new AegisClient({
+  baseUrl: "/api",
+  fetchInit: { credentials: "include", cache: "no-store" },
+});
+```
+
+## OSDK codegen (typed ontology objects)
+
+`npx aegis-osdk generate --lang typescript` (env `AEGIS_API_URL`/`AEGIS_TOKEN`
+or `--base-url`/`--token`) writes a typed module from the LIVE ontology —
+one interface per Object Type + a `Functions` class. Wire it with
+`asOsdkClient(client)`. Regenerate when the ontology contract changes
+(the file header carries the contract version). `npx aegis-osdk manifest`
+dumps the raw manifest JSON.
+
+## Hardening (v1.0)
+
+- **Typed results, no casts**: every direct resource method takes a type
+  parameter — `client.geo.nodes<GeoNodesOut>(opts)`, `client.ontology.objects.list<Camera>("Camera")`.
+  Default `T = Json` when omitted.
+- **Retry**: transient failures (network/timeout/429/502/503/504) auto-retry
+  with backoff on GET/HEAD (2 retries default). Tune via `retry` option;
+  `{retries: 0}` disables; `retryPost: true` extends to writes (only when
+  the endpoint is idempotent!).
+- **JWT refresh**: after `auth.login`, a 401 transparently rotates the
+  refresh token (`POST /auth/refresh`) and retries once — no manual
+  re-login loops needed. OSDK tokens (`osdk_…`) don't refresh — rotate via
+  `client.osdk.rotate`.
+
+## Resource surface (v1.0 — full parity with the Python SDK)
 
 - `client.auth` — `login`, `me` (WhoAmI: roles/permissions/tenant), `enableDevMode`
 - `client.iam` — `users.list/get`, `roles.list/get`, `groups` CRUD + members, `permissions.list(resource?)`, `nav.tree(asRoleId?)`
@@ -63,9 +97,26 @@ token — proxy through your backend or use the login flow.
 - `client.functions` — Code Functions: CRUD, `invoke(slug, inputs)`, tests, `publish`, `versions`, pull-request lifecycle + CI
 - `client.codeRepositories` — repos, branches, CI, merge
 - `client.datasets` — `list/get/sample`, branches, transactions (`beginTransaction(name, "SNAPSHOT"|"APPEND"|"UPDATE"|"DELETE")` → `commitTransaction`/`abortTransaction`), `mergeFastForward`/`mergeThreeWay`, classification, markings
+- **Reading**: `client.geo` (nodes/nodeTypes/sources/edges/zones), `client.mapTemplates` (list/get/create/instantiate/exportSvg), `client.media` (sets + item metadata), `client.docs` (tree/read), `client.pages` (registry CRUD/publish), `client.dossier` (startGeneric/startComposite → poll `get`), `client.timeseries` (charts + render)
+- **Operational**: `client.alerts` (`feeds`/`watches`/`geofences`/`shares`/`routes` incl. silence/`inbox` + `escalate`/`channels`), `client.alarms` (threshold rules), `client.events` (pipelineStatus + DLQ retry/purge), `client.connectors` (list/patch/register/test/run/skillCatalog), `client.pipelines` (CRUD/build/runs/previews), `client.chat` (channels/messages), `client.notepad`
+- **Governance**: `client.lineage` (graph/events), `client.accessAudit`, `client.markings` (+`categories`, eligibility), `client.resourceMarkings`, `client.propertyMarkings`, `client.rowPolicies`, `client.erasure` (ALWAYS `preview` before `forget`; `forget` needs `confirm:true`), `client.retention`, `client.guestTokens` (issue returns plaintext once)
+- **Platform**: `client.workshop` (`briefings`/`dossiers`/`covs`/`widgetCatalog` — no apps/widgets CRUD, by design), `client.compute` (`providers`/`releases`/selectModel/visionCount + `control(providerId)` scoped plane), `client.inference` (complete/chat/chatWithRag/models/auditTrail — server-audited LLM), `client.codegen`, `client.correlation` (quickLinks/startChain→getChain→saveChain), `client.situational` (nearby/correlate/cut), `client.merge` (suggestTarget/preview/apply)
+- **Domain**: `client.atlas` (layers/KML/evaluator), `client.briefing`, `client.cctv` (streams/detections/recordings/exports/bookmarks/gcps/hotlist; `recordingsPlaylist` returns raw m3u8 text), `client.edge` (pairing codes/fleet version), `client.video`, `client.comunicados`, `client.campaign.briefing`
+- **Collaboration**: `client.forms` (governed submissions), `client.appShell` (banner/footer/userMenu/sidenav/homepage get/put), `client.groups`, `client.projects` (move + `constraints`), `client.organizations`, `client.spaces`, `client.solutions` (design→materialize→teardown; marketplace listings), `client.workspaces` (+`versions`, navigation, promotions, kiosk), `client.workspaceUpdates`, `client.marketplace` (storefront/install wizard)
+- **Versioned surfaces** (`client.platformV22`…`platformV26`): action-log/quiver/usage (v22); aip-logic/action-types/assist/automate/health/contour/vertex/repos/object-sets/styles incl. `styles.uploadLogo` multipart (v23); rules/checkpoints/expectations/change-requests/scenarios/searchAround/aggregateObjectSet (v24); machinery/branch-protection/kiosk/analyst/dataset rollback/freshness/code-scan/evals (v25); promotions/object-views/capacity/listeners/scanner/monitoring/health-checks/insight/peers/run-history (v26)
+- **SSE streaming**: `for await (const ev of client.stream(path, {params, json, signal}))` — yields `{event, data, id?, retry?}`; pass `signal` to cancel (no default timeout). `parseSseStream` is exported for custom transports.
+- **Static catalogs (no HTTP)**: `NAV_PERMISSIONS`/`CAPABILITY_PERMISSIONS`/`ALL_PERMISSIONS` + `PermissionKey` union + `isSystemPermission()` — reference permission keys statically, never hardcode strings; `APPLICATIONS`/`applicationBySlug()` — OSDK app permission scopes for `osdk.create`.
+- Client-side helpers (no HTTP): `maxLevel`, `validateInvariant`, `CLASSIFICATION_RANK` — validate the classification invariant before writes.
 
 ## Conventions
 
+- **Declare request-body shapes with `type`, not `interface`**: SDK input
+  params are typed `Json` (`Record<string, unknown>`); TS gives object
+  `type` aliases an implicit index signature (assignable to `Json`) but
+  NOT interfaces — an `interface` argument fails with "Index signature
+  for type 'string' is missing". Result shapes can be either (they flow
+  through the generic, not assignability).
+
 - Wire fields are `snake_case` (backend-shaped); SDK method names are
   `camelCase`. Request bodies you build use snake_case keys (e.g.
   `{ prompt_text, project_id }`).