@gearbox-protocol/sdk 14.12.0-next.80 → 14.12.0-next.82

package/dist/types/new-sdk/opportunities/types.d.ts

@@ -1,28 +1,54 @@
 import { Opportunity, OpportunityFilter, PoolOpportunityDetail, PoolOpportunityKey, PoolOpportunityRef, StrategyOpportunityDetail, StrategyOpportunityKey, StrategyOpportunityRef } from "../../model/opportunities.js";
 import { PoolHistoryMetric, StrategyHistoryMetric } from "../../model/history.js";
+import { DataResponse } from "../../model/response.js";
 import "../../model/index.js";
-import { Mode, ReadResult } from "../types.js";
+import { MultichainOpportunitiesService } from "../../sdk/opportunities/MultichainOpportunitiesService.js";
+import "../../sdk/index.js";
+import { OffchainOpportunities } from "../../offchain/opportunities/OffchainOpportunities.js";
+import "../../offchain/index.js";
+import { Mode } from "../types.js";
 import { HistoryReader } from "../utils/history.js";
+import { SourceMerger } from "../utils/types.js";
+import "../utils/index.js";
 //#region src/new-sdk/opportunities/types.d.ts
 /**
- * Reads every mode supports, because either source alone can answer them.
+ * What the `opportunities` namespace offers in every mode.
  **/
 interface OpportunitiesBase {
   /**
-   * All pool and strategy opportunities, optionally narrowed.
-   *
-   * In `both` mode the two lists are unioned by canonical opportunity id and
-   * merged field-wise, with the chain winning any field both sources fill.
+   * All pool and strategy opportunities, optionally narrowed. In `both` mode
+   * each chain is served by whichever source is fresh enough, see
+   * {@link OpportunityMergers}.
    **/
-  list(filter?: OpportunityFilter): Promise<ReadResult<Opportunity[]>>;
+  list(filter?: OpportunityFilter): Promise<DataResponse<Opportunity[]>>;
   /**
    * Detailed view of one pool opportunity.
    **/
-  getPool(key: PoolOpportunityKey): Promise<ReadResult<PoolOpportunityDetail>>;
+  getPool(key: PoolOpportunityKey): Promise<DataResponse<PoolOpportunityDetail>>;
   /**
    * Detailed view of one strategy opportunity.
    **/
-  getStrategy(key: StrategyOpportunityKey): Promise<ReadResult<StrategyOpportunityDetail>>;
+  getStrategy(key: StrategyOpportunityKey): Promise<DataResponse<StrategyOpportunityDetail>>;
+  /**
+   * Narrows an already-read list, rows and metadata alike. `undefined` passes
+   * through, so a read still in flight stays that way.
+   **/
+  filter(response: DataResponse<Opportunity[]> | undefined, filter?: OpportunityFilter): DataResponse<Opportunity[]> | undefined;
+  /**
+   * The chain on its own, for a consumer that shows each source as it arrives.
+   * Throws in `offchain` mode.
+   **/
+  readonly onchain: MultichainOpportunitiesService;
+  /**
+   * The backend on its own, see {@link OpportunitiesBase.onchain}. Throws in
+   * `onchain` mode.
+   **/
+  readonly offchain: OffchainOpportunities;
+  /**
+   * Merge policy of each read, for a consumer combining the two branches
+   * itself, see {@link OpportunityMergers}.
+   **/
+  readonly merge: OpportunityMergers;
 }
 /**
  * Reads only a backend can answer.
@@ -30,37 +56,65 @@ interface OpportunitiesBase {
 interface OpportunitiesOffchainOnly {
   /**
    * Historical charts of one opportunity, one metric and one range at a time:
-   * `history(key).chart("depositApy", "1m")`.
-   *
-   * The key's kind decides which metrics exist, so asking a pool for a
-   * strategy series does not compile.
-   *
-   * Absent in `onchain` mode: the chain serves the present, and rebuilding a
-   * series from it would mean an archive read per point.
+   * `history(key).chart("depositApy", "1m")`. The key's kind decides which
+   * metrics exist, so asking a pool for a strategy series does not compile.
    **/
   history(key: PoolOpportunityRef): HistoryReader<PoolHistoryMetric>;
   history(key: StrategyOpportunityRef): HistoryReader<StrategyHistoryMetric>;
 }
 /**
- * Reads only the chain can answer. Empty for now — every on-chain read the
- * namespace exposes has a backend counterpart.
+ * Reads only the chain can answer. Empty for now.
  **/
 interface OpportunitiesOnchainOnly {}
