gscdump 1.4.11 → 1.5.1

package/dist/index.d.mts

@@ -18,7 +18,7 @@ import { hasGscReadScope, hasGscWriteScope, hasIndexingScope } from "./core/scop
 import { ParsedGscSiteUrl, normalizeGscSiteUrl, normalizeRegistrationTarget, parseGscSiteUrl } from "./core/site-url.mjs";
 import { normalizeUrl } from "./normalize.mjs";
 import { AccountNextAction, AccountStatus, AnalyticsNextAction, AnalyticsStatus, GSCDUMP_ONBOARDING_CONTRACT_VERSION, GSCDUMP_OPTIONAL_INDEXING_SCOPE, GSCDUMP_REQUIRED_ANALYTICS_SCOPE, GSCDUMP_WRITE_ANALYTICS_SCOPE, IndexingNextAction, IndexingStatus, LifecycleError, LifecycleErrorCode, LifecycleProgress, LifecycleWebhookEnvelope, LifecycleWebhookEvent, PartnerLifecycleAccount, PartnerLifecycleResponse, PartnerLifecycleSite, PropertyNextAction, PropertyStatus, QuerySourceMode, SitemapNextAction, SitemapStatus, accountNextActions, accountStatuses, analyticsNextActions, analyticsStatuses, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, lifecycleErrorCodes, parseGrantedScopes, propertyNextActions, propertyStatuses, querySourceModes, sitemapNextActions, sitemapStatuses } from "./onboarding.mjs";
-import { DiscoverSitemapOptions, FetchSitemapUrlsOptions, discoverSitemap, fetchSitemapUrls } from "./sitemap.mjs";
+import { discoverSitemap, fetchSitemapUrls } from "./sitemap-compat.mjs";
 import { decodeSiteId, encodeSiteId, normalizeSiteUrl } from "./tenant.mjs";
 import { urlMatchKey } from "./url.mjs";
