[WIP] introduce newsletter service contract module #9233

app/code/Magento/NewsletterApi/Api/Data/SubscriptionInterface.php

@@ -0,0 +1,106 @@
+<?php
+/**
+ * Copyright © Magento, Inc. All rights reserved.
+ * See COPYING.txt for license details.
+ */
+
+namespace Magento\NewsletterApi\Api\Data;
+
+use Magento\Framework\Api\ExtensibleDataInterface;
+use Magento\NewsletterApi\Api\Data\SubscriptionExtensionInterface;
+use Magento\NewsletterApi\Api\SubscriptionStateInterface;
+
+/**
+ * Newsletter Subscription Interface
+ *
+ * represents one newsletter subscription identified by an
+ * e-mail address or the internal id
+ *
+ * @api
+ */
+interface SubscriptionInterface extends ExtensibleDataInterface
+{
+    /**#@+
+     * Constants for keys of data array. Identical to the name of the getter in snake case
+     */
+    const SUBSCRIPTION_ID = 'subscription_id';
+    const EMAIL = 'email';
+    const STATUS = 'status';
+    /**#@-*/
+
+    /**
+     * Set ID
+     *
+     * set the internal id of the entity
+     *
+     * @param int $id
+     * @return void
+     */
+    public function setId($id);
+
+    /**
+     * Set E-Mail Address
+     *
+     * set the e-mail address of the subscriber
+     *
+     * @param string $email
+     * @return void
+     */
+    public function setEmail($email);
+
+    /**
+     * Set State
+     *
+     * set the state of the subscription
+     *
+     * @param \Magento\NewsletterApi\Api\SubscriptionStateInterface $state
+     *
+     * @return void
+     */
+    public function setState(SubscriptionStateInterface $state);
+
+    /**
+     * Get ID
+     *
+     * get the internal id of the subscription entity
+     *
+     * @return int
+     */
+    public function getId();
+
+    /**
+     * Get E-Mail Address
+     *
+     * get the email address of the subscriber
+     *
+     * @return string
+     */
+    public function getEmail();
+
+    /**
+     * Get State
+     *
+     * get the state of the subscription
+     *
+     * @return \Magento\NewsletterApi\Api\SubscriptionStateInterface
+     */
+    public function getState();
+
+    /**
+     * Get Extension Attributes
+     *
+     * Retrieve existing extension attributes object.
+     * Create a new one if not already initialized
+     *
+     * @return \Magento\NewsletterApi\Api\Data\SubscriptionExtensionInterface
+     */
+    public function getExtensionAttributes();
+
+    /**
+     * Set an extension attributes object.
+     *
+     * @param \Magento\NewsletterApi\Api\Data\SubscriptionExtensionInterface $extensionAttributes
+     * @return void
+     */
+    public function setExtensionAttributes(SubscriptionExtensionInterface $extensionAttributes);
+}

app/code/Magento/NewsletterApi/Api/Data/SubscriptionSearchResultsInterface.php

@@ -0,0 +1,32 @@
+<?php
+/**
+ * Copyright © Magento, Inc. All rights reserved.
+ * See COPYING.txt for license details.
+ */
+
+namespace Magento\NewsletterApi\Api\Data;
+
+use Magento\Framework\Api\SearchResultsInterface;
+
+/**
+ * Interface for newsletter subscription search results.
+ *
+ * @api
+ */
+interface SubscriptionSearchResultsInterface extends SearchResultsInterface
+{
+    /**
+     * Get newsletter subscription list.
+     *
+     * @return \Magento\NewsletterApi\Api\Data\SubscriptionInterface[]
+     */
+    public function getItems();
+
+    /**
+     * Set newsletter subscription list.
+     *
+     * @param \Magento\NewsletterApi\Api\Data\SubscriptionInterface[] $items
+     * @return void
+     */
+    public function setItems(array $items);
+}

app/code/Magento/NewsletterApi/Api/SubscriptionManagementInterface.php

