@notion-headless-cms/core 0.1.0 → 0.1.2

package/dist/chunk-V6ML4QE5.js

@@ -0,0 +1,26 @@
+// src/errors.ts
+var CMSError = class extends Error {
+  code;
+  cause;
+  context;
+  constructor(params) {
+    super(params.message, { cause: params.cause });
+    this.name = "CMSError";
+    this.code = params.code;
+    this.cause = params.cause;
+    this.context = params.context;
+  }
+};
+function isCMSError(error) {
+  return error instanceof CMSError;
+}
+function isCMSErrorInNamespace(error, namespace) {
+  return isCMSError(error) && error.code.startsWith(namespace);
+}
+
+export {
+  CMSError,
+  isCMSError,
+  isCMSErrorInNamespace
+};
+//# sourceMappingURL=chunk-V6ML4QE5.js.map

package/dist/chunk-V6ML4QE5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["type BuiltInCMSErrorCode =\n\t| \"core/config_invalid\"\n\t| \"core/schema_invalid\"\n\t| \"source/fetch_items_failed\"\n\t| \"source/fetch_item_failed\"\n\t| \"source/load_markdown_failed\"\n\t| \"cache/io_failed\"\n\t| \"cache/image_fetch_failed\"\n\t| \"renderer/failed\";\n\n/**\n * CMS エラーコード。\n * `BuiltInCMSErrorCode` のリテラル補完を維持しつつ、\n * サードパーティアダプタが独自コードを定義できるよう `string & {}` で拡張可能にする。\n */\nexport type CMSErrorCode = BuiltInCMSErrorCode | (string & {});\n\nexport interface CMSErrorContext {\n\toperation: string;\n\tslug?: string;\n\tdataSourceId?: string;\n\tpageId?: string;\n\t[key: string]: string | number | boolean | null | undefined;\n}\n\nexport class CMSError extends Error {\n\treadonly code: CMSErrorCode;\n\toverride readonly cause?: unknown;\n\treadonly context: CMSErrorContext;\n\n\tconstructor(params: {\n\t\tcode: CMSErrorCode;\n\t\tmessage: string;\n\t\tcause?: unknown;\n\t\tcontext: CMSErrorContext;\n\t}) {\n\t\tsuper(params.message, { cause: params.cause });\n\t\tthis.name = \"CMSError\";\n\t\tthis.code = params.code;\n\t\tthis.cause = params.cause;\n\t\tthis.context = params.context;\n\t}\n}\n\nexport function isCMSError(error: unknown): error is CMSError {\n\treturn error instanceof CMSError;\n}\n\n/** エラーコードが特定の名前空間に属するかを判定する（例: \"source/\"）。 */\nexport function isCMSErrorInNamespace(\n\terror: unknown,\n\tnamespace: string,\n): error is CMSError {\n\treturn isCMSError(error) && error.code.startsWith(namespace);\n}\n"],"mappings":";AAyBO,IAAM,WAAN,cAAuB,MAAM;AAAA,EAC1B;AAAA,EACS;AAAA,EACT;AAAA,EAET,YAAY,QAKT;AACF,UAAM,OAAO,SAAS,EAAE,OAAO,OAAO,MAAM,CAAC;AAC7C,SAAK,OAAO;AACZ,SAAK,OAAO,OAAO;AACnB,SAAK,QAAQ,OAAO;AACpB,SAAK,UAAU,OAAO;AAAA,EACvB;AACD;AAEO,SAAS,WAAW,OAAmC;AAC7D,SAAO,iBAAiB;AACzB;AAGO,SAAS,sBACf,OACA,WACoB;AACpB,SAAO,WAAW,KAAK,KAAK,MAAM,KAAK,WAAW,SAAS;AAC5D;","names":[]}

package/dist/content-Biqf0l_o.d.ts

