Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

15.3 KB
Raw Blame
import { callCoreCommand } from '../coreCommandClient';

/**
 * Credit balance payload returned by `GET /payments/credits/balance`.
 *
 * Mirrors the backend shape defined in
 * `backend-1/src/services/user/balanceService.ts` → `getCreditBalance(userId)`,
 * which in turn derives from `IUser.usage.promotionBalanceUsd` on the user
 * model and the team-level top-up ledger.
 */
export interface CreditBalance {
  /**
   * Promotional credit balance on the user document (signup bonus, coupons,
   * referral rewards). Corresponds to `IUserUsage.promotionBalanceUsd`.
   */
  promotionBalanceUsd: number;
  /**
   * Team-level top-up balance (paid credits that cover overage once the
   * included cycle budget is exhausted). Returned by `getTeamTopup(userId)`.
   */
  teamTopupUsd: number;
}

export interface TeamUsagePlanSummary {
  plan: string;
  name: string;
  marginPercent: number;
  payAsYouGoMarginPercent: number;
  discountVsPayAsYouGoPercent: number;
}

export interface TeamUsageDailyPoint {
  date: string;
  inferenceUsd: number;
  integrationsUsd: number;
  totalUsd: number;
}

export interface TeamUsageModelRow {
  model: string;
  provider: string;
  spentUsd: number;
  calls: number;
}

export interface TeamUsageIntegrationRow {
  provider: string;
  action: string;
  spentUsd: number;
  calls: number;
}

export interface TeamUsageInsights {
  period: { startDate: string; endDate: string };
  totals: {
    inferenceUsd: number;
    integrationsUsd: number;
    totalUsd: number;
    inferenceCalls: number;
    integrationCalls: number;
  };
  dailySeries: TeamUsageDailyPoint[];
  topModels: TeamUsageModelRow[];
  topIntegrations: TeamUsageIntegrationRow[];
}

/**
 * Cycle budget snapshot returned by `GET /teams/me/usage`. Backend PR #790
 * dropped rate-limit fields (5-hour window, daily caps); enforcement is now
 * purely budget-based via `BalanceService.canAfford`.
 */
export interface TeamUsage {
  remainingUsd: number;
  cycleBudgetUsd: number;
  cycleSpentUsd: number;
  cycleStartDate: string;
  cycleEndsAt: string;
  plan: TeamUsagePlanSummary;
  insights: TeamUsageInsights;
}

interface TopUpResult {
  url: string;
  gatewayTransactionId: string;
  amountUsd: number;
  gateway: string;
}

export interface CreditTransaction {
  id: string;
  type: 'EARN' | 'SPEND';
  action: string;
  amountUsd: number;
  balanceAfterUsd: number;
  createdAt: string;
}

interface PaginatedTransactions {
  transactions: CreditTransaction[];
  total: number;
}

// ── Auto-Recharge types ──────────────────────────────────────────────────────

export interface AutoRechargeSettings {
  enabled: boolean;
  thresholdUsd: number;
  rechargeAmountUsd: number;
  weeklyLimitUsd: number;
  spentThisWeekUsd: number;
  weekStartDate: string;
  inFlight: boolean;
  hasSavedPaymentMethod: boolean;
  lastTriggeredAt: string | null;
  lastRechargeAt: string | null;
  lastPaymentIntentId: string | null;
  lastError: string | null;
}

interface AutoRechargeUpdatePayload {
  enabled?: boolean;
  thresholdUsd?: number;
  rechargeAmountUsd?: number;
  weeklyLimitUsd?: number;
}

export interface BillingAddress {
  line1?: string;
  city?: string;
  state?: string;
  postalCode?: string;
  country?: string;
}

export interface CardBillingDetails {
  name?: string;
  email?: string;
  address?: BillingAddress;
}

export interface SavedCard {
  id: string;
  brand: string;
  expMonth: number;
  expYear: number;
  isDefault: boolean;
  last4: string;
  billingDetails: CardBillingDetails;
}

interface CardsData {
  customerId: string;
  defaultPaymentMethodId: string;
  cards: SavedCard[];
}

interface SetupIntentData {
  clientSecret: string;
  customerId: string;
  setupIntentId: string;
}

interface UpdateCardPayload {
  isDefault?: boolean;
  billingDetails?: CardBillingDetails;
}

