feat(costs): add costs audit that returns the ahrefs API units consumed and limit (#365)

Add costs audit that returns the Ahrefs API units consumed and limit.
Ahrefs API call to get limits and usage is free.
Audit will be scheduled weekly.
Since this is a global audit, it will be by default disabled in the global configuration.
It will only be enabled on dev, for ahrefs.com site.
The follow-up PR #369 will add a post-processor notifying only internally about the audit result.

Author: iuliag

src/costs/handler.js

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2024 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 AhrefsAPIClient from '@adobe/spacecat-shared-ahrefs-client';
+import { AuditBuilder } from '../common/audit-builder.js';
+
+export async function runner(auditUrl, context) {
+  const { log } = context;
+  const ahrefsAPIClient = AhrefsAPIClient.createFrom(context);
+
+  let ahrefsCostsAuditResult;
+  try {
+    const {
+      result,
+      fullAuditRef,
+    } = await ahrefsAPIClient.getLimitsAndUsage();
+
+    log.info(`Retrieved Ahrefs limits and usage: ${JSON.stringify(result)}`);
+    ahrefsCostsAuditResult = {
+      usedApiUnits: result?.limits_and_usage?.units_usage_api_key,
+      limitApiUnits: result?.limits_and_usage?.units_limit_api_key,
+      fullAuditRef,
+    };
+  } catch (e) {
+    log.error(`Ahrefs costs type audit failed with error: ${e.message}`, e);
+    ahrefsCostsAuditResult = {
+      error: `Ahrefs costs type audit failed with error: ${e.message}`,
+    };
+  }
+
+  return {
+    auditResult: {
+      ahrefs: ahrefsCostsAuditResult,
+    },
+    fullAuditRef: ahrefsCostsAuditResult?.fullAuditRef,
+  };
+}
+
+export default new AuditBuilder()
+  .withRunner(runner)
+  .withMessageSender(() => {})
+  .build();

src/index.js

@@ -29,6 +29,7 @@ import experimentation from './experimentation/handler.js';
 import conversion from './conversion/handler.js';
 import essExperimentationDaily from './experimentation-ess/daily.js';
 import essExperimentationAll from './experimentation-ess/all.js';
+import costs from './costs/handler.js';
 
 const HANDLERS = {
   apex,
@@ -43,6 +44,7 @@ const HANDLERS = {
   conversion,
   'experimentation-ess-daily': essExperimentationDaily,
   'experimentation-ess-all': essExperimentationAll,
+  costs,
 };
 
 function getElapsedSeconds(startTime) {

test/audits/costs.test.js

@@ -0,0 +1,102 @@
+/*
+ * Copyright 2024 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.
+ */
+
+/* eslint-env mocha */
+import { expect, use } from 'chai';
+import sinon from 'sinon';
+import sinonChai from 'sinon-chai';
+import chaiAsPromised from 'chai-as-promised';
+import nock from 'nock';
+import { MockContextBuilder } from '../shared.js';
+import { runner } from '../../src/costs/handler.js';
+
+use(sinonChai);
+use(chaiAsPromised);
+
+const message = {
+  type: 'costs',
+  url: 'site-id',
+};
+const sandbox = sinon.createSandbox();
+
+describe('Costs audit', () => {
+  let context;
+
+  beforeEach('setup', () => {
+    context = new MockContextBuilder()
+      .withSandbox(sandbox)
+      .withOverrides({
+        env: {
+          AHREFS_API_BASE_URL: 'https://ahrefs-example.com',
+          AHREFS_API_KEY: 'ahrefs-token',
+        },
+      })
+      .build(message);
+  });
+
+  afterEach(() => {
+    nock.cleanAll();
+    sandbox.restore();
+  });
+
+  it('costs audit returns ahrefs costs succesfully', async () => {
+    const limitsUsageResponse = {
+      limits_and_usage: {
+        subscription: 'Enterprise, billed yearly',
+        usage_reset_date: '2024-08-28T00:00:00Z',
+        units_limit_workspace: 12000000,
+        units_usage_workspace: 6618294,
+        units_limit_api_key: 1000000,
+        units_usage_api_key: 198771,
+        api_key_expiration_date: '2025-01-04T17:44:07Z',
+      },
+    };
+
+    nock('https://ahrefs-example.com')
+      .get('/subscription-info/limits-and-usage')
+      .reply(200, limitsUsageResponse);
+
+    const result = await runner('https://spacecat.com', context);
+
+    const expectedAuditResult = {
+      ahrefs: {
+        usedApiUnits: 198771,
+        limitApiUnits: 1000000,
+        fullAuditRef: 'https://ahrefs-example.com/subscription-info/limits-and-usage',
+      },
+    };
+
+    expect(result).to.eql({
+      auditResult: expectedAuditResult,
+      fullAuditRef: 'https://ahrefs-example.com/subscription-info/limits-and-usage',
+    });
+  });
+
+  it('costs audit returns error for ahrefs costs when call to ahrefs throws', async () => {
+    nock('https://ahrefs-example.com')
+      .get('/subscription-info/limits-and-usage')
+      .reply(500);
+
+    const result = await runner('https://spacecat.com', context);
+
+    const expectedAuditResult = {
+      ahrefs: {
+        error: 'Ahrefs costs type audit failed with error: Ahrefs API request failed with status: 500',
+      },
+    };
+
+    expect(result).to.eql({
+      auditResult: expectedAuditResult,
+      fullAuditRef: undefined,
+    });
+  });
+});