@@ -0,0 +1,51 @@
+/**
+ * ライブラリが動作するために必須なフィールド。
+ * 利用者はこのインターフェースを拡張して独自のコンテンツ型を定義する。
+ *
+ * @example
+ * interface Post extends BaseContentItem {
+ *   title: string;
+ *   author: string;
+ * }
+ * createCMS<Post>({ source: notionAdapter({ ... }) })
+ */
+interface BaseContentItem {
+    /** Notion ページ ID（変更検知に必須）。 */
+    id: string;
+    /** URL キー（必須）。 */
+    slug: string;
+    /** 最終更新タイムスタンプ（変更検知に必須）。 */
+    updatedAt: string;
+    /** コンテンツのステータス。ステータスのない DB では省略可能。 */
+    status?: string;
+    /** 公開日時。日付プロパティのない DB では省略可能。 */
+    publishedAt?: string;
+}
+/** ストレージにキャッシュされたレンダリング済みコンテンツ。 */
+interface CachedItem<T extends BaseContentItem = BaseContentItem> {
+    html: string;
+    item: T;
+    notionUpdatedAt: string;
+    cachedAt: number;
+}
+/** ストレージにキャッシュされたコンテンツ一覧。 */
+interface CachedItemList<T extends BaseContentItem = BaseContentItem> {
+    items: T[];
+    cachedAt: number;
+}
+/** ストレージから取得したバイナリオブジェクト。 */
+interface StorageBinary {
+    data: ArrayBuffer;
+    contentType?: string;
+}
+/** Notionのプロパティ名マッピング（すべてオプション）。 */
+interface CMSSchemaProperties {
+    /** Notionのスラッグプロパティ名。デフォルト: 'Slug' */
+    slug?: string;
+    /** Notionのステータスプロパティ名。デフォルト: 'Status' */
+    status?: string;
+    /** Notionの公開日プロパティ名。デフォルト: 'CreatedAt' */
+    date?: string;
+}
+
+export type { BaseContentItem as B, CMSSchemaProperties as C, StorageBinary as S, CachedItem as a, CachedItemList as b };

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+type BuiltInCMSErrorCode = "core/config_invalid" | "core/schema_invalid" | "source/fetch_items_failed" | "source/fetch_item_failed" | "source/load_markdown_failed" | "cache/io_failed" | "cache/image_fetch_failed" | "renderer/failed";
+/**
+ * CMS エラーコード。
+ * `BuiltInCMSErrorCode` のリテラル補完を維持しつつ、
+ * サードパーティアダプタが独自コードを定義できるよう `string & {}` で拡張可能にする。
+ */
+type CMSErrorCode = BuiltInCMSErrorCode | (string & {});
+interface CMSErrorContext {
+    operation: string;
+    slug?: string;
+    dataSourceId?: string;
+    pageId?: string;
+    [key: string]: string | number | boolean | null | undefined;
+}
+declare class CMSError extends Error {
+    readonly code: CMSErrorCode;
+    readonly cause?: unknown;
+    readonly context: CMSErrorContext;
+    constructor(params: {
+        code: CMSErrorCode;
+        message: string;
+        cause?: unknown;
+        context: CMSErrorContext;
+    });
+}
+declare function isCMSError(error: unknown): error is CMSError;
+/** エラーコードが特定の名前空間に属するかを判定する（例: "source/"）。 */
+declare function isCMSErrorInNamespace(error: unknown, namespace: string): error is CMSError;
+
+export { CMSError, type CMSErrorCode, type CMSErrorContext, isCMSError, isCMSErrorInNamespace };

package/dist/errors.js

@@ -0,0 +1,11 @@
+import {
+  CMSError,
+  isCMSError,
+  isCMSErrorInNamespace
+} from "./chunk-V6ML4QE5.js";
+export {
+  CMSError,
+  isCMSError,
+  isCMSErrorInNamespace
+};
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/hooks-B83RUclt.d.ts

