Top-ups (sdk.topups)

type TopupStatus =
  | 'TOPUP_CREATED'
  | 'TOPUP_AWAITING_USER_CONFIRMATION'
  | 'TOPUP_PROCESSING'
  | 'TOPUP_SUCCEEDED'
  | 'TOPUP_FAILED'
  | 'TOPUP_CANCELED';

interface Topup {
  id: string; // e.g. "top_01HXYZ789"
  userId: string; // e.g. "usr_abc123"
  amount: string; // e.g. "100.00"
  currency: string; // e.g. "USD"
  status: TopupStatus;
  airtm?: {
    confirmationUri?: string; // Redirect URI for buyer checkout
    paymentUrl?: string; // Web URL alias
    airtmPayinId?: string; // AirTM internal payin ID
    expiresAt?: string; // ISO-8601 expiration timestamp
  };
  createdAt: string; // ISO-8601 string
  updatedAt: string; // ISO-8601 string
}

async create(params: CreateTopupParams): Promise<Topup>

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

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

async function startDeposit(userId: string, amount: string) {
  try {
    const topup = await sdk.topups.create({
      userId,
      amount,
      currency: 'USD',
    });

    console.log('Top-up created:', topup.id);
    console.log('Status:', topup.status);

    // Redirect the user to complete payment on AirTM
    if (topup.airtm?.confirmationUri) {
      window.location.href = topup.airtm.confirmationUri;
    }

    return topup;
  } catch (error) {
    if (error instanceof ValidationError) {
      console.error('Validation error:', error.details);
    } else {
      console.error('Failed to initiate top-up:', error);
    }
  }
}

async list(params?: ListTopupsParams): Promise<PaginatedTopups>

interface PaginatedTopups {
  items: Topup[];
  pagination: {
    hasMore: boolean;
    nextCursor?: string | null;
    total?: number;
  };
}

const pendingTopups = await sdk.topups.list({
  userId: 'usr_abc123',
  status: 'TOPUP_AWAITING_USER_CONFIRMATION',
  limit: 10,
});

console.log(`Found ${pendingTopups.items.length} pending top-ups.`);
for (const item of pendingTopups.items) {
  console.log(`- ${item.id}: $${item.amount} ${item.currency}`);
}

async get(id: string): Promise<Topup>

const topup = await sdk.topups.get('top_xyz789');

if (topup.status === 'TOPUP_SUCCEEDED') {
  console.log('Top-up has completed successfully.');
} else {
  console.log(`Current top-up status: ${topup.status}`);
}

async refresh(id: string): Promise<Topup>

const refreshed = await sdk.topups.refresh('top_xyz789');
console.log('Synchronized top-up status:', refreshed.status);

async cancel(id: string): Promise<Topup>

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

try {
  const canceledTopup = await sdk.topups.cancel('top_xyz789');
  console.log(`Top-up ${canceledTopup.id} has been canceled.`);
} catch (error) {
  if (error instanceof InvalidTransitionError) {
    console.error('Cannot cancel: payment is already being processed or completed.');
  }
}