Balance (sdk.balance)

interface Balance {
  userId: string;
  available: string; // Decimal string formatted, e.g. "100.00"
  reserved: string;  // Decimal string formatted, e.g. "25.00"
  total: string;     // Sum of available + reserved, e.g. "125.00"
  currency: string;  // Currency ISO code, e.g. "USD" or "USDC"
  updatedAt: string; // ISO-8601 timestamp
}

async get(userId: string): Promise<Balance>

import { OfferHubSDK } from '@offerhub/sdk';

const sdk = new OfferHubSDK({
  apiUrl: process.env.OFFERHUB_API_URL!,
  apiKey: process.env.OFFERHUB_API_KEY!,
});

const balance = await sdk.balance.get('usr_abc123');
console.log(`Available: ${balance.available} ${balance.currency}`);
console.log(`Reserved: ${balance.reserved} ${balance.currency}`);

async credit(userId: string, params: CreditBalanceParams): Promise<Balance>

const updatedBalance = await sdk.balance.credit('usr_abc123', {
  amount: '50.00',
  currency: 'USD',
  reference: 'bonus_signup_2026',
  description: 'Welcome promotion bonus',
});

console.log('New available balance:', updatedBalance.available);

async debit(userId: string, params: DebitBalanceParams): Promise<Balance>

import { OfferHubSDK, InsufficientFundsError } from '@offerhub/sdk';

try {
  const updatedBalance = await sdk.balance.debit('usr_abc123', {
    amount: '15.00',
    currency: 'USD',
    description: 'Monthly platform fee',
  });
  console.log('Debited successfully. Remaining:', updatedBalance.available);
} catch (error) {
  if (error instanceof InsufficientFundsError) {
    console.error(`Debit failed: need ${error.required}, available ${error.available}`);
  }
}

async reserve(userId: string, params: ReserveBalanceParams): Promise<Balance>

const balanceAfterReserve = await sdk.balance.reserve('usr_buyer123', {
  amount: '100.00',
  orderId: 'ord_xyz789',
  reason: 'Escrow funding reservation',
});

console.log('Available:', balanceAfterReserve.available); // Decreased by 100.00
console.log('Reserved:', balanceAfterReserve.reserved);   // Increased by 100.00

async release(userId: string, params: ReleaseBalanceParams): Promise<Balance>

const balanceAfterRelease = await sdk.balance.release('usr_buyer123', {
  amount: '100.00',
  orderId: 'ord_xyz789',
  reason: 'Order cancelled by buyer prior to escrow funding',
});

console.log('Restored available funds:', balanceAfterRelease.available);

async cancelReservation(userId: string, params: CancelReservationParams): Promise<Balance>

const restoredBalance = await sdk.balance.cancelReservation('usr_buyer123', {
  orderId: 'ord_xyz789',
  reason: 'Deployment timeout',
});

console.log('All reservations cancelled. Available:', restoredBalance.available);

async deductReserved(userId: string, params: DeductReservedParams): Promise<Balance>

const balance = await sdk.balance.deductReserved('usr_buyer123', {
  amount: '100.00',
  orderId: 'ord_xyz789',
  reason: 'Soroban escrow contract funded on-chain',
});

console.log('Reserved balance decremented to:', balance.reserved);

async sync(userId: string): Promise<BalanceSyncResult>

interface BalanceSyncResult {
  synced: boolean;
  previousBalance: Balance;
  currentBalance: Balance;
  discrepancyDetected: boolean;
  adjustment?: string | null;
}

const syncResult = await sdk.balance.sync('usr_abc123');

if (syncResult.discrepancyDetected) {
  console.warn(`Discrepancy reconciled. Adjusted by: ${syncResult.adjustment}`);
} else {
  console.log('Balance in sync with provider.');
}

async verify(userId: string): Promise<BalanceVerification>

interface BalanceVerification {
  isValid: boolean;
  offChainBalance: Balance;
  onChainBalance: {
    address: string;
    balance: string;
    asset: string;
  };
  difference: string;
}

const verification = await sdk.balance.verify('usr_abc123');

if (!verification.isValid) {
  console.error(`Balance mismatch detected! Difference: ${verification.difference}`);
  // Trigger automated sync or alert admin
  await sdk.balance.sync('usr_abc123');
} else {
  console.log('Off-chain and on-chain balances match.');
}