feature: add WebhookEvents api

src/Framework/PaymentGateways/PaymentGateway.php

@@ -14,6 +14,7 @@
 use Give\Framework\PaymentGateways\Routes\RouteSignature;
 use Give\Framework\PaymentGateways\Traits\HandleHttpResponses;
 use Give\Framework\PaymentGateways\Traits\HasRouteMethods;
+use Give\Framework\PaymentGateways\Webhooks\WebhookEvents;
 use Give\Framework\Support\ValueObjects\Money;
 use Give\Log\Log;
 use Give\Subscriptions\Models\Subscription;
@@ -43,6 +44,13 @@ abstract class PaymentGateway implements PaymentGatewayInterface,
     public $subscriptionModule;
 
     /**
+     * @unreleased
+     * @var WebhookEvents $webhookEvents
+     */
+    public $webhookEvents;
+
+    /**
+     * @unreleased Set the webhookEvents property
      * @since 2.20.0 Change first argument type to SubscriptionModule abstract class.
      * @since 2.18.0
      *
@@ -55,6 +63,17 @@ public function __construct(SubscriptionModule $subscriptionModule = null)
         }
 
         $this->subscriptionModule = $subscriptionModule;
+        $this->webhookEvents = new WebhookEvents($this);
+    }
+
+    /**
+     * @unreleased
+     */
+    public static function webhookEvents(): WebhookEvents
+    {
+        $instance = new static();
+
+        return $instance->webhookEvents;
     }
 
     /**

src/Framework/PaymentGateways/Webhooks/ValueObjects/WebhookEventStatus.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Give\Framework\PaymentGateways\Webhooks\ValueObjects;
+
+use ActionScheduler_Store;
+use Give\Framework\Support\ValueObjects\Enum;
+
+/**
+ * @unreleased
+ *
+ * @method static WebhookEventStatus COMPLETE()
+ * @method static WebhookEventStatus PENDING()
+ * @method static WebhookEventStatus RUNNING()
+ * @method static WebhookEventStatus FAILED()
+ * @method static WebhookEventStatus CANCELED()
+ * @method bool isComplete()
+ * @method bool isPending()
+ * @method bool isRunning()
+ * @method bool isFailed()
+ * @method bool isCanceled()
+ */
+class WebhookEventStatus extends Enum
+{
+    const COMPLETE = ActionScheduler_Store::STATUS_COMPLETE;
+    const PENDING = ActionScheduler_Store::STATUS_PENDING;
+    const RUNNING = ActionScheduler_Store::STATUS_RUNNING;
+    const FAILED = ActionScheduler_Store::STATUS_FAILED;
+    const CANCELED = ActionScheduler_Store::STATUS_CANCELED;
+}

src/Framework/PaymentGateways/Webhooks/WebhookEvents.php

@@ -0,0 +1,130 @@
+<?php
+
+namespace Give\Framework\PaymentGateways\Webhooks;
+
+use Give\Donations\ValueObjects\DonationStatus;
+use Give\Framework\PaymentGateways\PaymentGateway;
+use Give\Framework\Support\Facades\ActionScheduler\AsBackgroundJobs;
+use Give\Subscriptions\ValueObjects\SubscriptionStatus;
+
+/**
+ * @unreleased
+ */
+class WebhookEvents
+{
+    /**
+     * @var PaymentGateway
+     */
+    protected $gateway;
+
+    /**
+     * @unreleased
+     */
+    public function __construct(PaymentGateway $gateway)
+    {
+        $this->gateway = $gateway;
+    }
+
+    /**
+     * @unreleased
+     *
+     * @return int The webhook event ID. Zero if there was an error setting the event.
+     */
+    public function setDonationStatus(
+        DonationStatus $status,
+        string $gatewayTransactionId,
+        string $message = '',
+        $skipRecurringDonations = false
+    ): int {
+        $hook = "givewp_{$this->gateway::id()}_webhook_event_donation_{$status->getValue()}";
+        $args = [$gatewayTransactionId, $message, $skipRecurringDonations];
+        $group = $this->getGroup();
+
+        return AsBackgroundJobs::enqueueAsyncAction($hook, $args, $group);
+    }
+
+    /**
+     * @unreleased
+     *
+     * @return int The webhook event ID. Zero if there was an error setting the event.
+     */
+    public function setSubscriptionStatus(
+        SubscriptionStatus $status,
+        string $gatewaySubscriptionId,
+        string $message = '',
+        bool $initialDonationShouldBeCompleted = false
+    ): int {
+        $hook = "givewp_{$this->gateway::id()}_webhook_event_subscription_{$status->getValue()}";
+        $args = [$gatewaySubscriptionId, $message, $initialDonationShouldBeCompleted];
+        $group = $this->getGroup();
+
+        return AsBackgroundJobs::enqueueAsyncAction($hook, $args, $group);
+    }
+
+    /**
+     * @unreleased
+     *
+     * @return int The webhook event ID. Zero if there was an error setting the event.
+     */
+    public function setSubscriptionFirstDonation(
+        string $gatewayTransactionId,
+        string $message = '',
+        bool $setSubscriptionActive = true
+    ): int {
+        $hook = "givewp_{$this->gateway::id()}_webhook_event_subscription_first_donation";
+        $args = [$gatewayTransactionId, $message, $setSubscriptionActive];
+        $group = $this->getGroup();
+
+        return AsBackgroundJobs::enqueueAsyncAction($hook, $args, $group);
+    }
+
+    /**
+     * @unreleased
+     *
+     * @return int The webhook event ID. Zero if there was an error setting the event.
+     */
+    public function setSubscriptionRenewalDonation(
+        string $gatewaySubscriptionId,
+        string $gatewayTransactionId,
+        string $message = ''
+    ): int {
+        $hook = "givewp_{$this->gateway::id()}_webhook_event_subscription_renewal_donation";
+        $args = [$gatewaySubscriptionId, $gatewayTransactionId, $message];
+        $group = $this->getGroup();
+
+        return AsBackgroundJobs::enqueueAsyncAction($hook, $args, $group);
+    }
+
+    /**
+     * @unreleased
+     *
+     * @param string $returnFormat OBJECT, ARRAY_A, or ids.
+     * @param string $status       ActionScheduler_Store::STATUS_COMPLETE, ActionScheduler_Store::STATUS_PENDING, ActionScheduler_Store::STATUS_RUNNING, ActionScheduler_Store::STATUS_FAILED, ActionScheduler_Store::STATUS_CANCELED
+     *
+     * @return array
+     */
+    public function getAll(string $returnFormat = OBJECT, string $status = ''): array
+    {
+        return AsBackgroundJobs::getActionsByGroup($this->getGroup(), $status);
+    }
+
+    /**
+     * @unreleased
+     *
+     * @param string $status ActionScheduler_Store::STATUS_COMPLETE, ActionScheduler_Store::STATUS_PENDING, ActionScheduler_Store::STATUS_RUNNING, ActionScheduler_Store::STATUS_FAILED, ActionScheduler_Store::STATUS_CANCELED
+     *
+     * @return int Total deleted webhook events.
+     */
+    public function deleteAll(string $status = ''): int
+    {
+        return AsBackgroundJobs::deleteActionsByGroup($this->getGroup(), $status);
+    }
+
+    /**
+     * @unreleased
+     */
+    private function getGroup(): string
+    {
+        return 'give-' . $this->gateway::id();
+    }
+}