+/**
+ * How each read combines what the two sources returned: a chain is served by
+ * the backend when it is fresh enough, and by the chain otherwise.
+ **/
+interface OpportunityMergers {
+  list: SourceMerger<Opportunity[]>;
+  pool: SourceMerger<PoolOpportunityDetail>;
+  strategy: SourceMerger<StrategyOpportunityDetail>;
+}
+/**
+ * Which reads the `opportunities` namespace has in each mode. A widened mode
+ * offers what every mode has, i.e. {@link OpportunitiesBase} alone.
+ **/
+interface OpportunitiesOnchainBranch {
+  readonly onchain: MultichainOpportunitiesService;
+}
+/**
+ * The backend on its own, see {@link OpportunitiesOnchainBranch}.
+ **/
+interface OpportunitiesOffchainBranch {
+  readonly offchain: OffchainOpportunities;
+}
+/**
+ * Merge policy of each read, exposed so that a consumer reading the two
+ * branches itself combines them exactly as `both` mode would: a chain is served
+ * by the backend when it is fresh enough, and by the chain otherwise.
+ **/
+interface OpportunityMergers {
+  list: SourceMerger<Opportunity[]>;
+  pool: SourceMerger<PoolOpportunityDetail>;
+  strategy: SourceMerger<StrategyOpportunityDetail>;
+}
+/**
+ * Merging, which only exists where there are two sources to merge.
+ **/
+interface OpportunitiesMerged {
+  readonly merge: OpportunityMergers;
+}
 /**
  * Which methods the `opportunities` namespace has in each mode.
- *
- * A lookup map rather than a conditional type: `both` is spelled out instead of
- * being inferred, and a widened mode degrades to the intersection of what all
- * modes offer rather than silently distributing into a union of everything.
  **/
 interface OpportunitiesByMode {
-  onchain: OpportunitiesBase & OpportunitiesOnchainOnly;
-  offchain: OpportunitiesBase & OpportunitiesOffchainOnly;
-  both: OpportunitiesBase & OpportunitiesOffchainOnly & OpportunitiesOnchainOnly;
+  onchain: OpportunitiesBase & OpportunitiesOnchainOnly & OpportunitiesOnchainBranch;
+  offchain: OpportunitiesBase & OpportunitiesOffchainOnly & OpportunitiesOffchainBranch;
+  both: OpportunitiesBase & OpportunitiesOnchainOnly & OpportunitiesOffchainOnly;
 }
 /**
  * The `opportunities` namespace of a {@link GearboxSDK} in mode `M`.
  **/
 type Opportunities<M extends Mode = Mode> = OpportunitiesByMode[M];
 //#endregion
-export { Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesOffchainOnly, OpportunitiesOnchainOnly };
+export { Opportunities, OpportunitiesBase, OpportunitiesByMode, OpportunitiesMerged, OpportunitiesOffchainBranch, OpportunitiesOffchainOnly, OpportunitiesOnchainBranch, OpportunitiesOnchainOnly, OpportunityMergers };

package/dist/types/new-sdk/positions/PositionsNamespace.d.ts

@@ -1,62 +1,41 @@
-import { ILogger } from "../../sdk/types/logger.js";
 import { PoolPositionRef, Position, PositionFilter, StrategyPositionRef } from "../../model/positions.js";
 import { PoolPositionHistoryMetric, StrategyPositionHistoryMetric } from "../../model/history.js";
+import { DataResponse } from "../../model/response.js";
 import "../../model/index.js";
 import { MultichainSDK } from "../../sdk/MultichainSDK.js";
 import "../../sdk/index.js";
 import { GearboxAPI } from "../../offchain/GearboxAPI.js";
 import "../../offchain/index.js";
-import { ReadResult } from "../types.js";
-import { AbstractNamespace } from "../AbstractNamespace.js";
+import { NamespaceOptions } from "../types.js";
 import { HistoryReader } from "../utils/history.js";
 import "../utils/index.js";
