@postrun/react 1.0.0 → 1.2.0

package/dist/index.d.cts

@@ -211,7 +211,7 @@ declare function useDeleteProfile(): _tanstack_react_query.UseMutationResult<{
 /** One account offered for selection — the element type of the accounts list. */
 type DiscoverableAccount = DiscoverableAccountList['data'][number];
 /** Why a connect attempt ended in `error` — actionable reasons for the host. */
-type ConnectErrorReason = 'popup_blocked' | 'auth_failed' | 'connection_not_found' | 'select_failed' | 'reauth_required';
+type ConnectErrorReason = 'prepare_failed' | 'popup_blocked' | 'auth_failed' | 'connection_not_found' | 'select_failed' | 'reauth_required';
 /**
  * The single outcome of a connect attempt. `active` carries the activated
  * connection (so the host can call `onConnected`); `connected_pending` means the
@@ -338,8 +338,28 @@ interface UseConnectParams {
     profileId: string;
     /** The platform to connect (X, LinkedIn, Meta, …). */
     platform: ConnectablePlatform;
-    /** Called once a connection is fully ACTIVE (an account is bound). */
+    /** Called once a connection is fully ACTIVE (an account is bound). The
+     * connections list is auto-refetched too, so you rarely need to act here. */
     onConnected?: (connection: Connection) => void;
+    /** Called when the connect SUCCEEDS — `active` OR `connected_pending` (the
+     * grant landed but the account binds out-of-band / via a slow webhook). Use
+     * this to close your UI and let the auto-refetched list show the result;
+     * `onConnected` additionally hands you the bound connection on `active`. */
+    onSuccess?: () => void;
+    /** Called when the attempt fails, with the typed reason. */
+    onError?: (reason: ConnectErrorReason) => void;
+    /** Called when the user closes the OAuth popup without finishing. The hook
+     * stays in the `cancelled` phase; call `reset()` to re-arm for another try. */
+    onCancelled?: () => void;
+    /**
+     * Pre-mint the Nango session on mount (default `true`). Keep it `true` for a
+     * dedicated "Connect X" button. Set it `false` for a MULTI-platform picker —
+     * then call `prepare()` on the platform button's `onPointerEnter`/`onFocus` so
+     * only the platform the user is about to click mints a session (not all of
+     * them on open). The popup still needs a pre-minted session, so prepare on
+     * intent, not on click.
+     */
+    prepareOnMount?: boolean;
 }
 /**
  * The connect flow's UI state. `connected_pending` is a TERMINAL success state —
@@ -373,10 +393,17 @@ interface UseConnectResult {
     /**
      * Start the OAuth flow. MUST be called directly in the user's click handler
      * (no `await` before it): it opens the OAuth popup synchronously, so the
-     * browser keeps it inside the user gesture. A no-op until the session is ready
-     * (state `preparing`) — disable the button until `phase` is `idle`.
+     * browser keeps it inside the user gesture. If the session isn't ready yet
+     * (`phase` !== `idle`) it kicks `prepare()` and no-ops the popup, so the next
+     * click works — prepare on intent (hover/focus) to make the first click open.
      */
     start: () => void;
+    /**
+     * Mint the Nango session ahead of the click. Idempotent (a no-op if a session
+     * is already held or a mint is in flight). Only needed with
+     * `prepareOnMount: false` — call it on the button's `onPointerEnter`/`onFocus`.
+     */
+    prepare: () => void;
     /** When `phase` is `picking`, activate the connection with the chosen account. */
     select: (externalAccountId: string) => void;
     /** Return to a fresh, ready state (re-mints the session) — e.g. a "try again". */
