@xeonr/renderer-sdk 1.3.0 → 1.5.1

package/src/react/useReportFatalError.tsx

@@ -1,71 +0,0 @@
-import { useCallback, useState } from 'react';
-
-/**
- * Hook for surfacing async failures to `<RendererErrorBoundary>` (and from
- * there to the host's crash overlay + telemetry).
- *
- * Renderers shouldn't render their own "Upload not found" / "Failed to
- * load" inline UI — those are still crashes from a telemetry standpoint,
- * and the host already owns a polished overlay with reload + fallback
- * actions. This hook lets a renderer take an error caught in an async
- * context (fetch `.catch()`, useEffect cleanup, etc.) and route it to
- * the host instead of rendering a half-broken inline state.
- *
- * Pattern:
- *
- * ```tsx
- * const reportFatal = useReportFatalError();
- * useEffect(() => {
- *   client.getUpload(...).catch(reportFatal);
- * }, []);
- * ```
- *
- * Mechanics: we keep an error in component state. When set, the *next*
- * render throws it — React's error-handling pipeline catches the throw
- * and bubbles to the nearest boundary. From there
- * `RendererErrorBoundary.componentDidCatch` reports the crash to the
- * host and renders nothing, and the host overlay (Reload / Copy /
- * Fallback) takes over the visible iframe area.
- *
- * Why state-then-throw rather than a direct `throw err`? You can't
- * throw to React from async code — React only sees throws that happen
- * during render or in event handlers. Routing through state ensures
- * the throw lands inside the render phase.
- *
- * The returned callback is stable across renders so it's safe to drop
- * straight into a `.catch()`.
- */
-export function useReportFatalError(): (err: unknown) => void {
-	// Generic state slot — we never read the value, only use the
-	// updater. We narrow to `never` so TypeScript stops us from
-	// accidentally using it as data anywhere.
-	const [, setState] = useState<never>();
-	return useCallback((err: unknown) => {
-		// Functional updater throws — React invokes it during the next
-		// render attempt, which puts the throw inside the render phase
-		// where boundaries can see it.
-		setState(() => {
-			if (err instanceof Error) {
-				throw err;
-			}
-			// Wrap non-Error throws so the boundary always sees a real
-			// Error instance with a meaningful .name / .message. Without
-			// this, `client.reportCrash` would synthesise a generic
-			// 'UnknownError' which loses the original payload's shape.
-			if (typeof err === 'string') {
-				throw new Error(err);
-			}
-			if (err && typeof err === 'object' && 'message' in err && typeof err.message === 'string') {
-				const wrapped = new Error(err.message);
-				if ('name' in err && typeof err.name === 'string') {
-					wrapped.name = err.name;
-				}
-				if ('stack' in err && typeof err.stack === 'string') {
-					wrapped.stack = err.stack;
-				}
-				throw wrapped;
-			}
-			throw new Error('Unknown renderer error');
-		});
-	}, []);
-}

package/src/types.ts