-import { PositionsBase, PositionsOffchainOnly } from "./types.js";
+import { AbstractNamespace } from "../AbstractNamespace.js";
+import { PositionMergers, PositionsBase, PositionsOffchainOnly } from "./types.js";
 import { Address } from "viem";
 //#region src/new-sdk/positions/PositionsNamespace.d.ts
 /**
- * The `positions` namespace of the combined SDK.
- *
- * A stateless router over the two sources, see {@link AbstractNamespace} for the
- * routing itself. What is specific to positions is the reads below and the merge
- * policy at the bottom of the class.
- *
- * The class implements the methods of every mode; {@link GearboxSDK} exposes it
- * as its mode's slice of {@link PositionsByMode}, so calling a method the mode
- * does not have is a compile error rather than a runtime one.
+ * The `positions` namespace of a {@link GearboxSDK}, see
+ * {@link PositionsByMode} for what each mode offers.
  **/
-declare class PositionsNamespace extends AbstractNamespace<Position> implements PositionsBase, PositionsOffchainOnly {
-  #private;
-  constructor(onchain: MultichainSDK | undefined, offchain: GearboxAPI | undefined, logger?: ILogger);
+declare class PositionsNamespace extends AbstractNamespace<MultichainSDK["positions"], GearboxAPI["positions"]> implements PositionsBase, PositionsOffchainOnly {
   /**
-   * {@inheritDoc PositionsBase.list}
+   * {@inheritDoc PositionsBase.merge}
    **/
-  list(wallet: Address, filter?: PositionFilter): Promise<ReadResult<Position[]>>;
+  readonly merge: PositionMergers;
+  constructor(onchain: MultichainSDK | undefined, offchain: GearboxAPI | undefined, options: NamespaceOptions);
   /**
-   * {@inheritDoc PositionsOffchainOnly.history}
+   * {@inheritDoc PositionsBase.list}
    **/
-  history(key: PoolPositionRef): HistoryReader<PoolPositionHistoryMetric>;
-  history(key: StrategyPositionRef): HistoryReader<StrategyPositionHistoryMetric>;
+  list(wallet: Address, filter?: PositionFilter): Promise<DataResponse<Position[]>>;
   /**
-   * Merges the two versions of one position.
-   *
-   * The chain wins every field it fills; the backend fills the rest and owns
-   * {@link OFFCHAIN_OWNED_FIELDS}.
-   *
-   * The rule is onchain-first, field-wise, and never deeper than one level: a
-   * group like `totalValue` or `apy` is taken whole from one source, so a row
-   * never mixes an on-chain token amount with a backend dollar value derived
-   * from a different block.
+   * {@inheritDoc PositionsBase.filter}
    **/
-  protected mergeOne<T extends object>(onchain: T, offchain: T): T;
+  filter(response: DataResponse<Position[]> | undefined, filter?: PositionFilter): DataResponse<Position[]> | undefined;
   /**
-   * Unions the two lists by canonical position id.
-   *
-   * Rows present in both are merged by {@link PositionsNamespace.mergeOne}.
-   * Rows only the backend knows are appended: a chain the SDK does not cover,
-   * or a market it has not loaded, must not hide a position the wallet actually
-   * holds.
+   * {@inheritDoc PositionsOffchainOnly.history}
    **/
-  protected mergeList(onchain: Position[], offchain: Position[]): Position[];
+  history(key: PoolPositionRef): HistoryReader<PoolPositionHistoryMetric>;
+  history(key: StrategyPositionRef): HistoryReader<StrategyPositionHistoryMetric>;
 }
 //#endregion
 export { PositionsNamespace };

package/dist/types/new-sdk/positions/index.d.ts

@@ -1,3 +1,3 @@
-import { Positions, PositionsBase, PositionsByMode, PositionsOffchainOnly, PositionsOnchainOnly } from "./types.js";
+import { PositionMergers, Positions, PositionsBase, PositionsByMode, PositionsMerged, PositionsOffchainBranch, PositionsOffchainOnly, PositionsOnchainBranch, PositionsOnchainOnly } from "./types.js";
 import { PositionsNamespace } from "./PositionsNamespace.js";
-export { Positions, PositionsBase, PositionsByMode, PositionsNamespace, PositionsOffchainOnly, PositionsOnchainOnly };
+export { PositionMergers, Positions, PositionsBase, PositionsByMode, PositionsMerged, PositionsNamespace, PositionsOffchainBranch, PositionsOffchainOnly, PositionsOnchainBranch, PositionsOnchainOnly };

package/dist/types/new-sdk/positions/types.d.ts

@@ -1,22 +1,48 @@
 import { PoolPositionRef, Position, PositionFilter, StrategyPositionRef } from "../../model/positions.js";
 import { PoolPositionHistoryMetric, StrategyPositionHistoryMetric } from "../../model/history.js";
+import { DataResponse } from "../../model/response.js";
 import "../../model/index.js";
-import { Mode, ReadResult } from "../types.js";
+import { MultichainPositionsService } from "../../sdk/positions/MultichainPositionsService.js";
+import "../../sdk/index.js";
+import { OffchainPositions } from "../../offchain/positions/OffchainPositions.js";
+import "../../offchain/index.js";
+import { Mode } from "../types.js";
 import { HistoryReader } from "../utils/history.js";
+import { SourceMerger } from "../utils/types.js";
+import "../utils/index.js";
 import { Address } from "viem";
 //#region src/new-sdk/positions/types.d.ts
 /**
- * Reads every mode supports, because either source alone can answer them.
+ * What the `positions` namespace offers in every mode.
  **/
 interface PositionsBase {
   /**
    * Everything a wallet holds: its pool shares, its credit accounts and the
-   * delayed withdrawals it took over by liquidating, optionally narrowed.
-   *
-   * In `both` mode the two lists are unioned by canonical position id and
-   * merged field-wise, with the chain winning any field both sources fill.
+   * delayed withdrawals it took over by liquidating, optionally narrowed. In
+   * `both` mode each chain is served by whichever source is fresh enough, see
+   * {@link PositionMergers}.
    **/
-  list(wallet: Address, filter?: PositionFilter): Promise<ReadResult<Position[]>>;
+  list(wallet: Address, filter?: PositionFilter): Promise<DataResponse<Position[]>>;
+  /**
+   * Narrows an already-read list, rows and metadata alike. `undefined` passes
+   * through, so a read still in flight stays that way.
+   **/
+  filter(response: DataResponse<Position[]> | undefined, filter?: PositionFilter): DataResponse<Position[]> | undefined;
+  /**
+   * The chain on its own, for a consumer that shows each source as it arrives.
+   * Throws in `offchain` mode.
+   **/
+  readonly onchain: MultichainPositionsService;
+  /**
+   * The backend on its own, see {@link PositionsBase.onchain}. Throws in
+   * `onchain` mode.
+   **/
+  readonly offchain: OffchainPositions;
+  /**
+   * Merge policy of each read, for a consumer combining the two branches
+   * itself, see {@link PositionMergers}.
+   **/
+  readonly merge: PositionMergers;
 }
 /**
  * Reads only a backend can answer.
@@ -24,39 +50,63 @@ interface PositionsBase {
 interface PositionsOffchainOnly {
   /**
    * Historical charts of one position, one metric and one range at a time:
-   * `history(key).chart("netApy", "1m")`.
-   *
-   * The key's kind decides which metrics exist, so asking a pool position for a
-   * strategy series does not compile. Liquidation positions have no history at
-   * all: a delayed withdrawal is a single event rather than a series, which is
-   * why no key names one.
-   *
-   * Absent in `onchain` mode: the chain serves the present, and rebuilding a
-   * series from it would mean an archive read per point.
+   * `history(key).chart("netApy", "1m")`. The key's kind decides which metrics
+   * exist, so asking a pool position for a strategy series does not compile.
+   * Liquidation positions have no charts: a delayed withdrawal is a single
+   * event rather than a series.
    **/
   history(key: PoolPositionRef): HistoryReader<PoolPositionHistoryMetric>;
   history(key: StrategyPositionRef): HistoryReader<StrategyPositionHistoryMetric>;
 }
 /**
- * Reads only the chain can answer. Empty for now — every on-chain read the
- * namespace exposes has a backend counterpart.
+ * Reads only the chain can answer. Empty for now.
  **/
 interface PositionsOnchainOnly {}
