From fd1433bf9bb8d2f3d46772d1740b098f9f12bfae Mon Sep 17 00:00:00 2001
From: larssandergreen <lars@wildsight.ca>
Date: Thu, 29 Jun 2023 18:25:41 -0600
Subject: [PATCH] Add missing Mailing Events to API4: Delivered, Forward, Reply

---
 .../Event/BAO/MailingEventDelivered.php       | 19 ++++++++++++---
 CRM/Mailing/Event/BAO/MailingEventForward.php |  2 +-
 .../Civi/Api4/MailingEventDelivered.php       | 23 +++++++++++++++++++
 .../Civi/Api4/MailingEventForward.php         | 23 +++++++++++++++++++
 ext/civi_mail/Civi/Api4/MailingEventReply.php | 23 +++++++++++++++++++
 5 files changed, 86 insertions(+), 4 deletions(-)
 create mode 100644 ext/civi_mail/Civi/Api4/MailingEventDelivered.php
 create mode 100644 ext/civi_mail/Civi/Api4/MailingEventForward.php
 create mode 100644 ext/civi_mail/Civi/Api4/MailingEventReply.php

diff --git a/CRM/Mailing/Event/BAO/MailingEventDelivered.php b/CRM/Mailing/Event/BAO/MailingEventDelivered.php
index 6d823e71e3..0d651c1fe7 100644
--- a/CRM/Mailing/Event/BAO/MailingEventDelivered.php
+++ b/CRM/Mailing/Event/BAO/MailingEventDelivered.php
@@ -17,15 +17,15 @@
 class CRM_Mailing_Event_BAO_MailingEventDelivered extends CRM_Mailing_Event_DAO_MailingEventDelivered {
 
   /**
-   * Create a new delivery event.
+   * Record a new delivery event.
    *
    * @param array $params
    *   Associative array of delivery event values.
    *
    * @return \CRM_Mailing_Event_BAO_MailingEventDelivered
    */
-  public static function &create(&$params) {
-    $q = &CRM_Mailing_Event_BAO_MailingEventQueue::verify($params['job_id'],
+  public static function recordDelivery(&$params) {
+    $q = CRM_Mailing_Event_BAO_MailingEventQueue::verify($params['job_id'],
       $params['event_queue_id'],
       $params['hash']
     );
@@ -54,6 +54,19 @@ class CRM_Mailing_Event_BAO_MailingEventDelivered extends CRM_Mailing_Event_DAO_
     return $delivered;
   }
 
+  /**
+   * Create function was renamed `recordDelivery` because it's not a standard CRUD create function
+   *
+   * @param array $params
+   * @deprecated
+   *
+   * @return \CRM_Mailing_Event_BAO_MailingEventDelivered
+   */
+  public static function create(&$params) {
+    CRM_Core_Error::deprecatedFunctionWarning('recordDelivery');
+    return self::recordDelivery($params);
+  }
+
   /**
    * Get row count for the event selector.
    *
diff --git a/CRM/Mailing/Event/BAO/MailingEventForward.php b/CRM/Mailing/Event/BAO/MailingEventForward.php
index a94fcab29a..b626eccafb 100644
--- a/CRM/Mailing/Event/BAO/MailingEventForward.php
+++ b/CRM/Mailing/Event/BAO/MailingEventForward.php
@@ -183,7 +183,7 @@ class CRM_Mailing_Event_BAO_MailingEventForward extends CRM_Mailing_Event_DAO_Ma
       $successfulForward = TRUE;
       // Register the delivery event.
 
-      CRM_Mailing_Event_BAO_MailingEventDelivered::create($params);
+      CRM_Mailing_Event_BAO_MailingEventDelivered::recordDelivery($params);
     }
 
     $transaction->commit();
diff --git a/ext/civi_mail/Civi/Api4/MailingEventDelivered.php b/ext/civi_mail/Civi/Api4/MailingEventDelivered.php
new file mode 100644
index 0000000000..08d38df771
--- /dev/null
+++ b/ext/civi_mail/Civi/Api4/MailingEventDelivered.php
@@ -0,0 +1,23 @@
+<?php
+/*
+ +--------------------------------------------------------------------+
+ | Copyright CiviCRM LLC. All rights reserved.                        |
+ |                                                                    |
+ | This work is published under the GNU AGPLv3 license with some      |
+ | permitted exceptions and without any warranty. For full license    |
+ | and copyright information, see https://civicrm.org/licensing       |
+ +--------------------------------------------------------------------+
+ */
+namespace Civi\Api4;
+
+/**
+ * Tracks when a queued email is actually delivered to the MTA.
+ *
+ * @see \Civi\Api4\Mailing
+ * @since 5.64
+ * @package Civi\Api4
+ */
+class MailingEventDelivered extends Generic\DAOEntity {
+  use Generic\Traits\ReadOnlyEntity;
+
+}
diff --git a/ext/civi_mail/Civi/Api4/MailingEventForward.php b/ext/civi_mail/Civi/Api4/MailingEventForward.php
new file mode 100644
index 0000000000..9459c4df6b
--- /dev/null
+++ b/ext/civi_mail/Civi/Api4/MailingEventForward.php
@@ -0,0 +1,23 @@
+<?php
+/*
+ +--------------------------------------------------------------------+
+ | Copyright CiviCRM LLC. All rights reserved.                        |
+ |                                                                    |
+ | This work is published under the GNU AGPLv3 license with some      |
+ | permitted exceptions and without any warranty. For full license    |
+ | and copyright information, see https://civicrm.org/licensing       |
+ +--------------------------------------------------------------------+
+ */
+namespace Civi\Api4;
+
+/**
+ * Tracks when a contact forwards a mailing to a (new) contact
+ *
+ * @see \Civi\Api4\Mailing
+ * @since 5.64
+ * @package Civi\Api4
+ */
+class MailingEventForward extends Generic\DAOEntity {
+  use Generic\Traits\ReadOnlyEntity;
+
+}
diff --git a/ext/civi_mail/Civi/Api4/MailingEventReply.php b/ext/civi_mail/Civi/Api4/MailingEventReply.php
new file mode 100644
index 0000000000..d21b1c5d96
--- /dev/null
+++ b/ext/civi_mail/Civi/Api4/MailingEventReply.php
@@ -0,0 +1,23 @@
+<?php
+/*
+ +--------------------------------------------------------------------+
+ | Copyright CiviCRM LLC. All rights reserved.                        |
+ |                                                                    |
+ | This work is published under the GNU AGPLv3 license with some      |
+ | permitted exceptions and without any warranty. For full license    |
+ | and copyright information, see https://civicrm.org/licensing       |
+ +--------------------------------------------------------------------+
+ */
+namespace Civi\Api4;
+
+/**
+ * TTracks when a contact replies to a mailing.
+ *
+ * @see \Civi\Api4\Mailing
+ * @since 5.64
+ * @package Civi\Api4
+ */
+class MailingEventReply extends Generic\DAOEntity {
+  use Generic\Traits\ReadOnlyEntity;
+
+}
-- 
2.25.1