@dudousxd/nestjs-telescope-ui 1.18.0 → 1.20.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # @dudousxd/nestjs-telescope-ui
 
+## 1.20.0
+
+### Minor Changes
+
+- [#67](https://github.com/DavideCarvalho/nestjs-telescope/pull/67) [`87c8732`](https://github.com/DavideCarvalho/nestjs-telescope/commit/87c8732006a46eeea50d1dd1536c8a9794a13ae5) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Ship the console launcher on its own subpath: `@dudousxd/nestjs-telescope-ui/react/console`.
+
+  The launcher was only reachable from the `./react` barrel, which re-exports the whole dashboard
+  component set and therefore pulls in `recharts` and `react-router-dom`. Neither is declared by this
+  package, and a bundler resolves re-exported modules even when nothing references them — so a host
+  that wanted nothing but the launcher button got a hard build failure on a missing dependency
+  instead of tree-shaking it away.
+
+  `./react/console` re-exports the hook, the button and the headless client primitives, and nothing
+  else. Its entire dependency footprint is `react`, guarded by a test that walks the import graph.
+
+  `./react` is unchanged and still exports the launcher, so nothing breaks.
+
+## 1.19.0
+
+### Minor Changes
+
+- [#65](https://github.com/DavideCarvalho/nestjs-telescope/pull/65) [`be97836`](https://github.com/DavideCarvalho/nestjs-telescope/commit/be978365f716cbe9e120b4024abb5d0ff6129d3d) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - **React tier for the console launcher: `useOpenTelescopeConsole` and `<OpenTelescopeConsoleButton>`, exported from `@dudousxd/nestjs-telescope-ui/react`.**
+
+  The headless `openTelescopeConsole` gave hosts the mint-then-navigate call; every host then wrote the
+  same three lines of React around it — an `isPending` flag, an error slot, and a button that has to
+  remember not to fire twice. Three tiers now, pick the one that fits and drop a level when it stops
+  fitting:
+
+  ```tsx
+  import {
+    OpenTelescopeConsoleButton,
+    useOpenTelescopeConsole,
+    openTelescopeConsoleMutationOptions,
+  } from "@dudousxd/nestjs-telescope-ui/react";
+
+  // 1. drop-in
+  <OpenTelescopeConsoleButton
+    className="btn btn-primary"
+    headers={authHeaders}
+  />;
+
+  // 2. state only, your markup
+  const { open, isPending, error, reset } = useOpenTelescopeConsole({
+    headers: authHeaders,
+  });
+
+  // 3. openTelescopeConsole(...) from `/client` — no React at all
+  ```
+
+  - `open()` **never rejects**; the refusal lands in `error` as a `ConsoleSessionError` (with its
+    `status` and `url`). It deliberately does not clear `isPending` on success, because the navigation
+    is already underway and flipping back to idle flickers "ready to click again" on a page that is
+    leaving.
+  - `<OpenTelescopeConsoleButton>` is **unstyled on purpose** — a bare `<button>` that forwards
+    `className`/`style`/every other button prop, so it inherits the host's design system instead of
+    importing CSS that fights it. It renders inside the host app, not inside Telescope's own bundle.
+    It disables itself and sets `aria-busy` while in flight, and renders the refusal as
+    `<p role="alert">` by default: a launcher that silently does nothing reads as broken rather than
+    forbidden. `renderError` substitutes that node; `renderError={null}` opts out entirely.
+  - `openTelescopeConsoleMutationOptions()` returns the `{ mutationKey, mutationFn }` shape
+    `useMutation` takes, so a host already on TanStack Query gets the launcher in its cache, devtools
+    and error handling with no adapter — and this package still never imports `@tanstack/react-query`.
+
+  React stays an optional peer dependency: a host that only mounts the NestJS module pulls none of
+  this in. Additive only; nothing existing changes.
+
 ## 1.18.0
 
 ### Minor Changes

package/dist/react/console.d.ts

@@ -0,0 +1,4 @@
+export * from './use-open-console.js';
+export * from './open-console-button.js';
+export { ConsoleSessionError, telescopeConsoleSessionUrl, telescopeConsoleUrl, mintTelescopeConsoleSession, openTelescopeConsole, type OpenConsoleOptions, } from '../client/console-session.js';
+//# sourceMappingURL=console.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../src/react/console.ts"],"names":[],"mappings":"AAUA,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,mBAAmB,EACnB,2BAA2B,EAC3B,oBAAoB,EACpB,KAAK,kBAAkB,GACxB,MAAM,8BAA8B,CAAC"}

package/dist/react/console.js

@@ -0,0 +1,14 @@
+// The console launcher on its own subpath (`@dudousxd/nestjs-telescope-ui/react/console`).
+//
+// It is also exported from `./react`, but that barrel re-exports the whole dashboard component set,
+// which pulls in `recharts` and `react-router-dom`. Those are not declared by this package, so a
+// host that wants ONLY the launcher — the common case, a button on an admin page — cannot import
+// from the barrel: a bundler resolves re-exported modules even when nothing uses them, and the
+// build fails on the missing dependency rather than tree-shaking it away.
+//
+// This entry re-exports only the launcher and the headless primitives it wraps, so its entire
+// dependency footprint is `react`.
+export * from './use-open-console.js';
+export * from './open-console-button.js';
+export { ConsoleSessionError, telescopeConsoleSessionUrl, telescopeConsoleUrl, mintTelescopeConsoleSession, openTelescopeConsole, } from '../client/console-session.js';
+//# sourceMappingURL=console.js.map

package/dist/react/console.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.js","sourceRoot":"","sources":["../../src/react/console.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,EAAE;AACF,oGAAoG;AACpG,iGAAiG;AACjG,iGAAiG;AACjG,+FAA+F;AAC/F,0EAA0E;AAC1E,EAAE;AACF,8FAA8F;AAC9F,mCAAmC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,mBAAmB,EACnB,2BAA2B,EAC3B,oBAAoB,GAErB,MAAM,8BAA8B,CAAC"}

package/dist/react/index.d.ts

@@ -1,6 +1,8 @@
 export * from './telescope-context.js';
 export * from './use-telescope-queries.js';
 export * from './use-telescope-stream.js';
+export * from './use-open-console.js';
+export * from './open-console-button.js';
 export * from './components/entry-types.js';
 export * from './components/entries-table.js';
 export * from './components/user-tag.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qCAAqC,CAAC;AACpD,cAAc,wBAAwB,CAAC;AACvC,cAAc,qCAAqC,CAAC;AACpD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,kCAAkC,CAAC;AACjD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAK1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qCAAqC,CAAC;AACpD,cAAc,wBAAwB,CAAC;AACvC,cAAc,qCAAqC,CAAC;AACpD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,kCAAkC,CAAC;AACjD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oBAAoB,CAAC"}

package/dist/react/index.js

@@ -1,6 +1,12 @@
 export * from './telescope-context.js';
 export * from './use-telescope-queries.js';
 export * from './use-telescope-stream.js';
+// Console launcher, three tiers: `openTelescopeConsole` (no React, from `./client`),
+// `useOpenTelescopeConsole` (state only, your markup), `<OpenTelescopeConsoleButton>` (drop-in).
+// `openTelescopeConsoleMutationOptions` 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';
 export * from './components/entry-types.js';
 export * from './components/entries-table.js';
 export * from './components/user-tag.js';

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qCAAqC,CAAC;AACpD,cAAc,wBAAwB,CAAC;AACvC,cAAc,qCAAqC,CAAC;AACpD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,kCAAkC,CAAC;AACjD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,qFAAqF;AACrF,iGAAiG;AACjG,6FAA6F;AAC7F,iCAAiC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qCAAqC,CAAC;AACpD,cAAc,wBAAwB,CAAC;AACvC,cAAc,qCAAqC,CAAC;AACpD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,kCAAkC,CAAC;AACjD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oBAAoB,CAAC"}

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

@@ -0,0 +1,28 @@
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
+import type { OpenConsoleOptions } from '../client/console-session.js';
+export interface OpenTelescopeConsoleButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'children'>, OpenConsoleOptions {
+    /** Button label. Defaults to "Open Telescope". */
+    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 useOpenTelescopeConsole}.
+     */
+    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. That matters more here than for the dashboard's own components: this one
+ * renders inside the HOST's app, not inside Telescope's Tailwind bundle. When it doesn't fit, drop
+ * to {@link useOpenTelescopeConsole} (same behaviour, your markup) or to `openTelescopeConsole` (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 OpenTelescopeConsoleButton({ children, pendingLabel, renderError, basePath, headers, fetch: fetchImpl, signal, navigate, disabled, ...buttonProps }: OpenTelescopeConsoleButtonProps): 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,+BACf,SAAQ,IAAI,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC,EAC3E,kBAAkB;IACpB,kDAAkD;IAClD,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;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,OAAO,EACP,KAAK,EAAE,SAAS,EAChB,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,GAAG,WAAW,EACf,EAAE,+BAA+B,GAAG,GAAG,CAAC,OAAO,CAyB/C"}

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

@@ -0,0 +1,28 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useOpenTelescopeConsole } 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. That matters more here than for the dashboard's own components: this one
+ * renders inside the HOST's app, not inside Telescope's Tailwind bundle. When it doesn't fit, drop
+ * to {@link useOpenTelescopeConsole} (same behaviour, your markup) or to `openTelescopeConsole` (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 OpenTelescopeConsoleButton({ children, pendingLabel, renderError, basePath, headers, fetch: fetchImpl, signal, navigate, disabled, ...buttonProps }) {
+    const { open, isPending, error } = useOpenTelescopeConsole({
+        ...(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 Telescope') }), 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,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAgBhE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,0BAA0B,CAAC,EACzC,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,OAAO,EACP,KAAK,EAAE,SAAS,EAChB,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,GAAG,WAAW,EACkB;IAChC,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,uBAAuB,CAAC;QACzD,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,gBAAgB,CAAC,GACnE,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 `openTelescopeConsole` — the middle tier between the bare function
+ * (`../client/console-session.ts`) and the drop-in `<OpenTelescopeConsoleButton>`.
+ *
+ * You get the state a launcher UI actually needs (in-flight, error) and keep full control of the
+ * markup. Nothing here is Telescope-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 useOpenTelescopeConsole(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(openTelescopeConsoleMutationOptions({ headers }));
+ * ```
+ */
+export declare function openTelescopeConsoleMutationOptions(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,uBAAuB,CAAC,OAAO,GAAE,kBAAuB,GAAG,oBAAoB,CAoC9F;AAED;;;;;;;;GAQG;AACH,wBAAgB,mCAAmC,CAAC,OAAO,GAAE,kBAAuB,GAAG;IACrF,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,46 @@
+import { useCallback, useRef, useState } from 'react';
+import { ConsoleSessionError, openTelescopeConsole, telescopeConsoleSessionUrl, } from '../client/console-session.js';
+export function useOpenTelescopeConsole(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 openTelescopeConsole(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.
+        })
+            .catch((cause) => {
+            setError(cause instanceof ConsoleSessionError
+                ? cause
+                : // A non-`ConsoleSessionError` can only come from the caller's own `navigate`, so name
+                    // the endpoint this hook was pointed at rather than leaving `url` empty.
+                    new ConsoleSessionError(String(cause), telescopeConsoleSessionUrl(optionsRef.current.basePath)));
+            setIsPending(false);
+        });
+    }, []);
+    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(openTelescopeConsoleMutationOptions({ headers }));
+ * ```
+ */
+export function openTelescopeConsoleMutationOptions(options = {}) {
+    return {
+        mutationKey: ['telescope', 'console', 'open', options.basePath ?? null],
+        mutationFn: () => openTelescopeConsole(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,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACtD,OAAO,EACL,mBAAmB,EAEnB,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,8BAA8B,CAAC;AAqBtC,MAAM,UAAU,uBAAuB,CAAC,UAA8B,EAAE;IACtE,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,oBAAoB,CAAC,UAAU,CAAC,OAAO,CAAC;aAC1C,IAAI,CAAC,GAAG,EAAE;YACT,2FAA2F;YAC3F,2FAA2F;YAC3F,yEAAyE;QAC3E,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACxB,QAAQ,CACN,KAAK,YAAY,mBAAmB;gBAClC,CAAC,CAAC,KAAK;gBACP,CAAC,CAAC,sFAAsF;oBACtF,yEAAyE;oBACzE,IAAI,mBAAmB,CACrB,MAAM,CAAC,KAAK,CAAC,EACb,0BAA0B,CAAC,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,CACxD,CACN,CAAC;YACF,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC,CAAC,CAAC;IACP,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,mCAAmC,CAAC,UAA8B,EAAE;IAIlF,OAAO;QACL,WAAW,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAU;QAChF,UAAU,EAAE,GAAG,EAAE,CAAC,oBAAoB,CAAC,OAAO,CAAC;KAChD,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-telescope-ui",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "description": "Bundled dashboard + composable React components for @dudousxd/nestjs-telescope.",
   "license": "MIT",
   "repository": {
@@ -27,6 +27,11 @@
       "import": "./dist/react/index.js",
       "default": "./dist/react/index.js"
     },
+    "./react/console": {
+      "types": "./dist/react/console.d.ts",
+      "import": "./dist/react/console.js",
+      "default": "./dist/react/console.js"
+    },
     "./client": {
       "types": "./dist/client/index.d.ts",
       "import": "./dist/client/index.js",
@@ -42,6 +47,9 @@
   "peerDependencies": {
     "@nestjs/common": ">=11.0.0",
     "@nestjs/core": ">=11.0.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
+    "@tanstack/react-query": ">=5.0.0",
     "@dudousxd/nestjs-telescope": "^1.24.0"
   },
   "peerDependenciesMeta": {