aegis-platform-sdk 0.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,11 +1,127 @@
-# Changelog
-
-## 0.1.0 — 2026-07-08
-
-First cut of the TypeScript SDK, mirroring `aegis-platform-sdk` (Python) v0.10.0.
-
-- `AegisClient` — fetch-based transport, zero runtime dependencies, ESM + CJS.
-- Auth: `login` (JWT attach), `me`, `enableDevMode`; env fallbacks `AEGIS_API_URL` / `AEGIS_TOKEN`.
-- Error hierarchy: `AegisAPIError`, `AuthError` (401), `PermissionDeniedError` (403), `NotFoundError` (404).
-- 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).
-- Generic `client.request(method, path, opts)` escape hatch for unwrapped endpoints.
+# Changelog
+
+## 1.3.0 — 2026-07-31
+
+Two operator gestures born with the desk app. Additive; no breaking changes.
+Parity with the Python SDK (`edge.create_pairing_code(grants=…)`,
+`alerts.set_channel` / `delete_channel`).
+
+- **`client.edge.createPairingCode({ grants })`** — a pairing code can now
+  **grant gestures** to whichever device redeems it. Empty — the default — is
+  **read only**: least privilege, and granting has to be a choice. The grant
+  travels from the code to the node and dies with it on `revoke`. Even when
+  granted, the device never receives the gesture's ADDRESS
+  (`agent_id`/`skill_key`): it sends the verb and the server routes it.
+- **`client.alerts.setChannel(ref, config)` / `deleteChannel(ref)`** —
+  `PUT`/`DELETE /alerts/channels/{ref}`, pointing a delivery channel at its
+  destination. Exists so this is a GESTURE: before it, sending alerts to the
+  team's Discord meant editing the tenant's JSONB in the database. Audited
+  (`alert_channel.configured` / `.removed`). Reads return the config
+  **masked** — a webhook URL is the credential.
+- New `discord` channel in the horizontal messaging registry: shows up in
+  `client.alerts.channels()` on its own, no contract change.
+
+## 1.2.0 — 2026-07-09
+
+New method on `publicGuest`. No breaking changes.
+
+- **`client.publicGuest.position(token)`** — `GET /public/v1/guest/{token}/position`.
+  The resident-side read of a visitor's live location: the operator issues the
+  resident's token with `geo.live_ref` = the visitor's guest-token id, and this
+  returns `{available, lat, lng, ts, inside_fence, arrived, deviated,
+  distance_to_target_m, visit_status}`. Least-privilege — the resident sees only
+  that one visit. Poll it (no push; the bus→SSE bridge is a later wave).
+  Dogfooded by the Safe-Tag `residentmap` SPA.
+- 2 new tests (194 total).
+
+## 1.1.0 — 2026-07-09
+
+New resource. No breaking changes.
+
+- **`client.publicGuest`** — the consumer side of a public guest token
+  (`/public/v1/guest/{token}/*`), the counterpart to `client.guestTokens`
+  (operator issue/list/revoke). 8 request methods (`menu`, `fix`, `invoke`,
+  `document`, `queryObjectSet`, `documentNode`, `page`, `evaluatePage`) plus
+  `mediaUrl(token, key)` — a string builder for `<img src>` (media bytes are
+  binary; the JSON transport doesn't fetch them). Anonymous by design: build
+  `new AegisClient({ baseUrl })` with no token; the token travels in the path.
+  Dogfooded by the Safe-Tag SPAs (livetracker/residentmap repointed off
+  Firebase onto AEGIS).
+- 15 new tests (192 total).
+
+## 1.0.0 — 2026-07-08
+
+F5 — Hardening. No breaking API changes; new default behaviors noted below.
+
+- **Retry/backoff** (new default behavior): transient failures (network
+  errors, timeouts, 429/502/503/504) are retried with exponential backoff +
+  full jitter — GET/HEAD only, 2 retries. Configure via `retry` option
+  (`{retries, baseDelayMs, maxDelayMs, retryPost}`); `{retries: 0}` disables.
+- **Automatic JWT refresh**: `auth.login` now captures the refresh token; on
+  a 401 the client rotates it via `POST /auth/refresh` (single-flight) and
+  retries the request once. A rejected refresh clears the token (no loops).
+  Seed manually via `refreshToken` option / `setRefreshToken()`; explicit
+  `auth.refresh(token)` added.
+- **Per-method generics**: 510 resource methods now accept a type parameter —
+  `client.geo.nodes<GeoNodesOut>()` instead of `as unknown as` casts
+  (`T = Json` default keeps all existing code compiling).
+- All resource classes and their option types are exported from the package
+  root (typed params in consumer code + full typedoc coverage).
+- `npm run docs` (typedoc) + `examples/` (OSDK-token server usage, browser
+  proxy mode with SSE).
+- 12 new tests (177 total).
+
+## 0.4.0 — 2026-07-08
+
+F3 (OSDK codegen CLI) + F4 groundwork (proxy-mode, dogfooded in security-app).
+
+- **`aegis-osdk` CLI** (`npx aegis-osdk generate|manifest`): fetches
+  `GET /ontology/osdk/generate?lang=typescript|python` from a live deployment
+  and writes the typed module; prints the contract version. Proven live against
+  a real AEGIS backend (generated module passes strict `tsc`).
+- **`asOsdkClient(client)`** adapter — bridges `AegisClient` to the `OSDKClient`
+  `{get, post}` contract expected by generated modules.
+- **Proxy mode** (cookie-auth frontends like security-app): relative `baseUrl`
+  (e.g. `/api`, resolved against the browser origin) + `fetchInit` option
+  (`{credentials: "include", cache: "no-store"}` merged into every request,
+  including `stream()`).
+- `geo.referenceLayers()` / `geo.referenceLayer(id, {uf, municipio})` — gap
+  found while dogfooding (endpoints existed in the backend but in neither SDK).
+- 12 new tests (165 total).
+
+## 0.3.0 — 2026-07-08
+
+F1.5 (full parity closure) + F2 (SSE streaming). **Every Python SDK module now has a TS mirror.**
+
+- **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`.
+- **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).
+- **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).
+- **Static catalogs**: full IAM permission catalog (`NAV_PERMISSIONS`/`CAPABILITY_PERMISSIONS`/`PermissionKey` union, `isSystemPermission`) and the OSDK `APPLICATIONS` catalog (7 apps) with `validateApplication`.
+- **F2 — SSE**: `client.stream(path)` async iterator + spec-compliant `parseSseStream` (chunk-boundary safe, CRLF, comments, sticky id/retry); errors map through the exception hierarchy.
+- Transport: multipart `form` option; array query params (repeated keys).
+- 60 new tests (153 total).
+
+## 0.2.0 — 2026-07-08
+
+F1 — resource parity, 27 new client surfaces (mirror of Python SDK v0.10.0):
+
+- **Reading**: `geo`, `mapTemplates` (incl. `exportSvg` raw-SVG), `media`, `docs`, `pages`, `dossier` (async start → poll), `timeseries`.
+- **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`.
+- **Governance**: `lineage`, `accessAudit`, `markings` (+categories/eligibility), `resourceMarkings`, `propertyMarkings`, `rowPolicies`, `erasure` (preview/forget), `retention`, `guestTokens`.
+- **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`.
+- Client-side classification helpers: `maxLevel`, `validateInvariant`, `ClassificationInvariantViolation` (mirror of `aegis.classification`).
+- 64 new tests (93 total).
+
+Deliberate deviations from Python (documented in `docs/PLAN.md`): the stdout-based
+`aegis.maps` builder is sandbox-IDE-only and was not ported (only `MapTemplates` HTTP
+surface); `inference` is a client resource here instead of a functional namespace.
+
+## 0.1.0 — 2026-07-08
+
+First cut of the TypeScript SDK, mirroring `aegis-platform-sdk` (Python) v0.10.0.
+
+- `AegisClient` — fetch-based transport, zero runtime dependencies, ESM + CJS.
+- Auth: `login` (JWT attach), `me`, `enableDevMode`; env fallbacks `AEGIS_API_URL` / `AEGIS_TOKEN`.
+- Error hierarchy: `AegisAPIError`, `AuthError` (401), `PermissionDeniedError` (403), `NotFoundError` (404).
+- 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).
+- Generic `client.request(method, path, opts)` escape hatch for unwrapped endpoints.

package/README.md

@@ -1,105 +1,144 @@
-# 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](https://pypi.org/project/aegis-platform-sdk/))
-— 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
-
-```bash
-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.
-
-```ts
-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)
-
-```ts
-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
-
-```ts
-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 |
-
-Anything not wrapped yet is reachable via the escape hatch:
-
-```ts
-const rows = await client.request("GET", "/entities/aggregate", {
-  params: { property: "kind" },
-});
-```
-
-## 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:
-
-```bash
-mkdir -p .claude/skills
-cp -r node_modules/aegis-platform-sdk/skills/aegis-sdk .claude/skills/aegis-sdk
-```
-
-## Development
-
-```bash
-npm install
-npm run typecheck && npm test && npm run build
-```
-
-Releases: see [`PUBLISHING.md`](./PUBLISHING.md). Roadmap and extension
-plan: [`docs/PLAN.md`](./docs/PLAN.md).
-
-## License
-
-Proprietary — Safe-Core Technologies. See [LICENSE](./LICENSE).
+# 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](https://pypi.org/project/aegis-platform-sdk/))
+— 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
+
+```bash
+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.
+
+```ts
+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)
+
+```ts
+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
+
+```ts
+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.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 |
+| `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:
+
+```ts
+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
+
+```bash
+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)
+
+```ts
+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:
+
+```bash
+mkdir -p .claude/skills
+cp -r node_modules/aegis-platform-sdk/skills/aegis-sdk .claude/skills/aegis-sdk
+```
+
+## Development
+
+```bash
+npm install
+npm run typecheck && npm test && npm run build
+```
+
+Releases: see [`PUBLISHING.md`](./PUBLISHING.md). Roadmap and extension
+plan: [`docs/PLAN.md`](./docs/PLAN.md).
+
+## License
+
+Proprietary — Safe-Core Technologies. See [LICENSE](./LICENSE).