Feature: Messaging tiers with eligibility checks and admin approval workflow (#986)

Author: daveearley

backend/app/DomainObjects/AccountDomainObject.php

@@ -15,6 +15,8 @@ class AccountDomainObject extends Generated\AccountDomainObjectAbstract
 
     private ?AccountVatSettingDomainObject $accountVatSetting = null;
 
+    private ?AccountMessagingTierDomainObject $messagingTier = null;
+
     public function getApplicationFee(): AccountApplicationFeeDTO
     {
         /** @var AccountConfigurationDomainObject $applicationFee */
@@ -56,6 +58,16 @@ public function setAccountVatSetting(AccountVatSettingDomainObject $accountVatSe
         $this->accountVatSetting = $accountVatSetting;
     }
 
+    public function getMessagingTier(): ?AccountMessagingTierDomainObject
+    {
+        return $this->messagingTier;
+    }
+
+    public function setMessagingTier(AccountMessagingTierDomainObject $messagingTier): void
+    {
+        $this->messagingTier = $messagingTier;
+    }
+
     /**
      * Get the primary active Stripe platform for this account
      * Returns the platform with setup completed, preferring the most recent

backend/app/DomainObjects/AccountMessagingTierDomainObject.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace HiEvents\DomainObjects;
+
+class AccountMessagingTierDomainObject extends Generated\AccountMessagingTierDomainObjectAbstract
+{
+}

backend/app/DomainObjects/Enums/MessagingEligibilityFailureEnum.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace HiEvents\DomainObjects\Enums;
+
+enum MessagingEligibilityFailureEnum: string
+{
+    case STRIPE_NOT_CONNECTED = 'stripe_not_connected';
+    case NO_PAID_ORDERS = 'no_paid_orders';
+    case EVENT_TOO_NEW = 'event_too_new';
+}

backend/app/DomainObjects/Enums/MessagingTierViolationEnum.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace HiEvents\DomainObjects\Enums;
+
+enum MessagingTierViolationEnum: string
+{
+    case MESSAGE_LIMIT_EXCEEDED = 'message_limit_exceeded';
+    case RECIPIENT_LIMIT_EXCEEDED = 'recipient_limit_exceeded';
+    case LINKS_NOT_ALLOWED = 'links_not_allowed';
+
+    public function getMessage(): string
+    {
+        return match ($this) {
+            self::MESSAGE_LIMIT_EXCEEDED => __('You have reached your daily message limit. Please try again later or contact support to increase your limits.'),
+            self::RECIPIENT_LIMIT_EXCEEDED => __('The number of recipients exceeds your account limit. Please contact support to increase your limits.'),
+            self::LINKS_NOT_ALLOWED => __('Your account tier does not allow links in messages. Please contact support to enable this feature.'),
+        };
+    }
+}

backend/app/DomainObjects/Generated/AccountDomainObjectAbstract.php

@@ -12,6 +12,7 @@ abstract class AccountDomainObjectAbstract extends \HiEvents\DomainObjects\Abstr
     final public const PLURAL_NAME = 'accounts';
     final public const ID = 'id';
     final public const ACCOUNT_CONFIGURATION_ID = 'account_configuration_id';
+    final public const ACCOUNT_MESSAGING_TIER_ID = 'account_messaging_tier_id';
     final public const CURRENCY_CODE = 'currency_code';
     final public const TIMEZONE = 'timezone';
     final public const CREATED_AT = 'created_at';
@@ -29,6 +30,7 @@ abstract class AccountDomainObjectAbstract extends \HiEvents\DomainObjects\Abstr
 
     protected int $id;
     protected ?int $account_configuration_id = null;
+    protected ?int $account_messaging_tier_id = null;
     protected string $currency_code = 'USD';
     protected ?string $timezone = null;
     protected ?string $created_at = null;
@@ -49,6 +51,7 @@ public function toArray(): array
         return [
                     'id' => $this->id ?? null,
                     'account_configuration_id' => $this->account_configuration_id ?? null,
+                    'account_messaging_tier_id' => $this->account_messaging_tier_id ?? null,
                     'currency_code' => $this->currency_code ?? null,
                     'timezone' => $this->timezone ?? null,
                     'created_at' => $this->created_at ?? null,
@@ -88,6 +91,17 @@ public function getAccountConfigurationId(): ?int
         return $this->account_configuration_id;
     }
 
+    public function setAccountMessagingTierId(?int $account_messaging_tier_id): self
+    {
+        $this->account_messaging_tier_id = $account_messaging_tier_id;
+        return $this;
+    }
+
+    public function getAccountMessagingTierId(): ?int
+    {
+        return $this->account_messaging_tier_id;
+    }
+
     public function setCurrencyCode(string $currency_code): self
     {
         $this->currency_code = $currency_code;

backend/app/DomainObjects/Generated/AccountMessagingTierDomainObjectAbstract.php

@@ -0,0 +1,132 @@
+<?php
+
+namespace HiEvents\DomainObjects\Generated;
+
+/**
+ * THIS FILE IS AUTOGENERATED - DO NOT EDIT IT DIRECTLY.
+ * @package HiEvents\DomainObjects\Generated
+ */
+abstract class AccountMessagingTierDomainObjectAbstract extends \HiEvents\DomainObjects\AbstractDomainObject
+{
+    final public const SINGULAR_NAME = 'account_messaging_tier';
+    final public const PLURAL_NAME = 'account_messaging_tiers';
+    final public const ID = 'id';
+    final public const NAME = 'name';
+    final public const MAX_MESSAGES_PER_24H = 'max_messages_per_24h';
+    final public const MAX_RECIPIENTS_PER_MESSAGE = 'max_recipients_per_message';
+    final public const LINKS_ALLOWED = 'links_allowed';
+    final public const CREATED_AT = 'created_at';
+    final public const UPDATED_AT = 'updated_at';
+    final public const DELETED_AT = 'deleted_at';
+
+    protected int $id;
+    protected string $name;
+    protected int $max_messages_per_24h;
+    protected int $max_recipients_per_message;
+    protected bool $links_allowed = false;
+    protected ?string $created_at = null;
+    protected ?string $updated_at = null;
+    protected ?string $deleted_at = null;
+
+    public function toArray(): array
+    {
+        return [
+                    'id' => $this->id ?? null,
+                    'name' => $this->name ?? null,
+                    'max_messages_per_24h' => $this->max_messages_per_24h ?? null,
+                    'max_recipients_per_message' => $this->max_recipients_per_message ?? null,
+                    'links_allowed' => $this->links_allowed ?? null,
+                    'created_at' => $this->created_at ?? null,
+                    'updated_at' => $this->updated_at ?? null,
+                    'deleted_at' => $this->deleted_at ?? null,
+                ];
+    }
+
+    public function setId(int $id): self
+    {
+        $this->id = $id;
+        return $this;
+    }
+
+    public function getId(): int
+    {
+        return $this->id;
+    }
+
+    public function setName(string $name): self
+    {
+        $this->name = $name;
+        return $this;
+    }
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    public function setMaxMessagesPer24h(int $max_messages_per_24h): self
+    {
+        $this->max_messages_per_24h = $max_messages_per_24h;
+        return $this;
+    }
+
+    public function getMaxMessagesPer24h(): int
+    {
+        return $this->max_messages_per_24h;
+    }
+
+    public function setMaxRecipientsPerMessage(int $max_recipients_per_message): self
+    {
+        $this->max_recipients_per_message = $max_recipients_per_message;
+        return $this;
+    }
+
+    public function getMaxRecipientsPerMessage(): int
+    {
+        return $this->max_recipients_per_message;
+    }
+
+    public function setLinksAllowed(bool $links_allowed): self
+    {
+        $this->links_allowed = $links_allowed;
+        return $this;
+    }
+
+    public function getLinksAllowed(): bool
+    {
+        return $this->links_allowed;
+    }
+
+    public function setCreatedAt(?string $created_at): self
+    {
+        $this->created_at = $created_at;
+        return $this;
+    }
+
+    public function getCreatedAt(): ?string
+    {
+        return $this->created_at;
+    }
+
+    public function setUpdatedAt(?string $updated_at): self
+    {
+        $this->updated_at = $updated_at;
+        return $this;
+    }
+
+    public function getUpdatedAt(): ?string
+    {
+        return $this->updated_at;
+    }
+
+    public function setDeletedAt(?string $deleted_at): self
+    {
+        $this->deleted_at = $deleted_at;
+        return $this;
+    }
+
+    public function getDeletedAt(): ?string
+    {
+        return $this->deleted_at;
+    }
+}

backend/app/DomainObjects/Generated/MessageDomainObjectAbstract.php

@@ -26,6 +26,7 @@ abstract class MessageDomainObjectAbstract extends \HiEvents\DomainObjects\Abstr
     final public const CREATED_AT = 'created_at';
     final public const UPDATED_AT = 'updated_at';
     final public const DELETED_AT = 'deleted_at';
+    final public const ELIGIBILITY_FAILURES = 'eligibility_failures';
 
     protected int $id;
     protected int $event_id;
@@ -43,6 +44,7 @@ abstract class MessageDomainObjectAbstract extends \HiEvents\DomainObjects\Abstr
     protected string $created_at;
     protected ?string $updated_at = null;
     protected ?string $deleted_at = null;
+    protected array|string|null $eligibility_failures = null;
 
     public function toArray(): array
     {
@@ -63,6 +65,7 @@ public function toArray(): array
                     'created_at' => $this->created_at ?? null,
                     'updated_at' => $this->updated_at ?? null,
                     'deleted_at' => $this->deleted_at ?? null,
+                    'eligibility_failures' => $this->eligibility_failures ?? null,
                 ];
     }
 
@@ -241,4 +244,15 @@ public function getDeletedAt(): ?string
     {
         return $this->deleted_at;
     }
+
+    public function setEligibilityFailures(array|string|null $eligibility_failures): self
+    {
+        $this->eligibility_failures = $eligibility_failures;
+        return $this;
+    }
+
+    public function getEligibilityFailures(): array|string|null
+    {
+        return $this->eligibility_failures;
+    }
 }

