@gauntlet-xyz/sdk 2.0.0 → 2.5.0

package/src/api/client.ts

@@ -0,0 +1,234 @@
+import type { components } from './generated';
+import { apiGet, type GauntletApiConfig, type QueryParams } from './http';
+
+type Schemas = components['schemas'];
+
+export type UserActivity = Schemas['UserActivity'];
+export type UserActivityResponse = Schemas['UserActivityResponse'];
+export type UserPosition = Schemas['UserPosition'];
+export type UserAllPositionsResponse = Schemas['UserAllPositionsResponse'];
+export type UserPositionLatestResponse = Schemas['UserPositionLatestResponse'];
+export type UserPositionsTimeseriesResponse = Schemas['UserPositionsTimeseriesResponse'];
+export type PositionTimeseriesPoint = Schemas['PositionTimeseriesPoint'];
+export type VaultDetail = Schemas['VaultDetail'];
+export type VaultDetailResponse = Schemas['VaultDetailResponse'];
+export type VaultTimeseriesResponse = Schemas['VaultTimeseriesResponse'];
+export type VaultTimeseriesPoint = Schemas['VaultTimeseriesPoint'];
+export type VaultMetrics = Schemas['VaultMetrics'];
+export type FeaturedVault = Schemas['FeaturedVault'];
+export type FeaturedVaultsResponse = Schemas['FeaturedVaultsResponse'];
+export type StrategyCard = Schemas['StrategyCard'];
+export type StrategyListResponse = Schemas['StrategyListResponse'];
+export type TvlResponse = Schemas['TvlResponse'];
+export type LatestPriceResponse = Schemas['LatestPriceResponse'];
+export type PriceTimeseriesResponse = Schemas['TimeseriesResponse'];
+export type TokenRef = Schemas['TokenRef'];
+export type PartialResponseError = Schemas['PartialResponseError'];
+export type AmountPair = Schemas['AmountPair'];
+export type TimeseriesMeta = Schemas['TimeseriesMeta'];
+export type HealthResponse = Schemas['HealthResponse'];
+export type ChainSyncStatus = Schemas['ChainSyncStatus'];
+
+export interface PageOptions {
+  /** Opaque cursor from a previous response's `meta.next_cursor`. */
+  next?: string;
+  limit?: number;
+  order?: 'asc' | 'desc';
+}
+
+export interface TimeWindowOptions extends PageOptions {
+  /** ISO 8601 date (`2026-01-01`) or RFC 3339 timestamp. */
+  start?: string;
+  end?: string;
+  granularity?: 'hour' | 'day' | 'week' | 'month';
+}
+
+export interface ActivityOptions extends PageOptions {
+  /** CAIP-10 vault id (`"{chainId}:{address}"`). Omit for wallet-wide activity. */
+  vaultId?: string;
+  /**
+   * Wallet-wide feeds only: include activity in hidden (enabled but unlisted)
+   * vaults alongside visible ones. Activity in disabled vaults is never
+   * returned. Ignored when `vaultId` is set.
+   */
+  includeHidden?: boolean;
+}
+
+export interface PositionsOptions extends PageOptions {
+  /**
+   * Include positions in hidden (enabled but unlisted) vaults alongside
+   * visible ones. Positions in disabled vaults are never returned.
+   */
+  includeHidden?: boolean;
+}
+
+export interface LatestPriceOptions {
+  address: string;
+  chainId: number;
+  /** Optional ISO 8601 timestamp for a point-in-time price. */
+  at?: string;
+}
+
+export interface PriceTimeseriesOptions {
+  address: string;
+  chainId: number;
+  start: string;
+  end: string;
+  granularity?: 'raw' | 'hour' | 'day' | 'week' | 'month';
+  limit?: number;
+}
+
+/**
+ * Typed client for the Gaia REST API (api.gauntlet.xyz).
+ *
+ * All response types are generated from the service's OpenAPI spec
+ * (`src/api/generated.ts`, regenerated via `yarn generate:api-types`) so they
+ * cannot drift from the server models. Values are returned exactly as the API
+ * emits them — human-unit decimal strings and CAIP-10 vault ids; use
+ * `decimalToBigInt` / `sharesToBigInt` and `apiVaultIdFromVaultId` /
+ * `vaultIdFromApiVaultId` to convert, or the higher-level `activityFlows` /
+ * `positionHistory` helpers for pre-normalized values.
+ *
+ * Available on a configured client as `client.api`, or standalone:
+ * ```ts
+ * const api = new GauntletApi({ apiKey: process.env.GAUNTLET_API_KEY });
+ * const { data } = await api.vaults();
+ * ```
+ */
+export class GauntletApi {
+  private readonly config: GauntletApiConfig;
+
+  constructor(config: GauntletApiConfig = {}) {
+    this.config = config;
+  }
+
+  private get<T>(path: string, query?: QueryParams): Promise<T> {
+    return apiGet<T>(this.config, path, query);
+  }
+
+  /** GET /health — service liveness (version + uptime). */
+  health(): Promise<HealthResponse> {
+    return this.get('/health');
+  }
+
+  /** GET /health/chains — per-chain indexer sync freshness. */
+  chainSyncStatus(): Promise<ChainSyncStatus[]> {
+    return this.get('/health/chains');
+  }
+
+  /** GET /v1/vaults — all indexed vaults with live metrics (TVL, APY, unit price). */
+  vaults(options: PageOptions = {}): Promise<{ data: VaultDetail[]; meta: TimeseriesMeta }> {
+    return this.get('/v1/vaults', { next: options.next, limit: options.limit });
+  }
+
+  /** GET /v1/vaults/featured — admin-curated featured vault cards. */
+  featuredVaults(): Promise<FeaturedVaultsResponse> {
+    return this.get('/v1/vaults/featured');
+  }
+
+  /** GET /v1/strategies — admin-curated strategy cards. */
+  strategies(): Promise<StrategyListResponse> {
+    return this.get('/v1/strategies');
+  }
+
+  /** GET /v1/vaults/{vault_id} — one vault with live metrics. `vaultId` is CAIP-10. */
+  vault(vaultId: string): Promise<VaultDetailResponse> {
+    return this.get(`/v1/vaults/${encodeURIComponent(vaultId)}`);
+  }
+
+  /** GET /v1/vaults/{vault_id}/definition — raw indexed vault definition. */
+  vaultDefinition(vaultId: string): Promise<unknown> {
+    return this.get(`/v1/vaults/${encodeURIComponent(vaultId)}/definition`);
+  }
+
+  /** GET /v1/vaults/{vault_id}/timeseries — TVL / unit-price / APY history. */
+  vaultTimeseries(
+    vaultId: string,
+    options: TimeWindowOptions = {}
+  ): Promise<VaultTimeseriesResponse> {
+    return this.get(`/v1/vaults/${encodeURIComponent(vaultId)}/timeseries`, { ...options });
+  }
+
+  /** GET /v1/users/{wallet}/positions — all of a wallet's indexed positions with PnL. */
+  positions(
+    walletAddress: string,
+    options: PositionsOptions = {}
+  ): Promise<UserAllPositionsResponse> {
+    return this.get(`/v1/users/${encodeURIComponent(walletAddress)}/positions`, {
+      next: options.next,
+      limit: options.limit,
+      include_hidden: options.includeHidden,
+    });
+  }
+
+  /** GET /v1/users/{wallet}/positions/{vault_id} — one position with PnL breakdown. */
+  position(walletAddress: string, vaultId: string): Promise<UserPositionLatestResponse> {
+    return this.get(
+      `/v1/users/${encodeURIComponent(walletAddress)}/positions/${encodeURIComponent(vaultId)}`
+    );
+  }
+
+  /** GET /v1/users/{wallet}/positions/{vault_id}/timeseries — value / cost-basis / PnL / ROI history. */
+  positionTimeseries(
+    walletAddress: string,
+    vaultId: string,
+    options: TimeWindowOptions = {}
+  ): Promise<UserPositionsTimeseriesResponse> {
+    return this.get(
+      `/v1/users/${encodeURIComponent(walletAddress)}/positions/${encodeURIComponent(vaultId)}/timeseries`,
+      { ...options }
+    );
+  }
+
+  /** GET /v1/users/{wallet}/activity — one page of the wallet's immutable event log. */
+  activity(walletAddress: string, options: ActivityOptions = {}): Promise<UserActivityResponse> {
+    const { vaultId, includeHidden, ...page } = options;
+    return this.get(`/v1/users/${encodeURIComponent(walletAddress)}/activity`, {
+      vault_id: vaultId,
+      include_hidden: includeHidden,
+      ...page,
+    });
+  }
+
+  /**
+   * Iterates the wallet's full activity log, following `meta.next_cursor`
+   * across pages so callers never handle cursors.
+   */
+  async *activityRows(
+    walletAddress: string,
+    options: Omit<ActivityOptions, 'next'> = {}
+  ): AsyncGenerator<UserActivity> {
+    let next: string | undefined;
+    do {
+      const page = await this.activity(walletAddress, { ...options, next });
+      yield* page.data;
+      next = page.meta.next_cursor ?? undefined;
+    } while (next);
+  }
+
+  /** GET /v1/tvl — aggregate Gauntlet TVL, optionally with per-source breakdown. */
+  tvl(options: { includeBreakdown?: boolean } = {}): Promise<TvlResponse> {
+    return this.get('/v1/tvl', { include_breakdown: options.includeBreakdown });
+  }
+
+  /** GET /v1/prices — latest USD price for a token. */
+  latestPrice(options: LatestPriceOptions): Promise<LatestPriceResponse> {
+    return this.get('/v1/prices', {
+      address: options.address,
+      chain_id: options.chainId,
+      at: options.at,
+    });
+  }
+
+  /** GET /v1/prices/timeseries — USD price history for a token. */
+  priceTimeseries(options: PriceTimeseriesOptions): Promise<PriceTimeseriesResponse> {
+    return this.get('/v1/prices/timeseries', {
+      address: options.address,
+      chain_id: options.chainId,
+      start: options.start,
+      end: options.end,
+      granularity: options.granularity,
+      limit: options.limit,
+    });
+  }
+}

