@pear-protocol/core-sdk 1.20.0 → 2.0.0

package/dist/core/index.d.ts

@@ -187,7 +187,7 @@ declare class Core {
         get: (query?: HttpTypes.QuoteFeeParamsInput, headers?: ClientHeaders) => Promise<{
             baseBps: string;
             discounts: {
-                scope: "connector" | "all" | "user" | "client_id";
+                scope: "user" | "connector" | "all" | "client_id";
                 rate: string;
             }[];
             finalBps: string;
@@ -3471,16 +3471,19 @@ declare class Core {
             }[];
         }>;
         /**
-         * Closed-trade history, newest close first, composed server-side.
+         * Closed-position history, newest close first, composed server-side.
          *
-         * A page may hold fewer than `limit` trades and still return a `nextCursor` —
+         * A page may hold fewer than `limit` positions and still return a `nextCursor` —
          * page until `nextCursor` is absent, never until a page comes back short.
+         * `includeSteps` is accepted only together with `positionId`: the timeline is
+         * unbounded per row, so it is served one position at a time.
          */
         closed: (query?: HttpTypes.ClosedPositionListParamsInput, headers?: ClientHeaders) => Promise<{
             limit: number;
-            trades: {
+            positions: {
                 positionId: string;
                 connector: "hyperliquid" | "binance" | "bybit" | "okx" | "lighter";
+                status: "CLOSED";
                 openedAt: string;
                 closedAt: string;
                 origin: "PARTIAL" | "PEAR" | "EXTERNAL";
@@ -3547,180 +3550,369 @@ declare class Core {
             }[];
             nextCursor?: string | undefined;
         }>;
+        /**
+         * Open-position history: the realized part of every open position, newest
+         * opened first, composed server-side. Every open position yields exactly
+         * one row — one whose fills are not visible yet comes back as an explicit
+         * zero-state row.
+         *
+         * Page until `nextCursor` is absent, never until a page comes back short.
+         */
+        open: (query?: HttpTypes.OpenPositionListParamsInput, headers?: ClientHeaders) => Promise<{
+            limit: number;
+            positions: {
+                positionId: string;
+                connector: "hyperliquid" | "binance" | "bybit" | "okx" | "lighter";
+                status: "OPEN";
+                openedAt: string;
+                updatedAt: string;
+                origin: "PARTIAL" | "PEAR" | "EXTERNAL";
+                realizedGrossPnl: `-${string}` | `+${string}`;
+                netCashflow: `-${string}` | `+${string}`;
+                totalFees: `-${string}` | `+${string}`;
+                tradeFees: `-${string}` | `+${string}`;
+                pearFees: `-${string}` | `+${string}`;
+                totalFunding: `-${string}` | `+${string}`;
+                initialExposureUSD: Record<string, `-${string}` | `+${string}`>;
+                hasSyntheticFills: boolean;
+                hasProvisionalFills: boolean;
+                unstableHistoricalData: boolean;
+                legs: {
+                    asset: string;
+                    side: "LONG" | "SHORT";
+                    realized: {
+                        quantity: string;
+                        unpricedQuantity: string;
+                        grossPnl: `-${string}` | `+${string}`;
+                        netPnl: `-${string}` | `+${string}`;
+                        exitVwap?: string | undefined;
+                    };
+                    remaining: {
+                        quantity: `-${string}` | `+${string}`;
+                        entryVwap?: string | undefined;
+                    };
+                    totalFees: `-${string}` | `+${string}`;
+                    tradeFees: `-${string}` | `+${string}`;
+                    pearFees: `-${string}` | `+${string}`;
+                    funding: `-${string}` | `+${string}`;
+                }[];
+                steps?: {
+                    at: string;
+                    grossPnl: `-${string}` | `+${string}`;
+                    legs: ({
+                        kind: "INCREASE";
+                        asset: string;
+                        side: "BUY" | "SELL";
+                        quantity: string;
+                        price: string;
+                        tradeFee: `-${string}` | `+${string}`;
+                        pearFee: `-${string}` | `+${string}`;
+                    } | {
+                        kind: "REDUCE";
+                        asset: string;
+                        side: "BUY" | "SELL";
+                        quantity: string;
+                        price: string;
+                        entryBasis: string;
+                        grossPnl: `-${string}` | `+${string}`;
+                        tradeFee: `-${string}` | `+${string}`;
+                        pearFee: `-${string}` | `+${string}`;
+                    } | {
+                        kind: "REDUCE_UNPRICED";
+                        asset: string;
+                        side: "BUY" | "SELL";
+                        quantity: string;
+                        tradeFee: `-${string}` | `+${string}`;
+                        pearFee: `-${string}` | `+${string}`;
+                    })[];
+                    executionId?: string | undefined;
+                }[] | undefined;
+            }[];
+            nextCursor?: string | undefined;
+        }>;
+    };
+    /** Fill-level history; basket commands live under the singular `trade` namespace. */
+    trades: {
+        /** List fill-level trades grouped by execution with compound cursor pagination. */
+        list: (query?: HttpTypes.TradeListParamsInput, headers?: ClientHeaders) => Promise<{
+            limit: number;
+            groups: {
+                id: string;
+                connector: "hyperliquid" | "binance" | "bybit" | "okx" | "lighter";
+                at: string;
+                netCashflow: `-${string}` | `+${string}`;
+                trades: {
+                    id: string;
+                    positionId: string;
+                    symbol: string;
+                    connector: "hyperliquid" | "binance" | "bybit" | "okx" | "lighter";
+                    side: "BUY" | "SELL";
+                    quantity: string;
+                    price: string;
+                    timestamp: string;
+                    settlement: "PROVISIONAL" | "CONFIRMED";
+                    positionEffect: {
+                        kind: "OPEN";
+                        openedQuantity: string;
+                    } | {
+                        kind: "INCREASE";
+                        increasedQuantity: string;
+                    } | {
+                        kind: "REDUCE";
+                        reducedQuantity: string;
+                        realization: {
+                            kind: "PRICED";
+                            quantity: string;
+                            entryPrice: string;
+                            exitPrice: string;
+                            grossPnl: `-${string}` | `+${string}`;
+                        } | {
+                            kind: "UNPRICED";
+                            quantity: string;
+                        };
+                    } | {
+                        kind: "CLOSE";
+                        reducedQuantity: string;
+                        realization: {
+                            kind: "PRICED";
+                            quantity: string;
+                            entryPrice: string;
+                            exitPrice: string;
+                            grossPnl: `-${string}` | `+${string}`;
+                        } | {
+                            kind: "UNPRICED";
+                            quantity: string;
+                        };
+                    } | {
+                        kind: "FLIP";
+                        reducedQuantity: string;
+                        openedQuantity: string;
+                        realization: {
+                            kind: "PRICED";
+                            quantity: string;
+                            entryPrice: string;
+                            exitPrice: string;
+                            grossPnl: `-${string}` | `+${string}`;
+                        } | {
+                            kind: "UNPRICED";
+                            quantity: string;
+                        };
+                    };
+                    basisBefore: {
+                        signedQuantity: `-${string}` | `+${string}`;
+                        basis: {
+                            kind: "FLAT";
+                        } | {
+                            kind: "PRICED";
+                            entryPrice: string;
+                        } | {
+                            kind: "UNPRICED";
+                        };
+                    };
+                    basisAfter: {
+                        signedQuantity: `-${string}` | `+${string}`;
+                        basis: {
+                            kind: "FLAT";
+                        } | {
+                            kind: "PRICED";
+                            entryPrice: string;
+                        } | {
+                            kind: "UNPRICED";
+                        };
+                    };
+                    tradeFee?: `-${string}` | `+${string}` | undefined;
+                    pearFee?: `-${string}` | `+${string}` | undefined;
+                    executionId?: string | undefined;
+                }[];
+                executionId?: string | undefined;
+                scheduleId?: string | undefined;
+                triggerId?: string | undefined;
+            }[];
+            nextCursor?: string | undefined;
+        }>;
     };
     portfolio: {
         overview: (query?: HttpTypes.PortfolioQueryInput, headers?: ClientHeaders) => Promise<{
-            intervals: {
-                oneDay: {
-                    periodStart: string;
-                    periodEnd: string;
-                    volume: number;
-                    openInterest: number;
-                    winningTradesCount: number;
-                    winningTradesUsd: number;
-                    losingTradesCount: number;
-                    losingTradesUsd: number;
-                }[];
-                oneWeek: {
-                    periodStart: string;
-                    periodEnd: string;
-                    volume: number;
-                    openInterest: number;
-                    winningTradesCount: number;
-                    winningTradesUsd: number;
-                    losingTradesCount: number;
-                    losingTradesUsd: number;
-                }[];
-                oneMonth: {
-                    periodStart: string;
-                    periodEnd: string;
-                    volume: number;
-                    openInterest: number;
-                    winningTradesCount: number;
-                    winningTradesUsd: number;
-                    losingTradesCount: number;
-                    losingTradesUsd: number;
-                }[];
-                oneYear: {
-                    periodStart: string;
-                    periodEnd: string;
-                    volume: number;
-                    openInterest: number;
-                    winningTradesCount: number;
-                    winningTradesUsd: number;
-                    losingTradesCount: number;
-                    losingTradesUsd: number;
-                }[];
-                all: {
-                    periodStart: string;
-                    periodEnd: string;
-                    volume: number;
-                    openInterest: number;
-                    winningTradesCount: number;
-                    winningTradesUsd: number;
-                    losingTradesCount: number;
-                    losingTradesUsd: number;
-                }[];
-            } | null;
-            overall: {
-                totalWinningTradesCount: number;
-                totalLosingTradesCount: number;
-                totalWinningUsd: number;
-                totalLosingUsd: number;
-                currentOpenInterest: number;
-                currentTotalVolume: number;
+            realizedCashflow: {
+                grossPnl: number;
+                tradeFees: number;
+                pearFees: number;
+                netCashflow: number;
+                funding: number;
+                netCashflowWithFunding: number;
+                undeterminedQuantityByAsset: Record<string, number>;
+                fundingSynced: boolean;
+                intervals?: {
+                    oneDay: {
+                        grossPnl: number;
+                        tradeFees: number;
+                        pearFees: number;
+                        netCashflow: number;
+                        funding: number;
+                        netCashflowWithFunding: number;
+                        undeterminedQuantityByAsset: Record<string, number>;
+                        periodStart: string;
+                        periodEnd: string;
+                    }[];
+                    oneWeek: {
+                        grossPnl: number;
+                        tradeFees: number;
+                        pearFees: number;
+                        netCashflow: number;
+                        funding: number;
+                        netCashflowWithFunding: number;
+                        undeterminedQuantityByAsset: Record<string, number>;
+                        periodStart: string;
+                        periodEnd: string;
+                    }[];
+                    oneMonth: {
+                        grossPnl: number;
+                        tradeFees: number;
+                        pearFees: number;
+                        netCashflow: number;
+                        funding: number;
+                        netCashflowWithFunding: number;
+                        undeterminedQuantityByAsset: Record<string, number>;
+                        periodStart: string;
+                        periodEnd: string;
+                    }[];
+                    oneYear: {
+                        grossPnl: number;
+                        tradeFees: number;
+                        pearFees: number;
+                        netCashflow: number;
+                        funding: number;
+                        netCashflowWithFunding: number;
+                        undeterminedQuantityByAsset: Record<string, number>;
+                        periodStart: string;
+                        periodEnd: string;
+                    }[];
+                    all: {
+                        grossPnl: number;
+                        tradeFees: number;
+                        pearFees: number;
+                        netCashflow: number;
+                        funding: number;
+                        netCashflowWithFunding: number;
+                        undeterminedQuantityByAsset: Record<string, number>;
+                        periodStart: string;
+                        periodEnd: string;
+                    }[];
+                } | undefined;
+            };
+            closedPositionStats: {
+                totalPositions: number;
+                wins: number;
+                losses: number;
+                hitRate: number | null;
+                profitFactor: number | null;
+                avgWinSize: number | null;
+                avgLossSize: number | null;
+                netPnl: number;
+                positionPnls: number[];
+                positionReturns: number[];
+            };
+            openSnapshot: {
+                openInterest: number;
                 unrealizedPnl: number;
-                realizedPnl: number;
-                totalFees: number;
-                totalTrades: number;
+            };
+            volume: {
+                total: number;
+                intervals?: {
+                    oneDay: {
+                        periodStart: string;
+                        periodEnd: string;
+                        volume: number;
+                    }[];
+                    oneWeek: {
+                        periodStart: string;
+                        periodEnd: string;
+                        volume: number;
+                    }[];
+                    oneMonth: {
+                        periodStart: string;
+                        periodEnd: string;
+                        volume: number;
+                    }[];
+                    oneYear: {
+                        periodStart: string;
+                        periodEnd: string;
+                        volume: number;
+                    }[];
+                    all: {
+                        periodStart: string;
+                        periodEnd: string;
+                        volume: number;
+                    }[];
+                } | undefined;
             };
         }>;
         analytics: (query?: HttpTypes.PortfolioAnalyticsQueryInput, headers?: ClientHeaders) => Promise<{
             config: {
-                rollingWindowDays: number;
                 startDate: string;
                 endDate: string;
+            };
+            realizedCashflow: {
+                grossPnl: number;
+                tradeFees: number;
+                pearFees: number;
+                netCashflow: number;
+                funding: number;
+                netCashflowWithFunding: number;
+                undeterminedQuantityByAsset: Record<string, number>;
                 fundingSynced: boolean;
+                series?: {
+                    grossPnl: number;
+                    tradeFees: number;
+                    pearFees: number;
+                    netCashflow: number;
+                    funding: number;
+                    netCashflowWithFunding: number;
+                    undeterminedQuantityByAsset: Record<string, number>;
+                    periodStart: string;
+                    periodEnd: string;
+                }[] | undefined;
             };
-            portfolio: {
-                realizedOnly: {
-                    pnlAbsolute: number;
-                    pnlPercent: number | null;
-                    hitRate: number | null;
-                    profitFactor: number | null;
-                    avgWinSize: number | null;
-                    avgLossSize: number | null;
-                    avgReturnPerWin: number | null;
-                    avgReturnPerLoss: number | null;
-                    maxDrawdown: number | null;
-                    sharpeRatio: number | null;
-                    sortinoRatio: number | null;
-                };
-                realizedPlusUnrealized: {
-                    pnlAbsolute: number;
-                    pnlPercent: number | null;
-                    hitRate: number | null;
-                    profitFactor: number | null;
-                    avgWinSize: number | null;
-                    avgLossSize: number | null;
-                    avgReturnPerWin: number | null;
-                    avgReturnPerLoss: number | null;
-                    maxDrawdown: number | null;
-                    sharpeRatio: number | null;
-                    sortinoRatio: number | null;
-                };
-                realizedHitRate: number | null;
+            closedPositionStats: {
+                totalPositions: number;
+                wins: number;
+                losses: number;
+                hitRate: number | null;
                 profitFactor: number | null;
                 avgWinSize: number | null;
                 avgLossSize: number | null;
-                breakevenHitRate: number | null;
-                cushion: number | null;
+                netPnl: number;
+                positionPnls: number[];
+                positionReturns: number[];
             };
-            assets: {
-                asset: string;
-                realizedOnly: {
-                    pnlAbsolute: number;
-                    pnlPercent: number | null;
-                    hitRate: number | null;
-                    profitFactor: number | null;
-                    avgWinSize: number | null;
-                    avgLossSize: number | null;
-                    avgReturnPerWin: number | null;
-                    avgReturnPerLoss: number | null;
-                    maxDrawdown: number | null;
-                    sharpeRatio: number | null;
-                    sortinoRatio: number | null;
-                };
-                realizedPlusUnrealized: {
-                    pnlAbsolute: number;
-                    pnlPercent: number | null;
-                    hitRate: number | null;
-                    profitFactor: number | null;
-                    avgWinSize: number | null;
-                    avgLossSize: number | null;
-                    avgReturnPerWin: number | null;
-                    avgReturnPerLoss: number | null;
-                    maxDrawdown: number | null;
-                    sharpeRatio: number | null;
-                    sortinoRatio: number | null;
-                };
-                unrealizedReturnPerDay: number | null;
-            }[];
-            pairs: {
+            pairBreakdown: {
                 key: string;
                 longAssets: string[];
                 shortAssets: string[];
-                trades: number;
+                positions: number;
                 wins: number;
                 losses: number;
                 hitRate: number | null;
-                avgWinSize: number | null;
-                avgLossSize: number | null;
-                expectancy: number | null;
-                totalPnl: number;
+                profitFactor: number | null;
+                expectancy: number;
+                grossPnl: number;
+                tradeFees: number;
+                pearFees: number;
+                netPnl: number;
                 bookPercent: number | null;
             }[];
-            series?: {
-                date: string;
-                trades: number;
-                wins: number;
-                losses: number;
-                dayPnl: number;
-                dayVolume: number;
-                dayFunding: number;
-                dayNetPnl: number;
-                hitRate: number | null;
-                winLossRatio: number | null;
-                rollingHitRate: number | null;
-                rollingWinLossRatio: number | null;
-                dailyReturn: number | null;
-                cumulativeReturn: number;
-                equity: number;
-                drawdown: number;
-                rollingSharpe: number | null;
-                rollingSortino: number | null;
-                rollingVolatility: number | null;
-            }[] | undefined;
+            openSnapshot: {
+                openInterest: number;
+                unrealizedPnl: number;
+            };
+            volume: {
+                total: number;
+                series?: {
+                    periodStart: string;
+                    periodEnd: string;
+                    volume: number;
+                }[] | undefined;
+            };
         }>;
     };
     prices: {
@@ -3917,9 +4109,11 @@ declare class Core {
             limit: number;
             count: number;
             pendingCount: number;
+            totalVolumeUsd: string;
             referees: ({
                 status: "BOUND";
                 tradeCount: number;
+                volumeUsd: string;
                 address?: `0x${string}` | undefined;
                 referredAt?: number | undefined;
             } | {
@@ -4168,6 +4362,7 @@ declare class Core {
             createBulk: (body: HttpTypes.CreateFundingPaymentsRequest, headers?: ClientHeaders) => Promise<Record<string, never>>;
         };
     };
+    /** Basket commands; executed-fill history lives under the plural `trades` namespace. */
     trade: {
         open: (body: HttpTypes.CreateTradeOpen, headers?: ClientHeaders) => Promise<{
             execution: {

package/dist/core/index.js

@@ -309,10 +309,12 @@ class Core {
       });
     }, "openLite"),
     /**
-    * Closed-trade history, newest close first, composed server-side.
+    * Closed-position history, newest close first, composed server-side.
     *
-    * A page may hold fewer than `limit` trades and still return a `nextCursor` —
+    * A page may hold fewer than `limit` positions and still return a `nextCursor` —
     * page until `nextCursor` is absent, never until a page comes back short.
+    * `includeSteps` is accepted only together with `positionId`: the timeline is
+    * unbounded per row, so it is served one position at a time.
     */
     closed: /* @__PURE__ */ __name(async (query, headers) => {
       return await this.client.fetch(`/positions/closed`, {
@@ -320,7 +322,33 @@ class Core {
         headers,
         query
       });
-    }, "closed")
+    }, "closed"),
+    /**
+    * Open-position history: the realized part of every open position, newest
+    * opened first, composed server-side. Every open position yields exactly
+    * one row — one whose fills are not visible yet comes back as an explicit
+    * zero-state row.
+    *
+    * Page until `nextCursor` is absent, never until a page comes back short.
+    */
+    open: /* @__PURE__ */ __name(async (query, headers) => {
+      return await this.client.fetch(`/positions/open`, {
+        method: "GET",
+        headers,
+        query
+      });
+    }, "open")
+  };
+  /** Fill-level history; basket commands live under the singular `trade` namespace. */
+  trades = {
+    /** List fill-level trades grouped by execution with compound cursor pagination. */
+    list: /* @__PURE__ */ __name(async (query, headers) => {
+      return await this.client.fetch(`/trades`, {
+        method: "GET",
+        headers,
+        query
+      });
+    }, "list")
   };
   portfolio = {
     overview: /* @__PURE__ */ __name(async (query, headers) => {
@@ -560,6 +588,7 @@ class Core {
       }, "createBulk")
     }
   };
+  /** Basket commands; executed-fill history lives under the plural `trades` namespace. */
   trade = {
     open: /* @__PURE__ */ __name(async (body, headers) => {
       return await this.client.fetch(`/trade/open`, {

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { Auth } from './auth/index.js';
 import { Core } from './core/index.js';
 import { External } from './external/index.js';
 import { SDKConfig } from './types.js';
+export { AuthErrorContext } from './types.js';
 export { ExternalTrigger, ExternalTriggerSource, HttpTypes, SearchTriggersParams, SearchTriggersResponse, TriggerOutcome } from '@pear-protocol/types';
 export * from '@pear-protocol/utils';
 export { FetchError } from './utils.js';

package/dist/index.js

@@ -91,13 +91,47 @@ class PearSDK {
       });
       if (config.onAuthError) {
         const onAuthError = config.onAuthError;
-        client.useResponse(async (response) => {
-          if (response.status === 401) {
-            onAuthError();
+        const replayed = /* @__PURE__ */ new WeakSet();
+        const recoveries = /* @__PURE__ */ new Map();
+        const recover = /* @__PURE__ */ __name((request, failedCredential) => {
+          const inFlight = recoveries.get(failedCredential);
+          if (inFlight) {
+            logger.debug("[bearer-auth] Recovery already in flight for this credential, waiting...");
+            return inFlight;
+          }
+          const context = {
+            request: request.clone(),
+            failedCredential
+          };
+          const recovery = (async () => onAuthError(context))().finally(() => {
+            if (recoveries.get(failedCredential) === recovery) {
+              recoveries.delete(failedCredential);
+            }
+          });
+          recoveries.set(failedCredential, recovery);
+          return recovery;
+        }, "recover");
+        const bearerAuthMiddleware = /* @__PURE__ */ __name(async (response, retry, request) => {
+          if (response.status !== 401) {
+            return response;
+          }
+          if (replayed.has(request)) {
+            logger.error("[bearer-auth] Replay after recovery returned 401 again, giving up");
             throw new FetchError("Unauthorized. Token may be expired or revoked.", "Unauthorized", 401);
           }
-          return response;
-        });
+          const failedCredential = readBearerCredential(request);
+          logger.warn(`[bearer-auth] 401 received for ${request.method} ${request.url}`);
+          replayed.add(request);
+          try {
+            await recover(request, failedCredential);
+          } catch (err) {
+            logger.error("[bearer-auth] Recovery rejected, not replaying:", String(err));
+            throw new FetchError("Unauthorized. Token may be expired or revoked.", "Unauthorized", 401);
+          }
+          logger.info(`[bearer-auth] Replaying ${request.method} ${request.url}`);
+          return retry();
+        }, "bearerAuthMiddleware");
+        client.useResponse(bearerAuthMiddleware);
       }
     }
     if (authMode === "apikey" && config.auth?.key) {
@@ -111,13 +145,20 @@ class PearSDK {
       });
       if (config.onAuthError) {
         const onAuthError = config.onAuthError;
-        client.useResponse(async (response) => {
-          if (response.status === 401) {
-            onAuthError();
-            throw new FetchError("Unauthorized. API key may be expired or revoked.", "Unauthorized", 401);
+        const apiKeyAuthMiddleware = /* @__PURE__ */ __name(async (response, _retry, request) => {
+          if (response.status !== 401) {
+            return response;
           }
-          return response;
-        });
+          const notified = onAuthError({
+            request: request.clone(),
+            failedCredential: request.headers.get("x-api-key")
+          });
+          void Promise.resolve(notified).catch((err) => {
+            logger.error("[apikey-auth] onAuthError callback rejected:", String(err));
+          });
+          throw new FetchError("Unauthorized. API key may be expired or revoked.", "Unauthorized", 401);
+        }, "apiKeyAuthMiddleware");
+        client.useResponse(apiKeyAuthMiddleware);
       }
     }
     if (config.getTradeAccountId) {
@@ -142,5 +183,13 @@ function isSessionRefreshRequest(url) {
   return pathname.endsWith("/auth/session/refresh") || pathname.endsWith("/auth/session/refresh/token");
 }
 __name(isSessionRefreshRequest, "isSessionRefreshRequest");
+function readBearerCredential(request) {
+  const header = request.headers.get("authorization");
+  if (!header) {
+    return null;
+  }
+  return header.replace(/^Bearer\s+/i, "");
+}
+__name(readBearerCredential, "readBearerCredential");
 
 export { PearSDK as default };

package/dist/types.d.ts

@@ -2,6 +2,20 @@ import { HttpTypes } from '@pear-protocol/types';
 import { ProxyConfig } from '@pear-protocol/utils';
 
 type AuthMode = 'session' | 'bearer' | 'apikey';
+/** What received a 401, so `onAuthError` can tell whose request it was. */
+type AuthErrorContext = {
+    /**
+     * A snapshot clone of the request that received the 401 — same method, URL, headers and
+     * body, but safe to consume: reading it never disturbs the underlying request, in
+     * bearer mode the very request the SDK is about to replay.
+     */
+    request: Request;
+    /**
+     * The credential that request carried: the bearer token without its `Bearer ` prefix, or
+     * the `x-api-key` value. `null` when the getter supplied none.
+     */
+    failedCredential: string | null;
+};
 type SDKConfig = {
     /**
      * API endpoint.
@@ -58,14 +72,21 @@ type SDKConfig = {
      */
     clientId?: string | null;
     /**
-     * Called when server returns 401 (bearer / apikey mode).
+     * Called when the server returns 401 (bearer / apikey mode). The context carries the
+     * request and credential that actually received the 401, not the getter's current value.
+     *
+     * Bearer mode awaits the callback, then replays the original request exactly once with
+     * the token the getter returns afterward; reject to refuse the replay (e.g. after an
+     * identity switch). A second 401 ends the request without calling back. Refresh through
+     * a separate transport — calling this SDK instance from the callback deadlocks. Apikey
+     * mode stays notify-only: no await, no replay.
      *
-     * Example: () => {
-     *   console.error('Unauthorized. Token may be expired or revoked.');
-     *   localStorage.removeItem('apiKey');
+     * Example: async ({ failedCredential }) => {
+     *   if (failedCredential !== activeToken()) throw new Error('identity changed');
+     *   await refreshTokenViaSeparateTransport();
      * }
      */
-    onAuthError?: () => void;
+    onAuthError?: (context: AuthErrorContext) => void | Promise<void>;
     /**
      * Called when the session cannot be recovered (session mode only).
      * Fires after a 401 when the subsequent `POST /auth/refresh` also fails.
@@ -132,4 +153,4 @@ type RequestMiddleware = (request: Request, next: () => Promise<Response>) => Pr
 type ResponseMiddleware = (response: Response, retry: () => Promise<Response>, request: Request) => Promise<Response>;
 type ClientIdBody = HttpTypes.RebalanceManual | HttpTypes.CreateSchedule | HttpTypes.CreateTradeOpen | HttpTypes.CreateTradeAdjust | HttpTypes.CreateTradeClose | HttpTypes.CreateTradeCloseAll | HttpTypes.CreateTriggerOpen | HttpTypes.CreateTriggerClose;
 
-export type { AuthMode, ClientHeaders, ClientIdBody, FetchArgs, FetchInput, FetchParams, Logger, RequestMiddleware, ResponseMiddleware, SDKConfig };
+export type { AuthErrorContext, AuthMode, ClientHeaders, ClientIdBody, FetchArgs, FetchInput, FetchParams, Logger, RequestMiddleware, ResponseMiddleware, SDKConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pear-protocol/core-sdk",
-  "version": "1.20.0",
+  "version": "2.0.0",
   "description": "Pear Protocol Core SDK",
   "private": false,
   "type": "module",
@@ -26,8 +26,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@pear-protocol/types": "^1.32.0",
-    "@pear-protocol/utils": "^0.8.1",
+    "@pear-protocol/types": "^2.0.0",
+    "@pear-protocol/utils": "^1.0.0",
     "qs": "^6.14.0"
   },
   "devDependencies": {