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

package/dist/types/model/opportunities.schema.d.ts

@@ -568,6 +568,54 @@ declare const opportunityFilterSchema: z.ZodObject<{
   sunset: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodLiteral<"all">]>>;
   rwa: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodLiteral<"all">]>>;
 }, z.core.$strip>;
+/**
+ * {@link OpportunityFilter} as a URL can carry it: every condition is a string,
+ * and a condition that does not narrow is absent rather than empty.
+ **/
+declare const opportunityFilterQueryParamsSchema: z.ZodObject<{
+  kind: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"pool">, z.ZodLiteral<"strategy">]>>;
+  chainIds: z.ZodOptional<z.ZodString>;
+  underlyingType: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"Stable">, z.ZodLiteral<"ETH">, z.ZodLiteral<"BTC">]>>;
+  paused: z.ZodOptional<z.ZodEnum<{
+    false: "false";
+    true: "true";
+  }>>;
+  sunset: z.ZodOptional<z.ZodEnum<{
+    false: "false";
+    true: "true";
+  }>>;
+  rwa: z.ZodOptional<z.ZodEnum<{
+    false: "false";
+    true: "true";
+  }>>;
+}, z.core.$strip>;
+/**
+ * Code for {@link OpportunityFilter} to encode/decode to/from url query parameters.
+ **/
+declare const opportunityFilterQuerySchema: z.ZodCodec<z.ZodObject<{
+  kind: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"pool">, z.ZodLiteral<"strategy">]>>;
+  chainIds: z.ZodOptional<z.ZodString>;
+  underlyingType: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"Stable">, z.ZodLiteral<"ETH">, z.ZodLiteral<"BTC">]>>;
+  paused: z.ZodOptional<z.ZodEnum<{
+    false: "false";
+    true: "true";
+  }>>;
+  sunset: z.ZodOptional<z.ZodEnum<{
+    false: "false";
+    true: "true";
+  }>>;
+  rwa: z.ZodOptional<z.ZodEnum<{
+    false: "false";
+    true: "true";
+  }>>;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodOptional<z.ZodUnion<[z.ZodUnion<readonly [z.ZodLiteral<"pool">, z.ZodLiteral<"strategy">]>, z.ZodLiteral<"all">]>>;
+  chainIds: z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodNumber>, z.ZodLiteral<"all">]>>;
+  underlyingType: z.ZodOptional<z.ZodUnion<[z.ZodUnion<readonly [z.ZodLiteral<"Stable">, z.ZodLiteral<"ETH">, z.ZodLiteral<"BTC">]>, z.ZodLiteral<"all">]>>;
+  paused: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodLiteral<"all">]>>;
+  sunset: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodLiteral<"all">]>>;
+  rwa: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodLiteral<"all">]>>;
+}, z.core.$strip>>;
 /**
  * {@link RateCurvePoint}
  **/
@@ -1185,4 +1233,4 @@ declare const opportunityKeySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   kind: z.ZodLiteral<"strategy">;
 }, z.core.$strip>], "kind">;
 //#endregion
-export { apyBreakdownSchema, opportunityBaseSchema, opportunityDetailSchema, opportunityFilterSchema, opportunityKeySchema, opportunityKindSchema, opportunitySchema, pointRewardsSchema, pointsProgramSchema, poolOpportunityDetailSchema, poolOpportunityKeySchema, poolOpportunitySchema, priceFeedDataSchema, priceFeedSummarySchema, quotaAssetSchema, rateCurvePointSchema, rateCurveSchema, rewardsSchema, strategyOpportunityDetailSchema, strategyOpportunityKeySchema, strategyOpportunitySchema, tokenRewardsSchema };
+export { apyBreakdownSchema, opportunityBaseSchema, opportunityDetailSchema, opportunityFilterQueryParamsSchema, opportunityFilterQuerySchema, opportunityFilterSchema, opportunityKeySchema, opportunityKindSchema, opportunitySchema, pointRewardsSchema, pointsProgramSchema, poolOpportunityDetailSchema, poolOpportunityKeySchema, poolOpportunitySchema, priceFeedDataSchema, priceFeedSummarySchema, quotaAssetSchema, rateCurvePointSchema, rateCurveSchema, rewardsSchema, strategyOpportunityDetailSchema, strategyOpportunityKeySchema, strategyOpportunitySchema, tokenRewardsSchema };

