Types Reference

import {
  Giza, Agent, Chain, Paginator,
  type Address, type Transaction, type OptimizeOptions,
} from '@gizatech/agent-sdk';

interface GizaConfig {
  chain: Chain;
  apiKey?: string;
  partner?: string;
  apiUrl?: string;
  timeout?: number;
  enableRetry?: boolean;
}

interface ResolvedGizaConfig {
  chain: Chain;
  apiKey: string;
  partner: string;
  apiUrl: string;
  agentId: string;
  timeout: number;
  enableRetry: boolean;
}

type Address = `0x${string}`;

enum Chain {
  DEVNET = -1,
  ETHEREUM = 1,
  POLYGON = 137,
  CHAIN_999 = 999,
  BASE = 8453,
  CHAIN_9745 = 9745,
  SEPOLIA = 11155111,
  ARBITRUM = 42161,
  BASE_SEPOLIA = 84532,
}

class GizaError extends Error {
  constructor(message: string);
}

class ValidationError extends GizaError {
  constructor(message: string);
}

class NotImplementedError extends GizaError {
  constructor(message: string);
}

interface ActivateOptions {
  owner: Address;
  token: Address;
  protocols: string[];
  txHash: string;
  constraints?: ConstraintConfig[];
}

interface AprOptions {
  startDate?: string;
  endDate?: string;
  useExactEndDate?: boolean;
}

interface DeactivateOptions {
  transfer?: boolean;
}

interface PaginationOptions {
  limit?: number;
  sort?: string;
}

interface PerformanceOptions {
  from?: string;
}

interface WaitForDeactivationOptions {
  interval?: number;
  timeout?: number;
  onUpdate?: (status: AgentStatus) => void;
}

interface SmartAccountInfo {
  smartAccountAddress: Address;
  backendWallet: Address;
  origin_wallet: Address;
  chain: Chain;
}

interface ActivateResponse {
  message: string;
  wallet: string;
}

interface DeactivateResponse {
  message: string;
}

interface TopUpResponse {
  message: string;
}

interface RunResponse {
  status: string;
}

interface AgentInfo {
  wallet: Address;
  deposits: Deposit[];
  withdraws?: Withdraw[];
  status: AgentStatus;
  activation_date: string;
  last_deactivation_date?: string;
  last_reactivation_date?: string;
  selected_protocols: string[];
  current_protocols?: string[];
  current_token?: string;
  eoa?: Address;
}

interface PerformanceChartResponse {
  performance: PerformanceData[];
}

interface PerformanceData {
  date: string;
  value: number;
  value_in_usd?: number;
  accrued_rewards?: AccruedRewardsBySymbol;
  portfolio?: Portfolio;
  agent_token_amount?: number;
}

interface WalletAprResponse {
  apr: number;
  sub_periods?: WalletAprSubPeriod[];
}

interface WalletAprSubPeriod {
  start_date: string;
  end_date: string;
  return_: number;
  initial_value: number;
}

type AprByTokenResponse = AllocatedValue[];

interface AllocatedValue {
  value: number;
  value_in_usd: number;
  base_apr?: number;
  total_apr?: number;
}

type Portfolio = Record<string, AllocatedValue>;

interface AccruedRewardsWithValue {
  locked: number;
  unlocked: number;
  locked_value: number;
  locked_value_usd: number;
  unlocked_value: number;
  unlocked_value_usd: number;
  claimed?: number;
  claimed_value?: number;
  claimed_value_usd?: number;
}

type AccruedRewardsBySymbol = Record<string, AccruedRewardsWithValue>;

interface Transaction {
  action: TxAction;
  date: string;
  amount: number;
  amount_out?: number;
  token_type: string;
  status: TxStatus;
  transaction_hash?: string;
  protocol?: string;
  new_token?: string;
  correlation_id?: string;
  apr?: number;
  block_number?: number;
}

interface TransactionHistoryResponse {
  transactions: Transaction[];
  pagination: PaginationInfo;
}

interface PaginationInfo {
  page: number;
  items_per_page: number;
  total_pages: number;
  total_items: number;
}

type WithdrawResponse =
  | FullWithdrawResponse
  | PartialWithdrawResponse;

interface FullWithdrawResponse {
  message: string;
}

interface PartialWithdrawResponse {
  date: string;
  amount: number;
  value: number;
  withdraw_details: WithdrawDetail[];
}

interface WithdrawDetail {
  token: string;
  amount: string;
  value: number;
  value_in_usd: number;
  principal_amount?: number;
  yield_amount?: number;
  fee_amount?: number;
  tx_hash?: string;
  block_number?: number;
}

