@tuwaio/pulsar-react 1.0.0-fix-gelato-alpha.2.4635500 → 1.0.0-fix-docs-alpha.1.b07dd22

package/README.md

@@ -63,10 +63,16 @@ export const usePulsarStore = createBoundedUseStore(
   createPulsarStore<TransactionUnion>({
     name: storageName,
     adapter: pulsarEvmAdapter(config, appChains),
+    beforeTxProcess: async () => {
+      // Optional global preflight. Throw here to block before wallet interaction.
+      await assertUserCanSubmitTransactions();
+    },
   }),
 );
 ```
 
+The preflight and metadata validation lives in `@tuwaio/pulsar-core`, not in React. Before wallet interaction or persistence, Pulsar validates that each `title` string is 100 characters or less, each `description` string is 300 characters or less, and the serialized `payload` is 10KB or less. Invalid pending transactions restored by `useInitializeTransactionsPool` are removed from persisted storage during initialization.
+
 ### Step 2: Initialize the Store in Your App
 
 Create a small, client-side component that uses the `useInitializeTransactionsPool` hook. This component's job is to re-activate trackers for pending transactions when the app loads.

package/dist/index.d.mts

@@ -1,38 +1,48 @@
 /**
- * @file This file defines a React hook for initializing the transaction pool.
- * This hook is crucial for resuming the tracking of pending transactions after a page reload.
+ * @file React hook for bootstrapping the Pulsar transaction lifecycle on app start.
+ * It rehydrates pending transaction trackers and can optionally perform an initial
+ * remote history fetch right after tracker initialization.
  */
 /**
- * A React hook that triggers the initialization of the transaction pool when the component mounts.
+ * Configuration for {@link useInitializeTransactionsPool}.
+ */
+type UseInitializeTransactionsPoolParams = {
+    /**
+     * Re-initializes background trackers for all pending transactions stored in the Pulsar store.
+     */
+    initializeTransactionsPool: () => Promise<void>;
+    /**
+     * Optional error handler called when initialization or the optional initial fetch fails.
+     *
+     * @defaultValue `console.error`
+     */
+    onError?: (error: Error) => void;
+};
+/**
+ * Re-initializes pending transaction trackers when the component mounts.
  *
- * This should be used once in your application's layout or root component. It ensures that any
- * pending transactions from a previous session (stored in `localStorage`) are picked up and
-
- * their trackers are re-activated.
+ * Use this hook once in your application's root layout or top-level provider.
+ * It restores tracker activity after reloads and can optionally fetch the initial
+ * remote transaction history right after restoration.
  *
- * @param {object} params - The parameters for the hook.
- * @param {() => Promise<void>} params.initializeTransactionsPool - The `initializeTransactionsPool` function from your Pulsar store instance.
- * @param {(error: Error) => void} [params.onError] - An optional custom function to handle any errors that occur during initialization. Defaults to `console.error`.
+ * @param params Hook configuration.
+ * @param params.initializeTransactionsPool Function that restores trackers for pending transactions.
+ * @param params.onError Optional custom error handler.
  *
  * @example
  * ```tsx
  * import { useInitializeTransactionsPool } from '@tuwaio/pulsar-react';
- * import { pulsarStore } from './path/to/your/store';
  *