+/**
+ * How each read combines what the two sources returned: a chain is served by
+ * the backend when it is fresh enough, and by the chain otherwise.
+ **/
+interface PositionMergers {
+  list: SourceMerger<Position[]>;
+}
+/**
+ * Which reads the `positions` namespace has in each mode. A widened mode offers
+ * what every mode has, i.e. {@link PositionsBase} alone.
+ **/
+interface PositionsOnchainBranch {
+  readonly onchain: MultichainPositionsService;
+}
+/**
+ * The backend on its own, see {@link PositionsOnchainBranch}.
+ **/
+interface PositionsOffchainBranch {
+  readonly offchain: OffchainPositions;
+}
+/**
+ * Merge policy of each read, exposed so that a consumer reading the two
+ * branches itself combines them exactly as `both` mode would: a chain is served
+ * by the backend when it is fresh enough, and by the chain otherwise.
+ **/
+interface PositionMergers {
+  list: SourceMerger<Position[]>;
+}
+/**
+ * Merging, which only exists where there are two sources to merge.
+ **/
+interface PositionsMerged {
+  readonly merge: PositionMergers;
+}
 /**
  * Which methods the `positions` namespace has in each mode.
- *
- * A lookup map rather than a conditional type: `both` is spelled out instead of
- * being inferred, and a widened mode degrades to the intersection of what all
- * modes offer rather than silently distributing into a union of everything.
  **/
 interface PositionsByMode {
   onchain: PositionsBase & PositionsOnchainOnly;
   offchain: PositionsBase & PositionsOffchainOnly;
-  both: PositionsBase & PositionsOffchainOnly & PositionsOnchainOnly;
+  both: PositionsBase & PositionsOnchainOnly & PositionsOffchainOnly;
 }
 /**
  * The `positions` namespace of a {@link GearboxSDK} in mode `M`.
  **/
 type Positions<M extends Mode = Mode> = PositionsByMode[M];
 //#endregion
