starintel-labs/starintel-client
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Implement discovery-driven StarIntel client (contract registry only) #2

Merged
nsaspy merged 2 commits from rage/1-discovery-client into main 2026-09-09 14:54:16 +00:00
Conversation 0 Commits 2 Files changed 17 +3551 -1
nsaspy commented 2026-09-08 23:27:17 +00:00
Owner
Copy link

Closes starintel-labs/starintel-client#1 (Auto-RAGE run log: rage/1-discovery-client.org).

Public API

starintel_client — discovery-driven client built exclusively from the server's machine-readable contract:

  • StarIntelClient(base_url, api_key=...) sync facade over an httpx async transport primitive; bounded timeouts; conservative retry (idempotent GETs only, never 4xx)
  • Bearer star_sk_v1_... auth; per-request X-Correlation-ID generation + server echo capture
  • Manifest/OpenAPI parsing into typed models; operations are manifest-driven — unknown or legacy paths are rejected by construction
  • StarIntelApiError normalizing server envelopes (status, msg, correlation_id, stable code)
  • Typed methods for currently-contracted operations: health, server metadata, login/context, human-user lifecycle, API-credential lifecycle, discovery

Legacy-route ban enforced by test

tests/test_no_legacy_routes.py fails the suite if /new/document/:dtype, /documents/bulk, /document/:id, /new/target/:actor, GET /search, or view-route strings appear under src/.

Verification

  • pytest -q — 84 passed, 2 skipped (hermetic stdlib-http.server mock; live tests opt-in via STARINTEL_LIVE_TEST=1)
  • ruff check . — clean; mypy (strict, 8 files) — clean
  • Live (recorded in run log, not required for merge): with STARINTEL_LIVE_TEST=1 the client validated against the real server — 19 contracted ops at the time, adapted with zero code changes when the registry grew (stats.get, public.search.get, targets.create), demonstrating the discovery-driven design

Blocked elsewhere

Document publication surfaces automatically from the manifest once starintel-server#5 (versioned document routes) merges — no client change expected; the RAGE run log records this decision.

Closes starintel-labs/starintel-client#1 (Auto-RAGE run log: `rage/1-discovery-client.org`). ## Public API `starintel_client` — discovery-driven client built exclusively from the server's machine-readable contract: - `StarIntelClient(base_url, api_key=...)` sync facade over an httpx async transport primitive; bounded timeouts; conservative retry (idempotent GETs only, never 4xx) - Bearer `star_sk_v1_...` auth; per-request `X-Correlation-ID` generation + server echo capture - Manifest/OpenAPI parsing into typed models; operations are **manifest-driven** — unknown or legacy paths are rejected by construction - `StarIntelApiError` normalizing server envelopes (`status`, `msg`, `correlation_id`, stable `code`) - Typed methods for currently-contracted operations: health, server metadata, login/context, human-user lifecycle, API-credential lifecycle, discovery ## Legacy-route ban enforced by test `tests/test_no_legacy_routes.py` fails the suite if `/new/document/:dtype`, `/documents/bulk`, `/document/:id`, `/new/target/:actor`, `GET /search`, or view-route strings appear under `src/`. ## Verification - `pytest -q` — 84 passed, 2 skipped (hermetic stdlib-http.server mock; live tests opt-in via `STARINTEL_LIVE_TEST=1`) - `ruff check .` — clean; `mypy` (strict, 8 files) — clean - Live (recorded in run log, not required for merge): with `STARINTEL_LIVE_TEST=1` the client validated against the real server — 19 contracted ops at the time, adapted with **zero code changes** when the registry grew (`stats.get`, `public.search.get`, `targets.create`), demonstrating the discovery-driven design ## Blocked elsewhere Document publication surfaces automatically from the manifest once starintel-server#5 (versioned document routes) merges — no client change expected; the RAGE run log records this decision.
Manifest+OpenAPI parsing with legacy-route rejection, correlation ids,
bounded-timeout httpx transports with GET-only retry, sync+async clients,
typed wrappers for the 16 currently-contracted operations, hermetic stdlib
mock-server tests, anti-legacy src/ scan, live opt-in tests.
nsaspy merged commit 881e3e9e15 into main 2026-09-09 14:54:16 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
starintel-labs/starintel-client!2
No description provided.