package/dist/types/offchain/AbstractOffchainNamespace.d.ts

@@ -0,0 +1,87 @@
+import { ILogger } from "../sdk/types/logger.js";
+import { HistoryMetric, HistoryRange, HistorySeries } from "../model/history.js";
+import { GearboxAPIOptions, OffchainResult } from "./types.js";
+import { z } from "zod/v4";
+//#region src/offchain/AbstractOffchainNamespace.d.ts
+/**
+ * Query parameters of a backend read. An entry set to `undefined` is a
+ * condition that does not narrow, and is left out of the URL.
+ **/
+type OffchainQuery = Record<string, string | undefined>;
+/**
+ * One backend read.
+ *
+ * @typeParam S - Schema the payload is decoded with.
+ **/
+interface OffchainGetRequest<S extends z.ZodType> {
+  /**
+   * Path below the base URL, e.g. `"/v2/opportunities/pools/1/0x..."`.
+   **/
+  path: string;
+  /**
+   * Parameters to append, see {@link OffchainQuery}.
+   **/
+  query?: OffchainQuery;
+  /**
+   * Schema the payload is decoded with. Decoding is what turns the response
+   * into read model values, so it is required rather than optional.
+   **/
+  schema: S;
+}
+/**
+ * One backend read of a historical series.
+ *
+ * @typeParam M - Metric the series carries.
+ **/
+interface OffchainHistoryRequest<M extends HistoryMetric> {
+  /**
+   * Path of the series, metric included.
+   **/
+  path: string;
+  /**
+   * Metric the response must carry, see
+   * {@link AbstractOffchainNamespace.readHistory}.
+   **/
+  metric: M;
+  /**
+   * Window to cover.
+   **/
+  range: HistoryRange;
+}
+/**
+ * Common logic of every {@link GearboxAPI} namespace.
+ *
+ * A namespace is a set of routes: it knows which path answers which read and
+ * which schema describes the payload. Everything under that — where the
+ * backend is, how long a request may take, how a failure is reported and how a
+ * response becomes read model values — lives here, so a namespace holds
+ * nothing but its routes.
+ **/
+declare abstract class AbstractOffchainNamespace {
+  #private;
+  protected readonly logger?: ILogger;
+  protected constructor(name: string, options?: GearboxAPIOptions);
+  /**
+   * Base URL every read of this namespace is issued against.
+   **/
+  get baseUrl(): string | undefined;
+  /**
+   * Reads one endpoint and decodes its payload.
+   *
+   * The envelope is built here rather than by the caller: the status is
+   * `"success"` whenever this returns at all, because anything else has
+   * already thrown.
+   **/
+  protected get<S extends z.ZodType>(request: OffchainGetRequest<S>): Promise<OffchainResult<z.output<S>>>;
+  /**
+   * Reads one historical series.
+   *
+   * The requested metric is pinned in the schema, which is what upholds the
+   * `HistorySeries<M>` a caller gets back: a response carrying a different
+   * metric is version skew and fails validation like any other mismatch,
+   * rather than being cast into the requested shape.
+   **/
+  protected readHistory<M extends HistoryMetric>(request: OffchainHistoryRequest<M>): Promise<OffchainResult<HistorySeries<M>>>;
+}
+//#endregion
+export { AbstractOffchainNamespace, OffchainGetRequest, OffchainHistoryRequest, OffchainQuery };

package/dist/types/offchain/index.d.ts

@@ -1,7 +1,8 @@
-import { GearboxAPIOptions, OffchainNotImplementedError, OffchainResult, OffchainSourceMeta } from "./types.js";
+import { GearboxAPIOptions, OffchainNotConfiguredError, OffchainNotImplementedError, OffchainResult, OffchainSourceMeta, OffchainTransportError, OffchainValidationError } from "./types.js";
+import { AbstractOffchainNamespace, OffchainGetRequest, OffchainHistoryRequest, OffchainQuery } from "./AbstractOffchainNamespace.js";
 import { OffchainOpportunities } from "./opportunities/OffchainOpportunities.js";
 import "./opportunities/index.js";
 import { OffchainPositions } from "./positions/OffchainPositions.js";
 import "./positions/index.js";
 import { GearboxAPI } from "./GearboxAPI.js";
