feat(newsletters): full HTTP layer + engine services (Spring) (#70)

* feat(newsletter): add retry column, permissions seed, and config

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(newsletter): add repositories and engine services

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(newsletter): add HTTP controllers, scheduler, and security

Co-authored-by: Cursor <cursoragent@cursor.com>

* test(newsletter): add engine and public controller coverage

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(newsletter): use Java null-check instead of ?? operator in settings controller

* fix(newsletter): add 1-arg redirect overload + drop setId on preview delivery

* fix(newsletter): add setId to NewsletterDelivery for test construction

* fix(newsletter): repair 4 test-harness issues (WebMvcTest ApiTokenService bean, stateful bounce-store mock, lenient strict-stubbing)

* Push newsletter segment filters to the database via JPA Specifications.

Avoid loading the full contacts table on every dynamic-list resolve, count, or sendable query. Column names remain allowlisted before mapping to entity paths; metadata rules use bounded JSON LIKE predicates.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Matt Gros <mpge@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: mpge

build.gradle.kts

@@ -46,6 +46,7 @@ dependencies {
     annotationProcessor("org.springframework.boot:spring-boot-configuration-processor")
 
     testImplementation("org.springframework.boot:spring-boot-starter-test")
+    testImplementation("org.springframework.boot:spring-boot-starter-data-jpa-test")
     testImplementation("org.springframework.boot:spring-boot-starter-webmvc-test")
     testImplementation("org.springframework.security:spring-security-test")
 }

src/main/java/dev/escalated/config/EscalatedProperties.java

@@ -21,6 +21,7 @@ public class EscalatedProperties {
     private EmailProperties email = new EmailProperties();
     private List<TicketActionProperties> ticketActions = new ArrayList<>();
     private TicketSubjectsProperties ticketSubjects = new TicketSubjectsProperties();
+    private NewslettersProperties newsletters = new NewslettersProperties();
 
     public boolean isEnabled() {
         return enabled;
@@ -126,6 +127,14 @@ public void setTicketSubjects(TicketSubjectsProperties ticketSubjects) {
         this.ticketSubjects = ticketSubjects;
     }
 
+    public NewslettersProperties getNewsletters() {
+        return newsletters;
+    }
+
+    public void setNewsletters(NewslettersProperties newsletters) {
+        this.newsletters = newsletters;
+    }
+
     /**
      * Host-app models a ticket can be *about* (Project, Customer, asset, …).
      * {@code types} is the allowlist the agent/admin API may attach; leave empty
@@ -337,4 +346,143 @@ public void setInboundSecret(String inboundSecret) {
             this.inboundSecret = inboundSecret;
         }
     }
+
+    /** Newsletter broadcast feature (off by default). */
+    public static class NewslettersProperties {
+        private boolean enabled = false;
+        private String appUrl = "http://localhost";
+        private String defaultFrom;
+        private String defaultReplyTo;
+        private String defaultTheme = "default";
+        private int rateLimitPerMinute = 60;
+        private int batchSize = 50;
+        private boolean trackingEnabled = true;
+        private double autoPauseBounceRate = 0.05;
+        private int autoPauseThreshold = 100;
+        private int claimTimeoutMinutes = 10;
+        private String brandAccent = "#2563eb";
+        private String brandLogoUrl;
+        private String brandPhysicalAddress;
+        private String themesDir = "";
+
+        public boolean isEnabled() {
+            return enabled;
+        }
+
+        public void setEnabled(boolean enabled) {
+            this.enabled = enabled;
+        }
+
+        public String getAppUrl() {
+            return appUrl;
+        }
+
+        public void setAppUrl(String appUrl) {
+            this.appUrl = appUrl;
+        }
+
+        public String getDefaultFrom() {
+            return defaultFrom;
+        }
+
+        public void setDefaultFrom(String defaultFrom) {
+            this.defaultFrom = defaultFrom;
+        }
+
+        public String getDefaultReplyTo() {
+            return defaultReplyTo;
+        }
+
+        public void setDefaultReplyTo(String defaultReplyTo) {
+            this.defaultReplyTo = defaultReplyTo;
+        }
+
+        public String getDefaultTheme() {
+            return defaultTheme;
+        }
+
+        public void setDefaultTheme(String defaultTheme) {
+            this.defaultTheme = defaultTheme;
+        }
+
+        public int getRateLimitPerMinute() {
+            return rateLimitPerMinute;
+        }
+
+        public void setRateLimitPerMinute(int rateLimitPerMinute) {
+            this.rateLimitPerMinute = rateLimitPerMinute;
+        }
+
+        public int getBatchSize() {
+            return batchSize;
+        }
+
+        public void setBatchSize(int batchSize) {
+            this.batchSize = batchSize;
+        }
+
+        public boolean isTrackingEnabled() {
+            return trackingEnabled;
+        }
+
+        public void setTrackingEnabled(boolean trackingEnabled) {
+            this.trackingEnabled = trackingEnabled;
+        }
+
+        public double getAutoPauseBounceRate() {
+            return autoPauseBounceRate;
+        }
+
+        public void setAutoPauseBounceRate(double autoPauseBounceRate) {
+            this.autoPauseBounceRate = autoPauseBounceRate;
+        }
+
+        public int getAutoPauseThreshold() {
+            return autoPauseThreshold;
+        }
+
+        public void setAutoPauseThreshold(int autoPauseThreshold) {
+            this.autoPauseThreshold = autoPauseThreshold;
+        }
+
+        public int getClaimTimeoutMinutes() {
+            return claimTimeoutMinutes;
+        }
+
+        public void setClaimTimeoutMinutes(int claimTimeoutMinutes) {
+            this.claimTimeoutMinutes = claimTimeoutMinutes;
+        }
+
+        public String getBrandAccent() {
+            return brandAccent;
+        }
+
+        public void setBrandAccent(String brandAccent) {
+            this.brandAccent = brandAccent;
+        }
+
+        public String getBrandLogoUrl() {
+            return brandLogoUrl;
+        }
+
+        public void setBrandLogoUrl(String brandLogoUrl) {
+            this.brandLogoUrl = brandLogoUrl;
+        }
+
+        public String getBrandPhysicalAddress() {
+            return brandPhysicalAddress;
+        }
+
+        public void setBrandPhysicalAddress(String brandPhysicalAddress) {
+            this.brandPhysicalAddress = brandPhysicalAddress;
+        }
+
+        public String getThemesDir() {
+            return themesDir;
+        }
+
+        public void setThemesDir(String themesDir) {
+            this.themesDir = themesDir;
+        }
+    }
 }

src/main/java/dev/escalated/config/NewsletterConfiguration.java

@@ -0,0 +1,46 @@
+package dev.escalated.config;
+
+import dev.escalated.services.newsletter.NewsletterRenderer;
+import java.nio.file.Path;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.core.io.ResourceLoader;
+
+@Configuration
+@ConditionalOnProperty(prefix = "escalated.newsletters", name = "enabled", havingValue = "true")
+public class NewsletterConfiguration {
+
+    @Bean
+    public NewsletterRenderer newsletterRenderer(
+            EscalatedProperties properties,
+            ResourceLoader resourceLoader,
+            @Value("${spring.application.name:Support}") String appName) {
+        EscalatedProperties.NewslettersProperties newsletters = properties.getNewsletters();
+        NewsletterRenderer.Options opts = new NewsletterRenderer.Options();
+        opts.baseUrl = newsletters.getAppUrl();
+        opts.defaultTheme = newsletters.getDefaultTheme();
+        opts.trackingEnabled = newsletters.isTrackingEnabled();
+        opts.brandAccent = newsletters.getBrandAccent();
+        opts.brandLogoUrl = newsletters.getBrandLogoUrl();
+        opts.brandPhysicalAddress = newsletters.getBrandPhysicalAddress();
+        opts.brandName = appName;
+
+        String configured = newsletters.getThemesDir();
+        if (configured != null && !configured.isBlank()) {
+            opts.themesDir = configured;
+        } else {
+            try {
+                opts.themesDir = Path.of(
+                                resourceLoader
+                                        .getResource("classpath:templates/escalated/newsletter_themes/")
+                                        .getURI())
+                        .toString();
+            } catch (Exception ex) {
+                opts.themesDir = "templates/escalated/newsletter_themes";
+            }
+        }
+        return new NewsletterRenderer(opts);
+    }
+}