@notion-headless-cms/core 0.3.20 → 0.3.22

package/README.md

@@ -136,4 +136,3 @@ import { memoryCache } from "@notion-headless-cms/core/cache/memory";
 
 - [クイックスタート](../../docs/quickstart.md)
 - [CMS メソッド一覧](../../docs/api/cms-methods.md)
-- [v2.0 移行ガイド](../../docs/migration/v2.0.md)

package/dist/cache/memory.d.mts

@@ -1,2 +1,25 @@
-import { i as memoryCache, n as MemoryDocumentOptions, r as MemoryImageOptions, t as MemoryCacheOptions } from "../memory-BT9rLPr1.mjs";
-export { MemoryCacheOptions, MemoryDocumentOptions, MemoryImageOptions, memoryCache };
+import { t as CacheAdapter } from "../cache-DS81aOcC.mjs";
+
+//#region src/cache/memory.d.ts
+interface MemoryDocumentOptions {
+  /** アイテム保持上限。未指定時は上限なし。超過時は LRU で古いものから削除。 */
+  maxItems?: number;
+}
+interface MemoryImageOptions {
+  /** エントリ保持上限。未指定時は上限なし。超過時は LRU で古いものから削除。 */
+  maxItems?: number;
+  /** 合計保持サイズ上限（バイト）。未指定時は上限なし。超過時は LRU で古いものから削除。 */
+  maxSizeBytes?: number;
+}
+interface MemoryCacheOptions extends MemoryDocumentOptions, MemoryImageOptions {}
+/**
+ * インメモリのキャッシュアダプタ。document + image 両方を担当する。
+ * プロセス再起動でクリアされるため、ローカル開発・SSG ビルド・テスト用途。
+ *
+ * @example
+ * cache: [memoryCache({ maxItems: 1000 })]
+ */
+declare function memoryCache(options?: MemoryCacheOptions): CacheAdapter;
+//#endregion
+export { MemoryCacheOptions, MemoryDocumentOptions, MemoryImageOptions, memoryCache };
+//# sourceMappingURL=memory.d.mts.map

package/dist/{memory-BT9rLPr1.d.mts → cache-DS81aOcC.d.mts}

@@ -133,26 +133,5 @@ interface CacheAdapter {
   img?: ImageCacheOps;
 }
 //#endregion
-//#region src/cache/memory.d.ts
-interface MemoryDocumentOptions {
-  /** アイテム保持上限。未指定時は上限なし。超過時は LRU で古いものから削除。 */
-  maxItems?: number;
-}
-interface MemoryImageOptions {
-  /** エントリ保持上限。未指定時は上限なし。超過時は LRU で古いものから削除。 */
-  maxItems?: number;
-  /** 合計保持サイズ上限（バイト）。未指定時は上限なし。超過時は LRU で古いものから削除。 */
-  maxSizeBytes?: number;
-}
-interface MemoryCacheOptions extends MemoryDocumentOptions, MemoryImageOptions {}
-/**
- * インメモリのキャッシュアダプタ。document + image 両方を担当する。
- * プロセス再起動でクリアされるため、ローカル開発・SSG ビルド・テスト用途。
- *
- * @example
- * cache: [memoryCache({ maxItems: 1000 })]
- */
-declare function memoryCache(options?: MemoryCacheOptions): CacheAdapter;
-//#endregion
-export { CacheAdapter as a, DataSource as c, PropertyDef as d, PropertyMap as f, memoryCache as i, InvalidateKind as l, MemoryDocumentOptions as n, DocumentCacheOps as o, WebhookConfig as p, MemoryImageOptions as r, ImageCacheOps as s, MemoryCacheOptions as t, InvalidateScope as u };
-//# sourceMappingURL=memory-BT9rLPr1.d.mts.map
+export { InvalidateKind as a, PropertyMap as c, DataSource as i, WebhookConfig as l, DocumentCacheOps as n, InvalidateScope as o, ImageCacheOps as r, PropertyDef as s, CacheAdapter as t };
+//# sourceMappingURL=cache-DS81aOcC.d.mts.map

package/dist/config-D4JQ_pmq.d.mts