-export { type AccountNextAction, type AccountStatus, AmpInspectionResult, AmpIssue, type AnalyticsNextAction, type AnalyticsStatus, ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, type BackfillProgress, BatchInspectUrlsFlatSettledOptions, CallOptions, CanonicalDifferenceKind, DAYS_PER_RANGE, DEFAULT_GSC_REQUEST_TIMEOUT_MS, DataRow, DimensionFilter, DimensionFilterGroup, DiscoverSitemapOptions, Err, FetchSitemapUrlsOptions, FetchSitesWithSitemapsOptions, GSCDUMP_ONBOARDING_CONTRACT_VERSION, GSCDUMP_OPTIONAL_INDEXING_SCOPE, GSCDUMP_REQUIRED_ANALYTICS_SCOPE, GSCDUMP_WRITE_ANALYTICS_SCOPE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_INDEXING_SCOPE, GSC_READ_SCOPE, GSC_RETENTION_MONTHS, GSC_SITE_VERIFICATION_SCOPE, GSC_WRITE_SCOPE, GoogleSearchConsoleClient, GoogleSearchConsoleClientOptions, GscApiError, type GscApiErrorInfo, type GscError, type GscErrorKind, GscPropertyCandidate, INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, IndexStatusResult, IndexingEligibility, IndexingIneligibleReason, IndexingIssueType, IndexingMetadata, type IndexingNextAction, IndexingNotificationType, IndexingResult, type IndexingStatus, InspectUrlFlatSettledResult, InspectUrlIndexResponse, InspectUrlResult, InspectionPriority, KNOWN_COVERAGE_STATES, KNOWN_PAGE_FETCH_STATES, LegacyInspectionPriority, type LifecycleError, type LifecycleErrorCode, type LifecycleProgress, type LifecycleWebhookEnvelope, type LifecycleWebhookEvent, MAX_FLAT_INSPECTION_BATCH_CONCURRENCY, MS_PER_DAY, MobileUsabilityIssue, MobileUsabilityResult, OAuthTokenInfo, OAuthTokens, Ok, ParsedGscSiteUrl, ParsedIndexingResult, type PartnerLifecycleAccount, type PartnerLifecycleResponse, type PartnerLifecycleSite, Period, type PropertyNextAction, type PropertyStatus, PublishUrlNotificationResponse, QueryReturn, type QuerySourceMode, RequiredNonNullable, ResolvedAnalyticsRange, Result, RichResultsDetectedItem, RichResultsIssue, RichResultsItem, RichResultsResult, SearchAnalyticsMetadata, SearchAnalyticsQuery, SearchAnalyticsResponse, Site, SiteAnalytics, type SitemapNextAction, type SitemapStatus, URL_INSPECTION_EFFECTIVE_LIMIT, UnmappedInspectionReasons, UrlInspectionResult, UrlNotification, UrlNotificationMetadata, ValueWeightedInspectionPriority, VerificationMethod, VerificationSite, VerificationSiteType, VerificationToken, VerificationWebResource, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchInspectUrlsFlatSettled, batchRequestIndexing, canUseUrlInspection, classifyCanonicalDifference, classifyError, countDays, createAuth, createFetch, decodeSiteId, deleteSite, deleteSitemap, discoverSitemap, encodeSiteId, err, exchangeAuthCodeResult, fetchSitemap, fetchSitemapUrls, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, findBestGscProperty, findExactGscProperty, formatGscPropertyCandidates, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getIndexingEligibility, getIndexingMetadata, getLatestGscDate, getNextCheckAfter, getNextCheckPriority, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, getVerificationToken, getVerifiedSite, googleSearchConsole, groupIntoRanges, gscErrorToException, gscPropertyMatchesTarget, hasGoogleScope, hasGscReadScope, hasGscWriteScope, hasIndexingScope, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, inspectUrl, inspectUrlFlat, introspectAccessToken, introspectAccessTokenResult, isCanonicalMismatch, isErr, isFragmentUrl, isOk, isPermissionDeniedError, isValidGscDate, isVerifiedGscPermission, isVerifiedGscProperty, lifecycleErrorCodes, listVerifiedSites, matchGscSite, normalizeGscSiteUrl, normalizeRegistrationTarget, normalizeSiteUrl, normalizeUrl, ok, parseGoogleError, parseGrantedScopes, parseGscSiteUrl, pickBestGscProperty, propertyNextActions, propertyStatuses, querySourceModes, refreshAccessToken, requestIndexing, resolveVerificationTarget, rethrowAsGscApiError, revokeOAuthToken, revokeOAuthTokenResult, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, submitSitemap, toIsoDate, unmappedInspectionReasons, unverifySite, unwrapResult, urlMatchKey, verificationMethodsFor, verifySite };
+export { type AccountNextAction, type AccountStatus, AmpInspectionResult, AmpIssue, type AnalyticsNextAction, type AnalyticsStatus, ApiSite, ApiSitemap, ApiSitemapContent, Auth, AuthClient, AuthOptions, type BackfillProgress, BatchInspectUrlsFlatSettledOptions, CallOptions, CanonicalDifferenceKind, DAYS_PER_RANGE, DEFAULT_GSC_REQUEST_TIMEOUT_MS, DataRow, DimensionFilter, DimensionFilterGroup, Err, FetchSitesWithSitemapsOptions, GSCDUMP_ONBOARDING_CONTRACT_VERSION, GSCDUMP_OPTIONAL_INDEXING_SCOPE, GSCDUMP_REQUIRED_ANALYTICS_SCOPE, GSCDUMP_WRITE_ANALYTICS_SCOPE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_INDEXING_SCOPE, GSC_READ_SCOPE, GSC_RETENTION_MONTHS, GSC_SITE_VERIFICATION_SCOPE, GSC_WRITE_SCOPE, GoogleSearchConsoleClient, GoogleSearchConsoleClientOptions, GscApiError, type GscApiErrorInfo, type GscError, type GscErrorKind, GscPropertyCandidate, INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, IndexStatusResult, IndexingEligibility, IndexingIneligibleReason, IndexingIssueType, IndexingMetadata, type IndexingNextAction, IndexingNotificationType, IndexingResult, type IndexingStatus, InspectUrlFlatSettledResult, InspectUrlIndexResponse, InspectUrlResult, InspectionPriority, KNOWN_COVERAGE_STATES, KNOWN_PAGE_FETCH_STATES, LegacyInspectionPriority, type LifecycleError, type LifecycleErrorCode, type LifecycleProgress, type LifecycleWebhookEnvelope, type LifecycleWebhookEvent, MAX_FLAT_INSPECTION_BATCH_CONCURRENCY, MS_PER_DAY, MobileUsabilityIssue, MobileUsabilityResult, OAuthTokenInfo, OAuthTokens, Ok, ParsedGscSiteUrl, ParsedIndexingResult, type PartnerLifecycleAccount, type PartnerLifecycleResponse, type PartnerLifecycleSite, Period, type PropertyNextAction, type PropertyStatus, PublishUrlNotificationResponse, QueryReturn, type QuerySourceMode, RequiredNonNullable, ResolvedAnalyticsRange, Result, RichResultsDetectedItem, RichResultsIssue, RichResultsItem, RichResultsResult, SearchAnalyticsMetadata, SearchAnalyticsQuery, SearchAnalyticsResponse, Site, SiteAnalytics, type SitemapNextAction, type SitemapStatus, URL_INSPECTION_EFFECTIVE_LIMIT, UnmappedInspectionReasons, UrlInspectionResult, UrlNotification, UrlNotificationMetadata, ValueWeightedInspectionPriority, VerificationMethod, VerificationSite, VerificationSiteType, VerificationToken, VerificationWebResource, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchInspectUrlsFlatSettled, batchRequestIndexing, canUseUrlInspection, classifyCanonicalDifference, classifyError, countDays, createAuth, createFetch, decodeSiteId, deleteSite, deleteSitemap, discoverSitemap, encodeSiteId, err, exchangeAuthCodeResult, fetchSitemap, fetchSitemapUrls, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, findBestGscProperty, findExactGscProperty, formatGscPropertyCandidates, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getIndexingEligibility, getIndexingMetadata, getLatestGscDate, getNextCheckAfter, getNextCheckPriority, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, getVerificationToken, getVerifiedSite, googleSearchConsole, groupIntoRanges, gscErrorToException, gscPropertyMatchesTarget, hasGoogleScope, hasGscReadScope, hasGscWriteScope, hasIndexingScope, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, inspectUrl, inspectUrlFlat, introspectAccessToken, introspectAccessTokenResult, isCanonicalMismatch, isErr, isFragmentUrl, isOk, isPermissionDeniedError, isValidGscDate, isVerifiedGscPermission, isVerifiedGscProperty, lifecycleErrorCodes, listVerifiedSites, matchGscSite, normalizeGscSiteUrl, normalizeRegistrationTarget, normalizeSiteUrl, normalizeUrl, ok, parseGoogleError, parseGrantedScopes, parseGscSiteUrl, pickBestGscProperty, propertyNextActions, propertyStatuses, querySourceModes, refreshAccessToken, requestIndexing, resolveVerificationTarget, rethrowAsGscApiError, revokeOAuthToken, revokeOAuthTokenResult, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, submitSitemap, toIsoDate, unmappedInspectionReasons, unverifySite, unwrapResult, urlMatchKey, verificationMethodsFor, verifySite };

package/dist/index.mjs

@@ -18,7 +18,7 @@ import { URL_INSPECTION_EFFECTIVE_LIMIT } from "./core/quota.mjs";
 import "./core/types.mjs";
 import { normalizeUrl } from "./normalize.mjs";
 import { GSCDUMP_ONBOARDING_CONTRACT_VERSION, GSCDUMP_OPTIONAL_INDEXING_SCOPE, GSCDUMP_REQUIRED_ANALYTICS_SCOPE, GSCDUMP_WRITE_ANALYTICS_SCOPE, accountNextActions, accountStatuses, analyticsNextActions, analyticsStatuses, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, lifecycleErrorCodes, parseGrantedScopes, propertyNextActions, propertyStatuses, querySourceModes, sitemapNextActions, sitemapStatuses } from "./onboarding.mjs";