-export { Positions, PositionsBase, PositionsByMode, PositionsOffchainOnly, PositionsOnchainOnly };
+export { PositionMergers, Positions, PositionsBase, PositionsByMode, PositionsMerged, PositionsOffchainBranch, PositionsOffchainOnly, PositionsOnchainBranch, PositionsOnchainOnly };

package/dist/types/new-sdk/types.d.ts

@@ -1,6 +1,5 @@
 import { ILogger } from "../sdk/types/logger.js";
 import { NetworkType } from "../sdk/chain/chains.js";
-import { MultichainNetworkMeta } from "../sdk/types/multichain.js";
 import { MultichainAttachOptions, MultichainSDK, MultichainSDKOptions } from "../sdk/MultichainSDK.js";
 import "../sdk/index.js";
 import { GearboxAPIOptions } from "../offchain/types.js";
@@ -8,89 +7,25 @@ import { GearboxAPI } from "../offchain/GearboxAPI.js";
 import "../offchain/index.js";
 //#region src/new-sdk/types.d.ts
 /**
- * Which sources a {@link GearboxSDK} reads from. Fixed at construction: a
- * running instance never changes mode, and the mode decides which methods
- * exist at all rather than what they return.
+ * Which sources a {@link GearboxSDK} reads from, and therefore which of its
+ * methods exist.
  **/
 type Mode = "onchain" | "offchain" | "both";
 /**
- * Outcome of the off-chain read behind a response.
- **/
-interface OffchainSourceStatus {
-  /**
-   * Whether the backend served the request.
-   **/
-  status: "success" | "error";
-  /**
-   * Rejection reason. Only set when {@link status} is `"error"`.
-   **/
-  error?: unknown;
-}
-/**
- * Which sources produced a response and which of them failed.
- *
- * Meta is always present, in every mode. A partial answer is the normal case
- * for a multi-chain read, so a caller that ignores this block is choosing to
- * treat "one chain is down" as "these opportunities do not exist".
- **/
-interface SourceMeta {
-  /**
-   * Outcome per queried chain. Empty when the read touched no chain, either
-   * because the SDK is off-chain or because a filter selected no chain.
-   **/
-  chains: MultichainNetworkMeta[];
-  /**
-   * Outcome of the off-chain read, absent when the SDK has no backend source.
-   **/
-  offchain?: OffchainSourceStatus;
-}
-/**
- * What every {@link GearboxSDK} read returns.
- *
- * @typeParam T - Payload type.
- **/
-interface ReadResult<T> {
-  /**
-   * Requested payload, built from every source that answered.
-   **/
-  result: T;
-  /**
-   * Which sources produced it, see {@link SourceMeta}.
-   **/
-  meta: SourceMeta;
-}
-/**
- * Thrown when a read had sources to ask and none of them answered.
- *
- * A read that partially succeeded never throws: it returns what it has and
- * reports the rest in {@link SourceMeta}.
- **/
-declare class AllSourcesFailedError extends Error {
-  /**
-   * Outcome of every source the failed read asked.
-   **/
-  readonly meta: SourceMeta;
-  constructor(action: string, meta: SourceMeta);
-}
-/**
- * On-chain source of a {@link GearboxSDK}: either an already-attached SDK to
- * reuse, or the options to build one with.
- *
- * An injected instance is never re-attached — its owner decides when it syncs.
+ * On-chain source of a {@link GearboxSDK}: either an SDK to reuse, which its
+ * owner keeps attaching itself, or the options to build one with.
  **/
 type OnchainSource = MultichainSDK | PlainMultichainSDKOptions;
 /**
  * {@link MultichainSDKOptions} without plugin typing.
- *
- * The facade exposes the on-chain SDK as a plain `MultichainSDK`; a consumer
- * that injects a plugin-typed instance keeps its own typed reference to it.
  **/
 type PlainMultichainSDKOptions = MultichainSDKOptions<{}>;
 /**
  * Off-chain source of a {@link GearboxSDK}: either a client to reuse or the
- * options to build one with.
+ * options to build one with. The chains come from
+ * {@link GearboxSDKOptions.networks} either way.
  **/
