gscdump 4.4.0 → 4.6.0

package/README.md

@@ -92,6 +92,41 @@ See [URL inspection and indexing](../../docs/gscdump-cli/guides/6.url-indexing.m
 
 The package root also exports batch and projection helpers such as `fetchSitesWithSitemaps`, `batchInspectUrlsFlatSettled`, `inspectUrlFlat`, and `batchRequestIndexing`.
 
+## Send IndexNow change notifications
+
+Publish a UTF-8 key file on the exact host you submit.
+The key file contains your key, with no other content.
+
+```ts
+import { indexNow } from 'gscdump/indexnow'
+
+const client = indexNow()
+const input = {
+  host: 'example.com',
+  key: 'your-key-12345',
+  keyLocation: 'https://example.com/your-key-12345.txt',
+}
+const verification = await client.verify(input)
+if (verification.ok && verification.value._tag === 'verified') {
+  const result = await client.submit({
+    ...input,
+    urls: ['https://example.com/changed-page'],
+  })
+  console.log(result)
+}
+```
+
+The client rejects URLs outside the exact host or key directory before sending.
+Verification allows HTTPS, disables redirects, and reads at most 1,024 bytes within ten seconds.
+Inject `fetch`, `clock`, or `timeoutMs` when you need different transport or timing.
+Expected input failures return `Result`; infrastructure failures propagate.
+
+Submission Receipts describe delivery. HTTP 200 means accepted; HTTP 202 means key validation remains pending.
+Neither response proves indexing.
+The direct client sends one batch of up to 10,000 URLs without retries.
+Hosted callers use the SDK operations, which cap each batch at 1,000 URLs.
+See the [IndexNow protocol](https://www.indexnow.org/documentation).
+
 ## Read Bing Indexing Evidence
 
 Use `gscdump/bing` with an OAuth access token or Bing Webmaster API key. The client returns tagged
@@ -129,6 +164,7 @@ sitemap membership is available through `@gscdump/sdk/v1`.
 
 - `gscdump/client`: Google client and authentication types
 - `gscdump/indexing`: inspection and indexing helpers
+- `gscdump/indexnow`: key verification and change notifications
 - `gscdump/errors`: typed Google API failures
 - `gscdump/sites`: Site helpers
 - `gscdump/sitemap-identity`: sitemap scope and membership hashing

package/dist/bing/normalize.mjs

@@ -1,5 +1,5 @@
 import { err, ok } from "../core/result.mjs";
-const BING_UNAVAILABLE_DATE_MS = -62135568e6;
+const BING_UNAVAILABLE_DATE_MS = -0xa9730b66800;
 const BING_DATE_PATTERN = /^\/Date\((-?\d+)(?:[+-]\d{4})?\)\/$/;
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/core/coverage-state.d.mts

@@ -0,0 +1,74 @@
+import { CoverageStateCounts, CoverageStateTag, VerdictFreshness } from "@gscdump/contracts";
+type MappedCoverageStateTag = Exclude<CoverageStateTag, 'unrecognized' | 'not_reported'>;
+/**
+ * Parsed coverage state for one URL Inspection result.
+ *
+ * - A mapped tag: Google's prose names one known state.
+ * - `unrecognized`: Google returned prose no tag maps. `coverageState` keeps it.
+ * - `not_reported`: the result carried no coverage prose.
+ */
+export type CoverageState = {
+  _tag: MappedCoverageStateTag;
+} | {
+  _tag: 'unrecognized';
+  coverageState: string;
+} | {
+  _tag: 'not_reported';
+};
+/**
+ * Every coverage prose string Google returns, by tag. Two spellings exist for the
+ * noindex exclusion: the URL Inspection API uses typographic quotes, and the Page
+ * indexing report uses straight quotes.
+ */
+export declare const GOOGLE_COVERAGE_STATES: {
+  readonly unknown_to_google: readonly ["URL is unknown to Google"];
+  readonly discovered_not_indexed: readonly ["Discovered - currently not indexed"];
+  readonly crawled_not_indexed: readonly ["Crawled - currently not indexed"];
+  readonly indexed: readonly ["Submitted and indexed", "Indexed, not submitted in sitemap", "Indexed, though blocked by robots.txt", "Indexed; consider marking as canonical", "Page indexed without content"];
+  readonly noindex: readonly ["Excluded by ‘noindex’ tag", "Excluded by 'noindex' tag"];
+  readonly blocked_robots: readonly ["Blocked by robots.txt"];
+  readonly soft_404: readonly ["Soft 404"];
+  readonly not_found: readonly ["Not found (404)"];
+  readonly server_error: readonly ["Server error (5xx)"];
+  readonly access_denied: readonly ["Blocked due to unauthorized request (401)"];
+  readonly access_forbidden: readonly ["Blocked due to access forbidden (403)"];
+  readonly blocked_4xx: readonly ["Blocked due to other 4xx issue"];
+  readonly redirect: readonly ["Page with redirect"];
+  readonly redirect_error: readonly ["Redirect error"];
+  readonly alternate_canonical: readonly ["Alternate page with proper canonical tag"];
+  readonly duplicate_no_canonical: readonly ["Duplicate without user-selected canonical"];
+  readonly duplicate_google_canonical: readonly ["Duplicate, Google chose different canonical than user"];
+  readonly page_removed: readonly ["Blocked by page removal tool"];
+};
+/** Parse Google's coverage prose for one URL. Surrounding whitespace is ignored. */
+export declare function parseCoverageState(coverageState: string | null | undefined): CoverageState;
+/** Zero for every coverage state tag. */
+export declare function emptyCoverageStateCounts(): CoverageStateCounts;
+/** Count parsed coverage states over URL Inspection results. */
+export declare function countCoverageStates(coverageStates: Iterable<string | null | undefined>): CoverageStateCounts;
+/**
+ * A SQL `CASE` expression that yields the coverage state tag for `column`, from
+ * the same prose table as {@link parseCoverageState}. It uses exact `IN` matches
+ * and `TRIM`, so it runs unchanged on SQLite and DuckDB. `column` is trusted SQL:
+ * pass a column name or a cast, never user input.
+ */
+export declare function coverageStateTagSql(column: string): string;
+/**
+ * The inspection-time cutoffs for verdicts older than 7 and 30 days, as ISO
+ * strings. RFC 3339 UTC strings sort in time order, so a stored `inspectedAt`
+ * string compares against these directly.
+ */
+export declare function verdictAgeCutoffs(nowMs: number): {
+  olderThan7d: string;
+  olderThan30d: string;
+};
+/**
+ * Turn verdict age counts into the wire freshness shape. The input is untrusted
+ * arithmetic from a SQL row, so counts are clamped: an older bucket can never
+ * exceed a younger one, and no bucket can exceed `verdicts`.
+ */
+export declare function measureVerdictFreshness(input: {
+  verdicts: number;
+  olderThan7d: number;
+  olderThan30d: number;
+}): VerdictFreshness;

package/dist/core/coverage-state.mjs

@@ -0,0 +1,80 @@
+const GOOGLE_COVERAGE_STATES = {
+	unknown_to_google: ["URL is unknown to Google"],
+	discovered_not_indexed: ["Discovered - currently not indexed"],
+	crawled_not_indexed: ["Crawled - currently not indexed"],
+	indexed: [
+		"Submitted and indexed",
+		"Indexed, not submitted in sitemap",
+		"Indexed, though blocked by robots.txt",
+		"Indexed; consider marking as canonical",
+		"Page indexed without content"
+	],
+	noindex: ["Excluded by ‘noindex’ tag", "Excluded by 'noindex' tag"],
+	blocked_robots: ["Blocked by robots.txt"],
+	soft_404: ["Soft 404"],
+	not_found: ["Not found (404)"],
+	server_error: ["Server error (5xx)"],
+	access_denied: ["Blocked due to unauthorized request (401)"],
+	access_forbidden: ["Blocked due to access forbidden (403)"],
+	blocked_4xx: ["Blocked due to other 4xx issue"],
+	redirect: ["Page with redirect"],
+	redirect_error: ["Redirect error"],
+	alternate_canonical: ["Alternate page with proper canonical tag"],
+	duplicate_no_canonical: ["Duplicate without user-selected canonical"],
+	duplicate_google_canonical: ["Duplicate, Google chose different canonical than user"],
+	page_removed: ["Blocked by page removal tool"]
+};
+const MAPPED_TAGS = Object.keys(GOOGLE_COVERAGE_STATES);
+const TAG_BY_PROSE = new Map(MAPPED_TAGS.flatMap((tag) => GOOGLE_COVERAGE_STATES[tag].map((prose) => [prose, tag])));
+function parseCoverageState(coverageState) {
+	const prose = coverageState?.trim();
+	if (!prose) return { _tag: "not_reported" };
+	const tag = TAG_BY_PROSE.get(prose);
+	return tag ? { _tag: tag } : {
+		_tag: "unrecognized",
+		coverageState: prose
+	};
+}
+function emptyCoverageStateCounts() {
+	const counts = {
+		unrecognized: 0,
+		not_reported: 0
+	};
+	for (const tag of MAPPED_TAGS) counts[tag] = 0;
+	return counts;
+}
+function countCoverageStates(coverageStates) {
+	const counts = emptyCoverageStateCounts();
+	for (const coverageState of coverageStates) counts[parseCoverageState(coverageState)._tag]++;
+	return counts;
+}
+function sqlString(value) {
+	return `'${value.replaceAll("'", "''")}'`;
+}
+function coverageStateTagSql(column) {
+	return `CASE WHEN ${column} IS NULL OR TRIM(${column}) = '' THEN 'not_reported' ${MAPPED_TAGS.map((tag) => `WHEN TRIM(${column}) IN (${GOOGLE_COVERAGE_STATES[tag].map(sqlString).join(", ")}) THEN ${sqlString(tag)}`).join(" ")} ELSE 'unrecognized' END`;
+}
+const DAY_MS = 864e5;
+function verdictAgeCutoffs(nowMs) {
+	return {
+		olderThan7d: (/* @__PURE__ */ new Date(nowMs - 7 * DAY_MS)).toISOString(),
+		olderThan30d: (/* @__PURE__ */ new Date(nowMs - 30 * DAY_MS)).toISOString()
+	};
+}
+function percentOf(part, whole) {
+	return whole > 0 ? Math.round(part / whole * 1e3) / 10 : 0;
+}
+function measureVerdictFreshness(input) {
+	const verdicts = Math.max(0, Math.trunc(input.verdicts));
+	const olderThan7d = Math.min(verdicts, Math.max(0, Math.trunc(input.olderThan7d)));
+	const olderThan30d = Math.min(olderThan7d, Math.max(0, Math.trunc(input.olderThan30d)));
+	return {
+		_tag: "measured",
+		verdicts,
+		olderThan7d,
+		olderThan30d,
+		olderThan7dPercent: percentOf(olderThan7d, verdicts),
+		olderThan30dPercent: percentOf(olderThan30d, verdicts)
+	};
+}
+export { GOOGLE_COVERAGE_STATES, countCoverageStates, coverageStateTagSql, emptyCoverageStateCounts, measureVerdictFreshness, parseCoverageState, verdictAgeCutoffs };

package/dist/core/indexing-issues.d.mts

@@ -51,9 +51,11 @@ export declare const INDEXING_ISSUE_SEVERITY: Record<IndexingIssueType, 'error'
  */
 export declare const KNOWN_PAGE_FETCH_STATES: ReadonlySet<string>;
 /**
- * Every `coverageState` string we have a bucket for, plus the indexed-state strings
- * that are not faults. Google is free to invent new prose here at any time — that's
- * exactly what {@link unmappedInspectionReasons} exists to catch.
+ * Every `coverageState` string gscdump maps to a tag, plus the indexed-state
+ * strings that are not faults. Derived from the one prose table behind
+ * `parseCoverageState`, so this canary and the coverage tags cannot drift. Google
+ * is free to invent new prose here at any time; that is what
+ * {@link unmappedInspectionReasons} exists to catch.
  */
 export declare const KNOWN_COVERAGE_STATES: ReadonlySet<string>;
 export interface UnmappedInspectionReasons {

package/dist/core/indexing-issues.mjs

@@ -1,3 +1,4 @@
+import { GOOGLE_COVERAGE_STATES } from "./coverage-state.mjs";
 function isFragmentUrl(url) {
 	return typeof url === "string" && url.includes("#");
 }
@@ -111,29 +112,7 @@ const KNOWN_PAGE_FETCH_STATES = /* @__PURE__ */ new Set([
 	"INTERNAL_CRAWL_ERROR",
 	"INVALID_URL"
 ]);
-const KNOWN_COVERAGE_STATES = /* @__PURE__ */ new Set([
-	"Submitted and indexed",
-	"Indexed, not submitted in sitemap",
-	"Indexed, though blocked by robots.txt",
-	"Indexed; consider marking as canonical",
-	"URL is unknown to Google",
-	"Crawled - currently not indexed",
-	"Discovered - currently not indexed",
-	"Not found (404)",
-	"Soft 404",
-	"Server error (5xx)",
-	"Blocked due to access forbidden (403)",
-	"Blocked due to unauthorized request (401)",
-	"Blocked due to other 4xx issue",
-	"Redirect error",
-	"Blocked by robots.txt",
-	"Excluded by ‘noindex’ tag",
-	"Page with redirect",
-	"Alternate page with proper canonical tag",
-	"Duplicate without user-selected canonical",
-	"Duplicate, Google chose different canonical than user",
-	"Blocked by page removal tool"
-]);
+const KNOWN_COVERAGE_STATES = new Set(Object.values(GOOGLE_COVERAGE_STATES).flat());
 function unmappedInspectionReasons(rows) {
 	const coverageStates = /* @__PURE__ */ new Set();
 	const pageFetchStates = /* @__PURE__ */ new Set();

package/dist/index.d.mts

@@ -12,6 +12,7 @@ import { OAuthTokenInfo, OAuthTokens, exchangeAuthCodeResult, introspectAccessTo
 import { FetchSitesWithSitemapsOptions, addSite, deleteSite, deleteSitemap, fetchSitemap, fetchSitemaps, fetchSites, fetchSitesWithSitemaps, submitSitemap } from "./api/sites.mjs";
 import { getVerificationToken, getVerifiedSite, listVerifiedSites, resolveVerificationTarget, siteUrlToVerificationSite, unverifySite, verificationMethodsFor, verifySite } from "./api/verification.mjs";
 import { CanonicalDifferenceKind, classifyCanonicalDifference, isCanonicalMismatch } from "./core/canonical.mjs";
+import { CoverageState, GOOGLE_COVERAGE_STATES, countCoverageStates, coverageStateTagSql, emptyCoverageStateCounts, measureVerdictFreshness, parseCoverageState, verdictAgeCutoffs } from "./core/coverage-state.mjs";
 import { INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, IndexingIssueType, KNOWN_COVERAGE_STATES, KNOWN_PAGE_FETCH_STATES, UnmappedInspectionReasons, isFragmentUrl, unmappedInspectionReasons } from "./core/indexing-issues.mjs";
 import { GscPropertyCandidate, SiteCandidate, SiteResolution, findBestGscProperty, findExactGscProperty, formatGscPropertyCandidates, gscPropertyMatchesTarget, isVerifiedGscPermission, isVerifiedGscProperty, matchGscSite, pickBestGscProperty, resolveSiteInput } from "./core/property.mjs";
 import { URL_INSPECTION_EFFECTIVE_LIMIT } from "./core/quota.mjs";
@@ -20,4 +21,4 @@ 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 { 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, 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, type GscQuota, 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, SiteCandidate, SiteResolution, type SitemapNextAction, type SitemapStatus, URL_INSPECTION_EFFECTIVE_LIMIT, URL_INSPECTION_QUOTA, 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, describeInspectionError, encodeSiteId, err, exchangeAuthCodeResult, fetchSitemap, 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, resolveSiteInput, 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, CoverageState, DAYS_PER_RANGE, DEFAULT_GSC_REQUEST_TIMEOUT_MS, DataRow, DimensionFilter, DimensionFilterGroup, Err, FetchSitesWithSitemapsOptions, GOOGLE_COVERAGE_STATES, 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, type GscQuota, 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, SiteCandidate, SiteResolution, type SitemapNextAction, type SitemapStatus, URL_INSPECTION_EFFECTIVE_LIMIT, URL_INSPECTION_QUOTA, UnmappedInspectionReasons, UrlInspectionResult, UrlNotification, UrlNotificationMetadata, ValueWeightedInspectionPriority, VerificationMethod, VerificationSite, VerificationSiteType, VerificationToken, VerificationWebResource, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchInspectUrlsFlatSettled, batchRequestIndexing, canUseUrlInspection, classifyCanonicalDifference, classifyError, countCoverageStates, countDays, coverageStateTagSql, createAuth, createFetch, decodeSiteId, deleteSite, deleteSitemap, describeInspectionError, emptyCoverageStateCounts, encodeSiteId, err, exchangeAuthCodeResult, fetchSitemap, 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, measureVerdictFreshness, normalizeGscSiteUrl, normalizeRegistrationTarget, normalizeSiteUrl, normalizeUrl, ok, parseCoverageState, parseGoogleError, parseGrantedScopes, parseGscSiteUrl, pickBestGscProperty, propertyNextActions, propertyStatuses, querySourceModes, refreshAccessToken, requestIndexing, resolveSiteInput, resolveVerificationTarget, rethrowAsGscApiError, revokeOAuthToken, revokeOAuthTokenResult, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, submitSitemap, toIsoDate, unmappedInspectionReasons, unverifySite, unwrapResult, urlMatchKey, verdictAgeCutoffs, verificationMethodsFor, verifySite };

package/dist/index.mjs

@@ -11,6 +11,7 @@ import { getVerificationToken, getVerifiedSite, listVerifiedSites, resolveVerifi
 import { classifyCanonicalDifference, isCanonicalMismatch } from "./core/canonical.mjs";
 import { DAYS_PER_RANGE, GSC_FINALIZED_LAG_DAYS, GSC_FRESHEST_LAG_DAYS, GSC_RETENTION_MONTHS, MS_PER_DAY, addDays, countDays, generateGscDateRange, getBackfillProgress, getDateRange, getFreshestGscDate, getLatestGscDate, getNextDate, getOldestGscDate, getPendingDates, getPreviousDate, getPstDate, groupIntoRanges, isValidGscDate, toIsoDate } from "./core/gsc-dates.mjs";
 import { DEFAULT_GSC_REQUEST_TIMEOUT_MS, createAuth, createFetch, googleSearchConsole } from "./core/client.mjs";
+import { GOOGLE_COVERAGE_STATES, countCoverageStates, coverageStateTagSql, emptyCoverageStateCounts, measureVerdictFreshness, parseCoverageState, verdictAgeCutoffs } from "./core/coverage-state.mjs";
 import { INDEXING_ISSUE_FILTERS, INDEXING_ISSUE_LABELS, INDEXING_ISSUE_SEVERITY, KNOWN_COVERAGE_STATES, KNOWN_PAGE_FETCH_STATES, isFragmentUrl, unmappedInspectionReasons } from "./core/indexing-issues.mjs";
 import { normalizeGscSiteUrl, normalizeRegistrationTarget, parseGscSiteUrl } from "./core/site-url.mjs";
 import { findBestGscProperty, findExactGscProperty, formatGscPropertyCandidates, gscPropertyMatchesTarget, isVerifiedGscPermission, isVerifiedGscProperty, matchGscSite, pickBestGscProperty, resolveSiteInput } from "./core/property.mjs";
@@ -20,4 +21,4 @@ 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 { 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, URL_INSPECTION_QUOTA, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchInspectUrlsFlatSettled, batchRequestIndexing, canUseUrlInspection, classifyCanonicalDifference, classifyError, countDays, createAuth, createFetch, decodeSiteId, deleteSite, deleteSitemap, describeInspectionError, encodeSiteId, err, exchangeAuthCodeResult, fetchSitemap, 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, resolveSiteInput, resolveVerificationTarget, rethrowAsGscApiError, revokeOAuthToken, revokeOAuthTokenResult, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, submitSitemap, toIsoDate, unmappedInspectionReasons, unverifySite, unwrapResult, urlMatchKey, verificationMethodsFor, verifySite };
+export { DAYS_PER_RANGE, DEFAULT_GSC_REQUEST_TIMEOUT_MS, GOOGLE_COVERAGE_STATES, 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, URL_INSPECTION_QUOTA, accountNextActions, accountStatuses, addDays, addSite, analyticsNextActions, analyticsStatuses, batchInspectUrls, batchInspectUrlsFlatSettled, batchRequestIndexing, canUseUrlInspection, classifyCanonicalDifference, classifyError, countCoverageStates, countDays, coverageStateTagSql, createAuth, createFetch, decodeSiteId, deleteSite, deleteSitemap, describeInspectionError, emptyCoverageStateCounts, encodeSiteId, err, exchangeAuthCodeResult, fetchSitemap, 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, measureVerdictFreshness, normalizeGscSiteUrl, normalizeRegistrationTarget, normalizeSiteUrl, normalizeUrl, ok, parseCoverageState, parseGoogleError, parseGrantedScopes, parseGscSiteUrl, pickBestGscProperty, propertyNextActions, propertyStatuses, querySourceModes, refreshAccessToken, requestIndexing, resolveSiteInput, resolveVerificationTarget, rethrowAsGscApiError, revokeOAuthToken, revokeOAuthTokenResult, runSequentialBatch, siteUrlToVerificationSite, sitemapNextActions, sitemapStatuses, submitSitemap, toIsoDate, unmappedInspectionReasons, unverifySite, unwrapResult, urlMatchKey, verdictAgeCutoffs, verificationMethodsFor, verifySite };

package/dist/indexnow.d.mts

@@ -0,0 +1,53 @@
+import { Result } from "./core/result.mjs";
+export interface IndexNowInput {
+  host: string;
+  key: string;
+  keyLocation: string;
+}
+export type IndexNowDelivery = {
+  _tag: 'accepted';
+  httpStatus: 200;
+  reason: null;
+  retryAfterMs: null;
+} | {
+  _tag: 'pending';
+  httpStatus: 202;
+  reason: 'key-validation-pending';
+  retryAfterMs: null;
+} | {
+  _tag: 'rejected';
+  httpStatus: 400 | 403 | 422;
+  reason: string;
+  retryAfterMs: null;
+} | {
+  _tag: 'retrying';
+  httpStatus: number;
+  reason: string;
+  retryAfterMs: number | null;
+} | {
+  _tag: 'failed';
+  httpStatus: number;
+  reason: string;
+  retryAfterMs: null;
+};
+export interface IndexNowInvalidRequest {
+  _tag: 'InvalidRequest';
+  reason: string;
+}
+export type IndexNowVerification = {
+  _tag: 'verified';
+} | {
+  _tag: 'verification-required';
+  reason: string;
+};
+export interface IndexNowClient {
+  verify: (input: IndexNowInput) => Promise<Result<IndexNowVerification, IndexNowInvalidRequest>>;
+  submit: (input: IndexNowInput & {
+    urls: string[];
+  }) => Promise<Result<IndexNowDelivery, IndexNowInvalidRequest>>;
+}
+export declare function indexNow(options?: {
+  fetch?: typeof globalThis.fetch;
+  clock?: () => Date;
+  timeoutMs?: number;
+}): IndexNowClient;

package/dist/indexnow.mjs

@@ -0,0 +1,129 @@
+import { err, ok } from "./core/result.mjs";
+function parseUrl(value) {
+	return URL.canParse(value) ? new URL(value) : null;
+}
+function parseInput(input) {
+	const location = parseUrl(input.keyLocation);
+	if (!/^[a-z0-9-]{8,128}$/i.test(input.key)) return err({
+		_tag: "InvalidRequest",
+		reason: "invalid-key"
+	});
+	if (!location || location.protocol !== "https:" || location.host !== input.host || location.username || location.password || location.hash || location.search || location.port) return err({
+		_tag: "InvalidRequest",
+		reason: "invalid-key-location"
+	});
+	return ok(location);
+}
+function indexNow(options = {}) {
+	const fetch = options.fetch ?? globalThis.fetch;
+	const timeoutMs = options.timeoutMs ?? 1e4;
+	const clock = options.clock ?? (() => /* @__PURE__ */ new Date());
+	return {
+		async verify(input) {
+			const parsed = parseInput(input);
+			if (!parsed.ok) return parsed;
+			const response = await fetch(input.keyLocation, {
+				redirect: "error",
+				signal: AbortSignal.timeout(timeoutMs)
+			});
+			if (response.status !== 200) return ok({
+				_tag: "verification-required",
+				reason: "key-file-unavailable"
+			});
+			const reader = response.body?.getReader();
+			if (!reader) return ok({
+				_tag: "verification-required",
+				reason: "key-file-empty"
+			});
+			const chunks = [];
+			let length = 0;
+			for (;;) {
+				const next = await reader.read();
+				if (next.done) break;
+				length += next.value.length;
+				if (length > 1024) {
+					await reader.cancel();
+					return ok({
+						_tag: "verification-required",
+						reason: "key-file-too-large"
+					});
+				}
+				chunks.push(next.value);
+			}
+			const bytes = new Uint8Array(length);
+			let offset = 0;
+			for (const chunk of chunks) {
+				bytes.set(chunk, offset);
+				offset += chunk.length;
+			}
+			return ok(new TextDecoder().decode(bytes).trim() === input.key ? { _tag: "verified" } : {
+				_tag: "verification-required",
+				reason: "key-file-mismatch"
+			});
+		},
+		async submit(input) {
+			const parsed = parseInput(input);
+			if (!parsed.ok) return parsed;
+			if (!input.urls.length || input.urls.length > 1e4) return err({
+				_tag: "InvalidRequest",
+				reason: "invalid-url-count"
+			});
+			const directory = parsed.value.pathname.slice(0, parsed.value.pathname.lastIndexOf("/") + 1);
+			for (const value of input.urls) {
+				const url = parseUrl(value);
+				if (!url || !["https:", "http:"].includes(url.protocol) || url.host !== input.host || url.username || url.password || url.port || url.hash || !url.pathname.startsWith(directory)) return err({
+					_tag: "InvalidRequest",
+					reason: "url-outside-key-scope"
+				});
+			}
+			const response = await fetch("https://api.indexnow.org/indexnow", {
+				method: "POST",
+				redirect: "error",
+				signal: AbortSignal.timeout(timeoutMs),
+				headers: { "content-type": "application/json; charset=utf-8" },
+				body: JSON.stringify({
+					host: input.host,
+					key: input.key,
+					keyLocation: input.keyLocation,
+					urlList: input.urls
+				})
+			});
+			if (response.status === 200) return ok({
+				_tag: "accepted",
+				httpStatus: 200,
+				reason: null,
+				retryAfterMs: null
+			});
+			if (response.status === 202) return ok({
+				_tag: "pending",
+				httpStatus: 202,
+				reason: "key-validation-pending",
+				retryAfterMs: null
+			});
+			if (response.status === 400 || response.status === 403 || response.status === 422) return ok({
+				_tag: "rejected",
+				httpStatus: response.status,
+				reason: response.status === 403 ? "invalid-key" : "invalid-request",
+				retryAfterMs: null
+			});
+			if (response.status === 429 || response.status >= 500) {
+				const retry = response.headers.get("retry-after");
+				const seconds = retry === null ? NaN : Number(retry);
+				const delay = Number.isFinite(seconds) && seconds >= 0 ? seconds * 1e3 : retry === null ? NaN : Date.parse(retry) - clock().getTime();
+				return ok({
+					_tag: "retrying",
+					httpStatus: response.status,
+					reason: response.status === 429 ? "rate-limited" : "service-unavailable",
+					retryAfterMs: Number.isFinite(delay) ? Math.max(0, delay) : null
+				});
+			}
+			return ok({
+				_tag: "failed",
+				httpStatus: response.status,
+				reason: "unexpected-response",
+				retryAfterMs: null
+			});
+		}
+	};
+}
+export { indexNow };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gscdump",
   "type": "module",
-  "version": "4.4.0",
+  "version": "4.6.0",
   "description": "Direct Google Search Console and Bing Webmaster clients with typed queries and Indexing Evidence",
   "author": {
     "name": "Harlan Wilton",
@@ -102,6 +102,11 @@
       "types": "./dist/tenant.d.mts",
       "import": "./dist/tenant.mjs",
       "default": "./dist/tenant.mjs"
+    },
+    "./indexnow": {
+      "types": "./dist/indexnow.d.mts",
+      "import": "./dist/indexnow.mjs",
+      "default": "./dist/indexnow.mjs"
     }
   },
   "main": "./dist/index.mjs",
@@ -113,7 +118,7 @@
     "node": ">=22.13.0"
   },
   "dependencies": {
-    "@gscdump/contracts": "^4.4.0",
+    "@gscdump/contracts": "^4.6.0",
     "ofetch": "^1.5.1"
   },
   "scripts": {