-import { discoverSitemap, fetchSitemapUrls } from "./sitemap.mjs";
+import { discoverSitemap, fetchSitemapUrls } from "./sitemap-compat.mjs";
 import { decodeSiteId, encodeSiteId, normalizeSiteUrl } from "./tenant.mjs";
 import { urlMatchKey } from "./url.mjs";
 export { DAYS_PER_RANGE, DEFAULT_GSC_REQUEST_TIMEOUT_MS, GSCDUMP_ONBOARDING_CONTRACT_VERSION, GSCDUMP_OPTIONAL_INDEXING_SCOPE, GSCDUMP_REQUIRED_ANALYTICS_SCOPE, GSCDUMP_WRITE_ANALYTICS_SCOPE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_INDEXING_SCOPE, GSC_READ_SCOPE, GSC_RETENTION_MONTHS, GSC_SITE_VERIFICATION_SCOPE, GSC_WRITE_SCOPE, GscApiError, INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, KNOWN_COVERAGE_STATES, KNOWN_PAGE_FETCH_STATES, MAX_FLAT_INSPECTION_BATCH_CONCURRENCY, MS_PER_DAY, URL_INSPECTION_EFFECTIVE_LIMIT, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchInspectUrlsFlatSettled, batchRequestIndexing, canUseUrlInspection, classifyCanonicalDifference, classifyError, countDays, createAuth, createFetch, decodeSiteId, deleteSite, deleteSitemap, discoverSitemap, encodeSiteId, err, exchangeAuthCodeResult, fetchSitemap, fetchSitemapUrls, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, findBestGscProperty, findExactGscProperty, formatGscPropertyCandidates, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getIndexingEligibility, getIndexingMetadata, getLatestGscDate, getNextCheckAfter, getNextCheckPriority, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, getVerificationToken, getVerifiedSite, googleSearchConsole, groupIntoRanges, gscErrorToException, gscPropertyMatchesTarget, hasGoogleScope, hasGscReadScope, hasGscWriteScope, hasIndexingScope, hasOptionalIndexingScope, hasRequiredAnalyticsScope, indexingNextActions, indexingStatuses, inspectUrl, inspectUrlFlat, introspectAccessToken, introspectAccessTokenResult, isCanonicalMismatch, isErr, isFragmentUrl, isOk, isPermissionDeniedError, isValidGscDate, isVerifiedGscPermission, isVerifiedGscProperty, lifecycleErrorCodes, listVerifiedSites, matchGscSite, normalizeGscSiteUrl, normalizeRegistrationTarget, normalizeSiteUrl, normalizeUrl, ok, parseGoogleError, parseGrantedScopes, parseGscSiteUrl, pickBestGscProperty, propertyNextActions, propertyStatuses, querySourceModes, refreshAccessToken, requestIndexing, resolveVerificationTarget, rethrowAsGscApiError, revokeOAuthToken, revokeOAuthTokenResult, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, submitSitemap, toIsoDate, unmappedInspectionReasons, unverifySite, unwrapResult, urlMatchKey, verificationMethodsFor, verifySite };

package/dist/sitemap-compat.d.mts

@@ -0,0 +1,8 @@
+import { DiscoverSitemapOptions, FetchSitemapUrlsOptions } from "./sitemap.mjs";
+/**
+ * Keep the v1 root exports without making every `gscdump` import initialize
+ * Nuxt Sitemap. The parser remains isolated behind the `./sitemap` entry.
+ */
+declare function discoverSitemap(site: string, options?: DiscoverSitemapOptions): Promise<string | null>;
+declare function fetchSitemapUrls(sitemapUrl: string, options?: FetchSitemapUrlsOptions): Promise<string[]>;
+export { discoverSitemap, fetchSitemapUrls };

package/dist/sitemap-compat.mjs

@@ -0,0 +1,7 @@
+async function discoverSitemap(site, options = {}) {
+	return (await import("./sitemap.mjs")).discoverSitemap(site, options);
+}
+async function fetchSitemapUrls(sitemapUrl, options = {}) {
+	return (await import("./sitemap.mjs")).fetchSitemapUrls(sitemapUrl, options);
+}
+export { discoverSitemap, fetchSitemapUrls };

package/dist/sitemap.d.mts

