@digestseo/mcp-gsc 0.3.1 → 0.4.0

package/src/access-token-lifecycle.ts

@@ -0,0 +1,107 @@
+import {
+  GoogleRefreshTokenRevokedError,
+  GSC_ACCESS_REVOKED_MESSAGE,
+  refreshAccessToken,
+} from './google';
+import {
+  deleteUser,
+  getDecryptedRefreshToken,
+} from './storage';
+
+export interface GoogleAccessTokenEnv {
+  USER_KV: KVNamespace;
+  TOKEN_ENCRYPTION_KEY: string;
+  GOOGLE_CLIENT_ID: string;
+  GOOGLE_CLIENT_SECRET: string;
+}
+
+export interface GoogleAccessTokenProvider {
+  getAccessToken(googleId: string): Promise<string>;
+}
+
+interface AccessTokenCacheEntry {
+  token: string;
+  expires_at: number;
+}
+
+export interface AccessTokenLifecycleDependencies {
+  getDecryptedRefreshToken: typeof getDecryptedRefreshToken;
+  refreshAccessToken: typeof refreshAccessToken;
+  deleteUser: typeof deleteUser;
+  now: () => number;
+}
+
+const DEFAULT_DEPENDENCIES: AccessTokenLifecycleDependencies = {
+  getDecryptedRefreshToken,
+  refreshAccessToken,
+  deleteUser,
+  now: Date.now,
+};
+
+/**
+ * Keeps access tokens in memory only for the lifetime of the provider. It
+ * centralizes refresh-token revocation handling for every Google API caller.
+ */
+export class GoogleAccessTokenLifecycle implements GoogleAccessTokenProvider {
+  private readonly cache = new Map<string, AccessTokenCacheEntry>();
+  private readonly inFlightRefreshes = new Map<string, Promise<string>>();
+  private readonly dependencies: AccessTokenLifecycleDependencies;
+
+  constructor(
+    private readonly env: GoogleAccessTokenEnv,
+    dependencies: Partial<AccessTokenLifecycleDependencies> = {},
+  ) {
+    this.dependencies = { ...DEFAULT_DEPENDENCIES, ...dependencies };
+  }
+
+  async getAccessToken(googleId: string): Promise<string> {
+    const now = this.dependencies.now();
+    const cached = this.cache.get(googleId);
+    if (cached && cached.expires_at > now + 60_000) {
+      return cached.token;
+    }
+
+    const inFlight = this.inFlightRefreshes.get(googleId);
+    if (inFlight) return inFlight;
+
+    const refresh = this.refreshAndCache(googleId);
+    this.inFlightRefreshes.set(googleId, refresh);
+    try {
+      return await refresh;
+    } finally {
+      if (this.inFlightRefreshes.get(googleId) === refresh) {
+        this.inFlightRefreshes.delete(googleId);
+      }
+    }
+  }
+
+  private async refreshAndCache(googleId: string): Promise<string> {
+    const refreshToken = await this.dependencies.getDecryptedRefreshToken(
+      this.env,
+      googleId,
+    );
+    if (!refreshToken) {
+      throw new Error(GSC_ACCESS_REVOKED_MESSAGE);
+    }
+
+    try {
+      const tokens = await this.dependencies.refreshAccessToken(
+        refreshToken,
+        this.env.GOOGLE_CLIENT_ID,
+        this.env.GOOGLE_CLIENT_SECRET,
+      );
+      this.cache.set(googleId, {
+        token: tokens.access_token,
+        expires_at: this.dependencies.now() + tokens.expires_in * 1000,
+      });
+      return tokens.access_token;
+    } catch (err) {
+      if (err instanceof GoogleRefreshTokenRevokedError) {
+        this.cache.delete(googleId);
+        await this.dependencies.deleteUser(this.env, googleId);
+        console.warn('Refresh token revoked; deleted stored user credentials');
+      }
+      throw err;
+    }
+  }
+}

package/src/cannibalization-schema.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+
+export const CANNIBALIZATION_MIN_IMPRESSIONS_SCHEMA = z
+  .number()
+  .int()
+  .min(0)
+  .default(50)
+  .describe('Minimum impressions for a page-query pair to be considered. Must be at least 0. Default is 50.');
+
+export const CANNIBALIZATION_MIN_PAGE_PERCENTAGE_SCHEMA = z
+  .number()
+  .min(0)
+  .max(100)
+  .default(10)
+  .describe('Minimum percentage of total query impressions a page must have to count as a cannibalizing page (0-100). Default is 10%.');

package/src/content-decay-schema.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+
+export const CONTENT_DECAY_COMPARE_DAYS_SCHEMA = z
+  .number()
+  .int()
+  .min(1)
+  .default(30)
+  .describe('Number of days to compare (recent period vs previous period). Must be at least 1. Default is 30.');

package/src/crypto.ts