@@ -397,7 +424,7 @@ interface UseConnectResult {
  * The hosted `/connect` page remains the fallback for callers NOT using this SDK
  * (a plain link to `hosted_connect_url`); this hook never redirects.
  */
-declare function useConnect({ profileId, platform, onConnected, }: UseConnectParams): UseConnectResult;
+declare function useConnect({ profileId, platform, onConnected, onSuccess, onError, onCancelled, prepareOnMount, }: UseConnectParams): UseConnectResult;
 /**
  * List a profile's connected accounts. Pass a `filter` to narrow by `kind`
  * (`posting` = social, `ads`) or `status` — e.g. a composer fetches
@@ -496,10 +523,15 @@ interface ConnectRenderApi {
     state: ConnectState;
     /**
      * Begin connecting. Call this DIRECTLY from your button's `onClick` — it opens
-     * the OAuth popup synchronously, so don't `await` anything before it. A no-op
-     * until the session is ready (`state.phase === 'preparing'`).
+     * the OAuth popup synchronously, so don't `await` anything before it.
      */
     start: () => void;
+    /**
+     * Mint the session ahead of the click — only needed with
+     * `prepareOnMount={false}` (a multi-platform picker): call it on the button's
+     * `onPointerEnter`/`onFocus`.
+     */
+    prepare: () => void;
     /** When `state.phase === 'picking'`, activate with the chosen account id. */
     select: (externalAccountId: string) => void;
     /** Reset to a fresh, ready state (e.g. a "try again" after an error/cancel). */
@@ -512,6 +544,15 @@ interface ConnectProps {
     platform: ConnectablePlatform;
     /** Called once a connection is fully ACTIVE (an account is bound). */
     onConnected?: (connection: Connection) => void;
+    /** Called when the connect succeeds — `active` OR `connected_pending`. */
+    onSuccess?: () => void;
+    /** Called when the attempt fails, with the typed reason. */
+    onError?: (reason: ConnectErrorReason) => void;
+    /** Called when the user closes the OAuth popup without finishing. */
+    onCancelled?: () => void;
+    /** Pre-mint on mount (default `true`). Set `false` for a multi-platform picker
+     * and call `prepare()` on intent — see {@link UseConnectParams.prepareOnMount}. */
+    prepareOnMount?: boolean;
     /** Render your own button + picker + status from the flow state. */
     children: (api: ConnectRenderApi) => ReactNode;
 }
@@ -546,7 +587,7 @@ interface ConnectProps {
  * The trigger MUST call `start()` directly in the click (it opens the popup
  * synchronously). Mount `<Connect>` inside a `<PostrunProvider>`.
  */
-declare function Connect({ profileId, platform, onConnected, children, }: ConnectProps): ReactNode;
+declare function Connect({ profileId, platform, onConnected, onSuccess, onError, onCancelled, prepareOnMount, children, }: ConnectProps): ReactNode;
 
 type MediaUploadStatus = 'idle' | 'uploading' | 'processing' | 'ready' | 'failed';
 interface MediaUploadOptions {

package/dist/index.d.ts

@@ -211,7 +211,7 @@ declare function useDeleteProfile(): _tanstack_react_query.UseMutationResult<{
 /** One account offered for selection — the element type of the accounts list. */
 type DiscoverableAccount = DiscoverableAccountList['data'][number];
 /** Why a connect attempt ended in `error` — actionable reasons for the host. */
-type ConnectErrorReason = 'popup_blocked' | 'auth_failed' | 'connection_not_found' | 'select_failed' | 'reauth_required';
+type ConnectErrorReason = 'prepare_failed' | 'popup_blocked' | 'auth_failed' | 'connection_not_found' | 'select_failed' | 'reauth_required';
 /**
  * The single outcome of a connect attempt. `active` carries the activated
  * connection (so the host can call `onConnected`); `connected_pending` means the
@@ -338,8 +338,28 @@ interface UseConnectParams {
     profileId: string;
     /** The platform to connect (X, LinkedIn, Meta, …). */
     platform: ConnectablePlatform;
-    /** Called once a connection is fully ACTIVE (an account is bound). */
+    /** Called once a connection is fully ACTIVE (an account is bound). The
+     * connections list is auto-refetched too, so you rarely need to act here. */
     onConnected?: (connection: Connection) => void;
+    /** Called when the connect SUCCEEDS — `active` OR `connected_pending` (the
+     * grant landed but the account binds out-of-band / via a slow webhook). Use
+     * this to close your UI and let the auto-refetched list show the result;
+     * `onConnected` additionally hands you the bound connection on `active`. */
+    onSuccess?: () => void;
+    /** Called when the attempt fails, with the typed reason. */
+    onError?: (reason: ConnectErrorReason) => void;
+    /** Called when the user closes the OAuth popup without finishing. The hook
+     * stays in the `cancelled` phase; call `reset()` to re-arm for another try. */
+    onCancelled?: () => void;
+    /**
+     * Pre-mint the Nango session on mount (default `true`). Keep it `true` for a
+     * dedicated "Connect X" button. Set it `false` for a MULTI-platform picker —
+     * then call `prepare()` on the platform button's `onPointerEnter`/`onFocus` so
+     * only the platform the user is about to click mints a session (not all of
+     * them on open). The popup still needs a pre-minted session, so prepare on
+     * intent, not on click.
+     */
+    prepareOnMount?: boolean;
 }
 /**
  * The connect flow's UI state. `connected_pending` is a TERMINAL success state —
@@ -373,10 +393,17 @@ interface UseConnectResult {
     /**
      * Start the OAuth flow. MUST be called directly in the user's click handler
      * (no `await` before it): it opens the OAuth popup synchronously, so the
-     * browser keeps it inside the user gesture. A no-op until the session is ready
-     * (state `preparing`) — disable the button until `phase` is `idle`.
+     * browser keeps it inside the user gesture. If the session isn't ready yet
+     * (`phase` !== `idle`) it kicks `prepare()` and no-ops the popup, so the next
+     * click works — prepare on intent (hover/focus) to make the first click open.
      */
     start: () => void;
+    /**
+     * Mint the Nango session ahead of the click. Idempotent (a no-op if a session
+     * is already held or a mint is in flight). Only needed with
+     * `prepareOnMount: false` — call it on the button's `onPointerEnter`/`onFocus`.
+     */
+    prepare: () => void;
     /** When `phase` is `picking`, activate the connection with the chosen account. */
     select: (externalAccountId: string) => void;
     /** Return to a fresh, ready state (re-mints the session) — e.g. a "try again". */
@@ -397,7 +424,7 @@ interface UseConnectResult {
  * The hosted `/connect` page remains the fallback for callers NOT using this SDK
  * (a plain link to `hosted_connect_url`); this hook never redirects.
  */
-declare function useConnect({ profileId, platform, onConnected, }: UseConnectParams): UseConnectResult;
+declare function useConnect({ profileId, platform, onConnected, onSuccess, onError, onCancelled, prepareOnMount, }: UseConnectParams): UseConnectResult;
 /**
  * List a profile's connected accounts. Pass a `filter` to narrow by `kind`
  * (`posting` = social, `ads`) or `status` — e.g. a composer fetches
@@ -496,10 +523,15 @@ interface ConnectRenderApi {
     state: ConnectState;
     /**
      * Begin connecting. Call this DIRECTLY from your button's `onClick` — it opens
-     * the OAuth popup synchronously, so don't `await` anything before it. A no-op
-     * until the session is ready (`state.phase === 'preparing'`).
+     * the OAuth popup synchronously, so don't `await` anything before it.
      */
     start: () => void;
+    /**
+     * Mint the session ahead of the click — only needed with
+     * `prepareOnMount={false}` (a multi-platform picker): call it on the button's
+     * `onPointerEnter`/`onFocus`.
+     */
+    prepare: () => void;
     /** When `state.phase === 'picking'`, activate with the chosen account id. */
     select: (externalAccountId: string) => void;
     /** Reset to a fresh, ready state (e.g. a "try again" after an error/cancel). */
@@ -512,6 +544,15 @@ interface ConnectProps {
     platform: ConnectablePlatform;
     /** Called once a connection is fully ACTIVE (an account is bound). */
     onConnected?: (connection: Connection) => void;
+    /** Called when the connect succeeds — `active` OR `connected_pending`. */
+    onSuccess?: () => void;
+    /** Called when the attempt fails, with the typed reason. */
+    onError?: (reason: ConnectErrorReason) => void;
+    /** Called when the user closes the OAuth popup without finishing. */
+    onCancelled?: () => void;
+    /** Pre-mint on mount (default `true`). Set `false` for a multi-platform picker
+     * and call `prepare()` on intent — see {@link UseConnectParams.prepareOnMount}. */
+    prepareOnMount?: boolean;
     /** Render your own button + picker + status from the flow state. */
     children: (api: ConnectRenderApi) => ReactNode;
 }
@@ -546,7 +587,7 @@ interface ConnectProps {
  * The trigger MUST call `start()` directly in the click (it opens the popup
  * synchronously). Mount `<Connect>` inside a `<PostrunProvider>`.
  */
-declare function Connect({ profileId, platform, onConnected, children, }: ConnectProps): ReactNode;
+declare function Connect({ profileId, platform, onConnected, onSuccess, onError, onCancelled, prepareOnMount, children, }: ConnectProps): ReactNode;
 
 type MediaUploadStatus = 'idle' | 'uploading' | 'processing' | 'ready' | 'failed';
 interface MediaUploadOptions {

package/dist/index.js

@@ -303,19 +303,31 @@ var POLL_TIMEOUT_MS = 15e3;
 function useConnect({
   profileId,
   platform,
-  onConnected
+  onConnected,
+  onSuccess,
+  onError,
+  onCancelled,
+  prepareOnMount = true
 }) {
-  const { client } = usePostrun();
+  const { client, queryClient } = usePostrun();
   const [state, setState] = useState({ phase: "preparing" });
   const [remintNonce, setRemintNonce] = useState(0);
   const sessionRef = useRef(null);
   const pickRef = useRef(null);
   const inFlightRef = useRef(false);
   const flowGenRef = useRef(0);
+  const preparingRef = useRef(false);
+  const prepareGenRef = useRef(0);
   const onConnectedRef = useRef(onConnected);
+  const onSuccessRef = useRef(onSuccess);
+  const onErrorRef = useRef(onError);
+  const onCancelledRef = useRef(onCancelled);
   useEffect(() => {
     onConnectedRef.current = onConnected;
-  }, [onConnected]);
+    onSuccessRef.current = onSuccess;
+    onErrorRef.current = onError;
+    onCancelledRef.current = onCancelled;
+  });
   const abandonFlow = useCallback(() => {
     flowGenRef.current += 1;
     inFlightRef.current = false;
@@ -323,12 +335,23 @@ function useConnect({
     pickRef.current = null;
     pick?.reject(new Error("connect flow abandoned"));
   }, []);
-  useEffect(() => {
-    let abandoned = false;
+  const prepare = useCallback(() => {
+    if (sessionRef.current || preparingRef.current) return;
+    preparingRef.current = true;
+    const gen = prepareGenRef.current;
     setState({ phase: "preparing" });
-    sessionRef.current = null;
+    const failPrepare = () => {
+      preparingRef.current = false;
+      setState({ phase: "error", reason: "prepare_failed" });
+      onErrorRef.current?.("prepare_failed");
+    };
     connectionsConnect({ client, path: { id: profileId }, body: { platform } }).then(({ data }) => {
-      if (abandoned || !data) return;
+      if (prepareGenRef.current !== gen) return;
+      if (!data) {
+        failPrepare();
+        return;
+      }
+      preparingRef.current = false;
       sessionRef.current = {
         token: data.connect_session_token,
         providerConfigKey: data.provider_config_key,
@@ -336,16 +359,28 @@ function useConnect({
       };
       setState({ phase: "idle" });
     }).catch(() => {
-      if (!abandoned) setState({ phase: "error", reason: "auth_failed" });
+      if (prepareGenRef.current !== gen) return;
+      failPrepare();
     });
+  }, [client, profileId, platform]);
+  useEffect(() => {
+    prepareGenRef.current += 1;
+    preparingRef.current = false;
+    sessionRef.current = null;
+    setState({ phase: "preparing" });
+    if (prepareOnMount) prepare();
     return () => {
-      abandoned = true;
+      prepareGenRef.current += 1;
       abandonFlow();
     };
-  }, [client, profileId, platform, remintNonce, abandonFlow]);
+  }, [profileId, platform, remintNonce, prepareOnMount, prepare, abandonFlow]);
   const start = useCallback(() => {
     const session = sessionRef.current;
-    if (!session || inFlightRef.current) return;
+    if (!session) {
+      prepare();
+      return;
+    }
+    if (inFlightRef.current) return;
     inFlightRef.current = true;
     const gen = flowGenRef.current;
     const isCurrent = () => flowGenRef.current === gen;
@@ -410,20 +445,26 @@ function useConnect({
       switch (outcome.status) {
         case "active":
           setState({ phase: "active", connection: outcome.connection });
+          void queryClient.invalidateQueries({ queryKey: connectionKeys.lists() });
           onConnectedRef.current?.(outcome.connection);
+          onSuccessRef.current?.();
           return;
         case "connected_pending":
           setState({ phase: "connected_pending" });
+          void queryClient.invalidateQueries({ queryKey: connectionKeys.lists() });
+          onSuccessRef.current?.();
           return;
         case "cancelled":
           setState({ phase: "cancelled" });
+          onCancelledRef.current?.();
           return;
         case "error":
           setState({ phase: "error", reason: outcome.reason });
+          onErrorRef.current?.(outcome.reason);
           return;
       }
     });
-  }, [client, profileId]);
+  }, [client, profileId, prepare, queryClient]);
   const select = useCallback((externalAccountId) => {
     const pick = pickRef.current;
     if (!pick) return;
@@ -434,7 +475,7 @@ function useConnect({
   const reset = useCallback(() => {
     setRemintNonce((n) => n + 1);
   }, []);
-  return { state, start, select, reset };
+  return { state, start, prepare, select, reset };
 }
 function useConnections(profileId, filter) {
   const { client, queryClient } = usePostrun();
@@ -506,9 +547,21 @@ function Connect({
   profileId,
   platform,
   onConnected,
+  onSuccess,
+  onError,
+  onCancelled,
+  prepareOnMount,
   children
 }) {
-  const api = useConnect({ profileId, platform, onConnected });
+  const api = useConnect({
+    profileId,
+    platform,
+    onConnected,
+    onSuccess,
+    onError,
+    onCancelled,
+    prepareOnMount
+  });
   return children(api);
 }
 var UploadError = class extends Error {