-export { GearboxAPI, GearboxAPIOptions, OffchainNotImplementedError, OffchainOpportunities, OffchainPositions, OffchainResult, OffchainSourceMeta };
+export { AbstractOffchainNamespace, GearboxAPI, GearboxAPIOptions, OffchainGetRequest, OffchainHistoryRequest, OffchainNotConfiguredError, OffchainNotImplementedError, OffchainOpportunities, OffchainPositions, OffchainQuery, OffchainResult, OffchainSourceMeta, OffchainTransportError, OffchainValidationError };

package/dist/types/offchain/opportunities/OffchainOpportunities.d.ts

@@ -1,59 +1,29 @@
 import { Opportunity, OpportunityFilter, PoolOpportunityDetail, PoolOpportunityKey, StrategyOpportunityDetail, StrategyOpportunityKey } from "../../model/opportunities.js";
 import { HistoryMetric, HistorySeries, OpportunityHistoryQuery } from "../../model/history.js";
 import { GearboxAPIOptions, OffchainResult } from "../types.js";
+import { AbstractOffchainNamespace } from "../AbstractOffchainNamespace.js";
 //#region src/offchain/opportunities/OffchainOpportunities.d.ts
 /**
  * Backend counterpart of the `opportunities` namespace.
- *
- * This is a stub: the HTTP client is not written yet, so list reads answer with
- * an empty list and detail reads throw. Every signature is already the final
- * one, because the backend returns the read model types directly — there is no
- * wire DTO and no mapper between the two.
- *
- * When the transport lands, each method will validate the response against the
- * matching schema from `src/model` before returning it. A validation failure is
- * a version-skew error and is handled exactly like a transport error: the
- * combined SDK drops the backend's contribution in `both` mode and rethrows in
- * `offchain` mode.
  **/
