feat: add the visit endpoint (#75)

Author: xd-o-bx

README.md

@@ -259,6 +259,12 @@ Official Documentation: [VisitorActivities](http://developer.pardot.com/kb/api-v
 - Query
 - Read
 
+### Visits
+Official Documentation: [Visits](https://developer.pardot.com/kb/api-version-3/visits/)
+
+- Query
+- Read
+
 ## How to Contribute 
 
 Want to help implement the missing API end points?  Fork the repository, write some code, and 

src/main/java/com/darksci/pardot/api/PardotClient.java

@@ -58,6 +58,8 @@
 import com.darksci.pardot.api.parser.user.UserCreateResponseParser;
 import com.darksci.pardot.api.parser.user.UserQueryResponseParser;
 import com.darksci.pardot.api.parser.user.UserReadResponseParser;
+import com.darksci.pardot.api.parser.visit.VisitQueryResponseParser;
+import com.darksci.pardot.api.parser.visit.VisitReadResponseParser;
 import com.darksci.pardot.api.parser.visitor.VisitorQueryResponseParser;
 import com.darksci.pardot.api.parser.visitor.VisitorReadResponseParser;
 import com.darksci.pardot.api.parser.visitoractivity.VisitorActivityQueryResponseParser;
@@ -127,6 +129,8 @@
 import com.darksci.pardot.api.request.user.UserQueryRequest;
 import com.darksci.pardot.api.request.user.UserReadRequest;
 import com.darksci.pardot.api.request.user.UserUpdateRoleRequest;
+import com.darksci.pardot.api.request.visit.VisitQueryRequest;
+import com.darksci.pardot.api.request.visit.VisitReadRequest;
 import com.darksci.pardot.api.request.visitor.VisitorAssignRequest;
 import com.darksci.pardot.api.request.visitor.VisitorQueryRequest;
 import com.darksci.pardot.api.request.visitor.VisitorReadRequest;
@@ -170,6 +174,8 @@
 import com.darksci.pardot.api.response.user.User;
 import com.darksci.pardot.api.response.user.UserAbilitiesResponse;
 import com.darksci.pardot.api.response.user.UserQueryResponse;
+import com.darksci.pardot.api.response.visit.Visit;
+import com.darksci.pardot.api.response.visit.VisitQueryResponse;
 import com.darksci.pardot.api.response.visitor.Visitor;
 import com.darksci.pardot.api.response.visitor.VisitorQueryResponse;
 import com.darksci.pardot.api.response.visitoractivity.VisitorActivity;
@@ -1127,6 +1133,28 @@ public Optional<VisitorActivity> visitorActivityRead(final VisitorActivityReadRe
         );
     }
 
+    /**
+     * Make API request to query visits.
+     * @param request Request definition.
+     * @return Parsed api response.
+     */
+    public VisitQueryResponse.Result visitQuery(final VisitQueryRequest request) {
+        return submitRequest(request, new VisitQueryResponseParser())
+                .orElseThrowInvalidRequestException();
+    }
+
+    /**
+     * Make API request to read a visit.
+     * @param request Request definition.
+     * @return Parsed api response
+     */
+    public Optional<Visit> visitRead(final VisitReadRequest request) {
+        return optionalUnlessErrorCode(
+                submitRequest(request, new VisitReadResponseParser()),
+                ErrorCode.INVALID_ID, ErrorCode.INVALID_VISIT_ID
+        );
+    }
+
     /**
      * Entry point for adhoc user defined requests.
      *

src/main/java/com/darksci/pardot/api/parser/visit/VisitQueryResponseParser.java

@@ -0,0 +1,35 @@
+/**
+ * Copyright 2017, 2018, 2019, 2020 Stephen Powis https://github.com/Crim/pardot-java-client
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+ * persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package com.darksci.pardot.api.parser.visit;
+
+import com.darksci.pardot.api.parser.JacksonFactory;
+import com.darksci.pardot.api.parser.ResponseParser;
+import com.darksci.pardot.api.response.visit.VisitQueryResponse;
+
+import java.io.IOException;
+
+/**
+ * Handles parsing Visit Query API responses into POJOs.
+ */
+public class VisitQueryResponseParser implements ResponseParser<VisitQueryResponse.Result> {
+
+    @Override
+    public VisitQueryResponse.Result parseResponse(final String responseStr) throws IOException {
+        return JacksonFactory.newInstance().readValue(responseStr, VisitQueryResponse.class).getResult();
+    }
+}

src/main/java/com/darksci/pardot/api/parser/visit/VisitReadResponseParser.java

@@ -0,0 +1,36 @@
+/**
+ * Copyright 2017, 2018, 2019, 2020 Stephen Powis https://github.com/Crim/pardot-java-client
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+ * persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package com.darksci.pardot.api.parser.visit;
+
+import com.darksci.pardot.api.parser.JacksonFactory;
+import com.darksci.pardot.api.parser.ResponseParser;
+import com.darksci.pardot.api.response.visit.Visit;
+import com.darksci.pardot.api.response.visit.VisitReadResponse;
+
+import java.io.IOException;
+
+/**
+ * Handles parsing Visit Read API responses into POJOs.
+ */
+public class VisitReadResponseParser implements ResponseParser<Visit> {
+
+    @Override
+    public Visit parseResponse(final String responseStr) throws IOException {
+        return JacksonFactory.newInstance().readValue(responseStr, VisitReadResponse.class).getVisit();
+    }
+}

src/main/java/com/darksci/pardot/api/request/visit/VisitQueryRequest.java

@@ -0,0 +1,91 @@
+/**
+ * Copyright 2017, 2018, 2019, 2020 Stephen Powis https://github.com/Crim/pardot-java-client
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+ * persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package com.darksci.pardot.api.request.visit;
+
+import com.darksci.pardot.api.request.BaseQueryRequest;
+
+import java.util.Collection;
+
+/**
+ * Defines a Visit Query Request.
+ */
+public class VisitQueryRequest extends BaseQueryRequest<VisitQueryRequest> {
+
+    @Override
+    public String getApiEndpoint() {
+        return "visit/do/query";
+    }
+
+    // Filter Options
+
+    /**
+     * Only select visits who are associated with the specified visit id.
+     * @param id The visit id to filter by.
+     * @return RequestBuilder
+     */
+    public VisitQueryRequest withId(final Long id) {
+        return withCollectionParam("ids", id);
+    }
+
+    /**
+     * Only select visits who are associated with the specified visit ids.
+     * @param ids The visit ids to filter by.
+     * @return RequestBuilder
+     */
+    public VisitQueryRequest withIds(final Collection<Long> ids) {
+        return withCollectionParams("ids", ids);
+    }
+
+    /**
+     * Only select visits who are associated with the specified visitor id.
+     * @param visitorId The visitor id to filter by.
+     * @return RequestBuilder
+     */
+    public VisitQueryRequest withVisitorId(final Long visitorId) {
+        return withCollectionParam("visitor_ids", visitorId);
+    }
+
+    /**
+     * Only select visits who are associated with the specified visitor ids.
+     * @param visitorIds The visitor ids to filter by.
+     * @return RequestBuilder
+     */
+    public VisitQueryRequest withVisitorIds(final Collection<Long> visitorIds) {
+        return withCollectionParams("visitor_ids", visitorIds);
+    }
+
+    /**
+     * Only select visits who are associated with the specified prospect id.
+     * @param prospectId The prospect id to filter by.
+     * @return RequestBuilder
+     */
+    public VisitQueryRequest withProspectId(final Long prospectId) {
+        return withCollectionParam("prospect_ids", prospectId);
+    }
+
+    /**
+     * Only select visits who are associated with the specified prospect ids.
+     * @param prospectIds The prospect ids to filter by.
+     * @return RequestBuilder
+     */
+    public VisitQueryRequest withProspectIds(final Collection<Long> prospectIds) {
+        return withCollectionParams("prospect_ids", prospectIds);
+    }
+
+
+}

src/main/java/com/darksci/pardot/api/request/visit/VisitReadRequest.java

@@ -0,0 +1,40 @@
+/**
+ * Copyright 2017, 2018, 2019, 2020 Stephen Powis https://github.com/Crim/pardot-java-client
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+ * persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package com.darksci.pardot.api.request.visit;
+
+import com.darksci.pardot.api.request.BaseRequest;
+
+/**
+ * Used to generate a Visit read request.
+ */
+public class VisitReadRequest extends BaseRequest<VisitReadRequest> {
+
+    @Override
+    public String getApiEndpoint() {
+        return "visit/do/read";
+    }
+
+    /**
+     * Returns the data for the visit specified by id.
+     * @param id The Id of the target visit.
+     * @return VisitReadRequest builder.
+     */
+    public VisitReadRequest selectById(final Long id) {
+        return setParam("id", id);
+    }
+}

src/main/java/com/darksci/pardot/api/response/ErrorCode.java

@@ -37,6 +37,7 @@ public enum ErrorCode {
     INVALID_VISITOR_ID(24),
     INVALID_OPPORTUNITY_ID(35),
     INVALID_CAMPAIGN_ID(38),
+    INVALID_VISIT_ID(48),
     EMAIL_ADDRESS_IS_ALREADY_IN_USE(54),
     INVALID_LIST_ID(55),
     INVALID_EMAIL_FORMAT(65),

src/main/java/com/darksci/pardot/api/response/visit/Visit.java

@@ -0,0 +1,112 @@
+/**
+ * Copyright 2017, 2018, 2019, 2020 Stephen Powis https://github.com/Crim/pardot-java-client
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+ * persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package com.darksci.pardot.api.response.visit;
+
+import com.fasterxml.jackson.annotation.JsonFormat;
+import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlElementWrapper;
+import org.joda.time.LocalDateTime;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Represents a Pardot visit.
+ */
+public class Visit {
+    private Long id;
+    private Long visitorId;
+    private Long prospectId;
+    private Integer visitorPageViewCount;
+    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+    private LocalDateTime firstVisitorPageViewAt;
+    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+    private LocalDateTime lastVisitorPageViewAt;
+    private Integer durationInSeconds;
+    private String campaignParameter;
+    private String mediumParameter;
+    private String sourceParameter;
+    private String contentParameter;
+    private String termParameter;
+    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+    private LocalDateTime createdAt;
+    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+    private LocalDateTime updatedAt;
+
+    @JacksonXmlElementWrapper(localName = "visitor_page_views")
+    private List<VisitorPageView> visitorPageViews;
+
+    public Long getId() { return id; }
+
+    public Long getVisitorId() { return visitorId; }
+
+    public Long getProspectId() { return prospectId; }
+
+    public Integer getVisitorPageViewCount() { return visitorPageViewCount; }
+
+    public LocalDateTime getFirstVisitorPageViewAt() { return firstVisitorPageViewAt; }
+
+    public LocalDateTime getLastVisitorPageViewAt() { return lastVisitorPageViewAt; }
+
+    public Integer getDurationInSeconds() { return durationInSeconds; }
+
+    public String getCampaignParameter() { return campaignParameter; }
+
+    public String getMediumParameter() { return mediumParameter; }
+
+    public String getSourceParameter() { return sourceParameter; }
+
+    public String getContentParameter() { return contentParameter; }
+
+    public String getTermParameter() { return termParameter; }
+
+    public LocalDateTime getCreatedAt() { return createdAt; }
+
+    public LocalDateTime getUpdatedAt() { return updatedAt; }
+
+    /**
+     * Visitor Page Views associated to the visit, or empty list if none.
+     *
+     * @return Associated Visitor Page Views, or empty list if none.
+     */
+    public List<VisitorPageView> getVisitorPageViews() {
+        if (visitorPageViews == null) {
+            return new ArrayList<>();
+        }
+        return visitorPageViews;
+    }
+
+    @Override
+    public String toString() {
+        return "Visitor{"
+            + "id=" + id
+            + ", visitorId=" + visitorId
+            + ", prospectId=" + prospectId
+            + ", visitorPageViewCount=" + visitorPageViewCount
+            + ", firstVisitorPageViewAt=" + firstVisitorPageViewAt
+            + ", lastVisitorPageViewAt=" + lastVisitorPageViewAt
+            + ", durationInSeconds=" + durationInSeconds
+            + ", campaignParameter='" + campaignParameter + '\''
+            + ", mediumParameter='" + mediumParameter + '\''
+            + ", sourceParameter='" + sourceParameter + '\''
+            + ", contentParameter='" + contentParameter + '\''
+            + ", termParameter='" + termParameter + '\''
+            + ", createdAt=" + createdAt
+            + ", updatedAt=" + updatedAt
+            + '}';
+    }
+}