@dudousxd/nestjs-media-dashboard 0.10.0 → 0.12.0

package/dist/client/console-session.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Headless client for opening the console from YOUR app.
+ *
+ * The console SPA is served at a literal path and knows nothing about your app's auth, so a plain
+ * browser navigation to it carries no identity. Mode A closes that gap: an XHR from inside your app
+ * — which DOES carry your auth — posts to the console's session endpoint, the `session` hook
+ * decides, and the library answers with its own signed cookie. The navigation that follows rides it.
+ *
+ * No UI here on purpose: you own the button, the page and the copy. This module owns the two things
+ * a host would otherwise have to rediscover — where the session endpoint actually lives, and how to
+ * call it without the failure mode below.
+ */
+/**
+ * Where `POST` mints the console session cookie.
+ *
+ * Note this derives from `apiBasePath`, NOT `basePath`: the auth controller is mounted with the
+ * console's JSON API, which `MediaDashboardModule` mounts separately from the SPA. Deriving it here
+ * rather than at the call site means a host cannot get that split wrong, and cannot be silently
+ * broken by the route moving under a version bump — the break would only show up as a runtime 404.
+ */
+export declare function mediaConsoleSessionUrl(apiBasePath?: string): string;
+/** Where the console SPA itself is served. */
+export declare function mediaConsoleUrl(basePath?: string): string;
+export interface OpenConsoleOptions {
+    /** Where the console SPA is mounted. MUST match `MediaDashboardModule.forRoot({ basePath })`. */
+    basePath?: string;
+    /**
+     * Where the console's JSON API — and with it the session endpoint — is mounted. MUST match
+     * `MediaDashboardModule.forRoot({ apiBasePath })`. Defaults to `${basePath}/api`, the same
+     * defaulting the module itself does, so a host that set neither can pass neither.
+     */
+    apiBasePath?: string;
+    /**
+     * Headers for the mint request — in practice your app's `Authorization` header. A function (sync
+     * or async) is accepted so a token can be read at call time rather than captured at wiring time,
+     * which is what a refreshing token needs.
+     */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /** Injected for tests and non-browser callers. Defaults to the global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+    signal?: AbortSignal;
+    /**
+     * Performs the navigation after a successful mint. Defaults to `location.assign`. Override to
+     * route through your own router, or to open in a new tab.
+     */
+    navigate?: (url: string) => void;
+}
+/** Thrown when the session could not be minted. Never thrown after a successful mint. */
+export declare class ConsoleSessionError extends Error {
+    readonly url: string;
+    /** The HTTP status, or `undefined` when the request never produced one (network error). */
+    readonly status?: number | undefined;
+    constructor(message: string, url: string, 
+    /** The HTTP status, or `undefined` when the request never produced one (network error). */
+    status?: number | undefined);
+}
+/**
+ * Mint the console session cookie. Resolves on success; throws {@link ConsoleSessionError} on
+ * refusal. Use this directly when you want to mint without navigating (a pre-flight check, or a
+ * link the user opens later).
+ */
+export declare function mintMediaConsoleSession(options?: OpenConsoleOptions): Promise<void>;
+/**
+ * Mint the session, then navigate to the console. Throws without navigating when the mint is
+ * refused, so a denied user gets a real error instead of landing on the console's
+ * "no session" page — which reads as a bug rather than a permission decision.
+ */
+export declare function openMediaConsole(options?: OpenConsoleOptions): Promise<void>;
+//# sourceMappingURL=console-session.d.ts.map

package/dist/client/console-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-session.d.ts","sourceRoot":"","sources":["../../src/client/console-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAaH;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,GAAE,MAA8B,GAAG,MAAM,CAE1F;AAED,8CAA8C;AAC9C,wBAAgB,eAAe,CAAC,QAAQ,GAAE,MAA0B,GAAG,MAAM,CAE5E;AAED,MAAM,WAAW,kBAAkB;IACjC,iGAAiG;IACjG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IACnE,kFAAkF;IAClF,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AAED,yFAAyF;AACzF,qBAAa,mBAAoB,SAAQ,KAAK;IAG1C,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;gBAHxB,OAAO,EAAE,MAAM,EACN,GAAG,EAAE,MAAM;IACpB,2FAA2F;IAClF,MAAM,CAAC,EAAE,MAAM,YAAA;CAK3B;AAiBD;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkD7F;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKtF"}

package/dist/client/console-session.js

