@circle-fin/app-kit 1.6.1 → 1.7.0

package/index.d.ts

@@ -8399,7 +8399,8 @@ declare function isFatalError(error: unknown): boolean;
  *
  * @remarks
  * Check order for KitError instances:
- * 1. If `recoverability === 'RETRYABLE'`, return `true` immediately (priority check).
+ * 1. If `recoverability === 'RETRYABLE'` or `recoverability === 'RESUMABLE'`,
+ *    return `true` immediately (priority check).
  * 2. Otherwise, check if `error.code` is in `DEFAULT_RETRYABLE_ERROR_CODES` (fallback check).
  * 3. Non-KitError instances always return `false`.
  *
@@ -8410,6 +8411,12 @@ declare function isFatalError(error: unknown): boolean;
  * subsequent attempts, such as network timeouts or temporary service
  * unavailability. These errors are safe to retry after a delay.
  *
+ * RESUMABLE errors indicate a multi-phase operation that completed some phases
+ * before failing (for example, a token approval landed but the execution
+ * transaction failed). They are also retryable — re-running the operation is
+ * safe — but callers that have a kit-level `retry()` should prefer it so that
+ * already-completed phases are skipped.
+ *
  * @param error - Unknown error to check
  * @returns True if error is retryable
  *
@@ -8455,9 +8462,19 @@ declare function isFatalError(error: unknown): boolean;
  * })
  * isRetryableError(error3) // false
  *
+ * // KitError with RESUMABLE recoverability (partially-completed operation)
+ * const error4 = new KitError({
+ *   code: 8101,
+ *   name: 'EARN_EXECUTION_FAILED',
+ *   type: 'SERVICE',
+ *   recoverability: 'RESUMABLE',
+ *   message: 'Execution failed after approval',
+ * })
+ * isRetryableError(error4) // true
+ *
  * // Non-KitError
