@xeonr/renderer-sdk 1.3.0 → 1.5.1

package/src/client.ts

@@ -1,619 +0,0 @@
-import type {
-	HostInitMessage,
-	HostMessage,
-	HostThemeUpdateMessage,
-	HostTokenRefreshMessage,
-	HostGenerateTokenResultMessage,
-	IframeHistoryPushMessage,
-	IframeHistoryReplaceMessage,
-	IframeCrashMessage,
-	RendererCrashKind,
-} from './protocol.js';
-import { buildCrashMessage, isHostMessage, postCrashToHost } from './protocol.js';
-import type { InitPayload, RendererApiAdapter, RendererConfig, RendererScope, RenderingType } from './types.js';
-
-export interface RendererClientOptions {
-	/**
-	 * Expected origin of the host application.
-	 * If set, messages from other origins are silently ignored.
-	 * If omitted, all origins are accepted (suitable for local dev).
-	 */
-	targetOrigin?: string;
-
-	/**
-	 * How long after init to wait for `signalReady()` before auto-acking
-	 * anyway, in milliseconds. Only honored when the renderer's
-	 * `config.json` has `deferReady: true`. Default 30000 (30s).
-	 * Matches the host bridge's 10s init-timeout × ~3 — enough headroom
-	 * for slow data fetches without leaving the user staring at a
-	 * loading overlay indefinitely.
-	 */
-	readyTimeoutMs?: number;
-}
-
-type InitCallback = (payload: InitPayload) => void;
-type ThemeCallback = (theme: 'light' | 'dark') => void;
-type TokenCallback = (token: string, expiresAt: number) => void;
-type NavigateCallback = (path: string) => void;
-
-/**
- * Client SDK for custom renderers running inside a sandboxed iframe.
- *
- * Usage:
- * ```ts
- * import { RendererClient } from '@xeonr/renderer-sdk';
- *
- * const client = new RendererClient();
- *
- * client.onInit((payload) => {
- *   console.log('Received scope:', payload.scope);
- *   console.log('Token:', payload.token);
- *   // Bootstrap your app here
- * });
- *
- * client.onThemeChange((theme) => {
- *   document.documentElement.setAttribute('data-theme', theme);
- * });
- * ```
- */
-export class RendererClient {
-	private targetOrigin: string;
-	private initCallbacks: InitCallback[] = [];
-	private themeCallbacks: ThemeCallback[] = [];
-	private tokenCallbacks: TokenCallback[] = [];
-	private navigateCallbacks: NavigateCallback[] = [];
-
-	private currentToken: string | null = null;
-	private currentTokenExpiresAt: number | null = null;
-	private currentScope: RendererScope | null = null;
-	private currentRenderingType: RenderingType | null = null;
-	private currentConfig: RendererConfig | null = null;
-	private currentTheme: 'light' | 'dark' = 'light';
-	private currentApiBaseUrl: string | null = null;
-	private currentEntrypoint: 'dashboard' | 'portal' | null = null;
-	private currentPath: string = '/';
-	private currentConnected = false;
-
-	private listener: ((event: MessageEvent) => void) | null = null;
-	private errorListener: ((event: ErrorEvent) => void) | null = null;
-	private rejectionListener: ((event: PromiseRejectionEvent) => void) | null = null;
-	private hashChangeListener: (() => void) | null = null;
-	// `signalReady` machinery — see `deferReady` in RendererClientOptions.
-	// `ackDeferred` is set at construction; `ackSent` flips when we
-	// actually post the ack so signalReady stays idempotent.
-	private ackDeferred = false;
-	private ackSent = false;
-	private readyTimeoutMs = 30_000;
-	private readyTimeoutHandle: ReturnType<typeof setTimeout> | null = null;
-	private readyRetryInterval: ReturnType<typeof setInterval> | null = null;
-	private readyRetryTimeout: ReturnType<typeof setTimeout> | null = null;
-	private historyPatched = false;
-	private originalPushState: typeof history.pushState | null = null;
-	private originalReplaceState: typeof history.replaceState | null = null;
-	private destroyed = false;
-	private suppressHashChange = false;
-	private pendingTokenResolvers: Array<(result: { token: string; expiresAt: number }) => void> = [];
-	private pendingGenerateTokenResolvers: Map<string, { resolve: (result: { accepted: boolean }) => void; reject: (error: Error) => void }> = new Map();
-	private apiAdapter: RendererApiAdapter | null = null;
-
-	constructor(options?: RendererClientOptions) {
-		this.targetOrigin = options?.targetOrigin ?? '*';
-		// `ackDeferred` is decided by config.json (read in handleInit)
-		// rather than the constructor — the SDK can't know which mode
-		// the renderer wants until init lands, but that's fine because
-		// the ack itself only fires after init anyway.
-		if (typeof options?.readyTimeoutMs === 'number' && options.readyTimeoutMs > 0) {
-			this.readyTimeoutMs = options.readyTimeoutMs;
-		}
-		this.setup();
-	}
-
-	// ---------------------------------------------------------------------------
-	// Lifecycle
-	// ---------------------------------------------------------------------------
-
-	/** Register a callback for when the host sends the init message. */
-	onInit(cb: InitCallback): () => void {
-		this.initCallbacks.push(cb);
-		return () => {
-			this.initCallbacks = this.initCallbacks.filter(c => c !== cb);
-		};
-	}
-
-	// ---------------------------------------------------------------------------
-	// Receive from host
-	// ---------------------------------------------------------------------------
-
-	/** Register a callback for host theme changes. */
-	onThemeChange(cb: ThemeCallback): () => void {
-		this.themeCallbacks.push(cb);
-		return () => {
-			this.themeCallbacks = this.themeCallbacks.filter(c => c !== cb);
-		};
-	}
-
-	/** Register a callback for token refreshes from the host. */
-	onTokenRefresh(cb: TokenCallback): () => void {
-		this.tokenCallbacks.push(cb);
-		return () => {
-			this.tokenCallbacks = this.tokenCallbacks.filter(c => c !== cb);
-		};
-	}
-
-	/** Register a callback for hash-based navigation changes. */
-	onNavigate(cb: NavigateCallback): () => void {
-		this.navigateCallbacks.push(cb);
-		return () => {
-			this.navigateCallbacks = this.navigateCallbacks.filter(c => c !== cb);
-		};
-	}
-
-	// ---------------------------------------------------------------------------
-	// Send to host
-	// ---------------------------------------------------------------------------
-
-	/** Request the host to open a specific upload. */
-	openUpload(uploadId: string): void {
-		this.postToHost({ type: 'uplim:openUpload', uploadId });
-	}
-
-	/** Request a fresh integration access token from the host. */
-	requestToken(): void {
-		this.postToHost({ type: 'uplim:tokenRequest' });
-	}
-
-	/** Request a fresh token and wait for the response. */
-	requestTokenAsync(): Promise<{ token: string; expiresAt: number }> {
-		return new Promise((resolve) => {
-			this.pendingTokenResolvers.push(resolve);
-			this.postToHost({ type: 'uplim:tokenRequest' });
-		});
-	}
-
-	/** Request the host to close this renderer (modal mode). */
-	close(): void {
-		this.postToHost({ type: 'uplim:close' });
-	}
-
-	/**
-	 * Request the host to prompt the user to generate a long-lived token.
-	 * The token is displayed to the user but never returned to the renderer.
-	 * Resolves with `{ accepted: true }` if the user accepts, or `{ accepted: false }` if rejected.
-	 */
-	generateToken(opts: { reason: string; duration: 'forever' | string }): Promise<{ accepted: boolean }> {
-		const requestId = crypto.randomUUID();
-		return new Promise((resolve, reject) => {
-			this.pendingGenerateTokenResolvers.set(requestId, { resolve, reject });
-			this.postToHost({
-				type: 'uplim:generateToken',
-				requestId,
-				reason: opts.reason,
-				duration: opts.duration,
-			});
-		});
-	}
-
-	// ---------------------------------------------------------------------------
-	// Getters
-	// ---------------------------------------------------------------------------
-
-	/** Get the current integration access token. */
-	getToken(): string | null {
-		return this.currentToken;
-	}
-
-	/** Get the token expiry as a Unix timestamp (ms). */
-	getTokenExpiresAt(): number | null {
-		return this.currentTokenExpiresAt;
-	}
-
-	/** Check if the current token is expired or about to expire (within 30s). */
-	isTokenExpired(): boolean {
-		if (!this.currentTokenExpiresAt) return true;
-		return Date.now() >= this.currentTokenExpiresAt - 30_000;
-	}
-
-	/** Get the current scope. */
-	getScope(): RendererScope | null {
-		return this.currentScope;
-	}
-
-	/** Get the current rendering type. */
-	getRenderingType(): RenderingType | null {
-		return this.currentRenderingType;
-	}
-
-	/** Get the renderer config from config.json. */
-	getConfig(): RendererConfig | null {
-		return this.currentConfig;
-	}
-
-	/** Get the current theme. */
-	getTheme(): 'light' | 'dark' {
-		return this.currentTheme;
-	}
-
-	/** Get the current hash path (e.g. '/settings/advanced'). */
-	getPath(): string {
-		return this.currentPath;
-	}
-
-	/** Has the init message been processed? Late subscribers (e.g. a
-	 * second `useRendererClient` mount after init landed) read this to
-	 * seed their initial state without waiting for the next onInit. */
-	isConnected(): boolean {
-		return this.currentConnected;
-	}
-
-	/** Which HTML entrypoint was loaded (dashboard or portal). */
-	getEntrypoint(): 'dashboard' | 'portal' | null {
-		return this.currentEntrypoint;
-	}
-
-	/** Base URL for upl.im API calls, as supplied by the host. */
-	getApiBaseUrl(): string | null {
-		return this.currentApiBaseUrl;
-	}
-
-	/**
-	 * Returns an API adapter compatible with `getUploadClientWithEnv()` from `@xeonr/uploads-sdk`.
-	 * Handles authentication and automatic token refresh via the host bridge.
-	 *
-	 * ```ts
-	 * import { getUploadClientWithEnv } from '@xeonr/uploads-sdk/api/base';
-	 * import { BucketUploadsService } from '@xeonr/uploads-protocol/uplim/api/v1/uploads_pb';
-	 *
-	 * const adapter = client.getApiAdapter();
-	 * const uploadsClient = getUploadClientWithEnv(BucketUploadsService, adapter);
-	 * ```
-	 */
-	getApiAdapter(): RendererApiAdapter {
-		if (this.apiAdapter) return this.apiAdapter;
-
-		// Use a getter so hostname reflects the latest apiBaseUrl (set on init)
-		const self = this;
-		this.apiAdapter = {
-			get hostname() { return self.currentApiBaseUrl ?? undefined; },
-			tokenHelper: async () => this.currentToken,
-			onAuthenticationExpired: async (retryCount: number) => {
-				if (retryCount > 0) return false;
-				const result = await this.requestTokenAsync();
-				return !!result.token;
-			},
-		};
-
-		return this.apiAdapter;
-	}
-
-	// ---------------------------------------------------------------------------
-	// Cleanup
-	// ---------------------------------------------------------------------------
-
-	/** Remove all listeners and stop the client. */
-	destroy(): void {
-		this.destroyed = true;
-		this.stopReadyRetry();
-		if (this.readyTimeoutHandle) {
-			clearTimeout(this.readyTimeoutHandle);
-			this.readyTimeoutHandle = null;
-		}
-		if (this.listener) {
-			window.removeEventListener('message', this.listener);
-			this.listener = null;
-		}
-		if (this.errorListener) {
-			window.removeEventListener('error', this.errorListener);
-			this.errorListener = null;
-		}
-		if (this.rejectionListener) {
-			window.removeEventListener('unhandledrejection', this.rejectionListener);
-			this.rejectionListener = null;
-		}
-		if (this.hashChangeListener) {
-			window.removeEventListener('hashchange', this.hashChangeListener);
-			this.hashChangeListener = null;
-		}
-		if (this.historyPatched) {
-			if (this.originalPushState) window.history.pushState = this.originalPushState;
-			if (this.originalReplaceState) window.history.replaceState = this.originalReplaceState;
-			this.historyPatched = false;
-		}
-		this.initCallbacks = [];
-		this.themeCallbacks = [];
-		this.tokenCallbacks = [];
-		this.navigateCallbacks = [];
-		for (const [, pending] of this.pendingGenerateTokenResolvers) {
-			pending.reject(new Error('Client destroyed'));
-		}
-		this.pendingGenerateTokenResolvers.clear();
-	}
-
-	// ---------------------------------------------------------------------------
-	// Internal
-	// ---------------------------------------------------------------------------
-
-	private setup(): void {
-		this.listener = (event: MessageEvent) => {
-			if (this.destroyed) return;
-			if (this.targetOrigin !== '*' && event.origin !== this.targetOrigin) return;
-			if (!isHostMessage(event.data)) return;
-
-			// Any valid host message implies the host's listener is attached and the
-			// handshake is underway, so stop pinging.
-			this.stopReadyRetry();
-			this.handleMessage(event.data);
-		};
-
-		window.addEventListener('message', this.listener);
-
-		this.installCrashHooks();
-
-		// Tell the host we're ready. We retry on an interval because a fast iframe can
-		// post 'ready' before the host has attached its message listener — the first
-		// ping is lost, the host times out, and the user has to click retry. Pinging
-		// until the host responds closes that race without changing the protocol.
-		this.postToHost({ type: 'uplim:ready' });
-		this.readyRetryInterval = setInterval(() => {
-			if (this.destroyed) return;
-			this.postToHost({ type: 'uplim:ready' });
-		}, 200);
-		// Bound the retries: if the host genuinely isn't there after 8s, stop pinging
-		// so we don't spam a misbehaving parent.
-		this.readyRetryTimeout = setTimeout(() => {
-			this.stopReadyRetry();
-		}, 8000);
-	}
-
-	private stopReadyRetry(): void {
-		if (this.readyRetryInterval) {
-			clearInterval(this.readyRetryInterval);
-			this.readyRetryInterval = null;
-		}
-		if (this.readyRetryTimeout) {
-			clearTimeout(this.readyRetryTimeout);
-			this.readyRetryTimeout = null;
-		}
-	}
-
-	private handleMessage(message: HostMessage): void {
-		switch (message.type) {
-			case 'uplim:init':
-				this.handleInit(message);
-				break;
-			case 'uplim:theme':
-				this.handleThemeUpdate(message);
-				break;
-			case 'uplim:token':
-				this.handleTokenRefresh(message);
-				break;
-			case 'uplim:generateTokenResult':
-				this.handleGenerateTokenResult(message);
-				break;
-			case 'uplim:historyBack':
-				window.history.back();
-				break;
-			case 'uplim:historyForward':
-				window.history.forward();
-				break;
-		}
-	}
-
-	private handleInit(message: HostInitMessage): void {
-		const { payload } = message;
-		this.currentToken = payload.token;
-		this.currentTokenExpiresAt = payload.tokenExpiresAt;
-		this.currentScope = payload.scope;
-		this.currentRenderingType = payload.renderingType;
-		this.currentConfig = payload.config;
-		this.currentTheme = payload.theme;
-		this.currentApiBaseUrl = payload.apiBaseUrl;
-		this.currentEntrypoint = payload.entrypoint;
-		this.currentConnected = true;
-
-		// Apply initial path from host URL fragment
-		if (payload.initialPath) {
-			this.suppressHashChange = true;
-			window.location.hash = payload.initialPath;
-			this.currentPath = payload.initialPath;
-			this.suppressHashChange = false;
-		} else {
-			this.currentPath = this.getHashPath();
-		}
-
-		// Start observing hash changes
-		this.setupHashTracking();
-
-		for (const cb of this.initCallbacks) {
-			cb(payload);
-		}
-
-		// Ack semantics — driven by the renderer's config.json
-		// (`deferReady` field). Declaring it in config rather than as a
-		// constructor option keeps all renderer metadata in one place
-		// (alongside permissions / sandbox / connectHosts / buildHash)
-		// and avoids a code-vs-config-disagreement footgun.
-		this.ackDeferred = payload.config?.deferReady === true;
-		if (!this.ackDeferred) {
-			this.sendAck();
-		} else {
-			this.readyTimeoutHandle = setTimeout(() => {
-				if (this.destroyed || this.ackSent) return;
-				// Best-effort log so an operator can spot the late ack
-				// in dev tools; production console noise is acceptable
-				// here because this only fires when something is wrong.
-				console.warn(
-					'[uplim] signalReady() not called within ' +
-					this.readyTimeoutMs + 'ms — auto-acking so the host overlay can dismiss.',
-				);
-				this.sendAck();
-			}, this.readyTimeoutMs);
-		}
-	}
-
-	/**
-	 * Post the deferred ack so the host overlay dismisses. No-op once
-	 * the ack has been sent (the host-side bridge tolerates duplicates
-	 * but we suppress them here for cleanliness). When `deferReady` was
-	 * not set on construction this is also a no-op — the SDK already
-	 * acked synchronously on init.
-	 */
-	signalReady(): void {
-		if (this.destroyed || this.ackSent || !this.ackDeferred) return;
-		this.sendAck();
-	}
-
-	private sendAck(): void {
-		if (this.ackSent) return;
-		this.ackSent = true;
-		if (this.readyTimeoutHandle) {
-			clearTimeout(this.readyTimeoutHandle);
-			this.readyTimeoutHandle = null;
-		}
-		this.postToHost({ type: 'uplim:ack' });
-	}
-
-	private handleThemeUpdate(message: HostThemeUpdateMessage): void {
-		this.currentTheme = message.theme;
-		for (const cb of this.themeCallbacks) {
-			cb(message.theme);
-		}
-	}
-
-	private handleTokenRefresh(message: HostTokenRefreshMessage): void {
-		this.currentToken = message.token;
-		this.currentTokenExpiresAt = message.tokenExpiresAt;
-
-		// Resolve any pending requestTokenAsync() calls
-		const resolvers = this.pendingTokenResolvers;
-		this.pendingTokenResolvers = [];
-		for (const resolve of resolvers) {
-			resolve({ token: message.token, expiresAt: message.tokenExpiresAt });
-		}
-
-		for (const cb of this.tokenCallbacks) {
-			cb(message.token, message.tokenExpiresAt);
-		}
-	}
-
-	private handleGenerateTokenResult(message: HostGenerateTokenResultMessage): void {
-		const pending = this.pendingGenerateTokenResolvers.get(message.requestId);
-		if (pending) {
-			this.pendingGenerateTokenResolvers.delete(message.requestId);
-			pending.resolve({ accepted: message.accepted });
-		}
-	}
-
-	private getHashPath(): string {
-		const hash = window.location.hash;
-		if (!hash || hash === '#') return '/';
-		// Strip leading '#' (and optional leading '#/')
-		return hash.startsWith('#/') ? hash.slice(1) : hash.slice(1);
-	}
-
-	private onHashChanged(isPush: boolean): void {
-		if (this.destroyed || this.suppressHashChange) return;
-
-		const newPath = this.getHashPath();
-		if (newPath === this.currentPath) return;
-
-		this.currentPath = newPath;
-
-		const msg: IframeHistoryPushMessage | IframeHistoryReplaceMessage = isPush
-			? { type: 'uplim:historyPush', path: newPath }
-			: { type: 'uplim:historyReplace', path: newPath };
-		this.postToHost(msg);
-
-		for (const cb of this.navigateCallbacks) {
-			cb(newPath);
-		}
-	}
-
-	private setupHashTracking(): void {
-		if (this.hashChangeListener) return;
-
-		// Listen for direct hash changes (e.g. window.location.hash = '...' or <a href="#...">)
-		this.hashChangeListener = () => this.onHashChanged(true);
-		window.addEventListener('hashchange', this.hashChangeListener);
-
-		// Patch pushState/replaceState — hash routers use these instead of setting
-		// window.location.hash directly, and they don't fire hashchange.
-		this.originalPushState = window.history.pushState.bind(window.history);
-		this.originalReplaceState = window.history.replaceState.bind(window.history);
-
-		const self = this;
-		window.history.pushState = function (...args: Parameters<typeof history.pushState>) {
-			self.originalPushState!(...args);
-			self.onHashChanged(true);
-		};
-		window.history.replaceState = function (...args: Parameters<typeof history.replaceState>) {
-			self.originalReplaceState!(...args);
-			self.onHashChanged(false);
-		};
-		this.historyPatched = true;
-	}
-
-	private postToHost(message: object): void {
-		if (this.destroyed) return;
-		window.parent.postMessage(message, this.targetOrigin);
-	}
-
-	/**
-	 * Install window-level crash hooks the moment the client is constructed
-	 * (i.e. as soon as a renderer touches the SDK). We deliberately do this
-	 * here — not in a React-only entry point — so that even renderers that
-	 * forget to wrap their root in `<RendererErrorBoundary>` still report
-	 * async / global failures to the host.
-	 *
-	 * The two hooks cover the failure modes a React boundary can't see:
-	 *   - `window.error` — synchronous throws outside React's tree (raw
-	 *     <script> bugs, event-handler exceptions, image onerror handlers).
-	 *   - `unhandledrejection` — Promise chains with no `.catch()`, which
-	 *     are surprisingly common in fetch-heavy renderers.
-	 *
-	 * Both fire-and-forget via `postCrashToHost`; the host decides whether
-	 * to render the overlay (a single render-time crash usually warrants
-	 * it, a stray unhandled rejection may not).
-	 */
-	private installCrashHooks(): void {
-		if (typeof window === 'undefined') return;
-
-		this.errorListener = (event: ErrorEvent) => {
-			if (this.destroyed) return;
-			// Prefer event.error for the real stack; fall back to a synthetic
-			// shape when the browser only gave us message/filename/lineno
-			// (cross-origin scripts strip event.error to null).
-			const thrown = event.error ?? {
-				name: 'ErrorEvent',
-				message: event.message || 'Uncaught error',
-				stack: event.filename
-					? `at ${event.filename}:${event.lineno ?? '?'}:${event.colno ?? '?'}`
-					: '',
-			};
-			this.reportCrash('error', thrown);
-		};
-		window.addEventListener('error', this.errorListener);
-
-		this.rejectionListener = (event: PromiseRejectionEvent) => {
-			if (this.destroyed) return;
-			this.reportCrash('unhandled-rejection', event.reason);
-		};
-		window.addEventListener('unhandledrejection', this.rejectionListener);
-	}
-
-	/**
-	 * Forward a crash to the host. Called by the global hooks and by
-	 * `<RendererErrorBoundary>`; renderers may also call it explicitly if
-	 * they catch something themselves and want it surfaced (e.g. data-load
-	 * failure that wipes the UI even though no exception escaped).
-	 *
-	 * No-throw: telemetry must never make the underlying crash worse.
-	 */
-	reportCrash(kind: RendererCrashKind, thrown: unknown): void {
-		try {
-			const msg: IframeCrashMessage = buildCrashMessage(kind, thrown);
-			postCrashToHost(msg, this.targetOrigin);
-		} catch {
-			// Swallowed on purpose — see above.
-		}
-	}
-}

