@adobe/mysticat-shared-seo-client 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+## @adobe/mysticat-shared-seo-client-v1.0.0 (2026-04-01)
+
+### Features
+
+* **seo-client:** add mysticat-shared-seo-client package ([#1490](https://github.com/adobe/spacecat-shared/issues/1490)) ([27faade](https://github.com/adobe/spacecat-shared/commit/27faade8b3179ee213dce6044c08ebb5ceff1a19))

package/README.md

@@ -0,0 +1,48 @@
+# Mysticat Shared - SEO Client
+
+An SEO API client for SpaceCat services.
+
+## Installation
+
+```bash
+npm install @adobe/mysticat-shared-seo-client
+```
+
+## Usage
+
+### Creating an instance from Helix UniversalContext
+
+```js
+const client = SeoClient.createFrom(context);
+```
+
+### Constructor
+
+```js
+import SeoClient from '@adobe/mysticat-shared-seo-client';
+
+const config = {
+  apiKey: '<API_KEY>',
+  apiBaseUrl: '<API_BASE_URL>',
+};
+
+const client = new SeoClient(config, fetch);
+```
+
+## Testing
+
+```bash
+npm run test
+```
+
+## Linting
+
+```bash
+npm run lint
+```
+
+## Additional Information
+
+- **Repository**: [GitHub](https://github.com/adobe/spacecat-shared.git)
+- **Issue Tracking**: [GitHub Issues](https://github.com/adobe/spacecat-shared/issues)
+- **License**: Apache-2.0

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@adobe/mysticat-shared-seo-client",
+  "version": "1.0.0",
+  "description": "Shared modules of the SpaceCat Services - SEO Client",
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0 <25.0.0",
+    "npm": ">=10.9.0 <12.0.0"
+  },
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "scripts": {
+    "test": "c8 mocha",
+    "lint": "eslint .",
+    "clean": "rm -rf package-lock.json node_modules"
+  },
+  "mocha": {
+    "require": "test/setup-env.js",
+    "reporter": "mocha-multi-reporters",
+    "reporter-options": "configFile=.mocha-multi.json",
+    "spec": "test/**/*.test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/adobe/spacecat-shared.git"
+  },
+  "author": "",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/adobe/spacecat-shared/issues"
+  },
+  "homepage": "https://github.com/adobe/spacecat-shared#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@adobe/fetch": "4.2.3",
+    "@adobe/helix-universal": "5.4.0",
+    "@adobe/spacecat-shared-utils": "1.81.1"
+  },
+  "devDependencies": {
+    "chai": "6.2.2",
+    "chai-as-promised": "8.0.2",
+    "nock": "14.0.11",
+    "sinon": "21.0.3",
+    "sinon-chai": "4.0.1",
+    "typescript": "5.9.3"
+  }
+}

package/src/client.js

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { isValidUrl } from '@adobe/spacecat-shared-utils';
+import { context as h2, h1 } from '@adobe/fetch';
+
+/* c8 ignore next 3 */
+export const { fetch } = process.env.HELIX_FETCH_FORCE_HTTP1
+  ? h1()
+  : h2();
+
+const STUB_RESPONSE = { result: {}, fullAuditRef: '' };
+
+export default class SeoClient {
+  static createFrom(context) {
+    const { SEO_API_BASE_URL: apiBaseUrl, SEO_API_KEY: apiKey } = context.env;
+    return new SeoClient({ apiBaseUrl, apiKey }, fetch, context.log);
+  }
+
+  constructor(config, fetchAPI, log = console) {
+    const { apiKey, apiBaseUrl } = config;
+
+    if (!isValidUrl(apiBaseUrl)) {
+      throw new Error(`Invalid SEO API Base URL: ${apiBaseUrl}`);
+    }
+
+    if (typeof fetchAPI !== 'function') {
+      throw Error('"fetchAPI" must be a function');
+    }
+
+    this.apiBaseUrl = apiBaseUrl;
+    this.apiKey = apiKey;
+    this.fetchAPI = fetchAPI;
+    this.log = log;
+  }
+
+  // eslint-disable-next-line no-unused-vars, class-methods-use-this
+  async sendRequest(endpoint, queryParams = {}) {
+    return STUB_RESPONSE;
+  }
+
+  // eslint-disable-next-line no-unused-vars, class-methods-use-this
+  async getBrokenBacklinks(url, limit = 50) {
+    return STUB_RESPONSE;
+  }
+
+  // eslint-disable-next-line no-unused-vars, class-methods-use-this
+  async getTopPages(url, limit = 200) {
+    return STUB_RESPONSE;
+  }
+
+  // eslint-disable-next-line no-unused-vars, class-methods-use-this
+  async getBacklinks(url, limit = 200) {
+    return STUB_RESPONSE;
+  }
+
+  // eslint-disable-next-line no-unused-vars, class-methods-use-this
+  async getOrganicKeywords(url, options = {}) {
+    return STUB_RESPONSE;
+  }
+
+  // eslint-disable-next-line no-unused-vars, class-methods-use-this
+  async getPaidPages(url, date = new Date().toISOString().split('T')[0], limit = 200, mode = 'prefix') {
+    return STUB_RESPONSE;
+  }
+
+  // eslint-disable-next-line no-unused-vars, class-methods-use-this
+  async getMetrics(url, date = new Date().toISOString().split('T')[0]) {
+    return STUB_RESPONSE;
+  }
+
+  // eslint-disable-next-line no-unused-vars, class-methods-use-this
+  async getMetricsByCountry(url, date = new Date().toISOString().split('T')[0]) {
+    return STUB_RESPONSE;
+  }
+}