interface WithdrawalStatusResponse {
  status: AgentStatus;
  wallet: Address;
  activation_date: string;
  last_deactivation_date?: string;
  last_reactivation_date?: string;
}

interface FeeResponse {
  percentage_fee: number;
  fee: number;
}

interface LimitResponse {
  limit: number;
}

interface ClaimedReward {
  token: string;
  amount: number;
  amount_float: number;
  current_price_in_underlying: number;
}

interface ClaimedRewardsResponse {
  rewards: ClaimedReward[];
}

interface DepositListResponse {
  deposits: Deposit[];
}

interface Deposit {
  amount: number;
  token_type: string;
  date?: string;
  tx_hash?: string;
  block_number?: number;
}

interface Withdraw {
  date: string;
  amount: number;
  value: number;
  withdraw_details: WithdrawDetail[];
}

interface ExecutionWithTransactionsDTO {
  id: string;
  execution_plan: unknown;
  execution_type: string;
  status: ExecutionStatus;
  created_at: string;
  transactions: Transaction[];
}

interface PaginatedExecutionDTO {
  items: ExecutionWithTransactionsDTO[];
  total: number;
}

interface LogDTO {
  type: string;
  data: unknown;
}

interface PaginatedLogDTO {
  items: LogDTO[];
  total: number;
}

interface RewardDTO {
  user_id: string;
  base_apr: number;
  extra_apr: number;
  ticker: string;
  reward_amount: number;
  group: string;
  transaction_hash: string;
  start_date: string;
  end_date: string;
  id: string;
  created_at: string;
  updated_at: string;
}

interface PaginatedRewardDTO {
  items: RewardDTO[];
  total: number;
}

interface Protocol {
  name: string;
  is_active: boolean;
  description: string;
  tvl: number;
  apr: number | null;
  pools: ProtocolPool[] | null;
  created_at: string;
  updated_at: string | null;
  chain_id: number;
  parent_protocol: string;
  link: string;
  address: string | null;
  agent_token: string | null;
  title: string | null;
}

interface ProtocolPool {
  name: string;
  apy: number;
}

interface ProtocolsResponse {
  protocols: string[];
}

interface ProtocolsRawResponse {
  protocols: Protocol[];
}

interface ProtocolSupply {
  protocol: string;
  supply: number;
  tokens: string[];
}

interface ProtocolsSupplyResponse {
  protocols: ProtocolSupply[];
}

interface ConstraintConfig {
  kind: string;
  params: Record<string, unknown>;
}

interface ConstraintConfigResponse {
  [key: string]: unknown;
}

interface ChainConfigResponse {
  [key: string]: unknown;
}

interface GlobalConfigResponse {
  min_withdraw_usd: number;
  optimizer_threshold_usd: number;
  max_protocol_liquidity_percentage: number;
  constraints: ConstraintConfigResponse;
  chains: Record<string, ChainConfigResponse>;
}

interface HealthcheckResponse {
  message: string;
  version: string;
  time: string;
}

interface ChainsResponse {
  chain_ids: number[];
}

interface TokenDistributionItem {
  token: string;
  amount: number;
  percentage: number;
}

interface ProtocolDistribution {
  protocol: string;
  amount: number;
  percentage: number;
}

interface LiquidityDistribution {
  initial_deposits: TokenDistributionItem[];
  current_tokens: TokenDistributionItem[];
  protocols: ProtocolDistribution[];
}

interface Statistics {
  total_balance: number;
  total_deposits: number;
  total_users: number;
  total_transactions: number;
  total_apr: number;
  liquidity_distribution: LiquidityDistribution;
}

interface TVLResponse {
  tvl: number;
}

interface TokenInfo {
  address: string;
  symbol: string;
  decimals: number;
  balance: number;
  current_price: number;
}

interface TokensResponse {
  tokens: TokenInfo[];
}

enum AgentStatus {
  UNKNOWN = 'unknown',
  ACTIVATING = 'activating',
  ACTIVATION_FAILED = 'activation_failed',
  ACTIVATED = 'activated',
  RUNNING = 'running',
  RUN_FAILED = 'run_failed',
  BLOCKED = 'blocked',
  DEACTIVATING = 'deactivating',
  DEACTIVATION_FAILED = 'deactivation_failed',
  DEACTIVATED = 'deactivated',
  EMERGENCY = 'emergency',
  DEACTIVATED_FEE_NOT_PAID = 'deactivated_fee_not_paid',
  BRIDGING = 'bridging',
}