@@ -0,0 +1,150 @@
+import { t as BaseContentItem } from "./content-DwsfWZao.mjs";
+import { i as DataSource, t as CacheAdapter } from "./cache-DS81aOcC.mjs";
+import { i as CMSHooks, r as Logger, t as CMSPlugin } from "./plugin-B795Ok3X.mjs";
+
+//#region src/types/sources.d.ts
+/**
+ * CMS データソースアダプターのインターフェース。
+ * 各アダプターパッケージ (`@notion-headless-cms/notion-source` 等) が実装し、
+ * `createClient({ sources: { ... } })` に渡される。
+ */
+interface CMSAdapter<C extends CollectionsConfig = CollectionsConfig> {
+  readonly collections: C;
+}
+/**
+ * アダプターパッケージが宣言マージで拡張する空インターフェース。
+ * import するだけでキーが補完候補に現れる (Fastify プラグインと同じパターン)。
+ *
+ * @example
+ * declare module "@notion-headless-cms/core" {
+ *   interface CMSSources {
+ *     notion?: CMSAdapter;
+ *   }
+ * }
+ */
+interface CMSSources {}
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
+/** 全ソースの collections を交差型でマージする。 */
+type MergeSourceCollections<S extends CMSSources> = UnionToIntersection<{ [K in keyof S]: S[K] extends CMSAdapter<infer C> ? C : never }[keyof S]>;
+//#endregion
+//#region src/types/config.d.ts
+/** `Logger` の出力を絞り込むログレベル。指定したレベル未満のログを抑制する。 */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * renderer プラグインの不透明型。
+ * core は unified / remark / rehype に依存せず、このリストをそのまま renderer に渡すだけ。
+ */
+type RendererPluginList = unknown[];
+/**
+ * render() オプション。core は renderer の実装を知らず、この型だけを扱う。
+ * @notion-headless-cms/markdown-html の renderMarkdown() はこのシグネチャと構造的に互換。
+ */
+interface RenderOptions {
+  imageProxyBase?: string;
+  cacheImage?: (url: string) => Promise<string>;
+  remarkPlugins?: RendererPluginList;
+  rehypePlugins?: RendererPluginList;
+}
+/** カスタムレンダラー関数の型。デフォルトは @notion-headless-cms/markdown-html の renderMarkdown。 */
+type RendererFn = (markdown: string, opts?: RenderOptions) => Promise<string>;
+/** レンダリング・コンテンツ処理設定。 */
+interface ContentConfig {
+  /** 追加する remark プラグイン。 */
+  remarkPlugins?: RendererPluginList;
+  /** 追加する rehype プラグイン。 */
+  rehypePlugins?: RendererPluginList;
+}
+/** SWR（Stale-While-Revalidate）設定。 */
+interface SWRConfig {
+  /** SWR の有効期間 (ミリ秒)。未設定時は TTL なし（失効まで stale を返す）。 */
+  ttlMs?: number;
+}
+/** レートリミット・リトライ設定。 */
+interface RateLimiterConfig {
+  /** 同時実行数の上限。デフォルト: 3 */
+  maxConcurrent?: number;
+  /** リトライ対象の HTTP ステータスコード。デフォルト: [429, 502, 503] */
+  retryOn?: number[];
+  /** 最大リトライ回数。デフォルト: 4 */
+  maxRetries?: number;
+  /** リトライ時の基準待機時間（ミリ秒）。デフォルト: 1000 */
+  baseDelayMs?: number;
+}
+/**
+ * コレクション 1 件の定義。CLI が生成する `nhc.ts` から `createClient` に渡される。
+ *
+ * `source` は notion-orm 等の DataSource 実装。
+ * `slugField` / `statusField` は TS フィールド名 (DataSource の `properties` キーと一致)。
+ */
+interface CollectionDef<T extends BaseContentItem = BaseContentItem> {
+  /** Notion etc. のデータソース実装。 */
+  source: DataSource<T>;
+  /** slug として使う TS フィールド名 (必須)。`source.properties[slugField]` で Notion プロパティ名を解決する。 */
+  slugField: string;
+  /** ステータスとして使う TS フィールド名。 */
+  statusField?: string;
+  /** 公開扱いするステータス値。`list()` のデフォルト絞り込みに使う。 */
+  publishedStatuses?: readonly string[];
+  /** アクセス許可するステータス値。`get()` の閲覧可否判定に使う。 */
+  accessibleStatuses?: readonly string[];
+  /** コレクション固有のライフサイクルフック。グローバル hooks の後に実行される。 */
+  hooks?: CMSHooks<T>;
+}
+/**
+ * `createClient({ collections })` の map 型。
+ * キーがコレクション名、値が `CollectionDef<T>`。
+ */
+type CollectionsConfig = Record<string, CollectionDef<BaseContentItem>>;
+/** `CollectionsConfig` から各 T を抽出するユーティリティ型。 */
+type InferCollectionItem<C> = C extends CollectionDef<infer T> ? T : BaseContentItem;
+/**
+ * `createClient()` の入力。
+ *
+ * @example
+ * import { createClient, nodePreset } from "@notion-headless-cms/core";
+ * import { notionSource } from "@notion-headless-cms/notion-source";
+ * import { schema } from "./generated/nhc.schema";
+ *
+ * const cms = createClient({
+ *   sources: { notion: notionSource({ schema, token: process.env.NOTION_TOKEN! }) },
+ *   ...nodePreset(),
+ * });
+ */
+interface CreateClientOptions<S extends CMSSources = CMSSources> {
+  /** データソースアダプター (`@notion-headless-cms/notion-source` 等) のマップ。 */
+  sources?: S;
+  /**
+   * キャッシュアダプタ (配列)。未指定時はキャッシュなし。
+   * - `memoryCache()` のように doc + image 両方を担当するもの
+   * - `r2Cache()` (image のみ)、`kvCache()` (doc のみ) のように片側のみ担当するもの
+   * - 複数 adapter を配列で組み合わせると、各 adapter の `handles` で振り分けられる
+   */
+  cache?: readonly CacheAdapter[];
+  /** SWR（Stale-While-Revalidate）設定。 */
+  swr?: SWRConfig;
+  /**
+   * Markdown→HTML レンダラー。
+   * 省略時は `@notion-headless-cms/markdown-html` の `renderMarkdown` を動的 import で使用する。
+   * カスタム実装も `RendererFn` 型を満たせば使用可能。
+   */
+  renderer?: RendererFn;
+  /** 画像プロキシのベース URL。デフォルト `/api/images`。 */
+  imageProxyBase?: string;
+  /** Cloudflare Workers の `waitUntil` に相当する非同期処理の登録関数。 */
+  waitUntil?: (p: Promise<unknown>) => void;
+  /** ライフサイクルフック (全コレクション共通)。 */
+  hooks?: CMSHooks<BaseContentItem>;
+  /** プラグイン配列。 */
+  plugins?: CMSPlugin<BaseContentItem>[];
+  /** ロガー。 */
+  logger?: Logger;
+  /** ログレベルの下限。指定したレベル未満のログを内部で抑制する。 */
+  logLevel?: LogLevel;
+  /** レートリミット・リトライ設定。 */
+  rateLimiter?: RateLimiterConfig;
+  /** レンダリング・コンテンツ処理設定。 */
+  content?: ContentConfig;
+}
+//#endregion
+export { InferCollectionItem as a, RenderOptions as c, SWRConfig as d, CMSAdapter as f, CreateClientOptions as i, RendererFn as l, MergeSourceCollections as m, CollectionsConfig as n, LogLevel as o, CMSSources as p, ContentConfig as r, RateLimiterConfig as s, CollectionDef as t, RendererPluginList as u };
+//# sourceMappingURL=config-D4JQ_pmq.d.mts.map

