@digestseo/mcp-gsc 0.3.1 → 0.4.1

package/src/indexed-pages-range.ts

@@ -0,0 +1,54 @@
+import { assertDateRange } from './date-validation';
+
+export interface IndexedPagesDateRange {
+  startDate: string;
+  endDate: string;
+}
+
+function addUtcDays(date: string, days: number): string {
+  const result = new Date(`${date}T00:00:00Z`);
+  result.setUTCDate(result.getUTCDate() + days);
+  return result.toISOString().slice(0, 10);
+}
+
+export function resolveIndexedPagesDateRange(
+  startDate: string | undefined,
+  endDate: string | undefined,
+  today: string,
+): IndexedPagesDateRange {
+  const latestCompleteDate = addUtcDays(today, -3);
+
+  if (!startDate && !endDate) {
+    return {
+      startDate: addUtcDays(latestCompleteDate, -29),
+      endDate: latestCompleteDate,
+    };
+  }
+
+  if (!startDate) {
+    return {
+      startDate: addUtcDays(endDate!, -29),
+      endDate: endDate!,
+    };
+  }
+
+  if (!endDate) {
+    if (startDate > latestCompleteDate) {
+      throw new Error(
+        `start_date must be on or before ${latestCompleteDate} when end_date is omitted. ` +
+        'The generated end_date cannot be later than the latest complete date.',
+      );
+    }
+    const generatedEndDate = addUtcDays(startDate, 29);
+    return {
+      startDate,
+      endDate:
+        generatedEndDate > latestCompleteDate
+          ? latestCompleteDate
+          : generatedEndDate,
+    };
+  }
+
+  assertDateRange(startDate, endDate);
+  return { startDate, endDate };
+}

package/src/indexing-property-authorization.ts

