@dudousxd/nestjs-agent-dashboard 0.12.0 → 0.13.1

package/dist/react/index.d.ts

@@ -0,0 +1,4 @@
+export * from './use-open-console.js';
+export * from './open-console-button.js';
+export * from '../client/console-session.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AASA,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AAEzC,cAAc,8BAA8B,CAAC"}

package/dist/react/index.js

@@ -0,0 +1,14 @@
+// The React tier of `@dudousxd/nestjs-agent-dashboard`, published at the `./react` subpath so a
+// host that only mounts the NestJS module never pulls React in. Three levels, pick one:
+//
+//   openAgentConsole(...)        — no React at all (`./client`), you own everything
+//   useOpenAgentConsole(...)     — state for a launcher UI, you own the markup
+//   <OpenAgentConsoleButton />   — drop-in, unstyled, forwards every button prop
+//
+// `openAgentConsoleMutationOptions` wires the same call into TanStack Query without this package
+// depending on TanStack.
+export * from './use-open-console.js';
+export * from './open-console-button.js';
+// Re-exported so a React consumer needs one import path, not two.
+export * from '../client/console-session.js';
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,wFAAwF;AACxF,EAAE;AACF,oFAAoF;AACpF,+EAA+E;AAC/E,iFAAiF;AACjF,EAAE;AACF,iGAAiG;AACjG,yBAAyB;AACzB,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,kEAAkE;AAClE,cAAc,8BAA8B,CAAC"}

package/dist/react/open-console-button.d.ts

@@ -0,0 +1,26 @@
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
+import type { OpenConsoleOptions } from '../client/console-session.js';
+export interface OpenAgentConsoleButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'children'>, OpenConsoleOptions {
+    /** Button label. Defaults to "Open AI gateway". */
+    children?: ReactNode;
+    /** Shown while the session is being minted. Defaults to "Opening…". */
+    pendingLabel?: ReactNode;
+    /**
+     * Render the refusal yourself. Omit and the button renders a plain `<p role="alert">` under
+     * itself; pass `null` to render nothing and read the error from {@link useOpenAgentConsole}.
+     */
+    renderError?: ((error: Error) => ReactNode) | null;
+}
+/**
+ * Drop-in launcher: the top tier, for a host that just wants a working button.
+ *
+ * Deliberately unstyled — it emits a bare `<button>` and forwards `className`/`style`/every other
+ * button prop, so it inherits whatever design system the host already has instead of importing CSS
+ * that would fight it. When it doesn't fit, drop to {@link useOpenAgentConsole} (same behaviour,
+ * your markup) or to `openAgentConsole` (no React at all).
+ *
+ * The error is rendered by default rather than swallowed: a refused mint is the case a launcher most
+ * needs to surface, and a button that silently does nothing reads as broken rather than forbidden.
+ */
+export declare function OpenAgentConsoleButton({ children, pendingLabel, renderError, basePath, headers, fetch: fetchImpl, signal, navigate, disabled, ...buttonProps }: OpenAgentConsoleButtonProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=open-console-button.d.ts.map

package/dist/react/open-console-button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-console-button.d.ts","sourceRoot":"","sources":["../../src/react/open-console-button.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,MAAM,WAAW,2BACf,SAAQ,IAAI,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC,EAC3E,kBAAkB;IACpB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,uEAAuE;IACvE,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,SAAS,CAAC,GAAG,IAAI,CAAC;CACpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,OAAO,EACP,KAAK,EAAE,SAAS,EAChB,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,GAAG,WAAW,EACf,EAAE,2BAA2B,2CA4B7B"}

package/dist/react/open-console-button.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useOpenAgentConsole } from './use-open-console.js';
+/**
+ * Drop-in launcher: the top tier, for a host that just wants a working button.
+ *
+ * Deliberately unstyled — it emits a bare `<button>` and forwards `className`/`style`/every other
+ * button prop, so it inherits whatever design system the host already has instead of importing CSS
+ * that would fight it. When it doesn't fit, drop to {@link useOpenAgentConsole} (same behaviour,
+ * your markup) or to `openAgentConsole` (no React at all).
+ *
+ * The error is rendered by default rather than swallowed: a refused mint is the case a launcher most
+ * needs to surface, and a button that silently does nothing reads as broken rather than forbidden.
+ */
+export function OpenAgentConsoleButton({ children, pendingLabel, renderError, basePath, headers, fetch: fetchImpl, signal, navigate, disabled, ...buttonProps }) {
+    const { open, isPending, error } = useOpenAgentConsole({
+        // Spread-if-defined rather than passing the keys through: the package compiles with
+        // `exactOptionalPropertyTypes`, under which an explicit `basePath: undefined` is not assignable
+        // to `basePath?: string`.
+        ...(basePath !== undefined ? { basePath } : {}),
+        ...(headers !== undefined ? { headers } : {}),
+        ...(fetchImpl !== undefined ? { fetch: fetchImpl } : {}),
+        ...(signal !== undefined ? { signal } : {}),
+        ...(navigate !== undefined ? { navigate } : {}),
+    });
+    return (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", ...buttonProps, onClick: open, disabled: disabled || isPending, "aria-busy": isPending || undefined, children: isPending ? (pendingLabel ?? 'Opening…') : (children ?? 'Open AI gateway') }), error &&
+                renderError !== null &&
+                (renderError?.(error) ?? _jsx("p", { role: "alert", children: error.message }))] }));
+}
+//# sourceMappingURL=open-console-button.js.map