-type OffchainSource = GearboxAPI | GearboxAPIOptions;
+type OffchainSource = GearboxAPI | Omit<GearboxAPIOptions, "chainIds">;
 /**
  * Options for creating a {@link GearboxSDK}.
  *
@@ -102,9 +37,8 @@ interface GearboxSDKOptions<M extends Mode = Mode> {
    **/
   mode: M;
   /**
-   * Chains the SDK covers. This list is authoritative: when {@link onchain} is
-   * an already-attached instance covering a different set of chains, the
-   * mismatch is logged and this list still decides what is read.
+   * Chains the SDK covers, which every read of every source is scoped to. An
+   * injected source covering a different set is rejected at construction.
    **/
   networks: NetworkType[];
   /**
@@ -115,14 +49,27 @@ interface GearboxSDKOptions<M extends Mode = Mode> {
    * Off-chain source. Required in `offchain` and `both` mode.
    **/
   offchain?: OffchainSource;
+  /**
+   * How many seconds the backend may lag the chain and still serve a chain in
+   * `both` mode, see {@link DEFAULT_MAX_OFFCHAIN_LAG}.
+   **/
+  maxOffchainLagSeconds?: number;
   /**
    * Options passed to {@link MultichainSDK.attach}, used only when the SDK
    * builds the on-chain source itself.
    **/
   attach?: MultichainAttachOptions;
+  logger?: ILogger;
+}
+/**
+ * What a {@link GearboxSDK} hands every namespace it builds.
+ **/
+interface NamespaceOptions {
   /**
-   * Logger for source selection and degradation diagnostics.
+   * How far the backend may lag the chain, see
+   * {@link GearboxSDKOptions.maxOffchainLagSeconds}.
    **/
+  maxOffchainLagSeconds: number;
   logger?: ILogger;
 }
 /**
@@ -146,4 +93,4 @@ interface OffchainByMode {
   both: GearboxAPI;
 }
 //#endregion
-export { AllSourcesFailedError, GearboxSDKOptions, Mode, OffchainByMode, OffchainSource, OffchainSourceStatus, OnchainByMode, OnchainSource, PlainMultichainSDKOptions, ReadResult, SourceMeta };
+export { GearboxSDKOptions, Mode, NamespaceOptions, OffchainByMode, OffchainSource, OnchainByMode, OnchainSource, PlainMultichainSDKOptions };

package/dist/types/new-sdk/utils/filterResponse.d.ts

@@ -0,0 +1,16 @@
+import { ChainScopedFilter } from "../../model/filters.js";
+import { DataResponse } from "../../model/response.js";
+import "../../model/index.js";
+//#region src/new-sdk/utils/filterResponse.d.ts
+/**
+ * Narrows an already-read list, rows and metadata alike. `undefined` passes
+ * through, so a read still in flight stays that way.
+ *
+ * @typeParam T - Row type.
+ * @typeParam F - Filter type.
+ * @param matches - Whether one row satisfies the filter, e.g.
+ *   `matchesOpportunityFilter`.
+ **/
+declare function filterResponse<T, F extends ChainScopedFilter>(response: DataResponse<T[]> | undefined, filter: F | undefined, matches: (row: T, filter?: F) => boolean): DataResponse<T[]> | undefined;
+//#endregion
+export { filterResponse };

package/dist/types/new-sdk/utils/history.d.ts

