@notion-headless-cms/core 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -83,6 +83,51 @@ interface CacheConfig<T extends BaseContentItem = BaseContentItem> {
     ttlMs?: number;
 }
 
+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;
+}
+
+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>;
+
+/** ソース側クエリのフィルタ・ソート条件。 */
+interface SourceQueryOptions {
+    filter?: {
+        statuses?: string[];
+        tags?: string[];
+        [key: string]: unknown;
+    };
+    sort?: {
+        property: string;
+        direction: "asc" | "desc";
+    }[];
+    pageSize?: number;
+    cursor?: string;
+}
+/** ソース側クエリの結果。 */
+interface SourceQueryResult<T> {
+    items: T[];
+    hasMore: boolean;
+    nextCursor?: string;
+}
 /**
  * コンテンツソース（Notion など）を抽象化するインターフェース。
  * core は Notion の知識を持たず、DataSourceAdapter 経由でのみデータを取得する。
@@ -96,6 +141,8 @@ 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>>;
 }
 
 /** スキーマ設定。公開ステータスのフィルタやプロパティ名マッピングを制御する。 */
@@ -125,6 +172,17 @@ interface ContentConfig {
     /** カスタムブロックハンドラーのマップ。Notionブロックタイプをキーとする。 */
     blocks?: Record<string, BlockHandler>;
 }
+/** レートリミット・リトライ設定。 */
+interface RateLimiterConfig {
+    /** 同時実行数の上限。デフォルト: 3 */
+    maxConcurrent?: number;
+    /** リトライ対象の HTTP ステータスコード。デフォルト: [429, 502, 503] */
+    retryOn?: number[];
+    /** 最大リトライ回数。デフォルト: 4 */
+    maxRetries?: number;
+    /** リトライ時の基準待機時間（ミリ秒）。デフォルト: 1000 */
+    baseDelayMs?: number;
+}
 /**
  * createCMS() に渡すオプション。
  * ジェネリクス型 T にカスタムコンテンツ型を指定できる（デフォルト: BaseContentItem）。
@@ -140,6 +198,14 @@ 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;
 }
 
 /** インメモリキャッシュ（ドキュメント用）を生成する。 */
@@ -157,13 +223,88 @@ declare function noopDocumentCache<T extends BaseContentItem = BaseContentItem>(
 /** 何もしない画像キャッシュを返す（シングルトン）。 */
 declare function noopImageCache(): ImageCacheAdapter;
 
+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 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;
+    }): this;
+    execute(): Promise<QueryResult<T>>;
+    executeOne(): Promise<T | null>;
+    adjacent(slug: string): Promise<{
+        prev: T | null;
+        next: T | null;
+    }>;
+}
+
+/** キャッシュ優先アクセサ。 */
+interface CachedAccessor<T extends BaseContentItem> {
+    list(): Promise<{
+        items: T[];
+        isStale: boolean;
+        cachedAt: number;
+    }>;
+    get(slug: string): Promise<CachedItem<T> | null>;
+}
+/** キャッシュ管理オペレーション。 */
+interface CacheManager<T extends BaseContentItem> {
+    prefetchAll(opts?: {
+        concurrency?: number;
+        onProgress?: (done: number, total: number) => void;
+    }): Promise<{
+        ok: number;
+        failed: number;
+    }>;
+    revalidate(scope?: "all" | {
+        slug: string;
+    }): Promise<void>;
+    sync(payload?: {
+        slug?: string;
+    }): Promise<{
+        updated: string[];
+    }>;
+    checkList(version: string): Promise<{
+        changed: false;
+    } | {
+        changed: true;
+        items: T[];
+    }>;
+    checkItem(slug: string, lastEdited: string): Promise<{
+        changed: false;
+    } | {
+        changed: true;
+        html: string;
+        item: T;
+        notionUpdatedAt: string;
+    }>;
+}
 /**
  * Notion をバックエンドとして使う汎用ヘッドレス CMS クラス。
  *
  * @example
  * const cms = createCMS({
  *   source: notionAdapter({ token: '...', dataSourceId: '...' }),
- *   schema: { publishedStatuses: ['公開'] },
  * });
  * const items = await cms.list();
  */