package/dist/react/open-console-button.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-console-button.js","sourceRoot":"","sources":["../../src/react/open-console-button.tsx"],"names":[],"mappings":";AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAgB5D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,EACrC,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,OAAO,EACP,KAAK,EAAE,SAAS,EAChB,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,GAAG,WAAW,EACc;IAC5B,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,mBAAmB,CAAC;QACrD,oFAAoF;QACpF,gGAAgG;QAChG,0BAA0B;QAC1B,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3C,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChD,CAAC,CAAC;IAEH,OAAO,CACL,8BACE,iBACE,IAAI,EAAC,QAAQ,KACT,WAAW,EACf,OAAO,EAAE,IAAI,EACb,QAAQ,EAAE,QAAQ,IAAI,SAAS,eACpB,SAAS,IAAI,SAAS,YAEhC,SAAS,CAAC,CAAC,CAAC,CAAC,YAAY,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,iBAAiB,CAAC,GACpE,EACR,KAAK;gBACJ,WAAW,KAAK,IAAI;gBACpB,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,IAAI,YAAG,IAAI,EAAC,OAAO,YAAE,KAAK,CAAC,OAAO,GAAK,CAAC,IAC9D,CACJ,CAAC;AACJ,CAAC"}

package/dist/react/use-open-console.d.ts

@@ -0,0 +1,34 @@
+import { ConsoleSessionError, type OpenConsoleOptions } from '../client/console-session.js';
+/**
+ * React layer over `openAgentConsole` — the middle tier between the bare function
+ * (`../client/console-session.ts`) and the drop-in `<OpenAgentConsoleButton>`.
+ *
+ * You get the state a launcher UI actually needs (in-flight, error) and keep full control of the
+ * markup. Nothing here is AI-gateway-specific beyond the endpoint: it is a mint-then-navigate call
+ * with the two states that call can be in.
+ */
+export interface UseOpenConsoleResult {
+    /** Start the mint-then-navigate. Never rejects — read `error` instead. */
+    open: () => void;
+    /** True from the click until the navigation starts, or until it fails. */
+    isPending: boolean;
+    /** The last refusal, or `null`. Cleared when `open()` is called again. */
+    error: ConsoleSessionError | null;
+    /** Drop a stale error without retrying — e.g. when a dialog closes. */
+    reset: () => void;
+}
+export declare function useOpenAgentConsole(options?: OpenConsoleOptions): UseOpenConsoleResult;
+/**
+ * TanStack Query integration WITHOUT a TanStack dependency: the returned object is the shape
+ * `useMutation` takes, so a host that already uses Query wires the launcher into its own cache,
+ * devtools and error handling with no extra adapter — and a host that doesn't never pays for it.
+ *
+ * ```ts
+ * const { mutate, isPending } = useMutation(openAgentConsoleMutationOptions({ headers }));
+ * ```
+ */
+export declare function openAgentConsoleMutationOptions(options?: OpenConsoleOptions): {
+    mutationKey: readonly unknown[];
+    mutationFn: () => Promise<void>;
+};
+//# sourceMappingURL=use-open-console.d.ts.map

