io.sphere.sdk.customers.Customer Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of sphere-models Show documentation
sphere-models
There is a newer version: 1.0.0-M26
package io.sphere.sdk.customers;

import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import io.sphere.sdk.customergroups.CustomerGroup;
import io.sphere.sdk.customers.commands.CustomerCreatePasswordTokenCommand;
import io.sphere.sdk.customers.commands.CustomerPasswordResetCommand;
import io.sphere.sdk.models.Address;
import io.sphere.sdk.models.Resource;
import io.sphere.sdk.models.Reference;
import io.sphere.sdk.types.Custom;

import javax.annotation.Nullable;
import java.time.LocalDate;
import java.util.List;
import java.util.Optional;

/**
 * A customer is a person purchasing products. Carts, Orders and Reviews can be associated to a customer.
 *
 * A Customer can have {@link io.sphere.sdk.types.Custom custom fields}.
 *
 * Create a customer/sign-up
 *
 * The customer who signs up can have an anonymous cart which can be assigned to the customer.
 * For convenience the {@link io.sphere.sdk.customers.commands.CustomerCreateCommand}
 * does not directly return a customer but an object ({@link CustomerSignInResult}) which has a field "customer" for the {@link Customer}
 * and another field "cart" which can optionally have a cart if in the customer creation the cart id has been used.
 *
 * An example for creating a customer without a cart:
 * {@include.example io.sphere.sdk.customers.commands.CustomerCreateCommandTest#createCustomer()}
 *
 * Example for creating a customer with a cart:
 * {@include.example io.sphere.sdk.customers.commands.CustomerCreateCommandTest#createCustomerWithCart()}
 * Verify the customers email address
 *
 * The customer contains the property {@link Customer#isEmailVerified()}, which is by default false.
 * If the shop is not supposed to use the commercetools platform email authentication and proved the customer email somehow else
 * then a customer can be created with this field set to true: {@link CustomerDraftBuilder#emailVerified(Boolean)}.
 *
 * To verify the customers email address with commercetools platform first an email token needs to be created with {@link io.sphere.sdk.customers.commands.CustomerCreateEmailTokenCommand}.
 * You can specify a certain time frame so that the token gets invalidated at some point.
 * The response contains a token {@link CustomerToken#getValue()} which needs to be sent to the customer.
 * Commercetools platform won't send an email to the customer. The shop must implement this feature.
 * When the customer received the token send he/she needs to submit to the shop and then the shop to the platform with {@link io.sphere.sdk.customers.commands.CustomerVerifyEmailCommand}.
 *
 * Example
 *
 * {@include.example io.sphere.sdk.customers.commands.CustomerCreateEmailTokenCommandTest#execution()}
 *
 * Sign-in a customer
 *
 * Before signing in, a customer might have created an anonymous cart.
 * After signing in with {@link io.sphere.sdk.customers.commands.CustomerSignInCommand}, the content of the anonymous cart should be in the customer's cart.
 * If the customer did not have a cart associated to him, then the anonymous cart becomes the customer's cart.
 * If a customer already had a cart associated to him, then the content of the anonymous cart will be copied to the customer's cart.
 * If a line item in the anonymous cart matches an existing line item in the customer's cart (same product ID and variant ID),
 * then the maximum quantity of both line items is used as the new quantity.
 *
 * For convenience the {@link io.sphere.sdk.customers.commands.CustomerCreateCommand} which contains the customer
 * and the optional cart.
 *
 * Example for a successful sign in:
 * {@include.example io.sphere.sdk.customers.commands.CustomerSignInCommandTest#execution()}
 *
 *  Example for invalid credentials:
 * {@include.example io.sphere.sdk.customers.commands.CustomerSignInCommandTest#executionWithInvalidEmail()}
 *
 * Changing the password of a customer
 * This covers the case that the customer forgot the password or just want to change it.
 *
 * First a password reset token needs to be created with {@link CustomerCreatePasswordTokenCommand} by using the customers email.
 * This token ({@link CustomerToken#getValue()} from the result of {@link CustomerCreatePasswordTokenCommand}) needs to be sent to the customers email address by the shop. Commercetools platform won't send the email.
 * The customer receives the token and can submit it to the shop including the new password. To change then the password in the commercetools platform use {@link CustomerPasswordResetCommand}.
 * The result of the command is the updated customer, so if the customer needs to sign in after the password change the command {@link io.sphere.sdk.customers.commands.CustomerSignInCommand} is required.
 *
 * {@include.example io.sphere.sdk.customers.commands.CustomerPasswordResetCommandTest#execution()}
 *
 * Update customer data
 *
 * See {@link io.sphere.sdk.customers.commands.CustomerUpdateCommand}.
 *
 * Delete a customer entry
 *
 * See {@link io.sphere.sdk.customers.commands.CustomerDeleteCommand}.
 *
 *
 * @see io.sphere.sdk.customers.commands.CustomerChangePasswordCommand
 * @see io.sphere.sdk.customers.commands.CustomerCreateCommand
 * @see io.sphere.sdk.customers.commands.CustomerCreatePasswordTokenCommand
 * @see io.sphere.sdk.customers.commands.CustomerDeleteCommand
 * @see io.sphere.sdk.customers.commands.CustomerPasswordResetCommand
 * @see io.sphere.sdk.customers.commands.CustomerSignInCommand
 * @see io.sphere.sdk.customers.commands.CustomerUpdateCommand
 * @see io.sphere.sdk.customers.commands.CustomerVerifyEmailCommand
 * @see io.sphere.sdk.customers.queries.CustomerByIdGet
 * @see io.sphere.sdk.customers.queries.CustomerByTokenGet
 * @see io.sphere.sdk.customers.queries.CustomerQuery
 */
