@pulse-editor/react-api 0.1.1-beta.83 → 0.1.1-beta.84

package/dist/hooks/editor/use-app-settings.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Hook to access and update persisted settings for a specific app in the editor.
+ * @param appId The ID of the app whose settings should be retrieved and updated.
+ * @returns `isReady`, the current `settings` object, and an `updateSettings` function.
+ */
+export default function useAppSettings(appId: string): {
+    isReady: boolean;
+    isLoaded: boolean;
+    settings: Record<string, any>;
+    refetch: () => Promise<void>;
+    updateSettings: (newSettings: Record<string, any>) => Promise<void>;
+    deleteSetting: (key: string) => Promise<void>;
+};

package/dist/hooks/editor/use-oauth.d.ts

@@ -0,0 +1,36 @@
+import { OAuthConnectConfig } from "@pulse-editor/shared-utils";
+export type OAuthState = {
+    accessToken?: string;
+    refreshToken?: string;
+    tokenType?: string;
+    scope?: string;
+    expiresAt?: string | number;
+    idToken?: string;
+    [key: string]: any;
+};
+/**
+ * Hook to manage OAuth credentials for a Pulse App.
+ *
+ * Handles the full OAuth flow automatically:
+ * - Dynamic client registration (RFC 7591) when `registrationEndpoint` is provided
+ * - PKCE code challenge generation
+ * - Opening the authorization modal
+ * - Token exchange and storage (via the Pulse Editor backend)
+ *
+ * @param appId The ID of the app.
+ * @param provider A provider identifier used to namespace the OAuth state.
+ */
+export default function useOAuth(appId: string, provider?: string): {
+    isReady: boolean;
+    isLoading: boolean;
+    oauth: OAuthState | null;
+    isAuthenticated: boolean;
+    connect: (config: OAuthConnectConfig) => Promise<void>;
+    disconnect: () => Promise<void>;
+    refetchOAuth: () => Promise<void>;
+    refreshToken: (params: {
+        tokenEndpoint: string;
+        clientId: string;
+        clientSecret?: string;
+    }) => Promise<OAuthState | null>;
+};

package/dist/hooks/editor/use-snapshot-state.d.ts

@@ -1 +1,9 @@
-export default function useSnapShotState<T>(key: string, initialValue?: T, onRestore?: (value: T) => void): readonly [T, import("react").Dispatch<import("react").SetStateAction<T>>];
+/**
+ * A hook that syncs state with a snapshot context,
+ * allowing for state restoration across component unmounts and remounts.
+ * @param key
+ * @param initialValue
+ * @param onRestore
+ * @returns
+ */
+export default function useSnapshotState<T>(key: string, initialValue?: T, onRestore?: (value: T) => void): readonly [T, import("react").Dispatch<import("react").SetStateAction<T>>];

package/dist/main.d.ts

@@ -1,8 +1,8 @@
 import useAgentTools from "./hooks/agent/use-agent-tools";
 import useAgents from "./hooks/agent/use-agents";
+import useActionEffect from "./hooks/editor/use-action-effect";
 import useLoading from "./hooks/editor/use-loading";
 import useNotification from "./hooks/editor/use-notification";
-import useActionEffect from "./hooks/editor/use-action-effect";
 import useTheme from "./hooks/editor/use-theme";
 import useFile from "./hooks/workspace/use-file";
 import useImageGen from "./hooks/ai-modality/use-image-gen";
@@ -11,11 +11,14 @@ import useOCR from "./hooks/ai-modality/use-ocr";
 import useSTT from "./hooks/ai-modality/use-stt";
 import useTTS from "./hooks/ai-modality/use-tts";
 import useVideoGen from "./hooks/ai-modality/use-video-gen";
+import useAppSettings from "./hooks/editor/use-app-settings";
 import { useArtifact } from "./hooks/editor/use-artifact";
 import useEditorEnv from "./hooks/editor/use-editor-env";
 import useOpenApp from "./hooks/editor/use-open-app";
 import useOpenLink from "./hooks/editor/use-open-link";
 import useOwnedAppView from "./hooks/editor/use-owned-app-view";