package/dist/react/use-open-console.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-open-console.d.ts","sourceRoot":"","sources":["../../src/react/use-open-console.ts"],"names":[],"mappings":"AACA,OAAO,EACL,mBAAmB,EACnB,KAAK,kBAAkB,EAGxB,MAAM,8BAA8B,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,0EAA0E;IAC1E,SAAS,EAAE,OAAO,CAAC;IACnB,0EAA0E;IAC1E,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAClC,uEAAuE;IACvE,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,kBAAuB,GAAG,oBAAoB,CA2D1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,GAAE,kBAAuB,GAAG;IACjF,WAAW,EAAE,SAAS,OAAO,EAAE,CAAC;IAChC,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC,CAKA"}

package/dist/react/use-open-console.js

@@ -0,0 +1,70 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { ConsoleSessionError, agentConsoleSessionUrl, openAgentConsole, } from '../client/console-session.js';
+export function useOpenAgentConsole(options = {}) {
+    const [isPending, setIsPending] = useState(false);
+    const [error, setError] = useState(null);
+    // Kept in a ref so a caller passing an inline object literal (the common case) doesn't change the
+    // identity of `open` on every render, which would defeat memoizing anything downstream.
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const open = useCallback(() => {
+        setIsPending(true);
+        setError(null);
+        void openAgentConsole(optionsRef.current)
+            .then(() => {
+            // Deliberately NOT clearing `isPending` on success: the navigation is already underway and
+            // this component is about to be torn down. Flipping the button back to idle first produces
+            // a visible flicker of "ready to click again" on a page that is leaving.
+            //
+            // "About to be torn down" is true only until the user presses Back — see the `pageshow`
+            // effect below, which is the other half of this decision.
+        })
+            .catch((cause) => {
+            setError(cause instanceof ConsoleSessionError
+                ? cause
+                : // Anything else got thrown before the client could classify it, so the endpoint is
+                    // the only context worth carrying — `ConsoleSessionError` takes the url, not a kind.
+                    new ConsoleSessionError(String(cause), agentConsoleSessionUrl(optionsRef.current.basePath)));
+            setIsPending(false);
+        });
+    }, []);
+    // The success path above leaves `isPending` stuck on purpose, which is only correct while the
+    // page really is dying. It often isn't: `openAgentConsole` navigates with `location.assign`, and
+    // a browser back/forward-cache hit FREEZES this page instead of destroying it — pressing Back
+    // restores this component with the React state it fell asleep with, so the launcher wakes up
+    // showing a spinner on a button that is disabled forever. Only a bfcache restore fires `pageshow`
+    // with `persisted: true`, which makes it the one signal that distinguishes "you came back" from
+    // "you loaded"; keying off anything looser (a plain `pageshow`, `visibilitychange`, `focus`)
+    // would also fire while a mint is genuinely in flight and reintroduce the flicker the comment
+    // above exists to prevent. So: clear it here, and ONLY here.
+    useEffect(() => {
+        // Guarded rather than assumed: this hook ships in a published package and hosts render it
+        // through SSR, where `window` does not exist. (`window` is never touched at module scope.)
+        if (typeof window === 'undefined')
+            return;
+        const onPageShow = (event) => {
+            if (event.persisted)
+                setIsPending(false);
+        };
+        window.addEventListener('pageshow', onPageShow);
+        return () => window.removeEventListener('pageshow', onPageShow);
+    }, []);
+    const reset = useCallback(() => setError(null), []);
+    return { open, isPending, error, reset };
+}
+/**
+ * TanStack Query integration WITHOUT a TanStack dependency: the returned object is the shape
+ * `useMutation` takes, so a host that already uses Query wires the launcher into its own cache,
+ * devtools and error handling with no extra adapter — and a host that doesn't never pays for it.
+ *
+ * ```ts
+ * const { mutate, isPending } = useMutation(openAgentConsoleMutationOptions({ headers }));
+ * ```
+ */
+export function openAgentConsoleMutationOptions(options = {}) {
+    return {
+        mutationKey: ['agent', 'console', 'open', options.basePath ?? null],
+        mutationFn: () => openAgentConsole(options),
+    };
+}
+//# sourceMappingURL=use-open-console.js.map