@@ -0,0 +1,119 @@
+export interface SearchConsoleSite {
+  siteUrl: string;
+  permissionLevel: string;
+}
+
+const SITE_OWNER_PERMISSION = 'siteOwner';
+const DOMAIN_PROPERTY_PREFIX = 'sc-domain:';
+
+function parseHttpUrl(value: string, fieldName: string): URL {
+  if (value !== value.trim() || !/^https?:\/\//i.test(value)) {
+    throw new Error(`${fieldName} must be a fully qualified HTTP or HTTPS URL.`);
+  }
+
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`${fieldName} must be a fully qualified HTTP or HTTPS URL.`);
+  }
+
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error(`${fieldName} must use the HTTP or HTTPS scheme.`);
+  }
+  if (!url.hostname) {
+    throw new Error(`${fieldName} must include a hostname.`);
+  }
+  if (url.username || url.password) {
+    throw new Error(`${fieldName} must not include userinfo.`);
+  }
+
+  return url;
+}
+
+function parseDomainProperty(siteUrl: string): string {
+  const domain = siteUrl.slice(DOMAIN_PROPERTY_PREFIX.length);
+  if (!domain || /[/?#@:]/.test(domain)) {
+    throw new Error('site_url is not a valid Search Console domain property.');
+  }
+
+  const parsed = parseHttpUrl(`https://${domain}`, 'site_url');
+  if (parsed.pathname !== '/' || parsed.search || parsed.hash || parsed.port) {
+    throw new Error('site_url is not a valid Search Console domain property.');
+  }
+
+  return parsed.hostname;
+}
+
+function normalizeSiteUrl(siteUrl: string): string {
+  if (siteUrl.startsWith(DOMAIN_PROPERTY_PREFIX)) {
+    return `${DOMAIN_PROPERTY_PREFIX}${parseDomainProperty(siteUrl)}`;
+  }
+
+  const parsed = parseHttpUrl(siteUrl, 'site_url');
+  if (parsed.search || parsed.hash) {
+    throw new Error('site_url must not include a query string or fragment.');
+  }
+  return parsed.href;
+}
+
+function isWithinUrlPrefix(target: URL, property: URL): boolean {
+  if (target.origin !== property.origin) return false;
+
+  const propertyPath = property.pathname;
+  if (propertyPath === '/') return true;
+  const descendantPrefix = propertyPath.endsWith('/')
+    ? propertyPath
+    : `${propertyPath}/`;
+
+  return (
+    target.pathname === propertyPath ||
+    target.pathname.startsWith(descendantPrefix)
+  );
+}
+
+function isWithinDomainProperty(target: URL, domain: string): boolean {
+  return target.hostname === domain || target.hostname.endsWith(`.${domain}`);
+}
+
+/**
+ * Confirms that an Indexing API URL is contained by an owner-level Search
+ * Console property available to the authenticated account. URL parsing avoids
+ * string-prefix and userinfo lookalike bypasses before any page fetch occurs.
+ */
+export function assertIndexingUrlAuthorized(
+  url: string,
+  siteUrl: string,
+  sites: SearchConsoleSite[],
+): void {
+  const target = parseHttpUrl(url, 'url');
+  const normalizedSiteUrl = normalizeSiteUrl(siteUrl);
+  const authorizedSite = sites.find((site) => {
+    if (site.permissionLevel !== SITE_OWNER_PERMISSION) return false;
+    try {
+      return normalizeSiteUrl(site.siteUrl) === normalizedSiteUrl;
+    } catch {
+      return false;
+    }
+  });
+
+  if (!authorizedSite) {
+    throw new Error(
+      'site_url must be a Search Console property where the authenticated Google account is an owner.',
+    );
+  }
+
+  if (normalizedSiteUrl.startsWith(DOMAIN_PROPERTY_PREFIX)) {
+    if (isWithinDomainProperty(target, parseDomainProperty(normalizedSiteUrl))) {
+      return;
+    }
+  } else if (isWithinUrlPrefix(target, new URL(normalizedSiteUrl))) {
+    return;
+  }
+
+  throw new Error('url must belong to the authorized site_url Search Console property.');
+}
+
+export function assertIndexingRequestUrl(url: string): void {
+  parseHttpUrl(url, 'url');
+}

package/src/pending-auth-state.ts

@@ -0,0 +1,87 @@
+const PENDING_AUTH_TTL_MS = 10 * 60 * 1000;
+
+export interface PendingAuthRequest {
+  claudeAuthRequest: unknown;
+  created_at: number;
+  expires_at: number;
+}
+
+interface PendingAuthStateEnv {
+  PENDING_AUTH_STATE: DurableObjectNamespace;
+}
+
+interface PendingAuthStateStub {
+  store(claudeAuthRequest: unknown): Promise<void>;
+  consume(): Promise<PendingAuthRequest | null>;
+}
+
+/**
+ * One instance is addressed by one OAuth nonce. Its storage transaction makes
+ * consumption a single read-check-delete operation, even for concurrent
+ * callbacks routed to the same Durable Object.
+ */
+/**
+ * Storage-only pending authorization state. Keeping this independent from the
+ * Worker runtime lets the single-use/expiry semantics stay covered by the
+ * fast Node test suite while the exported Durable Object delegates to it.
+ */
+export class PendingAuthStateStore {
+  constructor(
+    private readonly storage: DurableObjectStorage,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  async store(claudeAuthRequest: unknown): Promise<void> {
+    const created_at = this.now();
+    const record: PendingAuthRequest = {
+      claudeAuthRequest,
+      created_at,
+      expires_at: created_at + PENDING_AUTH_TTL_MS,
+    };
+
+    await Promise.all([
+      this.storage.put('pending', record),
+      this.storage.setAlarm(record.expires_at),
+    ]);
+  }
+
+  async consume(): Promise<PendingAuthRequest | null> {
+    return this.storage.transaction(async (txn) => {
+      const record = await txn.get<PendingAuthRequest>('pending');
+      if (!record) return null;
+
+      await txn.delete('pending');
+      await txn.deleteAlarm();
+
+      return record.expires_at > this.now() ? record : null;
+    });
+  }
+
+  async alarm(): Promise<void> {
+    await this.storage.deleteAll();
+  }
+}
+
+function getPendingAuthStateStub(
+  env: PendingAuthStateEnv,
+  nonce: string,
+): PendingAuthStateStub {
+  return env.PENDING_AUTH_STATE.get(
+    env.PENDING_AUTH_STATE.idFromName(nonce),
+  ) as unknown as PendingAuthStateStub;
+}
+
+export async function stashPendingAuth(
+  env: PendingAuthStateEnv,
+  nonce: string,
+  claudeAuthRequest: unknown,
+): Promise<void> {
+  await getPendingAuthStateStub(env, nonce).store(claudeAuthRequest);
+}
+
+export async function consumePendingAuth(
+  env: PendingAuthStateEnv,
+  nonce: string,
+): Promise<PendingAuthRequest | null> {
+  return getPendingAuthStateStub(env, nonce).consume();
+}

package/src/quick-wins-schema.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { SEARCH_CONSOLE_DATE_SCHEMA } from './date-validation';
+import {
+  DEFAULT_ANALYSIS_RESULT_LIMIT,
+  MAX_ANALYSIS_RESULT_LIMIT,
+} from './result-bounds';
+
+const POSITION_RANGE_ERROR = {
+  message: 'min_position must be less than or equal to max_position.',
+  path: ['max_position'],
+};
+
+const QUICK_WINS_THRESHOLDS_SHAPE = {
+  min_impressions: z.number().int().min(0).default(100).describe('Minimum impressions required to consider a query. Must be at least 0. Default is 100.'),
+  min_position: z.number().positive().default(8).describe('Minimum average position to target (inclusive). Must be greater than 0. Default is 8.'),
+  max_position: z.number().positive().default(20).describe('Maximum average position to target (inclusive). Must be greater than 0. Default is 20.'),
+};
+
+export function createQuickWinsInputSchema(siteUrlDescription: string) {
+  return z
+    .object({
+      site_url: z.string().describe(siteUrlDescription),
+      start_date: SEARCH_CONSOLE_DATE_SCHEMA.describe('Start date (inclusive) in YYYY-MM-DD format.'),
+      end_date: SEARCH_CONSOLE_DATE_SCHEMA.describe('End date (inclusive) in YYYY-MM-DD format. Note the 2-3 day GSC data lag.'),
+      ...QUICK_WINS_THRESHOLDS_SHAPE,
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_ANALYSIS_RESULT_LIMIT)
+        .default(DEFAULT_ANALYSIS_RESULT_LIMIT)
+        .describe('Maximum ranked quick-win results to return in this response.'),
+      start_row: z
+        .number()
+        .int()
+        .min(0)
+        .default(0)
+        .describe('Zero-based offset into the ranked quick-win result list.'),
+    })
+    .refine(
+      ({ min_position, max_position }) => min_position <= max_position,
+      POSITION_RANGE_ERROR,
+    );
+}

package/src/result-bounds.ts

@@ -0,0 +1,91 @@
+export const STRUCTURED_RESULT_BYTE_BUDGET = 48_000;
+export const DEFAULT_ANALYSIS_RESULT_LIMIT = 50;
+export const MAX_ANALYSIS_RESULT_LIMIT = 100;
+export const MAX_DIRECT_SOURCE_ROWS = 500;
+
+export interface BoundedItems<T> {
+  items: T[];
+  byteLimitReached: boolean;
+}
+
+function jsonByteLength(value: unknown): number {
+  return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}
+
+/**
+ * Keep one structured-content list inside a conservative byte budget.
+ *
+ * Count limits alone are not sufficient because Search Console keys are
+ * caller-controlled strings (queries and URLs). This helper therefore applies
+ * both the requested item ceiling and an encoded-JSON byte ceiling.
+ */
+export function takeBoundedItems<T>(
+  items: readonly T[],
+  maxItems: number,
+  byteBudget = STRUCTURED_RESULT_BYTE_BUDGET,
+): BoundedItems<T> {
+  if (!Number.isInteger(maxItems) || maxItems < 1) {
+    throw new Error('maxItems must be a positive integer.');
+  }
+  if (!Number.isInteger(byteBudget) || byteBudget < 1) {
+    throw new Error('byteBudget must be a positive integer.');
+  }
+
+  const bounded: T[] = [];
+  // Account for the surrounding JSON array. Per-item commas are added below.
+  let usedBytes = 2;
+  let byteLimitReached = false;
+
+  for (const item of items.slice(0, maxItems)) {
+    const itemBytes = jsonByteLength(item) + (bounded.length > 0 ? 1 : 0);
+    if (usedBytes + itemBytes > byteBudget) {
+      byteLimitReached = true;
+      break;
+    }
+    bounded.push(item);
+    usedBytes += itemBytes;
+  }
+
+  return { items: bounded, byteLimitReached };
+}
+
+export interface ResultPageMetadata {
+  start_row: number;
+  limit: number;
+  returned_count: number;
+  total_count?: number;
+  has_more: boolean;
+  truncated: boolean;
+  byte_limit_reached: boolean;
+  next_start_row?: number;
+}
+
+export function resultPageMetadata(input: {
+  startRow: number;
+  limit: number;
+  returnedCount: number;
+  totalCount?: number;
+  hasMore: boolean;
+  byteLimitReached: boolean;
+}): ResultPageMetadata {
+  const {
+    startRow,
+    limit,
+    returnedCount,
+    totalCount,
+    hasMore,
+    byteLimitReached,
+  } = input;
+  return {
+    start_row: startRow,
+    limit,
+    returned_count: returnedCount,
+    ...(totalCount !== undefined ? { total_count: totalCount } : {}),
+    has_more: hasMore,
+    truncated: hasMore || byteLimitReached,
+    byte_limit_reached: byteLimitReached,
+    ...(hasMore && returnedCount > 0
+      ? { next_start_row: startRow + returnedCount }
+      : {}),
+  };
+}

package/src/storage.ts

@@ -1,98 +1,65 @@
-import { encryptToken, decryptToken } from './crypto';
-
-interface StorageEnv {
-  OAUTH_KV: KVNamespace;
-  USER_KV: KVNamespace;
-  TOKEN_ENCRYPTION_KEY: string;
-}
-
-const PENDING_TTL_SECONDS = 600;
-
-export interface PendingAuthRequest {
-  claudeAuthRequest: unknown;
-  created_at: number;
-}
-
-export async function stashPendingAuth(
-  env: StorageEnv,
-  nonce: string,
-  claudeAuthRequest: unknown,
-): Promise<void> {
-  const record: PendingAuthRequest = {
-    claudeAuthRequest,
-    created_at: Date.now(),
-  };
-  await env.OAUTH_KV.put(`pending:${nonce}`, JSON.stringify(record), {
-    expirationTtl: PENDING_TTL_SECONDS,
-  });
-}
-
-export async function popPendingAuth(
-  env: StorageEnv,
-  nonce: string,
-): Promise<PendingAuthRequest | null> {
-  const key = `pending:${nonce}`;
-  const raw = await env.OAUTH_KV.get(key);
-  if (!raw) return null;
-  await env.OAUTH_KV.delete(key);
-  return JSON.parse(raw) as PendingAuthRequest;
-}
-
-export interface UserRecord {
-  email: string;
-  encrypted_refresh_token: string;
-  iv: string;
-  created_at: number;
-  updated_at: number;
-}
-
-export async function saveUser(
-  env: StorageEnv,
-  googleId: string,
-  email: string,
-  refreshToken: string,
-): Promise<void> {
-  const { ciphertext, iv } = await encryptToken(
-    refreshToken,
-    env.TOKEN_ENCRYPTION_KEY,
-  );
-  const existing = await getUser(env, googleId);
-  const now = Date.now();
-  const record: UserRecord = {
-    email,
-    encrypted_refresh_token: ciphertext,
-    iv,
-    created_at: existing?.created_at ?? now,
-    updated_at: now,
-  };
-  await env.USER_KV.put(`user:${googleId}`, JSON.stringify(record));
-}
-
-export async function getUser(
-  env: StorageEnv,
-  googleId: string,
-): Promise<UserRecord | null> {
-  const raw = await env.USER_KV.get(`user:${googleId}`);
-  if (!raw) return null;
-  return JSON.parse(raw) as UserRecord;
-}
-
-export async function deleteUser(
-  env: StorageEnv,
-  googleId: string,
-): Promise<void> {
-  await env.USER_KV.delete(`user:${googleId}`);
-}
-
-export async function getDecryptedRefreshToken(
-  env: StorageEnv,
-  googleId: string,
-): Promise<string | null> {
-  const user = await getUser(env, googleId);
-  if (!user) return null;
-  return await decryptToken(
-    user.encrypted_refresh_token,
-    user.iv,
-    env.TOKEN_ENCRYPTION_KEY,
-  );
-}
+import { encryptToken, decryptToken } from './crypto';
+
+interface StorageEnv {
+  USER_KV: KVNamespace;
+  TOKEN_ENCRYPTION_KEY: string;
+}
+
+export interface UserRecord {
+  email: string;
+  encrypted_refresh_token: string;
+  iv: string;
+  created_at: number;
+  updated_at: number;
+}
+
+export async function saveUser(
+  env: StorageEnv,
+  googleId: string,
+  email: string,
+  refreshToken: string,
+): Promise<void> {
+  const { ciphertext, iv } = await encryptToken(
+    refreshToken,
+    env.TOKEN_ENCRYPTION_KEY,
+  );
+  const existing = await getUser(env, googleId);
+  const now = Date.now();
+  const record: UserRecord = {
+    email,
+    encrypted_refresh_token: ciphertext,
+    iv,
+    created_at: existing?.created_at ?? now,
+    updated_at: now,
+  };
+  await env.USER_KV.put(`user:${googleId}`, JSON.stringify(record));
+}
+
+export async function getUser(
+  env: StorageEnv,
+  googleId: string,
+): Promise<UserRecord | null> {
+  const raw = await env.USER_KV.get(`user:${googleId}`);
+  if (!raw) return null;
+  return JSON.parse(raw) as UserRecord;
+}
+
+export async function deleteUser(
+  env: StorageEnv,
+  googleId: string,
+): Promise<void> {
+  await env.USER_KV.delete(`user:${googleId}`);
+}
+
+export async function getDecryptedRefreshToken(
+  env: StorageEnv,
+  googleId: string,
+): Promise<string | null> {
+  const user = await getUser(env, googleId);
+  if (!user) return null;
+  return await decryptToken(
+    user.encrypted_refresh_token,
+    user.iv,
+    env.TOKEN_ENCRYPTION_KEY,
+  );
+}