@@ -1,26 +1,179 @@
-interface DiscoverSitemapOptions {
-  /** User-Agent sent on the discovery requests. */
-  userAgent?: string;
-  /** AbortSignal threaded through fetches; defaults to a 10s timeout per call. */
+interface SitemapUrlEntry {
+  loc: string;
+  lastmod?: string;
+  changefreq?: string;
+  priority?: number;
+}
+interface SitemapIndexEntry {
+  loc: string;
+  lastmod?: string;
+}
+interface SitemapDocumentMeta {
+  bytesRead: number;
+  complete: boolean;
+  hasBom: boolean;
+  hasXmlDeclaration: boolean;
+  namespace: string | null;
+}
+type SitemapDocumentResult = {
+  _tag: 'urlset';
+  entries: SitemapUrlEntry[];
+  meta: SitemapDocumentMeta;
+} | {
+  _tag: 'index';
+  entries: SitemapIndexEntry[];
+  meta: SitemapDocumentMeta;
+} | {
+  _tag: 'empty_body';
+} | {
+  _tag: 'html';
+  metaRefreshUrl?: string;
+} | {
+  _tag: 'byte_limit';
+  bytesRead: number;
+  maxBytes: number;
+} | {
+  _tag: 'parse_error';
+  error: string;
+} | {
+  _tag: 'unsupported_document';
+  root: string | null;
+};
+interface ParseSitemapDocumentOptions {
+  maxBytes?: number;
+  maxEntries?: number;
+  acceptUrl?: (entry: SitemapUrlEntry) => boolean;
+}
+type SitemapBody = string | Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
+interface SitemapFetchOptions extends ParseSitemapDocumentOptions {
+  fetcher?: typeof fetch;
+  headers?: HeadersInit;
   signal?: AbortSignal;
+  timeoutMs?: number;
+}
+type SitemapFetchResult = {
+  _tag: 'ok';
+  url: string;
+  document: Extract<SitemapDocumentResult, {
+    _tag: 'urlset' | 'index';
+  }>;
+} | {
+  _tag: 'not_found';
+  url: string;
+  status: 404 | 410;
+} | {
+  _tag: 'http_error';
+  url: string;
+  status: number;
+  statusText: string;
+} | {
+  _tag: 'network_error';
+  url: string;
+  error: string;
+} | {
+  _tag: 'document_error';
+  url: string;
+  error: Exclude<SitemapDocumentResult, {
+    _tag: 'urlset' | 'index';
+  }>;
+};
+interface DiscoverSitemapOptions extends SitemapFetchOptions {
+  userAgent?: string;
+}
+interface SitemapDiscoveryFailure {
+  url: string;
+  kind: 'http' | 'network' | 'document';
+  detail: string;
+}
+type SitemapDiscoveryResult = {
+  _tag: 'found';
+  url: string;
+  source: 'common_path' | 'robots';
+} | {
+  _tag: 'not_found';
+} | {
+  _tag: 'incomplete';
+  failures: SitemapDiscoveryFailure[];
+};
+interface WalkSitemapsOptions extends SitemapFetchOptions {
+  maxDepth?: number;
+  maxDocuments?: number;
+  maxUrls?: number;
 }
-/**
- * Try to discover a sitemap for `domain` by checking robots.txt for a
- * `Sitemap:` directive, then a small set of common paths. Returns the first
- * URL that responds with a 2xx, or `null`.
- */
-declare function discoverSitemap(domain: string, options?: DiscoverSitemapOptions): Promise<string | null>;
 interface FetchSitemapUrlsOptions extends DiscoverSitemapOptions {
-  /** Maximum nested sitemap-index depth to follow. Default 3. */
   maxDepth?: number;
-  /** Stop after this many URLs (across all nested sitemaps). Default unlimited. */
   limit?: number;
 }
+interface SitemapWalkFailure {
+  url: string;
+  depth: number;
+  error: Exclude<SitemapFetchResult, {
+    _tag: 'ok';
+  }>;
+}
+type SitemapWalkResult = {
+  _tag: 'ok';
+  entries: SitemapUrlEntry[];
+  documentsRead: number;
+  complete: boolean;
+  failures: SitemapWalkFailure[];
+} | {
+  _tag: 'not_found';
+} | {
+  _tag: 'error';
+  failures: SitemapWalkFailure[];
+};
+type SitemapIdentityResult = {
+  _tag: 'ok';
+  url: string;
+} | {
+  _tag: 'invalid';
+  reason: 'empty' | 'invalid_url' | 'off_origin';
+};
+interface SitemapEvidenceRecord {
+  path: string;
+  lastDownloaded?: string | null;
+  fetchedAt?: number | null;
+}
+interface ScopedSitemapRecords<T extends SitemapEvidenceRecord> {
+  sitemaps: Array<T & {
+    path: string;
+  }>;
+  excludedCount: number;
+  duplicateCount: number;
+}
+/**
+ * Streaming sitemap parser backed by the same utility Nuxt Sitemap consumers
+ * previously used. Expected failures are tagged values.
+ * Entry limits produce a useful partial document with `meta.complete = false`;
+ * byte limits fail closed because the document boundary was not observed.
+ */
+declare function parseSitemapDocument(body: SitemapBody, options?: ParseSitemapDocumentOptions): Promise<SitemapDocumentResult>;
+declare function fetchSitemapDocument(url: string, options?: SitemapFetchOptions): Promise<SitemapFetchResult>;
+declare function parseRobotsSitemapUrls(robots: string, baseUrl?: string): string[];
+declare function canonicalSitemapIdentity(path: string, site?: string): SitemapIdentityResult;
+declare function sameSitemapIdentity(left: string, right: string, site?: string): boolean;
+declare function scopeSitemapRecords<T extends SitemapEvidenceRecord>(records: readonly T[], site?: string): ScopedSitemapRecords<T>;
+/**
+ * Discover a real sitemap document. A 200 HTML shell is rejected, and
+ * transport failures remain distinguishable from an authoritative miss.
+ */
+declare function discoverSitemapResult(site: string, options?: DiscoverSitemapOptions): Promise<SitemapDiscoveryResult>;
+/**
+ * Compatibility surface retained at the package root. New callers that need
+ * explicit incomplete-discovery evidence should use `discoverSitemapResult`.
+ */
+declare function discoverSitemap(site: string, options?: DiscoverSitemapOptions): Promise<string | null>;
+/**
+ * Bounded sitemap and sitemap-index walk. Partial results are explicit through
+ * `complete` and `failures`; callers must not infer removals from an incomplete
+ * walk.
+ */
+declare function walkSitemaps(roots: string | readonly string[], options?: WalkSitemapsOptions): Promise<SitemapWalkResult>;
 /**
- * Fetch a sitemap (or sitemap index) and return the list of `<loc>` URLs.
- * Sitemap-index files are followed up to `maxDepth` levels. Duplicates are
- * de-duplicated. The XML parser is regex-based — it handles the common
- * `<loc>https://...</loc>` shape but doesn't validate the schema.
+ * Compatibility surface retained at the package root. The shared parser and
+ * traversal own the work while the original string-array contract remains.
  */
 declare function fetchSitemapUrls(sitemapUrl: string, options?: FetchSitemapUrlsOptions): Promise<string[]>;
-export { DiscoverSitemapOptions, FetchSitemapUrlsOptions, discoverSitemap, fetchSitemapUrls };
+declare function sitemapContentHash(entries: readonly Pick<SitemapUrlEntry, 'loc'>[]): Promise<string>;
+export { DiscoverSitemapOptions, FetchSitemapUrlsOptions, ParseSitemapDocumentOptions, ScopedSitemapRecords, SitemapBody, SitemapDiscoveryFailure, SitemapDiscoveryResult, SitemapDocumentMeta, SitemapDocumentResult, SitemapEvidenceRecord, SitemapFetchOptions, SitemapFetchResult, SitemapIdentityResult, SitemapIndexEntry, SitemapUrlEntry, SitemapWalkFailure, SitemapWalkResult, WalkSitemapsOptions, canonicalSitemapIdentity, discoverSitemap, discoverSitemapResult, fetchSitemapDocument, fetchSitemapUrls, parseRobotsSitemapUrls, parseSitemapDocument, sameSitemapIdentity, scopeSitemapRecords, sitemapContentHash, walkSitemaps };

package/dist/sitemap.mjs

@@ -1,70 +1,670 @@
-const FETCH_TIMEOUT_MS = 1e4;
-const COMMON_PATHS = ["/sitemap.xml", "/sitemap_index.xml"];
-const SITEMAP_DIRECTIVE_RE = /^Sitemap:\s*(\S+)/im;
-async function discoverSitemap(domain, options = {}) {
-	const userAgent = options.userAgent ?? "gscdump sitemap fetcher";
-	const baseUrl = `https://${domain}`;
-	const signalFor = () => options.signal ?? AbortSignal.timeout(FETCH_TIMEOUT_MS);
-	const robotsRes = await fetch(`${baseUrl}/robots.txt`, {
-		headers: { "User-Agent": userAgent },
-		signal: signalFor()
-	}).catch(() => null);
-	if (robotsRes?.ok) {
-		const match = (await robotsRes.text()).match(SITEMAP_DIRECTIVE_RE);
-		if (match?.[1]) {
-			if ((await fetch(match[1], {
-				method: "HEAD",
-				signal: signalFor()
-			}).catch(() => null))?.ok) return match[1];
-		}
-	}
-	for (const path of COMMON_PATHS) {
-		const url = `${baseUrl}${path}`;
-		if ((await fetch(url, {
-			method: "HEAD",
-			headers: { "User-Agent": userAgent },
-			signal: signalFor()
-		}).catch(() => null))?.ok) return url;
-	}
-	return null;
-}
-const LOC_RE = /<loc>([^<]+)<\/loc>/gi;
-const SITEMAPINDEX_RE = /<sitemapindex\b/i;
-async function fetchSitemapUrls(sitemapUrl, options = {}) {
-	const userAgent = options.userAgent ?? "gscdump sitemap fetcher";
-	const maxDepth = options.maxDepth ?? 3;
-	const limit = options.limit;
-	const signalFor = () => options.signal ?? AbortSignal.timeout(FETCH_TIMEOUT_MS);
+import { urlMatchKey } from "./url.mjs";
+import { parseSitemapStream } from "@nuxtjs/sitemap/utils";
+const DEFAULT_FETCH_TIMEOUT_MS = 1e4;
+const DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
+const DEFAULT_MAX_ENTRIES = 5e4;
+const DEFAULT_MAX_DEPTH = 3;
+const DEFAULT_MAX_DOCUMENTS = 100;
+const SNIFF_BYTES = 65536;
+const COMMON_SITEMAP_PATHS = [
+	"/sitemap.xml",
+	"/sitemap_index.xml",
+	"/sitemap-index.xml",
+	"/sitemaps.xml"
+];
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function looksLikeHtml(prefix) {
+	const start = prefix.trimStart().replace(/^\uFEFF/, "").replace(/^<\?xml[\s\S]*?\?>\s*/i, "").replace(/^(?:<!--[\s\S]*?-->\s*)+/, "");
+	return /^<!doctype\s+html\b|^<html\b/i.test(start);
+}
+function extractMetaRefreshUrl(html) {
+	return /content=["']?\d+;\s*url=([^"'\s>]+)/i.exec(html)?.[1];
+}
+function isAsyncIterable(value) {
+	return typeof value === "object" && value !== null && Symbol.asyncIterator in value;
+}
+async function* readableStreamChunks(stream) {
+	const reader = stream.getReader();
+	let done = false;
+	try {
+		while (!done) {
+			const next = await reader.read();
+			done = next.done;
+			if (next.value) yield next.value;
+		}
+	} finally {
+		if (!done) await reader.cancel("sitemap reader stopped before the response body completed");
+	}
+}
+async function* bodyChunks(body) {
+	if (typeof body === "string") {
+		yield new TextEncoder().encode(body);
+		return;
+	}
+	if (body instanceof Uint8Array) {
+		yield body;
+		return;
+	}
+	if (isAsyncIterable(body)) {
+		yield* body;
+		return;
+	}
+	yield* readableStreamChunks(body);
+}
+function replayStream(reader, initial) {
+	let offset = 0;
+	return new ReadableStream({
+		async pull(controller) {
+			if (offset < initial.length) {
+				controller.enqueue(initial[offset++]);
+				return;
+			}
+			const next = await reader.read();
+			if (next.done) {
+				controller.close();
+				return;
+			}
+			if (next.value) controller.enqueue(next.value);
+		},
+		async cancel(reason) {
+			await reader.cancel(reason);
+		}
+	});
+}
+async function bodyWithDetectedCompression(body) {
+	const reader = body.getReader();
+	const initial = [];
+	let prefixLength = 0;
+	while (prefixLength < 2) {
+		const next = await reader.read();
+		if (next.done) break;
+		if (next.value) {
+			initial.push(next.value);
+			prefixLength += next.value.byteLength;
+		}
+	}
+	const prefix = initial.length === 1 ? initial[0] : Uint8Array.from(initial.flatMap((chunk) => [...chunk]));
+	const replay = replayStream(reader, initial);
+	if (!(prefix.length >= 2 && prefix[0] === 31 && prefix[1] === 139)) return replay;
+	if (typeof DecompressionStream === "undefined") {
+		await replay.cancel("gzip decompression is unavailable in this runtime");
+		throw new Error("gzip sitemap body requires DecompressionStream support");
+	}
+	return replay.pipeThrough(new DecompressionStream("gzip"));
+}
+function sitemapInputBoundaryError(bytesRead, maxBytes) {
+	return Object.assign(/* @__PURE__ */ new Error(`Sitemap exceeds ${maxBytes} bytes`), {
+		_tag: "byte_limit",
+		bytesRead,
+		maxBytes
+	});
+}
+function isSitemapInputBoundaryError(error) {
+	return error !== null && typeof error === "object" && "_tag" in error && error._tag === "byte_limit";
+}
+async function* replaySitemapInput(initial, iterator, stats, maxBytes) {
+	let done = false;
+	try {
+		yield* initial;
+		while (!done) {
+			const next = await iterator.next();
+			done = Boolean(next.done);
+			if (!next.value) continue;
+			const bytesRead = stats.bytesRead + next.value.byteLength;
+			if (bytesRead > maxBytes) throw sitemapInputBoundaryError(bytesRead, maxBytes);
+			stats.bytesRead = bytesRead;
+			yield next.value;
+		}
+	} finally {
+		if (!done) await iterator.return?.(void 0);
+	}
+}
+async function prepareSitemapInput(body, maxBytes) {
+	const iterator = bodyChunks(body)[Symbol.asyncIterator]();
+	const decoder = new TextDecoder("utf-8", { ignoreBOM: true });
+	const initial = [];
+	const stats = {
+		bytesRead: 0,
+		prefix: "",
+		hasContent: false,
+		hasBom: false
+	};
+	let done = false;
+	while (stats.prefix.length < SNIFF_BYTES && !done) {
+		const next = await iterator.next();
+		done = Boolean(next.done);
+		if (!next.value) continue;
+		const bytesRead = stats.bytesRead + next.value.byteLength;
+		if (bytesRead > maxBytes) {
+			await iterator.return?.(void 0);
+			return {
+				_tag: "byte_limit",
+				bytesRead,
+				maxBytes
+			};
+		}
+		initial.push(next.value);
+		stats.bytesRead = bytesRead;
+		const text = decoder.decode(next.value, { stream: true });
+		stats.prefix += text.slice(0, SNIFF_BYTES - stats.prefix.length);
+	}
+	if (done && stats.prefix.length < SNIFF_BYTES) stats.prefix += decoder.decode();
+	stats.hasContent = Boolean(stats.prefix.trim());
+	stats.hasBom = stats.prefix.charCodeAt(0) === 65279;
+	if (!stats.hasContent) {
+		await iterator.return?.(void 0);
+		return { _tag: "empty_body" };
+	}
+	if (looksLikeHtml(stats.prefix)) {
+		await iterator.return?.(void 0);
+		const metaRefreshUrl = extractMetaRefreshUrl(stats.prefix);
+		return {
+			_tag: "html",
+			...metaRefreshUrl ? { metaRefreshUrl } : {}
+		};
+	}
+	return {
+		_tag: "ready",
+		input: replaySitemapInput(initial, iterator, stats, maxBytes),
+		stats
+	};
+}
+function normalizeSitemapUrlInput(input) {
+	if (typeof input === "string") return { loc: input };
+	if (!input.loc) return null;
+	const lastmod = input.lastmod instanceof Date ? input.lastmod.toISOString() : input.lastmod;
+	return {
+		loc: input.loc,
+		...lastmod ? { lastmod } : {},
+		...input.changefreq ? { changefreq: input.changefreq } : {},
+		...input.priority !== void 0 ? { priority: input.priority } : {}
+	};
+}
+function rootMetadata(prefix) {
+	const rootMatch = /<(?:[\w.-]+:)?(urlset|sitemapindex)\b([^>]*)>/i.exec(prefix);
+	if (!rootMatch) return {
+		root: /<(?:[\w.-]+:)?([\w.-]+)\b/.exec(prefix)?.[1]?.toLowerCase() ?? null,
+		namespace: null
+	};
+	const attributes = rootMatch[2] ?? "";
+	const namespace = /\sxmlns(?::[\w.-]+)?=(["'])(.*?)\1/i.exec(attributes)?.[2] ?? null;
+	return {
+		root: rootMatch[1].toLowerCase(),
+		namespace
+	};
+}
+async function parseSitemapDocument(body, options = {}) {
+	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+	const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+	const prepared = await prepareSitemapInput(body, maxBytes);
+	if (prepared._tag !== "ready") return prepared;
+	let root = null;
+	let complete = true;
+	const urls = [];
+	const sitemaps = [];
+	try {
+		for await (const event of parseSitemapStream(prepared.input)) {
+			if (event._tag === "kind") {
+				root = event.kind === "index" ? "sitemapindex" : "urlset";
+				continue;
+			}
+			if (event._tag === "warning") continue;
+			if (event._tag === "url") {
+				const entry = normalizeSitemapUrlInput(event.url);
+				if (!entry || options.acceptUrl && !options.acceptUrl(entry)) continue;
+				if (urls.length >= maxEntries) {
+					complete = false;
+					break;
+				}
+				urls.push(entry);
+			} else if (event._tag === "sitemap") {
+				if (sitemaps.length >= maxEntries) {
+					complete = false;
+					break;
+				}
+				sitemaps.push(event.sitemap);
+			}
+			if (!complete) break;
+		}
+	} catch (error) {
+		if (isSitemapInputBoundaryError(error)) return error;
+		const metadata = rootMetadata(prepared.stats.prefix);
+		if (metadata.root && metadata.root !== "urlset" && metadata.root !== "sitemapindex") return {
+			_tag: "unsupported_document",
+			root: metadata.root
+		};
+		return {
+			_tag: "parse_error",
+			error: `Not a valid sitemap: ${errorMessage(error)}`
+		};
+	}
+	const metadata = rootMetadata(prepared.stats.prefix);
+	const meta = {
+		bytesRead: prepared.stats.bytesRead,
+		complete,
+		hasBom: prepared.stats.hasBom,
+		hasXmlDeclaration: /^\s*<\?xml\b/i.test(prepared.stats.prefix),
+		namespace: metadata.namespace
+	};
+	if (root === "urlset") return {
+		_tag: "urlset",
+		entries: urls,
+		meta
+	};
+	if (root === "sitemapindex") return {
+		_tag: "index",
+		entries: sitemaps,
+		meta
+	};
+	return {
+		_tag: "unsupported_document",
+		root
+	};
+}
+function requestSignal(signal, timeoutMs) {
+	if (signal) return signal;
+	return AbortSignal.timeout(timeoutMs);
+}
+async function fetchSitemapDocument(url, options = {}) {
+	const fetcher = options.fetcher ?? globalThis.fetch;
+	let response;
+	try {
+		response = await fetcher(url, {
+			headers: {
+				accept: "application/xml,text/xml,application/rss+xml,*/*;q=0.1",
+				...options.headers
+			},
+			redirect: "follow",
+			signal: requestSignal(options.signal, options.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS)
+		});
+	} catch (error) {
+		return {
+			_tag: "network_error",
+			url,
+			error: errorMessage(error)
+		};
+	}
+	if (response.status === 404 || response.status === 410) return {
+		_tag: "not_found",
+		url,
+		status: response.status
+	};
+	if (!response.ok) return {
+		_tag: "http_error",
+		url,
+		status: response.status,
+		statusText: response.statusText
+	};
+	if (!response.body) return {
+		_tag: "document_error",
+		url,
+		error: { _tag: "empty_body" }
+	};
+	let body;
+	try {
+		body = await bodyWithDetectedCompression(response.body);
+	} catch (error) {
+		return {
+			_tag: "document_error",
+			url,
+			error: {
+				_tag: "parse_error",
+				error: errorMessage(error)
+			}
+		};
+	}
+	const document = await parseSitemapDocument(body, options);
+	if (document._tag === "urlset" || document._tag === "index") return {
+		_tag: "ok",
+		url: response.url || url,
+		document
+	};
+	return {
+		_tag: "document_error",
+		url,
+		error: document
+	};
+}
+function parseRobotsSitemapUrls(robots, baseUrl) {
+	const urls = [];
 	const seen = /* @__PURE__ */ new Set();
-	const out = [];
-	const visit = async (url, depth) => {
-		if (limit != null && out.length >= limit) return;
-		if (depth > maxDepth) return;
-		const res = await fetch(url, {
-			headers: { "User-Agent": userAgent },
-			signal: signalFor()
+	for (const match of robots.matchAll(/^\s*sitemap:\s*(\S+)/gim)) {
+		const raw = match[1];
+		if (!raw) continue;
+		let value = raw;
+		if (baseUrl) try {
+			value = new URL(raw, baseUrl).toString();
+		} catch {
+			continue;
+		}
+		if (!seen.has(value)) {
+			seen.add(value);
+			urls.push(value);
+		}
+	}
+	return urls;
+}
+function normalizeSiteOrigin(input) {
+	const value = input.trim().replace(/^sc-domain:/i, "");
+	try {
+		const url = new URL(/^https?:\/\//i.test(value) ? value : `https://${value}`);
+		if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+		return url.origin;
+	} catch {
+		return null;
+	}
+}
+function canonicalSitemapIdentity(path, site = "") {
+	const value = path.trim();
+	if (!value) return {
+		_tag: "invalid",
+		reason: "empty"
+	};
+	const siteOrigin = normalizeSiteOrigin(site);
+	let parsed;
+	try {
+		parsed = new URL(value, siteOrigin ? `${siteOrigin}/` : void 0);
+	} catch {
+		return {
+			_tag: "invalid",
+			reason: "invalid_url"
+		};
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return {
+		_tag: "invalid",
+		reason: "invalid_url"
+	};
+	if (siteOrigin && parsed.origin !== siteOrigin) return {
+		_tag: "invalid",
+		reason: "off_origin"
+	};
+	parsed.hash = "";
+	return {
+		_tag: "ok",
+		url: `${parsed.origin}${parsed.pathname}${parsed.search}`
+	};
+}
+function sameSitemapIdentity(left, right, site = "") {
+	const leftIdentity = canonicalSitemapIdentity(left, site);
+	if (leftIdentity._tag !== "ok") return false;
+	const rightIdentity = canonicalSitemapIdentity(right, site);
+	return rightIdentity._tag === "ok" && leftIdentity.url === rightIdentity.url;
+}
+function evidenceTime(record) {
+	const downloadedAt = record.lastDownloaded ? Date.parse(record.lastDownloaded) : NaN;
+	if (Number.isFinite(downloadedAt)) return downloadedAt;
+	return record.fetchedAt ?? 0;
+}
+function scopeSitemapRecords(records, site = "") {
+	const byIdentity = /* @__PURE__ */ new Map();
+	let excludedCount = 0;
+	let duplicateCount = 0;
+	for (const record of records) {
+		const identity = canonicalSitemapIdentity(record.path, site);
+		if (identity._tag !== "ok") {
+			excludedCount++;
+			continue;
+		}
+		const normalized = {
+			...record,
+			path: identity.url
+		};
+		const existing = byIdentity.get(identity.url);
+		if (!existing) {
+			byIdentity.set(identity.url, normalized);
+			continue;
+		}
+		duplicateCount++;
+		if (evidenceTime(normalized) >= evidenceTime(existing)) byIdentity.set(identity.url, normalized);
+	}
+	return {
+		sitemaps: [...byIdentity.values()],
+		excludedCount,
+		duplicateCount
+	};
+}
+function discoveryFailure(result) {
+	if (result._tag === "network_error") return {
+		url: result.url,
+		kind: "network",
+		detail: result.error
+	};
+	if (result._tag === "http_error") return {
+		url: result.url,
+		kind: "http",
+		detail: `HTTP ${result.status}: ${result.statusText}`
+	};
+	return {
+		url: result.url,
+		kind: "document",
+		detail: result.error._tag
+	};
+}
+async function readRobots(origin, options) {
+	const url = `${origin}/robots.txt`;
+	const fetcher = options.fetcher ?? globalThis.fetch;
+	let response;
+	try {
+		response = await fetcher(url, {
+			headers: { "user-agent": options.userAgent ?? "gscdump sitemap fetcher" },
+			signal: requestSignal(options.signal, options.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS)
+		});
+	} catch (error) {
+		return {
+			urls: [],
+			failure: {
+				url,
+				kind: "network",
+				detail: errorMessage(error)
+			}
+		};
+	}
+	if (response.status === 404 || response.status === 410) return { urls: [] };
+	if (!response.ok) return {
+		urls: [],
+		failure: {
+			url,
+			kind: "http",
+			detail: `HTTP ${response.status}: ${response.statusText}`
+		}
+	};
+	const maxBytes = Math.min(options.maxBytes ?? DEFAULT_MAX_BYTES, 1024 * 1024);
+	const body = response.body;
+	if (!body) return { urls: [] };
+	const decoder = new TextDecoder();
+	let bytes = 0;
+	let text = "";
+	try {
+		for await (const chunk of readableStreamChunks(body)) {
+			bytes += chunk.byteLength;
+			if (bytes > maxBytes) return {
+				urls: [],
+				failure: {
+					url,
+					kind: "document",
+					detail: `robots.txt exceeds ${maxBytes} bytes`
+				}
+			};
+			text += decoder.decode(chunk, { stream: true });
+		}
+		text += decoder.decode();
+	} catch (error) {
+		return {
+			urls: [],
+			failure: {
+				url,
+				kind: "network",
+				detail: errorMessage(error)
+			}
+		};
+	}
+	return { urls: parseRobotsSitemapUrls(text, origin) };
+}
+async function discoverSitemapResult(site, options = {}) {
+	const origin = normalizeSiteOrigin(site);
+	if (!origin) return {
+		_tag: "incomplete",
+		failures: [{
+			url: site,
+			kind: "document",
+			detail: "invalid site URL"
+		}]
+	};
+	const headers = {
+		"user-agent": options.userAgent ?? "gscdump sitemap fetcher",
+		...options.headers
+	};
+	const failures = [];
+	for (const path of COMMON_SITEMAP_PATHS) {
+		const result = await fetchSitemapDocument(`${origin}${path}`, {
+			...options,
+			headers
+		});
+		if (result._tag === "ok") return {
+			_tag: "found",
+			url: result.url,
+			source: "common_path"
+		};
+		if (result._tag !== "not_found" && !(result._tag === "document_error" && (result.error._tag === "html" || result.error._tag === "unsupported_document"))) failures.push(discoveryFailure(result));
+	}
+	const robots = await readRobots(origin, options);
+	if (robots.failure) failures.push(robots.failure);
+	for (const url of robots.urls) {
+		const result = await fetchSitemapDocument(url, {
+			...options,
+			headers
 		});
-		if (!res.ok) throw new Error(`Fetch ${url} failed: ${res.status}`);
-		const text = await res.text();
-		if (SITEMAPINDEX_RE.test(text)) {
-			for (const match of text.matchAll(LOC_RE)) {
-				if (limit != null && out.length >= limit) return;
-				const child = match[1].trim();
-				if (!child) continue;
-				await visit(child, depth + 1);
+		if (result._tag === "ok") return {
+			_tag: "found",
+			url: result.url,
+			source: "robots"
+		};
+		if (result._tag !== "not_found") failures.push(discoveryFailure(result));
+	}
+	return failures.length > 0 ? {
+		_tag: "incomplete",
+		failures
+	} : { _tag: "not_found" };
+}
+async function discoverSitemap(site, options = {}) {
+	const result = await discoverSitemapResult(site, options);
+	return result._tag === "found" ? result.url : null;
+}
+function walkFailure(url, depth, error) {
+	return {
+		url,
+		depth,
+		error
+	};
+}
+async function walkSitemaps(roots, options = {}) {
+	const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+	const maxDocuments = options.maxDocuments ?? DEFAULT_MAX_DOCUMENTS;
+	const maxUrls = options.maxUrls ?? DEFAULT_MAX_ENTRIES;
+	const queue = (typeof roots === "string" ? [roots] : [...roots]).map((url) => ({
+		url,
+		depth: 0
+	}));
+	const rootCount = queue.length;
+	const seenDocuments = /* @__PURE__ */ new Set();
+	const seenUrls = /* @__PURE__ */ new Set();
+	const entries = [];
+	const failures = [];
+	let documentsRead = 0;
+	let complete = true;
+	let loadedRoot = false;
+	let missingRoots = 0;
+	while (queue.length > 0) {
+		if (documentsRead >= maxDocuments) {
+			complete = false;
+			break;
+		}
+		const next = queue.shift();
+		if (seenDocuments.has(next.url)) continue;
+		seenDocuments.add(next.url);
+		const result = await fetchSitemapDocument(next.url, {
+			...options,
+			maxEntries: Math.max(maxUrls - entries.length, 1)
+		});
+		if (result._tag !== "ok") {
+			if (next.depth === 0 && result._tag === "not_found") {
+				missingRoots++;
+				continue;
+			} else failures.push(walkFailure(next.url, next.depth, result));
+			complete = false;
+			continue;
+		}
+		if (next.depth === 0) loadedRoot = true;
+		documentsRead++;
+		complete &&= result.document.meta.complete;
+		if (result.document._tag === "index") {
+			if (next.depth >= maxDepth && result.document.entries.length > 0) {
+				complete = false;
+				continue;
+			}
+			for (const child of result.document.entries) queue.push({
+				url: child.loc,
+				depth: next.depth + 1
+			});
+			continue;
+		}
+		for (const entry of result.document.entries) {
+			if (seenUrls.has(entry.loc)) continue;
+			if (entries.length >= maxUrls) {
+				complete = false;
+				break;
 			}
-			return;
+			seenUrls.add(entry.loc);
+			entries.push(entry);
 		}
-		for (const match of text.matchAll(LOC_RE)) {
-			const u = match[1].trim();
-			if (!u) continue;
-			if (seen.has(u)) continue;
-			seen.add(u);
-			out.push(u);
-			if (limit != null && out.length >= limit) return;
+		if (entries.length >= maxUrls && queue.length > 0) {
+			complete = false;
+			break;
 		}
+	}
+	if (!loadedRoot && missingRoots === rootCount && failures.length === 0) return { _tag: "not_found" };
+	if (!loadedRoot) return {
+		_tag: "error",
+		failures
+	};
+	return {
+		_tag: "ok",
+		entries,
+		documentsRead,
+		complete,
+		failures
 	};
-	await visit(sitemapUrl, 0);
-	return out;
 }
-export { discoverSitemap, fetchSitemapUrls };
+function legacyWalkFailureMessage(failure) {
+	const result = failure.error;
+	if (result._tag === "not_found" || result._tag === "http_error") return `Fetch ${failure.url} failed: ${result.status}`;
+	if (result._tag === "network_error") return result.error;
+	if (result.error._tag === "parse_error") return result.error.error;
+	return `Sitemap ${failure.url} failed: ${result.error._tag}`;
+}
+async function fetchSitemapUrls(sitemapUrl, options = {}) {
+	const { limit, maxDepth, userAgent, ...fetchOptions } = options;
+	const result = await walkSitemaps(sitemapUrl, {
+		...fetchOptions,
+		headers: {
+			"user-agent": userAgent ?? "gscdump sitemap fetcher",
+			...fetchOptions.headers
+		},
+		maxDepth,
+		maxDocuments: Number.MAX_SAFE_INTEGER,
+		maxUrls: limit ?? Number.MAX_SAFE_INTEGER
+	});
+	if (result._tag === "not_found") throw new Error(`Fetch ${sitemapUrl} failed: 404`);
+	if (result._tag === "error") throw new Error(result.failures[0] ? legacyWalkFailureMessage(result.failures[0]) : "Sitemap fetch failed");
+	if (result.failures[0]) throw new Error(legacyWalkFailureMessage(result.failures[0]));
+	return result.entries.map((entry) => entry.loc);
+}
+async function sitemapContentHash(entries) {
+	const normalized = entries.map((entry) => urlMatchKey(entry.loc)).filter((url) => Boolean(url)).sort();
+	const input = new TextEncoder().encode(normalized.join("\n"));
+	const hash = await crypto.subtle.digest("SHA-256", input);
+	return Array.from(new Uint8Array(hash), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+export { canonicalSitemapIdentity, discoverSitemap, discoverSitemapResult, fetchSitemapDocument, fetchSitemapUrls, parseRobotsSitemapUrls, parseSitemapDocument, sameSitemapIdentity, scopeSitemapRecords, sitemapContentHash, walkSitemaps };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gscdump",
   "type": "module",
-  "version": "1.4.11",
+  "version": "1.5.1",
   "description": "Direct Google Search Console client with typed queries, streaming pagination, URL inspection, and indexing helpers",
   "author": {
     "name": "Harlan Wilton",
@@ -52,6 +52,11 @@
       "import": "./dist/core/result.mjs",
       "default": "./dist/core/result.mjs"
     },
+    "./sitemap": {
+      "types": "./dist/sitemap.d.mts",
+      "import": "./dist/sitemap.mjs",
+      "default": "./dist/sitemap.mjs"
+    },
     "./contracts": {
       "types": "./dist/contracts.d.mts",
       "import": "./dist/contracts.mjs",
@@ -82,8 +87,9 @@
     "node": ">=22"
   },
   "dependencies": {
+    "@nuxtjs/sitemap": "8.3.0",
     "ofetch": "^1.5.1",
-    "@gscdump/contracts": "^1.4.11"
+    "@gscdump/contracts": "^1.5.1"
   },
   "scripts": {
     "dev": "obuild --stub",