package/dist/react/use-open-console.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-open-console.js","sourceRoot":"","sources":["../../src/react/use-open-console.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjE,OAAO,EACL,mBAAmB,EAEnB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,8BAA8B,CAAC;AAqBtC,MAAM,UAAU,mBAAmB,CAAC,UAA8B,EAAE;IAClE,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAA6B,IAAI,CAAC,CAAC;IAErE,kGAAkG;IAClG,wFAAwF;IACxF,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IACnC,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC;IAE7B,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,EAAE;QAC5B,YAAY,CAAC,IAAI,CAAC,CAAC;QACnB,QAAQ,CAAC,IAAI,CAAC,CAAC;QACf,KAAK,gBAAgB,CAAC,UAAU,CAAC,OAAO,CAAC;aACtC,IAAI,CAAC,GAAG,EAAE;YACT,2FAA2F;YAC3F,2FAA2F;YAC3F,yEAAyE;YACzE,EAAE;YACF,wFAAwF;YACxF,0DAA0D;QAC5D,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACxB,QAAQ,CACN,KAAK,YAAY,mBAAmB;gBAClC,CAAC,CAAC,KAAK;gBACP,CAAC,CAAC,mFAAmF;oBACnF,qFAAqF;oBACrF,IAAI,mBAAmB,CACrB,MAAM,CAAC,KAAK,CAAC,EACb,sBAAsB,CAAC,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,CACpD,CACN,CAAC;YACF,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC,CAAC,CAAC;IACP,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,8FAA8F;IAC9F,iGAAiG;IACjG,8FAA8F;IAC9F,6FAA6F;IAC7F,kGAAkG;IAClG,gGAAgG;IAChG,6FAA6F;IAC7F,8FAA8F;IAC9F,6DAA6D;IAC7D,SAAS,CAAC,GAAG,EAAE;QACb,0FAA0F;QAC1F,2FAA2F;QAC3F,IAAI,OAAO,MAAM,KAAK,WAAW;YAAE,OAAO;QAC1C,MAAM,UAAU,GAAG,CAAC,KAA0B,EAAE,EAAE;YAChD,IAAI,KAAK,CAAC,SAAS;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAC3C,CAAC,CAAC;QACF,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QAChD,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IAClE,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAEpD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC3C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,+BAA+B,CAAC,UAA8B,EAAE;IAI9E,OAAO;QACL,WAAW,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAU;QAC5E,UAAU,EAAE,GAAG,EAAE,CAAC,gBAAgB,CAAC,OAAO,CAAC;KAC5C,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-agent-dashboard",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/DavideCarvalho/nestjs-agent.git",
@@ -28,6 +28,11 @@
       "types": "./dist/client/agent-client.d.ts",
       "import": "./dist/client/agent-client.js",
       "default": "./dist/client/agent-client.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "default": "./dist/react/index.js"
     }
   },
   "files": [
@@ -37,9 +42,19 @@
     "@dudousxd/nestjs-agent-core": ">=0.1.0 <1.0.0",
     "@nestjs/common": "^10.0.0 || ^11.0.0",
     "@nestjs/core": "^10.0.0 || ^11.0.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
     "reflect-metadata": "^0.2.0",
     "rxjs": "^7.0.0"
   },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@dudousxd/nestjs-diagnostics": "0.7.0"
   },
@@ -50,11 +65,14 @@
     "@nestjs/testing": "11.1.6",
     "@swc/core": "1.15.41",
     "@tanstack/react-query": "5.62.7",
+    "@testing-library/dom": "10.4.0",
+    "@testing-library/react": "16.3.0",
     "@types/react": "19.2.5",
     "@types/react-dom": "19.2.3",
     "@types/supertest": "6.0.2",
     "@vitejs/plugin-react": "4.3.4",
     "autoprefixer": "10.4.20",
+    "jsdom": "26.1.0",
     "postcss": "8.5.16",
     "react": "19.2.5",
     "react-dom": "19.2.5",
@@ -69,7 +87,7 @@
     "@dudousxd/nestjs-agent-core": "0.10.0"
   },
   "scripts": {
-    "build": "vite build && tsup && tsc -p tsconfig.client.json",
-    "typecheck": "tsc -p tsconfig.server.json --noEmit && tsc -p tsconfig.server.spec.json --noEmit && tsc -p tsconfig.app.json --noEmit"
+    "build": "vite build && tsup && tsc -p tsconfig.client.json && tsc -p tsconfig.react.json",
+    "typecheck": "tsc -p tsconfig.server.json --noEmit && tsc -p tsconfig.server.spec.json --noEmit && tsc -p tsconfig.app.json --noEmit && tsc -p tsconfig.react.spec.json --noEmit"
   }
 }