@@ -0,0 +1,120 @@
+/**
+ * Headless client for opening the console from YOUR app.
+ *
+ * The console SPA is served at a literal path and knows nothing about your app's auth, so a plain
+ * browser navigation to it carries no identity. Mode A closes that gap: an XHR from inside your app
+ * — which DOES carry your auth — posts to the console's session endpoint, the `session` hook
+ * decides, and the library answers with its own signed cookie. The navigation that follows rides it.
+ *
+ * No UI here on purpose: you own the button, the page and the copy. This module owns the two things
+ * a host would otherwise have to rediscover — where the session endpoint actually lives, and how to
+ * call it without the failure mode below.
+ */
+/** The mount default; matches `DurableDashboardModule.forRoot()`'s own `basePath` default. */
+const DEFAULT_BASE_PATH = '/media';
+/** Matches `MediaDashboardModule`'s own `apiBasePath` default of `${basePath}/api`. */
+const DEFAULT_API_BASE_PATH = '/media/api';
+function normalizeBasePath(basePath) {
+    const trimmed = basePath.trim().replace(/\/+$/, '');
+    if (trimmed === '')
+        return '';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+/**
+ * Where `POST` mints the console session cookie.
+ *
+ * Note this derives from `apiBasePath`, NOT `basePath`: the auth controller is mounted with the
+ * console's JSON API, which `MediaDashboardModule` mounts separately from the SPA. Deriving it here
+ * rather than at the call site means a host cannot get that split wrong, and cannot be silently
+ * broken by the route moving under a version bump — the break would only show up as a runtime 404.
+ */
+export function mediaConsoleSessionUrl(apiBasePath = DEFAULT_API_BASE_PATH) {
+    return `${normalizeBasePath(apiBasePath)}/session`;
+}
+/** Where the console SPA itself is served. */
+export function mediaConsoleUrl(basePath = DEFAULT_BASE_PATH) {
+    return normalizeBasePath(basePath) || '/';
+}
+/** Thrown when the session could not be minted. Never thrown after a successful mint. */
+export class ConsoleSessionError extends Error {
+    url;
+    status;
+    constructor(message, url, 
+    /** The HTTP status, or `undefined` when the request never produced one (network error). */
+    status) {
+        super(message);
+        this.url = url;
+        this.status = status;
+        this.name = 'ConsoleSessionError';
+    }
+}
+/**
+ * Mirror the module's own defaulting: an explicit `apiBasePath` wins, otherwise it hangs off
+ * `basePath`, so a host that only customised the SPA mount still hits the right session endpoint.
+ */
+function resolveApiBasePath(options) {
+    if (options.apiBasePath !== undefined)
+        return options.apiBasePath;
+    if (options.basePath !== undefined)
+        return `${normalizeBasePath(options.basePath)}/api`;
+    return DEFAULT_API_BASE_PATH;
+}
+async function resolveHeaders(headers) {
+    if (headers === undefined)
+        return {};
+    return typeof headers === 'function' ? await headers() : headers;
+}
+/**
+ * Mint the console session cookie. Resolves on success; throws {@link ConsoleSessionError} on
+ * refusal. Use this directly when you want to mint without navigating (a pre-flight check, or a
+ * link the user opens later).
+ */
+export async function mintMediaConsoleSession(options = {}) {
+    const url = mediaConsoleSessionUrl(resolveApiBasePath(options));
+    const doFetch = options.fetch ?? globalThis.fetch;
+    if (typeof doFetch !== 'function') {
+        throw new ConsoleSessionError('No `fetch` available; pass one via `options.fetch`.', url);
+    }
+    let response;
+    try {
+        response = await doFetch(url, {
+            method: 'POST',
+            // The whole point: the response's Set-Cookie must stick, and the cookie must ride the
+            // navigation that follows.
+            credentials: 'include',
+            headers: await resolveHeaders(options.headers),
+            // Load-bearing, and the reason this helper exists rather than three lines at the call site.
+            // `fetch` FOLLOWS redirects by default, so an app whose auth layer rewrites a 401 into a
+            // "go to /signin" redirect makes this request resolve 200 against the sign-in HTML —
+            // `response.ok` reads true, the caller navigates, and the user lands in a console with no
+            // session, which looks exactly like a permissions bug. Handling the redirect explicitly turns
+            // that into a clear error instead of a silent false success.
+            redirect: 'manual',
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+    }
+    catch (cause) {
+        throw new ConsoleSessionError(`Could not reach the console session endpoint at ${url}: ${String(cause)}`, url);
+    }
+    // `redirect: 'manual'` surfaces differently per runtime: browsers give an opaque response
+    // (`type: 'opaqueredirect'`, status 0), Node/undici gives the real 3xx. Both mean the same thing.
+    const redirected = response.type === 'opaqueredirect' || (response.status >= 300 && response.status < 400);
+    if (redirected) {
+        throw new ConsoleSessionError(`The console session endpoint at ${url} answered with a redirect instead of minting a session. Something in front of it — usually an auth middleware or exception filter that rewrites 401s into a sign-in redirect — is intercepting the response. Exempt this path from that rewrite so the real status reaches this caller.`, url, response.status || undefined);
+    }
+    if (!response.ok) {
+        throw new ConsoleSessionError(`The console refused to open (HTTP ${response.status}).`, url, response.status);
+    }
+}
+/**
+ * Mint the session, then navigate to the console. Throws without navigating when the mint is
+ * refused, so a denied user gets a real error instead of landing on the console's
+ * "no session" page — which reads as a bug rather than a permission decision.
+ */
+export async function openMediaConsole(options = {}) {
+    await mintMediaConsoleSession(options);
+    const target = mediaConsoleUrl(options.basePath);
+    const navigate = options.navigate ?? ((url) => globalThis.location?.assign(url));
+    navigate(target);
+}
+//# sourceMappingURL=console-session.js.map

package/dist/client/console-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-session.js","sourceRoot":"","sources":["../../src/client/console-session.ts"],"names":[],"mappings":"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"}

package/dist/client/index.d.ts

@@ -1,3 +1,4 @@
+export { ConsoleSessionError, mediaConsoleSessionUrl, mediaConsoleUrl, mintMediaConsoleSession, openMediaConsole, type OpenConsoleOptions, } from './console-session.js';
 export * from './types.js';
 export { apiBase, mediaConsoleClient, type MediaConsoleClient } from './media-console-client.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,uBAAuB,EACvB,gBAAgB,EAChB,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAE9B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/client/index.js

@@ -1,3 +1,6 @@
+// Headless console-launcher primitives (path derivation + mint-then-navigate). Re-exported here
+// because `./client` resolves to this file — see the package's `exports` map.
+export { ConsoleSessionError, mediaConsoleSessionUrl, mediaConsoleUrl, mintMediaConsoleSession, openMediaConsole, } from './console-session.js';
 export * from './types.js';
 export { apiBase, mediaConsoleClient } from './media-console-client.js';
 //# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAA2B,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,8EAA8E;AAC9E,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,uBAAuB,EACvB,gBAAgB,GAEjB,MAAM,sBAAsB,CAAC;AAE9B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAA2B,MAAM,2BAA2B,CAAC"}

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;AAGzC,cAAc,8BAA8B,CAAC"}

package/dist/react/index.js

@@ -0,0 +1,15 @@
+// The React tier of `@dudousxd/nestjs-media-dashboard`, published at the `./react` subpath so a
+// host that only mounts the NestJS module never pulls React in. Three levels, pick one:
+//
+//   openMediaConsole(...)        — no React at all (`./client`), you own everything
+//   useOpenMediaConsole(...)     — state for a launcher UI, you own the markup
+//   <OpenMediaConsoleButton />   — drop-in, unstyled, forwards every button prop
+//
+// `openMediaConsoleMutationOptions` 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. Only the console-launcher
+// primitives: `./client` also exports the console's own data client, which a launcher never needs.
+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,4FAA4F;AAC5F,mGAAmG;AACnG,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 OpenMediaConsoleButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'children'>, OpenConsoleOptions {
+    /** Button label. Defaults to "Open Media console". */
+    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 useOpenMediaConsole}.
+     */
+    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 useOpenMediaConsole} (same behaviour,
+ * your markup) or to `openMediaConsole` (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 OpenMediaConsoleButton({ children, pendingLabel, renderError, basePath, apiBasePath, headers, fetch: fetchImpl, signal, navigate, disabled, ...buttonProps }: OpenMediaConsoleButtonProps): 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,sDAAsD;IACtD,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,WAAW,EACX,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 { useOpenMediaConsole } 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 useOpenMediaConsole} (same behaviour,
+ * your markup) or to `openMediaConsole` (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 OpenMediaConsoleButton({ children, pendingLabel, renderError, basePath, apiBasePath, headers, fetch: fetchImpl, signal, navigate, disabled, ...buttonProps }) {
+    // Spread conditionally rather than passing `undefined`: `exactOptionalPropertyTypes` is on, and
+    // an explicit `undefined` is not the same as an absent key to the option defaulting downstream.
+    const { open, isPending, error } = useOpenMediaConsole({
+        ...(basePath !== undefined ? { basePath } : {}),
+        ...(apiBasePath !== undefined ? { apiBasePath } : {}),
+        ...(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 Media console') }), 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,WAAW,EACX,OAAO,EACP,KAAK,EAAE,SAAS,EAChB,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,GAAG,WAAW,EACc;IAC5B,gGAAgG;IAChG,gGAAgG;IAChG,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,mBAAmB,CAAC;QACrD,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,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,oBAAoB,CAAC,GACvE,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,41 @@
+import { type OpenConsoleOptions } from '../client/console-session.js';
+/**
+ * React layer over `openMediaConsole` — the middle tier between the bare function
+ * (`../client/console-session.ts`) and the drop-in `<OpenMediaConsoleButton>`.
+ *
+ * You get the state a launcher UI actually needs (in-flight, error) and keep full control of the
+ * markup. Nothing here is Media-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.
+     *
+     * Typed as `Error` rather than `ConsoleSessionError` because `ConsoleSessionError` carries the
+     * session endpoint it was refused by, and a failure that did not come from the mint (a `navigate`
+     * override that throws) has no endpoint to attribute — inventing one would be a lie. Every
+     * refusal from the mint itself IS a `ConsoleSessionError`, so `instanceof` narrows.
+     */
+    error: Error | null;
+    /** Drop a stale error without retrying — e.g. when a dialog closes. */
+    reset: () => void;
+}
+export declare function useOpenMediaConsole(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(openMediaConsoleMutationOptions({ headers }));
+ * ```
+ */
+export declare function openMediaConsoleMutationOptions(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,EAAE,KAAK,kBAAkB,EAAoB,MAAM,8BAA8B,CAAC;AAEzF;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,0EAA0E;IAC1E,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;OAOG;IACH,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,uEAAuE;IACvE,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,kBAAuB,GAAG,oBAAoB,CA2B1F;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,CAeA"}

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

@@ -0,0 +1,52 @@
+import { useCallback, useRef, useState } from 'react';
+import { openMediaConsole } from '../client/console-session.js';
+export function useOpenMediaConsole(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 openMediaConsole(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 Error ? cause : new Error(String(cause)));
+            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(openMediaConsoleMutationOptions({ headers }));
+ * ```
+ */
+export function openMediaConsoleMutationOptions(options = {}) {
+    return {
+        // Both mounts points are in the key: `apiBasePath` decides which endpoint mints the session and
+        // is settable independently of `basePath` (flip mounts the console API under its own `/api`
+        // prefix), so two mounts differing only in it are two different calls and must not share cache
+        // state.
+        mutationKey: [
+            'media',
+            'console',
+            'open',
+            options.basePath ?? null,
+            options.apiBasePath ?? null,
+        ],
+        mutationFn: () => openMediaConsole(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,EAA2B,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AA4BzF,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,CAAe,IAAI,CAAC,CAAC;IAEvD,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;QAC3E,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACxB,QAAQ,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACpE,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,+BAA+B,CAAC,UAA8B,EAAE;IAI9E,OAAO;QACL,gGAAgG;QAChG,4FAA4F;QAC5F,+FAA+F;QAC/F,SAAS;QACT,WAAW,EAAE;YACX,OAAO;YACP,SAAS;YACT,MAAM;YACN,OAAO,CAAC,QAAQ,IAAI,IAAI;YACxB,OAAO,CAAC,WAAW,IAAI,IAAI;SACnB;QACV,UAAU,EAAE,GAAG,EAAE,CAAC,gBAAgB,CAAC,OAAO,CAAC;KAC5C,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-media-dashboard",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Standalone navigable /media console (disks, live uploads, media library) for nestjs-media — a bundled React SPA served by NestJS",
   "license": "MIT",
   "author": "Davide Carvalho",
@@ -23,6 +23,11 @@
       "types": "./dist/client/index.d.ts",
       "import": "./dist/client/index.js",
       "default": "./dist/client/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "default": "./dist/react/index.js"
     }
   },
   "files": [
@@ -31,19 +36,32 @@
   "peerDependencies": {
     "@nestjs/common": "^10.0.0 || ^11.0.0",
     "@nestjs/core": "^10.0.0 || ^11.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
     "rxjs": "^7.0.0",
     "@dudousxd/nestjs-media-core": "0.8.0"
   },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@nestjs/common": "11.1.26",
     "@nestjs/core": "11.1.26",
     "@nestjs/platform-express": "11.1.26",
     "@nestjs/testing": "11.1.26",
     "@tanstack/react-query": "5.62.7",
+    "@testing-library/dom": "10.4.1",
+    "@testing-library/react": "16.1.0",
     "@types/react": "18.3.18",
     "@types/react-dom": "18.3.5",
     "@vitejs/plugin-react": "4.3.4",
     "autoprefixer": "10.4.20",
+    "jsdom": "25.0.1",
     "postcss": "8.4.49",
     "react": "18.3.1",
     "react-dom": "18.3.1",
@@ -58,7 +76,7 @@
     "@dudousxd/nestjs-media-core": "0.8.0"
   },
   "scripts": {
-    "build": "vite build && tsup && tsc -p tsconfig.client.json",
-    "typecheck": "tsc -p tsconfig.server.json --noEmit && tsc -p tsconfig.app.json --noEmit && tsc -p tsconfig.spec.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.app.json --noEmit && tsc -p tsconfig.react.json --noEmit && tsc -p tsconfig.spec.json --noEmit"
   }
 }