aegis-platform-sdk 1.0.0 → 1.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +136 -78
- package/README.md +144 -143
- package/dist/cli.js +191 -1
- package/dist/cli.js.map +1 -1
- package/dist/index.cjs +193 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +304 -3
- package/dist/index.d.ts +304 -3
- package/dist/index.js +192 -1
- package/dist/index.js.map +1 -1
- package/package.json +58 -58
- package/skills/aegis-sdk/SKILL.md +140 -139
package/CHANGELOG.md
CHANGED
|
@@ -1,78 +1,136 @@
|
|
|
1
|
-
# Changelog
|
|
2
|
-
|
|
3
|
-
## 1.
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
-
|
|
78
|
-
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 1.3.1 — 2026-07-31
|
|
4
|
+
|
|
5
|
+
Docs only — no API change.
|
|
6
|
+
|
|
7
|
+
- **`skills/aegis-sdk/SKILL.md`** (which ships inside the package, and is what
|
|
8
|
+
Claude Code reads to use the SDK) still described the pre-1.3.0 surface, so
|
|
9
|
+
`alerts.setChannel`/`deleteChannel` and `edge.createPairingCode({grants})`
|
|
10
|
+
were invisible to anyone driving the SDK through the skill.
|
|
11
|
+
|
|
12
|
+
## 1.3.0 — 2026-07-31
|
|
13
|
+
|
|
14
|
+
Two operator gestures born with the desk app. Additive; no breaking changes.
|
|
15
|
+
Parity with the Python SDK (`edge.create_pairing_code(grants=…)`,
|
|
16
|
+
`alerts.set_channel` / `delete_channel`).
|
|
17
|
+
|
|
18
|
+
- **`client.edge.createPairingCode({ grants })`** — a pairing code can now
|
|
19
|
+
**grant gestures** to whichever device redeems it. Empty — the default — is
|
|
20
|
+
**read only**: least privilege, and granting has to be a choice. The grant
|
|
21
|
+
travels from the code to the node and dies with it on `revoke`. Even when
|
|
22
|
+
granted, the device never receives the gesture's ADDRESS
|
|
23
|
+
(`agent_id`/`skill_key`): it sends the verb and the server routes it.
|
|
24
|
+
- **`client.alerts.setChannel(ref, config)` / `deleteChannel(ref)`** —
|
|
25
|
+
`PUT`/`DELETE /alerts/channels/{ref}`, pointing a delivery channel at its
|
|
26
|
+
destination. Exists so this is a GESTURE: before it, sending alerts to the
|
|
27
|
+
team's Discord meant editing the tenant's JSONB in the database. Audited
|
|
28
|
+
(`alert_channel.configured` / `.removed`). Reads return the config
|
|
29
|
+
**masked** — a webhook URL is the credential.
|
|
30
|
+
- New `discord` channel in the horizontal messaging registry: shows up in
|
|
31
|
+
`client.alerts.channels()` on its own, no contract change.
|
|
32
|
+
|
|
33
|
+
## 1.2.0 — 2026-07-09
|
|
34
|
+
|
|
35
|
+
New method on `publicGuest`. No breaking changes.
|
|
36
|
+
|
|
37
|
+
- **`client.publicGuest.position(token)`** — `GET /public/v1/guest/{token}/position`.
|
|
38
|
+
The resident-side read of a visitor's live location: the operator issues the
|
|
39
|
+
resident's token with `geo.live_ref` = the visitor's guest-token id, and this
|
|
40
|
+
returns `{available, lat, lng, ts, inside_fence, arrived, deviated,
|
|
41
|
+
distance_to_target_m, visit_status}`. Least-privilege — the resident sees only
|
|
42
|
+
that one visit. Poll it (no push; the bus→SSE bridge is a later wave).
|
|
43
|
+
Dogfooded by the Safe-Tag `residentmap` SPA.
|
|
44
|
+
- 2 new tests (194 total).
|
|
45
|
+
|
|
46
|
+
## 1.1.0 — 2026-07-09
|
|
47
|
+
|
|
48
|
+
New resource. No breaking changes.
|
|
49
|
+
|
|
50
|
+
- **`client.publicGuest`** — the consumer side of a public guest token
|
|
51
|
+
(`/public/v1/guest/{token}/*`), the counterpart to `client.guestTokens`
|
|
52
|
+
(operator issue/list/revoke). 8 request methods (`menu`, `fix`, `invoke`,
|
|
53
|
+
`document`, `queryObjectSet`, `documentNode`, `page`, `evaluatePage`) plus
|
|
54
|
+
`mediaUrl(token, key)` — a string builder for `<img src>` (media bytes are
|
|
55
|
+
binary; the JSON transport doesn't fetch them). Anonymous by design: build
|
|
56
|
+
`new AegisClient({ baseUrl })` with no token; the token travels in the path.
|
|
57
|
+
Dogfooded by the Safe-Tag SPAs (livetracker/residentmap repointed off
|
|
58
|
+
Firebase onto AEGIS).
|
|
59
|
+
- 15 new tests (192 total).
|
|
60
|
+
|
|
61
|
+
## 1.0.0 — 2026-07-08
|
|
62
|
+
|
|
63
|
+
F5 — Hardening. No breaking API changes; new default behaviors noted below.
|
|
64
|
+
|
|
65
|
+
- **Retry/backoff** (new default behavior): transient failures (network
|
|
66
|
+
errors, timeouts, 429/502/503/504) are retried with exponential backoff +
|
|
67
|
+
full jitter — GET/HEAD only, 2 retries. Configure via `retry` option
|
|
68
|
+
(`{retries, baseDelayMs, maxDelayMs, retryPost}`); `{retries: 0}` disables.
|
|
69
|
+
- **Automatic JWT refresh**: `auth.login` now captures the refresh token; on
|
|
70
|
+
a 401 the client rotates it via `POST /auth/refresh` (single-flight) and
|
|
71
|
+
retries the request once. A rejected refresh clears the token (no loops).
|
|
72
|
+
Seed manually via `refreshToken` option / `setRefreshToken()`; explicit
|
|
73
|
+
`auth.refresh(token)` added.
|
|
74
|
+
- **Per-method generics**: 510 resource methods now accept a type parameter —
|
|
75
|
+
`client.geo.nodes<GeoNodesOut>()` instead of `as unknown as` casts
|
|
76
|
+
(`T = Json` default keeps all existing code compiling).
|
|
77
|
+
- All resource classes and their option types are exported from the package
|
|
78
|
+
root (typed params in consumer code + full typedoc coverage).
|
|
79
|
+
- `npm run docs` (typedoc) + `examples/` (OSDK-token server usage, browser
|
|
80
|
+
proxy mode with SSE).
|
|
81
|
+
- 12 new tests (177 total).
|
|
82
|
+
|
|
83
|
+
## 0.4.0 — 2026-07-08
|
|
84
|
+
|
|
85
|
+
F3 (OSDK codegen CLI) + F4 groundwork (proxy-mode, dogfooded in security-app).
|
|
86
|
+
|
|
87
|
+
- **`aegis-osdk` CLI** (`npx aegis-osdk generate|manifest`): fetches
|
|
88
|
+
`GET /ontology/osdk/generate?lang=typescript|python` from a live deployment
|
|
89
|
+
and writes the typed module; prints the contract version. Proven live against
|
|
90
|
+
a real AEGIS backend (generated module passes strict `tsc`).
|
|
91
|
+
- **`asOsdkClient(client)`** adapter — bridges `AegisClient` to the `OSDKClient`
|
|
92
|
+
`{get, post}` contract expected by generated modules.
|
|
93
|
+
- **Proxy mode** (cookie-auth frontends like security-app): relative `baseUrl`
|
|
94
|
+
(e.g. `/api`, resolved against the browser origin) + `fetchInit` option
|
|
95
|
+
(`{credentials: "include", cache: "no-store"}` merged into every request,
|
|
96
|
+
including `stream()`).
|
|
97
|
+
- `geo.referenceLayers()` / `geo.referenceLayer(id, {uf, municipio})` — gap
|
|
98
|
+
found while dogfooding (endpoints existed in the backend but in neither SDK).
|
|
99
|
+
- 12 new tests (165 total).
|
|
100
|
+
|
|
101
|
+
## 0.3.0 — 2026-07-08
|
|
102
|
+
|
|
103
|
+
F1.5 (full parity closure) + F2 (SSE streaming). **Every Python SDK module now has a TS mirror.**
|
|
104
|
+
|
|
105
|
+
- **Domain**: `atlas` (layers + KML import + evaluator), `briefing`, `cctv` (streams/detections/recordings/exports/bookmarks/GCPs/LPR hotlist, raw m3u8 playlist), `edge` (pairing/fleet version), `video` (streams/detections/tags/soak/exports), `comunicados`, `campaign.briefing`.
|
|
106
|
+
- **Collaboration/apps**: `forms`, `appShell` (banner/footer/user-menu/sidenav/homepage), `groups` (alias of `iam.groups`), `projects` (move + constraints), `organizations`, `spaces`, `solutions` (design/materialize/diagrams/teardown/marketplace), `workspaces` (+versions/navigation/promotions/kiosk), `workspaceUpdates`, `marketplace` (v23 storefront + install wizard).
|
|
107
|
+
- **Versioned surfaces**: `platformV22` (action-log, notepad templates, quiver, variable transforms, usage), `platformV23` (aip-logic, action-types, assist, pipeline, quiver, connectors, automate, health, contour, vertex, repos, object-sets, carbon, styles incl. multipart logo upload), `platformV24` (flat: rules, checkpoints, expectations, change requests, scenarios, object-set search-around/aggregate, …), `platformV25` (machinery, branch protection, kiosk, analyst threads, dataset rollback/snapshot/limits, freshness, code scan, evals), `platformV26` (promotions, object/core views, capacity, listeners, scanner, monitoring, health checks, media versions, insight, peers, run history).
|
|
108
|
+
- **Static catalogs**: full IAM permission catalog (`NAV_PERMISSIONS`/`CAPABILITY_PERMISSIONS`/`PermissionKey` union, `isSystemPermission`) and the OSDK `APPLICATIONS` catalog (7 apps) with `validateApplication`.
|
|
109
|
+
- **F2 — SSE**: `client.stream(path)` async iterator + spec-compliant `parseSseStream` (chunk-boundary safe, CRLF, comments, sticky id/retry); errors map through the exception hierarchy.
|
|
110
|
+
- Transport: multipart `form` option; array query params (repeated keys).
|
|
111
|
+
- 60 new tests (153 total).
|
|
112
|
+
|
|
113
|
+
## 0.2.0 — 2026-07-08
|
|
114
|
+
|
|
115
|
+
F1 — resource parity, 27 new client surfaces (mirror of Python SDK v0.10.0):
|
|
116
|
+
|
|
117
|
+
- **Reading**: `geo`, `mapTemplates` (incl. `exportSvg` raw-SVG), `media`, `docs`, `pages`, `dossier` (async start → poll), `timeseries`.
|
|
118
|
+
- **Operational**: `alerts` (feeds/watches/geofences/shares/routes/inbox + escalate/channels), `alarms`, `events` (pipeline + DLQ, ids-XOR-all guard), `connectors` (incl. two-step `register`), `pipelines`, `chat`, `notepad`.
|
|
119
|
+
- **Governance**: `lineage`, `accessAudit`, `markings` (+categories/eligibility), `resourceMarkings`, `propertyMarkings`, `rowPolicies`, `erasure` (preview/forget), `retention`, `guestTokens`.
|
|
120
|
+
- **Platform**: `workshop` (briefings/dossiers/covs/widgetCatalog), `compute` (providers/releases/vision + per-provider `control()` plane), `inference` (complete/chat/chatWithRag/models/collections/auditTrail), `codegen`, `correlation`, `situational`, `merge`.
|
|
121
|
+
- Client-side classification helpers: `maxLevel`, `validateInvariant`, `ClassificationInvariantViolation` (mirror of `aegis.classification`).
|
|
122
|
+
- 64 new tests (93 total).
|
|
123
|
+
|
|
124
|
+
Deliberate deviations from Python (documented in `docs/PLAN.md`): the stdout-based
|
|
125
|
+
`aegis.maps` builder is sandbox-IDE-only and was not ported (only `MapTemplates` HTTP
|
|
126
|
+
surface); `inference` is a client resource here instead of a functional namespace.
|
|
127
|
+
|
|
128
|
+
## 0.1.0 — 2026-07-08
|
|
129
|
+
|
|
130
|
+
First cut of the TypeScript SDK, mirroring `aegis-platform-sdk` (Python) v0.10.0.
|
|
131
|
+
|
|
132
|
+
- `AegisClient` — fetch-based transport, zero runtime dependencies, ESM + CJS.
|
|
133
|
+
- Auth: `login` (JWT attach), `me`, `enableDevMode`; env fallbacks `AEGIS_API_URL` / `AEGIS_TOKEN`.
|
|
134
|
+
- Error hierarchy: `AegisAPIError`, `AuthError` (401), `PermissionDeniedError` (403), `NotFoundError` (404).
|
|
135
|
+
- Resources: `iam` (users/roles/groups/permissions/nav), `osdk` (token lifecycle), `operator.tasks`, `ontology` (objects, graph, explorer, object-types, link-types, OSDK manifest/codegen), `aip` (flows, agents, models, budget), `functions` + `codeRepositories` (Code Functions v26), `datasets` (branches, transactions, classification, markings).
|
|
136
|
+
- Generic `client.request(method, path, opts)` escape hatch for unwrapped endpoints.
|
package/README.md
CHANGED
|
@@ -1,143 +1,144 @@
|
|
|
1
|
-
# AEGIS SDK — TypeScript (`aegis-platform-sdk`)
|
|
2
|
-
|
|
3
|
-
Typed TypeScript client for the AEGIS HTTPS API (Safe-Core Technologies).
|
|
4
|
-
Mirrors the Python SDK ([`aegis-platform-sdk` on PyPI](https://pypi.org/project/aegis-platform-sdk/))
|
|
5
|
-
— same resource layout, same error hierarchy, same auth model.
|
|
6
|
-
|
|
7
|
-
- **Zero runtime dependencies** — platform `fetch` (Node ≥ 18, browsers, edge runtimes).
|
|
8
|
-
- **ESM + CJS** with full `.d.ts` types.
|
|
9
|
-
- **Same surface as Python**: `client.iam.users.list()` ⇄ `client.iam.users.list()`.
|
|
10
|
-
|
|
11
|
-
## Install
|
|
12
|
-
|
|
13
|
-
```bash
|
|
14
|
-
npm install aegis-platform-sdk
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
## Programmatic auth (OSDK Application)
|
|
18
|
-
|
|
19
|
-
Issue a token in the AEGIS UI: **Governance → OSDK Applications**. The
|
|
20
|
-
plaintext appears once; stash it like any other secret.
|
|
21
|
-
|
|
22
|
-
```ts
|
|
23
|
-
import { AegisClient } from "aegis-platform-sdk";
|
|
24
|
-
|
|
25
|
-
const client = new AegisClient({
|
|
26
|
-
baseUrl: "https://aegis.example.com",
|
|
27
|
-
token: "osdk_xK9pQzR2L8mYvN4w...",
|
|
28
|
-
});
|
|
29
|
-
|
|
30
|
-
const me = await client.auth.me();
|
|
31
|
-
console.log(me.username, me.permissions);
|
|
32
|
-
```
|
|
33
|
-
|
|
34
|
-
Env fallbacks (`AEGIS_API_URL`, `AEGIS_TOKEN`) let you construct
|
|
35
|
-
`new AegisClient()` with no arguments in server-side code.
|
|
36
|
-
|
|
37
|
-
## Human auth (login)
|
|
38
|
-
|
|
39
|
-
```ts
|
|
40
|
-
const client = new AegisClient({ baseUrl: "https://aegis.example.com" });
|
|
41
|
-
await client.auth.login("operador", "senha", { totpCode: "123456" }); // JWT attaches automatically
|
|
42
|
-
const tree = await client.iam.nav.tree();
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
## Error handling
|
|
46
|
-
|
|
47
|
-
```ts
|
|
48
|
-
import { AegisAPIError, PermissionDeniedError } from "aegis-platform-sdk";
|
|
49
|
-
|
|
50
|
-
try {
|
|
51
|
-
await client.iam.users.list();
|
|
52
|
-
} catch (err) {
|
|
53
|
-
if (err instanceof PermissionDeniedError) console.error("missing perm:", err.detail);
|
|
54
|
-
else if (err instanceof AegisAPIError) console.error(err.statusCode, err.detail, err.payload);
|
|
55
|
-
}
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
401 → `AuthError` · 403 → `PermissionDeniedError` · 404 → `NotFoundError` · everything else → `AegisAPIError`.
|
|
59
|
-
|
|
60
|
-
## Resources
|
|
61
|
-
|
|
62
|
-
| Resource | Surface |
|
|
63
|
-
|----------|---------|
|
|
64
|
-
| `client.auth` | `login`, `me`, `enableDevMode` |
|
|
65
|
-
| `client.iam` | `users`, `roles`, `groups` (CRUD + members), `permissions`, `nav.tree` |
|
|
66
|
-
| `client.osdk` | OSDK token lifecycle: `list/get/create/rotate/revoke` |
|
|
67
|
-
| `client.operator.tasks` | NL task queue: `list/get/create/cancel/retry/reprioritize` |
|
|
68
|
-
| `client.ontology` | `objects` (CRUD, bulk, links, history, timeseries), `graph.expand`, `explorer` (histogram/timeline), `objectTypes`, `linkTypes`, `osdkManifest/osdkFunctions/osdkGenerate` |
|
|
69
|
-
| `client.aip` | `flows`, `agents`, `models` (catalog/defaults), `budget` |
|
|
70
|
-
| `client.functions` | Code Functions: CRUD, `invoke`, tests, publish, versions, pull requests + CI |
|
|
71
|
-
| `client.codeRepositories` | repos, branches, CI, merge |
|
|
72
|
-
| `client.datasets` | datasets, branches, transactions (begin/commit/abort), merges, classification, markings |
|
|
73
|
-
| `client.geo` / `mapTemplates` / `media` / `docs` / `pages` / `dossier` / `timeseries` | reading & consumption surfaces |
|
|
74
|
-
| `client.
|
|
75
|
-
| `client.
|
|
76
|
-
| `client.
|
|
77
|
-
| `client.
|
|
78
|
-
| `client.
|
|
79
|
-
| `client.
|
|
80
|
-
| `client.
|
|
81
|
-
| `
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
npx aegis-osdk
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
}
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
npm
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
1
|
+
# AEGIS SDK — TypeScript (`aegis-platform-sdk`)
|
|
2
|
+
|
|
3
|
+
Typed TypeScript client for the AEGIS HTTPS API (Safe-Core Technologies).
|
|
4
|
+
Mirrors the Python SDK ([`aegis-platform-sdk` on PyPI](https://pypi.org/project/aegis-platform-sdk/))
|
|
5
|
+
— same resource layout, same error hierarchy, same auth model.
|
|
6
|
+
|
|
7
|
+
- **Zero runtime dependencies** — platform `fetch` (Node ≥ 18, browsers, edge runtimes).
|
|
8
|
+
- **ESM + CJS** with full `.d.ts` types.
|
|
9
|
+
- **Same surface as Python**: `client.iam.users.list()` ⇄ `client.iam.users.list()`.
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install aegis-platform-sdk
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Programmatic auth (OSDK Application)
|
|
18
|
+
|
|
19
|
+
Issue a token in the AEGIS UI: **Governance → OSDK Applications**. The
|
|
20
|
+
plaintext appears once; stash it like any other secret.
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
import { AegisClient } from "aegis-platform-sdk";
|
|
24
|
+
|
|
25
|
+
const client = new AegisClient({
|
|
26
|
+
baseUrl: "https://aegis.example.com",
|
|
27
|
+
token: "osdk_xK9pQzR2L8mYvN4w...",
|
|
28
|
+
});
|
|
29
|
+
|
|
30
|
+
const me = await client.auth.me();
|
|
31
|
+
console.log(me.username, me.permissions);
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Env fallbacks (`AEGIS_API_URL`, `AEGIS_TOKEN`) let you construct
|
|
35
|
+
`new AegisClient()` with no arguments in server-side code.
|
|
36
|
+
|
|
37
|
+
## Human auth (login)
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
const client = new AegisClient({ baseUrl: "https://aegis.example.com" });
|
|
41
|
+
await client.auth.login("operador", "senha", { totpCode: "123456" }); // JWT attaches automatically
|
|
42
|
+
const tree = await client.iam.nav.tree();
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Error handling
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
import { AegisAPIError, PermissionDeniedError } from "aegis-platform-sdk";
|
|
49
|
+
|
|
50
|
+
try {
|
|
51
|
+
await client.iam.users.list();
|
|
52
|
+
} catch (err) {
|
|
53
|
+
if (err instanceof PermissionDeniedError) console.error("missing perm:", err.detail);
|
|
54
|
+
else if (err instanceof AegisAPIError) console.error(err.statusCode, err.detail, err.payload);
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
401 → `AuthError` · 403 → `PermissionDeniedError` · 404 → `NotFoundError` · everything else → `AegisAPIError`.
|
|
59
|
+
|
|
60
|
+
## Resources
|
|
61
|
+
|
|
62
|
+
| Resource | Surface |
|
|
63
|
+
|----------|---------|
|
|
64
|
+
| `client.auth` | `login`, `me`, `enableDevMode` |
|
|
65
|
+
| `client.iam` | `users`, `roles`, `groups` (CRUD + members), `permissions`, `nav.tree` |
|
|
66
|
+
| `client.osdk` | OSDK token lifecycle: `list/get/create/rotate/revoke` |
|
|
67
|
+
| `client.operator.tasks` | NL task queue: `list/get/create/cancel/retry/reprioritize` |
|
|
68
|
+
| `client.ontology` | `objects` (CRUD, bulk, links, history, timeseries), `graph.expand`, `explorer` (histogram/timeline), `objectTypes`, `linkTypes`, `osdkManifest/osdkFunctions/osdkGenerate` |
|
|
69
|
+
| `client.aip` | `flows`, `agents`, `models` (catalog/defaults), `budget` |
|
|
70
|
+
| `client.functions` | Code Functions: CRUD, `invoke`, tests, publish, versions, pull requests + CI |
|
|
71
|
+
| `client.codeRepositories` | repos, branches, CI, merge |
|
|
72
|
+
| `client.datasets` | datasets, branches, transactions (begin/commit/abort), merges, classification, markings |
|
|
73
|
+
| `client.geo` / `mapTemplates` / `media` / `docs` / `pages` / `dossier` / `timeseries` | reading & consumption surfaces |
|
|
74
|
+
| `client.publicGuest` | public guest-token consumer (`/public/v1/guest/{token}/*`): `menu`, `fix`, `invoke`, `position` (resident reads visitor's live location), `document`, `page`, `evaluatePage`, `mediaUrl` — anonymous, token in the path |
|
|
75
|
+
| `client.alerts` / `alarms` / `events` / `connectors` / `pipelines` / `chat` / `notepad` | operational surfaces |
|
|
76
|
+
| `client.lineage` / `accessAudit` / `markings` / `resourceMarkings` / `propertyMarkings` / `rowPolicies` / `erasure` / `retention` / `guestTokens` | governance surfaces |
|
|
77
|
+
| `client.workshop` / `compute` / `inference` / `codegen` / `correlation` / `situational` / `merge` | platform surfaces |
|
|
78
|
+
| `client.atlas` / `briefing` / `cctv` / `edge` / `video` / `comunicados` / `campaign` | domain surfaces |
|
|
79
|
+
| `client.forms` / `appShell` / `groups` / `projects` / `organizations` / `spaces` / `solutions` / `workspaces` / `workspaceUpdates` / `marketplace` | collaboration & apps |
|
|
80
|
+
| `client.platformV22` … `client.platformV26` | versioned platform surfaces |
|
|
81
|
+
| `client.stream(path)` | SSE async iterator (task progress, AIP streaming) |
|
|
82
|
+
| `NAV_PERMISSIONS` / `CAPABILITY_PERMISSIONS` / `APPLICATIONS` | static permission + OSDK app catalogs |
|
|
83
|
+
|
|
84
|
+
Anything not wrapped yet is reachable via the escape hatch:
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
const rows = await client.request("GET", "/entities/aggregate", {
|
|
88
|
+
params: { property: "kind" },
|
|
89
|
+
});
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Hardening (1.0)
|
|
93
|
+
|
|
94
|
+
- **Typed results**: `client.geo.nodes<GeoNodesOut>()` — every direct method
|
|
95
|
+
takes a type parameter (default `Json`).
|
|
96
|
+
- **Retry/backoff**: transient failures (network, timeout, 429/5xx-gateway)
|
|
97
|
+
retried on GET/HEAD with jittered exponential backoff — tune via
|
|
98
|
+
`retry: { retries, baseDelayMs, maxDelayMs, retryPost }`.
|
|
99
|
+
- **Auto JWT refresh**: after `auth.login`, a 401 rotates the refresh token
|
|
100
|
+
and retries once, transparently.
|
|
101
|
+
|
|
102
|
+
## OSDK codegen CLI
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
npx aegis-osdk generate --lang typescript # typed module from the LIVE ontology
|
|
106
|
+
npx aegis-osdk manifest # raw manifest JSON
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Auth via `AEGIS_API_URL`/`AEGIS_TOKEN` or `--base-url`/`--token`. Wire the
|
|
110
|
+
generated module with `asOsdkClient(client)`.
|
|
111
|
+
|
|
112
|
+
## Proxy mode (cookie-auth frontends)
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
const aegis = new AegisClient({
|
|
116
|
+
baseUrl: "/api", // relative — resolved against the browser origin
|
|
117
|
+
fetchInit: { credentials: "include", cache: "no-store" },
|
|
118
|
+
});
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Claude Code skill
|
|
122
|
+
|
|
123
|
+
The npm package ships a Claude Code skill under `skills/aegis-sdk/`. In an
|
|
124
|
+
external project that consumes this SDK, copy it into the project's
|
|
125
|
+
`.claude/skills/` so Claude Code knows the SDK surface and conventions:
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
mkdir -p .claude/skills
|
|
129
|
+
cp -r node_modules/aegis-platform-sdk/skills/aegis-sdk .claude/skills/aegis-sdk
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## Development
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
npm install
|
|
136
|
+
npm run typecheck && npm test && npm run build
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Releases: see [`PUBLISHING.md`](./PUBLISHING.md). Roadmap and extension
|
|
140
|
+
plan: [`docs/PLAN.md`](./docs/PLAN.md).
|
|
141
|
+
|
|
142
|
+
## License
|
|
143
|
+
|
|
144
|
+
Proprietary — Safe-Core Technologies. See [LICENSE](./LICENSE).
|