@@ -1,138 +0,0 @@
-/**
- * config.json schema — lives at the root of a renderer archive.
- * Validated server-side on upload; provided to the renderer in the init message.
- */
-export interface RendererConfig {
-	version: 1;
-	/** Permissions the renderer requests from the host. */
-	permissions?: RendererPermission[];
-	sandbox?: {
-		allowPopups?: boolean;
-		allowForms?: boolean;
-		allowDownloads?: boolean;
-	};
-	/**
-	 * Extra origins this renderer needs to reach via `fetch` / `XMLHttpRequest`
-	 * / WebSocket. Surfaced to the browser as additional entries in the CSP
-	 * `connect-src` directive. The upl.im API + auth hosts are always allowed
-	 * by the renderer-proxy; only list extras here (e.g. a third-party API
-	 * the renderer integrates with).
-	 *
-	 * Each entry is a fully-qualified origin like `https://api.example.com`
-	 * or a wildcarded host like `https://*.example.com`. No paths, no
-	 * trailing slashes. Origins are validated at deploy time.
-	 */
-	connectHosts?: string[];
-	/**
-	 * Short build identifier the build pipeline stamps into config.json
-	 * (e.g. the renderer-plugin-vite hash of the output directory).
-	 * Surfaced in crash telemetry as a separate dimension so we can
-	 * distinguish "crashed in build A" from "crashed in build B" even
-	 * when both builds share the same archive_upload_id (the developer
-	 * republished without bumping the archive). Bounded to 64 chars.
-	 */
-	buildHash?: string;
-	/**
-	 * When true, the SDK holds `uplim:ack` until the renderer explicitly
-	 * calls `markReady()` from `useRendererClient()`. The host's loading
-	 * overlay stays visible until that signal arrives, so the user
-	 * never sees a blank canvas between bridge ack and the renderer's
-	 * first paint.
-	 *
-	 * Leave unset (or `false`) for fast renderers where the gap is
-	 * invisible — that's the right default and lowest-friction pattern
-	 * (image, code, plain markdown). Set `true` when the renderer takes
-	 * perceptible time to settle (large file fetch, video decode,
-	 * multi-page paginate) and the blank-canvas flash is noticeable.
-	 *
-	 * The SDK auto-acks after 30s (configurable via
-	 * `RendererClientOptions.readyTimeoutMs`) and logs a warning if
-	 * `markReady()` never fires — so a forgotten signal can't trap
-	 * users behind the overlay.
-	 */
-	deferReady?: boolean;
-}
-
-export type RendererPermission =
-	| 'createFolder'
-	| 'openUpload';
-
-/**
- * What resource the renderer is scoped to.
- * Sent from host to iframe in the init message.
- */
-export type RendererScope =
-	| RendererBucketScope
-	| RendererFolderScope
-	| RendererUploadScope
-	| RendererVirtualFileScope;
-
-export interface RendererBucketScope {
-	type: 'bucket';
-	bucketId: string;
-}
-
-export interface RendererFolderScope {
-	type: 'folder';
-	bucketId: string;
-	folderId: string;
-	path: string;
-}
-
-export interface RendererUploadScope {
-	type: 'upload';
-	bucketId: string;
-	uploadId: string;
-}
-
-export interface RendererVirtualFileScope {
-	type: 'virtual-file';
-	bucketId: string;
-	folderId?: string;
-	path: string;
-}
-
-/**
- * How the renderer is being displayed within the dashboard entrypoint.
- * A single renderer may handle multiple rendering types.
- */
-export type RenderingType =
-	| 'bucket-renderer'
-	| 'folder-renderer'
-	| 'preview-modal';
-
-/**
- * API adapter compatible with `IUploadAdapterEnv` from `@xeonr/uploads-sdk`.
- * Pass this to `getUploadClientWithEnv()` to get a pre-configured API client
- * that handles authentication and token refresh automatically.
- */
-export interface RendererApiAdapter {
-	hostname?: string;
-	tokenHelper?: () => Promise<string | null>;
-	onAuthenticationExpired?: (retryCount: number) => Promise<boolean>;
-	onAuthenticationFailed?: () => Promise<any>;
-}
-
-/** Payload received by the renderer on initialization. */
-export interface InitPayload {
-	/** Protocol version. */
-	version: 1;
-	/** Integration access token scoped to the integration's client. */
-	token: string;
-	/** Unix timestamp (ms) when the token expires. */
-	tokenExpiresAt: number;
-	/** Current host theme. */
-	theme: 'light' | 'dark';
-	/** Which entrypoint was loaded. */
-	entrypoint: 'dashboard' | 'portal';
-	/** What resource the renderer is scoped to. */
-	scope: RendererScope;
-	/** How the renderer is being displayed (dashboard only). */
-	renderingType: RenderingType;
-	/** Base URL for upl.im API calls. */
-	apiBaseUrl: string;
-	/** The parsed config.json from the renderer archive. */
-	config: RendererConfig;
-	/** Initial hash path to navigate to, derived from the host URL fragment. */
-	initialPath?: string;
-}

package/tsconfig.json

@@ -1,18 +0,0 @@
-{
-	"compilerOptions": {
-		"target": "ES2022",
-		"module": "ESNext",
-		"moduleResolution": "bundler",
-		"declaration": true,
-		"declarationMap": true,
-		"sourceMap": true,
-		"outDir": "./dist",
-		"rootDir": "./src",
-		"jsx": "react-jsx",
-		"strict": true,
-		"esModuleInterop": true,
-		"skipLibCheck": true,
-		"forceConsistentCasingInFileNames": true
-	},
-	"include": ["src"]
-}

package/tsconfig.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["./src/client.ts","./src/index.ts","./src/protocol.ts","./src/types.ts","./src/react/index.ts","./src/react/userendererclient.ts"],"version":"5.9.3"}