package/src/index.ts

@@ -1,47 +0,0 @@
-export { RendererClient } from './client.js';
-export type { RendererClientOptions } from './client.js';
-
-export type {
-	RendererConfig,
-	RendererPermission,
-	RendererScope,
-	RendererBucketScope,
-	RendererFolderScope,
-	RendererUploadScope,
-	RendererVirtualFileScope,
-	RenderingType,
-	InitPayload,
-	RendererApiAdapter,
-} from './types.js';
-
-export {
-	MESSAGE_PREFIX,
-	PROTOCOL_VERSION,
-	isRendererMessage,
-	isHostMessage,
-	isIframeMessage,
-	buildCrashMessage,
-	postCrashToHost,
-} from './protocol.js';
-
-export type {
-	HostMessage,
-	HostInitMessage,
-	HostThemeUpdateMessage,
-	HostTokenRefreshMessage,
-	HostGenerateTokenResultMessage,
-	HostHistoryBackMessage,
-	HostHistoryForwardMessage,
-	IframeMessage,
-	IframeReadyMessage,
-	IframeOpenUploadMessage,
-	IframeTokenRequestMessage,
-	IframeCloseMessage,
-	IframeInitAckMessage,
-	IframeGenerateTokenMessage,
-	IframeHistoryPushMessage,
-	IframeHistoryReplaceMessage,
-	IframeCrashMessage,
-	RendererCrashKind,
-	RendererMessage,
-} from './protocol.js';