@notion-headless-cms/core 0.0.4 → 0.0.6

package/dist/index.d.ts

@@ -0,0 +1,233 @@
+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';
+
+/**
+ * ライブラリが動作するために必須なフィールド。
+ * 利用者はこのインターフェースを拡張して独自のコンテンツ型を定義する。
+ *
+ * @example
+ * interface Post extends BaseContentItem {
+ *   title: string;
+ *   author: string;
+ * }
+ * createCMS<Post>({ schema: { mapItem: (page) => ... } })
+ */
+interface BaseContentItem {
+    id: string;
+    slug: string;
+    status: string;
+    publishedAt: string;
+    updatedAt: 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;
+}
+/** CMSコアが依存するストレージ抽象。 */
+interface StorageAdapter {
+    get(key: string): Promise<ArrayBuffer | null>;
+    put(key: string, data: ArrayBuffer | ArrayBufferView | string, options?: {
+        contentType?: string;
+    }): Promise<void>;
+    json<T>(key: string): Promise<T | null>;
+    binary(key: string): Promise<StorageBinary | null>;
+}
+/** ライブラリが必要とする最小限の環境バインディング。 */
+interface CMSEnv {
+    NOTION_TOKEN: string;
+    NOTION_DATA_SOURCE_ID: string;
+}
+/** Notionのプロパティ名マッピング（すべてオプション）。 */
+interface CMSSchemaProperties {
+    /** Notionのスラッグプロパティ名。デフォルト: 'Slug' */
+    slug?: string;
+    /** Notionのステータスプロパティ名。デフォルト: 'Status' */
+    status?: string;
+    /** Notionの公開日プロパティ名。デフォルト: 'CreatedAt' */
+    date?: string;
+}
+/**
+ * CMSの設定オブジェクト。
+ * ジェネリクス型 T にカスタムコンテンツ型を指定できる（デフォルト: BaseContentItem）。
+ */
+interface CMSConfig<T extends BaseContentItem = BaseContentItem> {
+    /** Notion API 認証情報。コンストラクタでクライアントを事前生成するために使用。 */
+    env?: CMSEnv;
+    /** キャッシュ/画像保存用ストレージ。未設定時はキャッシュ機能を無効化。 */
+    storage?: StorageAdapter;
+    schema?: {
+        /**
+         * Notionページをコンテンツ型 T にマッピングするカスタム関数。
+         * 指定した場合 properties の設定は無視される（slug プロパティ名のみ例外）。
+         */
+        mapItem?: (page: PageObjectResponse) => T;
+        /** mapItem 未使用時のプロパティ名マッピング。 */
+        properties?: CMSSchemaProperties;
+        /** getItems() で返す「公開済み」ステータス値の配列。デフォルト: [] （全件返す） */
+        publishedStatuses?: string[];
+        /** getItemBySlug() でアクセス可能なステータス値の配列。デフォルト: [] （全件許可） */
+        accessibleStatuses?: string[];
+    };
+    transformer?: {
+        /** カスタムブロックハンドラーのマップ。Notionブロックタイプをキーとする。 */
+        blocks?: Record<string, BlockHandler>;
+    };
+    renderer?: {
+        /** 画像プロキシのベースURL。デフォルト: '/api/images' */
+        imageProxyBase?: string;
+        /** 追加する remark プラグイン。 */
+        remarkPlugins?: PluggableList;
+        /** 追加する rehype プラグイン。 */
+        rehypePlugins?: PluggableList;
+        /** デフォルトのパイプラインを置き換えるカスタムレンダラー。 */
+        render?: RendererFn;
+    };
+    cache?: {
+        /** コンテンツ一覧のキャッシュキー。デフォルト: 'content.json' */
+        listKey?: string;
+        /** 個別コンテンツのキャッシュキープレフィックス。デフォルト: 'content/' */
+        itemPrefix?: string;
+        /** 画像キャッシュのキープレフィックス。デフォルト: 'images/' */
+        imagePrefix?: string;
+        /** キャッシュの有効期間（ミリ秒）。未設定の場合はTTLなし。 */
+        ttlMs?: number;
+    };
+}
+
+/** 文字列をSHA-256でハッシュ化し、16進数文字列として返す。画像キーの生成に使用。 */
+declare function sha256Hex(input: string): Promise<string>;
+/**
+ * キャッシュが有効期限切れかどうかを判定する。
+ * ttlMs が未指定の場合は常に false（無期限有効）を返す。
+ */
+declare function isStale(cachedAt: number, ttlMs?: number): boolean;
+/** ストレージキャッシュ操作をまとめたヘルパークラス。キープレフィックスは設定で変更可能。 */
+declare class CacheStore<T extends BaseContentItem = BaseContentItem> {
+    private readonly storage?;
+    private readonly listKey;
+    private readonly itemPrefix;
+    private readonly imagePrefix;
+    constructor(storage: StorageAdapter | undefined, listKey: string, itemPrefix: string, imagePrefix: string);
+    getItemList(): Promise<CachedItemList<T> | null>;
+    setItemList(items: T[]): Promise<void>;
+    getItem(slug: string): Promise<CachedItem<T> | null>;
+    setItem(slug: string, data: CachedItem<T>): Promise<void>;
+    getImage(hash: string): Promise<StorageBinary | null>;
+    setImage(hash: string, data: ArrayBuffer, contentType: string): Promise<void>;
+}
+
+/**
+ * Notion をバックエンドとして使う汎用ヘッドレス CMSクラス。
+ *
+ * @example
+ * const cms = createCMS({
+ *   env: { NOTION_TOKEN: '...', NOTION_DATA_SOURCE_ID: '...' },
+ *   schema: { publishedStatuses: ['Published'] }
+ * });
+ * const items = await cms.getItems();
+ */
+declare class CMS<T extends BaseContentItem = BaseContentItem> {
+    private readonly itemMapper;
+    private readonly slugPropName;
+    private readonly publishedStatuses;
+    private readonly accessibleStatuses;
+    private readonly imageProxyBase;
+    private readonly transformerConfig;
+    private readonly rendererConfig;
+    private readonly store;
+    private readonly hasStorage;
+    private readonly ttlMs;
+    private readonly client;
+    private readonly dataSourceId;
+    constructor(config?: CMSConfig<T>);
+    private requireClient;
+    /** 公開済みコンテンツ一覧を Notion から直接取得する。 */
+    getItems(): Promise<T[]>;
+    /** スラッグでコンテンツを Notion から直接取得する。 */
+    getItemBySlug(slug: string): Promise<T | null>;
+    /** アイテムが publishedStatuses に含まれるステータスかどうかを返す。 */
+    isPublished(item: T): boolean;
+    /** コンテンツをMarkdown→HTMLにレンダリングし、CachedItemとして返す。 */
+    renderItem(item: T): Promise<CachedItem<T>>;
+    /** スラッグでコンテンツを取得してMarkdown→HTMLにレンダリングする。 */
+    renderItemBySlug(slug: string): Promise<CachedItem<T> | null>;
+    getCachedItemList(): Promise<CachedItemList<T> | null>;
+    setCachedItemList(items: T[]): Promise<void>;
+    getCachedItem(slug: string): Promise<CachedItem<T> | null>;
+    setCachedItem(slug: string, data: CachedItem<T>): Promise<void>;
+    getCachedImage(hash: string): Promise<StorageBinary | null>;
+    createCachedImageResponse(hash: string): Promise<Response | null>;
+    getItemsCachedFirst(options?: {
+        waitUntil?: (promise: Promise<void>) => void;
+    }): Promise<{
+        items: T[];
+        listVersion: string;
+    }>;
+    getItemCachedFirst(slug: string, options?: {
+        waitUntil?: (promise: Promise<void>) => void;
+    }): Promise<CachedItem<T> | null>;
+    checkItemsUpdate(clientVersion: string): Promise<{
+        changed: false;
+    } | {
+        changed: true;
+        items: T[];
+    }>;
+    checkItemUpdate(slug: string, lastEdited: string): Promise<{
+        changed: false;
+    } | {
+        changed: true;
+        html: string;
+        item: T;
+        notionUpdatedAt: string;
+    }>;
+    private buildCachedItem;
+}
+/** 設定済みのCMSインスタンスを生成するファクトリ関数。 */
+declare function createCMS<T extends BaseContentItem = BaseContentItem>(config?: CMSConfig<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;
+    });
+}
+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;
+
+export { type BaseContentItem, CMS, type CMSConfig, type CMSEnv, CMSError, type CMSErrorCode, type CMSErrorContext, type CMSSchemaProperties, CacheStore, type CachedItem, type CachedItemList, type StorageAdapter, type StorageBinary, createCMS, getPlainText, isCMSError, isStale, mapItem, sha256Hex };