@@ -1,58 +1,80 @@
-function base64Decode(b64: string): Uint8Array<ArrayBuffer> {
-  const binary = atob(b64);
-  const buf = new ArrayBuffer(binary.length);
-  const bytes = new Uint8Array(buf);
-  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
-  return bytes;
-}
-
-function base64Encode(bytes: Uint8Array): string {
-  let binary = '';
-  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
-  return btoa(binary);
-}
-
-async function importKey(base64Key: string): Promise<CryptoKey> {
-  const keyBytes = base64Decode(base64Key);
-  return crypto.subtle.importKey(
-    'raw',
-    keyBytes,
-    { name: 'AES-GCM' },
-    false,
-    ['encrypt', 'decrypt'],
-  );
-}
-
-export async function encryptToken(
-  plaintext: string,
-  base64Key: string,
-): Promise<{ ciphertext: string; iv: string }> {
-  const key = await importKey(base64Key);
-  const iv = crypto.getRandomValues(new Uint8Array(12));
-  const encoded = new TextEncoder().encode(plaintext);
-  const ciphertext = await crypto.subtle.encrypt(
-    { name: 'AES-GCM', iv },
-    key,
-    encoded,
-  );
-  return {
-    ciphertext: base64Encode(new Uint8Array(ciphertext)),
-    iv: base64Encode(iv),
-  };
-}
-
-export async function decryptToken(
-  ciphertext: string,
-  iv: string,
-  base64Key: string,
-): Promise<string> {
-  const key = await importKey(base64Key);
-  const ctBytes = base64Decode(ciphertext);
-  const ivBytes = base64Decode(iv);
-  const decrypted = await crypto.subtle.decrypt(
-    { name: 'AES-GCM', iv: ivBytes },
-    key,
-    ctBytes,
-  );
-  return new TextDecoder().decode(decrypted);
-}
+function base64Decode(b64: string): Uint8Array<ArrayBuffer> {
+  const binary = atob(b64);
+  const buf = new ArrayBuffer(binary.length);
+  const bytes = new Uint8Array(buf);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+function base64Encode(bytes: Uint8Array): string {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary);
+}
+
+const TOKEN_ENCRYPTION_KEY_ERROR =
+  'Invalid TOKEN_ENCRYPTION_KEY configuration: expected a valid base64-encoded 32-byte (256-bit) AES key.';
+
+function decodeTokenEncryptionKey(base64Key: string): Uint8Array<ArrayBuffer> {
+  if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(base64Key)) {
+    throw new Error(TOKEN_ENCRYPTION_KEY_ERROR);
+  }
+
+  let keyBytes: Uint8Array<ArrayBuffer>;
+  try {
+    keyBytes = base64Decode(base64Key);
+  } catch {
+    throw new Error(TOKEN_ENCRYPTION_KEY_ERROR);
+  }
+
+  if (keyBytes.byteLength !== 32) {
+    throw new Error(TOKEN_ENCRYPTION_KEY_ERROR);
+  }
+
+  return keyBytes;
+}
+
+async function importKey(base64Key: string): Promise<CryptoKey> {
+  const keyBytes = decodeTokenEncryptionKey(base64Key);
+  return crypto.subtle.importKey(
+    'raw',
+    keyBytes,
+    { name: 'AES-GCM' },
+    false,
+    ['encrypt', 'decrypt'],
+  );
+}
+
+export async function encryptToken(
+  plaintext: string,
+  base64Key: string,
+): Promise<{ ciphertext: string; iv: string }> {
+  const key = await importKey(base64Key);
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const encoded = new TextEncoder().encode(plaintext);
+  const ciphertext = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    encoded,
+  );
+  return {
+    ciphertext: base64Encode(new Uint8Array(ciphertext)),
+    iv: base64Encode(iv),
+  };
+}
+
+export async function decryptToken(
+  ciphertext: string,
+  iv: string,
+  base64Key: string,
+): Promise<string> {
+  const key = await importKey(base64Key);
+  const ctBytes = base64Decode(ciphertext);
+  const ivBytes = base64Decode(iv);
+  const decrypted = await crypto.subtle.decrypt(
+    { name: 'AES-GCM', iv: ivBytes },
+    key,
+    ctBytes,
+  );
+  return new TextDecoder().decode(decrypted);
+}

package/src/date-validation.ts

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+
+const YYYY_MM_DD = /^(\d{4})-(\d{2})-(\d{2})$/;
+const SEARCH_CONSOLE_TIME_ZONE = 'America/Los_Angeles';
+
+export function getSearchConsoleCalendarDate(now: Date = new Date()): string {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone: SEARCH_CONSOLE_TIME_ZONE,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  }).formatToParts(now);
+  const value = (type: Intl.DateTimeFormatPartTypes) =>
+    parts.find((part) => part.type === type)?.value;
+  const year = value('year');
+  const month = value('month');
+  const day = value('day');
+  if (!year || !month || !day) {
+    throw new Error('Could not resolve the Search Console calendar date.');
+  }
+  return `${year}-${month}-${day}`;
+}
+
+export function isValidCalendarDate(value: string): boolean {
+  const match = YYYY_MM_DD.exec(value);
+  if (!match) return false;
+
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  if (month < 1 || month > 12 || day < 1) return false;
+
+  const daysInMonth = [
+    31,
+    (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0 ? 29 : 28,
+    31,
+    30,
+    31,
+    30,
+    31,
+    31,
+    30,
+    31,
+    30,
+    31,
+  ];
+  return day <= daysInMonth[month - 1];
+}
+
+export const SEARCH_CONSOLE_DATE_SCHEMA = z.string().superRefine((value, ctx) => {
+  if (!YYYY_MM_DD.test(value)) {
+    ctx.addIssue({
+      code: 'custom',
+      message: 'Use YYYY-MM-DD format (for example, 2026-01-31).',
+    });
+    return;
+  }
+
+  if (!isValidCalendarDate(value)) {
+    ctx.addIssue({
+      code: 'custom',
+      message: 'Use a real calendar date in YYYY-MM-DD format (for example, 2024-02-29).',
+    });
+  }
+});
+
+export function assertDateRange(
+  startDate: string,
+  endDate: string,
+  startName = 'start_date',
+  endName = 'end_date',
+): void {
+  if (startDate > endDate) {
+    throw new Error(`${startName} must be on or before ${endName}.`);
+  }
+}
+
+export function assertDateNotInFuture(date: string, today: string): void {
+  if (date > today) {
+    throw new Error(
+      'End date must be today or earlier. Google Search Console has no data for dates that have not happened yet.',
+    );
+  }
+}