package/dist/{errors-CC_x98vG.d.mts → errors-DTt9ii0i.d.mts}

@@ -51,16 +51,27 @@ declare class CMSError extends Error {
   readonly code: CMSErrorCode;
   readonly cause?: unknown;
   readonly context: CMSErrorContext;
+  /** エラーを解消するための次のアクション（表示用）。 */
+  readonly nextSteps?: readonly string[];
+  /** 詳細ドキュメントへの URL（表示用）。 */
+  readonly docsUrl?: string;
   constructor(params: {
     code: CMSErrorCode;
     message: string;
     cause?: unknown;
     context: CMSErrorContext;
+    nextSteps?: readonly string[];
+    docsUrl?: string;
   });
   /** エラーコードが指定した値と一致するか判定する。 */
   is(code: CMSErrorCode): boolean;
   /** エラーコードが指定した名前空間に属するか判定する（例: `"source/"`）。 */
   inNamespace(namespace: string): boolean;
+  /**
+   * nextSteps と docsUrl を含む人間向けの詳細メッセージを返す。
+   * エラーダイアログ・ログ出力時に使う。
+   */
+  format(): string;
 }
 declare function isCMSError(error: unknown): error is CMSError;
 /** エラーコードが特定の名前空間に属するかを判定する（例: "source/"）。 */
@@ -81,4 +92,4 @@ declare function matchCMSError<R>(error: unknown, handlers: Partial<Record<CMSEr
 }): R | undefined;
 //#endregion
 export { isCMSError as a, CMSErrorContext as i, CMSError as n, isCMSErrorInNamespace as o, CMSErrorCode as r, matchCMSError as s, BuiltInCMSErrorCode as t };
-//# sourceMappingURL=errors-CC_x98vG.d.mts.map
+//# sourceMappingURL=errors-DTt9ii0i.d.mts.map

package/dist/errors.d.mts

@@ -1,2 +1,2 @@
-import { a as isCMSError, i as CMSErrorContext, n as CMSError, o as isCMSErrorInNamespace, r as CMSErrorCode, s as matchCMSError, t as BuiltInCMSErrorCode } from "./errors-CC_x98vG.mjs";
+import { a as isCMSError, i as CMSErrorContext, n as CMSError, o as isCMSErrorInNamespace, r as CMSErrorCode, s as matchCMSError, t as BuiltInCMSErrorCode } from "./errors-DTt9ii0i.mjs";
 export { BuiltInCMSErrorCode, CMSError, CMSErrorCode, CMSErrorContext, isCMSError, isCMSErrorInNamespace, matchCMSError };

package/dist/errors.mjs