@JsonDeserialize(as = CustomerImpl.class)
public interface Customer extends Resource, Custom {
    @Nullable
    String getCustomerNumber();

    String getEmail();

    String getFirstName();

    String getLastName();

    String getPassword();

    String getMiddleName();

    String getTitle();

    List getAddresses();

    @Nullable
    String getDefaultShippingAddressId();

    default Optional findDefaultShippingAddress() {
        return getAddresses().stream()
                .filter(address -> address.getId() != null && address.getId().equals(getDefaultShippingAddressId()))
                .findFirst();
    }

    @Nullable
    default Address getDefaultShippingAddress() {
        return findDefaultShippingAddress().orElse(null);
    }

    @Nullable
    String getDefaultBillingAddressId();

    @Nullable
    default Address getDefaultBillingAddress() {
        return findDefaultBillingAddress().orElse(null);
    }

    default Optional findDefaultBillingAddress() {
        final String defaultBillingAddressId = getDefaultBillingAddressId();

        return getAddresses().stream()
                .filter(address -> defaultBillingAddressId != null && address.getId() != null && address.getId().equals(defaultBillingAddressId))
                .findFirst();
    }

    Boolean isEmailVerified();

    @Nullable
    String getExternalId();

    @Nullable
    Reference getCustomerGroup();

    default CustomerName getName() {
        return CustomerName.of(getTitle(), getFirstName(), getMiddleName(), getLastName());
    }

    @Nullable
    String getCompanyName();

    @Nullable
    String getVatId();

    @Nullable
    LocalDate getDateOfBirth();

    @Override
    default Reference toReference() {
        return Reference.of(referenceTypeId(), getId(), this);
    }

    static String resourceTypeId(){
        return "customer";
    }

    static String referenceTypeId(){
        return "customer";
    }

    /**
     *
     * @deprecated use {@link #referenceTypeId()} instead
     * @return referenceTypeId
     */
    @Deprecated
    static String typeId(){
        return "customer";
    }

    static TypeReference typeReference(){
        return new TypeReference() {
            @Override
            public String toString() {
                return "TypeReference";
            }
        };
    }
}