@notion-headless-cms/core 0.5.1 → 0.5.3

package/dist/index.mjs

@@ -19,7 +19,6 @@ function isStale(cachedAt, ttlMs) {
 }
 //#endregion
 //#region src/cache/noop.ts
-/** 何もキャッシュしないドキュメントオペレーション。常に null を返す。 */
 const noopDoc = {
 	getList(_collection) {
 		return Promise.resolve(null);
@@ -43,7 +42,6 @@ const noopDoc = {
 		return Promise.resolve();
 	}
 };
-/** 何もキャッシュしない画像オペレーション。 */
 const noopImg = {
 	get(_hash) {
 		return Promise.resolve(null);
@@ -59,6 +57,69 @@ const noopImg = {
 const noopDocOps = noopDoc;
 const noopImgOps = noopImg;
 //#endregion
+//#region src/page-index.ts
+/**
+* Notion ページ ID を比較用に正規化する。
+* Notion の ID は文脈によりダッシュの有無・大文字小文字が揺れるため、
+* ダッシュ除去 + 小文字化して突き合わせる。
+*
+* react-renderer 側も同一実装で `pageLinks` を引くため、変更時は両方を揃えること。
+*/
+function normalizePageId(id) {
+	return id.replace(/-/g, "").toLowerCase();
+}
+function asCollectionClient(source, name) {
+	const client = source[name];
+	if (!client || typeof client.list !== "function") return void 0;
+	return client;
+}
+/**
+* 全コレクションを `list()` で走査し、pageId → {collection, slug, title} の逆引きマップを構築する。
+* Notion 内部リンク（link_to_page / page mention など）を自サイト URL へ解決するための材料。
+*
+* `list()` は SWR ドキュメントキャッシュ経由のためウォーム後は安価。
+*/
+async function buildPageIndex(source, opts) {
+	const names = opts?.collections ?? source.collections;
+	const index = /* @__PURE__ */ new Map();
+	if (!names || typeof names[Symbol.iterator] !== "function") return index;
+	for (const name of names) {
+		const client = asCollectionClient(source, name);
+		if (!client) continue;
+		const items = await client.list();
+		if (!Array.isArray(items)) continue;
+		for (const item of items) {
+			const key = normalizePageId(item.id);
+			if (!index.has(key)) index.set(key, {
+				collection: name,
+				slug: item.slug,
+				title: item.title
+			});
+		}
+	}
+	return index;
+}
+const defaultUrl = (entry) => `/${entry.collection}/${entry.slug}`;
+/**
+* Notion 内部リンクを「正規化 pageId → {href, title}」のプレーンマップに解決する。
+* サーバ側（loader / RSC / route handler）で 1 回構築し、`<NotionRenderer pageLinks={...} />`
+* に渡す。プレーンオブジェクトなのでシリアライズ境界（RSC / loader）を越えられる。
+*
+* @example
+* const pageLinks = await buildPageLinkMap(cms);
+* <NotionRenderer blocks={blocks} pageLinks={pageLinks} />;
+*/
+async function buildPageLinkMap(source, opts) {
+	const index = opts?.index ?? await buildPageIndex(source, opts);
+	const toUrl = opts?.url ?? defaultUrl;
+	const map = {};
+	for (const [key, entry] of index) map[key] = {
+		href: toUrl(entry, key),
+		title: entry.title
+	};
+	return map;
+}
+//#endregion
 //#region src/image.ts
 /**
 * レスポンスの Content-Type ヘッダから画像の MIME タイプを取り出す。
@@ -332,9 +393,22 @@ var CollectionClientImpl = class {
 		this.cache = {
 			invalidate: () => this.invalidateImpl(),
 			invalidateItem: (slug) => this.invalidateItemImpl(slug),
-			warm: (opts) => this.warmImpl(opts)
+			warm: (opts) => this.warmImpl(opts),
+			prime: (slug) => this.primeImpl(slug)
 		};
 	}
+	/**
+	* Notion ページ ID で該当アイテムを解決し、単件ウォーム + リストキャッシュを更新する。
+	* このコレクションに属さない page id の場合は何もせず `null` を返す。
+	* 一致した場合は温めた slug を返す（公式 webhook から `cms.warmByPageId` 経由で呼ばれる）。
+	*/
+	async warmByPageId(pageId) {
+		const item = await this.resolveByPageId(pageId);
+		if (!item) return null;
+		await this.primeItem(item);
+		await this.refreshList();
+		return item.slug;
+	}
 	async find(slug, opts = {}) {
 		if (opts.bypassCache) {
 			this.ctx.hooks.onCacheMiss?.(slug);
@@ -450,9 +524,7 @@ var CollectionClientImpl = class {
 			const chunk = items.slice(i, i + concurrency);
 			await Promise.all(chunk.map(async (item) => {
 				try {
-					await this.persistMeta(item.slug, item);
-					const content = await buildCachedItemContent(item, this.ctx.render);
-					await this.ctx.docCache.setContent(this.ctx.collection, item.slug, content);
+					await this.primeItem(item);
 					ok++;
 				} catch (err) {
 					failed.push({
@@ -477,6 +549,47 @@ var CollectionClientImpl = class {
 			failed
 		};
 	}
+	async primeImpl(slug) {
+		const item = await this.fetchRaw(slug);
+		if (!item) return;
+		await this.primeItem(item);
+	}
+	/** 取得済みアイテムからメタ・本文キャッシュを作り直す（warm / prime / warmByPageId 共通）。 */
+	async primeItem(item) {
+		await this.persistMeta(item.slug, item);
+		const content = await buildCachedItemContent(item, this.ctx.render);
+		await this.ctx.docCache.setContent(this.ctx.collection, item.slug, content);
+	}
+	/** リストキャッシュを最新の取得結果で作り直す。 */
+	async refreshList() {
+		const items = await this.fetchListRaw();
+		await this.ctx.docCache.setList(this.ctx.collection, {
+			items,
+			cachedAt: Date.now()
+		});
+	}
+	/** Notion page id からアクセス可能なアイテムを解決する。`findById` 優先、無ければ list を走査。 */
+	async resolveByPageId(pageId) {
+		const target = normalizePageId(pageId);
+		const findById = this.ctx.source.findById?.bind(this.ctx.source);
+		let item;
+		if (findById) item = await withRetry(() => findById(pageId), {
+			...this.ctx.retryConfig,
+			onRetry: (attempt, status, delayMs) => {
+				this.ctx.logger?.warn?.("findById() リトライ中", {
+					attempt,
+					status,
+					pageId,
+					backoffMs: delayMs
+				});
+			}
+		});
+		else item = (await this.fetchListRaw()).find((i) => normalizePageId(i.id) === target) ?? null;
+		if (!item) return null;
+		if (item.isArchived || item.isInTrash) return null;
+		if (this.ctx.accessibleStatuses.length > 0 && (!item.status || !this.ctx.accessibleStatuses.includes(item.status))) return null;
+		return item;
+	}
 	async persistMeta(slug, item, opts = {}) {
 		let meta = buildCachedItemMeta(item, this.ctx.source);
 		if (this.ctx.hooks.beforeCacheMeta) meta = await this.ctx.hooks.beforeCacheMeta(meta);
@@ -805,30 +918,85 @@ function makeComparator(sort) {
 const DEFAULT_OPTS = {
 	basePath: "/api/cms",
 	imagesPath: "/images",
-	revalidatePath: "/revalidate"
+	revalidatePath: "/revalidate",
+	versionsPath: "/versions",
+	checkPath: "/check",
+	notionWebhookPath: "/notion-webhook"
 };
-/** Webhook 系の CMSError コードを HTTP ステータスへ写像する。未対応コードは null。 */
-function webhookErrorStatus(code) {
+const JSON_HEADERS = { "content-type": "application/json" };
+/** HMAC-SHA256 を hex で返す。core はゼロ依存のため import せずグローバル `crypto.subtle` を使う。 */
+async function hmacSha256Hex(secret, message) {
+	const enc = new TextEncoder();
+	const key = await crypto.subtle.importKey("raw", enc.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	const sig = await crypto.subtle.sign("HMAC", key, enc.encode(message));
+	let hex = "";
+	for (const b of new Uint8Array(sig)) hex += b.toString(16).padStart(2, "0");
+	return hex;
+}
+/** タイミング攻撃を避ける定数時間文字列比較。 */
+function timingSafeEqual(a, b) {
+	if (a.length !== b.length) return false;
+	let diff = 0;
+	for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	return diff === 0;
+}
+function jsonResponse(body, status) {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: JSON_HEADERS
+	});
+}
+function httpStatusForError(code) {
 	if (code === "webhook/signature_invalid") return 401;
 	if (code === "webhook/not_implemented") return 501;
 	if (code === "webhook/unknown_collection") return 404;
 	if (code === "webhook/payload_invalid") return 400;
+	if (code === "handler/unknown_collection") return 404;
 	return null;
 }
+function errorResponse(err) {
+	if (!isCMSError(err)) return null;
+	const status = httpStatusForError(err.code);
+	if (status === null) return null;
+	return new Response(JSON.stringify({
+		ok: false,
+		code: err.code
+	}), {
+		status,
+		headers: JSON_HEADERS
+	});
+}
+function splitCollectionSlug(sub) {
+	const slashIndex = sub.indexOf("/");
+	if (slashIndex <= 0 || slashIndex === sub.length - 1) return null;
+	return {
+		collection: sub.slice(0, slashIndex),
+		slug: sub.slice(slashIndex + 1)
+	};
+}
 /**
 * Web Standard な Request → Response ルーター。
 * Next.js / React Router / Hono / Cloudflare Workers いずれでも使える。
 *
 * ルート:
-* - GET  `{basePath}/images/:hash`              — 画像プロキシ
-* - POST `{basePath}/revalidate/:collection`    — Webhook 受信 + $revalidate()
+* - GET       `{basePath}/images/:hash`               — 画像プロキシ
+* - GET       `{basePath}/versions/:collection/:slug` — peekVersion（更新検知ポーリング）
+* - GET/POST  `{basePath}/check/:collection/:slug?v=` — check（更新を実照会してキャッシュ更新）
+* - POST      `{basePath}/revalidate/:collection`     — Webhook 受信 + $revalidate()
 */
 function createHandler(adapter, opts = {}) {
 	const basePath = trimTrailingSlash(opts.basePath ?? DEFAULT_OPTS.basePath);
 	const imagesPath = opts.imagesPath ?? DEFAULT_OPTS.imagesPath;
 	const revalidatePath = opts.revalidatePath ?? DEFAULT_OPTS.revalidatePath;
+	const versionsPath = opts.versionsPath ?? DEFAULT_OPTS.versionsPath;
+	const checkPath = opts.checkPath ?? DEFAULT_OPTS.checkPath;
+	const notionWebhookPath = opts.notionWebhookPath ?? DEFAULT_OPTS.notionWebhookPath;
 	return async (req) => {
-		const path = new URL(req.url).pathname;
+		const url = new URL(req.url);
+		const path = url.pathname;
 		if (!path.startsWith(basePath)) return new Response("Not Found", { status: 404 });
 		const rel = path.slice(basePath.length) || "/";
 		if (req.method === "GET" && rel.startsWith(`${imagesPath}/`)) {
@@ -841,6 +1009,103 @@ function createHandler(adapter, opts = {}) {
 			headers.set("cache-control", "public, max-age=31536000, immutable");
 			return new Response(object.data, { headers });
 		}
+		if (req.method === "GET" && rel.startsWith(`${versionsPath}/`)) {
+			const target = splitCollectionSlug(rel.slice(versionsPath.length + 1));
+			if (!target) return new Response(JSON.stringify({
+				ok: false,
+				reason: "collection and slug required"
+			}), {
+				status: 400,
+				headers: JSON_HEADERS
+			});
+			try {
+				const version = await adapter.peekVersionFor(target.collection, target.slug);
+				return new Response(JSON.stringify(version), {
+					status: 200,
+					headers: JSON_HEADERS
+				});
+			} catch (err) {
+				const res = errorResponse(err);
+				if (res) return res;
+				throw err;
+			}
+		}
+		if ((req.method === "GET" || req.method === "POST") && rel.startsWith(`${checkPath}/`)) {
+			const target = splitCollectionSlug(rel.slice(checkPath.length + 1));
+			const currentVersion = url.searchParams.get("v");
+			if (!target || !currentVersion) return new Response(JSON.stringify({
+				ok: false,
+				reason: "collection, slug and ?v= are required"
+			}), {
+				status: 400,
+				headers: JSON_HEADERS
+			});
+			try {
+				const result = await adapter.checkFor(target.collection, target.slug, currentVersion);
+				if (result === null) return new Response(JSON.stringify({
+					ok: false,
+					reason: "not found"
+				}), {
+					status: 404,
+					headers: JSON_HEADERS
+				});
+				return new Response(JSON.stringify({ stale: result.stale }), {
+					status: 200,
+					headers: JSON_HEADERS
+				});
+			} catch (err) {
+				const res = errorResponse(err);
+				if (res) return res;
+				throw err;
+			}
+		}
+		if (req.method === "POST" && rel === notionWebhookPath) {
+			const raw = await req.text();
+			let payload;
+			try {
+				payload = JSON.parse(raw);
+			} catch {
+				return jsonResponse({
+					ok: false,
+					reason: "invalid json"
+				}, 400);
+			}
+			if (payload && typeof payload === "object" && "verification_token" in payload) {
+				const token = String(payload.verification_token);
+				opts.notionWebhook?.onVerificationToken?.(token);
+				return jsonResponse({
+					ok: true,
+					verification_token: token
+				}, 200);
+			}
+			const secret = opts.notionWebhook?.secret ?? adapter.notionWebhookSecret;
+			if (!secret) return jsonResponse({
+				ok: false,
+				reason: "notion webhook secret not configured"
+			}, 503);
+			if (!timingSafeEqual(req.headers.get("X-Notion-Signature") ?? "", `sha256=${await hmacSha256Hex(secret, raw)}`)) return jsonResponse({
+				ok: false,
+				code: "webhook/signature_invalid"
+			}, 401);
+			const entity = payload.entity;
+			const pageId = entity?.type === "page" ? entity.id : void 0;
+			if (!pageId) return jsonResponse({
+				ok: true,
+				skipped: "no page entity"
+			}, 200);
+			if (adapter.scheduleBackground) {
+				adapter.scheduleBackground(adapter.warmByPageId(pageId));
+				return jsonResponse({
+					ok: true,
+					pageId
+				}, 200);
+			}
+			return jsonResponse({
+				ok: true,
+				pageId,
+				result: await adapter.warmByPageId(pageId)
+			}, 200);
+		}
 		if (req.method === "POST" && rel.startsWith(`${revalidatePath}/`)) {
 			const collection = rel.slice(revalidatePath.length + 1);
 			if (!collection || collection.includes("/")) return new Response(JSON.stringify({
@@ -848,7 +1113,7 @@ function createHandler(adapter, opts = {}) {
 				reason: "collection required"
 			}), {
 				status: 400,
-				headers: { "content-type": "application/json" }
+				headers: JSON_HEADERS
 			});
 			try {
 				const scope = await adapter.parseWebhookFor(collection, req, opts.webhookSecret);
@@ -858,19 +1123,11 @@ function createHandler(adapter, opts = {}) {
 					scope
 				}), {
 					status: 200,
-					headers: { "content-type": "application/json" }
+					headers: JSON_HEADERS
 				});
 			} catch (err) {
-				if (isCMSError(err)) {
-					const status = webhookErrorStatus(err.code);
-					if (status !== null) return new Response(JSON.stringify({
-						ok: false,
-						code: err.code
-					}), {
-						status,
-						headers: { "content-type": "application/json" }
-					});
-				}
+				const res = errorResponse(err);
+				if (res) return res;
 				throw err;
 			}
 		}
@@ -1011,6 +1268,7 @@ function createClient(opts) {
 	};
 	const collectionNames = [];
 	const collections = {};
+	const collectionImpls = {};
 	for (const [name, def] of Object.entries(collectionsInput)) {
 		collectionNames.push(name);
 		const source = def.source;
@@ -1030,7 +1288,7 @@ function createClient(opts) {
 			hooks: collectionHooks,
 			logger
 		};
-		collections[name] = new CollectionClientImpl({
+		const impl = new CollectionClientImpl({
 			collection: name,
 			source,
 			docCache: cacheRes.doc,
@@ -1046,6 +1304,8 @@ function createClient(opts) {
 			waitUntil,
 			slugField: def.slugField
 		});
+		collections[name] = impl;
+		collectionImpls[name] = impl;
 	}
 	const globalOps = {
 		collections: collectionNames,
@@ -1097,9 +1357,30 @@ function createClient(opts) {
 			});
 			await cacheRes.doc.invalidate(scope ?? "all");
 		},
+		async warmByPageId(pageId) {
+			for (const name of collectionNames) {
+				const slug = await collectionImpls[name]?.warmByPageId(pageId);
+				if (slug) {
+					logger?.debug?.("warmByPageId: ページを再ウォーム", {
+						operation: "warmByPageId",
+						collection: name,
+						slug,
+						pageId
+					});
+					return {
+						collection: name,
+						slug
+					};
+				}
+			}
+			return null;
+		},
 		handler(handlerOpts) {
 			return createHandler({
 				imageCache: cacheRes.img,
+				warmByPageId: (pageId) => globalOps.warmByPageId(pageId),
+				notionWebhookSecret: opts.notionWebhookSecret,
+				scheduleBackground: waitUntil,
 				async parseWebhookFor(collection, req, webhookSecret) {
 					const def = collectionsInput[collection];
 					if (!def) throw new CMSError({
@@ -1121,7 +1402,34 @@ function createClient(opts) {
 					});
 					return ds.parseWebhook(req, { secret: webhookSecret });
 				},
-				revalidate: (scope) => globalOps.invalidate(scope)
+				revalidate: (scope) => globalOps.invalidate(scope),
+				peekVersionFor(collection, slug) {
+					const client = collections[collection];
+					if (!client) throw new CMSError({
+						code: "handler/unknown_collection",
+						message: `Unknown collection: ${collection}`,
+						context: {
+							operation: "peekVersionFor",
+							collection,
+							slug
+						}
+					});
+					return client.peekVersion(slug);
+				},
+				async checkFor(collection, slug, currentVersion) {
+					const client = collections[collection];
+					if (!client) throw new CMSError({
+						code: "handler/unknown_collection",
+						message: `Unknown collection: ${collection}`,
+						context: {
+							operation: "checkFor",
+							collection,
+							slug
+						}
+					});
+					const result = await client.check(slug, currentVersion);
+					return result === null ? null : { stale: result.stale };
+				}
 			}, handlerOpts);
 		},
 		getCachedImage(hash) {
@@ -1131,69 +1439,6 @@ function createClient(opts) {
 	return Object.assign(Object.create(null), collections, globalOps);
 }
 //#endregion
-//#region src/page-index.ts
-/**
-* Notion ページ ID を比較用に正規化する。
-* Notion の ID は文脈によりダッシュの有無・大文字小文字が揺れるため、
-* ダッシュ除去 + 小文字化して突き合わせる。
-*
-* react-renderer 側も同一実装で `pageLinks` を引くため、変更時は両方を揃えること。
-*/
-function normalizePageId(id) {
-	return id.replace(/-/g, "").toLowerCase();
-}
-function asCollectionClient(source, name) {
-	const client = source[name];
-	if (!client || typeof client.list !== "function") return void 0;
-	return client;
-}
-/**
-* 全コレクションを `list()` で走査し、pageId → {collection, slug, title} の逆引きマップを構築する。
-* Notion 内部リンク（link_to_page / page mention など）を自サイト URL へ解決するための材料。
-*
-* `list()` は SWR ドキュメントキャッシュ経由のためウォーム後は安価。
-*/
-async function buildPageIndex(source, opts) {
-	const names = opts?.collections ?? source.collections;
-	const index = /* @__PURE__ */ new Map();
-	if (!names || typeof names[Symbol.iterator] !== "function") return index;
-	for (const name of names) {
-		const client = asCollectionClient(source, name);
-		if (!client) continue;
-		const items = await client.list();
-		if (!Array.isArray(items)) continue;
-		for (const item of items) {
-			const key = normalizePageId(item.id);
-			if (!index.has(key)) index.set(key, {
-				collection: name,
-				slug: item.slug,
-				title: item.title
-			});
-		}
-	}
-	return index;
-}
-const defaultUrl = (entry) => `/${entry.collection}/${entry.slug}`;
-/**
-* Notion 内部リンクを「正規化 pageId → {href, title}」のプレーンマップに解決する。
-* サーバ側（loader / RSC / route handler）で 1 回構築し、`<NotionRenderer pageLinks={...} />`
-* に渡す。プレーンオブジェクトなのでシリアライズ境界（RSC / loader）を越えられる。
-*
-* @example
-* const pageLinks = await buildPageLinkMap(cms);
-* <NotionRenderer blocks={blocks} pageLinks={pageLinks} />;
-*/
-async function buildPageLinkMap(source, opts) {
-	const index = opts?.index ?? await buildPageIndex(source, opts);
-	const toUrl = opts?.url ?? defaultUrl;
-	const map = {};
-	for (const [key, entry] of index) map[key] = {
-		href: toUrl(entry, key),
-		title: entry.title
-	};
-	return map;
-}
-//#endregion
 //#region src/types/config.ts
 /**
 * `RateLimiterConfig` のデフォルト値 (Issue #313 / M2)。