@@ -3,12 +3,18 @@ var CMSError = class extends Error {
 	code;
 	cause;
 	context;
+	/** エラーを解消するための次のアクション（表示用）。 */
+	nextSteps;
+	/** 詳細ドキュメントへの URL（表示用）。 */
+	docsUrl;
 	constructor(params) {
 		super(params.message, { cause: params.cause });
 		this.name = "CMSError";
 		this.code = params.code;
 		this.cause = params.cause;
 		this.context = params.context;
+		this.nextSteps = params.nextSteps;
+		this.docsUrl = params.docsUrl;
 	}
 	/** エラーコードが指定した値と一致するか判定する。 */
 	is(code) {
@@ -18,6 +24,19 @@ var CMSError = class extends Error {
 	inNamespace(namespace) {
 		return this.code.startsWith(namespace);
 	}
+	/**
+	* nextSteps と docsUrl を含む人間向けの詳細メッセージを返す。
+	* エラーダイアログ・ログ出力時に使う。
+	*/
+	format() {
+		const lines = [this.message];
+		if (this.nextSteps?.length) {
+			lines.push("\n次にやること:");
+			for (const step of this.nextSteps) lines.push(`  - ${step}`);
+		}
+		if (this.docsUrl) lines.push(`\n詳細: ${this.docsUrl}`);
+		return lines.join("\n");
+	}
 };
 function isCMSError(error) {
 	return error instanceof CMSError;

package/dist/errors.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * ライブラリ組み込みの CMS エラーコード。\n *\n * | コード | 発生条件 |\n * |---|---|\n * | `core/config_invalid` | 設定不備（token 未設定など） |\n * | `core/schema_invalid` | schema/mapping の型不整合 |\n * | `core/notion_orm_missing` | `@notion-headless-cms/notion-orm` の動的ロード失敗 |\n * | `core/sort_unsupported_type` | ソートキーの値型が string / number でない |\n * | `webhook/signature_invalid` | Webhook 署名検証失敗 |\n * | `webhook/payload_invalid` | Webhook ペイロード形式不正 |\n * | `webhook/unknown_collection` | Webhook の対象コレクションが未知 |\n * | `webhook/not_implemented` | DataSource が parseWebhook を実装していない |\n * | `source/fetch_items_failed` | `DataSource.list()` 失敗 |\n * | `source/fetch_item_failed` | `DataSource.findByProp()` 失敗 |\n * | `source/load_markdown_failed` | `DataSource.loadMarkdown()` 失敗 |\n * | `source/load_blocks_failed` | `DataSource.loadBlocks()` 失敗 |\n * | `cache/io_failed` | document / image キャッシュの I/O 失敗 |\n * | `cache/image_fetch_failed` | Notion 画像の HTTP 取得失敗 |\n * | `cache/image_invalid_content_type` | 画像レスポンスの Content-Type が不正 |\n * | `renderer/failed` | Markdown → HTML 変換失敗 |\n * | `swr/item_check_failed` | SWR バックグラウンドのアイテム差分チェック失敗 |\n * | `swr/list_check_failed` | SWR バックグラウンドのリスト差分チェック失敗 |\n * | `swr/content_rebuild_failed` | SWR バックグラウンドの本文再生成失敗 |\n * | `cli/config_invalid` | `nhc.config.ts` の内容不整合 |\n * | `cli/config_load_failed` | 設定ファイルの読み込み / 評価失敗 |\n * | `cli/schema_invalid` | CLI が受け取ったスキーマ / マッピング不整合 |\n * | `cli/generate_failed` | `nhc generate` の処理失敗 |\n * | `cli/init_failed` | `nhc init` の処理失敗 |\n * | `cli/notion_api_failed` | CLI が Notion API を呼び出す際の失敗 |\n * | `cli/env_file_not_found` | `--env-file` で指定したファイルが存在しない |\n *\n * サードパーティアダプタが独自コードを追加したい場合は `CMSErrorCode` を参照。\n */\nexport type BuiltInCMSErrorCode =\n  | \"core/config_invalid\"\n  | \"core/schema_invalid\"\n  | \"core/notion_orm_missing\"\n  | \"core/sort_unsupported_type\"\n  | \"webhook/signature_invalid\"\n  | \"webhook/payload_invalid\"\n  | \"webhook/unknown_collection\"\n  | \"webhook/not_implemented\"\n  | \"source/fetch_items_failed\"\n  | \"source/fetch_item_failed\"\n  | \"source/load_markdown_failed\"\n  | \"source/load_blocks_failed\"\n  | \"cache/io_failed\"\n  | \"cache/image_fetch_failed\"\n  | \"cache/image_invalid_content_type\"\n  | \"renderer/failed\"\n  | \"swr/item_check_failed\"\n  | \"swr/list_check_failed\"\n  | \"swr/content_rebuild_failed\"\n  | \"cli/config_invalid\"\n  | \"cli/config_load_failed\"\n  | \"cli/schema_invalid\"\n  | \"cli/generate_failed\"\n  | \"cli/init_failed\"\n  | \"cli/notion_api_failed\"\n  | \"cli/env_file_not_found\";\n\n/**\n * CMS エラーコード。\n * `BuiltInCMSErrorCode` のリテラル補完を維持しつつ、\n * サードパーティアダプタが独自コードを定義できるよう `string & {}` で拡張可能にする。\n */\nexport type CMSErrorCode = BuiltInCMSErrorCode | (string & {});\n\nexport interface CMSErrorContext {\n  operation: string;\n  slug?: string;\n  dataSourceId?: string;\n  pageId?: string;\n  [key: string]: string | number | boolean | null | undefined;\n}\n\nexport class CMSError extends Error {\n  readonly code: CMSErrorCode;\n  override readonly cause?: unknown;\n  readonly context: CMSErrorContext;\n\n  constructor(params: {\n    code: CMSErrorCode;\n    message: string;\n    cause?: unknown;\n    context: CMSErrorContext;\n  }) {\n    super(params.message, { cause: params.cause });\n    this.name = \"CMSError\";\n    this.code = params.code;\n    this.cause = params.cause;\n    this.context = params.context;\n  }\n\n  /** エラーコードが指定した値と一致するか判定する。 */\n  is(code: CMSErrorCode): boolean {\n    return this.code === code;\n  }\n\n  /** エラーコードが指定した名前空間に属するか判定する（例: `\"source/\"`）。 */\n  inNamespace(namespace: string): boolean {\n    return this.code.startsWith(namespace);\n  }\n}\n\nexport function isCMSError(error: unknown): error is CMSError {\n  return error instanceof CMSError;\n}\n\n/** エラーコードが特定の名前空間に属するかを判定する（例: \"source/\"）。 */\nexport function isCMSErrorInNamespace(\n  error: unknown,\n  namespace: string,\n): error is CMSError {\n  return isCMSError(error) && error.code.startsWith(namespace);\n}\n\ntype CMSErrorHandler<R> = (err: CMSError) => R;\n\n/**\n * `CMSError` を switch 式のように分岐して処理するユーティリティ。\n * `_` キーはフォールバック（CMSError 以外 or 未マッチ時）に使われる。\n *\n * @example\n * matchCMSError(err, {\n *   \"source/fetch_items_failed\": (e) => handleFetchError(e),\n *   _: (e) => { throw e; },\n * });\n */\nexport function matchCMSError<R>(\n  error: unknown,\n  handlers: Partial<Record<CMSErrorCode, CMSErrorHandler<R>>> & {\n    _?: (err: unknown) => R;\n  },\n): R | undefined {\n  if (!isCMSError(error)) {\n    return handlers._?.(error);\n  }\n  const handler =\n    handlers[error.code as CMSErrorCode] ??\n    (handlers._ as CMSErrorHandler<R> | undefined);\n  return handler?.(error);\n}\n"],"mappings":";AA6EA,IAAa,WAAb,cAA8B,MAAM;CAClC;CACA;CACA;CAEA,YAAY,QAKT;AACD,QAAM,OAAO,SAAS,EAAE,OAAO,OAAO,OAAO,CAAC;AAC9C,OAAK,OAAO;AACZ,OAAK,OAAO,OAAO;AACnB,OAAK,QAAQ,OAAO;AACpB,OAAK,UAAU,OAAO;;;CAIxB,GAAG,MAA6B;AAC9B,SAAO,KAAK,SAAS;;;CAIvB,YAAY,WAA4B;AACtC,SAAO,KAAK,KAAK,WAAW,UAAU;;;AAI1C,SAAgB,WAAW,OAAmC;AAC5D,QAAO,iBAAiB;;;AAI1B,SAAgB,sBACd,OACA,WACmB;AACnB,QAAO,WAAW,MAAM,IAAI,MAAM,KAAK,WAAW,UAAU;;;;;;;;;;;;AAe9D,SAAgB,cACd,OACA,UAGe;AACf,KAAI,CAAC,WAAW,MAAM,CACpB,QAAO,SAAS,IAAI,MAAM;AAK5B,SAFE,SAAS,MAAM,SACd,SAAS,KACK,MAAM"}
+{"version":3,"file":"errors.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * ライブラリ組み込みの CMS エラーコード。\n *\n * | コード | 発生条件 |\n * |---|---|\n * | `core/config_invalid` | 設定不備（token 未設定など） |\n * | `core/schema_invalid` | schema/mapping の型不整合 |\n * | `core/notion_orm_missing` | `@notion-headless-cms/notion-orm` の動的ロード失敗 |\n * | `core/sort_unsupported_type` | ソートキーの値型が string / number でない |\n * | `webhook/signature_invalid` | Webhook 署名検証失敗 |\n * | `webhook/payload_invalid` | Webhook ペイロード形式不正 |\n * | `webhook/unknown_collection` | Webhook の対象コレクションが未知 |\n * | `webhook/not_implemented` | DataSource が parseWebhook を実装していない |\n * | `source/fetch_items_failed` | `DataSource.list()` 失敗 |\n * | `source/fetch_item_failed` | `DataSource.findByProp()` 失敗 |\n * | `source/load_markdown_failed` | `DataSource.loadMarkdown()` 失敗 |\n * | `source/load_blocks_failed` | `DataSource.loadBlocks()` 失敗 |\n * | `cache/io_failed` | document / image キャッシュの I/O 失敗 |\n * | `cache/image_fetch_failed` | Notion 画像の HTTP 取得失敗 |\n * | `cache/image_invalid_content_type` | 画像レスポンスの Content-Type が不正 |\n * | `renderer/failed` | Markdown → HTML 変換失敗 |\n * | `swr/item_check_failed` | SWR バックグラウンドのアイテム差分チェック失敗 |\n * | `swr/list_check_failed` | SWR バックグラウンドのリスト差分チェック失敗 |\n * | `swr/content_rebuild_failed` | SWR バックグラウンドの本文再生成失敗 |\n * | `cli/config_invalid` | `nhc.config.ts` の内容不整合 |\n * | `cli/config_load_failed` | 設定ファイルの読み込み / 評価失敗 |\n * | `cli/schema_invalid` | CLI が受け取ったスキーマ / マッピング不整合 |\n * | `cli/generate_failed` | `nhc generate` の処理失敗 |\n * | `cli/init_failed` | `nhc init` の処理失敗 |\n * | `cli/notion_api_failed` | CLI が Notion API を呼び出す際の失敗 |\n * | `cli/env_file_not_found` | `--env-file` で指定したファイルが存在しない |\n *\n * サードパーティアダプタが独自コードを追加したい場合は `CMSErrorCode` を参照。\n */\nexport type BuiltInCMSErrorCode =\n  | \"core/config_invalid\"\n  | \"core/schema_invalid\"\n  | \"core/notion_orm_missing\"\n  | \"core/sort_unsupported_type\"\n  | \"webhook/signature_invalid\"\n  | \"webhook/payload_invalid\"\n  | \"webhook/unknown_collection\"\n  | \"webhook/not_implemented\"\n  | \"source/fetch_items_failed\"\n  | \"source/fetch_item_failed\"\n  | \"source/load_markdown_failed\"\n  | \"source/load_blocks_failed\"\n  | \"cache/io_failed\"\n  | \"cache/image_fetch_failed\"\n  | \"cache/image_invalid_content_type\"\n  | \"renderer/failed\"\n  | \"swr/item_check_failed\"\n  | \"swr/list_check_failed\"\n  | \"swr/content_rebuild_failed\"\n  | \"cli/config_invalid\"\n  | \"cli/config_load_failed\"\n  | \"cli/schema_invalid\"\n  | \"cli/generate_failed\"\n  | \"cli/init_failed\"\n  | \"cli/notion_api_failed\"\n  | \"cli/env_file_not_found\";\n\n/**\n * CMS エラーコード。\n * `BuiltInCMSErrorCode` のリテラル補完を維持しつつ、\n * サードパーティアダプタが独自コードを定義できるよう `string & {}` で拡張可能にする。\n */\nexport type CMSErrorCode = BuiltInCMSErrorCode | (string & {});\n\nexport interface CMSErrorContext {\n  operation: string;\n  slug?: string;\n  dataSourceId?: string;\n  pageId?: string;\n  [key: string]: string | number | boolean | null | undefined;\n}\n\nexport class CMSError extends Error {\n  readonly code: CMSErrorCode;\n  override readonly cause?: unknown;\n  readonly context: CMSErrorContext;\n  /** エラーを解消するための次のアクション（表示用）。 */\n  readonly nextSteps?: readonly string[];\n  /** 詳細ドキュメントへの URL（表示用）。 */\n  readonly docsUrl?: string;\n\n  constructor(params: {\n    code: CMSErrorCode;\n    message: string;\n    cause?: unknown;\n    context: CMSErrorContext;\n    nextSteps?: readonly string[];\n    docsUrl?: string;\n  }) {\n    super(params.message, { cause: params.cause });\n    this.name = \"CMSError\";\n    this.code = params.code;\n    this.cause = params.cause;\n    this.context = params.context;\n    this.nextSteps = params.nextSteps;\n    this.docsUrl = params.docsUrl;\n  }\n\n  /** エラーコードが指定した値と一致するか判定する。 */\n  is(code: CMSErrorCode): boolean {\n    return this.code === code;\n  }\n\n  /** エラーコードが指定した名前空間に属するか判定する（例: `\"source/\"`）。 */\n  inNamespace(namespace: string): boolean {\n    return this.code.startsWith(namespace);\n  }\n\n  /**\n   * nextSteps と docsUrl を含む人間向けの詳細メッセージを返す。\n   * エラーダイアログ・ログ出力時に使う。\n   */\n  format(): string {\n    const lines: string[] = [this.message];\n    if (this.nextSteps?.length) {\n      lines.push(\"\\n次にやること:\");\n      for (const step of this.nextSteps) {\n        lines.push(`  - ${step}`);\n      }\n    }\n    if (this.docsUrl) {\n      lines.push(`\\n詳細: ${this.docsUrl}`);\n    }\n    return lines.join(\"\\n\");\n  }\n}\n\nexport function isCMSError(error: unknown): error is CMSError {\n  return error instanceof CMSError;\n}\n\n/** エラーコードが特定の名前空間に属するかを判定する（例: \"source/\"）。 */\nexport function isCMSErrorInNamespace(\n  error: unknown,\n  namespace: string,\n): error is CMSError {\n  return isCMSError(error) && error.code.startsWith(namespace);\n}\n\ntype CMSErrorHandler<R> = (err: CMSError) => R;\n\n/**\n * `CMSError` を switch 式のように分岐して処理するユーティリティ。\n * `_` キーはフォールバック（CMSError 以外 or 未マッチ時）に使われる。\n *\n * @example\n * matchCMSError(err, {\n *   \"source/fetch_items_failed\": (e) => handleFetchError(e),\n *   _: (e) => { throw e; },\n * });\n */\nexport function matchCMSError<R>(\n  error: unknown,\n  handlers: Partial<Record<CMSErrorCode, CMSErrorHandler<R>>> & {\n    _?: (err: unknown) => R;\n  },\n): R | undefined {\n  if (!isCMSError(error)) {\n    return handlers._?.(error);\n  }\n  const handler =\n    handlers[error.code as CMSErrorCode] ??\n    (handlers._ as CMSErrorHandler<R> | undefined);\n  return handler?.(error);\n}\n"],"mappings":";AA6EA,IAAa,WAAb,cAA8B,MAAM;CAClC;CACA;CACA;;CAEA;;CAEA;CAEA,YAAY,QAOT;AACD,QAAM,OAAO,SAAS,EAAE,OAAO,OAAO,OAAO,CAAC;AAC9C,OAAK,OAAO;AACZ,OAAK,OAAO,OAAO;AACnB,OAAK,QAAQ,OAAO;AACpB,OAAK,UAAU,OAAO;AACtB,OAAK,YAAY,OAAO;AACxB,OAAK,UAAU,OAAO;;;CAIxB,GAAG,MAA6B;AAC9B,SAAO,KAAK,SAAS;;;CAIvB,YAAY,WAA4B;AACtC,SAAO,KAAK,KAAK,WAAW,UAAU;;;;;;CAOxC,SAAiB;EACf,MAAM,QAAkB,CAAC,KAAK,QAAQ;AACtC,MAAI,KAAK,WAAW,QAAQ;AAC1B,SAAM,KAAK,YAAY;AACvB,QAAK,MAAM,QAAQ,KAAK,UACtB,OAAM,KAAK,OAAO,OAAO;;AAG7B,MAAI,KAAK,QACP,OAAM,KAAK,SAAS,KAAK,UAAU;AAErC,SAAO,MAAM,KAAK,KAAK;;;AAI3B,SAAgB,WAAW,OAAmC;AAC5D,QAAO,iBAAiB;;;AAI1B,SAAgB,sBACd,OACA,WACmB;AACnB,QAAO,WAAW,MAAM,IAAI,MAAM,KAAK,WAAW,UAAU;;;;;;;;;;;;AAe9D,SAAgB,cACd,OACA,UAGe;AACf,KAAI,CAAC,WAAW,MAAM,CACpB,QAAO,SAAS,IAAI,MAAM;AAK5B,SAFE,SAAS,MAAM,SACd,SAAS,KACK,MAAM"}

