@xeonr/renderer-sdk 1.0.4

package/src/client.ts

@@ -0,0 +1,426 @@
+import type {
+	HostInitMessage,
+	HostMessage,
+	HostThemeUpdateMessage,
+	HostTokenRefreshMessage,
+	HostGenerateTokenResultMessage,
+	IframeHistoryPushMessage,
+	IframeHistoryReplaceMessage,
+} from './protocol.js';
+import { isHostMessage } 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;
+}
+
+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 currentPath: string = '/';
+
+	private listener: ((event: MessageEvent) => void) | null = null;
+	private hashChangeListener: (() => void) | 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 ?? '*';
+		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;
+	}
+
+	/**
+	 * 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;
+		if (this.listener) {
+			window.removeEventListener('message', this.listener);
+			this.listener = 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;
+
+			this.handleMessage(event.data);
+		};
+
+		window.addEventListener('message', this.listener);
+
+		// Tell the host we're ready
+		this.postToHost({ type: 'uplim:ready' });
+	}
+
+	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;
+
+		// 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);
+		}
+
+		// Tell the host we've processed init and are ready to be displayed
+		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);
+	}
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+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,
+} from './protocol.js';
+
+export type {
+	HostMessage,
+	HostInitMessage,
+	HostThemeUpdateMessage,
+	HostTokenRefreshMessage,
+	HostGenerateTokenResultMessage,
+	HostHistoryBackMessage,
+	HostHistoryForwardMessage,
+	IframeMessage,
+	IframeReadyMessage,
+	IframeOpenUploadMessage,
+	IframeTokenRequestMessage,
+	IframeCloseMessage,
+	IframeInitAckMessage,
+	IframeGenerateTokenMessage,
+	IframeHistoryPushMessage,
+	IframeHistoryReplaceMessage,
+	RendererMessage,
+} from './protocol.js';

package/src/protocol.ts

@@ -0,0 +1,144 @@
+import type { InitPayload } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Message namespace — all messages use this prefix
+// ---------------------------------------------------------------------------
+export const MESSAGE_PREFIX = 'uplim:' as const;
+export const PROTOCOL_VERSION = 1 as const;
+
+// ---------------------------------------------------------------------------
+// Host → Iframe messages
+// ---------------------------------------------------------------------------
+
+/** Sent after the iframe reports 'ready'. Contains everything the renderer needs to bootstrap. */
+export interface HostInitMessage {
+	type: 'uplim:init';
+	payload: InitPayload;
+}
+
+/** Sent when the host theme changes. */
+export interface HostThemeUpdateMessage {
+	type: 'uplim:theme';
+	theme: 'light' | 'dark';
+}
+
+/** Sent proactively or in response to a token request. */
+export interface HostTokenRefreshMessage {
+	type: 'uplim:token';
+	token: string;
+	tokenExpiresAt: number;
+}
+
+/** Sent in response to a generateToken request from the iframe. */
+export interface HostGenerateTokenResultMessage {
+	type: 'uplim:generateTokenResult';
+	requestId: string;
+	accepted: boolean;
+}
+
+/** Tell the iframe to go back in its history. */
+export interface HostHistoryBackMessage {
+	type: 'uplim:historyBack';
+}
+
+/** Tell the iframe to go forward in its history. */
+export interface HostHistoryForwardMessage {
+	type: 'uplim:historyForward';
+}
+
+export type HostMessage =
+	| HostInitMessage
+	| HostThemeUpdateMessage
+	| HostTokenRefreshMessage
+	| HostGenerateTokenResultMessage
+	| HostHistoryBackMessage
+	| HostHistoryForwardMessage;
+
+// ---------------------------------------------------------------------------
+// Iframe → Host messages
+// ---------------------------------------------------------------------------
+
+/** Iframe is loaded and ready to receive the init message. */
+export interface IframeReadyMessage {
+	type: 'uplim:ready';
+}
+
+/** Request the host to open a specific upload (e.g. in a preview modal). */
+export interface IframeOpenUploadMessage {
+	type: 'uplim:openUpload';
+	uploadId: string;
+}
+
+/** Request a fresh delegated token. Host responds with HostTokenRefreshMessage. */
+export interface IframeTokenRequestMessage {
+	type: 'uplim:tokenRequest';
+}
+
+/** Request the host to close the renderer (relevant for modal mode). */
+export interface IframeCloseMessage {
+	type: 'uplim:close';
+}
+
+/** Acknowledge that init has been processed and the renderer is ready to be displayed. */
+export interface IframeInitAckMessage {
+	type: 'uplim:ack';
+}
+
+/** Request the host to prompt the user to generate a long-lived token. */
+export interface IframeGenerateTokenMessage {
+	type: 'uplim:generateToken';
+	requestId: string;
+	reason: string;
+	duration: 'forever' | string;
+}
+
+/** Notify the host that the renderer navigated to a new hash path. */
+export interface IframeHistoryPushMessage {
+	type: 'uplim:historyPush';
+	path: string;
+}
+
+/** Notify the host that the renderer replaced the current hash path. */
+export interface IframeHistoryReplaceMessage {
+	type: 'uplim:historyReplace';
+	path: string;
+}
+
+export type IframeMessage =
+	| IframeReadyMessage
+	| IframeOpenUploadMessage
+	| IframeTokenRequestMessage
+	| IframeCloseMessage
+	| IframeInitAckMessage
+	| IframeGenerateTokenMessage
+	| IframeHistoryPushMessage
+	| IframeHistoryReplaceMessage;
+
+// ---------------------------------------------------------------------------
+// Union type for any message
+// ---------------------------------------------------------------------------
+export type RendererMessage = HostMessage | IframeMessage;
+
+// ---------------------------------------------------------------------------
+// Type guard helpers
+// ---------------------------------------------------------------------------
+export function isRendererMessage(data: unknown): data is RendererMessage {
+	return (
+		typeof data === 'object' &&
+		data !== null &&
+		'type' in data &&
+		typeof (data as { type: unknown }).type === 'string' &&
+		(data as { type: string }).type.startsWith(MESSAGE_PREFIX)
+	);
+}
+
+export function isHostMessage(data: unknown): data is HostMessage {
+	if (!isRendererMessage(data)) return false;
+	const t = data.type;
+	return t === 'uplim:init' || t === 'uplim:theme' || t === 'uplim:token' || t === 'uplim:generateTokenResult' || t === 'uplim:historyBack' || t === 'uplim:historyForward';
+}
+
+export function isIframeMessage(data: unknown): data is IframeMessage {
+	if (!isRendererMessage(data)) return false;
+	return !isHostMessage(data);
+}

package/src/react/index.ts

@@ -0,0 +1,2 @@
+export { useRendererClient } from './useRendererClient.js';
+export type { UseRendererClientOptions, UseRendererClientResult } from './useRendererClient.js';