package/src/api/decimal.ts

@@ -0,0 +1,49 @@
+import { formatUnits } from 'viem';
+import { DecimalPrecisionError, InvalidDecimalError } from './errors';
+
+const DECIMAL_RE = /^(-?)(\d+)(?:\.(\d+))?$/;
+
+/**
+ * Converts an API decimal string (human units, e.g. `"1250.5"`) into base-unit
+ * bigint at the given token decimals (e.g. `1250500000n` for 6 decimals).
+ *
+ * The conversion is exact: a value with more significant fractional digits
+ * than `decimals` throws `DecimalPrecisionError` rather than rounding.
+ * Hand-rolled instead of viem's `parseUnits`, which silently rounds excess
+ * precision (`parseUnits('1.0000005', 6)` → `1000001n`) — unacceptable for
+ * financial amounts.
+ */
+export function decimalToBigInt(value: string, decimals: number): bigint {
+  if (!Number.isInteger(decimals) || decimals < 0) {
+    throw new InvalidDecimalError(`decimals=${decimals}`);
+  }
+  const match = DECIMAL_RE.exec(value);
+  if (!match) throw new InvalidDecimalError(value);
+
+  const [, sign, whole, frac = ''] = match;
+  if (frac.length > decimals && !/^0*$/.test(frac.slice(decimals))) {
+    throw new DecimalPrecisionError(value, decimals);
+  }
+
+  const scaled = BigInt(whole + frac.slice(0, decimals).padEnd(decimals, '0'));
+  return sign === '-' ? -scaled : scaled;
+}
+
+/**
+ * Formats a base-unit bigint back into the API's human decimal-string
+ * representation (no trailing fractional zeros, no exponent notation).
+ */
+export function bigIntToDecimal(value: bigint, decimals: number): string {
+  if (!Number.isInteger(decimals) || decimals < 0) {
+    throw new InvalidDecimalError(`decimals=${decimals}`);
+  }
+  return formatUnits(value, decimals);
+}
+
+/** Vault shares are always reported in 18-decimal units by the Gaia API. */
+export const SHARE_DECIMALS = 18;
+
+/** Parses an API share amount (decimal string) into base-unit bigint (1e18). */
+export function sharesToBigInt(value: string): bigint {
+  return decimalToBigInt(value, SHARE_DECIMALS);
+}