package/dist/hooks.d.mts

@@ -1,2 +1,17 @@
-import { n as mergeLoggers, t as mergeHooks } from "./hooks-C6F2PG8x.mjs";
-export { mergeHooks, mergeLoggers };
+import { t as BaseContentItem } from "./content-DwsfWZao.mjs";
+import { i as CMSHooks, r as Logger, t as CMSPlugin } from "./plugin-B795Ok3X.mjs";
+
+//#region src/hooks.d.ts
+/**
+ * プラグイン配列とダイレクトフックを合成して単一の CMSHooks を返す。
+ * beforeCacheMeta / beforeCacheContent / afterRender はパイプライン（前の出力が次の入力）。
+ * オブザーバー系は全員に同じ値を渡し、例外は logger に流して握りつぶす。
+ */
+declare function mergeHooks<T extends BaseContentItem>(plugins: CMSPlugin<T>[], directHooks?: CMSHooks<T>, logger?: Logger): CMSHooks<T>;
+/** プラグイン配列とダイレクトロガーを合成して単一の Logger を返す。 */
+declare function mergeLoggers(plugins: Array<{
+  logger?: Partial<Logger>;
+}>, directLogger?: Logger): Logger | undefined;
+//#endregion
+export { mergeHooks, mergeLoggers };
+//# sourceMappingURL=hooks.d.mts.map

