| @@ -11,8 +11,9 @@ | ||
| 11 | 11 | use SureDonation\Inc\Database\Tables\Donors; |
| 12 | 12 | use SureDonation\Inc\Emails\Email_Handler; |
| 13 | 13 | use SureDonation\Inc\Helper; |
| 14 | 14 | use SureDonation\Inc\Payments\Payment_Helper; |
| 15 | +use SureDonation\Inc\Pdf\Receipt_Generator; | |
| 15 | 16 | use SureDonation\Inc\Payments\Stripe\Stripe_Helper; |
| 16 | 17 | use WP_Error; |
| 17 | 18 | use WP_REST_Request; |
| 18 | 19 | use WP_REST_Response; |
| @@ -121,10 +122,20 @@ | ||
| 121 | 122 | }, |
| 122 | 123 | ], |
| 123 | 124 | 'status' => [ |
| 124 | 125 | 'required' => true, |
| 126 | + 'type' => 'string', | |
| 127 | + // Sourced from the table's own whitelist rather than | |
| 128 | + // restated: the two lists had already drifted — suspicious | |
| 129 | + // is written on an amount mismatch and was missing here. | |
| 130 | + 'enum' => Donations::get_valid_statuses(), | |
| 125 | 131 | 'sanitize_callback' => 'sanitize_text_field', |
| 126 | - 'enum' => [ 'pending', 'processing', 'completed', 'failed', 'refunded', 'partially_refunded', 'cancelled' ], | |
| 132 | + // Required for the enum to be enforced at all. An arg with | |
| 133 | + // a sanitize_callback and no validate_callback has its enum | |
| 134 | + // silently skipped (see #340), so this endpoint answered | |
| 135 | + // "updated successfully" to a status it had refused to | |
| 136 | + // write. | |
| 137 | + 'validate_callback' => 'rest_validate_request_arg', | |
| 127 | 138 | ], |
| 128 | 139 | ], |
| 129 | 140 | ], |
| 130 | 141 | |
| @@ -150,10 +161,12 @@ | ||
| 150 | 161 | 'permission_callback' => [ $this, 'check_permissions' ], |
| 151 | 162 | 'args' => [ |
| 152 | 163 | 'action' => [ |
| 153 | 164 | 'required' => true, |
| 165 | + 'type' => 'string', | |
| 166 | + 'enum' => [ 'delete', 'update_status' ], | |
| 154 | 167 | 'sanitize_callback' => 'sanitize_text_field', |
| 155 | - 'enum' => [ 'delete', 'update_status' ], | |
| 168 | + 'validate_callback' => 'rest_validate_request_arg', | |
| 156 | 169 | ], |
| 157 | 170 | 'ids' => [ |
| 158 | 171 | 'required' => true, |
| 159 | 172 | 'validate_callback' => static function ( $param ) { |
| @@ -160,10 +173,12 @@ | ||
| 160 | 173 | return is_array( $param ) && ! empty( $param ); |
| 161 | 174 | }, |
| 162 | 175 | ], |
| 163 | 176 | 'status' => [ |
| 177 | + 'type' => 'string', | |
| 178 | + 'enum' => Donations::get_valid_statuses(), | |
| 164 | 179 | 'sanitize_callback' => 'sanitize_text_field', |
| 165 | - 'enum' => [ 'pending', 'processing', 'completed', 'failed', 'refunded', 'partially_refunded', 'cancelled' ], | |
| 180 | + 'validate_callback' => 'rest_validate_request_arg', | |
| 166 | 181 | ], |
| 167 | 182 | ], |
| 168 | 183 | ], |
| 169 | 184 | |
| @@ -188,10 +203,16 @@ | ||
| 188 | 203 | 'sanitize_callback' => 'absint', |
| 189 | 204 | ], |
| 190 | 205 | 'refund_type' => [ |
| 191 | 206 | 'required' => true, |
| 207 | + 'type' => 'string', | |
| 208 | + 'enum' => [ 'full', 'partial' ], | |
| 192 | 209 | 'sanitize_callback' => 'sanitize_text_field', |
| 193 | - 'enum' => [ 'full', 'partial' ], | |
| 210 | + // The last arg in this file carrying the #340 shape: an | |
| 211 | + // enum that reads as enforced and is not. rest_validate_ | |
| 212 | + // request_arg() reads the schema's type, so the type above | |
| 213 | + // is not decoration. | |
| 214 | + 'validate_callback' => 'rest_validate_request_arg', | |
| 194 | 215 | ], |
| 195 | 216 | 'refund_notes' => [ |
| 196 | 217 | 'sanitize_callback' => 'sanitize_textarea_field', |
| 197 | 218 | ], |
| @@ -355,9 +376,9 @@ | ||
| 355 | 376 | strtoupper( $order ) // using whitelist validation in the method. |
| 356 | 377 | ); |
| 357 | 378 | |
| 358 | 379 | // Get total count. |
| 359 | - $total = Donations::get_total_donations_by_status( $status, ! empty( $campaign ) ? absint( $campaign ) : 0 ); | |
| 380 | + $total = Donations::count_admin_list( $status, ! empty( $campaign ) ? absint( $campaign ) : 0, sanitize_text_field( $search ) ); | |
| 360 | 381 | } |
| 361 | 382 | |
| 362 | 383 | // Format donations data. |
| 363 | 384 | $donations = []; |
| @@ -521,8 +542,9 @@ | ||
| 521 | 542 | 'fees_covered', |
| 522 | 543 | 'donation_type', |
| 523 | 544 | 'is_anonymous', |
| 524 | 545 | 'donor_comment', |
| 546 | + 'donor_comment_status', | |
| 525 | 547 | 'payment_status', |
| 526 | 548 | 'gateway', |
| 527 | 549 | 'transaction_id', |
| 528 | 550 | ]; |
| @@ -586,14 +608,39 @@ | ||
| 586 | 608 | ); |
| 587 | 609 | } |
| 588 | 610 | |
| 589 | 611 | $old_status = $donation['payment_status'] ?? 'pending'; |
| 590 | - Donations::update_status( $donation_id, $status ); | |
| 612 | + $updated = Donations::update_status( $donation_id, $status ); | |
| 591 | 613 | |
| 614 | + // Strictly false, which is update_status() refusing the value. A 0 is | |
| 615 | + // $wpdb->update() reporting that no row changed, which cannot mean "no | |
| 616 | + // such row" here because the 404 above already proved it exists, and | |
| 617 | + // cannot mean "same status" either because update() always writes | |
| 618 | + // updated_at. Treating both as success is how a refused write looked | |
| 619 | + // like a successful one to every client. | |
| 620 | + // | |
| 621 | + // Note for anyone comparing this with bulk_action(): that path has no | |
| 622 | + // existence check, so a 0 there does mean "no such row" and is | |
| 623 | + // correctly counted as a failure. The two are not in conflict. | |
| 624 | + if ( false === $updated ) { | |
| 625 | + return new WP_Error( | |
| 626 | + 'donation_status_not_updated', | |
| 627 | + __( 'The donation status could not be updated.', 'suredonation' ), | |
| 628 | + [ 'status' => 500 ] | |
| 629 | + ); | |
| 630 | + } | |
| 631 | + | |
| 592 | 632 | // If status changed to completed, update donor stats. |
| 633 | + // | |
| 634 | + // Guarded, not plain: an admin completing a still-pending donation here | |
| 635 | + // does not stop the gateway webhook arriving for the same row later | |
| 636 | + // (Stripe retries for days), and the webhook's donor block has no | |
| 637 | + // "still pending" check of its own. Without a marker written here, that | |
| 638 | + // webhook would record the same donation a second time and double the | |
| 639 | + // donor's total, count and largest gift. | |
| 593 | 640 | if ( 'completed' !== $old_status && 'completed' === $status ) { |
| 594 | 641 | if ( ! empty( $donation['donor_id'] ) ) { |
| 595 | - Donors::record_donation( $donation['donor_id'], floatval( $donation['amount'] ) ); | |
| 642 | + Donors::record_donation_once( $donation['donor_id'], floatval( $donation['amount'] ), $donation_id ); | |
| 596 | 643 | } |
| 597 | 644 | } |
| 598 | 645 | |
| 599 | 646 | return new WP_REST_Response( |
| @@ -617,8 +664,29 @@ | ||
| 617 | 664 | |
| 618 | 665 | $result = Donations::delete( $donation_id ); |
| 619 | 666 | |
| 620 | 667 | if ( ! $result ) { |
| 668 | + // A donation is kept, deliberately, when its receipt PDF could not | |
| 669 | + // be removed, so that the pointer stays reachable for a retry | |
| 670 | + // instead of the file being orphaned. That reads as an unexplained | |
| 671 | + // failure unless it is named: the admin has to fix the filesystem, | |
| 672 | + // not retry. | |
| 673 | + // | |
| 674 | + // Ask the helper again rather than inferring from the surviving | |
| 675 | + // pointer. It is idempotent and reports whether a file is still | |
| 676 | + // there, so this is the fact rather than a guess: a row whose | |
| 677 | + // DELETE failed after its receipt was already removed would | |
| 678 | + // otherwise be reported as an uploads-permissions problem. | |
| 679 | + $donation = Donations::get( $donation_id ); | |
| 680 | + | |
| 681 | + if ( is_array( $donation ) && ! Receipt_Generator::delete_receipt( Helper::get_string_value( $donation['receipt_pdf_url'] ?? '' ) ) ) { | |
| 682 | + return new WP_Error( | |
| 683 | + 'receipt_delete_failed', | |
| 684 | + __( 'This donation was kept because its PDF receipt could not be removed from the uploads folder. Deleting the record on its own would leave the receipt behind. Check the permissions on the uploads folder, then try again.', 'suredonation' ), | |
| 685 | + [ 'status' => 500 ] | |
| 686 | + ); | |
| 687 | + } | |
| 688 | + | |
| 621 | 689 | return new WP_Error( |
| 622 | 690 | 'delete_failed', |
| 623 | 691 | __( 'Failed to delete donation.', 'suredonation' ), |
| 624 | 692 | [ 'status' => 500 ] |
| @@ -1087,34 +1155,42 @@ | ||
| 1087 | 1155 | * @since 0.0.1 |
| 1088 | 1156 | */ |
| 1089 | 1157 | private function get_donation_args( $required = true ) { |
| 1090 | 1158 | return [ |
| 1091 | - 'campaign_id' => [ | |
| 1159 | + 'campaign_id' => [ | |
| 1092 | 1160 | 'required' => $required, |
| 1093 | 1161 | 'sanitize_callback' => 'absint', |
| 1094 | 1162 | ], |
| 1095 | - 'donor_name' => [ | |
| 1163 | + 'donor_name' => [ | |
| 1096 | 1164 | 'sanitize_callback' => 'sanitize_text_field', |
| 1097 | 1165 | ], |
| 1098 | - 'donor_email' => [ | |
| 1166 | + 'donor_email' => [ | |
| 1099 | 1167 | 'sanitize_callback' => 'sanitize_email', |
| 1100 | 1168 | ], |
| 1101 | - 'donor_phone' => [ | |
| 1169 | + 'donor_phone' => [ | |
| 1102 | 1170 | 'sanitize_callback' => 'sanitize_text_field', |
| 1103 | 1171 | ], |
| 1104 | - 'amount' => [ | |
| 1172 | + 'amount' => [ | |
| 1105 | 1173 | 'required' => $required, |
| 1106 | 1174 | 'sanitize_callback' => static function ( $value ) { |
| 1107 | 1175 | return floatval( $value ); |
| 1108 | 1176 | }, |
| 1109 | 1177 | ], |
| 1110 | - 'fees_covered' => [ | |
| 1178 | + 'fees_covered' => [ | |
| 1111 | 1179 | 'sanitize_callback' => static function ( $value ) { |
| 1112 | 1180 | return floatval( $value ); |
| 1113 | 1181 | }, |
| 1114 | 1182 | ], |
| 1115 | - 'donation_type' => [ | |
| 1116 | - 'default' => 'one-time', | |
| 1183 | + // No 'default' on this or 'payment_status' below, deliberately. These args | |
| 1184 | + // are shared with the update route, where WordPress fills an absent param | |
| 1185 | + // with its declared default before the callback runs — so update_donation()' | |
| 1186 | + // s `! is_null()` test passes and the field is written even though the | |
| 1187 | + // client never sent it. A partial update (e.g. the Donor Comment panel | |
| 1188 | + // sending only donor_comment_status) therefore reset payment_status to | |
| 1189 | + // 'pending' and donation_type to 'one-time', un-completing the donation and | |
| 1190 | + // downgrading a subscription. create_donation() supplies its own fallbacks | |
| 1191 | + // (`?? 'pending'`, `?? 'one-time'`), so nothing depends on the defaults here. | |
| 1192 | + 'donation_type' => [ | |
| 1117 | 1193 | 'enum' => [ 'one-time', 'recurring', 'renewal' ], |
| 1118 | 1194 | 'sanitize_callback' => 'sanitize_text_field', |
| 1119 | 1195 | 'validate_callback' => static function ( $param ) { |
| 1120 | 1196 | return in_array( $param, [ 'one-time', 'recurring', 'renewal' ], true ); |
| @@ -1119,28 +1195,50 @@ | ||
| 1119 | 1195 | 'validate_callback' => static function ( $param ) { |
| 1120 | 1196 | return in_array( $param, [ 'one-time', 'recurring', 'renewal' ], true ); |
| 1121 | 1197 | }, |
| 1122 | 1198 | ], |
| 1123 | - 'is_anonymous' => [ | |
| 1199 | + 'is_anonymous' => [ | |
| 1124 | 1200 | 'sanitize_callback' => 'rest_sanitize_boolean', |
| 1125 | 1201 | ], |
| 1126 | - 'donor_comment' => [ | |
| 1127 | - 'sanitize_callback' => 'wp_kses_post', | |
| 1202 | + 'donor_comment' => [ | |
| 1203 | + // sanitize_textarea_field, matching the capture path in | |
| 1204 | + // Payment_Helper::get_mapped_donor_comment(). wp_kses_post() was | |
| 1205 | + // actively destructive here: it parses anything tag-shaped, so a | |
| 1206 | + // moderator saving the comment "a < b and 3 > 2" stored "a <b> 2" | |
| 1207 | + // — losing " and 3 " — and any surviving markup then rendered as | |
| 1208 | + // literal angle brackets, because the campaign page esc_html()s. | |
| 1209 | + // Both sanitizers preserve the donor's newlines. | |
| 1210 | + 'sanitize_callback' => 'sanitize_textarea_field', | |
| 1128 | 1211 | ], |
| 1129 | - 'payment_status' => [ | |
| 1130 | - 'default' => 'pending', | |
| 1131 | - 'enum' => [ 'pending', 'processing', 'completed', 'failed', 'refunded', 'partially_refunded', 'cancelled' ], | |
| 1212 | + 'donor_comment_status' => [ | |
| 1213 | + 'enum' => [ 'approved', 'pending', 'rejected' ], | |
| 1132 | 1214 | 'sanitize_callback' => 'sanitize_text_field', |
| 1215 | + // A sanitize_callback silently disables `enum` enforcement, so the | |
| 1216 | + // allowed set is checked here too — otherwise any string would reach | |
| 1217 | + // the column and every comment would read as un-approved. | |
| 1133 | 1218 | 'validate_callback' => static function ( $param ) { |
| 1134 | - return in_array( $param, [ 'pending', 'processing', 'completed', 'failed', 'refunded', 'partially_refunded', 'cancelled' ], true ); | |
| 1219 | + return in_array( $param, Donations::get_valid_comment_statuses(), true ); | |
| 1135 | 1220 | }, |
| 1136 | 1221 | ], |
| 1137 | - 'gateway' => [ | |
| 1222 | + 'payment_status' => [ | |
| 1223 | + 'type' => 'string', | |
| 1224 | + // Deliberately no 'default'. These args are shared with the | |
| 1225 | + // update route, and WordPress fills an absent param with its | |
| 1226 | + // default before the callback runs — so update_donation()'s | |
| 1227 | + // `! is_null()` test passes and the status is overwritten on a | |
| 1228 | + // partial update the client never sent it in. dev carries the | |
| 1229 | + // default; keeping it here would reinstate that bug. See | |
| 1230 | + // Test_Donations_API::test_update_donation_ignores_unsent_fields(). | |
| 1231 | + 'enum' => Donations::get_valid_statuses(), | |
| 1138 | 1232 | 'sanitize_callback' => 'sanitize_text_field', |
| 1233 | + 'validate_callback' => 'rest_validate_request_arg', | |
| 1139 | 1234 | ], |
| 1140 | - 'transaction_id' => [ | |
| 1235 | + 'gateway' => [ | |
| 1141 | 1236 | 'sanitize_callback' => 'sanitize_text_field', |
| 1142 | 1237 | ], |
| 1238 | + 'transaction_id' => [ | |
| 1239 | + 'sanitize_callback' => 'sanitize_text_field', | |
| 1240 | + ], | |
| 1143 | 1241 | ]; |
| 1144 | 1242 | } |
| 1145 | 1243 | |
| 1146 | 1244 | /** |
| @@ -1166,12 +1264,13 @@ | ||
| 1166 | 1264 | * @return int Amount in smallest currency unit. |
| 1167 | 1265 | * @since 0.0.1 |
| 1168 | 1266 | */ |
| 1169 | 1267 | private function amount_to_stripe_format( $amount, $currency ) { |
| 1170 | - $zero_decimal = [ 'BIF', 'CLP', 'DJF', 'GNF', 'JPY', 'KMF', 'KRW', 'MGA', 'PYG', 'RWF', 'UGX', 'VND', 'VUV', 'XAF', 'XOF', 'XPF' ]; | |
| 1171 | - return in_array( strtoupper( $currency ), $zero_decimal, true ) | |
| 1172 | - ? (int) round( $amount ) | |
| 1173 | - : (int) round( $amount * 100 ); | |
| 1268 | + // Delegates rather than repeating the zero-decimal list: the abilities | |
| 1269 | + // layer guards refunds with Payment_Helper, so a second hardcoded list | |
| 1270 | + // here could disagree with the guard about what a currency's minor unit | |
| 1271 | + // is. Payment_Helper derives it from the currency data table. | |
| 1272 | + return Payment_Helper::amount_to_stripe_format( $amount, $currency ); | |
| 1174 | 1273 | } |
| 1175 | 1274 | |
| 1176 | 1275 | /** |
| 1177 | 1276 | * Convert amount from Stripe's smallest currency unit. |
| @@ -1181,12 +1280,9 @@ | ||
| 1181 | 1280 | * @return float Amount in major currency unit. |
| 1182 | 1281 | * @since 0.0.1 |
| 1183 | 1282 | */ |
| 1184 | 1283 | private function amount_from_stripe_format( $amount, $currency ) { |
| 1185 | - $zero_decimal = [ 'BIF', 'CLP', 'DJF', 'GNF', 'JPY', 'KMF', 'KRW', 'MGA', 'PYG', 'RWF', 'UGX', 'VND', 'VUV', 'XAF', 'XOF', 'XPF' ]; | |
| 1186 | - return in_array( strtoupper( $currency ), $zero_decimal, true ) | |
| 1187 | - ? (float) $amount | |
| 1188 | - : (float) $amount / 100; | |
| 1284 | + return Payment_Helper::amount_from_stripe_format( $amount, $currency ); | |
| 1189 | 1285 | } |
| 1190 | 1286 | |
| 1191 | 1287 | /** |
| 1192 | 1288 | * Format donation data for API response. |
| @@ -1224,9 +1320,9 @@ | ||
| 1224 | 1320 | // group is the parent block label (e.g. "Address") used to nest |
| 1225 | 1321 | // sub-fields on the entry screen; '' for standalone fields. |
| 1226 | 1322 | $submitted_fields = []; |
| 1227 | 1323 | if ( isset( $donation_data['fields'] ) && is_array( $donation_data['fields'] ) ) { |
| 1228 | - foreach ( $donation_data['fields'] as $field ) { | |
| 1324 | + foreach ( $donation_data['fields'] as $slug => $field ) { | |
| 1229 | 1325 | if ( ! is_array( $field ) ) { |
| 1230 | 1326 | continue; |
| 1231 | 1327 | } |
| 1232 | 1328 | // sanitize_text_field (not esc_html) for REST data: the values are |
| @@ -1232,10 +1328,16 @@ | ||
| 1232 | 1328 | // sanitize_text_field (not esc_html) for REST data: the values are |
| 1233 | 1329 | // already sanitized at write time and React escapes on render, so |
| 1234 | 1330 | // esc_html here would double-encode (e.g. "Cats & Dogs" -> "Cats & Dogs"). |
| 1235 | 1331 | $submitted_fields[] = [ |
| 1332 | + // The stored key. Labels are admin-editable and translatable; | |
| 1333 | + // an add-on that presents a group its own way matches on this. | |
| 1334 | + 'slug' => sanitize_text_field( Helper::get_string_value( $slug ) ), | |
| 1236 | 1335 | 'label' => sanitize_text_field( Helper::get_string_value( $field['label'] ?? '' ) ), |
| 1237 | - 'value' => sanitize_text_field( Helper::get_string_value( $field['value'] ?? '' ) ), | |
| 1336 | + // Checkbox fields store a canonical untranslated token so the | |
| 1337 | + // stored column stays locale-stable; it is translated here, on | |
| 1338 | + // read, for the entry screen. Non-checkbox values pass through. | |
| 1339 | + 'value' => sanitize_text_field( Helper::format_checkbox_field_value( $field['value'] ?? '' ) ), | |
| 1238 | 1340 | 'group' => sanitize_text_field( Helper::get_string_value( $field['group'] ?? '' ) ), |
| 1239 | 1341 | ]; |
| 1240 | 1342 | } |
| 1241 | 1343 | } |
| @@ -1260,9 +1362,18 @@ | ||
| 1260 | 1362 | 'refunded_amount' => Helper::get_float_value( $donation['refunded_amount'] ?? 0 ), |
| 1261 | 1363 | 'currency' => esc_html( Helper::get_string_value( $donation['currency'] ?? 'USD' ) ), |
| 1262 | 1364 | 'donation_type' => esc_html( Helper::get_string_value( $donation['donation_type'] ?? 'one-time' ) ), |
| 1263 | 1365 | 'is_anonymous' => ! empty( $donation['is_anonymous'] ), |
| 1264 | - 'donor_comment' => wp_kses_post( Helper::get_string_value( $donation['donor_comment'] ?? '' ) ), | |
| 1366 | + // Returned raw, unlike its neighbours. The only consumer is the React | |
| 1367 | + // moderation panel, which renders it as a text child and so escapes it | |
| 1368 | + // itself; and DonorCommentSection writes this value straight back on | |
| 1369 | + // Save. Running it through wp_kses_post() here therefore did not | |
| 1370 | + // protect anything — it parsed anything tag-shaped and the moderator | |
| 1371 | + // persisted the parsed result, so "a < b and 3 > 2" was shown as | |
| 1372 | + // "a <b> 2" and saved as "a 2". esc_html() would be just as wrong: | |
| 1373 | + // the panel would display the entities rather than the donor's text. | |
| 1374 | + 'donor_comment' => Helper::get_string_value( $donation['donor_comment'] ?? '' ), | |
| 1375 | + 'donor_comment_status' => esc_html( Helper::get_string_value( $donation['donor_comment_status'] ?? 'approved' ) ), | |
| 1265 | 1376 | 'payment_status' => esc_html( Helper::get_string_value( $donation['payment_status'] ?? 'pending' ) ), |
| 1266 | 1377 | 'payment_mode' => esc_html( Helper::get_string_value( $payment_mode ) ), |
| 1267 | 1378 | 'gateway' => esc_html( Helper::get_string_value( $donation['gateway'] ?? '' ) ), |
| 1268 | 1379 | 'transaction_id' => esc_html( Helper::get_string_value( $donation['transaction_id'] ?? '' ) ), |
