[neelneelneel]

Description

Align the SDK with the Monolith and Semoss backend implementations and provide typed REST resources, React API requests, and Pixel builders. Preserve existing SDK entry points while improving request handling, response contracts, and affected application consumers.

Changes Made

• Add 49 REST resource modules with 371 request wrappers and 15 URL builders, exposed through @semoss/sdk/api/monolith/<resource> and servlet-specific subpaths.
• Share authentication, CSRF handling, headless cookies, redirects, and session state between typed resources and existing HTTP helpers. Add request cancellation options, structured route errors, and backend-specific request/response encoding.
• Add useAPI with typed method/argument tuples, inferred responses and callbacks, refresh/update actions, disabled requests, and stale-response cleanup.
• Add buildPixel and rawPixel, backed by a catalog of 1,542 built-in reactor names, aliases, and frame variants. Infer outputs in both runPixel and usePixel while retaining raw strings and explicit generics.
• Trace reactor outputs through implementations, helpers, SQL mappers, and serializers. Validate Pixel serialization, including nested values, escaping, numeric boundaries, and trusted expressions.
• Correct permission-candidate and agent response contracts. Update Playground sharing and partial tool-event handling, and distinguish automation progress from subagent activity.
• Extend SDK builds and declarations for resource subpaths, separate unit and production integration tests, and verify tree shaking and initialization.
• Add independent API/reactor sync metadata, source evidence, coverage checks, migration guidance, and tracked contract gaps.

How to Test

1. With Node 24 and pnpm 10.13.1, run the SDK checks:

   pnpm install --frozen-lockfile
   pnpm --filter @semoss/sdk exec tsc --noEmit --emitDeclarationOnly false
   pnpm --filter @semoss/sdk test
   pnpm --filter @semoss/sdk test:integration

   Expected: TypeScript passes, 345 SDK unit tests pass, and all 5 production integration tests pass. Published imports, declarations, inferred types, tree shaking, and initialization remain valid.

2. Run the affected consumer regression tests:

   pnpm --filter @semoss/automation test src/components/agent-run/agent-run-graph.test.ts
   pnpm --filter @semoss/playground test src/components/workspace/members/workspace-sharing-modal.test.tsx src/stores/message/agent-harness.test.ts

   Expected: progress remains separate from subagents, directory candidates display usable identities, and partial completion events preserve earlier tool details.

3. Against a configured backend, exercise the SDK README examples for typed resource calls, useAPI, and runPixel(buildPixel("GetProjectList", {})). Verify usePixel infers the result, disabling prevents requests, and refresh reruns the call. Existing raw Pixel strings and explicit response generics should continue working.

Notes

• Existing root helpers remain available; 18 thin REST wrappers now include deprecation guidance.
• Reactor name coverage is complete for the recorded backend snapshot. Twenty runtime-dependent outputs remain unknown; remaining input and nested-output audit gaps are documented in the catalog and libs/sdk/ISSUES.md.
• Backend findings and source provenance are recorded in semoss-sync.json. This PR does not modify backend implementations.
• Recorded validation includes SDK tests, production builds, TypeScript, focused Biome checks, and local backend parser/serializer probes. Authenticated live-service and browser UI testing remain manual.

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

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

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

[neelneelneel]

Example usage:

import { Env, buildPixel, rawPixel, runPixel } from "@semoss/sdk";
import { getProjects } from "@semoss/sdk/api/monolith/auth/project";

Env.update({ MODULE: "/Monolith", CSRF: true });

// Typed REST calls return the response body directly.
const projects = await getProjects(
    { limit: 20 },
    { signal: AbortSignal.timeout(10_000) },
);

// Pixel parameters and successful outputs are inferred.
const result = await runPixel(buildPixel("GetProjectList", {}), insightId);
const total = await runPixel(buildPixel("SUM", [10, 20, 30]), insightId);

// Ordinary strings are literals; rawPixel marks trusted expressions.
const query = buildPixel("Select", [
    rawPixel("department"),
    rawPixel("Sum(cost)"),
]);

Inside a React component or custom hook:

import { useAPI, usePixel } from "@semoss/sdk/react";

const api = useAPI(
    enabled ? [getProjects, { limit: 20 }] : null,
);

const pixel = usePixel(
    enabled ? buildPixel("GetProjectList", {}) : "",
    { data: [] },
    insightId,
);

Both hooks expose status, data, error, refresh(), and update(), with inferred response types.

REST resources share authentication, CSRF, and session handling, support cancellation, and expose structured ApiError errors. Existing raw Pixel strings, explicit generics, and legacy helpers remain supported.