@@ -0,0 +1,89 @@
+<?php
+/**
+ * Copyright © Magento, Inc. All rights reserved.
+ * See COPYING.txt for license details.
+ */
+
+namespace Magento\NewsletterApi\Api;
+
+/**
+ * Newsletter Subscription Management Interface
+ *
+ * @api
+ */
+interface SubscriptionManagementInterface
+{
+    /**
+     * Subscribe
+     *
+     * Adds a new Newsletter Subscription
+     *
+     * @param \Magento\NewsletterApi\Api\Data\SubscriptionInterface $subscription the subscription
+     *
+     * @return bool true on success
+     *
+     * @throws \Magento\Framework\Exception\CouldNotSaveException if an error occurred during subscription
+     * @throws \Magento\Framework\Exception\InputException when an invalid input has been provided
+     */
+    public function subscribe(Data\SubscriptionInterface $subscription);
+
+    /**
+     * unsubscribe
+     *
+     * unsubscribe by given email address
+     *
+     * @param string $email
+     *
+     * @return bool true on success
+     *
+     * @throws \Magento\Framework\Exception\InputException when an invalid input has been provided
+     * @throws \Magento\Framework\Exception\CouldNotDeleteException when an error occurred during unsubscribe
+     * @throws \Magento\Framework\Exception\StateException when entity is in invalid state for deletion
+     */
+    public function unsubscribe($email);
+
+    /**
+     * Subscribe a customer
+     *
+     * Adds a new Newsletter Subscription for the given customer
+     *
+     * @param int $customerId the id of the customer to subscribe
+     * @param \Magento\NewsletterApi\Api\Data\SubscriptionInterface $subscription the subscription
+     *
+     * @return bool true on success
+     *
+     * @throws \Magento\Framework\Exception\CouldNotSaveException if an error occurred during subscription
+     * @throws \Magento\Framework\Exception\InputException when an invalid input has been provided
+     */
+    public function subscribeCustomer($customerId, Data\SubscriptionInterface $subscription);
+
+    /**
+     * Get Subscription for given Customer
+     *
+     * retrieves the subscription entity for the given customer id
+     *
+     * @param int $customerId the id of the customer
+     *
+     * @return \Magento\NewsletterApi\Api\Data\SubscriptionInterface $subscription
+     *
+     * @throws \Magento\Framework\Exception\NoSuchEntityException when subscription does not exist
+     * @throws \Magento\Framework\Exception\InputException when an invalid input has been provided
+     */
+    public function getSubscriptionForCustomer($customerId);
+
+    /**
+     * unsubscribe customer
+     *
+     * remove the subscription entity linked to the given customer
+     * from the underlying persistence layer
+     *
+     * @param int $customerId the id of the customer to unsubscribe
+     *
+     * @return bool true on success
+     *
+     * @throws \Magento\Framework\Exception\InputException when an invalid input has been provided
+     * @throws \Magento\Framework\Exception\CouldNotDeleteException when an error occurred during unsubscribe
+     * @throws \Magento\Framework\Exception\StateException when entity is in invalid state for deletion
+     */
+    public function unsubscribeCustomer($customerId);
+}

app/code/Magento/NewsletterApi/Api/SubscriptionRepositoryInterface.php

@@ -0,0 +1,98 @@
+<?php
+/**
+ * Copyright © Magento, Inc. All rights reserved.
+ * See COPYING.txt for license details.
+ */
+
+namespace Magento\NewsletterApi\Api;
+
+use Magento\Framework\Api\SearchCriteriaInterface;
+use Magento\NewsletterApi\Api\Data\SubscriptionInterface;
+
+/**
+ * Newsletter Subscription CRUD interface.
+ *
+ * interface to handle newsletter subscription entities internally
+ *
+ * @api
+ */
+interface SubscriptionRepositoryInterface
+{
+    /**
+     * Save newsletter subscription.
+     *
+     * Persists a newsletter subscription entity and returns
+     * the internal id of the created object
+     *
+     * @param \Magento\NewsletterApi\Api\Data\SubscriptionInterface $subscription subscription entity to be saved
+     *
+     * @return int the id of the newly created object
+     *
+     * @throws \Magento\Framework\Exception\CouldNotSaveException when an error occurred while persisting the entity
+     * @throws \Magento\Framework\Exception\InputException when an invalid input has been provided
+     * @throws \Magento\Framework\Exception\AlreadyExistsException if the subscription already exists
+     */
+    public function save(SubscriptionInterface $subscription);
+
+    /**
+     * Retrieve newsletter subscription.
+     *
+     * retrieve a subscription entity from the persistence layer
+     * by providing the internal id of the entity
+     *
+     * @param int $subscriptionId the internal id of the entity
+     *
+     * @return \Magento\NewsletterApi\Api\Data\SubscriptionInterface the entity with the given id
+     *
+     * @throws \Magento\Framework\Exception\NoSuchEntityException if no entity with this id exists
+     * @throws \Magento\Framework\Exception\InputException if an invalid id was provided
+     */
+    public function getById($subscriptionId);
+
+    /**
+     * Retrieve newsletter subscription list
+     *
+     * get a list object containing subscription entities by specifying
+     * search criteria
+     *
+     * @param \Magento\Framework\Api\SearchCriteriaInterface $searchCriteria containing the search criteria for the list
+     *
+     * @return \Magento\NewsletterApi\Api\Data\SubscriptionSearchResultsInterface list containing the search result
+     *
+     * @throws \Magento\Framework\Exception\InputException if invalid search criteria have been provided
+     * @throws \Magento\Framework\Exception\NotFoundException if no object matched the given criteria
+     */
+    public function getList(SearchCriteriaInterface $searchCriteria);
+
+    /**
+     * Delete newsletter subscription.
+     *
+     * delete a subscription entity from the underlying persistence
+     * layer by providing the entity to delete
+     *
+     * @param \Magento\NewsletterApi\Api\Data\SubscriptionInterface $subscription the entity to be deleted
+     *
+     * @return bool true on success
+     *
+     * @throws \Magento\Framework\Exception\StateException when the entity is in an invalid state for deletion
+     * @throws \Magento\Framework\Exception\NoSuchEntityException when the entity does not exist
+     * @throws \Magento\Framework\Exception\CouldNotDeleteException when an error occurred during deletion
+     */
+    public function delete(SubscriptionInterface $subscription);
+
+    /**
+     * Delete newsletter subscription by ID.
+     *
+     * delete a subscription entity from the underlying persistence
+     * layer by providing the internal id of the entity to delete
+     *
+     * @param int $subscriptionId id of the entity to be deleted
+     *
+     * @return bool true on success
+     *
+     * @throws \Magento\Framework\Exception\StateException when the entity is in an invalid state for deletion
+     * @throws \Magento\Framework\Exception\NoSuchEntityException when an entity with given id does not exist
+     * @throws \Magento\Framework\Exception\CouldNotDeleteException when an error occurred during deletion
+     */
+    public function deleteById($subscriptionId);
+}