package/dist/html.d.mts

@@ -2,20 +2,26 @@
 interface NotionRevalidatorScriptOptions {
   /**
    * 再検証のトリガー。既定値: "visibility"
-   * - "visibility": タブ可視化 (`visibilitychange` で hidden→visible) の度に reload
+   * - "visibility": `visibilitychange` で hidden→visible の度に reload
    * - "focus": ウィンドウ focus の度に reload (visibility より発火が頻繁)
    */
   on?: "visibility" | "focus";
-  /**
-   * `<script nonce="...">` を出力したい場合 (CSP 対応)。
-   * 英数字・`-` / `_` / `+` / `/` / `=` のみ許可。属性値ブレイクアウトを防ぐため
-   * 不正な文字が含まれていれば throw する。
-   */
+  /** CSP 対応の `nonce` 値。base64 / base64url 由来の文字のみ許可、不正値は throw する。 */
   nonce?: string;
 }
 /**
- * React を使わないページに埋め込むための `<script>...</script>` 文字列を返す。
- * 返り値は外部入力を埋め込まない（nonce は厳格に検証）safe な内容。
+ * React を使わないテンプレート (Astro / Hono / Express など) 向けに、
+ * SWR 再検証用の `<script>...</script>` 文字列を返す。
+ *
+ * タブ可視化や focus を検知して `location.reload()` を呼び、サーバ側で
+ * `waitUntil` 配線済みの SWR bg が更新したキャッシュを次回訪問時に取得する。
+ * クエリ無し・別 API fetch 無し。
+ *
+ * @example
+ * // Astro
+ * <Fragment set:html={notionRevalidatorScript()} />
+ * // Hono
+ * c.html(h`...${raw(notionRevalidatorScript())}`);
  */
 declare function notionRevalidatorScript(opts?: NotionRevalidatorScriptOptions): string;
 //#endregion

