@withpotter/lib 0.13.0-next.101

package/dist/admin-api.d.ts

@@ -0,0 +1,1219 @@
+import { type DashboardStats, type FinanceAnalytics, type Transaction } from './api';
+export type { AccountRow, AccountsPage, AccountTenantRow, AccountSession, AccountStage, AccountKycStatus, TenantTeamMember, AccountsAnalytics, } from './admin-account-types';
+import type { AccountSession, AccountStage, AccountsPage, AccountTenantRow, TenantTeamMember, AccountsAnalytics } from './admin-account-types';
+import type { TenantSetup } from './admin-tenant-setup-types';
+import type { CountryFields } from './admin-country-api';
+import { type TenantListParams } from './admin-tenants-query';
+import type { AccountOfficer } from './admin-account-officer-api';
+import type { CurrencyAmount, CurrencyGmvKpi, CurrencyOverdue, CurrencyPerformance, CurrencyRevenueGmv, CurrencyRevenueQuality, CurrencySeries, CurrencySettlementSummary, CurrencyTopTenants, CurrencyTotals, FinanceByCurrency, TenantCurrencyMetrics } from './admin-currency-types';
+export type * from './admin-currency-types';
+export type { DashboardStats, FinanceAnalytics, Transaction } from './api';
+/** A merchant's finance dashboard as the admin API sends it: per currency too. */
+export type AdminFinanceAnalytics = FinanceAnalytics & FinanceByCurrency;
+export interface TenantTransactionsPage {
+    transactions: Transaction[];
+    pagination: {
+        total: number;
+        page: number;
+        limit: number;
+        totalPages: number;
+    };
+}
+export interface PlatformOverview {
+    tenants: {
+        total: number;
+        active: number;
+        new30d: number;
+        new7d: number;
+    };
+    accounts: {
+        total: number;
+        new30d: number;
+    };
+    orders: {
+        total: number;
+        gmv: number;
+        gmv30d: number;
+    };
+    subscriptions: {
+        active: number;
+        trialing: number;
+    };
+    growth: {
+        tenantSeries: Array<{
+            date: string;
+            count: number;
+        }>;
+    };
+}
+export interface TenantsAnalytics {
+    range: {
+        startDate: string;
+        endDate: string;
+    };
+    totals: {
+        tenants: number;
+        accounts: number;
+        avgTenantsPerAccount: number;
+        activeRate: number;
+        gmv: number;
+        orders: number;
+        aov: number;
+        gmvInRange: number;
+        ordersInRange: number;
+        newTenantsInRange: number;
+    };
+    statusBreakdown: Array<{
+        status: string;
+        count: number;
+    }>;
+    industryBreakdown: Array<{
+        industry: string;
+        count: number;
+    }>;
+    onboardingSeries: Array<{
+        date: string;
+        count: number;
+    }>;
+    performanceSeries: Array<{
+        date: string;
+        gmv: number;
+        orders: number;
+    }>;
+    /** Absent until the matching api deploy lands — guard with `?? []`. */
+    previousOnboardingSeries?: Array<{
+        date: string;
+        count: number;
+    }>;
+    previousPerformanceSeries?: Array<{
+        date: string;
+        gmv: number;
+        orders: number;
+    }>;
+    topTenants: Array<{
+        id: string;
+        businessName: string;
+        slug: string;
+        gmv: number;
+        orders: number;
+    }>;
+    /** @deprecated adds currencies together, not converted. */
+    baseCurrency: string;
+    /** @deprecated never convert with these. */
+    rates: Record<string, number>;
+    currencies?: string[];
+    totalsByCurrency?: CurrencyTotals[];
+    performanceSeriesByCurrency?: CurrencySeries[];
+    topTenantsByCurrency?: CurrencyTopTenants[];
+}
+export interface CockpitKpi {
+    current: number;
+    previous: number;
+    pct: number | null;
+}
+interface AttentionTenantRef {
+    id: string;
+    businessName: string;
+    slug: string;
+}
+export interface PlatformCockpit {
+    range: {
+        startDate: string;
+        endDate: string;
+    };
+    baseCurrency: string;
+    rates: Record<string, number>;
+    /** Currencies with money in this payload, A→Z. */
+    currencies?: string[];
+    topTenantsByCurrency?: CurrencyTopTenants[];
+    kpis: {
+        newTenants: CockpitKpi;
+        newAccounts: CockpitKpi;
+        /** @deprecated adds currencies together; use `gmvByCurrency`. */
+        gmv: CockpitKpi;
+        orders: CockpitKpi;
+        gmvByCurrency?: CurrencyGmvKpi[];
+    };
+    totals: {
+        totalTenants: number;
+        activeTenants: number;
+        totalAccounts: number;
+        activeSubscriptions: number;
+        trialingSubscriptions: number;
+        /** @deprecated adds currencies together; use `lifetimeGmvByCurrency`. */
+        lifetimeGmv: number;
+        lifetimeGmvByCurrency?: CurrencyAmount[];
+        /**
+         * Platform fees collected on card payments, one row per currency. Absent
+         * until the api serves it; the Overview shows no card without it.
+         */
+        gatewayFeesByCurrency?: CurrencyAmount[];
+        /**
+         * Wallets whose business passed KYC / KYB. Absent until the api serves
+         * it; the Overview shows no card without it.
+         */
+        verifiedWallets?: number;
+    };
+    sparklines: {
+        tenants: number[];
+        accounts: number[];
+        gmv: number[];
+        orders: number[];
+    };
+    statusBreakdown: Array<{
+        status: string;
+        count: number;
+    }>;
+    industryBreakdown: Array<{
+        industry: string;
+        count: number;
+    }>;
+    topTenants: Array<{
+        id: string;
+        businessName: string;
+        slug: string;
+        gmv: number;
+        orders: number;
+    }>;
+    health?: {
+        mrr: number;
+        newMrr: number;
+        churnedMrr: number;
+        netNewMrr: number;
+        grossMrrChurnPct: number;
+        grossRevenueRetentionPct: number;
+        newLogos: number;
+        churnedLogos: number;
+        netNewLogos: number;
+        logoChurnPct: number;
+        activePayingLogos: number;
+        gmvConcentrationTop10Pct: number;
+    };
+    performance?: {
+        takeRatePct: number | null;
+        annualizedGmvRunRate: number;
+        gmvPerActiveTenant: number;
+        revenuePerActiveTenant: number;
+        transactingTenants: number;
+        transactingTenantRatePct: number;
+        gmvGrowthPct: number | null;
+        ordersGrowthPct: number | null;
+        netNewLogos: number;
+        byCurrency?: CurrencyPerformance[];
+    };
+    verticals?: Array<{
+        industry: string;
+        tenants: number;
+        gmv: number;
+        orders: number;
+        aov: number;
+        gmvGrowthPct: number | null;
+        share: number;
+    }>;
+    /** GMV/orders across every service Box offers (sell-products, event-tickets, …). */
+    salesByService?: Array<{
+        service: string;
+        merchants: number;
+        gmv: number;
+        orders: number;
+        aov: number;
+        gmvGrowthPct: number | null;
+        share: number;
+    }>;
+    activation?: {
+        funnel: Array<{
+            stage: string;
+            count: number;
+        }>;
+        medianDaysToFirstOrder: number | null;
+        activationRatePct: number;
+        orderConversionPct: number;
+    };
+    accounts?: {
+        total: number;
+        active: number;
+        suspended: number;
+        verified: number;
+        unverifiedEmail: number;
+        neverLoggedIn: number;
+        dormant: number;
+        new: number;
+    };
+    trend: {
+        performanceSeries: Array<{
+            date: string;
+            gmv: number;
+            orders: number;
+        }>;
+        onboardingSeries: Array<{
+            date: string;
+            count: number;
+        }>;
+        /** Absent until the matching api deploy lands — guard with `?? []`. */
+        previousPerformanceSeries?: Array<{
+            date: string;
+            gmv: number;
+            orders: number;
+        }>;
+        previousOnboardingSeries?: Array<{
+            date: string;
+            count: number;
+        }>;
+        performanceSeriesByCurrency?: CurrencySeries[];
+    };
+    attention: {
+        /**
+         * Feeds whose query failed; their counts are placeholders, not zeros.
+         * Absent when talking to an API that predates this field.
+         */
+        unavailable?: Array<'needsReview' | 'dormantTenants' | 'overdueInvoices' | 'failedSettlements'>;
+        trialsEndingSoon: Array<AttentionTenantRef & {
+            trialEndsAt: string;
+            daysLeft: number;
+        }>;
+        needsReview: Array<AttentionTenantRef & {
+            status: string;
+            createdAt: string;
+        }>;
+        dormantTenants: Array<AttentionTenantRef & {
+            createdAt: string;
+        }>;
+        overdueInvoices: {
+            count: number;
+            /** @deprecated adds currencies together; use `totalByCurrency`. */
+            total: number;
+            totalByCurrency?: CurrencyOverdue[];
+            sample: Array<{
+                id: string;
+                invoiceNumber: string;
+                tenantId: string;
+                tenantName: string;
+                customerName: string | null;
+                amountDue: number;
+                currency: string;
+                dueDate: string | null;
+            }>;
+        };
+        failedSettlements: {
+            count: number;
+            sample: Array<{
+                id: string;
+                tenantId: string;
+                tenantName: string;
+                netAmount: number;
+                currency: string;
+                createdAt: string;
+            }>;
+        };
+    };
+}
+/**
+ * What one payment channel (Card, USSD, Bank transfer, Opay...) brought in, in one
+ * currency. `amountMinor` is in minor units. Sent only by a box that records how
+ * customers paid; others answer 404, and the panels that use it stay hidden.
+ */
+export interface GatewayChannelTotal {
+    channel: {
+        key: string;
+        label: string;
+    };
+    currency: string;
+    count: number;
+    amountMinor: string;
+}
+/**
+ * Revenue's Merchant payments and Subscriptions views. Amounts are whole minor
+ * units in strings (kobo), per currency, never added across currencies.
+ * Boxes older than this answer 404 and the views stay hidden.
+ */
+export interface LedgerFilters {
+    startDate?: string;
+    endDate?: string;
+    /** Shown as a word in the table; the API takes a card, ussd, transfer, opay… key. */
+    method?: string;
+    type?: string;
+    status?: string;
+    /** Matches a reference, a payer's name, email or phone, or a merchant's name. */
+    q?: string;
+    page?: number;
+    limit?: number;
+}
+export interface MerchantPaymentRow {
+    id: string;
+    reference: string;
+    paidAt: string;
+    payer: {
+        name: string | null;
+        email: string | null;
+        phone: string | null;
+    };
+    merchant: {
+        id: string;
+        name: string | null;
+    };
+    channel: {
+        key: string;
+        label: string;
+    };
+    /** The card (brand and last four) or the bank, when known. */
+    methodDetail: string | null;
+    type: string;
+    status: string;
+    currency: string;
+    amountMinor: string;
+    feeMinor: string;
+    netMinor: string;
+    orderId: string | null;
+}
+export interface LedgerCard {
+    currency: string;
+    grossMinor: string;
+    feeMinor: string;
+    netMinor: string;
+    refundsMinor: string;
+    payments: number;
+    /** Percent of attempts that went through; null when nothing was attempted. */
+    successRate: number | null;
+}
+export interface MerchantPaymentsPage {
+    rows: MerchantPaymentRow[];
+    page: number;
+    limit: number;
+    total: number;
+    /** Totals of exactly the rows the filters match. */
+    strip: Array<{
+        currency: string;
+        payments: number;
+        amountMinor: string;
+        feeMinor: string;
+        netMinor: string;
+    }>;
+    cards: {
+        current: LedgerCard[];
+        previous: LedgerCard[] | null;
+    };
+    byChannel: {
+        current: GatewayChannelTotal[];
+        previous: GatewayChannelTotal[] | null;
+    };
+}
+export interface SubscriptionPaymentRow {
+    id: string;
+    reference: string;
+    merchantName: string | null;
+    merchantEmail: string | null;
+    tenantId: string;
+    plan: string;
+    /** select_plan, upgrade, renewal, reactivation or mandate_setup. */
+    purpose: string;
+    amountKobo: number;
+    /** gateway, wallet or manual. */
+    method: string;
+    /** pending, succeeded or failed. */
+    status: string;
+    paidAt: string | null;
+    createdAt: string;
+    failureReason: string | null;
+}
+export interface SubscriptionPaymentsPage {
+    items: SubscriptionPaymentRow[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+export interface PlatformRevenue {
+    range: {
+        startDate: string;
+        endDate: string;
+    };
+    currency: string;
+    /**
+     * What Olive keeps from payouts, settlements and subscription charges: net
+     * credits on the ledger's platform fees account, in major units, one row per
+     * currency, A to Z. Empty when nothing was earned. Not card fees only, no
+     * refund netting, and test merchants are included. Absent until the api
+     * serves it, so the UI hides the figure rather than showing a zero.
+     */
+    platformFeesEarnedByCurrency?: CurrencyAmount[];
+    recurring: {
+        /** False when no billing source feeds the figures below (all are 0). */
+        tracked?: boolean;
+        /** The currency of the figures below, when the box names it. */
+        currency?: string;
+        /** Merchants on a paid plan right now (absent on older APIs). */
+        payingMerchants?: number;
+        mrr: number;
+        arr: number;
+        arpa: number;
+        activeSubscriptions: number;
+        trialingSubscriptions: number;
+        pastDueSubscriptions: number;
+        nonRenewingSubscriptions: number;
+        cancelledSubscriptions: number;
+        newInRange: number;
+        churnedInRange: number;
+        planBreakdown: Array<{
+            planId: string;
+            name: string;
+            interval: string;
+            subscribers: number;
+            mrr: number;
+        }>;
+    };
+    gmv: {
+        lifetime: number;
+        inRange: number;
+        ordersInRange: number;
+        aov: number;
+        series: Array<{
+            date: string;
+            gmv: number;
+            orders: number;
+        }>;
+        topTenants: Array<{
+            id: string;
+            businessName: string;
+            slug: string;
+            gmv: number;
+            orders: number;
+        }>;
+    };
+    quality?: {
+        quickRatio: number | null;
+        nrrPct: number | null;
+        expansionMrr: number;
+        contractionMrr: number;
+        mrrChurnRatePct: number | null;
+        logoChurnRatePct: number | null;
+        grossGmv: number;
+        refundedGmv: number;
+        netGmv: number;
+        refundRatePct: number;
+        refundedOrders: number;
+        cohorts: Array<{
+            cohort: string;
+            size: number;
+            retention: Array<number | null>;
+        }>;
+        gmvByCurrency?: CurrencyRevenueQuality[];
+    };
+    /** @deprecated never convert with these. */
+    rates: Record<string, number>;
+    currencies?: string[];
+    gmvByCurrency?: CurrencyRevenueGmv[];
+}
+export type TenantStatus = 'active' | 'suspended' | 'pending' | 'deleted';
+export interface TenantRow extends CountryFields {
+    id: string;
+    slug: string;
+    businessName: string;
+    status: TenantStatus;
+    industryKey: string | null;
+    createdAt: string;
+    /** The business's contact email (absent on older APIs). */
+    email?: string | null;
+    phone?: string | null;
+    /** The owner's sign-in email. */
+    ownerEmail?: string | null;
+    /** @deprecated adds currencies together; use `gmvByCurrency`. */
+    gmv: number;
+    gmvByCurrency?: CurrencyAmount[];
+    /** The merchant's account officer (absent on older APIs). */
+    accountOfficer?: Pick<AccountOfficer, 'id' | 'name'> | null;
+}
+export interface TenantsPage {
+    rows: TenantRow[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+export interface TenantActivityOrder {
+    id: string;
+    orderNumber: string;
+    total: number;
+    currency: string;
+    status: string;
+    paymentStatus: string;
+    customerEmail: string;
+    customerName: string | null;
+    customerPhone?: string | null;
+    /** How the customer paid (Card, USSD, Bank transfer, Opay); absent on older APIs. */
+    paymentMethod?: string | null;
+    createdAt: string;
+}
+export interface TenantDetail extends TenantSetup {
+    /** Who runs the workspace and how to reach it (absent on older APIs). */
+    contact?: {
+        email: string | null;
+        phone: string | null;
+    };
+    owner?: TenantTeamMember | null;
+    team?: TenantTeamMember[];
+    /** The admin in charge of this merchant (absent on older APIs). */
+    accountOfficer?: AccountOfficer | null;
+    id: string;
+    slug: string;
+    businessName: string;
+    status: TenantStatus;
+    industryKey: string | null;
+    customDomain: string | null;
+    createdAt: string;
+    chargeBearer: 'merchant' | 'customer';
+    currency: string;
+    metrics: {
+        totalOrders: number;
+        paidOrders: number;
+        pendingOrders: number;
+        gmv: number;
+        gmv30d: number;
+        gmv7d: number;
+        aov: number;
+        totalCustomers: number;
+        subscriptionStatus: string | null;
+        window: {
+            startDate: string;
+            endDate: string;
+            gmv: number;
+            orders: number;
+            paidOrders: number;
+            aov: number;
+            customers: number;
+        };
+        byCurrency?: TenantCurrencyMetrics[];
+    };
+    /** Currencies with paid orders, A→Z. */
+    currencies?: string[];
+    revenueSeries: Array<{
+        date: string;
+        amount: number;
+    }>;
+    revenueSeriesByCurrency?: Array<{
+        currency: string;
+        series: Array<{
+            date: string;
+            amount: number;
+        }>;
+    }>;
+    recentOrders: TenantActivityOrder[];
+}
+export interface TenantCustomer {
+    id: string;
+    email: string;
+    phone: string | null;
+    name: string | null;
+    type: string;
+    source: string | null;
+    status: string;
+    emailVerified: boolean;
+    totalOrders: number;
+    totalSpent: number;
+    lastOrderAt: string | null;
+    createdAt: string;
+}
+export interface TenantCustomersPage {
+    members: TenantCustomer[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+export interface TenantProduct {
+    id: string;
+    type: string;
+    slug: string;
+    title: string;
+    category: string | null;
+    tags: string[];
+    featured: boolean;
+    isActive: boolean;
+    image?: {
+        url: string;
+    } | null;
+    price: number | null;
+    compareAtPrice: number | null;
+    currency: string | null;
+    trackInventory: boolean;
+    quantity: number | null;
+    reserved: number | null;
+    lowStockThreshold: number | null;
+    createdAt: string;
+}
+export interface TenantProductStats {
+    total: number;
+    active: number;
+    featured: number;
+    lowStock: number;
+    outOfStock: number;
+}
+export interface TenantProductsData {
+    items: TenantProduct[];
+    total: number;
+    stats: TenantProductStats;
+}
+export interface ProductRef {
+    id: string;
+    title: string;
+}
+export interface SellerRow {
+    id: string;
+    title: string;
+    units: number;
+    revenue: number;
+}
+export interface CategorySlice {
+    category: string;
+    count: number;
+    value: number;
+}
+export interface ProductInsights {
+    currency: string;
+    totalProducts: number;
+    activeProducts: number;
+    featuredProducts: number;
+    lowStock: number;
+    outOfStock: number;
+    trackedProducts: number;
+    catalogValue: number;
+    inventoryValue: number;
+    inventoryAtRiskValue: number;
+    avgPrice: number;
+    medianPrice: number;
+    totalUnitsSold: number;
+    totalRevenue: number;
+    pctEverSold: number;
+    deadStock: number;
+    newestProduct: (ProductRef & {
+        createdAt: string;
+    }) | null;
+    lastUpdatedProduct: (ProductRef & {
+        updatedAt: string;
+    }) | null;
+    categories: CategorySlice[];
+    bestSellers: SellerRow[];
+    worstSellers: SellerRow[];
+    featuredSellThrough: {
+        featuredTotal: number;
+        featuredSold: number;
+        featuredUnits: number;
+        nonFeaturedTotal: number;
+        nonFeaturedSold: number;
+        nonFeaturedUnits: number;
+    };
+    unitsSeries: Array<{
+        date: string;
+        count: number;
+    }>;
+}
+export interface SpenderRow {
+    id: string;
+    name: string | null;
+    email: string;
+    totalSpent: number;
+    totalOrders: number;
+}
+export interface BreakdownSlice {
+    label: string;
+    count: number;
+}
+export interface CustomerInsights {
+    currency: string;
+    totalCustomers: number;
+    newCustomers30d: number;
+    payingCustomers: number;
+    repeatCustomers: number;
+    repeatRate: number;
+    dormantCustomers: number;
+    marketingOptInRate: number;
+    lifetimeValue: number;
+    avgSpendPerCustomer: number;
+    avgOrdersPerCustomer: number;
+    avgOrderValue: number;
+    topSpenders: SpenderRow[];
+    bySource: BreakdownSlice[];
+    byType: BreakdownSlice[];
+    signupsSeries: Array<{
+        date: string;
+        count: number;
+    }>;
+}
+export interface TenantInvoice {
+    id: string;
+    invoiceNumber: string;
+    status: string;
+    customerEmail: string | null;
+    customerName: string | null;
+    total: number;
+    amountPaid: number;
+    amountDue: number;
+    currency: string;
+    dueDate: string | null;
+    createdAt: string;
+}
+export interface TenantInvoiceStats {
+    draft: number;
+    sent: number;
+    paid: number;
+    overdue: number;
+    cancelled: number;
+    total: number;
+    totalRevenue: number;
+    totalOutstanding: number;
+}
+export interface TenantInvoicesData {
+    invoices: TenantInvoice[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+    stats: TenantInvoiceStats;
+}
+export interface TenantLoyaltyProgram {
+    id: string;
+    name: string;
+    pointsName: string;
+    pointsPerCurrency: number;
+    currencyPerPoint: number;
+    isActive: boolean;
+    tiers?: Array<{
+        id: string;
+        name: string;
+        threshold: number;
+    }>;
+    earnRules?: Array<{
+        id: string;
+        name: string;
+        points: number;
+    }>;
+}
+export interface TenantLoyaltyStats {
+    totalMembers: number;
+    totalPointsIssued: number;
+    totalPointsRedeemed: number;
+    activeMembers: number;
+    programActive: boolean;
+}
+export interface TenantLoyaltyData {
+    program: TenantLoyaltyProgram | null;
+    stats: TenantLoyaltyStats;
+}
+export interface TenantDiscount {
+    id: string;
+    name: string;
+    code: string;
+    discountType: string;
+    value: number;
+    maxDiscountAmount: number | null;
+    startsAt: string | null;
+    endsAt: string | null;
+    usageLimit: number | null;
+    usageCount: number;
+    status: string;
+    autoApply: boolean;
+    isValid: boolean;
+    isExpired: boolean;
+    createdAt: string;
+}
+export interface TenantDiscountsPage {
+    discounts: TenantDiscount[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+}
+export interface TenantSettlement {
+    id: string;
+    grossAmount: number;
+    paystackFee: number;
+    platformFee: number;
+    netAmount: number;
+    currency: string;
+    status: string;
+    settlementType: string;
+    bankAccount?: {
+        bankName: string;
+        accountNumber: string;
+    } | null;
+    settledAt: string | null;
+    createdAt: string;
+}
+export interface TenantSettlementSummary {
+    totalSettled: number;
+    totalPending: number;
+    totalFailed: number;
+    count: number;
+    platformFeesCollected: number;
+    currency: string;
+    currencies?: string[];
+    byCurrency?: CurrencySettlementSummary[];
+}
+export interface TenantBankAccount {
+    id: string;
+    bankCode: string;
+    bankName: string;
+    accountNumber: string;
+    accountName: string;
+    splitPercentage: number | null;
+    status: string;
+    isDefault: boolean;
+    /** Paystack subaccount code (ACCT_…). */
+    subaccountCode?: string | null;
+    failureReason?: string | null;
+    createdAt: string;
+}
+export interface TenantSettlementsData {
+    settlements: TenantSettlement[];
+    total: number;
+    page: number;
+    limit: number;
+    summary: TenantSettlementSummary;
+    bankAccounts: TenantBankAccount[];
+}
+export interface TenantSubscriptionPlan {
+    id: string;
+    name: string;
+    interval: string;
+    amount: number;
+    currency: string;
+}
+export interface TenantSubscription {
+    id: string;
+    planId: string;
+    customerId: string;
+    customerEmail: string;
+    status: string;
+    amount: number;
+    currency: string;
+    currentPeriodStart: string | null;
+    currentPeriodEnd: string | null;
+    nextPaymentDate: string | null;
+    cancelledAt: string | null;
+    paymentsCount: number;
+    createdAt: string;
+    plan?: TenantSubscriptionPlan | null;
+    customer?: {
+        id: string;
+        name: string | null;
+        email: string;
+    } | null;
+}
+export interface TenantSubscriptionStats {
+    totalActive: number;
+    totalNonRenewing: number;
+    totalCancelled: number;
+    monthlyRecurringRevenue: number;
+}
+export interface TenantSubscriptionsData {
+    subscriptions: TenantSubscription[];
+    total: number;
+    page: number;
+    limit: number;
+    stats: TenantSubscriptionStats;
+}
+export interface AdminsAnalytics {
+    range: {
+        startDate: string;
+        endDate: string;
+    };
+    totals: {
+        admins: number;
+        active: number;
+        suspended: number;
+        superadmins: number;
+        standardAdmins: number;
+        neverLoggedIn: number;
+        activeInRange: number;
+        actionsInRange: number;
+    };
+    roleBreakdown: Array<{
+        role: string;
+        count: number;
+    }>;
+    statusBreakdown: Array<{
+        status: string;
+        count: number;
+    }>;
+    activitySeries: Array<{
+        date: string;
+        count: number;
+    }>;
+    topActions: Array<{
+        action: string;
+        count: number;
+    }>;
+    recentActivity: Array<{
+        id: string;
+        adminEmail: string | null;
+        action: string;
+        targetType: string | null;
+        createdAt: string;
+    }>;
+}
+export interface AdminSession {
+    id: string;
+    email: string;
+    name: string | null;
+    role: 'admin' | 'superadmin';
+    permissions: string[];
+    mustChangePassword: boolean;
+}
+export interface AdminLoginCodeRequired {
+    codeRequired: true;
+    challengeId: string;
+    /** The address the code went to, masked: `a***@gmail.com`. */
+    sentTo: string;
+}
+export type AdminLoginAnswer = AdminLoginCodeRequired | {
+    codeRequired?: undefined;
+    mustChangePassword: boolean;
+    admin: Omit<AdminSession, 'permissions'>;
+};
+export declare const platformAdminApi: {
+    /**
+     * Password step. A box that emails sign-in codes answers `codeRequired` and
+     * sets no session yet; finish with `verifyLoginCode`.
+     */
+    login: (email: string, password: string) => Promise<AdminLoginAnswer>;
+    verifyLoginCode: (challengeId: string, code: string) => Promise<{
+        mustChangePassword: boolean;
+        admin: Omit<AdminSession, "permissions">;
+    }>;
+    resendLoginCode: (challengeId: string) => Promise<AdminLoginCodeRequired>;
+    logout: () => Promise<{
+        success: boolean;
+    }>;
+    me: () => Promise<AdminSession>;
+    changePassword: (currentPassword: string, newPassword: string) => Promise<{
+        success: boolean;
+    }>;
+    overview: () => Promise<PlatformOverview>;
+    gatewayChannels: (params?: {
+        startDate?: string;
+        endDate?: string;
+    }) => Promise<{
+        byChannel: GatewayChannelTotal[];
+    }>;
+    merchantPayments: (f?: LedgerFilters) => Promise<MerchantPaymentsPage>;
+    /** The same payments as CSV text. */
+    merchantPaymentsCsv: (f?: LedgerFilters) => Promise<string>;
+    subscriptionPayments: (f?: LedgerFilters) => Promise<SubscriptionPaymentsPage>;
+    subscriptionPaymentsCsv: (f?: LedgerFilters) => Promise<string>;
+    cockpit: (params?: {
+        startDate?: string;
+        endDate?: string;
+    }) => Promise<PlatformCockpit>;
+    revenue: (params?: {
+        startDate?: string;
+        endDate?: string;
+    }) => Promise<PlatformRevenue>;
+    tenantsAnalytics: (params?: {
+        startDate?: string;
+        endDate?: string;
+    }) => Promise<TenantsAnalytics>;
+    tenants: (params?: TenantListParams) => Promise<TenantsPage>;
+    tenant: (id: string, range?: {
+        startDate?: string;
+        endDate?: string;
+    }) => Promise<TenantDetail>;
+    tenantAnalytics: (id: string, range?: {
+        startDate?: string;
+        endDate?: string;
+        limit?: number;
+    }) => Promise<DashboardStats>;
+    tenantFinance: (id: string, range?: {
+        startDate?: string;
+        endDate?: string;
+        period?: string;
+    }) => Promise<AdminFinanceAnalytics>;
+    tenantTransactions: (id: string, params?: {
+        status?: string;
+        type?: string;
+        search?: string;
+        page?: number;
+        limit?: number;
+    }) => Promise<TenantTransactionsPage>;
+    tenantCustomers: (id: string, params?: {
+        search?: string;
+        type?: string;
+        status?: string;
+        page?: number;
+        limit?: number;
+    }) => Promise<TenantCustomersPage>;
+    tenantProducts: (id: string, params?: {
+        type?: string;
+        search?: string;
+    }) => Promise<TenantProductsData>;
+    tenantProductInsights: (id: string, range?: {
+        startDate?: string;
+    }) => Promise<ProductInsights>;
+    tenantCustomerInsights: (id: string, range?: {
+        startDate?: string;
+    }) => Promise<CustomerInsights>;
+    tenantInvoices: (id: string, params?: {
+        status?: string;
+        search?: string;
+        page?: number;
+        limit?: number;
+    }) => Promise<TenantInvoicesData>;
+    tenantLoyalty: (id: string) => Promise<TenantLoyaltyData>;
+    tenantDiscounts: (id: string, params?: {
+        status?: string;
+        discountType?: string;
+        search?: string;
+        page?: number;
+        limit?: number;
+    }) => Promise<TenantDiscountsPage>;
+    tenantSettlements: (id: string, params?: {
+        page?: number;
+        limit?: number;
+        startDate?: string;
+        endDate?: string;
+    }) => Promise<TenantSettlementsData>;
+    tenantSubscriptions: (id: string, params?: {
+        status?: string;
+        planId?: string;
+        page?: number;
+        limit?: number;
+    }) => Promise<TenantSubscriptionsData>;
+    setTenantStatus: (id: string, status: TenantStatus) => Promise<{
+        success: boolean;
+    }>;
+    accounts: (params?: {
+        page?: number;
+        pageSize?: number;
+        search?: string;
+        joinedFrom?: string;
+        joinedTo?: string;
+        stage?: AccountStage;
+    }) => Promise<AccountsPage>;
+    accountsAnalytics: (params?: {
+        startDate?: string;
+        endDate?: string;
+    }) => Promise<AccountsAnalytics>;
+    setAccountStatus: (id: string, status: string) => Promise<{
+        success: boolean;
+    }>;
+    verifyAccount: (id: string) => Promise<{
+        success: boolean;
+    }>;
+    accountSessions: (id: string) => Promise<AccountSession[]>;
+    accountTenants: (id: string) => Promise<AccountTenantRow[]>;
+    impersonateAccount: (id: string) => Promise<{
+        success: boolean;
+    }>;
+    admins: () => Promise<AdminRow[]>;
+    adminsAnalytics: (params?: {
+        startDate?: string;
+        endDate?: string;
+    }) => Promise<AdminsAnalytics>;
+    adminPermissions: () => Promise<string[]>;
+    inviteAdmin: (email: string, role: "admin" | "superadmin", permissions?: string[], roleIds?: string[]) => Promise<{
+        email: string;
+        tempPassword: string;
+    }>;
+    setAdminStatus: (id: string, status: "active" | "suspended") => Promise<{
+        success: boolean;
+    }>;
+    setAdminPermissions: (id: string, permissions: string[]) => Promise<{
+        success: boolean;
+    }>;
+    setAdminRoles: (id: string, roleIds: string[]) => Promise<{
+        success: boolean;
+    }>;
+    resetAdminPassword: (id: string) => Promise<{
+        tempPassword: string;
+    }>;
+    roles: () => Promise<RoleRow[]>;
+    createRole: (name: string, permissions: string[], description?: string) => Promise<RoleRow>;
+    updateRole: (id: string, data: {
+        name?: string;
+        permissions?: string[];
+        description?: string;
+    }) => Promise<{
+        success: boolean;
+    }>;
+    deleteRole: (id: string) => Promise<{
+        success: boolean;
+    }>;
+    audit: (params?: {
+        page?: number;
+        pageSize?: number;
+        search?: string;
+        action?: string;
+        adminEmail?: string;
+        from?: string;
+        to?: string;
+    }) => Promise<AuditPage>;
+    auditAnalytics: (params?: {
+        startDate?: string;
+        endDate?: string;
+    }) => Promise<AuditAnalytics>;
+};
+export interface AdminRow {
+    id: string;
+    email: string;
+    name: string | null;
+    role: 'admin' | 'superadmin';
+    status: 'active' | 'suspended';
+    permissions: string[];
+    roleIds: string[];
+    mustChangePassword: boolean;
+    lastLoginAt: string | null;
+    createdAt: string;
+}
+export interface RoleRow {
+    id: string;
+    key: string;
+    name: string;
+    description: string | null;
+    permissions: string[];
+    isSystem: boolean;
+    assignedCount: number;
+}
+export interface AuditRow {
+    id: string;
+    /** Who did it, by name. Absent from an engine that does not send it, or when the admin has none. */
+    adminName?: string | null;
+    adminEmail: string | null;
+    action: string;
+    targetType: string | null;
+    targetId: string | null;
+    metadata: Record<string, unknown>;
+    ipAddress: string | null;
+    /** The browser or tool the action came from. Absent from an engine that does not send it. */
+    userAgent?: string | null;
+    createdAt: string;
+}
+export interface AuditPage {
+    rows: AuditRow[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+export interface AuditAnalytics {
+    range: {
+        startDate: string;
+        endDate: string;
+    };
+    totals: {
+        actions: number;
+        activeAdmins: number;
+        actionTypes: number;
+        topAction: string | null;
+    };
+    actionSeries: Array<{
+        date: string;
+        count: number;
+    }>;
+    actionBreakdown: Array<{
+        action: string;
+        count: number;
+    }>;
+    adminBreakdown: Array<{
+        adminEmail: string;
+        count: number;
+    }>;
+    targetBreakdown: Array<{
+        targetType: string;
+        count: number;
+    }>;
+}