@gearbox-protocol/sdk 13.6.0-apy-plugin.4 → 13.6.0-apy-plugin.5

package/dist/cjs/plugins/pools-history/ApyPlugin.js

@@ -31,15 +31,40 @@ var import_apy_parser = require("./apy-parser.js");
 var import_constants = require("./constants.js");
 var import_pool_apy_utils = require("./pool-apy-utils.js");
 const MAP_LABEL = "pools7DAgo";
+const PLUGIN_KEY = "ApyPlugin";
 class ApyPlugin extends import_sdk.BasePlugin {
+  #timerInterval;
   #apyUrl;
   #cacheTtlMs;
   #pools7DAgo;
   #apySnapshot;
-  constructor(loadOnAttach = false, options) {
+  /**
+   * Default timer options
+   * @see PluginTimerOptions
+   */
+  #defaultTimerOptions;
+  /**
+   * When `true`, the timer is started eagerly during the `attach` phase
+   * rather than waiting for an explicit `load` call.
+   **/
+  startTimerOnAttach;
+  constructor(loadOnAttach = false, startTimerOnAttach = false, options) {
     super(loadOnAttach);
+    this.startTimerOnAttach = startTimerOnAttach;
     this.#apyUrl = options?.apyUrl ?? import_constants.APY_STATE_CACHE_URL;
     this.#cacheTtlMs = options?.cacheTtlMs ?? import_constants.DEFAULT_APY_INTERVAL_MS;
+    this.#defaultTimerOptions = options?.timer ?? {
+      refreshPools7DAgoOnTick: false,
+      intervalMs: import_constants.DEFAULT_APY_INTERVAL_MS,
+      onChange: () => {
+      }
+    };
+  }
+  async attach() {
+    await super.attach();
+    if (this.startTimerOnAttach) {
+      this.startTimer();
+    }
   }
   // ---------------------------------------------------------------------------
   // Load — single entry point for all data (on-chain + state-cache)
@@ -182,10 +207,48 @@ class ApyPlugin extends import_sdk.BasePlugin {
     return { data, data7DAgo, pointsBase: poolPointsBase, points };
   }
   // ---------------------------------------------------------------------------
+  // Periodic full refresh
+  // ---------------------------------------------------------------------------
+  /**
+   * Starts a periodic timer that performs a full plugin state refresh.
+   * Only one timer can be active; calling again is a no-op.
+   * @returns Cleanup function that stops the timer.
+   */
+  startTimer(opts) {
+    if (this.#timerInterval) {
+      this.#logger?.debug("plugin timer already running");
+      return () => this.stopTimer();
+    }
+    const intervalMs = opts?.intervalMs ?? this.#defaultTimerOptions.intervalMs;
+    this.#logger?.debug(`starting plugin timer (interval: ${intervalMs}ms)`);
+    this.#timerInterval = setInterval(async () => {
+      try {
+        const prevTimestamp = this.#apySnapshot?.timestamp;
+        await this.load(true, {
+          loadPools7DAgo: opts?.refreshPools7DAgoOnTick ?? this.#defaultTimerOptions.refreshPools7DAgoOnTick
+        });
+        if (this.#apySnapshot?.timestamp !== prevTimestamp) {
+          opts?.onChange?.() ?? this.#defaultTimerOptions.onChange?.();
+          await this.sdk.triggerPluginUpdate(PLUGIN_KEY);
+        }
+      } catch (e) {
+        this.#logger?.error(e, "periodic refresh failed");
+      }
+    }, intervalMs);
+    return () => this.stopTimer();
+  }
+  stopTimer() {
+    if (this.#timerInterval) {
+      clearInterval(this.#timerInterval);
+      this.#timerInterval = void 0;
+      this.#logger?.debug("plugin timer stopped");
+    }
+  }
+  // ---------------------------------------------------------------------------
   // Plugin lifecycle
   // ---------------------------------------------------------------------------
   async syncState() {
-    await this.load();
+    await this.load(true);
   }
   stateHuman(_) {
     return this.pools7DAgo.values().flatMap((p) => ({

package/dist/cjs/sdk/GearboxSDK.js

@@ -110,6 +110,17 @@ class GearboxSDK extends import_base.ChainContractsRegister {
    * @see {@link SDKHooks} for available event names.
    **/
   removeHook = this.#hooks.removeHook.bind(this.#hooks);
+  /**
+   * Triggers the `pluginUpdate` hook.
+   *
+   * Intended to be called by plugins when they update their internal state
+   * outside of the normal `syncState`/`rehydrate` cycle (e.g. via an
+   * internal timer).  Frontend listeners registered with
+   * `sdk.addHook("pluginUpdate", …)` will be notified.
+   **/
+  async triggerPluginUpdate(plugin) {
+    await this.#hooks.triggerHooks("pluginUpdate", { plugin });
+  }
   /**
    * Creates and initialises a new SDK instance by reading live on-chain state.
    *

package/dist/esm/plugins/pools-history/ApyPlugin.js

@@ -21,15 +21,40 @@ import {
   getPoolExtraAPY
 } from "./pool-apy-utils.js";
 const MAP_LABEL = "pools7DAgo";
+const PLUGIN_KEY = "ApyPlugin";
 class ApyPlugin extends BasePlugin {
+  #timerInterval;
   #apyUrl;
   #cacheTtlMs;
   #pools7DAgo;
   #apySnapshot;
-  constructor(loadOnAttach = false, options) {
+  /**
+   * Default timer options
+   * @see PluginTimerOptions
+   */
+  #defaultTimerOptions;
+  /**
+   * When `true`, the timer is started eagerly during the `attach` phase
+   * rather than waiting for an explicit `load` call.
+   **/
+  startTimerOnAttach;
+  constructor(loadOnAttach = false, startTimerOnAttach = false, options) {
     super(loadOnAttach);
+    this.startTimerOnAttach = startTimerOnAttach;
     this.#apyUrl = options?.apyUrl ?? APY_STATE_CACHE_URL;
     this.#cacheTtlMs = options?.cacheTtlMs ?? DEFAULT_APY_INTERVAL_MS;
+    this.#defaultTimerOptions = options?.timer ?? {
+      refreshPools7DAgoOnTick: false,
+      intervalMs: DEFAULT_APY_INTERVAL_MS,
+      onChange: () => {
+      }
+    };
+  }
+  async attach() {
+    await super.attach();
+    if (this.startTimerOnAttach) {
+      this.startTimer();
+    }
   }
   // ---------------------------------------------------------------------------
   // Load — single entry point for all data (on-chain + state-cache)
@@ -172,10 +197,48 @@ class ApyPlugin extends BasePlugin {
     return { data, data7DAgo, pointsBase: poolPointsBase, points };
   }
   // ---------------------------------------------------------------------------
+  // Periodic full refresh
+  // ---------------------------------------------------------------------------
+  /**
+   * Starts a periodic timer that performs a full plugin state refresh.
+   * Only one timer can be active; calling again is a no-op.
+   * @returns Cleanup function that stops the timer.
+   */
+  startTimer(opts) {
+    if (this.#timerInterval) {
+      this.#logger?.debug("plugin timer already running");
+      return () => this.stopTimer();
+    }
+    const intervalMs = opts?.intervalMs ?? this.#defaultTimerOptions.intervalMs;
+    this.#logger?.debug(`starting plugin timer (interval: ${intervalMs}ms)`);
+    this.#timerInterval = setInterval(async () => {
+      try {
+        const prevTimestamp = this.#apySnapshot?.timestamp;
+        await this.load(true, {
+          loadPools7DAgo: opts?.refreshPools7DAgoOnTick ?? this.#defaultTimerOptions.refreshPools7DAgoOnTick
+        });
+        if (this.#apySnapshot?.timestamp !== prevTimestamp) {
+          opts?.onChange?.() ?? this.#defaultTimerOptions.onChange?.();
+          await this.sdk.triggerPluginUpdate(PLUGIN_KEY);
+        }
+      } catch (e) {
+        this.#logger?.error(e, "periodic refresh failed");
+      }
+    }, intervalMs);
+    return () => this.stopTimer();
+  }
+  stopTimer() {
+    if (this.#timerInterval) {
+      clearInterval(this.#timerInterval);
+      this.#timerInterval = void 0;
+      this.#logger?.debug("plugin timer stopped");
+    }
+  }
+  // ---------------------------------------------------------------------------
   // Plugin lifecycle
   // ---------------------------------------------------------------------------
   async syncState() {
-    await this.load();
+    await this.load(true);
   }
   stateHuman(_) {
     return this.pools7DAgo.values().flatMap((p) => ({

package/dist/esm/sdk/GearboxSDK.js

@@ -101,6 +101,17 @@ class GearboxSDK extends ChainContractsRegister {
    * @see {@link SDKHooks} for available event names.
    **/
   removeHook = this.#hooks.removeHook.bind(this.#hooks);
+  /**
+   * Triggers the `pluginUpdate` hook.
+   *
+   * Intended to be called by plugins when they update their internal state
+   * outside of the normal `syncState`/`rehydrate` cycle (e.g. via an
+   * internal timer).  Frontend listeners registered with
+   * `sdk.addHook("pluginUpdate", …)` will be notified.
+   **/
+  async triggerPluginUpdate(plugin) {
+    await this.#hooks.triggerHooks("pluginUpdate", { plugin });
+  }
   /**
    * Creates and initialises a new SDK instance by reading live on-chain state.
    *

package/dist/types/plugins/pools-history/ApyPlugin.d.ts

@@ -9,8 +9,9 @@ export interface ApyPluginState {
 }
 export interface ApyPluginConstructorOptions {
     apyUrl?: string;
-    /** TTL for the shared HTTP cache in milliseconds (default: 10 minutes, see `DEFAULT_APY_INTERVAL_MS`) */
+    /** TTL for the shared HTTP cache in milliseconds (default: same as timer interval) */
     cacheTtlMs?: number;
+    timer?: PluginTimerOptions;
 }
 export interface ApyPluginLoadOptions {
     /**
@@ -20,9 +21,25 @@ export interface ApyPluginLoadOptions {
      */
     loadPools7DAgo?: boolean;
 }
+export interface PluginTimerOptions {
+    /** Polling interval in milliseconds (default: 10 minutes) */
+    intervalMs?: number;
+    /** Callback fired after each successful refresh */
+    onChange?: () => void;
+    /**
+     * When `true`, each tick also refreshes 7d-ago pool state on-chain.
+     */
+    refreshPools7DAgoOnTick?: boolean;
+}
 export declare class ApyPlugin extends BasePlugin<ApyPluginState> implements IGearboxSDKPlugin<ApyPluginState> {
     #private;
-    constructor(loadOnAttach?: boolean, options?: ApyPluginConstructorOptions);
+    /**
+     * When `true`, the timer is started eagerly during the `attach` phase
+     * rather than waiting for an explicit `load` call.
+     **/
+    readonly startTimerOnAttach: boolean;
+    constructor(loadOnAttach?: boolean, startTimerOnAttach?: boolean, options?: ApyPluginConstructorOptions);
+    attach(): Promise<void>;
     load(force?: boolean, loadOptions?: ApyPluginLoadOptions): Promise<ApyPluginState>;
     get loaded(): boolean;
     /**
@@ -39,6 +56,13 @@ export declare class ApyPlugin extends BasePlugin<ApyPluginState> implements IGe
      * @throws if plugin is not loaded
      */
     getPoolsAPY(): GetPoolsAPYResult;
+    /**
+     * Starts a periodic timer that performs a full plugin state refresh.
+     * Only one timer can be active; calling again is a no-op.
+     * @returns Cleanup function that stops the timer.
+     */
+    startTimer(opts?: PluginTimerOptions): () => void;
+    stopTimer(): void;
     syncState(): Promise<void>;
     stateHuman(_?: boolean): Pools7DAgoStateHuman[];
     get state(): ApyPluginState;

package/dist/types/sdk/GearboxSDK.d.ts

@@ -115,6 +115,13 @@ export interface SyncStateOptions {
      **/
     ignoreUpdateablePrices?: boolean;
 }
+/**
+ * Payload carried by the `pluginUpdate` hook.
+ **/
+export interface PluginUpdateInfo {
+    /** Identifier of the plugin that triggered the update (e.g. `"pools7DAgo"`). */
+    plugin: string;
+}
 /**
  * Hook event map for the SDK lifecycle.
  *
@@ -123,10 +130,13 @@ export interface SyncStateOptions {
  *
  * - `syncState` — fired after {@link GearboxSDK.syncState} completes.
  * - `rehydrate` — fired after {@link GearboxSDK.rehydrate} completes.
+ * - `pluginUpdate` — fired by a plugin when its internal state changes
+ *   outside of the normal `syncState`/`rehydrate` cycle (e.g. timer tick).
  **/
 export type SDKHooks = {
     syncState: [SyncStateOptions];
     rehydrate: [SyncStateOptions];
+    pluginUpdate: [PluginUpdateInfo];
 };
 /**
  * Main entry point for the Gearbox SDK.
@@ -175,6 +185,15 @@ export declare class GearboxSDK<const Plugins extends PluginsMap = {}> extends C
      * @see {@link SDKHooks} for available event names.
      **/
     removeHook: <K extends keyof SDKHooks>(hookName: K, fn: (...args: SDKHooks[K]) => void | Promise<void>) => void;
+    /**
+     * Triggers the `pluginUpdate` hook.
+     *
+     * Intended to be called by plugins when they update their internal state
+     * outside of the normal `syncState`/`rehydrate` cycle (e.g. via an
+     * internal timer).  Frontend listeners registered with
+     * `sdk.addHook("pluginUpdate", …)` will be notified.
+     **/
+    triggerPluginUpdate(plugin: string): Promise<void>;
     /**
      * Creates and initialises a new SDK instance by reading live on-chain state.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gearbox-protocol/sdk",
-  "version": "13.6.0-apy-plugin.4",
+  "version": "13.6.0-apy-plugin.5",
   "description": "Gearbox SDK",
   "license": "MIT",
   "main": "./dist/cjs/sdk/index.js",