gscdump 4.4.0 → 4.5.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/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.5.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.5.0",
     "ofetch": "^1.5.1"
   },
   "scripts": {