Feature/hook callback improvements (#40)

* feat: adjust hooks with refresh, destroy registry refresh interval

* feat: increase amount of callbacks

* feat: adjust default value

Author: fsher

packages/blinks-core/src/BlinkContainer.tsx

@@ -27,6 +27,7 @@ import {
   SingleValueActionComponent,
 } from './api';
 import { checkSecurity, isInterstitial, type SecurityLevel } from './utils';
+import { EMPTY_OBJECT } from './utils/constants.ts';
 import {
   isPostRequestError,
   isSignMessageError,
@@ -272,7 +273,7 @@ export const BlinkContainer = ({
   adapter,
   websiteUrl,
   websiteText,
-  callbacks,
+  callbacks = EMPTY_OBJECT,
   securityLevel = DEFAULT_SECURITY_LEVEL,
   Layout,
   selector,
@@ -339,14 +340,14 @@ export const BlinkContainer = ({
   }, [initialAction, websiteUrl]);
 
   useEffect(() => {
-    callbacks?.onActionMount?.(
-      action,
-      websiteUrl ?? action.url,
+    callbacks.onActionMount?.(
+      initialAction,
+      websiteUrl ?? initialAction.url,
       actionState.action,
     );
-    // we run this effect ONLY if the action changes
+    // we run this effect ONLY once
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [action.id]);
+  }, []);
 
   useEffect(() => {
     const liveDataConfig = action.liveData_experimental;
@@ -454,6 +455,7 @@ export const BlinkContainer = ({
     ) {
       setActionState(newActionState);
       dispatch({ type: ExecutionType.BLOCK });
+      callbacks.onActionCancel?.(action, component, 'security-state-changed');
       return;
     }
 
@@ -470,6 +472,7 @@ export const BlinkContainer = ({
       const account = await adapter.connect(context);
       if (!account) {
         dispatch({ type: ExecutionType.RESET });
+        callbacks?.onActionCancel?.(action, component, 'wallet-not-connected');
         return;
       }
 
@@ -484,6 +487,7 @@ export const BlinkContainer = ({
             ? response.error
             : 'Transaction data missing',
         });
+        callbacks.onActionError?.(action, component, 'post-request-error');
         return;
       }
 
@@ -493,6 +497,7 @@ export const BlinkContainer = ({
             type: ExecutionType.FINISH,
             successMessage: response.message,
           });
+          callbacks.onActionComplete?.(action, component, signature);
           return;
         }
 
@@ -501,6 +506,11 @@ export const BlinkContainer = ({
             type: ExecutionType.SOFT_RESET,
             errorMessage: 'Missing signature for message',
           });
+          callbacks.onActionError?.(
+            action,
+            component,
+            'message-signature-missing',
+          );
           return;
         }
 
@@ -525,11 +535,19 @@ export const BlinkContainer = ({
             type: ExecutionType.FINISH,
             successMessage: response.message,
           });
+          callbacks.onActionComplete?.(action, component, signature);
           return;
         }
 
         setAction(nextAction);
         dispatch({ type: ExecutionType.RESET });
+        callbacks.onActionChain?.(
+          action,
+          nextAction,
+          component,
+          response.type,
+          signature,
+        );
       };
 
       if (response.type === 'transaction' || !response.type) {
@@ -540,10 +558,33 @@ export const BlinkContainer = ({
 
         if (!signResult || isSignTransactionError(signResult)) {
           dispatch({ type: ExecutionType.RESET });
+          callbacks.onActionCancel?.(
+            action,
+            component,
+            'transaction-sign-cancel',
+          );
           return;
         }
 
-        await adapter.confirmTransaction(signResult.signature, context);
+        const confirmationResult = await adapter
+          .confirmTransaction(signResult.signature, context)
+          .then(() => ({ success: true as const }))
+          .catch((e) => ({ success: false as const, message: e.message }));
+
+        if (!confirmationResult.success) {
+          dispatch({
+            type: ExecutionType.SOFT_RESET,
+            errorMessage:
+              confirmationResult.message ?? 'Unknown error, please try again',
+          });
+          callbacks.onActionError?.(
+            action,
+            component,
+            'transaction-confirmation-failed',
+            signResult.signature,
+          );
+          return;
+        }
 
         await chain(signResult.signature);
         return;
@@ -554,6 +595,7 @@ export const BlinkContainer = ({
 
         if (!signResult || isSignMessageError(signResult)) {
           dispatch({ type: ExecutionType.RESET });
+          callbacks.onActionCancel?.(action, component, 'message-sign-cancel');
           return;
         }
 
@@ -585,6 +627,7 @@ export const BlinkContainer = ({
         type: ExecutionType.SOFT_RESET,
         errorMessage: (e as Error).message ?? 'Unknown error, please try again',
       });
+      callbacks.onActionError?.(action, component, 'unknown-error');
     }
   };
 

packages/blinks-core/src/api/ActionCallbacks.ts

@@ -1,9 +1,38 @@
-import { Action } from './Action';
+import type { LinkedActionType } from '@solana/actions-spec';
+import { AbstractActionComponent, Action } from './Action';
 
 export interface ActionCallbacksConfig {
+  // Initial action mount (called once)
   onActionMount: (
     action: Action,
     originalUrl: string,
     type: 'trusted' | 'malicious' | 'unknown',
   ) => void;
+  // Action execution was cancelled (e.g. user interaction or blocked from execution)
+  onActionCancel: (
+    action: Action,
+    trigger: AbstractActionComponent,
+    reason: string,
+  ) => void;
+  // Action executed and chained to the next action
+  onActionChain: (
+    previousAction: Action,
+    chainedAction: Action,
+    chainTrigger: AbstractActionComponent,
+    chainType: LinkedActionType,
+    signature?: string,
+  ) => void;
+  // Action execution completed fully (called once at the end of the chain or single action)
+  onActionComplete: (
+    action: Action,
+    trigger: AbstractActionComponent,
+    signature?: string,
+  ) => void;
+  // Action execution failed (e.g. network error, invalid response, timeout). Does not include action cancellation.
+  onActionError: (
+    action: Action,
+    trigger: AbstractActionComponent,
+    reason: string,
+    signature?: string,
+  ) => void;
 }

packages/blinks-core/src/api/ActionsRegistry.ts

@@ -10,7 +10,7 @@ export class ActionsRegistry {
   private websitesByHost: Record<string, RegisteredEntity>;
   private interstitialsByHost: Record<string, RegisteredEntity>;
 
-  private initPromise: Promise<ActionsRegistryConfig> | null = null;
+  private intervalId: NodeJS.Timeout | null = null;
 
   private constructor(config?: ActionsRegistryConfig) {
     this.actionsByHost = config
@@ -43,16 +43,25 @@ export class ActionsRegistry {
   }
 
   public async init(): Promise<void> {
-    if (this.initPromise !== null) {
+    if (this.intervalId !== null) {
       return;
     }
     await this.refresh();
-    setInterval(() => this.refresh(), DEFAULT_REFRESH_INTERVAL);
+    this.intervalId = setInterval(
+      () => this.refresh(),
+      DEFAULT_REFRESH_INTERVAL,
+    );
+  }
+
+  public stopRefresh(): void {
+    if (this.intervalId !== null) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
   }
 
   public async refresh(): Promise<void> {
-    this.initPromise = fetchActionsRegistryConfig();
-    const config = await this.initPromise;
+    const config = await fetchActionsRegistryConfig();
     this.actionsByHost = Object.fromEntries(
       config.actions.map((action) => [action.host, action]),
     );

packages/blinks-core/src/hooks/index.ts

@@ -1,11 +1,13 @@
 export { useAction } from './useAction';
 export { useActionsRegistryInterval } from './useActionRegistryInterval';
 export {
+  fetchBlinkList,
   useBlinkList,
   type BlinkList,
   type BlinkListEntry,
 } from './useBlinkList.ts';
 export {
+  fetchMetadata,
   useMetadata,
   type BlinkMetadata,
   type MetadataRow,

packages/blinks-core/src/hooks/useAction.ts

@@ -1,4 +1,4 @@
-import { useEffect, useState } from 'react';
+import { useCallback, useEffect, useState } from 'react';
 import {
   Action,
   type ActionSupportStrategy,
@@ -52,25 +52,26 @@ export function useAction({
   const [isLoading, setIsLoading] = useState(false);
   const [hasFetched, setHasFetched] = useState(false);
 
-  useEffect(() => {
-    setIsLoading(true);
-    if (!isRegistryLoaded || !actionApiUrl) {
-      return;
+  const fetchAction = useCallback(() => {
+    if (!actionApiUrl) {
+      return () => {};
     }
 
     let ignore = false;
+    setIsLoading(true);
     setHasFetched(false);
     Action.fetch(actionApiUrl, supportStrategy)
       .then((action) => {
-        if (ignore) {
-          return;
+        if (!ignore) {
+          setAction(action);
+          setHasFetched(true);
         }
-        setAction(action);
-        setHasFetched(true);
       })
       .catch((e) => {
-        console.error('[@dialectlabs/blinks-core] Failed to fetch action', e);
-        setAction(null);
+        if (!ignore) {
+          console.error('[@dialectlabs/blinks-core] Failed to fetch action', e);
+          setAction(null);
+        }
       })
       .finally(() => {
         if (!ignore) {
@@ -81,7 +82,19 @@ export function useAction({
     return () => {
       ignore = true;
     };
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- only update if actionApiUrl changes
+  }, [actionApiUrl, supportStrategy]);
+
+  useEffect(() => {
+    if (!isRegistryLoaded) {
+      return;
+    }
+
+    const cleanup = fetchAction();
+
+    return () => {
+      cleanup();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- only update if actionApiUrl changes or registry loaded
   }, [actionApiUrl, isRegistryLoaded]);
 
   // this effect handles race conditions between fetching the action support strategy changes
@@ -101,5 +114,5 @@ export function useAction({
     // eslint-disable-next-line react-hooks/exhaustive-deps -- only update if supportStrategy changes
   }, [supportStrategy, hasFetched]);
 
-  return { action, isLoading };
+  return { action, isLoading, refresh: fetchAction };
 }

packages/blinks-core/src/hooks/useActionRegistryInterval.ts

@@ -5,11 +5,14 @@ export function useActionsRegistryInterval() {
   const [isRegistryLoaded, setRegistryLoaded] = useState(false);
 
   useEffect(() => {
-    ActionsRegistry.getInstance()
-      .init()
-      .then(() => {
-        setRegistryLoaded(true);
-      });
+    const registry = ActionsRegistry.getInstance();
+    registry.init().then(() => {
+      setRegistryLoaded(true);
+    });
+
+    return () => {
+      registry.stopRefresh();
+    };
   }, [isRegistryLoaded]);
 
   return { isRegistryLoaded };

packages/blinks-core/src/hooks/useBlinkList.ts

@@ -55,7 +55,7 @@ export const useBlinkList = () => {
   };
 };
 
-async function fetchBlinkList(): Promise<BlinkList> {
+export async function fetchBlinkList(): Promise<BlinkList> {
   try {
     const response = await fetch(
       'https://registry.dial.to/v1/private/blinks/list',

packages/blinks-core/src/hooks/useMetadata.ts

@@ -59,7 +59,7 @@ export const useMetadata = ({ url, wallet }: UseMetadataArgs) => {
   };
 };
 
-async function fetchMetadata(
+export async function fetchMetadata(
   url: string,
   wallet?: string,
 ): Promise<BlinkMetadata> {

packages/blinks-core/src/utils/constants.ts

@@ -1 +1,3 @@
 export const SOLANA_ACTION_PREFIX = /^(solana-action:|solana:)/;
+
+export const EMPTY_OBJECT = Object.freeze({});

packages/blinks-core/src/utils/index.ts

@@ -1,5 +1,6 @@
 export { BlockchainIds } from './caip-2.ts';
 export { BLINK_CLIENT_KEY_HEADER, setClientKey } from './client-key.ts';
+export { SOLANA_ACTION_PREFIX } from './constants.ts';
 export * from './interstitial-url.ts';
 export { proxify, proxifyImage, setProxyUrl } from './proxify';
 export { checkSecurity, type SecurityLevel } from './security';