@xeonr/renderer-sdk 1.0.4

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/react/useRendererClient.d.ts

@@ -0,0 +1,61 @@
+import { RendererClient } from '../client.js';
+import type { RendererClientOptions } from '../client.js';
+import type { RendererApiAdapter, RendererConfig, RendererScope, RenderingType } from '../types.js';
+export interface UseRendererClientOptions extends RendererClientOptions {
+}
+export interface UseRendererClientResult {
+    /** Whether the host has sent the init message. */
+    connected: boolean;
+    /** What resource the renderer is scoped to. */
+    scope: RendererScope | null;
+    /** How the renderer is being displayed. */
+    renderingType: RenderingType | null;
+    /** The current integration access token. */
+    token: string | null;
+    /** Unix timestamp (ms) when the token expires. */
+    tokenExpiresAt: number | null;
+    /** The current host theme. */
+    theme: 'light' | 'dark';
+    /** The parsed config.json from the renderer archive. */
+    config: RendererConfig | null;
+    /** Which entrypoint was loaded (dashboard or portal). */
+    entrypoint: 'dashboard' | 'portal' | null;
+    /** Base URL for upl.im API calls. */
+    apiBaseUrl: string | null;
+    /** Pre-configured API adapter for use with `getUploadClientWithEnv()`. */
+    apiAdapter: RendererApiAdapter;
+    /** Current hash path within the renderer (e.g. '/settings'). Updated reactively on hash changes. */
+    path: string;
+    /** Request the host to open a specific upload. */
+    openUpload: (uploadId: string) => void;
+    /** Request a fresh integration access token. */
+    requestToken: () => void;
+    /** Request the host to close this renderer (modal mode). */
+    close: () => void;
+    /** The underlying RendererClient instance for advanced use. */
+    client: RendererClient;
+}
+/**
+ * React hook for building custom renderers.
+ *
+ * Creates a `RendererClient` instance, manages its lifecycle, and exposes
+ * reactive state that triggers re-renders when the host sends messages.
+ *
+ * ```tsx
+ * import { useRendererClient } from '@xeonr/renderer-sdk/react';
+ *
+ * function App() {
+ *   const { connected, scope, renderingType, theme, token } = useRendererClient();
+ *
+ *   if (!connected) return <div>Connecting...</div>;
+ *
+ *   return (
+ *     <div data-theme={theme}>
+ *       <pre>{JSON.stringify(scope, null, 2)}</pre>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useRendererClient(options?: UseRendererClientOptions): UseRendererClientResult;
+//# sourceMappingURL=useRendererClient.d.ts.map

package/dist/react/useRendererClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRendererClient.d.ts","sourceRoot":"","sources":["../../src/react/useRendererClient.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAe,MAAM,aAAa,CAAC;AAEjH,MAAM,WAAW,wBAAyB,SAAQ,qBAAqB;CAAG;AAE1E,MAAM,WAAW,uBAAuB;IACvC,kDAAkD;IAClD,SAAS,EAAE,OAAO,CAAC;IACnB,+CAA+C;IAC/C,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IAC5B,2CAA2C;IAC3C,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;IACpC,4CAA4C;IAC5C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,kDAAkD;IAClD,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,8BAA8B;IAC9B,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,wDAAwD;IACxD,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAC9B,yDAAyD;IACzD,UAAU,EAAE,WAAW,GAAG,QAAQ,GAAG,IAAI,CAAC;IAC1C,qCAAqC;IACrC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,0EAA0E;IAC1E,UAAU,EAAE,kBAAkB,CAAC;IAC/B,oGAAoG;IACpG,IAAI,EAAE,MAAM,CAAC;IAEb,kDAAkD;IAClD,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,gDAAgD;IAChD,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,IAAI,CAAC;IAElB,+DAA+D;IAC/D,MAAM,EAAE,cAAc,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,uBAAuB,CAgF7F"}

package/dist/react/useRendererClient.js

@@ -0,0 +1,96 @@
+import { useState, useRef, useEffect, useMemo } from 'react';
+import { RendererClient } from '../client.js';
+/**
+ * React hook for building custom renderers.
+ *
+ * Creates a `RendererClient` instance, manages its lifecycle, and exposes
+ * reactive state that triggers re-renders when the host sends messages.
+ *
+ * ```tsx
+ * import { useRendererClient } from '@xeonr/renderer-sdk/react';
+ *
+ * function App() {
+ *   const { connected, scope, renderingType, theme, token } = useRendererClient();
+ *
+ *   if (!connected) return <div>Connecting...</div>;
+ *
+ *   return (
+ *     <div data-theme={theme}>
+ *       <pre>{JSON.stringify(scope, null, 2)}</pre>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useRendererClient(options) {
+    const clientRef = useRef(null);
+    // Lazy-init the client (only once)
+    if (clientRef.current === null) {
+        clientRef.current = new RendererClient(options);
+    }
+    const client = clientRef.current;
+    const [connected, setConnected] = useState(false);
+    const [scope, setScope] = useState(null);
+    const [renderingType, setRenderingType] = useState(null);
+    const [token, setToken] = useState(null);
+    const [tokenExpiresAt, setTokenExpiresAt] = useState(null);
+    const [theme, setTheme] = useState('light');
+    const [config, setConfig] = useState(null);
+    const [entrypoint, setEntrypoint] = useState(null);
+    const [apiBaseUrl, setApiBaseUrl] = useState(null);
+    const [path, setPath] = useState('/');
+    useEffect(() => {
+        const unsubInit = client.onInit((payload) => {
+            setConnected(true);
+            setScope(payload.scope);
+            setRenderingType(payload.renderingType);
+            setToken(payload.token);
+            setTokenExpiresAt(payload.tokenExpiresAt);
+            setTheme(payload.theme);
+            setConfig(payload.config);
+            setEntrypoint(payload.entrypoint);
+            setApiBaseUrl(payload.apiBaseUrl);
+            setPath(client.getPath());
+            document.documentElement.dataset.theme = payload.theme;
+        });
+        const unsubTheme = client.onThemeChange((newTheme) => {
+            setTheme(newTheme);
+            document.documentElement.dataset.theme = newTheme;
+        });
+        const unsubToken = client.onTokenRefresh((newToken, newExpiresAt) => {
+            setToken(newToken);
+            setTokenExpiresAt(newExpiresAt);
+        });
+        const unsubNavigate = client.onNavigate((newPath) => {
+            setPath(newPath);
+        });
+        return () => {
+            unsubInit();
+            unsubTheme();
+            unsubToken();
+            unsubNavigate();
+            client.destroy();
+        };
+    }, [client]);
+    const methods = useMemo(() => ({
+        openUpload: (uploadId) => client.openUpload(uploadId),
+        requestToken: () => client.requestToken(),
+        close: () => client.close(),
+        apiAdapter: client.getApiAdapter(),
+    }), [client]);
+    return {
+        connected,
+        scope,
+        renderingType,
+        token,
+        tokenExpiresAt,
+        theme,
+        config,
+        entrypoint,
+        apiBaseUrl,
+        path,
+        client,
+        ...methods,
+    };
+}
+//# sourceMappingURL=useRendererClient.js.map

package/dist/react/useRendererClient.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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;
+    };
+}
+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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,CAAC,CAAC;IACX,uDAAuD;IACvD,WAAW,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACnC,OAAO,CAAC,EAAE;QACT,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,cAAc,CAAC,EAAE,OAAO,CAAC;KACzB,CAAC;CACF;AAED,MAAM,MAAM,kBAAkB,GAC3B,cAAc,GACd,YAAY,CAAC;AAEhB;;;GAGG;AACH,MAAM,MAAM,aAAa,GACtB,mBAAmB,GACnB,mBAAmB,GACnB,mBAAmB,GACnB,wBAAwB,CAAC;AAE5B,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACxC,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GACtB,iBAAiB,GACjB,iBAAiB,GACjB,eAAe,CAAC;AAEnB;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC3C,uBAAuB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnE,sBAAsB,CAAC,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;CAC5C;AAED,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC3B,wBAAwB;IACxB,OAAO,EAAE,CAAC,CAAC;IACX,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,cAAc,EAAE,MAAM,CAAC;IACvB,0BAA0B;IAC1B,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,mCAAmC;IACnC,UAAU,EAAE,WAAW,GAAG,QAAQ,CAAC;IACnC,+CAA+C;IAC/C,KAAK,EAAE,aAAa,CAAC;IACrB,4DAA4D;IAC5D,aAAa,EAAE,aAAa,CAAC;IAC7B,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,MAAM,EAAE,cAAc,CAAC;IACvB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@xeonr/renderer-sdk",
+  "version": "1.0.4",
+  "type": "module",
+  "license": "ISC",
+  "description": "SDK for building custom renderers for upl.im integrations",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./react": {
+      "default": "./dist/react/index.js",
+      "types": "./dist/react/index.d.ts"
+    },
+    "./protocol": {
+      "default": "./dist/protocol.js",
+      "types": "./dist/protocol.d.ts"
+    },
+    "./*": {
+      "default": "./dist/*.js",
+      "types": "./dist/*.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}