// ── Coupon types ────────────────────────────────────────────────────────────

interface CouponRedeemResult {
  couponCode: string;
  amountUsd: number;
  pending: boolean;
}

export interface RedeemedCoupon {
  code: string;
  amountUsd: number;
  redeemedAt: string | null;
  activationType: string;
  fulfilled: boolean;
  fulfilledAt: string | null;
  activationCondition: string | null;
}

function asRecord(value: unknown): Record<string, unknown> | null {
  return value && typeof value === 'object' && !Array.isArray(value)
    ? (value as Record<string, unknown>)
    : null;
}

function normalizeUsd(value: unknown, fallback = 0): number {
  if (typeof value === 'number' && Number.isFinite(value)) return value;
  if (typeof value === 'string' && value.trim() !== '') {
    const parsed = Number(value);
    if (Number.isFinite(parsed)) return parsed;
  }
  return fallback;
}

function asStringOrNull(value: unknown): string | null {
  return typeof value === 'string' && value.trim() !== '' ? value : null;
}

export function normalizeCouponRedeemResult(raw: unknown): CouponRedeemResult {
  const record = asRecord(raw) ?? {};
  const envelopeData = asRecord(record.data);
  const payload = envelopeData ?? record;
  return {
    couponCode:
      (typeof payload.couponCode === 'string' && payload.couponCode.trim()) ||
      (typeof payload.code === 'string' && payload.code.trim()) ||
      '',
    amountUsd: normalizeUsd(payload.amountUsd ?? payload.amount_usd),
    pending: Boolean(payload.pending),
  };
}

export function normalizeRedeemedCoupon(raw: unknown): RedeemedCoupon {
  const record = asRecord(raw) ?? {};
  return {
    code:
      (typeof record.code === 'string' && record.code.trim()) ||
      (typeof record.couponCode === 'string' && record.couponCode.trim()) ||
      '',
    amountUsd: normalizeUsd(record.amountUsd ?? record.amount_usd),
    redeemedAt: asStringOrNull(record.redeemedAt ?? record.redeemed_at),
    activationType:
      (typeof record.activationType === 'string' && record.activationType.trim()) ||
      (typeof record.activation_type === 'string' && record.activation_type.trim()) ||
      'IMMEDIATE',
    fulfilled: Boolean(record.fulfilled),
    fulfilledAt: asStringOrNull(record.fulfilledAt ?? record.fulfilled_at),
    activationCondition: asStringOrNull(record.activationCondition ?? record.activation_condition),
  };
}

function normalizeCreditBalance(payload: unknown): CreditBalance {
  const raw = (payload && typeof payload === 'object' ? payload : {}) as Record<string, unknown>;
  const nested = asRecord(raw.data) ?? asRecord(raw.balance) ?? null;
  const source = nested ?? raw;
  const promotionBalanceKeys = [
    'promotionBalanceUsd',
    'promotion_balance_usd',
    'promotionalBalanceUsd',
    'promotional_balance_usd',
    'promoBalanceUsd',
    'promo_balance_usd',
  ] as const;
  const teamTopupKeys = [
    'teamTopupUsd',
    'team_topup_usd',
    'teamTopUpUsd',
    'team_top_up_usd',
    'teamTopupBalanceUsd',
    'team_topup_balance_usd',
  ] as const;
  const missingPromotionBalance = promotionBalanceKeys.every(key => !(key in source));
  const missingTeamTopup = teamTopupKeys.every(key => !(key in source));

  if (missingPromotionBalance || missingTeamTopup) {
    console.debug('[creditsApi] normalizeCreditBalance missing expected keys', {
      raw: source,
      missingPromotionBalance,
      missingPromotionBalanceKeys: missingPromotionBalance ? promotionBalanceKeys : [],
      missingTeamTopup,
      missingTeamTopupKeys: missingTeamTopup ? teamTopupKeys : [],
    });
  }

  return {
    promotionBalanceUsd: normalizeUsd(
      source.promotionBalanceUsd ??
        source.promotion_balance_usd ??
        source.promotionalBalanceUsd ??
        source.promotional_balance_usd ??
        source.promoBalanceUsd ??
        source.promo_balance_usd
    ),
    teamTopupUsd: normalizeUsd(
      source.teamTopupUsd ??
        source.team_topup_usd ??
        source.teamTopUpUsd ??
        source.team_top_up_usd ??
        source.teamTopupBalanceUsd ??
        source.team_topup_balance_usd
    ),
  };
}

