[neelneelneel]

Description

The backend now owns the API contract and the SDK is generated from it. Monolith exports one OpenAPI 3.1 document, built from annotations in Semoss (reactors) and Monolith (REST resources). The TypeScript SDK in libs/sdk generates typed calls and a typed Pixel catalog from that document; a Python SDK can later read the same file. Everything is opt-in: existing SDK calls keep their behavior and types.

This change spans three repositories:

• Semoss describes reactor contracts.
• Monolith exports the document.
• semoss-ui (@semoss/sdk) generates the calls and adds typed hooks.

Changes Made

Semoss

• AbstractReactor2<Input, Output>: a reactor declares its inputs once, as a record.
  • keysToGet, keyRequired, the key descriptions, the MCP types and the typed input all come from that record.
  • The return value is wrapped in a NounMetadata automatically.
  • --help, asMcpTool() and positional inputs still work.
• Echo, GetCurrentInsightId and StopPixelExecution now extend it. Their outputs and messages are unchanged.
• @Internal (prerna.openapi.Internal) marks a reactor or REST operation as not for general use. @DynamicOutput marks a reactor whose output type isn't fixed.
• Adds the swagger-annotations-jakarta dependency and AbstractReactor2Test.

Monolith

• OpenApiExporter and scripts/generate-api write target/generator/openapi.json. Nothing is listed by hand:
  • Published: every @Operation method in the servlets' JAX-RS applications, and every AbstractReactor2 (under x-semoss-pixels).
  • Left out: anything with swagger's @Hidden.
  • Tagged x-internal: anything with @Internal.
  • x-semoss-servlets names each servlet's SDK module.
• The document is canonical, so repeated runs produce identical bytes. It is validated with swagger-parser, and the export fails on OpenAPI 3.0 forms, missing descriptions and duplicate operationIds.
• GET /api/config is described by a ServerConfig record. ServerConfigContractTest keeps the record in step with the keys the resource actually returns. The response itself is unchanged.
• An openapi Maven profile builds into target/openapi-build, so stale IDE output in target/classes can't shadow the Semoss jar.
• Adds JUnit 5, OpenApiExporterTest with fixtures in test/openapi/fixtures, and docs/openapi.md.

semoss-ui (@semoss/sdk)

• Generator: scripts/sdk-generator.
  • pnpm generate --openapi FILE writes src/generated/. Each call is a plain async function over the existing get/post, with its types written inline.
  • pnpm generate:check --openapi FILE reports drift.
  • The output is deterministic, whatever the document's key order or the machine's locale.
• Generated calls: published as @semoss/sdk/api/*, starting with config from @semoss/sdk/api/monolith. Calls the backend marks internal get an @internal TSDoc tag.
• Typed Pixels:
  • buildPixel and readPixelOutput, typed by the generated PixelCatalog. buildPixel writes every value as an escaped literal.
  • Typed overloads for runPixel, usePixel, useIteratorPixel, runPixelAsync and getPixelAsyncResult. Plain strings and explicit type arguments keep the legacy types.
• Hooks:
  • useAPI(fn, input, options) passes an AbortSignal and compares its input by value.
  • useIteratorApi can now page a generated call directly: it fills in limit and offset and accepts a select function. The existing (fetchPage, options, deps) form still works.
• Adds type-level tests (*.test-d.ts with tsconfig.typecheck.json) and @testing-library/react for the hook tests.

How to Test

1. Install Semoss, run the Monolith tests, then export the document and regenerate the SDK:

   cd Semoss && mvn -q -DskipTests install
   cd ../Monolith && mvn -q -P openapi test
   scripts/generate-api --skip-semoss-install --sdk <path to semoss-ui>/libs/sdk

[snyk-io]

⛔ Snyk checks have failed. 2 issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (2)
⛔	Open Source Security	0	2	0	0	2 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[neelneelneel]

Depends on SEMOSS/semoss-ui#3850
Depends on SEMOSS/Semoss#3259
Depends on #468