+import useOAuth from "./hooks/editor/use-oauth";
+export type { OAuthState } from "./hooks/editor/use-oauth";
 import useSnapshotState from "./hooks/editor/use-snapshot-state";
 import { useTranslations } from "./hooks/editor/use-translations";
 import useFileSystem from "./hooks/workspace/use-file-system";
@@ -24,4 +27,4 @@ import useTerminal from "./hooks/workspace/use-terminal";
 import useWorkspaceInfo from "./hooks/workspace/use-workspace-info";
 import ReceiveFileProvider from "./providers/receive-file-provider";
 import SnapshotProvider from "./providers/snapshot-provider";
-export { ReceiveFileProvider, SnapshotProvider, useAgents, useAgentTools, useArtifact, useEditorEnv, useFile, useFileSystem, useImageGen, useLLM, useLoading, useNotification, useOCR, useOpenApp, useOpenLink, useOwnedAppView, useReceiveFile, useActionEffect, useSnapshotState, useSTT, useTerminal, useTheme, useTranslations, useTTS, useVideoGen, useWorkspaceInfo, };
+export { ReceiveFileProvider, SnapshotProvider, useActionEffect, useAgents, useAgentTools, useAppSettings, useArtifact, useEditorEnv, useFile, useFileSystem, useImageGen, useLLM, useLoading, useNotification, useOCR, useOpenApp, useOpenLink, useOAuth, useOwnedAppView, useReceiveFile, useSnapshotState, useSTT, useTerminal, useTheme, useTranslations, useTTS, useVideoGen, useWorkspaceInfo, };

package/dist/main.js

@@ -492,40 +492,6 @@ function useAgents() {
     };
 }
 
-function useLoading() {
-    const receiverHandlerMap = new Map();
-    const { imc, isReady } = useIMC(receiverHandlerMap, "loading");
-    const [isLoading, setIsLoading] = useState(true);
-    useEffect(() => {
-        if (isReady) {
-            imc?.sendMessage(IMCMessageTypeEnum.EditorLoadingApp, {
-                isLoading,
-            });
-        }
-    }, [isLoading]);
-    function toggleLoading(isLoading) {
-        setIsLoading((prev) => isLoading);
-    }
-    return {
-        isReady,
-        toggleLoading,
-    };
-}
-
-function useNotification() {
-    const receiverHandlerMap = new Map();
-    const { imc, isReady } = useIMC(receiverHandlerMap, "notification");
-    function openNotification(text, type) {
-        if (isReady) {
-            imc?.sendMessage(IMCMessageTypeEnum.EditorShowNotification, {
-                text,
-                type,
-            });
-        }
-    }
-    return { isReady, openNotification };
-}
-
 var MANIFEST_EXT = '.json';
 var BROWSER_LOG_KEY = 'FEDERATION_DEBUG';
 var NameTransformSymbol = {
@@ -5851,6 +5817,40 @@ function useActionEffect(params, deps, isExtReady = true) {
     };
 }
 
+function useLoading() {
+    const receiverHandlerMap = new Map();
+    const { imc, isReady } = useIMC(receiverHandlerMap, "loading");
+    const [isLoading, setIsLoading] = useState(true);
+    useEffect(() => {
+        if (isReady) {
+            imc?.sendMessage(IMCMessageTypeEnum.EditorLoadingApp, {
+                isLoading,
+            });
+        }
+    }, [isLoading]);
+    function toggleLoading(isLoading) {
+        setIsLoading((prev) => isLoading);
+    }
+    return {
+        isReady,
+        toggleLoading,
+    };
+}
+
+function useNotification() {
+    const receiverHandlerMap = new Map();
+    const { imc, isReady } = useIMC(receiverHandlerMap, "notification");
+    function openNotification(text, type) {
+        if (isReady) {
+            imc?.sendMessage(IMCMessageTypeEnum.EditorShowNotification, {
+                text,
+                type,
+            });
+        }
+    }
+    return { isReady, openNotification };
+}
+
 function useTheme() {
     const [theme, setTheme] = useState("light");
     const receiverHandlerMap = new Map();
@@ -6182,6 +6182,54 @@ function useVideoGen() {
     };
 }
 
