feat(insights): land Donors + Gates tabs on main (NPPD-1617, NPPD-1604)

plugins/newspack-plugin/includes/wizards/insights/api/class-donors-rest-controller.php

@@ -0,0 +1,293 @@
+<?php
+/**
+ * Newspack Insights — Tab 7 Donors REST controller (NPPD-1617).
+ *
+ * Single endpoint: `GET /newspack-insights/v1/donors`. Same date-arg
+ * validation, permissions, and response-shape conventions as
+ * {@see Subscribers_REST_Controller}.
+ *
+ * @package Newspack
+ */
+
+namespace Newspack\Insights;
+
+defined( 'ABSPATH' ) || exit;
+
+use DateTimeImmutable;
+use DateTimeZone;
+use Exception;
+use WP_Error;
+use WP_REST_Controller;
+use WP_REST_Request;
+use WP_REST_Server;
+
+/**
+ * Donors REST controller.
+ */
+class Donors_REST_Controller extends WP_REST_Controller {
+
+	/**
+	 * Dedicated namespace shared with Tab 6.
+	 *
+	 * @var string
+	 */
+	protected $namespace = 'newspack-insights/v1';
+
+	/**
+	 * Route base.
+	 *
+	 * @var string
+	 */
+	protected $rest_base = 'donors';
+
+	/**
+	 * Register the Tab 7 route.
+	 *
+	 * @return void
+	 */
+	public function register_routes(): void {
+		register_rest_route(
+			$this->namespace,
+			'/' . $this->rest_base,
+			[
+				[
+					'methods'             => WP_REST_Server::READABLE,
+					'callback'            => [ $this, 'get_donors_data' ],
+					'permission_callback' => [ $this, 'permissions_check' ],
+					'args'                => $this->get_collection_params(),
+				],
+			]
+		);
+	}
+
+	/**
+	 * Permission check.
+	 *
+	 * @return bool|WP_Error
+	 */
+	public function permissions_check() {
+		if ( ! current_user_can( 'manage_options' ) ) {
+			return new WP_Error(
+				'newspack_insights_rest_forbidden',
+				__( 'You do not have permission to view Insights data.', 'newspack-plugin' ),
+				[ 'status' => rest_authorization_required_code() ]
+			);
+		}
+		return true;
+	}
+
+	/**
+	 * GET handler.
+	 *
+	 * @param WP_REST_Request $request Request.
+	 * @return \WP_REST_Response|WP_Error
+	 */
+	public function get_donors_data( WP_REST_Request $request ) {
+		$tz = $this->site_timezone();
+
+		try {
+			$start = $this->parse_date( $request->get_param( 'start' ), $tz, false );
+			$end   = $this->parse_date( $request->get_param( 'end' ), $tz, true );
+		} catch ( Exception $e ) {
+			return new WP_Error( 'newspack_insights_invalid_date', $e->getMessage(), [ 'status' => 400 ] );
+		}
+		if ( $start > $end ) {
+			return new WP_Error(
+				'newspack_insights_invalid_window',
+				__( 'Start date must be on or before end date.', 'newspack-plugin' ),
+				[ 'status' => 400 ]
+			);
+		}
+
+		$compare_start_param = $request->get_param( 'compare_start' );
+		$compare_end_param   = $request->get_param( 'compare_end' );
+		$compare_start       = null;
+		$compare_end         = null;
+		if ( $compare_start_param || $compare_end_param ) {
+			if ( ! $compare_start_param || ! $compare_end_param ) {
+				return new WP_Error(
+					'newspack_insights_invalid_comparison',
+					__( 'Both compare_start and compare_end must be provided to enable comparison mode.', 'newspack-plugin' ),
+					[ 'status' => 400 ]
+				);
+			}
+			try {
+				$compare_start = $this->parse_date( $compare_start_param, $tz, false );
+				$compare_end   = $this->parse_date( $compare_end_param, $tz, true );
+			} catch ( Exception $e ) {
+				return new WP_Error( 'newspack_insights_invalid_date', $e->getMessage(), [ 'status' => 400 ] );
+			}
+			if ( $compare_start > $compare_end ) {
+				return new WP_Error(
+					'newspack_insights_invalid_comparison_window',
+					__( 'compare_start must be on or before compare_end.', 'newspack-plugin' ),
+					[ 'status' => 400 ]
+				);
+			}
+		}
+
+		$metric = new Donors_Metric();
+		return rest_ensure_response( $this->build_response( $metric, $start, $end, $compare_start, $compare_end ) );
+	}
+
+	/**
+	 * Assemble response.
+	 *
+	 * @param Donors_Metric          $metric        Orchestrator.
+	 * @param DateTimeImmutable      $start         Current window start.
+	 * @param DateTimeImmutable      $end           Current window end.
+	 * @param DateTimeImmutable|null $compare_start Prior window start.
+	 * @param DateTimeImmutable|null $compare_end   Prior window end.
+	 * @return array
+	 */
+	private function build_response(
+		Donors_Metric $metric,
+		DateTimeImmutable $start,
+		DateTimeImmutable $end,
+		?DateTimeImmutable $compare_start,
+		?DateTimeImmutable $compare_end
+	): array {
+		$response = [
+			'classification' => $metric->get_classification_metadata(),
+			'snapshot'       => [
+				'active_donors'                       => $metric->get_active_donors(),
+				'active_recurring_donors'             => $metric->get_active_recurring_donors(),
+				'donation_mrr'                        => $metric->get_donation_mrr(),
+				'donation_arr'                        => $metric->get_donation_arr(),
+				'upcoming_donation_renewals_30d'      => $metric->get_upcoming_donation_renewals_30d(),
+				'upcoming_donation_cancellations_30d' => $metric->get_upcoming_donation_cancellations_30d(),
+			],
+			'current'        => $this->build_window( $metric, $start, $end ),
+			'previous'       => null,
+		];
+		if ( $compare_start && $compare_end ) {
+			$response['previous'] = $this->build_window( $metric, $compare_start, $compare_end );
+		}
+		return $response;
+	}
+
+	/**
+	 * Window-bound payload.
+	 *
+	 * @param Donors_Metric     $metric Orchestrator.
+	 * @param DateTimeImmutable $start  Start.
+	 * @param DateTimeImmutable $end    End.
+	 * @return array
+	 */
+	private function build_window( Donors_Metric $metric, DateTimeImmutable $start, DateTimeImmutable $end ): array {
+		return [
+			'window'                     => [
+				'start' => $start->format( 'Y-m-d' ),
+				'end'   => $end->format( 'Y-m-d' ),
+			],
+			'new_donors'                 => $metric->get_new_donors_in_window( $start, $end ),
+			'lapsed_donors'              => $metric->get_lapsed_donors_in_window( $start, $end ),
+			'one_time_revenue'           => $metric->get_one_time_donation_revenue( $start, $end ),
+			'recurring_revenue'          => $metric->get_recurring_donation_revenue( $start, $end ),
+			'total_revenue'              => $metric->get_total_donation_revenue( $start, $end ),
+			'average_gift'               => $metric->get_average_donation_gift( $start, $end ),
+			'lapsed_donor_recovery_rate' => $metric->get_lapsed_donor_recovery_rate( $start, $end ),
+			'recurring_donor_retention'  => $metric->get_recurring_donor_retention( $start, $end ),
+			'donations_by_tier'          => $metric->get_donations_by_tier( $start, $end ),
+		];
+	}
+
+	/**
+	 * Args spec.
+	 *
+	 * @return array
+	 */
+	public function get_collection_params() {
+		$base = [
+			'type'              => 'string',
+			'sanitize_callback' => 'sanitize_text_field',
+			'validate_callback' => [ $this, 'validate_date_string' ],
+		];
+		return [
+			'start'         => array_merge(
+				$base,
+				[
+					'description' => __( 'Inclusive window start date (YYYY-MM-DD, site timezone).', 'newspack-plugin' ),
+					'required'    => true,
+				]
+			),
+			'end'           => array_merge(
+				$base,
+				[
+					'description' => __( 'Inclusive window end date (YYYY-MM-DD, site timezone).', 'newspack-plugin' ),
+					'required'    => true,
+				]
+			),
+			'compare_start' => array_merge(
+				$base,
+				[
+					'description' => __( 'Optional comparison window start. Must pair with compare_end.', 'newspack-plugin' ),
+					'required'    => false,
+				]
+			),
+			'compare_end'   => array_merge(
+				$base,
+				[
+					'description' => __( 'Optional comparison window end. Must pair with compare_start.', 'newspack-plugin' ),
+					'required'    => false,
+				]
+			),
+		];
+	}
+
+	/**
+	 * REST validate_callback.
+	 *
+	 * @param mixed $value Value.
+	 * @return bool|WP_Error
+	 */
+	public function validate_date_string( $value ) {
+		if ( ! is_string( $value ) || '' === $value ) {
+			return new WP_Error(
+				'newspack_insights_invalid_date',
+				__( 'Date must be a non-empty YYYY-MM-DD string.', 'newspack-plugin' ),
+				[ 'status' => 400 ]
+			);
+		}
+		$parsed = DateTimeImmutable::createFromFormat( 'Y-m-d', $value, $this->site_timezone() );
+		if ( ! $parsed || $parsed->format( 'Y-m-d' ) !== $value ) {
+			return new WP_Error(
+				'newspack_insights_invalid_date',
+				/* translators: %s: the invalid date string */
+				sprintf( __( 'Invalid date "%s". Expected YYYY-MM-DD.', 'newspack-plugin' ), $value ),
+				[ 'status' => 400 ]
+			);
+		}
+		return true;
+	}
+
+	/**
+	 * Parse a Y-m-d string into a DateTimeImmutable.
+	 *
+	 * @param mixed        $value      Raw value.
+	 * @param DateTimeZone $tz         Timezone.
+	 * @param bool         $end_of_day If true, 23:59:59; else 00:00:00.
+	 * @return DateTimeImmutable
+	 * @throws Exception On parse failure.
+	 */
+	private function parse_date( $value, DateTimeZone $tz, bool $end_of_day ): DateTimeImmutable {
+		if ( ! is_string( $value ) || '' === $value ) {
+			throw new Exception( esc_html__( 'Missing date value.', 'newspack-plugin' ) );
+		}
+		$parsed = DateTimeImmutable::createFromFormat( 'Y-m-d', $value, $tz );
+		if ( ! $parsed || $parsed->format( 'Y-m-d' ) !== $value ) {
+			/* translators: %s: the invalid date string */
+			throw new Exception( esc_html( sprintf( __( 'Invalid date "%s". Expected YYYY-MM-DD.', 'newspack-plugin' ), $value ) ) );
+		}
+		return $end_of_day ? $parsed->setTime( 23, 59, 59 ) : $parsed->setTime( 0, 0, 0 );
+	}
+
+	/**
+	 * Site timezone.
+	 *
+	 * @return DateTimeZone
+	 */
+	private function site_timezone(): DateTimeZone {
+		return wp_timezone();
+	}
+}