From 3856ef6170e249d21616b53a9fe5870667884ff7 Mon Sep 17 00:00:00 2001
From: Jens Schuppe <schuppe@systopia.de>
Date: Fri, 5 Oct 2018 15:59:11 +0200
Subject: [PATCH] [WIP] TwingleDonation.EndRecurring and Cancel API actions.

---
 api/v3/TwingleDonation/Cancel.php       | 96 +++++++++++++++++++++++++
 api/v3/TwingleDonation/EndRecurring.php | 88 +++++++++++++++++++++++
 api/v3/TwingleDonation/Submit.php       | 11 +--
 3 files changed, 191 insertions(+), 4 deletions(-)
 create mode 100644 api/v3/TwingleDonation/Cancel.php
 create mode 100644 api/v3/TwingleDonation/EndRecurring.php

diff --git a/api/v3/TwingleDonation/Cancel.php b/api/v3/TwingleDonation/Cancel.php
new file mode 100644
index 0000000..ec43f2e
--- /dev/null
+++ b/api/v3/TwingleDonation/Cancel.php
@@ -0,0 +1,96 @@
+<?php
+/*------------------------------------------------------------+
+| SYSTOPIA Twingle Integration                                |
+| Copyright (C) 2018 SYSTOPIA                                 |
+| Author: J. Schuppe (schuppe@systopia.de)                    |
++-------------------------------------------------------------+
+| This program is released as free software under the         |
+| Affero GPL license. You can redistribute it and/or          |
+| modify it under the terms of this license which you         |
+| can read by viewing the included agpl.txt or online         |
+| at www.gnu.org/licenses/agpl.html. Removal of this          |
+| copyright header is strictly prohibited without             |
+| written permission from the original author(s).             |
++-------------------------------------------------------------*/
+
+use CRM_Twingle_ExtensionUtil as E;
+
+/**
+ * TwingleDonation.Cancel API specification (optional)
+ * This is used for documentation and validation.
+ *
+ * @param array $params description of fields supported by this API call
+ *
+ * @return void
+ *
+ * @see http://wiki.civicrm.org/confluence/display/CRMDOC/API+Architecture+Standards
+ */
+function _civicrm_api3_twingle_donation_Cancel_spec(&$params) {
+  $params['project_id'] = array(
+    'name' => 'project_id',
+    'title' => 'Project ID',
+    'type' => CRM_Utils_Type::T_STRING,
+    'api.required' => 1,
+    'description' => 'The Twingle project ID.',
+  );
+  $params['trx_id'] = array(
+    'name' => 'trx_id',
+    'title' => 'Transaction ID',
+    'type' => CRM_Utils_Type::T_STRING,
+    'api.required' => 1,
+    'description' => 'The unique transaction ID of the donation',
+  );
+  $params['cancelled_at'] = array(
+    'name'         => 'cancelled_at',
+    'title'        => 'Cancelled at',
+    'type'         => CRM_Utils_Type::T_INT,
+    'api.required' => 1,
+    'description'  => 'The date when the donation was cancelled, format: YYYYMMDD.',
+  );
+  $params['cancel_reason'] = array(
+    'name'         => 'cancel_reason',
+    'title'        => 'Cancel reason',
+    'type'         => CRM_Utils_Type::T_STRING,
+    'api.required' => 1,
+    'description'  => 'The reason for the donation being cancelled.',
+  );
+}
+
+/**
+ * TwingleDonation.Cancel API
+ *
+ * @param array $params
+ * @return array API result descriptor
+ * @see civicrm_api3_create_success
+ * @see civicrm_api3_create_error
+ * @throws API_Exception
+ */
+function civicrm_api3_twingle_donation_Cancel($params) {
+  try {
+    // Validate date for parameter "cancelled_at".
+    if (!DateTime::createFromFormat('Ymd', $params['cancelled_at'])) {
+      throw new CiviCRM_API3_Exception(
+        E::ts('Invalid date for parameter "cancelled_at".'),
+        'invalid_format'
+      );
+    }
+
+    $contribution = civicrm_api3('Contribution', 'getsingle', array(
+      'trxn_id' => $params['trx_id'],
+    ));
+    // TODO: Can recurring contributions be cancelled? End SEPA mandates?
+    $contribution = civicrm_api3('Contribution', 'create', array(
+      'id' => $contribution['id'],
+      'cancel_date' => $params['cancelled_at'],
+      'contribution_status_id' => 'Cancelled',
+      'cancel_reason' => $params['cancel_reason'],
+    ));
+
+    $result = civicrm_api3_create_success($contribution);
+  }
+  catch (CiviCRM_API3_Exception $exception) {
+    $result = civicrm_api3_create_error($exception->getMessage());
+  }
+
+  return $result;
+}
diff --git a/api/v3/TwingleDonation/EndRecurring.php b/api/v3/TwingleDonation/EndRecurring.php
new file mode 100644
index 0000000..6d592da
--- /dev/null
+++ b/api/v3/TwingleDonation/EndRecurring.php
@@ -0,0 +1,88 @@
+<?php
+/*------------------------------------------------------------+
+| SYSTOPIA Twingle Integration                                |
+| Copyright (C) 2018 SYSTOPIA                                 |
+| Author: J. Schuppe (schuppe@systopia.de)                    |
++-------------------------------------------------------------+
+| This program is released as free software under the         |
+| Affero GPL license. You can redistribute it and/or          |
+| modify it under the terms of this license which you         |
+| can read by viewing the included agpl.txt or online         |
+| at www.gnu.org/licenses/agpl.html. Removal of this          |
+| copyright header is strictly prohibited without             |
+| written permission from the original author(s).             |
++-------------------------------------------------------------*/
+
+use CRM_Twingle_ExtensionUtil as E;
+
+/**
+ * TwingleDonation.EndRecurring API specification (optional)
+ * This is used for documentation and validation.
+ *
+ * @param array $params description of fields supported by this API call
+ *
+ * @return void
+ *
+ * @see http://wiki.civicrm.org/confluence/display/CRMDOC/API+Architecture+Standards
+ */
+function _civicrm_api3_twingle_donation_EndRecurring_spec(&$params) {
+  $params['project_id'] = array(
+    'name' => 'project_id',
+    'title' => 'Project ID',
+    'type' => CRM_Utils_Type::T_STRING,
+    'api.required' => 1,
+    'description' => 'The Twingle project ID.',
+  );
+  $params['trx_id'] = array(
+    'name' => 'trx_id',
+    'title' => 'Transaction ID',
+    'type' => CRM_Utils_Type::T_STRING,
+    'api.required' => 1,
+    'description' => 'The unique transaction ID of the donation',
+  );
+  $params['ended_at'] = array(
+    'name'         => 'ended_at',
+    'title'        => 'Ended at',
+    'type'         => CRM_Utils_Type::T_INT,
+    'api.required' => 1,
+    'description'  => 'The date when the recurring donation was ended, format: YYYYMMDD.',
+  );
+}
+
+/**
+ * TwingleDonation.EndRecurring API
+ *
+ * @param array $params
+ * @return array API result descriptor
+ * @see civicrm_api3_create_success
+ * @see civicrm_api3_create_error
+ * @throws API_Exception
+ */
+function civicrm_api3_twingle_donation_EndRecurring($params) {
+  try {
+    // Validate date for parameter "ended_at".
+    if (!DateTime::createFromFormat('Ymd', $params['ended_at'])) {
+      throw new CiviCRM_API3_Exception(
+        E::ts('Invalid date for parameter "ended_at".'),
+        'invalid_format'
+      );
+    }
+
+    $contribution = civicrm_api3('ContributionRecur', 'getsingle', array(
+      'trxn_id' => $params['trx_id'],
+    ));
+    // TODO: End SEPA mandates?
+    $contribution = civicrm_api3('ContributionRecur', 'create', array(
+      'id' => $contribution['id'],
+      'end_date' => $params['ended_at'],
+      'contribution_status_id' => 'Completed', // TODO: Correct?
+    ));
+
+    $result = civicrm_api3_create_success($contribution);
+  }
+  catch (CiviCRM_API3_Exception $exception) {
+    $result = civicrm_api3_create_error($exception->getMessage());
+  }
+
+  return $result;
+}
diff --git a/api/v3/TwingleDonation/Submit.php b/api/v3/TwingleDonation/Submit.php
index 76409eb..c26faf1 100644
--- a/api/v3/TwingleDonation/Submit.php
+++ b/api/v3/TwingleDonation/Submit.php
@@ -248,10 +248,10 @@ function civicrm_api3_twingle_donation_Submit($params) {
 
     // Do not process an already existing contribution with the given
     // transaction ID.
-    $contribution = civicrm_api3('Contribution', 'get', array(
+    $existing_contribution = civicrm_api3('Contribution', 'get', array(
       'trxn_id' => $params['trx_id']
     ));
-    if ($contribution['count'] > 0) {
+    if ($existing_contribution['count'] > 0) {
       throw new CiviCRM_API3_Exception(
         E::ts('Contribution with the given transaction ID already exists.'),
         'api_error'
@@ -433,6 +433,8 @@ function civicrm_api3_twingle_donation_Submit($params) {
           'api_error'
         );
       }
+
+      $result_values = $mandate;
     }
     else {
       // Create (recurring) contribution.
@@ -465,10 +467,11 @@ function civicrm_api3_twingle_donation_Submit($params) {
           'api_error'
         );
       }
+
+      $result_values = $contribution;
     }
 
-    // TODO: Assemble return data.
-    $result = civicrm_api3_create_success();
+    $result = civicrm_api3_create_success($result_values);
   }
   catch (CiviCRM_API3_Exception $exception) {
     $result = civicrm_api3_create_error($exception->getMessage());