package/dist/index.js

@@ -0,0 +1,465 @@
+// src/cache.ts
+async function sha256Hex(input) {
+  const data = new TextEncoder().encode(input);
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function isStale(cachedAt, ttlMs) {
+  if (ttlMs === void 0) return false;
+  return Date.now() - cachedAt > ttlMs;
+}
+var CacheStore = class {
+  storage;
+  listKey;
+  itemPrefix;
+  imagePrefix;
+  constructor(storage, listKey, itemPrefix, imagePrefix) {
+    this.storage = storage;
+    this.listKey = listKey;
+    this.itemPrefix = itemPrefix;
+    this.imagePrefix = imagePrefix;
+  }
+  getItemList() {
+    if (!this.storage) return Promise.resolve(null);
+    return this.storage.json(this.listKey);
+  }
+  async setItemList(items) {
+    if (!this.storage) return;
+    const data = { items, cachedAt: Date.now() };
+    await this.storage.put(this.listKey, JSON.stringify(data), {
+      contentType: "application/json"
+    });
+  }
+  getItem(slug) {
+    if (!this.storage) return Promise.resolve(null);
+    return this.storage.json(`${this.itemPrefix}${slug}.json`);
+  }
+  async setItem(slug, data) {
+    if (!this.storage) return;
+    await this.storage.put(
+      `${this.itemPrefix}${slug}.json`,
+      JSON.stringify(data),
+      { contentType: "application/json" }
+    );
+  }
+  getImage(hash) {
+    if (!this.storage) return Promise.resolve(null);
+    return this.storage.binary(`${this.imagePrefix}${hash}`);
+  }
+  async setImage(hash, data, contentType) {
+    if (!this.storage) return;
+    await this.storage.put(`${this.imagePrefix}${hash}`, data, { contentType });
+  }
+};
+
+// src/cms.ts
+import {
+  createClient,
+  queryAllPages,
+  queryPageBySlug
+} from "@notion-headless-cms/fetcher";
+import { renderMarkdown } from "@notion-headless-cms/renderer";
+import { Transformer } from "@notion-headless-cms/transformer";
+
+// 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;
+}
+
+// src/image.ts
+function inferContentType(url, responseContentType) {
+  if (responseContentType?.startsWith("image/")) {
+    return responseContentType.split(";")[0].trim();
+  }
+  if (url.includes(".png")) return "image/png";
+  if (url.includes(".gif")) return "image/gif";
+  if (url.includes(".webp")) return "image/webp";
+  return "image/jpeg";
+}
+async function fetchAndCacheImage(store, notionUrl, imageProxyBase) {
+  const hash = await sha256Hex(notionUrl);
+  const proxyUrl = `${imageProxyBase}/${hash}`;
+  const existing = await store.getImage(hash);
+  if (existing) return proxyUrl;
+  try {
+    const response = await fetch(notionUrl, {
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (!response.ok) return proxyUrl;
+    const data = await response.arrayBuffer();
+    const contentType = inferContentType(
+      notionUrl,
+      response.headers.get("content-type")
+    );
+    await store.setImage(hash, data, contentType);
+  } catch (err) {
+    throw new CMSError({
+      code: "IMAGE_CACHE_FAILED",
+      message: "Failed to fetch or cache Notion image.",
+      cause: err,
+      context: { operation: "fetchAndCacheImage", notionUrl }
+    });
+  }
+  return proxyUrl;
+}
+function buildCacheImageFn(store, imageProxyBase) {
+  return (notionUrl) => fetchAndCacheImage(store, notionUrl, imageProxyBase);
+}
+
+// src/mapper.ts
+import { z } from "zod";
+var baseContentItemSchema = z.object({
+  id: z.string().min(1),
+  slug: z.string(),
+  status: z.string(),
+  publishedAt: z.string().min(1),
+  updatedAt: z.string().min(1)
+});
+function getPlainText(items) {
+  return items?.map((item) => item.plain_text).join("") ?? "";
+}
+function mapItem(page, props) {
+  const statusProperty = page.properties[props.status];
+  const dateProperty = page.properties[props.date];
+  const parsed = baseContentItemSchema.safeParse({
+    id: page.id,
+    slug: getPlainText(
+      page.properties[props.slug]?.rich_text
+    ),
+    status: statusProperty?.status?.name ?? statusProperty?.select?.name ?? "",
+    publishedAt: dateProperty?.date?.start ?? page.created_time,
+    updatedAt: page.last_edited_time
+  });
+  if (!parsed.success) {
+    throw new CMSError({
+      code: "NOTION_ITEM_SCHEMA_INVALID",
+      message: "Failed to parse Notion page into BaseContentItem.",
+      context: {
+        operation: "mapItem",
+        pageId: page.id,
+        issues: JSON.stringify(parsed.error.issues)
+      }
+    });
+  }
+  return parsed.data;
+}
+
+// src/cms.ts
+var DEFAULT_PROPERTIES = {
+  slug: "Slug",
+  status: "Status",
+  date: "CreatedAt"
+};
+var DEFAULT_IMAGE_PROXY_BASE = "/api/images";
+var DEFAULT_LIST_KEY = "content.json";
+var DEFAULT_ITEM_PREFIX = "content/";
+var DEFAULT_IMAGE_PREFIX = "images/";
+function buildListVersion(items) {
+  return items.map((item) => `${item.id}:${item.updatedAt}`).join("|");
+}
+function validateEnv(env) {
+  if (!env.NOTION_TOKEN || !env.NOTION_DATA_SOURCE_ID) {
+    throw new CMSError({
+      code: "CONFIG_INVALID",
+      message: "NOTION_TOKEN and NOTION_DATA_SOURCE_ID are required to use Notion CMS APIs.",
+      context: {
+        operation: "validateEnv",
+        hasNotionToken: !!env.NOTION_TOKEN,
+        hasNotionDataSourceId: !!env.NOTION_DATA_SOURCE_ID
+      }
+    });
+  }
+  return { dataSourceId: env.NOTION_DATA_SOURCE_ID };
+}
+var CMS = class {
+  itemMapper;
+  slugPropName;
+  publishedStatuses;
+  accessibleStatuses;
+  imageProxyBase;
+  transformerConfig;
+  rendererConfig;
+  store;
+  hasStorage;
+  ttlMs;
+  client;
+  dataSourceId;
+  constructor(config) {
+    const props = {
+      ...DEFAULT_PROPERTIES,
+      ...config?.schema?.properties
+    };
+    this.slugPropName = props.slug;
+    if (config?.schema?.mapItem) {
+      this.itemMapper = config.schema.mapItem;
+    } else {
+      this.itemMapper = (page) => mapItem(page, props);
+    }
+    this.publishedStatuses = config?.schema?.publishedStatuses ?? [];
+    this.accessibleStatuses = config?.schema?.accessibleStatuses ?? [];
+    this.imageProxyBase = config?.renderer?.imageProxyBase ?? DEFAULT_IMAGE_PROXY_BASE;
+    this.transformerConfig = config?.transformer;
+    this.rendererConfig = config?.renderer;
+    this.hasStorage = !!config?.storage;
+    this.ttlMs = config?.cache?.ttlMs;
+    this.store = new CacheStore(
+      config?.storage,
+      config?.cache?.listKey ?? DEFAULT_LIST_KEY,
+      config?.cache?.itemPrefix ?? DEFAULT_ITEM_PREFIX,
+      config?.cache?.imagePrefix ?? DEFAULT_IMAGE_PREFIX
+    );
+    if (config?.env) {
+      const { dataSourceId } = validateEnv(config.env);
+      this.client = createClient(config.env);
+      this.dataSourceId = dataSourceId;
+    }
+  }
+  // ── プライベートヘルパー（認証） ──────────────────────────────────────
+  requireClient() {
+    if (!this.client || !this.dataSourceId) {
+      throw new CMSError({
+        code: "CONFIG_INVALID",
+        message: "NOTION_TOKEN \u3068 NOTION_DATA_SOURCE_ID \u306F CMS \u306E\u8A2D\u5B9A\u306B\u5FC5\u8981\u3067\u3059\u3002",
+        context: { operation: "requireClient" }
+      });
+    }
+    return { client: this.client, dataSourceId: this.dataSourceId };
+  }
+  // ── コンテンツ取得 ────────────────────────────────────────────────────
+  /** 公開済みコンテンツ一覧を Notion から直接取得する。 */
+  async getItems() {
+    const { client, dataSourceId } = this.requireClient();
+    try {
+      const pages = await queryAllPages(client, dataSourceId);
+      const items = pages.map(this.itemMapper);
+      const filtered = this.publishedStatuses.length > 0 ? items.filter((item) => this.publishedStatuses.includes(item.status)) : items;
+      return filtered.sort(
+        (a, b) => new Date(b.publishedAt).getTime() - new Date(a.publishedAt).getTime()
+      );
+    } catch (err) {
+      if (isCMSError(err)) throw err;
+      throw new CMSError({
+        code: "NOTION_FETCH_ITEMS_FAILED",
+        message: "Failed to fetch items from Notion data source.",
+        cause: err,
+        context: { operation: "getItems", dataSourceId }
+      });
+    }
+  }
+  /** スラッグでコンテンツを Notion から直接取得する。 */
+  async getItemBySlug(slug) {
+    const { client, dataSourceId } = this.requireClient();
+    try {
+      const page = await queryPageBySlug(
+        client,
+        dataSourceId,
+        slug,
+        this.slugPropName
+      );
+      if (!page) return null;
+      const item = this.itemMapper(page);
+      if (this.accessibleStatuses.length > 0 && !this.accessibleStatuses.includes(item.status)) {
+        return null;
+      }
+      return 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: "getItemBySlug", dataSourceId, slug }
+      });
+    }
+  }
+  /** アイテムが publishedStatuses に含まれるステータスかどうかを返す。 */
+  isPublished(item) {
+    if (this.publishedStatuses.length === 0) return true;
+    return this.publishedStatuses.includes(item.status);
+  }
+  /** コンテンツをMarkdown→HTMLにレンダリングし、CachedItemとして返す。 */
+  async renderItem(item) {
+    const { client } = this.requireClient();
+    return this.buildCachedItem(client, item);
+  }
+  /** スラッグでコンテンツを取得してMarkdown→HTMLにレンダリングする。 */
+  async renderItemBySlug(slug) {
+    const { client, dataSourceId } = this.requireClient();
+    try {
+      const page = await queryPageBySlug(
+        client,
+        dataSourceId,
+        slug,
+        this.slugPropName
+      );
+      if (!page) return null;
+      const item = this.itemMapper(page);
+      if (this.accessibleStatuses.length > 0 && !this.accessibleStatuses.includes(item.status)) {
+        return null;
+      }
+      return this.buildCachedItem(client, 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: "renderItemBySlug", dataSourceId, slug }
+      });
+    }
+  }
+  // ── キャッシュ操作 ─────────────────────────────────────────────────────
+  getCachedItemList() {
+    return this.store.getItemList();
+  }
+  setCachedItemList(items) {
+    return this.store.setItemList(items);
+  }
+  getCachedItem(slug) {
+    return this.store.getItem(slug);
+  }
+  setCachedItem(slug, data) {
+    return this.store.setItem(slug, data);
+  }
+  getCachedImage(hash) {
+    return this.store.getImage(hash);
+  }
+  async createCachedImageResponse(hash) {
+    const object = await this.store.getImage(hash);
+    if (!object) return null;
+    const headers = new Headers();
+    if (object.contentType) headers.set("content-type", object.contentType);
+    headers.set("cache-control", "public, max-age=31536000, immutable");
+    return new Response(object.data, { headers });
+  }
+  // ── キャッシュ優先取得（Stale-While-Revalidate） ─────────────────────
+  async getItemsCachedFirst(options) {
+    const cached = await this.store.getItemList();
+    if (cached && !isStale(cached.cachedAt, this.ttlMs)) {
+      return {
+        items: cached.items,
+        listVersion: buildListVersion(cached.items)
+      };
+    }
+    const items = await this.getItems();
+    const save = this.store.setItemList(items);
+    if (options?.waitUntil) {
+      options.waitUntil(save);
+    } else {
+      await save;
+    }
+    return { items, listVersion: buildListVersion(items) };
+  }
+  async getItemCachedFirst(slug, options) {
+    const cached = await this.store.getItem(slug);
+    if (cached && !isStale(cached.cachedAt, this.ttlMs)) return cached;
+    const entry = await this.renderItemBySlug(slug);
+    if (!entry) return null;
+    const save = this.store.setItem(slug, entry);
+    if (options?.waitUntil) {
+      options.waitUntil(save);
+    } else {
+      await save;
+    }
+    return entry;
+  }
+  async checkItemsUpdate(clientVersion) {
+    const items = await this.getItems();
+    const serverVersion = buildListVersion(items);
+    if (serverVersion === clientVersion) return { changed: false };
+    await this.store.setItemList(items);
+    return { changed: true, items };
+  }
+  async checkItemUpdate(slug, lastEdited) {
+    const item = await this.getItemBySlug(slug);
+    if (!item) return { changed: false };
+    if (!this.isPublished(item)) return { changed: false };
+    if (item.updatedAt === lastEdited) return { changed: false };
+    const entry = await this.renderItemBySlug(slug);
+    if (!entry) return { changed: false };
+    await this.store.setItem(slug, entry);
+    return {
+      changed: true,
+      html: entry.html,
+      item: entry.item,
+      notionUpdatedAt: entry.notionUpdatedAt
+    };
+  }
+  // ── プライベートヘルパー ───────────────────────────────────────────────
+  async buildCachedItem(client, item) {
+    const transformer = new Transformer(
+      this.transformerConfig?.blocks ? { blocks: this.transformerConfig.blocks } : void 0
+    );
+    let markdown;
+    try {
+      markdown = await transformer.transform(client, item.id);
+    } catch (err) {
+      if (isCMSError(err)) throw err;
+      throw new CMSError({
+        code: "NOTION_MARKDOWN_FETCH_FAILED",
+        message: "Failed to load markdown from Notion.",
+        cause: err,
+        context: {
+          operation: "buildCachedItem:transform",
+          pageId: item.id,
+          slug: item.slug
+        }
+      });
+    }
+    const cacheImage = this.hasStorage ? buildCacheImageFn(this.store, this.imageProxyBase) : void 0;
+    let html;
+    try {
+      html = await renderMarkdown(markdown, {
+        imageProxyBase: this.imageProxyBase,
+        cacheImage,
+        remarkPlugins: this.rendererConfig?.remarkPlugins,
+        rehypePlugins: this.rendererConfig?.rehypePlugins,
+        render: this.rendererConfig?.render
+      });
+    } catch (err) {
+      if (isCMSError(err)) throw err;
+      throw new CMSError({
+        code: "RENDERER_FAILED",
+        message: "Failed to render markdown.",
+        cause: err,
+        context: {
+          operation: "buildCachedItem:renderMarkdown",
+          pageId: item.id,
+          slug: item.slug
+        }
+      });
+    }
+    return {
+      html,
+      item,
+      notionUpdatedAt: item.updatedAt,
+      cachedAt: Date.now()
+    };
+  }
+};
+function createCMS(config) {
+  return new CMS(config);
+}
+export {
+  CMS,
+  CMSError,
+  CacheStore,
+  createCMS,
+  getPlainText,
+  isCMSError,
+  isStale,
+  mapItem,
+  sha256Hex
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notion-headless-cms/core",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Core CMS engine for notion-headless-cms — fetch, transform, cache with stale-while-revalidate strategy",
   "keywords": [
     "notion",
@@ -39,12 +39,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@notion-headless-cms/fetcher": "latest",
-    "@notion-headless-cms/transformer": "latest",
-    "@notion-headless-cms/renderer": "latest",
     "@notionhq/client": "^5.18.0",
     "unified": "^11.0.5",
-    "zod": "^4.1.12"
+    "zod": "^4.1.12",
+    "@notion-headless-cms/fetcher": "0.0.4",
+    "@notion-headless-cms/transformer": "0.0.4",
+    "@notion-headless-cms/renderer": "0.0.4"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --out-dir dist",