+/**
+ * Hook to access and update persisted settings for a specific app in the editor.
+ * @param appId The ID of the app whose settings should be retrieved and updated.
+ * @returns `isReady`, the current `settings` object, and an `updateSettings` function.
+ */
+function useAppSettings(appId) {
+    const receiverHandlerMap = new Map();
+    const { imc, isReady } = useIMC(receiverHandlerMap, "app-settings");
+    const [settings, setSettings] = useState({});
+    const [isLoaded, setIsLoaded] = useState(false);
+    useEffect(() => {
+        if (isReady) {
+            refetch();
+        }
+    }, [isReady]);
+    async function refetch() {
+        const result = await imc?.sendMessage(IMCMessageTypeEnum.EditorGetAppSettings, { appId });
+        setSettings(result ?? {});
+        setIsLoaded(true);
+    }
+    async function updateSettings(newSettings) {
+        await imc?.sendMessage(IMCMessageTypeEnum.EditorSetAppSettings, {
+            appId,
+            settings: newSettings,
+        });
+        setSettings((prev) => ({ ...prev, ...newSettings }));
+    }
+    async function deleteSetting(key) {
+        await imc?.sendMessage(IMCMessageTypeEnum.EditorDeleteAppSetting, {
+            appId,
+            key,
+        });
+        setSettings((prev) => {
+            const next = { ...prev };
+            delete next[key];
+            return next;
+        });
+    }
+    return {
+        isReady,
+        isLoaded,
+        settings,
+        refetch,
+        updateSettings,
+        deleteSetting,
+    };
+}
+
 function useArtifact() {
     const receiverHandlerMap = new Map();
     const { imc, isReady } = useIMC(receiverHandlerMap, "artifact");
@@ -6285,6 +6333,124 @@ function useOwnedAppView() {
     };
 }
 