enum TxAction {
  UNKNOWN = 'unknown',
  APPROVE = 'approve',
  DEPOSIT = 'deposit',
  TRANSFER = 'transfer',
  BRIDGE = 'bridge',
  WITHDRAW = 'withdraw',
  SWAP = 'swap',
  REFILL_GAS_TANK = 'refill_gas_tank',
  WRAP = 'wrap',
  UNWRAP = 'unwrap',
  FEE_TRANSFER = 'fee_transfer',
}

enum TxStatus {
  UNKNOWN = 'unknown',
  PENDING = 'pending',
  APPROVED = 'approved',
  CANCELLED = 'cancelled',
  FAILED = 'failed',
}

enum SortOrder {
  DATE_ASC = 'date_asc',
  DATE_DESC = 'date_desc',
}

enum Order {
  ASC = 'asc',
  DESC = 'desc',
}

enum Period {
  ALL = 'all',
  DAY = 'day',
}

enum ExecutionStatus {
  RUNNING = 'running',
  FAILED = 'failed',
  SUCCESS = 'success',
}

interface OptimizeOptions {
  chain?: Chain;
  token: Address;
  capital: string;
  currentAllocations: Record<string, string>;
  protocols: string[];
  constraints?: ConstraintConfig[];
  wallet?: Address;
}

interface OptimizeResponse {
  optimization_result: OptimizationResult;
  action_plan: ActionDetail[];
  calldata: CalldataInfo[];
}

interface OptimizationResult {
  allocations: ProtocolAllocation[];
  total_costs: number;
  weighted_apr_initial: number;
  weighted_apr_final: number;
  apr_improvement: number;
  gas_estimate_usd?: number;
  break_even_days?: number;
}

interface ProtocolAllocation {
  protocol: string;
  allocation: string;
  apr: number;
}

interface ActionDetail {
  action_type: 'deposit' | 'withdraw';
  protocol: string;
  amount: string;
  underlying_amount?: string;
}

interface CalldataInfo {
  contract_address: string;
  function_name: string;
  parameters: string[];
  value: string;
  protocol: string;
  description: string;
}

enum WalletConstraints {
  MIN_PROTOCOLS = 'min_protocols',
  MAX_ALLOCATION_AMOUNT_PER_PROTOCOL = 'max_allocation_amount_per_protocol',
  MAX_AMOUNT_PER_PROTOCOL = 'max_amount_per_protocol',
  MIN_AMOUNT = 'min_amount',
  EXCLUDE_PROTOCOL = 'exclude_protocol',
  MIN_ALLOCATION_AMOUNT_PER_PROTOCOL = 'min_allocation_amount_per_protocol',
}

interface ConstraintConfig {
  kind: WalletConstraints;
  params: Record<string, unknown>;
}

class Paginator<T> implements AsyncIterable<T> {
  async *[Symbol.asyncIterator](): AsyncIterableIterator<T>;
  async page(num: number, opts?: { limit?: number }): Promise<PaginatedResponse<T>>;
  async first(count?: number): Promise<T[]>;
}

interface PaginatedResponse<T> {
  items: T[];
  total: number;
  page: number;
  limit: number;
  hasMore: boolean;
}

type PageFetcher<T> = (
  page: number,
  limit: number,
) => Promise<PaginatedResponse<T>>;

class GizaError extends Error {
  constructor(message: string);
}

class ValidationError extends GizaError {
  constructor(message: string);
}

class NotImplementedError extends GizaError {
  constructor(message: string);
}

class GizaAPIError extends GizaError {
  readonly statusCode: number;
  readonly responseData: unknown;
  readonly requestUrl?: string;
  readonly requestMethod?: string;
  readonly friendlyMessage: string;

  constructor(
    message: string,
    statusCode: number,
    responseData?: unknown,
    requestUrl?: string,
    requestMethod?: string,
  );

  static fromResponse(
    statusCode: number,
    responseData: unknown,
    requestUrl?: string,
    requestMethod?: string,
  ): GizaAPIError;

  toJSON(): object;
}

class TimeoutError extends GizaError {
  constructor(timeout: number, message?: string);
}

class NetworkError extends GizaError {
  constructor(message: string);
}

const DEFAULT_AGENT_ID = 'giza-app';

const DEFAULT_TIMEOUT = 45000;

const CHAIN_NAMES: Record<Chain, string> = {
  [-1]: 'Devnet',
  [1]: 'Ethereum',
  [137]: 'Polygon',
  [999]: 'Chain 999',
  [8453]: 'Base',
  [9745]: 'Chain 9745',
  [11155111]: 'Sepolia',
  [42161]: 'Arbitrum',
  [84532]: 'Base Sepolia',
};