- * const error4 = new Error('Standard error')
- * isRetryableError(error4) // false
+ * const error5 = new Error('Standard error')
+ * isRetryableError(error5) // false
  * ```
  */
 declare function isRetryableError(error: unknown): boolean;
@@ -14844,6 +14861,134 @@ interface ClaimedRewardsResult {
  * {@link EarningProvider.claimRewards}.
  */
 type ClaimRewardsResult = NoClaimableRewardsResult | ClaimedRewardsResult;
+/**
+ * Fields shared by every {@link EarnStep} variant.
+ *
+ * @example
+ * ```typescript
+ * const successBase: EarnStepBase = { state: 'success' }
+ *
+ * const errorBase: EarnStepBase = {
+ *   state: 'error',
+ *   errorMessage: 'Transaction reverted',
+ *   error: new Error('Transaction reverted'),
+ * }
+ * ```
+ */
+interface EarnStepBase {
+    /** Lifecycle state of the phase. */
+    readonly state: 'pending' | 'success' | 'error';
+    /** Human-readable error message, present only when `state` is `'error'`. */
+    readonly errorMessage?: string | undefined;
+    /** Raw error that caused the phase to fail, present only when `state` is `'error'`. */
+    readonly error?: unknown;
+}
+/**
+ * A single phase of a multi-phase earn operation.
+ *
+ * Discriminated on `name`. The `approve` and `execute` variants carry an
+ * optional `txHash` once an on-chain transaction has been submitted; the
+ * `fetchParams` variant never has a `txHash` because it is an API call.
+ *
+ * @example
+ * ```typescript
+ * const fetchStep: EarnStep = { name: 'fetchParams', state: 'success' }
+ * const approveStep: EarnStep = { name: 'approve', state: 'success', txHash: '0xabc...' }
+ * const executeStep: EarnStep = { name: 'execute', state: 'error', errorMessage: 'reverted' }
+ * ```
+ */
+type EarnStep = (EarnStepBase & {
+    readonly name: 'fetchParams';
+}) | (EarnStepBase & {
+    readonly name: 'approve';
+    readonly txHash?: string | undefined;
+}) | (EarnStepBase & {
+    readonly name: 'execute';
+    readonly txHash?: string | undefined;
+});
+/**
+ * Name of an action that earn operations dispatch through the event system.
+ *
+ * `approve` fires during deposits and withdrawals; the others fire for the
+ * operation of the same name.
+ *
+ * @example
+ * ```typescript
+ * const action: EarnActionName = 'approve'
+ * ```
+ */
+type EarnActionName = 'approve' | 'deposit' | 'withdraw' | 'claimRewards';
+/**
+ * Common fields on every earn action payload.
+ *
+ * The `protocol` / `service` discriminators play the same role as the
+ * `protocol` / `version` discriminators on BridgeKit's `CCTPV2ActionBase`:
+ * they keep events distinguishable when earn operations are composed into
+ * multi-protocol flows.
+ *
+ * @example
+ * ```typescript
+ * const base: EarnActionBase = { protocol: 'earn', service: 'earn-service' }
+ * ```
+ */
+interface EarnActionBase {
+    /** The protocol identifier. */
+    readonly protocol: 'earn';
+    /** The backing service identifier. */
+    readonly service: 'earn-service';
+}
+/**
+ * Action map for earn operation event dispatching.
+ *
+ * Each key is an action name and the value is the payload delivered to
+ * handlers registered via the kit's `on()` method. `values` carries the full
+ * {@link EarnStep} for the phase that triggered the event.
+ *
+ * @example
+ * ```typescript
+ * import { EarnKit } from '@circle-fin/earn-kit'
+ *
+ * const kit = new EarnKit()
+ *
+ * kit.on('approve', (payload) => {
+ *   if (payload.values.state === 'success') {
+ *     console.log('approval tx:', payload.values.txHash)
+ *   }
+ * })
+ *
+ * kit.on('deposit', (payload) => {
+ *   console.log(`deposit ${payload.method}: ${payload.values.state}`)
+ * })
+ * ```
+ */
+interface EarnActions {
+    /** Token-approval phase of a deposit or withdrawal. */
+    approve: EarnActionBase & {
+        readonly operation: 'deposit' | 'withdraw';
+        readonly method: 'approve';
+        readonly values: Extract<EarnStep, {
+            name: 'approve';
+        }>;
+    };
+    /** A deposit's `fetchParams` and `execute` phases. */
+    deposit: EarnActionBase & {
+        readonly operation: 'deposit';
+        readonly method: 'fetchParams' | 'execute';
+        readonly values: EarnStep;
+    };
+    /** A withdrawal's `fetchParams` and `execute` phases. */
+    withdraw: EarnActionBase & {
+        readonly operation: 'withdraw';
+        readonly method: 'fetchParams' | 'execute';
+        readonly values: EarnStep;
+    };
+    /** A claim-rewards operation's `fetchParams` and `execute` phases. */
+    claimRewards: EarnActionBase & {
+        readonly operation: 'claimRewards';
+        readonly method: 'fetchParams' | 'execute';
+        readonly values: EarnStep;
+    };
+}
 /**
  * Result from a deposit quote operation.
  *
@@ -15063,17 +15208,22 @@ interface GetClaimRewardsQuoteServiceParams<T extends AdapterCapabilities = Adap
  *
  * @example
  * ```typescript
