io.sphere.client.shop.CustomerService Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of sphere-java-client Show documentation
sphere-java-client
There is a newer version: 0.72.1
package io.sphere.client.shop;

import io.sphere.client.CommandRequest;
import io.sphere.client.FetchRequest;
import io.sphere.client.QueryRequest;
import io.sphere.client.model.VersionedId;
import io.sphere.client.shop.model.Customer;
import io.sphere.client.shop.model.CustomerName;
import io.sphere.client.shop.model.CustomerToken;
import io.sphere.client.shop.model.CustomerUpdate;
import io.sphere.client.exceptions.*;

/** Sphere HTTP API for working with customers in a given project. */
public interface CustomerService {
    /** Finds a customer by id. */
    FetchRequest byId(String id);

    /** Finds a customer by a token value. If the customer is not found, it means the token is invalid or expired. */
    FetchRequest byToken(String token);

    /** Queries all customers.
     *
     * @deprecated since 0.49.0. Use {@link #query()} instead.
     **/
    @Deprecated
    QueryRequest all();

    /** Queries customers. */
    QueryRequest query();

    /** Creates a new customer.
     *
     *  @return A command request which can fail with the following exceptions:
     *  
     *      {@link EmailAlreadyInUseException} if the email is already taken.
     *  */
    CommandRequest signUp(String email, String password, CustomerName name);

    /** Creates a new customer and associates an existing anonymous cart to the customer.
     *
     * 
     * If the customer already had a cart, the given anonymous cart is merged with customer's cart.
     * If no cart existed for the customer, the anonymous cart becomes customer's cart.
     *
     * @param anonymousCartId The id of the anonymous cart that should be merged / associated to the customer. Can't be empty.
     *
     *  @return A command request which can fail with the following exceptions:
     *  

     *      {@link EmailAlreadyInUseException} if the email is already taken.
     *  */
    CommandRequest signUp(String email, String password, CustomerName customerName, String anonymousCartId);

    /** Signs in a customer.
     *
     * @return A command request which can fail with the following exceptions:
     * 
     *     {@link InvalidCredentialsException} if no customer with given credentials exists.
     *  */
    CommandRequest signIn(String email, String password);

    /** Signs in a customer and associates an existing anonymous cart to the customer.
     * 
     * If the customer already had a cart, the given anonymous cart is merged with customer's cart.
     * If no cart existed for the customer, the anonymous cart becomes customer's cart.
     *
     * @param anonymousCartId The id of the anonymous cart that should be merged / associated to the customer. Can't be empty.
     *
     * @return A command request which can fail with the following exceptions:
     * 

     *     {@link InvalidCredentialsException} if no customer with given credentials exists.
     * */
    CommandRequest signIn(String email, String password, String anonymousCartId);
    
    /** Sets a new password for a customer.
     *
     *  @return A command request which can fail with the following exceptions:
     *  
     *      {@link InvalidPasswordException} if the current password is invalid.
     *  */
    CommandRequest changePassword(VersionedId customerId, String currentPassword, String newPassword);

    /** Updates a customer. */
    CommandRequest update(VersionedId customerId, CustomerUpdate customerUpdate);

    /** Sets a new password for a customer.
     *
     * Requires a token that was previously generated using the {@link #createPasswordResetToken(String)} method. */
    CommandRequest resetPassword(VersionedId customerId, String token, String newPassword);

    /** Creates a token used to verify customer's email.
     *
     *  Typically, verification emails are sent as part of the signup process but the decision is when and whether
     *  to verify customer emails is up to you.
     *
     *  
The typical workflow is the following:
     *  

     *    Create an email verification token using this method.
     *    
Send an email containing a link with the token to the customer.
     *    
The link points to a page where the customer has to log in (if not already logged in).
     *    If the customer is successfully logged in, you can call {@link CustomerService#confirmEmail},
     *    passing in current customer's id, version and the token, extracted from the URL.
     *  
     *
     *  See also {@link CustomerService}.
     *
     *  @param ttlMinutes Validity of the token in minutes. The maximum allowed value is 43200 (30 days). */
    CommandRequest createEmailVerificationToken(VersionedId customerId, int ttlMinutes);

    /** Sets {@link Customer#isEmailVerified} to true.
     *
     * Requires a token that was previously generated using the {@link #createEmailVerificationToken} method. */
    CommandRequest confirmEmail(VersionedId customerId, String token);

    /** Creates a password reset token for the customer with the given email.
     * The validity of the token is 10 minutes.
     *
     *  The typical workflow is the following:
     *  

     *    Customer enters his or her email in a password reset form and submits.
     *    
Create a password reset token using this method.
     *    
Send an email containing a link with the token to the customer.
     *    
The link points to a form where the customer can enter a new password. The form should load the customer
     *    using {@link #byToken} and remember customer's id and version in hidden form fields.
     *    If the customer can't be found, the token has expired or is invalid.
     *    
When the customer submits the form with the new password, call {@link CustomerService#resetPassword},
     *    passing in the customer id and version, the new password and the token (the token is extracted from the URL).
     *  
     *
     * @param email Email address for which the token should be created. */
    CommandRequest createPasswordResetToken(String email);

    /**
     * @see io.sphere.client.shop.CustomerService#createPasswordResetToken
     *
     * @param email Email address for which the token should be created.
     * @param ttlMinutes  A hint for the backend how long the token should be valid.
     *                    The actual timeout could be shorter.
     */
    CommandRequest createPasswordResetToken(String email, int ttlMinutes);
}