@dudousxd/nestjs-telescope-ui 1.17.0 → 1.18.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @dudousxd/nestjs-telescope-ui
 
+## 1.18.0
+
+### Minor Changes
+
+- [#63](https://github.com/DavideCarvalho/nestjs-telescope/pull/63) [`2d0e76e`](https://github.com/DavideCarvalho/nestjs-telescope/commit/2d0e76ee52e3a556c24b567fdb4b9e6cef25c067) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - **Headless console launcher: `openTelescopeConsole` / `mintTelescopeConsoleSession` / `telescopeConsoleSessionUrl`, exported from `@dudousxd/nestjs-telescope-ui/client`.**
+
+  The console is entered from the HOST's app: a browser navigation to it carries no identity, so
+  something inside the host has to mint the Mode A session cookie first (an XHR that _does_ carry the
+  host's auth), then navigate. Every host was writing that by hand, which meant hardcoding two things
+  this package owns:
+
+  - **the session endpoint's path** — `<path>/api/auth/session`. Nothing tells a host when that moves; the break
+    only shows up as a runtime 404 after a version bump.
+  - **`redirect: 'manual'`** — and this one is a real trap. `fetch` follows redirects by default, so a
+    host whose auth layer rewrites a 401 into a sign-in redirect gets a resolved 200 against the
+    sign-in HTML. `response.ok` reads true, the caller navigates, and the user lands in a console with
+    no session — indistinguishable from a permissions bug. The helper detects the redirect (browser
+    opaque response _and_ Node/undici 3xx) and throws a message naming the likely cause.
+
+  ```ts
+  import { openTelescopeConsole } from "@dudousxd/nestjs-telescope-ui/client";
+
+  await openTelescopeConsole({
+    headers: () => ({ Authorization: `Bearer ${token()}` }),
+  });
+  ```
+
+  No UI: the host owns the button, the page and the copy. `headers` accepts a sync or async function
+  so a refreshing token is read at call time rather than captured at wiring time. `fetch` and
+  `navigate` are injectable (tests, routers, non-browser callers). A refused mint throws
+  `ConsoleSessionError` (carrying `status` and `url`) and **does not navigate** — a denied user gets a
+  real error instead of the console's "no session" page.
+
+  Additive only: nothing existing changes.
+
 ## 1.17.0
 
 ### Minor Changes

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

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ *
+ * Telescope's mount is configured as `path` (no leading slash, e.g. `'telescope'`); this accepts either
+ * form and normalizes 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.
+ *
+ * Derived from `basePath` rather than hardcoded by the caller: this package owns the route (the auth
+ * controller lives under the configured mount), so a host that hardcodes it
+ * is guessing at something that can change under a version bump — with no compile error when it
+ * does, because the break only shows up as a 404 at runtime.
+ */
+export declare function telescopeConsoleSessionUrl(basePath?: string): string;
+/** Where the console SPA itself is served. */
+export declare function telescopeConsoleUrl(basePath?: string): string;
+export interface OpenConsoleOptions {
+    /** Where the console is mounted. MUST match `TelescopeUiModule.forRoot({ path }) / TelescopeModule.forRoot({ path })`. */
+    basePath?: 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 mintTelescopeConsoleSession(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 openTelescopeConsole(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;;;;;;;;;;;;;;GAcG;AAWH;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,GAAE,MAA0B,GAAG,MAAM,CAEvF;AAED,8CAA8C;AAC9C,wBAAgB,mBAAmB,CAAC,QAAQ,GAAE,MAA0B,GAAG,MAAM,CAEhF;AAED,MAAM,WAAW,kBAAkB;IACjC,0HAA0H;IAC1H,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;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;AAOD;;;;GAIG;AACH,wBAAsB,2BAA2B,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkDjG;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAK1F"}

package/dist/client/console-session.js

@@ -0,0 +1,110 @@
+/**
+ * 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.
+ *
+ * Telescope's mount is configured as `path` (no leading slash, e.g. `'telescope'`); this accepts either
+ * form and normalizes 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 `TelescopeUiModule.forRoot()`'s own default. */
+const DEFAULT_BASE_PATH = '/telescope';
+function normalizeBasePath(basePath) {
+    const trimmed = basePath.trim().replace(/\/+$/, '');
+    if (trimmed === '')
+        return '';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+/**
+ * Where `POST` mints the console session cookie.
+ *
+ * Derived from `basePath` rather than hardcoded by the caller: this package owns the route (the auth
+ * controller lives under the configured mount), so a host that hardcodes it
+ * is guessing at something that can change under a version bump — with no compile error when it
+ * does, because the break only shows up as a 404 at runtime.
+ */
+export function telescopeConsoleSessionUrl(basePath = DEFAULT_BASE_PATH) {
+    return `${normalizeBasePath(basePath)}/api/auth/session`;
+}
+/** Where the console SPA itself is served. */
+export function telescopeConsoleUrl(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';
+    }
+}
+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 mintTelescopeConsoleSession(options = {}) {
+    const url = telescopeConsoleSessionUrl(options.basePath);
+    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 openTelescopeConsole(options = {}) {
+    await mintTelescopeConsoleSession(options);
+    const target = telescopeConsoleUrl(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, telescopeConsoleSessionUrl, telescopeConsoleUrl, mintTelescopeConsoleSession, openTelescopeConsole, type OpenConsoleOptions, } from './console-session.js';
 export { createTelescopeClient } from './telescope-client.js';
 export type { BulkActionName, JobActionName, TelescopeClient, TelescopeClientOptions, } from './telescope-client.js';
 export type * from './types.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,YAAY,EACV,cAAc,EACd,aAAa,EACb,eAAe,EACf,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAC/B,mBAAmB,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,mBAAmB,EACnB,2BAA2B,EAC3B,oBAAoB,EACpB,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,YAAY,EACV,cAAc,EACd,aAAa,EACb,eAAe,EACf,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAC/B,mBAAmB,YAAY,CAAC"}

package/dist/client/index.js

@@ -1,2 +1,5 @@
+// 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, telescopeConsoleSessionUrl, telescopeConsoleUrl, mintTelescopeConsoleSession, openTelescopeConsole, } from './console-session.js';
 export { createTelescopeClient } from './telescope-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,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,8EAA8E;AAC9E,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,mBAAmB,EACnB,2BAA2B,EAC3B,oBAAoB,GAErB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-telescope-ui",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "Bundled dashboard + composable React components for @dudousxd/nestjs-telescope.",
   "license": "MIT",
   "repository": {