feat: create PushSource and catalogSource classes

src/main/java/com/coveo/pushapiclient/ApiUrl.java

@@ -0,0 +1,122 @@
+package com.coveo.pushapiclient;
+
+import java.net.MalformedURLException;
+import java.net.URL;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.List;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * Private util class to extract dynamic parts from a API URL
+ * Handles extraction of identifiers and platform URL from a source URL.
+ *
+ * @See https://docs.coveo.com/en/1546#push-api-url
+ *      https://docs.coveo.com/en/3295#stream-api-url
+ */
+class ApiUrl {
+    private final String organizationId;
+    private final String sourceId;
+    private final PlatformUrl platformUrl;
+    private final String sourceUrl;
+
+    public ApiUrl(URL sourceUrl) throws MalformedURLException {
+        List<String> identifiers = this.extractIdentifiers(sourceUrl);
+        this.organizationId = identifiers.get(0);
+        this.sourceId = identifiers.get(1);
+        this.sourceUrl = sourceUrl.toString();
+        this.platformUrl = this.extractPlatformUrl(sourceUrl);
+    }
+
+    public ApiUrl(String organizationId, String sourceId, PlatformUrl platformUrl) {
+        this.organizationId = organizationId;
+        this.sourceId = sourceId;
+        this.platformUrl = platformUrl;
+        this.sourceUrl = String.format("https://api.cloud.coveo.com/push/v1/organizations/%s/sources/%s",
+                this.organizationId, this.sourceId);
+    }
+
+    public String getUrl() {
+        return this.sourceUrl;
+    }
+
+    public String getOrganizationId() {
+        return this.organizationId;
+    }
+
+    public String getSourceId() {
+        return this.sourceId;
+    }
+
+    public PlatformUrl getPlatformUrl() {
+        return this.platformUrl;
+    }
+
+    private List<String> extractIdentifiers(URL sourceUrl) throws MalformedURLException {
+        String host = sourceUrl.getPath();
+        Pattern pattern = Pattern.compile("/push/v1/organizations/([^/]+)/sources/([^/]+)");
+        Matcher matcher = pattern.matcher(host);
+
+        if (matcher.find()) {
+            String organizationId = matcher.group(1);
+            String sourceId = matcher.group(2);
+            return Arrays.asList(organizationId, sourceId);
+        }
+
+        String errorMessage = this
+                .getErrorMessage("Unable to find organization and source ids from the provided API url");
+        throw new MalformedURLException(errorMessage);
+    }
+
+    private PlatformUrl extractPlatformUrl(URL sourceUrl) throws MalformedURLException {
+        String host = sourceUrl.getHost();
+        Pattern pattern = Pattern.compile("api([a-z]*)([a-z-]*)\\.cloud\\.coveo\\.com");
+        Matcher matcher = pattern.matcher(host);
+
+        if (matcher.find()) {
+            String extractedEnvironment = matcher.group(1);
+            String extractedRegion = matcher.group(2).replace("-", "");
+
+            Environment urlEnvironment = extractedEnvironment.isEmpty()
+                    ? PlatformUrl.DEFAULT_ENVIRONMENT
+                    : EnumSet.allOf(Environment.class)
+                            .stream()
+                            .filter(e -> e.getValue().equalsIgnoreCase(extractedEnvironment))
+                            .findFirst()
+                            .orElseThrow(() -> new MalformedURLException(
+                                    String.format("Invalid platform environment '%s'", extractedEnvironment)));
+
+            Region urlRegion = extractedRegion.isEmpty()
+                    ? PlatformUrl.DEFAULT_REGION
+                    : EnumSet.allOf(Region.class)
+                            .stream()
+                            .filter(r -> r.getValue().equalsIgnoreCase(extractedRegion))
+                            .findFirst()
+                            .orElseThrow(() -> new MalformedURLException(
+                                    String.format("Invalid platform region '%s'", extractedRegion)));
+
+            return new PlatformUrl(urlEnvironment, urlRegion);
+
+        }
+
+        String invalidHostMessage = this.getErrorMessage("Invalid API URL host");
+        throw new MalformedURLException(invalidHostMessage);
+    }
+
+    private String getErrorMessage(String reason) {
+        String newLine = System.getProperty("line.separator");
+        String message = "The provided API URL is invalid";
+
+        message.concat(newLine).concat(reason);
+
+        message
+                .concat(newLine)
+                .concat("For a Push Source, visit: https://docs.coveo.com/en/1546")
+                .concat(newLine)
+                .concat("For a Catalog Source, visit:https://docs.coveo.com/en/3295");
+
+        return message;
+    }
+
+}