+function generateRandomString(length) {
+    const array = new Uint8Array(length);
+    crypto.getRandomValues(array);
+    return Array.from(array, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Hook to manage OAuth credentials for a Pulse App.
+ *
+ * Handles the full OAuth flow automatically:
+ * - Dynamic client registration (RFC 7591) when `registrationEndpoint` is provided
+ * - PKCE code challenge generation
+ * - Opening the authorization modal
+ * - Token exchange and storage (via the Pulse Editor backend)
+ *
+ * @param appId The ID of the app.
+ * @param provider A provider identifier used to namespace the OAuth state.
+ */
+function useOAuth(appId, provider = "default") {
+    const { isReady, isLoaded, settings, deleteSetting, refetch } = useAppSettings(appId);
+    const keyPrefix = `oauth:${provider}:`;
+    const oauthEntries = Object.entries(settings).filter(([k]) => k.startsWith(keyPrefix));
+    const oauthRaw = oauthEntries.length > 0
+        ? Object.fromEntries(oauthEntries.map(([k, v]) => [k.slice(keyPrefix.length), v]))
+        : null;
+    const oauth = oauthRaw &&
+        Object.values(oauthRaw).some((v) => v !== null && v !== undefined)
+        ? oauthRaw
+        : null;
+    const receiverHandlerMap = new Map();
+    const { imc, isReady: isIMCReady } = useIMC(receiverHandlerMap, "oauth");
+    /**
+     * Initiate the OAuth flow. The editor handles everything:
+     * - Dynamic client registration (if `registrationEndpoint` is provided and `clientId` is omitted)
+     * - PKCE (`codeVerifier` is auto-generated if not provided)
+     * - Opening the consent modal and authorization window
+     * - Token exchange and storage
+     */
+    async function connect(config) {
+        if (!isIMCReady) {
+            throw new Error("IMC is not ready.");
+        }
+        // Auto-generate PKCE code verifier if not provided
+        const resolvedConfig = { ...config };
+        if (!resolvedConfig.codeVerifier) {
+            resolvedConfig.codeVerifier = generateRandomString(64);
+            resolvedConfig.codeChallengeMethod =
+                resolvedConfig.codeChallengeMethod ?? "S256";
+        }
+        await imc?.sendMessage(IMCMessageTypeEnum.EditorOAuthConnect, {
+            appId,
+            provider,
+            config: resolvedConfig,
+        });
+    }
+    /**
+     * Sign out: removes all stored OAuth tokens for this provider from the
+     * editor backend and resets local auth state immediately.
+     */
+    async function disconnect() {
+        // Collect keys before deletion so we don't rely on stale `oauth`
+        const keysToDelete = oauthEntries.map(([k]) => k);
+        await Promise.all(keysToDelete.map((key) => deleteSetting(key)));
+    }
+    /**
+     * Re-fetch OAuth state from app settings.
+     * Call this after the user completes the OAuth flow in the external window.
+     */
+    async function refetchOAuth() {
+        await refetch();
+    }
+    // Revalidate OAuth state when the user returns to the tab
+    useEffect(() => {
+        function handleVisibilityChange() {
+            if (document.visibilityState === "visible") {
+                refetch();
+            }
+        }
+        document.addEventListener("visibilitychange", handleVisibilityChange);
+        return () => {
+            document.removeEventListener("visibilitychange", handleVisibilityChange);
+        };
+    }, [isReady]);
+    /**
+     * Refresh the access token using the stored refresh token.
+     * The editor backend exchanges the refresh token with the OAuth provider
+     * and persists the new tokens automatically.
+     */
+    async function refreshToken(params) {
+        if (!isIMCReady) {
+            throw new Error("IMC is not ready.");
+        }
+        if (!oauth?.refreshToken) {
+            throw new Error("No refresh token available.");
+        }
+        const result = await imc?.sendMessage(IMCMessageTypeEnum.EditorOAuthRefreshToken, {
+            appId,
+            provider,
+            tokenEndpoint: params.tokenEndpoint,
+            refreshToken: oauth.refreshToken,
+            clientId: params.clientId,
+            clientSecret: params.clientSecret,
+        });
+        // Re-fetch settings to sync local state
+        await refetchOAuth();
+        return result ?? null;
+    }
+    return {
+        isReady,
+        isLoading: !isLoaded,
+        oauth,
+        isAuthenticated: Boolean(oauth?.accessToken),
+        connect,
+        disconnect,
+        refetchOAuth,
+        refreshToken,
+    };
+}
+
 const SnapshotContext = createContext(undefined);
 function SnapshotProvider({ children, }) {
     const [states, setStates] = useState({});
@@ -6315,7 +6481,15 @@ function SnapshotProvider({ children, }) {
     return (React.createElement(SnapshotContext.Provider, { value: { states, setStates } }, children));
 }
 
-function useSnapShotState(key, initialValue, onRestore) {
+/**
+ * A hook that syncs state with a snapshot context,
+ * allowing for state restoration across component unmounts and remounts.
+ * @param key
+ * @param initialValue
+ * @param onRestore
+ * @returns
+ */
+function useSnapshotState(key, initialValue, onRestore) {
     const snapshotContext = useContext(SnapshotContext);
     if (!snapshotContext) {
         throw new Error("useSnapShotState must be used within a SnapshotProvider");
@@ -6543,5 +6717,5 @@ function useWorkspaceInfo() {
     };
 }
 
-export { ReceiveFileProvider, SnapshotProvider, useActionEffect, useAgentTools, useAgents, useArtifact, useEditorEnv, useFile, useFileSystem, useImageGen, useLLM, useLoading, useNotification, useOCR, useOpenApp, useOpenLink, useOwnedAppView, useReceiveFile, useSTT, useSnapShotState as useSnapshotState, useTTS, useTerminal, useTheme, useTranslations, useVideoGen, useWorkspaceInfo };
+export { ReceiveFileProvider, SnapshotProvider, useActionEffect, useAgentTools, useAgents, useAppSettings, useArtifact, useEditorEnv, useFile, useFileSystem, useImageGen, useLLM, useLoading, useNotification, useOAuth, useOCR, useOpenApp, useOpenLink, useOwnedAppView, useReceiveFile, useSTT, useSnapshotState, useTTS, useTerminal, useTheme, useTranslations, useVideoGen, useWorkspaceInfo };
 //# sourceMappingURL=main.js.map