@@ -1,48 +1,18 @@
-import { HistoryChartMetadata, HistoryPoint, HistoryRange } from "../../model/history.js";
+import { HistoryRange, HistorySeries } from "../../model/history.js";
+import { DataResponse } from "../../model/response.js";
 import "../../model/index.js";
-import { SourceMeta } from "../types.js";
 //#region src/new-sdk/utils/history.d.ts
-/**
- * Everything that annotates a chart: what the backend said about the series,
- * plus which sources produced it.
- **/
-interface ChartMetadata extends HistoryChartMetadata {
-  /**
-   * Which sources answered, see {@link SourceMeta}. A chart is backend-only,
-   * so this reports the backend alone.
-   **/
-  source: SourceMeta;
-}
-/**
- * One chart: the points to draw and everything that annotates them.
- **/
-interface Chart {
-  /**
-   * Samples, oldest first.
-   **/
-  data: HistoryPoint[];
-  /**
-   * Annotations of the series, see {@link ChartMetadata}.
-   **/
-  metadata: ChartMetadata;
-}
 /**
  * Reads the charts of one subject, one metric and one range at a time.
  *
- * The constraint is `string` rather than {@link HistoryMetric}, matching
- * {@link HistorySeries}: opportunities and positions carry their own metric
- * unions, and those are free to drift apart.
- *
  * @typeParam Metric - Metrics the subject has.
  **/
 interface HistoryReader<Metric extends string> {
   /**
-   * Historical chart of one metric over one window.
-   *
-   * A metric the subject does not have is a compile error rather than an empty
-   * chart.
+   * Historical chart of one metric over one window. A metric the subject does
+   * not have is a compile error.
    **/
-  chart(metric: Metric, range: HistoryRange): Promise<Chart>;
+  chart(metric: Metric, range: HistoryRange): Promise<DataResponse<HistorySeries<Metric>>>;
 }
 //#endregion
-export { Chart, ChartMetadata, HistoryReader };
+export { HistoryReader };

package/dist/types/new-sdk/utils/index.d.ts

@@ -1,2 +1,5 @@
-import { Chart, ChartMetadata, HistoryReader } from "./history.js";
-export { Chart, ChartMetadata, HistoryReader };
+import { filterResponse } from "./filterResponse.js";
+import { HistoryReader } from "./history.js";
+import { DEFAULT_MAX_OFFCHAIN_LAG, mergeChainList, mergeChainOne } from "./mergeChains.js";
+import { SourceMerger } from "./types.js";
+export { DEFAULT_MAX_OFFCHAIN_LAG, HistoryReader, type SourceMerger, filterResponse, mergeChainList, mergeChainOne };

package/dist/types/new-sdk/utils/mergeChains.d.ts

@@ -0,0 +1,20 @@
+import { ChainScoped, DataResponse } from "../../model/response.js";
+import "../../model/index.js";
+//#region src/new-sdk/utils/mergeChains.d.ts
+/**
+ * How many seconds the backend may lag the chain and still be used.
+ **/
+declare const DEFAULT_MAX_OFFCHAIN_LAG = 120;
+/**
+ * Merges two lists chain by chain: a chain is served by the backend when it is
+ * within `maxLagSeconds` of the chain, by the chain otherwise, and reported as
+ * an error when neither source succeeded.
+ **/
+declare function mergeChainList<T extends ChainScoped>(onchain: DataResponse<T[]> | undefined, offchain: DataResponse<T[]> | undefined, maxLagSeconds?: number): DataResponse<T[]> | undefined;
+/**
+ * Merges two versions of one entity under the same freshness rule as
+ * {@link mergeChainList}, returning the winning response whole.
+ **/
+declare function mergeChainOne<T>(onchain: DataResponse<T> | undefined, offchain: DataResponse<T> | undefined, maxLagSeconds?: number): DataResponse<T> | undefined;
+//#endregion
+export { DEFAULT_MAX_OFFCHAIN_LAG, mergeChainList, mergeChainOne };

package/dist/types/new-sdk/utils/types.d.ts

@@ -0,0 +1,11 @@
+import { DataResponse } from "../../model/response.js";
+import "../../model/index.js";
+//#region src/new-sdk/utils/types.d.ts
+/**
+ * How one read combines what the two sources returned.
+ *
+ * @typeParam T - Payload type of the read.
+ **/
+type SourceMerger<T> = (onchain: DataResponse<T> | undefined, offchain: DataResponse<T> | undefined) => DataResponse<T> | undefined;
+//#endregion
+export { SourceMerger };