-declare class OffchainOpportunities {
+declare class OffchainOpportunities extends AbstractOffchainNamespace {
   #private;
   constructor(options?: GearboxAPIOptions);
-  /**
-   * Base URL the client will call once the transport is implemented.
-   **/
-  get baseUrl(): string | undefined;
   /**
    * All opportunities the backend knows about, optionally narrowed by
    * {@link OpportunityFilter}.
-   *
-   * @returns An empty list until the backend client is implemented.
    **/
   list(filter?: OpportunityFilter): Promise<OffchainResult<Opportunity[]>>;
   /**
    * Detailed view of one pool opportunity.
-   *
-   * @throws {@link OffchainNotImplementedError} until the backend client is
-   * implemented.
    **/
   getPool(key: PoolOpportunityKey): Promise<OffchainResult<PoolOpportunityDetail>>;
   /**
    * Detailed view of one strategy opportunity.
-   *
-   * @throws {@link OffchainNotImplementedError} until the backend client is
-   * implemented.
    **/
   getStrategy(key: StrategyOpportunityKey): Promise<OffchainResult<StrategyOpportunityDetail>>;
   /**
-   * One historical series of one opportunity. History exists only here:
-   * rebuilding it from the chain would mean an archive read per point.
-   *
-   * The requested metric types the response, so a caller asking for one metric
-   * does not have to narrow the union back down. When the transport lands,
-   * validation is what upholds it: a response carrying a different metric than
-   * the one asked for is a version-skew error like any other.
-   *
-   * @returns An empty series until the backend client is implemented.
+   * One historical series of one opportunity
    **/
   getHistory<M extends HistoryMetric>(query: OpportunityHistoryQuery<M>): Promise<OffchainResult<HistorySeries<M>>>;
 }

package/dist/types/offchain/positions/OffchainPositions.d.ts

@@ -1,29 +1,14 @@
 import { Position, PositionFilter } from "../../model/positions.js";
 import { HistorySeries, PositionHistoryMetric, PositionHistoryQuery } from "../../model/history.js";
 import { GearboxAPIOptions, OffchainResult } from "../types.js";
+import { AbstractOffchainNamespace } from "../AbstractOffchainNamespace.js";
 import { Address } from "viem";
 //#region src/offchain/positions/OffchainPositions.d.ts
 /**
  * Backend counterpart of the `positions` namespace.
- *
- * This is a stub: the HTTP client is not written yet, so reads answer with an
- * empty payload. Every signature is already the final one, because the backend
- * returns the read model types directly — there is no wire DTO and no mapper
- * between the two.
- *
- * When the transport lands, each method will validate the response against the
- * matching schema from `src/model` before returning it. A validation failure is
- * a version-skew error and is handled exactly like a transport error: the
- * combined SDK drops the backend's contribution in `both` mode and rethrows in
- * `offchain` mode.
  **/
-declare class OffchainPositions {
-  #private;
+declare class OffchainPositions extends AbstractOffchainNamespace {
   constructor(options?: GearboxAPIOptions);
-  /**
-   * Base URL the client will call once the transport is implemented.
-   **/
-  get baseUrl(): string | undefined;
   /**
    * Everything a wallet holds, optionally narrowed by {@link PositionFilter}.
    *

package/dist/types/offchain/types.d.ts

@@ -1,4 +1,5 @@
 import { ILogger } from "../sdk/types/logger.js";
+import { z } from "zod/v4";
 //#region src/offchain/types.d.ts
 /**
  * Outcome of the single request that serves a backend read. Unlike the
@@ -42,6 +43,47 @@ interface OffchainResult<T> {
 declare class OffchainNotImplementedError extends Error {
   constructor(endpoint: string);
 }
+/**
+ * Thrown when a read is issued against a client that was never told where the
+ * backend is.
+ **/
+declare class OffchainNotConfiguredError extends Error {
+  constructor(path: string);
+}
+/**
+ * Thrown when the backend could not be reached, or answered with a status
+ * outside the 2xx range.
+ **/
+declare class OffchainTransportError extends Error {
+  /**
+   * URL that was requested, query included.
+   **/
+  readonly url: string;
+  /**
+   * Status the backend answered with, absent when the request never completed.
+   **/
+  readonly status?: number;
+  constructor(url: string, reason: string, status?: number);
+}
+/**
+ * Thrown when the backend answered, but with a payload the read model does not
+ * describe.
+ *
+ * This is version skew rather than a bad request, and it is deliberately
+ * handled like a transport error: the combined SDK drops the backend's
+ * contribution in `both` mode and fails the read in `offchain` mode.
+ **/
+declare class OffchainValidationError extends Error {
+  /**
+   * URL whose payload failed to validate.
+   **/
+  readonly url: string;
+  /**
+   * What did not match, in the order zod reported it.
+   **/
+  readonly issues: readonly z.core.$ZodIssue[];
+  constructor(url: string, issues: readonly z.core.$ZodIssue[]);
+}
 /**
  * Options for creating a {@link GearboxAPI} instance.
  **/
@@ -52,10 +94,16 @@ interface GearboxAPIOptions {
    * @example `"https://api.gearbox.fi"`
    **/
   baseUrl?: string;
+  /**
+   * How long a single request may take, in milliseconds.
+   *
+   * @defaultValue 30 seconds
+   **/
+  timeout?: number;
   /**
    * Logger used for transport and validation diagnostics.
    **/
   logger?: ILogger;
 }
 //#endregion
-export { GearboxAPIOptions, OffchainNotImplementedError, OffchainResult, OffchainSourceMeta };
+export { GearboxAPIOptions, OffchainNotConfiguredError, OffchainNotImplementedError, OffchainResult, OffchainSourceMeta, OffchainTransportError, OffchainValidationError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gearbox-protocol/sdk",
-  "version": "14.12.0-next.79",
+  "version": "14.12.0-next.80",
   "description": "Gearbox SDK",
   "license": "MIT",
   "repository": {
@@ -83,6 +83,7 @@
     "build": "tsdown",
     "dev": "tsdown --watch",
     "example": "tsx scripts/example.ts | pino-pretty",
+    "list-opportunities": "tsx scripts/list-opportunities.ts",
     "test:watch": "vitest --project unit",
     "test:unit": "vitest run --project unit",
     "test:e2e": "vitest run --project e2e",