- * function AppLayout({ children }) {
- * // This hook will run once when the layout mounts.
- * useInitializeTransactionsPool({
- * initializeTransactionsPool: pulsarStore.getState().initializeTransactionsPool,
- * onError: (err) => console.warn('Failed to re-initialize trackers:', err),
- * });
+ * function AppLayout() {
+ *   useInitializeTransactionsPool({
+ *     initializeTransactionsPool: store.getState().initializeTransactionsPool,
+ *     onError: (error) => console.warn('Failed to restore transactions:', error),
+ *   });
  *
- * return <div>{children}</div>;
+ *   return <div>...</div>;
  * }
  * ```
  */
-declare const useInitializeTransactionsPool: ({ initializeTransactionsPool, onError, }: {
-    initializeTransactionsPool: () => Promise<void>;
-    onError?: (error: Error) => void;
-}) => void;
+declare const useInitializeTransactionsPool: ({ initializeTransactionsPool, onError, }: UseInitializeTransactionsPoolParams) => void;
 
-export { useInitializeTransactionsPool };
+export { type UseInitializeTransactionsPoolParams, useInitializeTransactionsPool };

package/dist/index.d.ts

@@ -1,38 +1,48 @@
 /**
- * @file This file defines a React hook for initializing the transaction pool.
- * This hook is crucial for resuming the tracking of pending transactions after a page reload.
+ * @file React hook for bootstrapping the Pulsar transaction lifecycle on app start.
+ * It rehydrates pending transaction trackers and can optionally perform an initial
+ * remote history fetch right after tracker initialization.
  */
 /**
- * A React hook that triggers the initialization of the transaction pool when the component mounts.
+ * Configuration for {@link useInitializeTransactionsPool}.
+ */
+type UseInitializeTransactionsPoolParams = {
+    /**
+     * Re-initializes background trackers for all pending transactions stored in the Pulsar store.
+     */
+    initializeTransactionsPool: () => Promise<void>;
+    /**
+     * Optional error handler called when initialization or the optional initial fetch fails.
+     *
+     * @defaultValue `console.error`
+     */
+    onError?: (error: Error) => void;
+};
+/**
+ * Re-initializes pending transaction trackers when the component mounts.
  *
- * This should be used once in your application's layout or root component. It ensures that any
- * pending transactions from a previous session (stored in `localStorage`) are picked up and
-
- * their trackers are re-activated.
+ * Use this hook once in your application's root layout or top-level provider.
+ * It restores tracker activity after reloads and can optionally fetch the initial
+ * remote transaction history right after restoration.
  *
- * @param {object} params - The parameters for the hook.
- * @param {() => Promise<void>} params.initializeTransactionsPool - The `initializeTransactionsPool` function from your Pulsar store instance.
- * @param {(error: Error) => void} [params.onError] - An optional custom function to handle any errors that occur during initialization. Defaults to `console.error`.
+ * @param params Hook configuration.
+ * @param params.initializeTransactionsPool Function that restores trackers for pending transactions.
+ * @param params.onError Optional custom error handler.
  *
  * @example
  * ```tsx
  * import { useInitializeTransactionsPool } from '@tuwaio/pulsar-react';
- * import { pulsarStore } from './path/to/your/store';
  *
- * function AppLayout({ children }) {
- * // This hook will run once when the layout mounts.
- * useInitializeTransactionsPool({
- * initializeTransactionsPool: pulsarStore.getState().initializeTransactionsPool,
- * onError: (err) => console.warn('Failed to re-initialize trackers:', err),
- * });
+ * function AppLayout() {
+ *   useInitializeTransactionsPool({
+ *     initializeTransactionsPool: store.getState().initializeTransactionsPool,
+ *     onError: (error) => console.warn('Failed to restore transactions:', error),
+ *   });
  *
- * return <div>{children}</div>;
+ *   return <div>...</div>;
  * }
  * ```
  */
-declare const useInitializeTransactionsPool: ({ initializeTransactionsPool, onError, }: {
-    initializeTransactionsPool: () => Promise<void>;
-    onError?: (error: Error) => void;
-}) => void;
+declare const useInitializeTransactionsPool: ({ initializeTransactionsPool, onError, }: UseInitializeTransactionsPoolParams) => void;
 
-export { useInitializeTransactionsPool };
+export { type UseInitializeTransactionsPoolParams, useInitializeTransactionsPool };

package/dist/index.js

@@ -1 +1 @@
-'use strict';var react=require('react');var c=({initializeTransactionsPool:r,onError:o})=>{react.useEffect(()=>{(async()=>{try{await r();}catch(e){(o??(i=>console.error("Failed to initialize transactions pool:",i)))(e);}})();},[r,o]);};exports.useInitializeTransactionsPool=c;
+'use strict';var react=require('react');var c=({initializeTransactionsPool:r,onError:o})=>{react.useEffect(()=>{let i=true;return (async()=>{try{if(await r(),!i)return}catch(a){(o??(t=>{console.error("[Pulsar] Failed to initialize transactions pool:",t);}))(a);}})(),()=>{i=false;}},[r,o]);};exports.useInitializeTransactionsPool=c;

package/dist/index.mjs

@@ -1 +1 @@
-import {useEffect}from'react';var c=({initializeTransactionsPool:r,onError:o})=>{useEffect(()=>{(async()=>{try{await r();}catch(e){(o??(i=>console.error("Failed to initialize transactions pool:",i)))(e);}})();},[r,o]);};export{c as useInitializeTransactionsPool};
+import {useEffect}from'react';var c=({initializeTransactionsPool:r,onError:o})=>{useEffect(()=>{let i=true;return (async()=>{try{if(await r(),!i)return}catch(a){(o??(t=>{console.error("[Pulsar] Failed to initialize transactions pool:",t);}))(a);}})(),()=>{i=false;}},[r,o]);};export{c as useInitializeTransactionsPool};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuwaio/pulsar-react",
-  "version": "1.0.0-fix-gelato-alpha.2.4635500",
+  "version": "1.0.0-fix-docs-alpha.1.b07dd22",
   "private": false,
   "author": "Oleksandr Tkach",
   "license": "Apache-2.0",
@@ -41,10 +41,10 @@
     "react": ">=19.2.3"
   },
   "devDependencies": {
-    "@types/react": "^19.2.14",
-    "react": "^19.2.4",
+    "@types/react": "^19.2.17",
+    "react": "^19.2.7",
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.3"
   },
   "scripts": {
     "start": "tsup src/index.ts --watch",