package/dist/html.mjs

@@ -1,8 +1,18 @@
 //#region src/html.ts
 const NONCE_PATTERN = /^[A-Za-z0-9+/=_-]+$/;
 /**
-* React を使わないページに埋め込むための `<script>...<\/script>` 文字列を返す。
-* 返り値は外部入力を埋め込まない（nonce は厳格に検証）safe な内容。
+* React を使わないテンプレート (Astro / Hono / Express など) 向けに、
+* SWR 再検証用の `<script>...<\/script>` 文字列を返す。
+*
+* タブ可視化や focus を検知して `location.reload()` を呼び、サーバ側で
+* `waitUntil` 配線済みの SWR bg が更新したキャッシュを次回訪問時に取得する。
+* クエリ無し・別 API fetch 無し。
+*
+* @example
+* // Astro
+* <Fragment set:html={notionRevalidatorScript()} />
+* // Hono
+* c.html(h`...${raw(notionRevalidatorScript())}`);
 */
 function notionRevalidatorScript(opts = {}) {
 	const body = (opts.on ?? "visibility") === "focus" ? "let l=false;addEventListener(\"focus\",()=>{if(l)location.reload();l=true});" : "document.addEventListener(\"visibilitychange\",()=>{if(document.visibilityState===\"visible\")location.reload()});";

package/dist/html.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"html.mjs","names":[],"sources":["../src/html.ts"],"sourcesContent":["// React を使わないテンプレート (Astro / Hono / Express など) で SWR 体験を\n// 成立させるための、ゼロ依存の小さな <script> 文字列ジェネレータ。\n//\n// 使い方 (Astro):\n//   import { notionRevalidatorScript } from \"@notion-headless-cms/core/html\";\n//   <Fragment set:html={notionRevalidatorScript()} />\n//\n// 使い方 (Hono):\n//   import { raw, html as h } from \"hono/html\";\n//   c.html(h`...${raw(notionRevalidatorScript())}`);\n//\n// 仕組み: タブ可視化 (visibilitychange で hidden→visible) を検知して\n// `location.reload()` で同じ URL を再リクエストする。サーバ側は\n// `cloudflarePreset` 等で `waitUntil` が配線されていれば、前回訪問時に\n// SWR bg が KV を最新化済み → 再取得で新内容が返る。クエリ無し・別 API fetch 無し。\n\nexport interface NotionRevalidatorScriptOptions {\n  /**\n   * 再検証のトリガー。既定値: \"visibility\"\n   * - \"visibility\": タブ可視化 (`visibilitychange` で hidden→visible) の度に reload\n   * - \"focus\": ウィンドウ focus の度に reload (visibility より発火が頻繁)\n   */\n  on?: \"visibility\" | \"focus\";\n  /**\n   * `<script nonce=\"...\">` を出力したい場合 (CSP 対応)。\n   * 英数字・`-` / `_` / `+` / `/` / `=` のみ許可。属性値ブレイクアウトを防ぐため\n   * 不正な文字が含まれていれば throw する。\n   */\n  nonce?: string;\n}\n\n// CSP nonce は本来 base64 / base64url 由来のランダム文字列。属性値の\n// クォート・タグブレイクアウトを未然に防ぐため、最小限の許可セットで検証する。\nconst NONCE_PATTERN = /^[A-Za-z0-9+/=_-]+$/;\n\n/**\n * React を使わないページに埋め込むための `<script>...</script>` 文字列を返す。\n * 返り値は外部入力を埋め込まない（nonce は厳格に検証）safe な内容。\n */\nexport function notionRevalidatorScript(\n  opts: NotionRevalidatorScriptOptions = {},\n): string {\n  const trigger = opts.on ?? \"visibility\";\n  const body =\n    trigger === \"focus\"\n      ? // 初回ロード時の focus は無視するため、loaded フラグで初回をスキップ。\n        'let l=false;addEventListener(\"focus\",()=>{if(l)location.reload();l=true});'\n      : 'document.addEventListener(\"visibilitychange\",()=>{if(document.visibilityState===\"visible\")location.reload()});';\n  let nonceAttr = \"\";\n  if (opts.nonce !== undefined) {\n    if (!NONCE_PATTERN.test(opts.nonce)) {\n      throw new Error(\n        \"notionRevalidatorScript: nonce に不正な文字が含まれています。base64 / base64url 由来の英数字のみ受け付けます。\",\n      );\n    }\n    nonceAttr = ` nonce=\"${opts.nonce}\"`;\n  }\n  return `<script${nonceAttr}>(()=>{${body}})();</script>`;\n}\n"],"mappings":";AAiCA,MAAM,gBAAgB;;;;;AAMtB,SAAgB,wBACd,OAAuC,EAAE,EACjC;CAER,MAAM,QADU,KAAK,MAAM,kBAEb,UAER,iFACA;CACN,IAAI,YAAY;AAChB,KAAI,KAAK,UAAU,KAAA,GAAW;AAC5B,MAAI,CAAC,cAAc,KAAK,KAAK,MAAM,CACjC,OAAM,IAAI,MACR,mFACD;AAEH,cAAY,WAAW,KAAK,MAAM;;AAEpC,QAAO,UAAU,UAAU,SAAS,KAAK"}
+{"version":3,"file":"html.mjs","names":[],"sources":["../src/html.ts"],"sourcesContent":["export interface NotionRevalidatorScriptOptions {\n  /**\n   * 再検証のトリガー。既定値: \"visibility\"\n   * - \"visibility\": `visibilitychange` で hidden→visible の度に reload\n   * - \"focus\": ウィンドウ focus の度に reload (visibility より発火が頻繁)\n   */\n  on?: \"visibility\" | \"focus\";\n  /** CSP 対応の `nonce` 値。base64 / base64url 由来の文字のみ許可、不正値は throw する。 */\n  nonce?: string;\n}\n\n// 属性値ブレイクアウトを防ぐため、CSP nonce は base64 / base64url 範囲に限定して検証する\nconst NONCE_PATTERN = /^[A-Za-z0-9+/=_-]+$/;\n\n/**\n * React を使わないテンプレート (Astro / Hono / Express など) 向けに、\n * SWR 再検証用の `<script>...</script>` 文字列を返す。\n *\n * タブ可視化や focus を検知して `location.reload()` を呼び、サーバ側で\n * `waitUntil` 配線済みの SWR bg が更新したキャッシュを次回訪問時に取得する。\n * クエリ無し・別 API fetch 無し。\n *\n * @example\n * // Astro\n * <Fragment set:html={notionRevalidatorScript()} />\n * // Hono\n * c.html(h`...${raw(notionRevalidatorScript())}`);\n */\nexport function notionRevalidatorScript(\n  opts: NotionRevalidatorScriptOptions = {},\n): string {\n  const trigger = opts.on ?? \"visibility\";\n  const body =\n    trigger === \"focus\"\n      ? // 初回ロード直後の focus は無視するため、loaded フラグで初回をスキップ\n        'let l=false;addEventListener(\"focus\",()=>{if(l)location.reload();l=true});'\n      : 'document.addEventListener(\"visibilitychange\",()=>{if(document.visibilityState===\"visible\")location.reload()});';\n  let nonceAttr = \"\";\n  if (opts.nonce !== undefined) {\n    if (!NONCE_PATTERN.test(opts.nonce)) {\n      throw new Error(\n        \"notionRevalidatorScript: nonce に不正な文字が含まれています。base64 / base64url 由来の英数字のみ受け付けます。\",\n      );\n    }\n    nonceAttr = ` nonce=\"${opts.nonce}\"`;\n  }\n  return `<script${nonceAttr}>(()=>{${body}})();</script>`;\n}\n"],"mappings":";AAYA,MAAM,gBAAgB;;;;;;;;;;;;;;;AAgBtB,SAAgB,wBACd,OAAuC,EAAE,EACjC;CAER,MAAM,QADU,KAAK,MAAM,kBAEb,UAER,iFACA;CACN,IAAI,YAAY;AAChB,KAAI,KAAK,UAAU,KAAA,GAAW;AAC5B,MAAI,CAAC,cAAc,KAAK,KAAK,MAAM,CACjC,OAAM,IAAI,MACR,mFACD;AAEH,cAAY,WAAW,KAAK,MAAM;;AAEpC,QAAO,UAAU,UAAU,SAAS,KAAK"}