@notion-headless-cms/core 0.3.20 → 0.3.22

package/dist/index.d.mts

@@ -1,7 +1,11 @@
 import { a as CachedItemMeta, c as ContentResult, i as CachedItemList, l as ImageRef, n as CMSSchemaProperties, o as StorageBinary, r as CachedItemContent, s as ContentBlock, t as BaseContentItem, u as InlineNode } from "./content-DwsfWZao.mjs";
-import { a as CacheAdapter, c as DataSource, d as PropertyDef, f as PropertyMap, i as memoryCache, l as InvalidateKind, o as DocumentCacheOps, p as WebhookConfig, s as ImageCacheOps, t as MemoryCacheOptions, u as InvalidateScope } from "./memory-BT9rLPr1.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-CC_x98vG.mjs";
-import { a as Logger, i as definePlugin, n as mergeLoggers, o as CMSHooks, r as CMSPlugin, s as MaybePromise, t as mergeHooks } from "./hooks-C6F2PG8x.mjs";
+import { a as InvalidateKind, c as PropertyMap, i as DataSource, l as WebhookConfig, n as DocumentCacheOps, o as InvalidateScope, r as ImageCacheOps, s as PropertyDef, t as CacheAdapter } from "./cache-DS81aOcC.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";
+import { a as MaybePromise, i as CMSHooks, n as definePlugin, r as Logger, t as CMSPlugin } from "./plugin-B795Ok3X.mjs";
+import { a as InferCollectionItem, c as RenderOptions, d as SWRConfig, i as CreateClientOptions, l as RendererFn, m as MergeSourceCollections, n as CollectionsConfig, o as LogLevel, p as CMSSources, r as ContentConfig, s as RateLimiterConfig, u as RendererPluginList } from "./config-D4JQ_pmq.mjs";
+import { MemoryCacheOptions, memoryCache } from "./cache/memory.mjs";
+import { mergeHooks, mergeLoggers } from "./hooks.mjs";
+import { NodePresetOptions, nodePreset } from "./preset/node.mjs";
 
 //#region src/types/collection.d.ts
 /**
@@ -136,162 +140,6 @@ interface CollectionClient<T extends BaseContentItem = BaseContentItem> {
   cache: CollectionCacheOps<T>;
 }
 //#endregion
-//#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/renderer の renderMarkdown() はこのシグネチャと構造的に互換。
- */
-interface RenderOptions {
-  imageProxyBase?: string;
-  cacheImage?: (url: string) => Promise<string>;
-  remarkPlugins?: RendererPluginList;
-  rehypePlugins?: RendererPluginList;
-}
-/** カスタムレンダラー関数の型。デフォルトは @notion-headless-cms/renderer の renderMarkdown。 */
-type RendererFn = (markdown: string, opts?: RenderOptions) => Promise<string>;
-/** レンダリング・コンテンツ処理設定。 */
-interface ContentConfig {
-  /** 画像プロキシのベースURL。デフォルト: '/api/images' */
-  imageProxyBase?: string;
-  /** 追加する 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()` の入力。
- * 通常は CLI が生成した `nhc.ts` の `createClient` がこの型をラップする。
- *
- * @example
- * createClient({
- *   collections: {
- *     posts: {
- *       source: createNotionCollection({ token, dataSourceId, properties }),
- *       slugField: "slug",
- *       statusField: "status",
- *       publishedStatuses: ["公開済み"],
- *     }
- *   },
- *   cache: [memoryCache()],
- *   swr: { ttlMs: 5 * 60_000 },
- * });
- */
-interface CreateClientOptions<C extends CollectionsConfig = CollectionsConfig, S extends CMSSources = CMSSources> {
-  /**
-   * データソースアダプター (`@notion-headless-cms/notion-source` 等) のマップ。
-   * `sources` を指定する場合 `collections` は不要。両方指定された場合は `sources` が優先される。
-   */
-  sources?: S;
-  /** コレクション定義のマップ。`sources` を使う場合は不要。 */
-  collections?: C;
-  /**
-   * キャッシュアダプタ (配列)。未指定時はキャッシュなし。
-   * - `memoryCache()` のように doc + image 両方を担当するもの
-   * - `r2Cache()` (image のみ)、`kvCache()` (doc のみ) のように片側のみ担当するもの
-   * - 複数 adapter を配列で組み合わせると、各 adapter の `handles` で振り分けられる
-   */
-  cache?: readonly CacheAdapter[];
-  /** SWR（Stale-While-Revalidate）設定。 */
-  swr?: SWRConfig;
-  /**
-   * Markdown→HTML レンダラー。
-   * 省略時は `@notion-headless-cms/renderer` の `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
 //#region src/cache.d.ts
 /** 文字列をSHA-256でハッシュ化し、16進数文字列として返す。画像キーの生成に使用。 */
 declare function sha256Hex(input: string): Promise<string>;
@@ -345,65 +193,37 @@ interface HandlerAdapter {
 declare function createHandler(adapter: HandlerAdapter, opts?: HandlerOptions): (req: Request) => Promise<Response>;
 //#endregion
 //#region src/cms.d.ts
-/** `CMSClient<C>` — コレクション別アクセス + グローバル操作の合成型。 */
+/** コレクション別アクセス + グローバル操作の合成型。 */
 type CMSClient<C extends CollectionsConfig> = { [K in keyof C]: CollectionClient<InferCollectionItem<C[K]>> } & CMSGlobalOps;
-/** `CMSClient` のグローバル名前空間。 */
 interface CMSGlobalOps {
-  /** 登録されているコレクション名の一覧。 */
   readonly collections: readonly string[];
-  /** 全コレクションまたは特定スコープのキャッシュを無効化する。 */
   invalidate(scope?: InvalidateScope): Promise<void>;
-  /** Web Standard なルーティングハンドラ (画像プロキシ / webhook) を生成する。 */
+  /** Web Standard な Request/Response ベースのルートハンドラ (画像プロキシ + webhook)。 */
   handler(opts?: HandlerOptions): (req: Request) => Promise<Response>;
-  /** ハッシュキーでキャッシュ画像を取得する。 */
   getCachedImage(hash: string): Promise<StorageBinary | null>;
   /**
-   * Notion 画像 URL を `{imageProxyBase}/{sha256}` 形式へ変換しキャッシュへ書き込む関数。
-   * 画像キャッシュが未設定 (noop) の場合は `undefined`。react-renderer の
-   * `resolveBlockImageUrls` などサーバー側で URL 書き換えに使う。
+   * Notion 画像 URL を `{imageProxyBase}/{sha256}` 形式へ変換しキャッシュへ書き込む。
+   * 画像キャッシュが未設定 (noop) の場合は `undefined`。
    */
   readonly cacheImage: ((url: string) => Promise<string>) | undefined;
-  /**
-   * 画像プロキシのベース URL (`createClient({ imageProxyBase })`)。
-   * デフォルト `/api/images`。
-   */
   readonly imageProxyBase: string;
 }
 /**
- * 複数の `CollectionDef` を束ねた CMS クライアントを生成する。
- *
- * 通常はユーザーが直接呼ぶことはなく、CLI 生成の `nhc.ts` の `createClient`
- * (低レベルのこの関数をラップしたもの) を経由する。
+ * CMS クライアントを生成する。
  *
  * @example
- * createClient({
- *   collections: {
- *     posts: {
- *       source: createNotionCollection({ token, dataSourceId, properties }),
- *       slugField: "slug",
- *       statusField: "status",
- *       publishedStatuses: ["公開済み"],
- *     }
- *   },
- *   cache: [memoryCache()],
- *   swr: { ttlMs: 5 * 60_000 },
+ * 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(),
  * });
+ *
+ * const posts = await cms.posts.list();
  */
-declare function createClient<C extends CollectionsConfig = CollectionsConfig, S extends CMSSources = CMSSources>(opts: CreateClientOptions<C, S>): CMSClient<MergeSourceCollections<S> extends CollectionsConfig ? MergeSourceCollections<S> : C>;
-//#endregion
-//#region src/rendering.d.ts
-/** 本文レンダリングに必要な依存を束ねたコンテキスト。 */
-interface RenderContext<T extends BaseContentItem> {
-  source: DataSource<T>;
-  rendererFn: RendererFn | undefined;
-  imgCache: ImageCacheOps;
-  imgCacheName: string;
-  hasImageCache: boolean;
-  imageProxyBase: string;
-  contentConfig: ContentConfig | undefined;
-  hooks: CMSHooks<T>;
-  logger: Logger | undefined;
-}
+declare function createClient<S extends CMSSources = CMSSources>(opts: CreateClientOptions<S>): CMSClient<MergeSourceCollections<S> extends CollectionsConfig ? MergeSourceCollections<S> : CollectionsConfig>;
 //#endregion
 //#region src/retry.d.ts
 interface RetryConfig {
@@ -425,69 +245,5 @@ declare const DEFAULT_RETRY_CONFIG: RetryConfig;
  */
 declare function withRetry<T>(fn: () => Promise<T>, config: RetryConfig): Promise<T>;
 //#endregion
-//#region src/collection.d.ts
-/**
- * コレクション別キャッシュキーを生成する。
- * item: `{collection}:{slug}` / list: `{collection}`
- *
- * (Cache adapter 内部のキー戦略はアダプタごとに異なるが、
- * 表示や再計算用に core 側でも公開ヘルパーを提供する)
- */
-declare function collectionKey(collection: string, slug?: string): string;
-/** 単一コレクションの DataSource + SWR キャッシュ依存を束ねたコンテキスト。 */
-interface CollectionContext<T extends BaseContentItem> {
-  collection: string;
-  source: DataSource<T>;
-  docCache: DocumentCacheOps;
-  docCacheName: string;
-  render: RenderContext<T>;
-  hooks: CMSHooks<T>;
-  logger: Logger | undefined;
-  ttlMs: number | undefined;
-  publishedStatuses: string[];
-  accessibleStatuses: string[];
-  retryConfig: RetryConfig;
-  maxConcurrent: number;
-  waitUntil: ((p: Promise<unknown>) => void) | undefined;
-  /**
-   * slug として使うフィールド名 (CLI 生成の `CollectionDef.slugField`)。
-   * `source.properties[slugField].notion` を Notion プロパティ名として
-   * `findByProp` を呼び出す。
-   */
-  slugField: string;
-}
-/** CollectionClient の実装。ユーザーは `createClient` 経由でインスタンスを受け取る。 */
-declare class CollectionClientImpl<T extends BaseContentItem> implements CollectionClient<T> {
-  private readonly ctx;
-  readonly cache: CollectionCacheOps<T>;
-  constructor(ctx: CollectionContext<T>);
-  find(slug: string, opts?: FindOptions): Promise<ItemWithContent<T> | null>;
-  list(opts?: ListOptions<T>): Promise<T[]>;
-  params(): Promise<string[]>;
-  check(slug: string, currentVersion: string): Promise<CheckResult<T> | null>;
-  adjacent(slug: string, opts?: AdjacencyOptions<T>): Promise<{
-    prev: T | null;
-    next: T | null;
-  }>;
-  private invalidateImpl;
-  private invalidateItemImpl;
-  private warmImpl;
-  private persistMeta;
-  private invalidateContentEntry;
-  /**
-   * 本文キャッシュをロードする。キャッシュが無いか、メタとの整合性が取れない場合は
-   * 再生成して書き戻す。
-   */
-  private loadOrBuildContent;
-  /** メタ既知の状態で本文だけバックグラウンド再生成する。エラーは onSwrError フックに通知する。 */
-  private rebuildContentBg;
-  private attachLazyContent;
-  private fetchList;
-  private checkAndUpdateItemBg;
-  private checkAndUpdateListBg;
-  private fetchListRaw;
-  private fetchRaw;
-}
-//#endregion
-export { type AdjacencyOptions, type BaseContentItem, type BuiltInCMSErrorCode, type CMSAdapter, type CMSClient, CMSError, type CMSErrorCode, type CMSErrorContext, type CMSGlobalOps, type CMSHooks, type CMSPlugin, type CMSSchemaProperties, type CMSSources, type CacheAdapter, type CachedItemContent, type CachedItemList, type CachedItemMeta, type CheckResult, type CollectionCacheOps, type CollectionClient, CollectionClientImpl, type CollectionContext, type CollectionDef, type CollectionsConfig, type ContentBlock, type ContentConfig, type ContentResult, type CreateClientOptions, DEFAULT_RETRY_CONFIG, type DataSource, type DocumentCacheOps, type FindOptions, type HandlerAdapter, type HandlerOptions, type ImageCacheOps, type ImageRef, type InferCollectionItem, type InlineNode, type InvalidateKind, type InvalidateScope, type ItemWithContent, type ListOptions, type LogLevel, type Logger, type MaybePromise, type MemoryCacheOptions, type MergeSourceCollections, type PropertyDef, type PropertyMap, type RateLimiterConfig, type RenderOptions, type RendererFn, type RendererPluginList, type RetryConfig, type SWRConfig, type SortOption, type StorageBinary, type WarmOptions, type WarmResult, type WebhookConfig, collectionKey, createClient, createHandler, definePlugin, isCMSError, isCMSErrorInNamespace, isStale, matchCMSError, memoryCache, mergeHooks, mergeLoggers, noopDocOps, noopImgOps, sha256Hex, withRetry };
+export { type AdjacencyOptions, type BaseContentItem, type BuiltInCMSErrorCode, type CMSClient, CMSError, type CMSErrorCode, type CMSErrorContext, type CMSGlobalOps, type CMSHooks, type CMSPlugin, type CMSSchemaProperties, type CMSSources, type CacheAdapter, type CachedItemContent, type CachedItemList, type CachedItemMeta, type CheckResult, type CollectionCacheOps, type CollectionClient, type ContentBlock, type ContentConfig, type ContentResult, type CreateClientOptions, DEFAULT_RETRY_CONFIG, type DataSource, type DocumentCacheOps, type FindOptions, type HandlerAdapter, type HandlerOptions, type ImageCacheOps, type ImageRef, type InlineNode, type InvalidateKind, type InvalidateScope, type ItemWithContent, type ListOptions, type LogLevel, type Logger, type MaybePromise, type MemoryCacheOptions, type NodePresetOptions, type PropertyDef, type PropertyMap, type RateLimiterConfig, type RenderOptions, type RendererFn, type RendererPluginList, type RetryConfig, type SWRConfig, type SortOption, type StorageBinary, type WarmOptions, type WarmResult, type WebhookConfig, createClient, createHandler, definePlugin, isCMSError, isCMSErrorInNamespace, isStale, matchCMSError, memoryCache, mergeHooks, mergeLoggers, nodePreset, noopDocOps, noopImgOps, sha256Hex, withRetry };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import { memoryCache } from "./cache/memory.mjs";
 import { CMSError, isCMSError, isCMSErrorInNamespace, matchCMSError } from "./errors.mjs";
 import { mergeHooks, mergeLoggers } from "./hooks.mjs";
+import { nodePreset } from "./preset/node.mjs";
 //#region src/cache.ts
 /** 文字列をSHA-256でハッシュ化し、16進数文字列として返す。画像キーの生成に使用。 */
 async function sha256Hex(input) {
@@ -159,16 +160,16 @@ function buildCacheImageFn(cache, cacheName, imageProxyBase, logger) {
 //#endregion
 //#region src/rendering.ts
 /**
-* `@notion-headless-cms/renderer` を動的 import してデフォルトレンダラーを返す。
+* `@notion-headless-cms/markdown-html` を動的 import してデフォルトレンダラーを返す。
 * core のゼロ依存ルールを守るため静的 import は禁止。
 */
 async function loadDefaultRenderer() {
 	try {
-		return (await import("@notion-headless-cms/renderer")).renderMarkdown;
+		return (await import("@notion-headless-cms/markdown-html")).renderMarkdown;
 	} catch {
 		throw new CMSError({
 			code: "core/config_invalid",
-			message: "renderer が未指定で、@notion-headless-cms/renderer のロードにも失敗しました。 createClient の renderer オプションを指定するか、@notion-headless-cms/renderer をインストールしてください。",
+			message: "renderer が未指定で、@notion-headless-cms/markdown-html のロードにも失敗しました。 createClient の renderer オプションを指定するか、@notion-headless-cms/markdown-html をインストールしてください。",
 			context: { operation: "loadDefaultRenderer" }
 		});
 	}
@@ -322,17 +323,6 @@ async function withRetry(fn, config) {
 }
 //#endregion
 //#region src/collection.ts
-/**
-* コレクション別キャッシュキーを生成する。
-* item: `{collection}:{slug}` / list: `{collection}`
-*
-* (Cache adapter 内部のキー戦略はアダプタごとに異なるが、
-* 表示や再計算用に core 側でも公開ヘルパーを提供する)
-*/
-function collectionKey(collection, slug) {
-	return slug ? `${collection}:${slug}` : collection;
-}
-/** CollectionClient の実装。ユーザーは `createClient` 経由でインスタンスを受け取る。 */
 var CollectionClientImpl = class {
 	cache;
 	constructor(ctx) {
@@ -492,21 +482,17 @@ var CollectionClientImpl = class {
 			kind: "content"
 		});
 	}
-	/**
-	* 本文キャッシュをロードする。キャッシュが無いか、メタとの整合性が取れない場合は
-	* 再生成して書き戻す。
-	*/
+	/** 本文キャッシュ。メタとの整合 (`notionUpdatedAt`) が崩れていれば再生成して書き戻す。 */
 	async loadOrBuildContent(slug, item) {
 		const expected = this.ctx.source.getLastModified(item);
 		const cached = await this.ctx.docCache.getContent(this.ctx.collection, slug);
-		const needsNotionBlocksBackfill = this.ctx.source.loadNotionBlocks !== void 0 && cached !== null && cached.notionBlocks === void 0;
-		if (cached && cached.notionUpdatedAt === expected && !needsNotionBlocksBackfill) return cached;
+		if (cached && cached.notionUpdatedAt === expected) return cached;
 		const fresh = await buildCachedItemContent(item, this.ctx.render);
 		await this.ctx.docCache.setContent(this.ctx.collection, slug, fresh);
 		this.ctx.hooks.onContentRevalidated?.(slug, fresh);
 		return fresh;
 	}
-	/** メタ既知の状態で本文だけバックグラウンド再生成する。エラーは onSwrError フックに通知する。 */
+	/** メタ既知の状態で本文だけ再生成する。エラーは onSwrError フックに通知して握り潰す。 */
 	async rebuildContentBg(slug, item) {
 		try {
 			const fresh = await buildCachedItemContent(item, this.ctx.render);
@@ -757,7 +743,7 @@ function applyListOptions(items, opts) {
 	if (skip > 0 || limit !== void 0) result = result.slice(skip, limit !== void 0 ? skip + limit : void 0);
 	return result;
 }
-/** publishedAt 降順、未設定の場合は lastEditedTime 降順でソートする。 */
+/** publishedAt 降順 (未設定なら lastEditedTime 降順) でソートする。 */
 function sortByPublishedAtDesc(items) {
 	return [...items].sort((a, b) => {
 		const av = a.publishedAt ?? a.lastEditedTime;
@@ -796,10 +782,7 @@ const DEFAULT_OPTS = {
 	imagesPath: "/images",
 	revalidatePath: "/revalidate"
 };
-/**
-* CMSError のコードから HTTP ステータスコードを返す。
-* 既知の webhook エラーコードのみ対応し、それ以外は null を返す。
-*/
+/** Webhook 系の CMSError コードを HTTP ステータスへ写像する。未対応コードは null。 */
 function webhookErrorStatus(code) {
 	if (code === "webhook/signature_invalid") return 401;
 	if (code === "webhook/not_implemented") return 501;
@@ -876,10 +859,7 @@ function trimTrailingSlash(s) {
 //#region src/cms.ts
 const DEFAULT_IMAGE_PROXY_BASE = "/api/images";
 /**
-* `cache` オプションから document / image オペレーションを解決する。
-*
-* - 各 adapter の `handles` を見て先勝ち (最初に見つかったもの) で振り分ける
-* - 未指定なら両方 noop
+* adapter の `handles` を見て先勝ちで document / image を割り当てる。未指定は両方 noop。
 */
 function resolveCache(cache) {
 	const adapters = cache ?? [];
@@ -915,7 +895,6 @@ const LOG_LEVEL_ORDER = {
 	warn: 2,
 	error: 3
 };
-/** `logger` から `minLevel` 未満のレベルを除いた新しい Logger を返す。 */
 function applyLogLevel(logger, minLevel) {
 	if (!logger) return void 0;
 	const minOrder = LOG_LEVEL_ORDER[minLevel];
@@ -929,36 +908,31 @@ function applyLogLevel(logger, minLevel) {
 	return filtered;
 }
 /**
-* 複数の `CollectionDef` を束ねた CMS クライアントを生成する。
-*
-* 通常はユーザーが直接呼ぶことはなく、CLI 生成の `nhc.ts` の `createClient`
-* (低レベルのこの関数をラップしたもの) を経由する。
+* CMS クライアントを生成する。
 *
 * @example
-* createClient({
-*   collections: {
-*     posts: {
-*       source: createNotionCollection({ token, dataSourceId, properties }),
-*       slugField: "slug",
-*       statusField: "status",
-*       publishedStatuses: ["公開済み"],
-*     }
-*   },
-*   cache: [memoryCache()],
-*   swr: { ttlMs: 5 * 60_000 },
+* 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(),
 * });
+*
+* const posts = await cms.posts.list();
 */
 function createClient(opts) {
-	let mergedFromSources;
+	const collectionsInput = {};
 	if (opts.sources) {
-		mergedFromSources = {};
-		for (const adapter of Object.values(opts.sources)) if (adapter) Object.assign(mergedFromSources, adapter.collections);
+		for (const adapter of Object.values(opts.sources)) if (adapter) Object.assign(collectionsInput, adapter.collections);
 	}
-	const collectionsInput = mergedFromSources ?? opts.collections;
-	if (!collectionsInput || Object.keys(collectionsInput).length === 0) throw new CMSError({
+	if (Object.keys(collectionsInput).length === 0) throw new CMSError({
 		code: "core/config_invalid",
-		message: "createClient: sources または collections に少なくとも 1 つのコレクションを指定してください。",
-		context: { operation: "createClient" }
+		message: "createClient: sources に少なくとも 1 つのコレクションを指定してください。",
+		context: { operation: "createClient" },
+		nextSteps: ["notionSource({ schema, token }) を sources.notion に渡す", "`nhc generate` でスキーマを生成してから import する"],
+		docsUrl: "https://github.com/kjfsm/notion-headless-cms/blob/main/docs/quickstart.md"
 	});
 	for (const [name, def] of Object.entries(collectionsInput)) {
 		if (!def.source) throw new CMSError({
@@ -967,7 +941,8 @@ function createClient(opts) {
 			context: {
 				operation: "createClient",
 				collection: name
-			}
+			},
+			nextSteps: ["notionSource(...) を sources に渡しているか確認する"]
 		});
 		if (!def.slugField) throw new CMSError({
 			code: "core/config_invalid",
@@ -975,7 +950,8 @@ function createClient(opts) {
 			context: {
 				operation: "createClient",
 				collection: name
-			}
+			},
+			nextSteps: [`nhc.config.ts の ${name} コレクションに slugField を設定する`]
 		});
 	}
 	const cacheRes = resolveCache(opts.cache);
@@ -1080,6 +1056,6 @@ function definePlugin(plugin) {
 	return plugin;
 }
 //#endregion
-export { CMSError, CollectionClientImpl, DEFAULT_RETRY_CONFIG, collectionKey, createClient, createHandler, definePlugin, isCMSError, isCMSErrorInNamespace, isStale, matchCMSError, memoryCache, mergeHooks, mergeLoggers, noopDocOps, noopImgOps, sha256Hex, withRetry };
+export { CMSError, DEFAULT_RETRY_CONFIG, createClient, createHandler, definePlugin, isCMSError, isCMSErrorInNamespace, isStale, matchCMSError, memoryCache, mergeHooks, mergeLoggers, nodePreset, noopDocOps, noopImgOps, sha256Hex, withRetry };
 
 //# sourceMappingURL=index.mjs.map