backend/app/DomainObjects/Status/MessageStatus.php

@@ -8,6 +8,7 @@ enum MessageStatus
 {
     use BaseEnum;
 
+    case PENDING_REVIEW;
     case PROCESSING;
     case SENT;
     case FAILED;

backend/app/Exceptions/MessagingTierLimitExceededException.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace HiEvents\Exceptions;
+
+use Exception;
+use HiEvents\Services\Domain\Message\DTO\MessagingTierViolationDTO;
+
+class MessagingTierLimitExceededException extends Exception
+{
+    public function __construct(
+        private readonly MessagingTierViolationDTO $violation,
+        int $code = 429,
+        ?Exception $previous = null
+    ) {
+        parent::__construct($this->violation->getFirstViolationMessage(), $code, $previous);
+    }
+
+    public function getViolation(): MessagingTierViolationDTO
+    {
+        return $this->violation;
+    }
+}

backend/app/Http/Actions/Admin/Accounts/UpdateAccountMessagingTierAction.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace HiEvents\Http\Actions\Admin\Accounts;
+
+use HiEvents\DomainObjects\Enums\Role;
+use HiEvents\Http\Actions\BaseAction;
+use HiEvents\Resources\Account\AdminAccountDetailResource;
+use HiEvents\Services\Application\Handlers\Admin\GetAccountHandler;
+use HiEvents\Services\Application\Handlers\Admin\UpdateAccountMessagingTierHandler;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+class UpdateAccountMessagingTierAction extends BaseAction
+{
+    public function __construct(
+        private readonly UpdateAccountMessagingTierHandler $handler,
+        private readonly GetAccountHandler $getAccountHandler,
+    ) {
+    }
+
+    public function __invoke(Request $request, int $accountId): JsonResponse
+    {
+        $this->minimumAllowedRole(Role::SUPERADMIN);
+
+        $validated = $request->validate([
+            'messaging_tier_id' => 'required|integer|exists:account_messaging_tiers,id',
+        ]);
+
+        $this->handler->handle($accountId, $validated['messaging_tier_id']);
+
+        $account = $this->getAccountHandler->handle($accountId);
+
+        return $this->jsonResponse(new AdminAccountDetailResource($account), wrapInData: true);
+    }
+}