package/src/api/errors.ts

@@ -0,0 +1,64 @@
+import { GauntletSDKError } from '../errors';
+
+export class GauntletApiError extends GauntletSDKError {
+  readonly status: number;
+  readonly path: string;
+  /** Machine-readable code from the API error envelope (e.g. `NOT_FOUND`), when present. */
+  readonly code?: string;
+
+  constructor(params: { status: number; path: string; message: string; code?: string }) {
+    super(
+      `Gauntlet API request to "${params.path}" failed with ${params.status}: ${params.message}`
+    );
+    this.name = 'GauntletApiError';
+    this.status = params.status;
+    this.path = params.path;
+    this.code = params.code;
+  }
+}
+
+export class InvalidDecimalError extends GauntletSDKError {
+  readonly value: string;
+
+  constructor(value: string) {
+    super(`Value "${value}" is not a valid decimal string`);
+    this.name = 'InvalidDecimalError';
+    this.value = value;
+  }
+}
+
+export class DecimalPrecisionError extends GauntletSDKError {
+  readonly value: string;
+  readonly decimals: number;
+
+  constructor(value: string, decimals: number) {
+    super(
+      `Decimal "${value}" has more fractional digits than the token's ${decimals} decimals; converting would lose precision`
+    );
+    this.name = 'DecimalPrecisionError';
+    this.value = value;
+    this.decimals = decimals;
+  }
+}
+
+export class InvalidCaipIdError extends GauntletSDKError {
+  readonly id: string;
+
+  constructor(id: string) {
+    super(`"${id}" is not a valid CAIP-10 vault id (expected "{chainId}:{address}")`);
+    this.name = 'InvalidCaipIdError';
+    this.id = id;
+  }
+}
+
+export class SettlementTimeoutError extends GauntletSDKError {
+  readonly requestHash: string;
+  readonly timeoutMs: number;
+
+  constructor(requestHash: string, timeoutMs: number) {
+    super(`Request "${requestHash}" did not settle within ${timeoutMs}ms`);
+    this.name = 'SettlementTimeoutError';
+    this.requestHash = requestHash;
+    this.timeoutMs = timeoutMs;
+  }
+}