Create a basic mailchimp client

.gitignore

@@ -1,6 +1,10 @@
-# Compiled class file
+target
 *.class
 
+# intellij
+*.iml
+.idea
+
 # Log file
 *.log
 
@@ -20,3 +24,4 @@
 
 # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
 hs_err_pid*
+

README.md

@@ -1 +1,8 @@
-# mailing-list-client
+[`mailing-list-client`](mailing-list-client/README.md) - This project
+provides an API for integrating with a mailing list service. It provides
+an implementation of the API for Mailchimp.
+
+[`mailchimp-webhooks`](mailchimp-webhooks/README.md) - This project
+provides an small example Spring Boot client that can listen to webhooks
+from Mailchimp that register user details changing in Mailchimp.
+

mailchimp-webhooks/README.md

@@ -0,0 +1,16 @@
+## Mailchimp Webhook Service
+
+A proof of concept Spring Boot service used create a simple webhook
+service for MailChimp. Currently accepts only "changed email" hooks.
+
+On recieving a webhook, it will write the `data[old_email]` and the
+`data[new_url]` to the logs.
+
+### Configuration
+
+Requires `${mailing.webhook.key}` to be set in the Spring
+`application.properties`, [providing some security to the
+application](https://developer.mailchimp.com/documentation/mailchimp/guides/about-webhooks/#securing-webhooks).
+
+The URL for the webhook will then be `${base.uri}/${mailing.webhook.key}`.
+

mailchimp-webhooks/pom.xml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>uk.ac.stfc.facilities</groupId>
+    <artifactId>mailing</artifactId>
+    <version>0.0.1-SNAPSHOT</version>
+
+    <parent>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-parent</artifactId>
+        <version>1.5.4.RELEASE</version>
+    </parent>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.apache.logging.log4j</groupId>
+            <artifactId>log4j-api</artifactId>
+            <version>2.8.2</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.logging.log4j</groupId>
+            <artifactId>log4j-core</artifactId>
+            <version>2.8.2</version>
+        </dependency>
+
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+</project>

mailchimp-webhooks/src/main/java/uk/ac/stfc/facilities/mailing/spring/Application.java

@@ -0,0 +1,12 @@
+package uk.ac.stfc.facilities.mailing.spring;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication
+public class Application {
+
+    public static void main(String[] args) {
+        SpringApplication.run(Application.class, args);
+    }
+}

mailchimp-webhooks/src/main/java/uk/ac/stfc/facilities/mailing/spring/MailchimpWebhookController.java

@@ -0,0 +1,43 @@
+package uk.ac.stfc.facilities.mailing.spring;
+
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+import org.springframework.stereotype.Controller;
+import org.springframework.web.bind.annotation.*;
+
+/**
+ * A Spring controller that listens to webhooks from Mailchimp, it
+ * currently handles the webhook handshake and updates to the users
+ * email. It refers to the <code>mailing.webhook.key</code> key in
+ * config to create the mapping.
+ */
+@Controller
+@RequestMapping("/${mailing.webhook.key}")
+public class MailchimpWebhookController {
+
+    private static final Logger LOGGER = LogManager.getLogger();
+
+    /**
+     * A simple method to respond with a successful status which is
+     * required for Mailchimp to accept a webhook client.
+     */
+    @GetMapping
+    @ResponseStatus(value = HttpStatus.OK)
+    public void handshake() {
+    }
+
+    /**
+     * A webhook that listens to changes to a user&apos;s email
+     * address change.
+     * @param oldEmail the old email for the user
+     * @param newEmail the new email for the user
+     */
+    @PostMapping
+    @ResponseBody
+    public void hook(
+            @RequestParam("data[old_email]") String oldEmail,
+            @RequestParam("data[new_email]") String newEmail
+    ) {
+        LOGGER.info("old: " + oldEmail + " to " + newEmail);
+    }
+}

mailchimp-webhooks/src/main/resources/application.properties

@@ -0,0 +1,5 @@
+# The mailing.key is used to create a more secure webhook URL, see:
+# https://developer.mailchimp.com/documentation/mailchimp/guides/about-webhooks/#securing-webhooks
+# This will mean the Webhook URL will look like "${base.uri}/${mailing.key}"
+mailing.webhook.key=
+

mailing-list-client/README.md

@@ -0,0 +1,31 @@
+## `mailing-list-api`
+
+Contains an API for connecting to mailing lists -
+`uk.ac.stfc.facilities.mailing.api`.
+
+Contains an implementation of the mailing lists API for Mailchimp -
+`uk.ac.stfc.facilities.mailing.mailchimp`
+
+### Using the `MailchimpClient`
+
+1. Create an instance of the `MailchimpClientConfiguration`, with the API key
+given as an argument to the constructor.
+```java
+MailchimpClientConfiguration config = new MailchimpClientConfiguration(API_KEY);
+```
+2. Get a new instance of the `MailchimpClient` using the factory method. This
+takes the configuration in as an argument.
+```java
+MailingListClient client = MailchimpClient.getInstance(config);
+```
+
+The client is now ready to use.
+
+### Running the integration tests for the `MailchimpClient`.
+
+An [`applications.test.properties`](mailing-list-api/application.test.properties)
+file must exist for the mailchimp client.
+
+**NB:** please ensure these tests are ran against an account with no
+billing information attatched to it.
+

mailing-list-client/application.test.properties

@@ -0,0 +1,17 @@
+# The API key for the Mailchimp. This can be found at:
+# https://admin.mailchimp.com/account/api/
+mailchimp.api.key=
+
+# The ID of an existing list in Mailchimp e.g. abcde1234
+mailchimp.list.id=
+# The name of the existing list in Mailchimp e.g. My Mailing List
+mailchimp.list.name=
+
+# The test domain that users belong to e.g. test.your-domain.com
+# This cannot be a domain like example.com because Mailchimp checks
+# for fake looking emails. Three emails should be added to the
+# existing mailing list with the following statuses:
+#  - permanent.test.1@<mailchimp.test.domain> - subscribed
+#  - permanent.test.2@<mailchimp.test.domain> - subscribed
+#  - permanent.test.3@<mailchimp.test.domain> - subscribed
+mailchimp.test.domain=

mailing-list-client/pom.xml

@@ -0,0 +1,87 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>uk.ac.stfc.facilities</groupId>
+    <artifactId>mailing-list-client</artifactId>
+    <version>0.0.1-SNAPSHOT</version>
+
+    <properties>
+        <java.version>1.8</java.version>
+        <maven.compiler.source>1.8</maven.compiler.source>
+        <maven.compiler.target>1.8</maven.compiler.target>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.httpcomponents</groupId>
+            <artifactId>httpclient</artifactId>
+            <version>4.5.3</version>
+        </dependency>
+        <dependency>
+            <groupId>com.google.code.gson</groupId>
+            <artifactId>gson</artifactId>
+            <version>2.6.2</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.logging.log4j</groupId>
+            <artifactId>log4j-core</artifactId>
+            <version>2.8.2</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.logging.log4j</groupId>
+            <artifactId>log4j-api</artifactId>
+            <version>2.8.2</version>
+        </dependency>
+
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-api</artifactId>
+            <version>5.0.0-RC2</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-params</artifactId>
+            <version>5.0.0-RC2</version>
+            <scope>test</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <version>3.8.0</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <version>2.8.47</version>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <version>2.19.1</version>
+                <dependencies>
+                    <dependency>
+                        <groupId>org.junit.platform</groupId>
+                        <artifactId>junit-platform-surefire-provider</artifactId>
+                        <version>1.0.0-RC2</version>
+                    </dependency>
+                    <dependency>
+                        <groupId>org.junit.jupiter</groupId>
+                        <artifactId>junit-jupiter-engine</artifactId>
+                        <version>5.0.0-RC2</version>
+                    </dependency>
+                </dependencies>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>