unsupervised-scheduler/src/Payment/PaymentRepository.php

<?php
declare(strict_types=1);

namespace Unsupervised\Schedular\Payment;

class PaymentRepository {

	private string $table;

	public function __construct( private \wpdb $db ) {
		$this->table = $db->prefix . 'us_payments';
	}

	public function insert( Payment $payment ): int {
		$this->db->insert(
			$this->table,
			[
				'student_id'               => $payment->studentId,
				'payer_id'                 => $payment->payerOrStudent(),
				'instructor_id'            => $payment->instructorId,
				'registration_type'        => $payment->registrationType,
				'registration_id'          => $payment->registrationId,
				'amount'                   => $payment->amount,
				'currency'                 => $payment->currency,
				'method'                   => $payment->method,
				'status'                   => $payment->status,
				'tax_rate'                 => $payment->taxRate,
				'tax_amount'               => $payment->taxAmount,
				'credit_applied'           => $payment->creditApplied,
				'due_date'                 => $payment->dueDate,
				'period_key'               => $payment->periodKey,
				'notice_batch'             => $payment->noticeBatch,
				'etransfer_email'          => $payment->etransferEmail,
				'stripe_payment_intent_id' => $payment->stripePaymentIntentId,
				'receipt_number'           => $payment->receiptNumber,
				'receipt_sent_at'          => $payment->receiptSentAt,
				'notice_sent_at'           => $payment->noticeSentAt,
				'paid_at'                  => $payment->paidAt,
				'created_at'               => current_time( 'mysql' ),
			],
			[ '%d', '%d', '%d', '%s', '%d', '%f', '%s', '%s', '%s', '%f', '%f', '%f', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s' ]
		);

		return $this->db->insert_id;
	}

	/**
	 * Backfill `payer_id` on payments written before guardian accounts existed,
	 * where the student was always the payer. Run once from the installer.
	 */
	public function backfillPayerIds(): void {
		$sql = $this->db->prepare( 'UPDATE %i SET payer_id = student_id WHERE payer_id = 0', $this->table );

		if ( null !== $sql ) {
			$this->db->query( $sql );
		}
	}

	/**
	 * Attach the Stripe PaymentIntent id created for a card payment so the webhook
	 * can later reconcile the charge back to this row.
	 */
	public function setStripeIntentId( int $id, string $intentId ): bool {
		return false !== $this->db->update(
			$this->table,
			[ 'stripe_payment_intent_id' => $intentId ],
			[ 'id' => $id ],
			[ '%s' ],
			[ '%d' ]
		);
	}

	public function findByStripeIntentId( string $intentId ): ?Payment {
		$row = $this->db->get_row(
			$this->db->prepare(
				'SELECT * FROM %i WHERE stripe_payment_intent_id = %s ORDER BY id DESC LIMIT 1',
				$this->table,
				$intentId
			)
		);

		return $row ? Payment::fromRow( $row ) : null;
	}

	public function updateEtransferEmail( int $id, ?string $email ): bool {
		return false !== $this->db->update(
			$this->table,
			[ 'etransfer_email' => $email ],
			[ 'id' => $id ],
			[ '%s' ],
			[ '%d' ]
		);
	}

	/**
	 * Add to the account credit applied against a payment, reducing what the student
	 * still owes on it (`Payment::netDue()`). Accumulates, so a second application
	 * adds to the first.
	 */
	public function addCreditApplied( int $id, float $amount ): bool {
		$sql = $this->db->prepare(
			'UPDATE %i SET credit_applied = credit_applied + %f WHERE id = %d',
			$this->table,
			$amount,
			$id
		);

		return null !== $sql && false !== $this->db->query( $sql );
	}

	/**
	 * Set a payment's tax rate and recompute the tax amount from its subtotal.
	 */
	public function updateTax( int $id, float $rate ): bool {
		$sql = $this->db->prepare(
			'UPDATE %i SET tax_rate = %f, tax_amount = ROUND( amount * %f / 100, 2 ) WHERE id = %d',
			$this->table,
			$rate,
			$rate,
			$id
		);

		return null !== $sql && false !== $this->db->query( $sql );
	}

	/**
	 * Paid payments in a month (`Y-m` bounds), optionally for one instructor —
	 * the reporting source.
	 *
	 * @return list<Payment>
	 */
	public function findPaidBetween( string $from, string $to, int $instructorId = 0 ): array {
		$sql    = 'SELECT * FROM %i WHERE status = %s AND paid_at >= %s AND paid_at < %s';
		$params = [ $this->table, Payment::STATUS_PAID, $from, $to ];

		if ( $instructorId > 0 ) {
			$sql     .= ' AND instructor_id = %d';
			$params[] = $instructorId;
		}

		$sql .= ' ORDER BY paid_at ASC';

		$rows = $this->db->get_results( $this->db->prepare( $sql, $params ) );

		return array_map( Payment::fromRow( ... ), $rows ?? [] );
	}

	public function findById( int $id ): ?Payment {
		$row = $this->db->get_row(
			$this->db->prepare( 'SELECT * FROM %i WHERE id = %d', $this->table, $id )
		);

		return $row ? Payment::fromRow( $row ) : null;
	}

	/**
	 * Tag a set of payments with a shared notice-batch reference — the payments the
	 * daily scan emailed a student together, so the admin can see which pending
	 * payments a single lump-sum e-transfer covers. No-op for an empty id list.
	 *
	 * @param list<int> $ids
	 */
	public function assignNoticeBatch( array $ids, string $batch ): void {
		if ( [] === $ids ) {
			return;
		}

		$placeholders = implode( ', ', array_fill( 0, count( $ids ), '%d' ) );
		$sql          = $this->db->prepare(
			"UPDATE %i SET notice_batch = %s WHERE id IN ( {$placeholders} )",
			$this->table,
			$batch,
			...$ids
		);

		if ( null !== $sql ) {
			$this->db->query( $sql );
		}
	}

	/**
	 * Whether a scheduled payment already exists for a registration and billing
	 * period. The daily billing scan uses this to avoid double-billing an
	 * enrolment for the same session (weekly) or month (monthly). A voided
	 * (`failed`) row still counts so a cancelled charge is not silently re-created.
	 */
	public function existsForPeriod( string $registrationType, int $registrationId, string $periodKey ): bool {
		$found = $this->db->get_var(
			$this->db->prepare(
				'SELECT id FROM %i WHERE registration_type = %s AND registration_id = %d AND period_key = %s LIMIT 1',
				$this->table,
				$registrationType,
				$registrationId,
				$periodKey
			)
		);

		return null !== $found;
	}

	public function findByRegistration( string $registrationType, int $registrationId ): ?Payment {
		$row = $this->db->get_row(
			$this->db->prepare(
				'SELECT * FROM %i WHERE registration_type = %s AND registration_id = %d ORDER BY id DESC LIMIT 1',
				$this->table,
				$registrationType,
				$registrationId
			)
		);

		return $row ? Payment::fromRow( $row ) : null;
	}

	/**
	 * Every payment for a student, newest first (admin payment history).
	 *
	 * @return list<Payment>
	 */
	public function findByStudent( int $studentId ): array {
		$rows = $this->db->get_results(
			$this->db->prepare(
				'SELECT * FROM %i WHERE student_id = %d ORDER BY created_at DESC, id DESC',
				$this->table,
				$studentId
			)
		);

		return array_map( Payment::fromRow( ... ), $rows ?? [] );
	}

	/**
	 * Pending payments, newest first (studio-admin confirmation queue).
	 *
	 * @return list<Payment>
	 */
	public function findPending(): array {
		$rows = $this->db->get_results(
			$this->db->prepare(
				'SELECT * FROM %i WHERE status = %s ORDER BY created_at DESC',
				$this->table,
				Payment::STATUS_PENDING
			)
		);

		return array_map( Payment::fromRow( ... ), $rows ?? [] );
	}

	/**
	 * Mark a payment paid, stamping the paid time and receipt number.
	 */
	public function markPaid( int $id, string $receiptNumber ): bool {
		return false !== $this->db->update(
			$this->table,
			[
				'status'         => Payment::STATUS_PAID,
				'paid_at'        => current_time( 'mysql' ),
				'receipt_number' => $receiptNumber,
			],
			[ 'id' => $id ],
			[ '%s', '%s', '%s' ],
			[ '%d' ]
		);
	}

	public function markReceiptSent( int $id ): bool {
		return false !== $this->db->update(
			$this->table,
			[ 'receipt_sent_at' => current_time( 'mysql' ) ],
			[ 'id' => $id ],
			[ '%s' ],
			[ '%d' ]
		);
	}

	/**
	 * Whether a registration has an unscheduled, un-voided charge — one taken at
	 * registration (`period_key IS NULL`, `status != failed`). The billing-mode
	 * reconciler uses this to spot an up-front charge that a newly-scheduled
	 * offering would otherwise cause the scan to bill a second time.
	 */
	public function hasUnscheduledCharge( string $registrationType, int $registrationId ): bool {
		$found = $this->db->get_var(
			$this->db->prepare(
				'SELECT id FROM %i WHERE registration_type = %s AND registration_id = %d AND period_key IS NULL AND status != %s LIMIT 1',
				$this->table,
				$registrationType,
				$registrationId,
				Payment::STATUS_FAILED
			)
		);

		return null !== $found;
	}

	/**
	 * Stamp a registration's existing unscheduled charge with a billing period and
	 * due date so the daily scan treats that period as already billed. Used when
	 * an offering is switched to scheduled billing: the charge taken at enrolment
	 * (which carries no `period_key`) would otherwise never match the scan's
	 * per-period dedup, and the enrolment would be billed a second time for the
	 * period the up-front charge already covers.
	 *
	 * Only ever adopts a charge that is genuinely unscheduled (`period_key IS
	 * NULL`) and not voided (`status != failed`) — so it cannot overwrite a real
	 * scheduled charge or revive a cancelled one. The caller guards against a
	 * period that already has a scheduled charge (see {@see existsForPeriod}).
	 * Returns the number of rows adopted (0 or 1).
	 */
	public function claimPeriodForUnscheduled( string $registrationType, int $registrationId, string $periodKey, string $dueDate ): int {
		$sql = $this->db->prepare(
			'UPDATE %i SET period_key = %s, due_date = %s
			 WHERE registration_type = %s AND registration_id = %d
			   AND period_key IS NULL AND status != %s
			 ORDER BY id ASC LIMIT 1',
			$this->table,
			$periodKey,
			$dueDate,
			$registrationType,
			$registrationId,
			Payment::STATUS_FAILED
		);

		if ( null === $sql ) {
			return 0;
		}

		return (int) $this->db->query( $sql );
	}

	/**
	 * Atomically claim a payment for its one due-payment notice. Stamps
	 * `notice_sent_at` only if it is still null, and returns whether *this* call
	 * won the claim (one row updated). The billing scan calls this before
	 * emailing so a payment's notice is sent exactly once: WP-Cron fires on
	 * request and can overlap under concurrent traffic, so two scans may both
	 * reach the send step for the same payment — the loser here updates zero rows
	 * and skips the email. The conditional `WHERE ... IS NULL` is the guard, not a
	 * prior read, so there is no check-then-act race.
	 */
	public function markNoticed( int $id ): bool {
		$sql = $this->db->prepare(
			'UPDATE %i SET notice_sent_at = %s WHERE id = %d AND notice_sent_at IS NULL',
			$this->table,
			current_time( 'mysql' ),
			$id
		);

		if ( null === $sql ) {
			return false;
		}

		return (int) $this->db->query( $sql ) === 1;
	}

	/**
	 * One-time repair for sites upgraded before `notice_sent_at` existed: dbDelta
	 * adds the column, and this backfills it so the historical payments those
	 * sites already emailed notices for are not re-noticed on the next scan.
	 * Every pre-existing pending scheduled row is treated as already noticed.
	 * Guarded by its own option flag in {@see \Unsupervised\Schedular\Plugin},
	 * not the version gate, since affected sites may already be on the current
	 * version. Returns false when the column is absent so the caller does not set
	 * its flag before dbDelta has run.
	 */
	public function backfillNoticeSent(): bool {
		$column = $this->db->get_var(
			$this->db->prepare(
				'SHOW COLUMNS FROM %i LIKE %s',
				$this->table,
				'notice_sent_at'
			)
		);

		if ( null === $column ) {
			return false;
		}

		$sql = $this->db->prepare(
			'UPDATE %i SET notice_sent_at = created_at WHERE notice_sent_at IS NULL AND period_key IS NOT NULL',
			$this->table
		);

		if ( null !== $sql ) {
			$this->db->query( $sql );
		}

		return true;
	}

	public function updateStatus( int $id, string $status ): bool {
		if ( ! in_array( $status, Payment::VALID_STATUSES, true ) ) {
			return false;
		}

		return (bool) $this->db->update(
			$this->table,
			[ 'status' => $status ],
			[ 'id' => $id ],
			[ '%s' ],
			[ '%d' ]
		);
	}
}