@aindy/ui-kit 1.0.5 → 2.0.0

package/README.md

@@ -0,0 +1,129 @@
+# @aindy/ui-kit
+
+Shared UI components, React contexts, and API core for **AINDY platform** frontends.
+
+`@aindy/ui-kit` is the client-side counterpart to the [`aindy-runtime`](https://pypi.org/project/aindy-runtime/)
+backend: it centralizes the authenticated HTTP layer, the canonical backend route table,
+auth/session contexts, and a small set of shared components and UI primitives so every
+frontend built on the runtime talks to it the same way. It is published to npm and consumed
+as a compiled bundle (`dist/` is built at publish time, not committed).
+
+## Install
+
+```bash
+npm install @aindy/ui-kit
+```
+
+**Peer dependencies** (provided by the host app):
+
+- `react` ^19
+- `react-dom` ^19
+- `react-router-dom` ^6
+
+## What it exports
+
+### API core (`./api/_core.js`)
+
+The authenticated request layer against the runtime. `buildApiUrl` prepends `API_BASE` to a
+`ROUTES` value; the `request` family attaches the stored token and returns the parsed body.
+
+| Export | Purpose |
+|---|---|
+| `request`, `authRequest`, `adminRequest`, `taggedRequest`, `requestAbsolute` | HTTP calls (auth-scoped / admin-scoped / cache-tagged / absolute-URL variants) |
+| `buildApiUrl` | Resolve a `ROUTES` value against `API_BASE` |
+| `getStoredToken`, `setStoredToken`, `clearStoredToken` | JWT storage |
+| `unwrapEnvelope` | Unwrap the runtime's `{ data: … }` response envelope |
+| `ApiError` | Typed error carrying status + body |
+| `API_BASE` | Build-time API base (`VITE_API_BASE_URL`, default `""` — relative to origin) |
+
+### Routes (`./api/_routes.js`)
+
+- `ROUTES` — the canonical backend route table. **Every runtime/platform route carries the
+  full `/platform` prefix** (e.g. `ROUTES.OPERATOR.FLOW_STRATEGIES` → `/platform/flows/strategies`).
+  A value that drops the prefix segment 404s.
+- `FEATURE_FLAGS` — NavLink gates for routes that are conditionally served; flip a flag to
+  `true` when its backing runtime route lands.
+
+> **Runtime routes vs app routes.** `ROUTES` should carry **runtime/platform** paths only —
+> these are shared by every consumer, and the runtime's authoritative list lives in
+> [`aindy-runtime` `docs/runtime/UI_CONTRACT.md`](https://github.com/Masterplanner25/aindy-runtime/blob/main/docs/runtime/UI_CONTRACT.md).
+> **App-domain** paths (e.g. `/compute/*` analytics, `/seo/*`) are **not** runtime routes and
+> must not be baked into this shared kit; a consuming app owns those in its own route map that
+> spreads and extends `ROUTES` (mirroring the backend's runtime/app split).
+
+### Auth (`./api/auth.js`)
+
+`bootIdentity`, `loginUser`, `registerUser`.
+
+> **Invariant:** all three must `.then(unwrapEnvelope)` — `bootIdentity` populates
+> `system.runtime.boot_mode` (read by the post-login redirect); returning the raw envelope
+> silently breaks it.
+
+### Contexts
+
+- `AuthProvider` / `useAuth` — session + identity.
+- `SystemProvider` / `useSystem` — runtime system state (incl. `boot_mode`).
+
+### Components
+
+`AppShell`, `ProtectedRoute`, `VersionMismatchBanner`, `Toast`, `LoadingPanel`,
+`DomainError`, `AdminAccessRequired` (+ `useAdminApiGuard`), `EmptyState`.
+
+### UI primitives
+
+`Button` (+ `buttonVariants`), the `Card` family (`Card`, `CardHeader`, `CardTitle`,
+`CardDescription`, `CardContent`, `CardFooter`), the `Tooltip` family (`Tooltip`,
+`TooltipTrigger`, `TooltipContent`, `TooltipProvider`).
+
+### Utilities
+
+`cn` (class merge), `APPROVAL_EVENT`, `useApiCall`, `useToast`, `safeArray`, `safeMap`.
+
+## Usage
+
+```jsx
+import {
+  AuthProvider, SystemProvider, ProtectedRoute, AppShell,
+  ROUTES, request, unwrapEnvelope,
+} from "@aindy/ui-kit";
+
+function App() {
+  return (
+    <AuthProvider>
+      <SystemProvider>
+        <AppShell>{/* routes */}</AppShell>
+      </SystemProvider>
+    </AuthProvider>
+  );
+}
+
+// A backend call through the canonical route table:
+const strategies = await request(ROUTES.OPERATOR.FLOW_STRATEGIES).then(unwrapEnvelope);
+```
+
+## Development
+
+```bash
+npm run build    # vite build → dist/ (index.js, index.cjs, index.d.ts)
+npm run lint     # eslint src
+npm test         # vitest
+```
+
+## Versioning & the runtime
+
+`@aindy/ui-kit` and `aindy-runtime` are **independently versioned**. This package *consumes*
+the runtime's HTTP contract; the runtime does not depend on it. A ui-kit release does **not**
+require a runtime release (and vice versa) — a runtime bump is only relevant when a ui-kit
+change depends on a *new* runtime route or behavior. Keep `ROUTES` in sync with the runtime's
+`docs/runtime/UI_CONTRACT.md`; a route that drifts from a served backend path is the
+`UIKIT-ROUTE-DRIFT-1` failure mode.
+
+## Publishing
+
+`dist/` is gitignored and built fresh at publish:
+
+```bash
+npm version patch        # e.g. 1.0.5 → 1.0.6
+npm run build
+npm publish
+```

package/dist/api/_routes.d.ts

@@ -1,7 +1,18 @@
+export const FEATURE_FLAGS: Readonly<{
+    OPERATOR_FLOW_STRATEGIES: true;
+    OPERATOR_AUTOMATION_LOGS: false;
+    OPERATOR_SCHEDULER_STATUS: false;
+    RIPPLETRACE_VIEWER: false;
+}>;
 export const ROUTES: Readonly<{
     AUTH: Readonly<{
         LOGIN: "/auth/login";
         REGISTER: "/auth/register";
+        LOGOUT: "/auth/logout";
+        VERIFY_EMAIL: "/auth/verify-email";
+        PASSWORD_CHANGE: "/auth/password/change";
+        PASSWORD_FORGOT: "/auth/password/forgot";
+        PASSWORD_RESET: "/auth/password/reset";
     }>;
     TASKS: Readonly<{
         LIST: "/tasks/list";
@@ -23,6 +34,8 @@ export const ROUTES: Readonly<{
         RUN: (runId: any) => string;
         APPROVE: (runId: any) => string;
         REJECT: (runId: any) => string;
+        RECOVER: (runId: any) => string;
+        REPLAY: (runId: any) => string;
         STEPS: (runId: any) => string;
         EVENTS: (runId: any) => string;
         TOOLS: "/apps/agent/tools";
@@ -142,14 +155,15 @@ export const ROUTES: Readonly<{
         FLOW_RUN_RESUME: (runId: any) => string;
         FLOW_REGISTRY: "/platform/flows/registry";
         FLOW_STRATEGIES: "/platform/flows/strategies";
-        AUTOMATION_LOGS: "/automation/logs";
-        AUTOMATION_LOG: (logId: any) => string;
-        AUTOMATION_REPLAY: (logId: any) => string;
-        SCHEDULER_STATUS: "/platform/observability/scheduler/status";
+        RIPPLETRACE_STATUS: "/platform/observability/rippletrace/status";
         OBSERVABILITY_REQUESTS: "/platform/observability/requests";
         OBSERVABILITY_DASHBOARD: "/platform/observability/dashboard";
         CLIENT_ERROR: "/client/error";
         CLIENT_VITALS: "/client/vitals";
+        AUTOMATION_LOGS: "/automation/logs";
+        AUTOMATION_LOG: (logId: any) => string;
+        AUTOMATION_REPLAY: (logId: any) => string;
+        SCHEDULER_STATUS: "/platform/observability/scheduler/status";
     }>;
     PLATFORM: Readonly<{
         DASHBOARD_OVERVIEW: "/dashboard/overview";

package/dist/api/auth.d.ts

@@ -1,3 +1,36 @@
 export function loginUser(credentials: any): Promise<any>;
+/**
+ * Begin registration. Against runtime >= 2.0.0 this resolves to
+ * `{ status: "verification_sent" }` and **carries no access token** — the response is
+ * deliberately identical whether or not the address was already registered, which is what
+ * closes the account-enumeration oracle. The token is issued by `verifyEmail` once the
+ * emailed link is followed.
+ */
 export function registerUser(credentials: any): Promise<any>;
+/** Consume an emailed verification token and receive the access token. */
+export function verifyEmail(token: any): Promise<any>;
+/**
+ * Rotate the signed-in user's password.
+ *
+ * Returns a freshly-versioned access token. **It must be stored** — the change invalidates
+ * every session including this one, so keeping the old token 401s on the next request.
+ */
+export function changePassword(currentPassword: any, newPassword: any, token?: string): Promise<any>;
+/**
+ * Begin password recovery.
+ *
+ * Resolves identically whether or not the address is registered — do not branch on the
+ * result to tell the user whether an account exists, that is the oracle this avoids. A 503
+ * means the deployment has no email channel configured, which is about the deployment and
+ * not about any account.
+ */
+export function forgotPassword(email: any): Promise<any>;
+/**
+ * Complete password recovery with an emailed token.
+ *
+ * Returns no access token — unlike `changePassword`, the caller has not proven they hold a
+ * session, so they sign in afresh.
+ */
+export function resetPassword(token: any, newPassword: any): Promise<any>;
+export function logoutUser(token?: string): Promise<any>;
 export function bootIdentity(token?: string): Promise<any>;

package/dist/api/index.d.ts

@@ -1,3 +1,3 @@
 export { ROUTES } from './_routes.js';
 export { ApiError, adminRequest, authRequest, authRequestExternal, buildApiUrl, clearStoredToken, getStoredToken, request, requestAbsolute, setStoredToken, taggedRequest, unwrapEnvelope, API_BASE } from './_core.js';
-export { bootIdentity, loginUser, registerUser } from './auth.js';
+export { bootIdentity, changePassword, forgotPassword, loginUser, registerUser, resetPassword, verifyEmail } from './auth.js';