src/main/java/com/coveo/pushapiclient/BaseSource.java

@@ -0,0 +1,32 @@
+package com.coveo.pushapiclient;
+
+public interface BaseSource {
+    /**
+     * Returns the API key used for all operations regarding your source.
+     *
+     * @return
+     */
+    String getApiKey();
+
+    /**
+     * Returns the {@link PlatformUrl} object associated to the source.
+     *
+     * @return
+     */
+    PlatformUrl getPlatformUrl();
+
+    /**
+     * The unique identifier of your organization.
+     *
+     * @return
+     */
+    String getOrganizationId();
+
+    /**
+     * The unique identifier of your source.
+     *
+     * @return
+     */
+    String getId();
+
+}

src/main/java/com/coveo/pushapiclient/CatalogSource.java

@@ -0,0 +1,154 @@
+package com.coveo.pushapiclient;
+
+import java.net.MalformedURLException;
+import java.net.URL;
+
+// TODO: LENS-851 - Make public when ready
+class CatalogSource implements StreamEnabledSource {
+    private final String apiKey;
+    private final ApiUrl urlExtractor;
+
+    /**
+     * Create a Catalog source instance from its
+     * <a href="https://docs.coveo.com/en/3295#stream-api-url">Stream API URL</a>
+     *
+     * @param apiKey    The API key used for all operations regarding your source.
+     *                  <p>
+     *                  Ensure your API key has the required privileges for the
+     *                  operation you will be performing
+     *                  *
+     *                  <p>
+     *                  For more information about which privileges are required,
+     *                  see
+     *                  <a href=
+     *                  "https://docs.coveo.com/en/1707#sources-domain">Privilege
+     *                  Reference.</a>
+     *
+     * @param sourceUrl The URL available when you edit your source in the <a href=
+     *                  "https://docs.coveo.com/en/183/glossary/coveo-administration-console">Coveo
+     *                  Administration Console</a>. The URL should contain your
+     *                  <code>ORGANIZATION_ID</code> and <code>SOURCE_ID</code>,
+     *                  which are required parameters for all operations regarding
+     *                  your source.
+     *                  <p>
+     *                  Some examples of valid source URLs:
+     *
+     *                  <pre>
+     * https://api.cloud.coveo.com/push/v1/organizations/my-org-if/sources/my-source-id/stream/open
+     * https://api-eu.cloud.coveo.com/push/v1/organizations/my-org-if/sources/my-source-id/stream/open
+     *                  </pre>
+     *
+     * @throws MalformedURLException
+     */
+    public CatalogSource(String apiKey, URL sourceUrl) throws MalformedURLException {
+        this.apiKey = apiKey;
+        this.urlExtractor = new ApiUrl(sourceUrl);
+    }
+
+    /**
+     * Create a Catalog source instance from its
+     * <a href="https://docs.coveo.com/en/3295#stream-api-url">Stream API URL</a>
+     *
+     * @param apiKey         The API key used for all operations regarding your
+     *                       source.
+     *                       <p>
+     *                       Ensure your API key has the required privileges for the
+     *                       operation you will be performing
+     *                       *
+     *                       <p>
+     *                       For more information about which privileges are
+     *                       required,
+     *                       see
+     *                       <a href=
+     *                       "https://docs.coveo.com/en/1707#sources-domain">Privilege
+     *                       Reference.</a>
+     *
+     * @param organizationId The unique identifier of your organization.
+     *                       <p>
+     *                       The Organization Id can be retrieved in the URL of your
+     *                       Coveo organization.
+     *
+     * @param sourceId       The unique identifier of the target Catalog source.
+     *                       <p>
+     *                       The Source Id can be retrieved when you edit your
+     *                       source in the <a href=
+     *                       "https://docs.coveo.com/en/183/glossary/coveo-administration-console">Coveo
+     *                       Administration Console</a>
+     *
+     */
+    public static CatalogSource fromPlatformUrl(String apiKey, String organizationId, String sourceId) {
+        PlatformUrl platformUrl = new PlatformUrl(PlatformUrl.DEFAULT_ENVIRONMENT, PlatformUrl.DEFAULT_REGION);
+        return new CatalogSource(apiKey, organizationId, sourceId, platformUrl);
+    }
+
+    /**
+     * Create a Catalog source instance from its
+     * <a href="https://docs.coveo.com/en/3295#stream-api-url">Stream API URL</a>
+     *
+     * @param apiKey         The API key used for all operations regarding your
+     *                       source.
+     *                       <p>
+     *                       Ensure your API key has the required privileges for the
+     *                       operation you will be performing
+     *                       *
+     *                       <p>
+     *                       For more information about which privileges are
+     *                       required,
+     *                       see
+     *                       <a href=
+     *                       "https://docs.coveo.com/en/1707#sources-domain">Privilege
+     *                       Reference.</a>
+     *
+     * @param organizationId The unique identifier of your organization.
+     *                       <p>
+     *                       The Organization Id can be retrieved in the URL of your
+     *                       Coveo organization.
+     *
+     * @param sourceId       The unique identifier of the target Catalog source.
+     *                       <p>
+     *                       The Source Id can be retrieved when you edit your
+     *                       source in the <a href=
+     *                       "https://docs.coveo.com/en/183/glossary/coveo-administration-console">Coveo
+     *                       Administration Console</a>
+     *
+     * @param platformUrl    The object containing additional information on the
+     *                       URL endpoint.
+     *                       You can use the {@link PlatformUrl} when your
+     *                       organization is located in a non-default Coveo
+     *                       environement and/or region. When not specified, the
+     *                       default platform URL values will be used:
+     *                       {@link PlatformUrl#DEFAULT_ENVIRONMENT} and
+     *                       {@link PlatformUrl#DEFAULT_REGION}
+     *
+     */
+    public static CatalogSource fromPlatformUrl(String apiKey, String organizationId, String sourceId,
+            PlatformUrl platformUrl) {
+        return new CatalogSource(apiKey, organizationId, sourceId, platformUrl);
+    }
+
+    private CatalogSource(String apiKey, String organizationId, String sourceId, PlatformUrl platformUrl) {
+        this.apiKey = apiKey;
+        this.urlExtractor = new ApiUrl(organizationId, sourceId, platformUrl);
+    }
+
+    @Override
+    public String getOrganizationId() {
+        return this.urlExtractor.getOrganizationId();
+    }
+
+    @Override
+    public PlatformUrl getPlatformUrl() {
+        return this.urlExtractor.getPlatformUrl();
+    }
+
+    @Override
+    public String getId() {
+        return this.urlExtractor.getSourceId();
+    }
+
+    @Override
+    public String getApiKey() {
+        return this.apiKey;
+    }
+
+}

src/main/java/com/coveo/pushapiclient/PushEnabledSource.java

@@ -0,0 +1,6 @@
+package com.coveo.pushapiclient;
+
+// Marker Interface
+public interface PushEnabledSource extends BaseSource {
+
+}