@@ -0,0 +1,41 @@
+import { B as BaseContentItem, a as CachedItem } from './content-Biqf0l_o.js';
+
+type MaybePromise<T> = T | Promise<T>;
+interface CMSHooks<T extends BaseContentItem = BaseContentItem> {
+    beforeCache?: (item: CachedItem<T>) => MaybePromise<CachedItem<T>>;
+    afterRender?: (html: string, item: T) => MaybePromise<string>;
+    onCacheHit?: (slug: string, item: CachedItem<T>) => void;
+    onCacheMiss?: (slug: string) => void;
+    onListCacheHit?: (items: T[], cachedAt: number) => void;
+    onListCacheMiss?: () => void;
+    onError?: (error: Error) => void;
+    onRenderStart?: (slug: string) => void;
+    onRenderEnd?: (slug: string, durationMs: number) => void;
+}
+
+interface Logger {
+    debug?: (message: string, context?: Record<string, unknown>) => void;
+    info?: (message: string, context?: Record<string, unknown>) => void;
+    warn?: (message: string, context?: Record<string, unknown>) => void;
+    error?: (message: string, context?: Record<string, unknown>) => void;
+}
+
+interface CMSPlugin<T extends BaseContentItem = BaseContentItem> {
+    name: string;
+    hooks?: CMSHooks<T>;
+    logger?: Partial<Logger>;
+}
+declare function definePlugin<T extends BaseContentItem>(plugin: CMSPlugin<T>): CMSPlugin<T>;
+
+/**
+ * プラグイン配列とダイレクトフックを合成して単一の CMSHooks を返す。
+ * beforeCache / afterRender はパイプライン（前の出力が次の入力）。
+ * onCacheHit などオブザーバー系は全員に同じ値を渡し、例外は 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;
+
+export { type CMSHooks as C, type Logger as L, type MaybePromise as M, type CMSPlugin as a, mergeLoggers as b, definePlugin as d, mergeHooks as m };

package/dist/hooks.d.ts

@@ -0,0 +1,2 @@
+import './content-Biqf0l_o.js';
+export { m as mergeHooks, b as mergeLoggers } from './hooks-B83RUclt.js';

package/dist/hooks.js

@@ -0,0 +1,9 @@
+import {
+  mergeHooks,
+  mergeLoggers
+} from "./chunk-4KGKWKKI.js";
+export {
+  mergeHooks,
+  mergeLoggers
+};
+//# sourceMappingURL=hooks.js.map

package/dist/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index.d.ts

@@ -1,7 +1,13 @@
-import { RendererFn } from '@notion-headless-cms/renderer';
-import { BlockHandler } from '@notion-headless-cms/transformer';
-import { PageObjectResponse, RichTextItemResponse } from '@notionhq/client/build/src/api-endpoints';
-import { PluggableList } from 'unified';
+export { MemoryDocumentCacheOptions, MemoryImageCacheOptions, memoryCache, memoryDocumentCache, memoryImageCache } from './cache/memory.js';
+export { noopDocumentCache, noopImageCache } from './cache/noop.js';
+import { B as BaseContentItem, C as CMSSchemaProperties, a as CachedItem, S as StorageBinary } from './content-Biqf0l_o.js';
+export { b as CachedItemList } from './content-Biqf0l_o.js';
+import { PluggableList } from '@notion-headless-cms/renderer';
+import { C as CacheConfig } from './cache-DvbyemBK.js';
+export { D as DocumentCacheAdapter, I as ImageCacheAdapter } from './cache-DvbyemBK.js';
+import { C as CMSHooks, a as CMSPlugin, L as Logger } from './hooks-B83RUclt.js';
+export { M as MaybePromise, d as definePlugin, m as mergeHooks, b as mergeLoggers } from './hooks-B83RUclt.js';
+export { CMSError, CMSErrorCode, CMSErrorContext, isCMSError, isCMSErrorInNamespace } from './errors.js';
 
 /** 文字列をSHA-256でハッシュ化し、16進数文字列として返す。画像キーの生成に使用。 */
 declare function sha256Hex(input: string): Promise<string>;
@@ -11,78 +17,26 @@ declare function sha256Hex(input: string): Promise<string>;
  */
 declare function isStale(cachedAt: number, ttlMs?: number): boolean;
 