- * import type { EarningProvider } from '@circle-fin/provider-earn-service'
+ * import type { EarningProvider, EarnActions } from '@circle-fin/provider-earn-service'
+ * import type { Actionable } from '@core/utils'
  * import { ArcTestnet } from '@core/chains'
  *
  * class CustomProvider implements EarningProvider {
  *   readonly name = 'CustomProvider'
  *   readonly supportedChains = [ArcTestnet]
+ *   actionDispatcher: Actionable<EarnActions> | undefined = undefined
+ *   registerDispatcher(dispatcher: Actionable<EarnActions>) { this.actionDispatcher = dispatcher }
  *   async getVaults() { return { vaults: [], errors: [] } }
  *   async getPosition() { throw new Error('Not implemented') }
  *   async deposit() { throw new Error('Not implemented') }
  *   async withdraw() { throw new Error('Not implemented') }
  *   async claimRewards() { throw new Error('Not implemented') }
+ *   supportsRetry(_error: unknown) { return false }
+ *   async retry(_error: unknown): Promise<never> { throw new Error('Not implemented') }
  *   async getDepositQuote() { throw new Error('Not implemented') }
  *   async getWithdrawalQuote() { throw new Error('Not implemented') }
  *   async getClaimRewardsQuote() { throw new Error('Not implemented') }
@@ -15085,6 +15235,21 @@ interface EarningProvider {
     readonly name: string;
     /** Chains supported by this provider. */
     readonly supportedChains: readonly ChainDefinition[];
+    /**
+     * Action dispatcher used to emit step-level events during multi-phase
+     * operations. Populated by {@link EarningProvider.registerDispatcher};
+     * `undefined` until a dispatcher is registered.
+     */
+    actionDispatcher?: Actionable<EarnActions> | undefined;
+    /**
+     * Register the action dispatcher the kit uses to broadcast step events.
+     *
+     * Called once by the kit during construction. Implementations should store
+     * the dispatcher and pass it through to every event emission point.
+     *
+     * @param dispatcher - The kit's shared action dispatcher.
+     */
+    registerDispatcher(dispatcher: Actionable<EarnActions>): void;
     /**
      * Retrieve information about one or more vaults.
      *
@@ -15186,6 +15351,43 @@ interface EarningProvider {
      *   cannot be validated
      */
     getClaimRewardsQuote<T extends AdapterCapabilities>(params: GetClaimRewardsQuoteServiceParams<T>): Promise<ClaimRewardsQuoteInfo>;
+    /**
+     * Report whether {@link EarningProvider.retry} can resume the operation
+     * that produced `error`.
+     *
+     * Returns `true` only for retryable {@link KitError} instances that carry
+     * earn retry context (an {@link EarnErrorTrace} in `cause.trace`) naming
+     * this provider.
+     *
+     * @param error - The error caught from a previous earn operation.
+     * @returns `true` if the operation can be retried via this provider.
+     */
+    supportsRetry(error: unknown): boolean;
+    /**
+     * Resume a multi-phase earn operation that previously failed.
+     *
+     * Reads the {@link EarnErrorTrace} from `error.cause.trace` to determine
+     * the original operation and inputs, then re-runs it, skipping phases that
+     * already completed (for example a successful token approval).
+     *
+     * @remarks
+     * `retry()` re-runs from the first incomplete phase, so it re-fetches
+     * execution params and re-submits the `execute` transaction. The earn
+     * service deduplicates execution requests server-side, which makes this safe
+     * in the common case. However, if a previous attempt broadcast the `execute`
+     * transaction but failed before its receipt was observed (for example a
+     * transient RPC error), that transaction may still be in flight when
+     * `retry()` re-broadcasts. Treat `retry()` as best-effort recovery, not an
+     * atomic operation; for high-value flows, confirm the original transaction's
+     * status before retrying.
+     *
+     * @param error - The error caught from a previous earn operation. Must be a
+     *   retryable {@link KitError} produced by this provider.
+     * @returns Promise resolving to the result of the resumed operation.
+     * @throws {@link KitError} If the error is not a retryable earn error, lacks
+     *   resume context, or the resumed operation itself fails.
+     */
+    retry(error: unknown): Promise<EarnDepositResult | EarnWithdrawResult | ClaimRewardsResult>;
 }
 
 /**
@@ -15193,7 +15395,10 @@ interface EarningProvider {
  *
  * Implement the {@link EarningProvider} interface for yield-bearing vault
  * operations including vault discovery, position queries, deposits,
- * withdrawals, and reward claiming.
+ * withdrawals, and reward claiming. Multi-phase operations (deposit,
+ * withdraw, claimRewards) emit step-level events through the kit's action
+ * dispatcher and attach step progress to thrown errors so callers can resume
+ * via {@link EarnServiceProvider.retry}.
  *
  * @example
  * ```typescript
@@ -15224,6 +15429,8 @@ declare class EarnServiceProvider implements EarningProvider {
     readonly name = "EarnService";
     /** {@inheritdoc} */
     readonly supportedChains: readonly ChainDefinition[];
+    /** {@inheritdoc} */
+    actionDispatcher: Actionable<EarnActions> | undefined;
     private readonly defaultConfig?;
     /**
      * Create a new EarnServiceProvider.
@@ -15232,17 +15439,41 @@ declare class EarnServiceProvider implements EarningProvider {
      *   Per-operation config takes precedence when provided.
      */
     constructor(config?: EarnServiceConfig);
+    /** {@inheritdoc} */
+    registerDispatcher(dispatcher: Actionable<EarnActions>): void;
     private resolveConfig;
+    /**
+     * Run one phase of a multi-phase earn operation: dispatch a `pending` event,
+     * execute it, then dispatch a `success` event (recording the resulting step)
+     * or — on failure — dispatch an `error` event, record the failed step, and
+     * re-throw the original error for the caller to wrap with full step context.
+     *
+     * @typeParam R - The phase's result type.
+     * @param ctx - The operation context (dispatcher, operation, steps, params).
+     * @param action - The action name to dispatch the events under.
+     * @param stepName - The phase name.
+     * @param run - The phase work to execute.
+     * @param txHashOf - Extracts the on-chain transaction hash from the result, if any.
+     * @returns The phase result.
+     */
+    private runPhase;
     /** {@inheritdoc} */
     getVaults(params: GetVaultsServiceParams): Promise<GetVaultsResult>;
     /** {@inheritdoc} */
     getPosition<T extends AdapterCapabilities>(params: GetPositionServiceParams<T>): Promise<PositionInfo>;
     /** {@inheritdoc} */
     deposit<T extends AdapterCapabilities>(params: DepositServiceParams<T>): Promise<EarnDepositResult>;
+    private runDepositFlow;
     /** {@inheritdoc} */
     withdraw<T extends AdapterCapabilities>(params: WithdrawServiceParams<T>): Promise<EarnWithdrawResult>;
+    private runWithdrawFlow;
     /** {@inheritdoc} */
     claimRewards<T extends AdapterCapabilities>(params: ClaimRewardsServiceParams<T>): Promise<ClaimRewardsResult>;
+    private runClaimRewardsFlow;
+    /** {@inheritdoc} */
+    supportsRetry(error: unknown): boolean;
+    /** {@inheritdoc} */
+    retry(error: unknown): Promise<EarnDepositResult | EarnWithdrawResult | ClaimRewardsResult>;
     /** {@inheritdoc} */
     getDepositQuote<T extends AdapterCapabilities>(params: GetDepositQuoteServiceParams<T>): Promise<DepositQuoteInfo>;
     /** {@inheritdoc} */
@@ -15674,6 +15905,12 @@ interface EarnKitConfig<TExtraProviders extends FlexibleEarningProvider[] = []>
  */
 declare class EarnKit {
     private readonly context;
+    /**
+     * Event dispatcher for step-level events emitted during multi-phase earn
+     * operations. Prefer {@link EarnKit.on} / {@link EarnKit.off} over using
+     * this directly.
+     */
+    readonly actionDispatcher: Actionable<EarnActions>;
     /**
      * Create a new EarnKit instance.
      *
@@ -15692,6 +15929,103 @@ declare class EarnKit {
      * ```
      */
     constructor(config?: EarnKitConfig<FlexibleEarningProvider[]>);
+    /**
+     * Register an event handler for an earn operation action.
+     *
+     * Subscribe to step-level events emitted during deposits, withdrawals, and
+     * reward claims. Handlers receive strongly typed payloads based on the
+     * action name. Use the wildcard `'*'` to receive every event. Multiple
+     * handlers can be registered for the same action.
+     *
+     * Action names:
+     * - `'deposit'` — a deposit's `fetchParams` and `execute` phases
+     * - `'withdraw'` — a withdrawal's `fetchParams` and `execute` phases
+     * - `'claimRewards'` — a claim's `fetchParams` and `execute` phases
+     * - `'approve'` — the token-approval phase of a deposit or withdrawal
+     * - `'*'` — all of the above
+     *
+     * @typeParam K - The action name to listen for.
+     * @param action - The action name, or `'*'` for all actions.
+     * @param handler - Callback invoked when the action occurs.
+     *
+     * @example
+     * ```typescript
+     * const kit = new EarnKit()
+     *
+     * kit.on('withdraw', (payload) => {
+     *   if (payload.values.name === 'execute' && payload.values.state === 'success') {
+     *     console.log('withdrawal tx:', payload.values.txHash)
+     *   }
+     * })
+     *
+     * kit.on('*', (payload) => {
+     *   console.log(`${payload.operation}/${payload.method}: ${payload.values.state}`)
+     * })
+     * ```
+     */
+    on<K extends EarnActionName>(action: K, handler: (payload: EarnActions[K]) => void): void;
+    on(action: '*', handler: (payload: EarnActions[EarnActionName]) => void): void;
+    /**
+     * Unregister a previously registered event handler.
+     *
+     * Pass the same handler function reference used during registration. Use
+     * the wildcard `'*'` to remove a handler that was listening to all actions.
+     *
+     * @typeParam K - The action name to stop listening for.
+     * @param action - The action name, or `'*'` for all actions.
+     * @param handler - The handler reference to remove.
+     *
+     * @example
+     * ```typescript
+     * const kit = new EarnKit()
+     *
+     * const handler = (payload: EarnActions['deposit']) => console.log(payload.method)
+     * kit.on('deposit', handler)
+     * // ...later
+     * kit.off('deposit', handler)
+     * ```
+     */
+    off<K extends EarnActionName>(action: K, handler: (payload: EarnActions[K]) => void): void;
+    off(action: '*', handler: (payload: EarnActions[EarnActionName]) => void): void;
+    /**
+     * Resume a multi-phase earn operation that previously failed.
+     *
+     * Pass the {@link KitError} caught from a `deposit`, `withdraw`, or
+     * `claimRewards` call. The error carries the original operation, inputs,
+     * and step progress, so the operation can be re-run while skipping phases
+     * that already completed (for example a successful token approval). Use
+     * `isRetryableError(error)` to check whether retrying is worthwhile before
+     * calling this.
+     *
+     * @remarks
+     * Resuming re-fetches execution params and re-submits the `execute`
+     * transaction; the earn service deduplicates execution server-side, which
+     * makes this safe in the common case. But if a prior attempt broadcast the
+     * `execute` transaction and then failed before its receipt was observed,
+     * that transaction may still be in flight when `retry()` re-broadcasts.
+     * Treat `retry()` as best-effort recovery, not an atomic operation.
+     *
+     * @param error - The error caught from a previous multi-phase earn operation.
+     * @returns A promise resolving to the result of the resumed operation.
+     * @throws {@link KitError} If `error` is not a retryable {@link KitError}
+     *   carrying earn retry context, names an unknown provider, or the resumed
+     *   operation itself fails.
+     *
+     * @example
+     * ```typescript
+     * import { isRetryableError } from '@circle-fin/earn-kit'
+     *
+     * try {
+     *   await kit.deposit(params)
+     * } catch (error) {
+     *   if (isRetryableError(error)) {
+     *     const result = await kit.retry(error)
+     *     console.log('recovered, tx:', 'txHash' in result ? result.txHash : undefined)
+     *   }
+     * }
+     * ```
+     */
+    retry(error: unknown): Promise<EarnDepositResult | EarnWithdrawResult | EarnClaimRewardsResult>;
     /**
      * Return the chains supported by configured earn providers.
      *