@@ -178,37 +319,24 @@ declare class CMS<T extends BaseContentItem = BaseContentItem> {
     private readonly imageProxyBase;
     private readonly contentConfig;
     private readonly waitUntil;
+    private readonly hooks;
+    private readonly logger;
+    private readonly retryConfig;
+    readonly cached: CachedAccessor<T>;
+    readonly cache: CacheManager<T>;
     constructor(opts: CreateCMSOptions<T>);
     /** 公開済みコンテンツ一覧をソースから直接取得する。 */
     list(): Promise<T[]>;
     /** スラッグでコンテンツをソースから直接取得する。 */
+    find(slug: string): Promise<T | null>;
+    /** @deprecated find() を使用してください。 */
     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[]>;
-    /** ページネーション付き一覧を返す。 */
-    paginate(opts: {
-        page: number;
-        perPage: number;
-    }): Promise<{
-        items: T[];
-        total: number;
-        page: number;
-        perPage: number;
-        hasNext: boolean;
-    }>;
-    /** 指定スラッグの前後コンテンツを返す。 */
-    getAdjacent(slug: string): Promise<{
-        prev: T | null;
-        next: T | null;
-    }>;
+    /** QueryBuilder を返す。ステータス・タグ・ページネーションなどを連鎖で指定できる。 */
+    query(): QueryBuilder<T>;
     /** 全コンテンツを事前レンダリングしてキャッシュに保存する。 */
     prefetchAll(opts?: {
         concurrency?: number;
@@ -230,12 +358,9 @@ declare class CMS<T extends BaseContentItem = BaseContentItem> {
         updated: string[];
     }>;
     /** キャッシュ優先でコンテンツ一覧を返す（SWR）。 */
-    getList(): Promise<{
-        items: T[];
-        listVersion: string;
-    }>;
+    private cachedList;
     /** キャッシュ優先で単一コンテンツを返す（SWR）。 */
-    getItem(slug: string): Promise<CachedItem<T> | null>;
+    private cachedGet;
     checkListUpdate(version: string): Promise<{
         changed: false;
     } | {
@@ -250,6 +375,41 @@ declare class CMS<T extends BaseContentItem = BaseContentItem> {
         item: T;
         notionUpdatedAt: string;
     }>;
+    /** @deprecated cached.list() を使用してください。 */
+    getList(): Promise<{
+        items: T[];
+        listVersion: string;
+    }>;
+    /** @deprecated cached.get() を使用してください。 */
+    getItem(slug: string): Promise<CachedItem<T> | null>;
+    /** @deprecated cache.prefetchAll() を使用してください。 */
+    prefetchAllLegacy(opts?: {
+        concurrency?: number;
+        onProgress?: (done: number, total: number) => void;
+    }): Promise<{
+        ok: number;
+        failed: number;
+    }>;
+    /** @deprecated query().status(s).execute() を使用してください。 */
+    listByStatus(status: string | readonly string[]): Promise<T[]>;
+    /** @deprecated query().where(pred).execute() を使用してください。 */
+    where(predicate: (item: T) => boolean): Promise<T[]>;
+    /** @deprecated query().paginate(opts).execute() を使用してください。 */
+    paginate(opts: {
+        page: number;
+        perPage: number;
+    }): Promise<{
+        items: T[];
+        total: number;
+        page: number;
+        perPage: number;
+        hasNext: boolean;
+    }>;
+    /** @deprecated query().adjacent(slug) を使用してください。 */
+    getAdjacent(slug: string): Promise<{
+        prev: T | null;
+        next: T | null;
+    }>;
     /** ハッシュキーでキャッシュ画像を取得する。 */
     getCachedImage(hash: string): Promise<StorageBinary | null>;
     /** ハッシュキーでキャッシュ画像を Response として返す。 */
@@ -280,6 +440,17 @@ declare class CMSError extends Error {
 }
 declare function isCMSError(error: unknown): error is CMSError;
 
+/**
+ * プラグイン配列とダイレクトフックを合成して単一の CMSHooks を返す。
+ * beforeCache / afterRender はパイプライン（前の出力が次の入力）。
+ * onCacheHit などオブザーバー系は全員に同じ値を渡す。
+ */
+declare function mergeHooks<T extends BaseContentItem>(plugins: CMSPlugin<T>[], directHooks?: CMSHooks<T>): CMSHooks<T>;
+/** プラグイン配列とダイレクトロガーを合成して単一の Logger を返す。 */
+declare function mergeLoggers(plugins: Array<{
+    logger?: Partial<Logger>;
+}>, directLogger?: Logger): Logger | undefined;
+
 /** Notionリッチテキスト配列をプレーンテキストに結合する。 */
 declare function getPlainText(items: RichTextItemResponse[] | undefined): string;
 /**
@@ -289,4 +460,15 @@ declare function getPlainText(items: RichTextItemResponse[] | undefined): string
  */
 declare function mapItem(page: PageObjectResponse, props: Required<CMSSchemaProperties>): BaseContentItem;
 
-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 };
+interface RetryConfig {
+    maxConcurrent: number;
+    retryOn: number[];
+    maxRetries: number;
+    baseDelayMs: number;
+    onRetry?: (attempt: number, status: number) => void;
+}
+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 CMSHooks, type CMSPlugin, type CMSSchemaProperties, type CacheConfig, type CachedItem, type CachedItemList, type ContentConfig, type CreateCMSOptions, DEFAULT_RETRY_CONFIG, type DataSourceAdapter, type DocumentCacheAdapter, type ImageCacheAdapter, type Logger, type MaybePromise, QueryBuilder, type QueryResult, type RateLimiterConfig, type RetryConfig, type SchemaConfig, type SourceQueryOptions, type SourceQueryResult, type StorageBinary, createCMS, definePlugin, getPlainText, isCMSError, isStale, mapItem, memoryCache, memoryDocumentCache, memoryImageCache, mergeHooks, mergeLoggers, noopDocumentCache, noopImageCache, sha256Hex, withRetry };

package/dist/index.js

@@ -115,6 +115,72 @@ function isCMSError(error) {
   return error instanceof CMSError;
 }
 
+// src/hooks.ts
+function mergeHooks(plugins, directHooks) {
+  const allHooks = [
+    ...plugins.map((p) => p.hooks ?? {}),
+    ...directHooks ? [directHooks] : []
+  ];
+  if (allHooks.length === 0) return {};
+  return {
+    beforeCache: buildPipeline(allHooks, "beforeCache"),
+    afterRender: buildRenderPipeline(allHooks),
+    onCacheHit: buildObserver(allHooks, "onCacheHit"),
+    onCacheMiss: buildObserver(allHooks, "onCacheMiss"),
+    onListCacheHit: buildObserver(allHooks, "onListCacheHit"),
+    onListCacheMiss: buildObserver(allHooks, "onListCacheMiss"),
+    onError: buildObserver(allHooks, "onError")
+  };
+}
+function buildPipeline(hooks, key) {
+  const fns = hooks.map((h) => h[key]).filter(Boolean);
+  if (fns.length === 0) return void 0;
+  return async (item) => {
+    let current = item;
+    for (const fn of fns) {
+      current = await fn(current);
+    }
+    return current;
+  };
+}
+function buildRenderPipeline(hooks) {
+  const fns = hooks.map((h) => h.afterRender).filter(Boolean);
+  if (fns.length === 0) return void 0;
+  return async (html, item) => {
+    let current = html;
+    for (const fn of fns) {
+      current = await fn(current, item);
+    }
+    return current;
+  };
+}
+function buildObserver(hooks, key) {
+  const fns = hooks.map((h) => h[key]).filter(Boolean);
+  if (fns.length === 0) return void 0;
+  return ((...args) => {
+    for (const fn of fns) {
+      fn(...args);
+    }
+  });
+}
+function mergeLoggers(plugins, directLogger) {
+  const loggers = [
+    ...plugins.map((p) => p.logger ?? {}),
+    ...directLogger ? [directLogger] : []
+  ];
+  if (loggers.length === 0) return void 0;
+  const merged = {};
+  for (const level of ["debug", "info", "warn", "error"]) {
+    const fns = loggers.map((l) => l[level]).filter(Boolean);
+    if (fns.length > 0) {
+      merged[level] = (message, context) => {
+        for (const fn of fns) fn(message, context);
+      };
+    }
+  }
+  return merged;
+}
+
 // src/image.ts
 function inferContentType(url, responseContentType) {
   if (responseContentType?.startsWith("image/")) {
@@ -155,11 +221,146 @@ function buildCacheImageFn(cache, imageProxyBase) {
   return (notionUrl) => fetchAndCacheImage(cache, notionUrl, imageProxyBase);
 }
 
+// src/query.ts
+var QueryBuilder = class {
+  source;
+  defaultStatuses;
+  _statuses = [];
+  _tags = [];
+  _predicate;
+  _sortField;
+  _sortDir = "asc";
+  _page = 1;
+  _perPage = 20;
+  constructor(source, defaultStatuses = []) {
+    this.source = source;
+    this.defaultStatuses = defaultStatuses;
+  }
+  status(s) {
+    this._statuses = Array.isArray(s) ? s : [s];
+    return this;
+  }
+  tag(t) {
+    this._tags = Array.isArray(t) ? t : [t];
+    return this;
+  }
+  where(predicate) {
+    this._predicate = predicate;
+    return this;
+  }
+  sortBy(field, dir = "asc") {
+    this._sortField = field;
+    this._sortDir = dir;
+    return this;
+  }
+  paginate(opts) {
+    this._page = opts.page;
+    this._perPage = opts.perPage;
+    return this;
+  }
+  async execute() {
+    const statuses = this._statuses.length > 0 ? this._statuses : this.defaultStatuses.length > 0 ? this.defaultStatuses : void 0;
+    if (this.source.query && !this._predicate) {
+      const result = await this.source.query({
+        filter: {
+          statuses,
+          tags: this._tags.length > 0 ? this._tags : void 0
+        },
+        sort: this._sortField ? [{ property: this._sortField, direction: this._sortDir }] : void 0,
+        pageSize: this._perPage
+      });
+      const items2 = result.items;
+      return {
+        items: items2,
+        total: items2.length,
+        page: this._page,
+        perPage: this._perPage,
+        hasNext: result.hasMore,
+        hasPrev: this._page > 1
+      };
+    }
+    let items = await this.source.list({
+      publishedStatuses: statuses
+    });
+    if (this._tags.length > 0) {
+      items = items.filter((item) => {
+        const itemTags = item.tags;
+        if (!Array.isArray(itemTags)) return false;
+        return this._tags.some((tag) => itemTags.includes(tag));
+      });
+    }
+    if (this._predicate) {
+      items = items.filter(this._predicate);
+    }
+    if (this._sortField) {
+      const field = this._sortField;
+      const dir = this._sortDir;
+      items = [...items].sort((a, b) => {
+        const av = a[field];
+        const bv = b[field];
+        const cmp = av < bv ? -1 : av > bv ? 1 : 0;
+        return dir === "asc" ? cmp : -cmp;
+      });
+    }
+    const total = items.length;
+    const start = (this._page - 1) * this._perPage;
+    const paged = items.slice(start, start + this._perPage);
+    return {
+      items: paged,
+      total,
+      page: this._page,
+      perPage: this._perPage,
+      hasNext: start + this._perPage < total,
+      hasPrev: this._page > 1
+    };
+  }
+  async executeOne() {
+    const result = await this.execute();
+    return result.items[0] ?? null;
+  }
+  async adjacent(slug) {
+    const statuses = this._statuses.length > 0 ? this._statuses : this.defaultStatuses.length > 0 ? this.defaultStatuses : void 0;
+    const items = await this.source.list({ publishedStatuses: statuses });
+    const idx = items.findIndex((item) => item.slug === slug);
+    if (idx === -1) return { prev: null, next: null };
+    return {
+      prev: idx > 0 ? items[idx - 1] : null,
+      next: idx < items.length - 1 ? items[idx + 1] : null
+    };
+  }
+};
+
+// src/retry.ts
+var DEFAULT_RETRY_CONFIG = {
+  maxConcurrent: 3,
+  retryOn: [429, 502, 503],
+  maxRetries: 4,
+  baseDelayMs: 1e3
+};
+async function withRetry(fn, config) {
+  let lastError;
+  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      const status = err.status;
+      if (status === void 0 || !config.retryOn.includes(status)) {
+        throw err;
+      }
+      lastError = err;
+      if (attempt < config.maxRetries) {
+        config.onRetry?.(attempt + 1, status);
+        await new Promise(
+          (resolve) => setTimeout(resolve, config.baseDelayMs * 2 ** attempt)
+        );
+      }
+    }
+  }
+  throw lastError;
+}
+
 // src/cms.ts
 var DEFAULT_IMAGE_PROXY_BASE = "/api/images";
-function buildListVersion(items) {
-  return items.map((item) => `${item.id}:${item.updatedAt}`).join("|");
-}
 function resolveDocumentCache(cache) {
   if (!cache || cache.document === false || cache.document === void 0) {
     return noopDocumentCache();
@@ -183,6 +384,11 @@ var CMS = class {
   imageProxyBase;
   contentConfig;
   waitUntil;
+  hooks;
+  logger;
+  retryConfig;
+  cached;
+  cache;
   constructor(opts) {
     this.source = opts.source;
     this.docCache = resolveDocumentCache(opts.cache);
@@ -194,23 +400,57 @@ var CMS = class {
     this.imageProxyBase = opts.content?.imageProxyBase ?? DEFAULT_IMAGE_PROXY_BASE;
     this.contentConfig = opts.content;
     this.waitUntil = opts.waitUntil;
+    this.hooks = mergeHooks(opts.plugins ?? [], opts.hooks);
+    this.logger = mergeLoggers(opts.plugins ?? [], opts.logger);
+    this.retryConfig = {
+      ...DEFAULT_RETRY_CONFIG,
+      ...opts.rateLimiter
+    };
+    this.cached = {
+      list: this.cachedList.bind(this),
+      get: this.cachedGet.bind(this)
+    };
+    this.cache = {
+      prefetchAll: this.prefetchAll.bind(this),
+      revalidate: this.revalidate.bind(this),
+      sync: this.syncFromWebhook.bind(this),
+      checkList: this.checkListUpdate.bind(this),
+      checkItem: this.checkItemUpdate.bind(this)
+    };
   }
   // ── コンテンツ取得 ──────────────────────────────────────────────────────
   /** 公開済みコンテンツ一覧をソースから直接取得する。 */
   list() {
-    return this.source.list({
-      publishedStatuses: this.publishedStatuses.length > 0 ? this.publishedStatuses : void 0
-    });
+    return withRetry(
+      () => this.source.list({
+        publishedStatuses: this.publishedStatuses.length > 0 ? this.publishedStatuses : void 0
+      }),
+      {
+        ...this.retryConfig,
+        onRetry: (attempt, status) => {
+          this.logger?.warn?.("list() \u30EA\u30C8\u30E9\u30A4\u4E2D", { attempt, status });
+        }
+      }
+    );
   }
   /** スラッグでコンテンツをソースから直接取得する。 */
-  async findBySlug(slug) {
-    const item = await this.source.findBySlug(slug);
+  async find(slug) {
+    const item = await withRetry(() => this.source.findBySlug(slug), {
+      ...this.retryConfig,
+      onRetry: (attempt, status) => {
+        this.logger?.warn?.("find() \u30EA\u30C8\u30E9\u30A4\u4E2D", { attempt, status, slug });
+      }
+    });
     if (!item) return null;
     if (this.accessibleStatuses.length > 0 && !this.accessibleStatuses.includes(item.status)) {
       return null;
     }
     return item;
   }
+  /** @deprecated find() を使用してください。 */
+  findBySlug(slug) {
+    return this.find(slug);
+  }
   /** アイテムが publishedStatuses に含まれるステータスかどうかを返す。 */
   isPublished(item) {
     if (this.publishedStatuses.length === 0) return true;
@@ -220,57 +460,9 @@ var CMS = class {
   async render(item) {
     return this.buildCachedItem(item);
   }
-  /** スラッグでコンテンツを取得して Markdown → HTML にレンダリングする。 */
-  async renderBySlug(slug) {
-    try {
-      const item = await this.findBySlug(slug);
-      if (!item) return null;
-      return this.buildCachedItem(item);
-    } catch (err) {
-      if (isCMSError(err)) throw err;
-      throw new CMSError({
-        code: "NOTION_FETCH_ITEM_BY_SLUG_FAILED",
-        message: "Failed to fetch item by slug from Notion data source.",
-        cause: err,
-        context: { operation: "renderBySlug", slug }
-      });
-    }
-  }
-  // ── 便利 API ───────────────────────────────────────────────────────────
-  /** ステータスでフィルタリングした一覧を返す。 */
-  async listByStatus(status) {
-    const statuses = Array.isArray(status) ? status : [status];
-    const all = await this.source.list();
-    return all.filter((item) => statuses.includes(item.status));
-  }
-  /** 任意の条件でフィルタリングした一覧を返す。 */
-  async where(predicate) {
-    const items = await this.list();
-    return items.filter(predicate);
-  }
-  /** ページネーション付き一覧を返す。 */
-  async paginate(opts) {
-    const all = await this.list();
-    const total = all.length;
-    const start = (opts.page - 1) * opts.perPage;
-    const items = all.slice(start, start + opts.perPage);
-    return {
-      items,
-      total,
-      page: opts.page,
-      perPage: opts.perPage,
-      hasNext: start + opts.perPage < total
-    };
-  }
-  /** 指定スラッグの前後コンテンツを返す。 */
-  async getAdjacent(slug) {
-    const items = await this.list();
-    const idx = items.findIndex((item) => item.slug === slug);
-    if (idx === -1) return { prev: null, next: null };
-    return {
-      prev: idx > 0 ? items[idx - 1] : null,
-      next: idx < items.length - 1 ? items[idx + 1] : null
-    };
+  /** QueryBuilder を返す。ステータス・タグ・ページネーションなどを連鎖で指定できる。 */
+  query() {
+    return new QueryBuilder(this.source, this.publishedStatuses);
   }
   /** 全コンテンツを事前レンダリングしてキャッシュに保存する。 */
   async prefetchAll(opts) {
@@ -310,7 +502,7 @@ var CMS = class {
   async syncFromWebhook(payload) {
     const updated = [];
     if (payload?.slug) {
-      const item = await this.findBySlug(payload.slug);
+      const item = await this.find(payload.slug);
       if (item) {
         const rendered = await this.buildCachedItem(item);
         await this.docCache.setItem(item.slug, rendered);
@@ -325,31 +517,36 @@ var CMS = class {
     }
     return { updated };
   }
-  // ── キャッシュ優先取得（Stale-While-Revalidate） ─────────────────────
+  // ── キャッシュ優先取得（Stale-While-Revalidate） ──────────────────────
   /** キャッシュ優先でコンテンツ一覧を返す（SWR）。 */
-  async getList() {
+  async cachedList() {
     const cached = await this.docCache.getList();
     if (cached && !isStale(cached.cachedAt, this.ttlMs)) {
-      return {
-        items: cached.items,
-        listVersion: buildListVersion(cached.items)
-      };
+      this.hooks.onListCacheHit?.(cached.items, cached.cachedAt);
+      return { items: cached.items, isStale: false, cachedAt: cached.cachedAt };
     }
+    this.hooks.onListCacheMiss?.();
     const items = await this.list();
-    const save = this.docCache.setList({ items, cachedAt: Date.now() });
+    const cachedAt = Date.now();
+    const save = this.docCache.setList({ items, cachedAt });
     if (this.waitUntil) {
       this.waitUntil(save);
     } else {
       await save;
     }
-    return { items, listVersion: buildListVersion(items) };
+    return { items, isStale: !!cached, cachedAt };
   }
   /** キャッシュ優先で単一コンテンツを返す（SWR）。 */
-  async getItem(slug) {
+  async cachedGet(slug) {
     const cached = await this.docCache.getItem(slug);
-    if (cached && !isStale(cached.cachedAt, this.ttlMs)) return cached;
-    const entry = await this.renderBySlug(slug);
-    if (!entry) return null;
+    if (cached && !isStale(cached.cachedAt, this.ttlMs)) {
+      this.hooks.onCacheHit?.(slug, cached);
+      return cached;
+    }
+    this.hooks.onCacheMiss?.(slug);
+    const item = await this.find(slug);
+    if (!item) return null;
+    const entry = await this.buildCachedItem(item);
     const save = this.docCache.setItem(slug, entry);
     if (this.waitUntil) {
       this.waitUntil(save);
@@ -366,12 +563,11 @@ var CMS = class {
     return { changed: true, items };
   }
   async checkItemUpdate(slug, lastEdited) {
-    const item = await this.findBySlug(slug);
+    const item = await this.find(slug);
     if (!item) return { changed: false };
     if (!this.isPublished(item)) return { changed: false };
     if (item.updatedAt === lastEdited) return { changed: false };
-    const entry = await this.renderBySlug(slug);
-    if (!entry) return { changed: false };
+    const entry = await this.buildCachedItem(item);
     await this.docCache.setItem(slug, entry);
     return {
       changed: true,
@@ -380,6 +576,45 @@ var CMS = class {
       notionUpdatedAt: entry.notionUpdatedAt
     };
   }
+  // ── 後方互換 SWR ────────────────────────────────────────────────────────
+  /** @deprecated cached.list() を使用してください。 */
+  async getList() {
+    const result = await this.cachedList();
+    return { items: result.items, listVersion: buildListVersion(result.items) };
+  }
+  /** @deprecated cached.get() を使用してください。 */
+  getItem(slug) {
+    return this.cachedGet(slug);
+  }
+  /** @deprecated cache.prefetchAll() を使用してください。 */
+  async prefetchAllLegacy(opts) {
+    return this.prefetchAll(opts);
+  }
+  // ── 後方互換クエリ API ──────────────────────────────────────────────────
+  /** @deprecated query().status(s).execute() を使用してください。 */
+  async listByStatus(status) {
+    const statuses = Array.isArray(status) ? status : [status];
+    return this.query().status(statuses).execute().then((r) => r.items);
+  }
+  /** @deprecated query().where(pred).execute() を使用してください。 */
+  async where(predicate) {
+    return this.query().where(predicate).execute().then((r) => r.items);
+  }
+  /** @deprecated query().paginate(opts).execute() を使用してください。 */
+  async paginate(opts) {
+    const result = await this.query().paginate(opts).execute();
+    return {
+      items: result.items,
+      total: result.total,
+      page: result.page,
+      perPage: result.perPage,
+      hasNext: result.hasNext
+    };
+  }
+  /** @deprecated query().adjacent(slug) を使用してください。 */
+  getAdjacent(slug) {
+    return this.query().adjacent(slug);
+  }
   // ── 画像配信 ───────────────────────────────────────────────────────────
   /** ハッシュキーでキャッシュ画像を取得する。 */
   getCachedImage(hash) {
@@ -396,6 +631,11 @@ var CMS = class {
   }
   // ── プライベートヘルパー ────────────────────────────────────────────────
   async buildCachedItem(item) {
+    const start = Date.now();
+    this.logger?.info?.("\u30B3\u30F3\u30C6\u30F3\u30C4\u306E\u30EC\u30F3\u30C0\u30EA\u30F3\u30B0\u958B\u59CB", {
+      slug: item.slug,
+      pageId: item.id
+    });
     let markdown;
     try {
       markdown = await this.source.loadMarkdown(item);
@@ -435,14 +675,28 @@ var CMS = class {
         }
       });
     }
-    return {
+    if (this.hooks.afterRender) {
+      html = await this.hooks.afterRender(html, item);
+    }
+    let result = {
       html,
       item,
       notionUpdatedAt: item.updatedAt,
       cachedAt: Date.now()
     };
+    if (this.hooks.beforeCache) {
+      result = await this.hooks.beforeCache(result);
+    }
+    this.logger?.info?.("\u30B3\u30F3\u30C6\u30F3\u30C4\u306E\u30EC\u30F3\u30C0\u30EA\u30F3\u30B0\u5B8C\u4E86", {
+      slug: item.slug,
+      durationMs: Date.now() - start
+    });
+    return result;
   }
 };
+function buildListVersion(items) {
+  return items.map((item) => `${item.id}:${item.updatedAt}`).join("|");
+}
 function createCMS(opts) {
   return new CMS(opts);
 }
@@ -484,10 +738,18 @@ function mapItem(page, props) {
   }
   return parsed.data;
 }
+
+// src/types/plugin.ts
+function definePlugin(plugin) {
+  return plugin;
+}
 export {
   CMS,
   CMSError,
+  DEFAULT_RETRY_CONFIG,
+  QueryBuilder,
   createCMS,
+  definePlugin,
   getPlainText,
   isCMSError,
   isStale,
@@ -495,7 +757,10 @@ export {
   memoryCache,
   memoryDocumentCache,
   memoryImageCache,
+  mergeHooks,
+  mergeLoggers,
   noopDocumentCache,
   noopImageCache,
-  sha256Hex
+  sha256Hex,
+  withRetry
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notion-headless-cms/core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Core CMS engine for notion-headless-cms — fetch, transform, cache with stale-while-revalidate strategy",
   "keywords": [
     "notion",
@@ -43,7 +43,7 @@
     "unified": "^11.0.5",
     "zod": "^4.1.12",
     "@notion-headless-cms/fetcher": "0.1.0",
-    "@notion-headless-cms/transformer": "0.1.0",
+    "@notion-headless-cms/transformer": "0.1.1",
     "@notion-headless-cms/renderer": "0.1.0"
   },
   "scripts": {