-/**
- * ライブラリが動作するために必須なフィールド。
- * 利用者はこのインターフェースを拡張して独自のコンテンツ型を定義する。
- *
- * @example
- * interface Post extends BaseContentItem {
- *   title: string;
- *   author: string;
- * }
- * createCMS<Post>({ source: notionAdapter({ ... }) })
- */
-interface BaseContentItem {
-    id: string;
-    slug: string;
-    status: string;
-    publishedAt: string;
-    updatedAt: string;
+/** ソース側クエリのフィルタ・ソート条件。 */
+interface SourceQueryOptions {
+    filter?: {
+        statuses?: string[];
+        tags?: string[];
+        [key: string]: unknown;
+    };
+    sort?: {
+        property: string;
+        direction: "asc" | "desc";
+    }[];
+    pageSize?: number;
+    cursor?: string;
 }
-/** ストレージにキャッシュされたレンダリング済みコンテンツ。 */
-interface CachedItem<T extends BaseContentItem = BaseContentItem> {
-    html: string;
-    item: T;
-    notionUpdatedAt: string;
-    cachedAt: number;
-}
-/** ストレージにキャッシュされたコンテンツ一覧。 */
-interface CachedItemList<T extends BaseContentItem = BaseContentItem> {
+/** ソース側クエリの結果。 */
+interface SourceQueryResult<T> {
     items: T[];
-    cachedAt: number;
-}
-/** ストレージから取得したバイナリオブジェクト。 */
-interface StorageBinary {
-    data: ArrayBuffer;
-    contentType?: string;
-}
-/** Notionのプロパティ名マッピング（すべてオプション）。 */
-interface CMSSchemaProperties {
-    /** Notionのスラッグプロパティ名。デフォルト: 'Slug' */
-    slug?: string;
-    /** Notionのステータスプロパティ名。デフォルト: 'Status' */
-    status?: string;
-    /** Notionの公開日プロパティ名。デフォルト: 'CreatedAt' */
-    date?: string;
-}
-
-/** ドキュメントキャッシュを抽象化するインターフェース。 */
-interface DocumentCacheAdapter<T extends BaseContentItem = BaseContentItem> {
-    readonly name: string;
-    getList(): Promise<CachedItemList<T> | null>;
-    setList(data: CachedItemList<T>): Promise<void>;
-    getItem(slug: string): Promise<CachedItem<T> | null>;
-    setItem(slug: string, data: CachedItem<T>): Promise<void>;
-    invalidate?(scope: "all" | {
-        slug: string;
-    } | {
-        tag: string;
-    }): Promise<void>;
-}
-/** 画像キャッシュを抽象化するインターフェース。 */
-interface ImageCacheAdapter {
-    readonly name: string;
-    get(hash: string): Promise<StorageBinary | null>;
-    set(hash: string, data: ArrayBuffer, contentType: string): Promise<void>;
-}
-/** キャッシュ設定オブジェクト。document / image それぞれ独立したアダプタを差し込める。 */
-interface CacheConfig<T extends BaseContentItem = BaseContentItem> {
-    document?: DocumentCacheAdapter<T> | false;
-    image?: ImageCacheAdapter | false;
-    /** キャッシュの有効期間（ミリ秒）。未設定の場合はTTLなし。 */
-    ttlMs?: number;
+    hasMore: boolean;
+    nextCursor?: string;
 }
-
 /**
  * コンテンツソース（Notion など）を抽象化するインターフェース。
  * core は Notion の知識を持たず、DataSourceAdapter 経由でのみデータを取得する。
@@ -96,21 +50,30 @@ interface DataSourceAdapter<T extends BaseContentItem = BaseContentItem> {
     }): Promise<T[]>;
     findBySlug(slug: string): Promise<T | null>;
     loadMarkdown(item: T): Promise<string>;
+    /** Notion 側でフィルタ・ソートを行うクエリ（オプション）。 */
+    query?(opts: SourceQueryOptions): Promise<SourceQueryResult<T>>;
 }
 
+/**
+ * render() オプション。core は renderer の実装を知らず、この型だけを扱う。
+ * @notion-headless-cms/renderer の renderMarkdown() はこのシグネチャと構造的に互換。
+ */
+interface RenderOptions {
+    imageProxyBase?: string;
+    cacheImage?: (url: string) => Promise<string>;
+    remarkPlugins?: PluggableList;
+    rehypePlugins?: PluggableList;
+}
+/** カスタムレンダラー関数の型。デフォルトは @notion-headless-cms/renderer の renderMarkdown。 */
+type RendererFn = (markdown: string, opts?: RenderOptions) => Promise<string>;
 /** スキーマ設定。公開ステータスのフィルタやプロパティ名マッピングを制御する。 */
 interface SchemaConfig<T extends BaseContentItem = BaseContentItem> {
-    /**
-     * Notionページをコンテンツ型 T にマッピングするカスタム関数。
-     * 指定した場合 properties の設定は無視される（slug プロパティ名のみ例外）。
-     */
-    mapItem?: (page: PageObjectResponse) => T;
-    /** mapItem 未使用時のプロパティ名マッピング。 */
-    properties?: CMSSchemaProperties;
     /** list() で返す「公開済み」ステータス値の配列。デフォルト: [] （全件返す） */
     publishedStatuses?: string[];
     /** findBySlug() でアクセス可能なステータス値の配列。デフォルト: [] （全件許可） */
     accessibleStatuses?: string[];
+    /** mapItem 未使用時のプロパティ名マッピング。source-notion 経由で渡す場合は不要。 */
+    properties?: CMSSchemaProperties;
 }
 /** レンダリング・コンテンツ処理設定。 */
 interface ContentConfig {
@@ -120,10 +83,17 @@ interface ContentConfig {
     remarkPlugins?: PluggableList;
     /** 追加する rehype プラグイン。 */
     rehypePlugins?: PluggableList;
-    /** デフォルトのパイプラインを置き換えるカスタムレンダラー。 */
-    render?: RendererFn;
-    /** カスタムブロックハンドラーのマップ。Notionブロックタイプをキーとする。 */
-    blocks?: Record<string, BlockHandler>;
+}
+/** レートリミット・リトライ設定。 */
+interface RateLimiterConfig {
+    /** 同時実行数の上限。デフォルト: 3 */
+    maxConcurrent?: number;
+    /** リトライ対象の HTTP ステータスコード。デフォルト: [429, 502, 503] */
+    retryOn?: number[];
+    /** 最大リトライ回数。デフォルト: 4 */
+    maxRetries?: number;
+    /** リトライ時の基準待機時間（ミリ秒）。デフォルト: 1000 */
+    baseDelayMs?: number;
 }
 /**
  * createCMS() に渡すオプション。
@@ -132,6 +102,8 @@ interface ContentConfig {
 interface CreateCMSOptions<T extends BaseContentItem = BaseContentItem> {
     /** データソースアダプタ（Notion など）。 */
     source: DataSourceAdapter<T>;
+    /** レンダラー関数。未指定時は @notion-headless-cms/renderer の renderMarkdown を使用。 */
+    renderer?: RendererFn;
     /** キャッシュ設定。未設定時はキャッシュなし。 */
     cache?: CacheConfig<T>;
     /** スキーマ・ステータス設定。 */
@@ -140,75 +112,64 @@ interface CreateCMSOptions<T extends BaseContentItem = BaseContentItem> {
     content?: ContentConfig;
     /** Cloudflare Workers の waitUntil に相当する非同期処理の登録関数。 */
     waitUntil?: (p: Promise<unknown>) => void;
+    /** ライフサイクルフック。 */
+    hooks?: CMSHooks<T>;
+    /** プラグイン配列。フックとロガーを組み合わせて提供できる。 */
+    plugins?: CMSPlugin<T>[];
+    /** ロガー。 */
+    logger?: Logger;
+    /** レートリミット・リトライ設定。 */
+    rateLimiter?: RateLimiterConfig;
 }
 
-/** インメモリキャッシュ（ドキュメント用）を生成する。 */
-declare function memoryDocumentCache<T extends BaseContentItem = BaseContentItem>(): DocumentCacheAdapter<T>;
-/** インメモリキャッシュ（画像用）を生成する。 */
-declare function memoryImageCache(): ImageCacheAdapter;
-/**
- * ドキュメントと画像の両方にインメモリキャッシュを返す便利関数。
- * memoryCache() はドキュメントキャッシュを返す（後方互換）。
- */
-declare function memoryCache<T extends BaseContentItem = BaseContentItem>(): DocumentCacheAdapter<T>;
-
-/** 何もしないドキュメントキャッシュを返す（シングルトン）。 */
-declare function noopDocumentCache<T extends BaseContentItem = BaseContentItem>(): DocumentCacheAdapter<T>;
-/** 何もしない画像キャッシュを返す（シングルトン）。 */
-declare function noopImageCache(): ImageCacheAdapter;
-
-/**
- * Notion をバックエンドとして使う汎用ヘッドレス CMS クラス。
- *
- * @example
- * const cms = createCMS({
- *   source: notionAdapter({ token: '...', dataSourceId: '...' }),
- *   schema: { publishedStatuses: ['公開'] },
- * });
- * const items = await cms.list();
- */
-declare class CMS<T extends BaseContentItem = BaseContentItem> {
+interface QueryResult<T> {
+    items: T[];
+    total: number;
+    page: number;
+    perPage: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+declare class QueryBuilder<T extends BaseContentItem> {
     private readonly source;
-    private readonly docCache;
-    private readonly imgCache;
-    private readonly hasImageCache;
-    private readonly ttlMs;
-    private readonly publishedStatuses;
-    private readonly accessibleStatuses;
-    private readonly imageProxyBase;
-    private readonly contentConfig;
-    private readonly waitUntil;
-    constructor(opts: CreateCMSOptions<T>);
-    /** 公開済みコンテンツ一覧をソースから直接取得する。 */
-    list(): Promise<T[]>;
-    /** スラッグでコンテンツをソースから直接取得する。 */
-    findBySlug(slug: string): Promise<T | null>;
-    /** アイテムが publishedStatuses に含まれるステータスかどうかを返す。 */
-    isPublished(item: T): boolean;
-    /** コンテンツを Markdown → HTML にレンダリングし、CachedItem として返す。 */
-    render(item: T): Promise<CachedItem<T>>;
-    /** スラッグでコンテンツを取得して Markdown → HTML にレンダリングする。 */
-    renderBySlug(slug: string): Promise<CachedItem<T> | null>;
-    /** ステータスでフィルタリングした一覧を返す。 */
-    listByStatus(status: string | readonly string[]): Promise<T[]>;
-    /** 任意の条件でフィルタリングした一覧を返す。 */
-    where(predicate: (item: T) => boolean): Promise<T[]>;
-    /** ページネーション付き一覧を返す。 */
+    private readonly defaultStatuses;
+    private _statuses;
+    private _tags;
+    private _predicate;
+    private _sortField;
+    private _sortDir;
+    private _page;
+    private _perPage;
+    constructor(source: DataSourceAdapter<T>, defaultStatuses?: string[]);
+    status(s: string | string[]): this;
+    tag(t: string | string[]): this;
+    where(predicate: (item: T) => boolean): this;
+    sortBy(field: keyof T & string, dir?: "asc" | "desc"): this;
     paginate(opts: {
         page: number;
         perPage: number;
-    }): Promise<{
-        items: T[];
-        total: number;
-        page: number;
-        perPage: number;
-        hasNext: boolean;
-    }>;
-    /** 指定スラッグの前後コンテンツを返す。 */
-    getAdjacent(slug: string): Promise<{
+    }): this;
+    execute(): Promise<QueryResult<T>>;
+    executeOne(): Promise<T | null>;
+    /** 前後アイテムを返す。sortBy() で指定したソート順を適用する。 */
+    adjacent(slug: string): Promise<{
         prev: T | null;
         next: T | null;
     }>;
+    /** 最初の 1 件を返す。`.paginate({ page: 1, perPage: 1 }).executeOne()` の短縮形。 */
+    first(): Promise<T | null>;
+}
+
+/** キャッシュ系の公開名前空間。SWR 読み取りとキャッシュ管理を統合する。 */
+interface CacheAccessor<T extends BaseContentItem> {
+    /** キャッシュ優先でコンテンツ一覧を返す（SWR）。 */
+    getList(): Promise<{
+        items: T[];
+        isStale: boolean;
+        cachedAt: number;
+    }>;
+    /** キャッシュ優先で単一コンテンツを返す（SWR）。HTML 付きの CachedItem を返す。 */
+    get(slug: string): Promise<CachedItem<T> | null>;
     /** 全コンテンツを事前レンダリングしてキャッシュに保存する。 */
     prefetchAll(opts?: {
         concurrency?: number;
@@ -217,32 +178,25 @@ declare class CMS<T extends BaseContentItem = BaseContentItem> {
         ok: number;
         failed: number;
     }>;
-    /** 静的生成用のスラッグ一覧を返す。 */
-    getStaticSlugs(): Promise<string[]>;
     /** 指定スコープのキャッシュを無効化する。 */
     revalidate(scope?: "all" | {
         slug: string;
     }): Promise<void>;
     /** Webhook ペイロードを元にキャッシュを同期する。 */
-    syncFromWebhook(payload?: {
+    sync(payload?: {
         slug?: string;
     }): Promise<{
         updated: string[];
     }>;
-    /** キャッシュ優先でコンテンツ一覧を返す（SWR）。 */
-    getList(): Promise<{
-        items: T[];
-        listVersion: string;
-    }>;
-    /** キャッシュ優先で単一コンテンツを返す（SWR）。 */
-    getItem(slug: string): Promise<CachedItem<T> | null>;
-    checkListUpdate(version: string): Promise<{
+    /** リスト全体の変更を検知する。version はリスト取得時の buildListVersion の値。 */
+    checkList(version: string): Promise<{
         changed: false;
     } | {
         changed: true;
         items: T[];
     }>;
-    checkItemUpdate(slug: string, lastEdited: string): Promise<{
+    /** 単一アイテムの変更を検知し、変更があれば再レンダリングしてキャッシュを更新する。 */
+    checkItem(slug: string, lastEdited: string): Promise<{
         changed: false;
     } | {
         changed: true;
@@ -250,43 +204,75 @@ declare class CMS<T extends BaseContentItem = BaseContentItem> {
         item: T;
         notionUpdatedAt: string;
     }>;
+}
+/**
+ * Notion をバックエンドとして使う汎用ヘッドレス CMS クラス。
+ *
+ * @example
+ * const cms = createCMS({
+ *   source: notionAdapter({ token: '...', dataSourceId: '...' }),
+ * });
+ * const items = await cms.list();
+ * const entry = await cms.cache.get('my-post');
+ */
+declare class CMS<T extends BaseContentItem = BaseContentItem> {
+    private readonly source;
+    private readonly docCache;
+    private readonly imgCache;
+    private readonly hasImageCache;
+    private readonly ttlMs;
+    private readonly publishedStatuses;
+    private readonly accessibleStatuses;
+    private readonly imageProxyBase;
+    private readonly contentConfig;
+    private readonly rendererFn;
+    private readonly waitUntil;
+    private readonly hooks;
+    private readonly logger;
+    private readonly retryConfig;
+    private readonly maxConcurrent;
+    readonly cache: CacheAccessor<T>;
+    constructor(opts: CreateCMSOptions<T>);
+    /** 公開済みコンテンツ一覧をソースから直接取得する。 */
+    list(): Promise<T[]>;
+    /** スラッグでコンテンツをソースから直接取得する。 */
+    find(slug: string): Promise<T | null>;
+    /** 複数スラッグをまとめてソースから直接取得する。accessibleStatuses フィルタを適用する。 */
+    findMany(slugs: string[]): Promise<Map<string, T>>;
+    /** アイテムが publishedStatuses に含まれるステータスかどうかを返す。 */
+    isPublished(item: T): boolean;
+    /** コンテンツを Markdown → HTML にレンダリングし、CachedItem として返す。キャッシュには保存しない。 */
+    render(item: T): Promise<CachedItem<T>>;
+    /** QueryBuilder を返す。ステータス・タグ・ページネーションなどを連鎖で指定できる。 */
+    query(): QueryBuilder<T>;
+    /** 静的生成用のスラッグ一覧を返す。 */
+    getStaticSlugs(): Promise<string[]>;
     /** ハッシュキーでキャッシュ画像を取得する。 */
     getCachedImage(hash: string): Promise<StorageBinary | null>;
     /** ハッシュキーでキャッシュ画像を Response として返す。 */
     createCachedImageResponse(hash: string): Promise<Response | null>;
+    private cachedList;
+    private cachedGet;
+    private prefetchAll;
+    private revalidate;
+    private syncFromWebhook;
+    private checkListUpdate;
+    private checkItemUpdate;
     private buildCachedItem;
 }
 /** 設定済みの CMS インスタンスを生成するファクトリ関数。 */
 declare function createCMS<T extends BaseContentItem = BaseContentItem>(opts: CreateCMSOptions<T>): CMS<T>;
 
-type CMSErrorCode = "CONFIG_INVALID" | "NOTION_ITEM_SCHEMA_INVALID" | "NOTION_FETCH_ITEMS_FAILED" | "NOTION_FETCH_ITEM_BY_SLUG_FAILED" | "NOTION_GET_BLOCKS_FAILED" | "NOTION_MARKDOWN_FETCH_FAILED" | "IMAGE_CACHE_FAILED" | "RENDERER_FAILED";
-interface CMSErrorContext {
-    operation: string;
-    slug?: string;
-    dataSourceId?: string;
-    pageId?: string;
-    [key: string]: string | number | boolean | null | undefined;
-}
-declare class CMSError extends Error {
-    readonly code: CMSErrorCode;
-    readonly cause?: unknown;
-    readonly context: CMSErrorContext;
-    constructor(params: {
-        code: CMSErrorCode;
-        message: string;
-        cause?: unknown;
-        context: CMSErrorContext;
-    });
+interface RetryConfig {
+    retryOn: number[];
+    maxRetries: number;
+    baseDelayMs: number;
+    /** true のとき指数バックオフにランダムジッターを加える（Thundering Herd 対策）。デフォルト: true */
+    jitter?: boolean;
+    onRetry?: (attempt: number, status: number) => void;
 }
-declare function isCMSError(error: unknown): error is CMSError;
-
-/** Notionリッチテキスト配列をプレーンテキストに結合する。 */
-declare function getPlainText(items: RichTextItemResponse[] | undefined): string;
-/**
- * NotionのPageObjectResponseをデフォルトの BaseContentItem に変換する。
- * 独自の拡張型（title などを含む）が必要な場合は、本関数の戻り値に
- * 追加フィールドを足してカスタム mapItem を実装する。
- */
-declare function mapItem(page: PageObjectResponse, props: Required<CMSSchemaProperties>): BaseContentItem;
+declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/** 指数バックオフ（オプションでジッター付き）でリトライする。retryOn に含まれる HTTP エラーのみ対象。 */
+declare function withRetry<T>(fn: () => Promise<T>, config: RetryConfig): Promise<T>;
 
-export { type BaseContentItem, CMS, CMSError, type CMSErrorCode, type CMSErrorContext, type CMSSchemaProperties, type CacheConfig, type CachedItem, type CachedItemList, type ContentConfig, type CreateCMSOptions, type DataSourceAdapter, type DocumentCacheAdapter, type ImageCacheAdapter, type SchemaConfig, type StorageBinary, createCMS, getPlainText, isCMSError, isStale, mapItem, memoryCache, memoryDocumentCache, memoryImageCache, noopDocumentCache, noopImageCache, sha256Hex };
+export { BaseContentItem, CMS, CMSHooks, CMSPlugin, CMSSchemaProperties, type CacheAccessor, CacheConfig, CachedItem, type ContentConfig, type CreateCMSOptions, DEFAULT_RETRY_CONFIG, type DataSourceAdapter, Logger, QueryBuilder, type QueryResult, type RateLimiterConfig, type RenderOptions, type RendererFn, type RetryConfig, type SchemaConfig, type SourceQueryOptions, type SourceQueryResult, StorageBinary, createCMS, isStale, sha256Hex, withRetry };