function normalizePlanSummary(raw: unknown): TeamUsagePlanSummary {
  const r = asRecord(raw) ?? {};
  return {
    plan: typeof r.plan === 'string' ? r.plan : 'FREE',
    name: typeof r.name === 'string' ? r.name : '',
    marginPercent: normalizeUsd(r.marginPercent),
    payAsYouGoMarginPercent: normalizeUsd(r.payAsYouGoMarginPercent),
    discountVsPayAsYouGoPercent: normalizeUsd(r.discountVsPayAsYouGoPercent),
  };
}

function normalizeDailyPoint(raw: unknown): TeamUsageDailyPoint {
  const r = asRecord(raw) ?? {};
  return {
    date: typeof r.date === 'string' ? r.date : '',
    inferenceUsd: normalizeUsd(r.inferenceUsd),
    integrationsUsd: normalizeUsd(r.integrationsUsd),
    totalUsd: normalizeUsd(r.totalUsd),
  };
}

function normalizeModelRow(raw: unknown): TeamUsageModelRow {
  const r = asRecord(raw) ?? {};
  return {
    model: typeof r.model === 'string' ? r.model : '',
    provider: typeof r.provider === 'string' ? r.provider : '',
    spentUsd: normalizeUsd(r.spentUsd),
    calls: Math.round(Number(r.calls) || 0),
  };
}

function normalizeIntegrationRow(raw: unknown): TeamUsageIntegrationRow {
  const r = asRecord(raw) ?? {};
  return {
    provider: typeof r.provider === 'string' ? r.provider : '',
    action: typeof r.action === 'string' ? r.action : '',
    spentUsd: normalizeUsd(r.spentUsd),
    calls: Math.round(Number(r.calls) || 0),
  };
}

function normalizeInsights(
  raw: unknown,
  fallbackStart: string,
  fallbackEnd: string
): TeamUsageInsights {
  const r = asRecord(raw) ?? {};
  const period = asRecord(r.period) ?? {};
  const totals = asRecord(r.totals) ?? {};
  const dailySeries = Array.isArray(r.dailySeries) ? r.dailySeries.map(normalizeDailyPoint) : [];
  const topModels = Array.isArray(r.topModels) ? r.topModels.map(normalizeModelRow) : [];
  const topIntegrations = Array.isArray(r.topIntegrations)
    ? r.topIntegrations.map(normalizeIntegrationRow)
    : [];
  return {
    period: {
      startDate: typeof period.startDate === 'string' ? period.startDate : fallbackStart,
      endDate: typeof period.endDate === 'string' ? period.endDate : fallbackEnd,
    },
    totals: {
      inferenceUsd: normalizeUsd(totals.inferenceUsd),
      integrationsUsd: normalizeUsd(totals.integrationsUsd),
      totalUsd: normalizeUsd(totals.totalUsd),
      inferenceCalls: Math.round(Number(totals.inferenceCalls) || 0),
      integrationCalls: Math.round(Number(totals.integrationCalls) || 0),
    },
    dailySeries,
    topModels,
    topIntegrations,
  };
}

export function normalizeTeamUsage(payload: unknown): TeamUsage {
  const raw = (
    payload && typeof payload === 'object' && !Array.isArray(payload) ? payload : {}
  ) as Record<string, unknown>;
  const cycleStartDate =
    typeof raw.cycleStartDate === 'string' ? raw.cycleStartDate : new Date().toISOString();
  const cycleEndsAt =
    typeof raw.cycleEndsAt === 'string' ? raw.cycleEndsAt : new Date().toISOString();
  return {
    remainingUsd: normalizeUsd(raw.remainingUsd),
    cycleBudgetUsd: normalizeUsd(raw.cycleBudgetUsd),
    cycleSpentUsd: normalizeUsd(raw.cycleSpentUsd),
    cycleStartDate,
    cycleEndsAt,
    plan: normalizePlanSummary(raw.plan),
    insights: normalizeInsights(raw.insights, cycleStartDate, cycleEndsAt),
  };
}