package/src/endpoints.js

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/**
+ * Endpoint definitions for the SEO API.
+ * Each entry maps a method name to its API path and default query parameters.
+ * Paths and params are stubs - to be populated when implementing API calls.
+ */
+export const ENDPOINTS = {
+  brokenBacklinks: { path: '', defaultParams: {} },
+  topPages: { path: '', defaultParams: {} },
+  backlinks: { path: '', defaultParams: {} },
+  organicKeywords: { path: '', defaultParams: {} },
+  paidPages: { path: '', defaultParams: {} },
+  metrics: { path: '', defaultParams: {} },
+  metricsByCountry: { path: '', defaultParams: {} },
+};

package/src/index.d.ts

@@ -0,0 +1,114 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { UniversalContext } from '@adobe/helix-universal';
+
+export interface SeoAPIOptions {
+    select: string;
+    where: string;
+    order_by: string;
+    date: string;
+    target: string;
+    limit: number;
+    mode: string;
+    output: string;
+}
+
+export default class SeoClient {
+  /**
+   * Static factory method to create an instance of SeoClient.
+   * @param {UniversalContext} context - An object containing the AWS Lambda context information
+   * @returns An instance of SeoClient.
+   */
+  static createFrom(context: UniversalContext): SeoClient;
+
+  /**
+   * Constructor for creating an instance of SeoClient.
+   * @param config
+   * @param fetchAPI
+   * @param log
+   */
+  constructor(config: object, fetchAPI, log?: Console);
+
+  /**
+   * Asynchronous method to send a request to the SEO API.
+   * @param endpoint
+   * @param queryParams
+   */
+  sendRequest(endpoint: string, queryParams?: SeoAPIOptions):
+      Promise<{ result: object, fullAuditRef: string }>;
+
+  /**
+   * Asynchronous method to get broken backlinks.
+   * @param url
+   * @param limit
+   */
+  getBrokenBacklinks(url: string, limit?: number):
+      Promise<{ result: object, fullAuditRef: string }>;
+
+  /**
+   * Asynchronous method to get top pages.
+   * @param url
+   * @param limit
+   */
+  getTopPages(url: string, limit?: number):
+      Promise<{ result: object, fullAuditRef: string }>;
+
+  /**
+   * Asynchronous method to get backlinks.
+   * @param url
+   * @param limit
+   */
+  getBacklinks(url: string, limit?: number):
+      Promise<{ result: object, fullAuditRef: string }>;
+
+  /**
+   * Asynchronous method to get organic keywords.
+   */
+  getOrganicKeywords(
+    url: string,
+    options?: {
+      country?: string,
+      keywordFilter?: string[],
+      limit?: number,
+      mode?: 'exact' | 'prefix',
+      excludeBranded?: boolean,
+    }):
+      Promise<{ result: object, fullAuditRef: string }>;
+
+  /**
+   * Asynchronous method to get paid pages for a URL.
+   * @param url - The target URL
+   * @param date - Optional date in YYYY-MM-DD format, defaults to today
+   * @param limit - Maximum number of results to return (max: 1000)
+   * @param mode - Search mode
+   */
+  getPaidPages(url: string, date?: string, limit?: number,
+    mode?: 'exact' | 'prefix' | 'domain' | 'subdomains'):
+      Promise<{ result: object, fullAuditRef: string }>;
+
+  /**
+   * Asynchronous method to get metrics for a URL.
+   * @param url - The target URL
+   * @param date - Optional date in YYYY-MM-DD format, defaults to today
+   */
+  getMetrics(url: string, date?: string):
+      Promise<{ result: object, fullAuditRef: string }>;
+
+  /**
+   * Asynchronous method to get metrics by country for a URL.
+   * @param url - The target URL
+   * @param date - Optional date in YYYY-MM-DD format, defaults to today
+   */
+  getMetricsByCountry(url: string, date?: string):
+      Promise<{ result: object, fullAuditRef: string }>;
+}

package/src/index.js

@@ -0,0 +1,22 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import SeoClient from './client.js';
+
+export default SeoClient;
+export { fetch } from './client.js';
+export { ENDPOINTS } from './endpoints.js';
+export { buildQueryParams, parseResponse } from './utils.js';
+
+export const ORGANIC_KEYWORDS_FIELDS = /** @type {const} */ ([]);
+
+export const METRICS_BY_COUNTRY_FILTER_FIELDS = /** @type {const} */ ([]);

package/src/utils.js

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/**
+ * Merges default query parameters with caller-provided overrides.
+ * @param {object} defaults - Default parameter values
+ * @param {object} overrides - Caller-provided overrides
+ * @returns {object} Merged parameters
+ */
+export function buildQueryParams(defaults, overrides) {
+  return { ...defaults, ...overrides };
+}
+
+/**
+ * Parses/normalizes an API response.
+ * Stub - passes through unchanged. To be extended when implementing API calls.
+ * @param {*} response - Raw API response
+ * @returns {*} Parsed response
+ */
+export function parseResponse(response) {
+  return response;
+}