CeloHTProvider.ts

import type {
  PaymentIntentRequest,
  PaymentIntentResult,
  PaymentProvider,
  PaymentVerificationOutcome,
} from "./types";

/**
 * CeloHT — Web3 payment provider.
 *
 * CeloHT is a dapp that lets people send and receive CELO and USDm on the
 * Celo blockchain. This class is Matchids' integration point for treating
 * CeloHT as a payment method, for both book purchases and Give Back
 * donations.
 *
 * Nothing here is invented: no contract address, ABI, RPC endpoint, or
 * CeloHT API route. Those get filled in only once CeloHT provides them —
 * see "What's needed to activate this" below. Until then, isConfigured()
 * returns false, createIntent() throws a clear error, and Matchids'
 * checkout UI shows CeloHT as unavailable rather than pretending it works.
 */
export class CeloHTProvider implements PaymentProvider {
  readonly id = "celoht" as const;

  isConfigured(): boolean {
    return Boolean(process.env.CELOHT_API_BASE_URL && process.env.CELOHT_API_KEY);
  }

  async createIntent(_request: PaymentIntentRequest): Promise<PaymentIntentResult> {
    if (!this.isConfigured()) {
      throw new Error(
        "CeloHT is not configured. Set CELOHT_API_BASE_URL and CELOHT_API_KEY — see .env.example."
      );
    }
    // Integration point: call CeloHT's real API to create a payment
    // request for CELO or USDm, returning whatever the checkout UI needs
    // (address + amount, a signed request link, a QR payload, etc.).
    throw new Error(
      "CeloHTProvider.createIntent is an integration point — implement the real CeloHT API call here."
    );
  }

  async verifyTransaction(_providerReference: string): Promise<PaymentVerificationOutcome> {
    if (!this.isConfigured()) {
      return { verified: false, reason: "CeloHT provider is not configured." };
    }
    // Integration point: verify the transaction against the Celo
    // blockchain, or against CeloHT's own verification endpoint. Must run
    // server-side — this is the only source of truth Matchids trusts.
    return { verified: false, reason: "CeloHTProvider.verifyTransaction is not yet implemented." };
  }
}