/**
 * Credits API endpoints
 */
export const creditsApi = {
  /**
   * Get the current user's credit balance (general + top-up)
   * GET /credits/balance
   */
  getBalance: async (): Promise<CreditBalance> => {
    const result = await callCoreCommand<CreditBalance>('openhuman.billing_get_balance');
    return normalizeCreditBalance(result);
  },

  /**
   * Get team inference budget usage for the current billing cycle
   * GET /teams/me/usage
   */
  getTeamUsage: async (): Promise<TeamUsage> => {
    const result = await callCoreCommand<TeamUsage>('openhuman.team_get_usage');
    return normalizeTeamUsage(result);
  },

  /**
   * Start a top-up (get Stripe or Coinbase payment URL)
   * POST /credits/top-up
   */
  topUp: async (
    amountUsd: number,
    gateway: 'stripe' | 'coinbase' = 'stripe'
  ): Promise<TopUpResult> => {
    return await callCoreCommand<TopUpResult>('openhuman.billing_top_up', { amountUsd, gateway });
  },

  /**
   * Get paginated credit transaction history
   * GET /credits/transactions
   */
  getTransactions: async (limit = 20, offset = 0): Promise<PaginatedTransactions> => {
    return await callCoreCommand<PaginatedTransactions>('openhuman.billing_get_transactions', {
      limit,
      offset,
    });
  },

  // ── Auto-Recharge ──────────────────────────────────────────────────────────

  /**
   * Get auto-recharge settings
   * GET /payments/credits/auto-recharge
   */
  getAutoRecharge: async (): Promise<AutoRechargeSettings> => {
    return await callCoreCommand<AutoRechargeSettings>('openhuman.billing_get_auto_recharge');
  },

  /**
   * Update auto-recharge settings. Enabling requires a saved card.
   * PATCH /payments/credits/auto-recharge
   */
  updateAutoRecharge: async (payload: AutoRechargeUpdatePayload): Promise<AutoRechargeSettings> => {
    return await callCoreCommand<AutoRechargeSettings>('openhuman.billing_update_auto_recharge', {
      payload,
    });
  },

  /**
   * List saved cards for auto-recharge
   * GET /payments/credits/auto-recharge/cards
   */
  getCards: async (): Promise<CardsData> => {
    return await callCoreCommand<CardsData>('openhuman.billing_get_cards');
  },

  /**
   * Create a Stripe SetupIntent for adding a new card.
   * The returned clientSecret must be confirmed with Stripe.js.
   * POST /payments/credits/auto-recharge/cards/setup-intent
   */
  createSetupIntent: async (): Promise<SetupIntentData> => {
    return await callCoreCommand<SetupIntentData>('openhuman.billing_create_setup_intent');
  },

  /**
   * Update a saved card (set as default or update billing details)
   * PATCH /payments/credits/auto-recharge/cards/:paymentMethodId
   */
  updateCard: async (paymentMethodId: string, payload: UpdateCardPayload): Promise<CardsData> => {
    return await callCoreCommand<CardsData>('openhuman.billing_update_card', {
      paymentMethodId,
      payload,
    });
  },

  /**
   * Remove a saved card. If it was the default, another card becomes default.
   * DELETE /payments/credits/auto-recharge/cards/:paymentMethodId
   */
  deleteCard: async (paymentMethodId: string): Promise<CardsData> => {
    return await callCoreCommand<CardsData>('openhuman.billing_delete_card', { paymentMethodId });
  },

  // ── Coupons ──────────────────────────────────────────────────────────────

  /**
   * Redeem a coupon code to add credits.
   * POST /coupons/redeem
   */
  redeemCoupon: async (code: string): Promise<CouponRedeemResult> => {
    const result = await callCoreCommand<unknown>('openhuman.billing_redeem_coupon', { code });
    return normalizeCouponRedeemResult(result);
  },

  /**
   * List coupons redeemed by the current user.
   * GET /coupons/me
   */
  getUserCoupons: async (): Promise<RedeemedCoupon[]> => {
    const coupons = await callCoreCommand<unknown[]>('openhuman.billing_get_coupons');
    return Array.isArray(coupons) ? coupons.map(normalizeRedeemedCoupon) : [];
  },
};