@notion-headless-cms/core 0.1.2 → 0.1.3

package/dist/index.d.mts

@@ -0,0 +1,449 @@
+import { a as StorageBinary, i as CachedItemList, n as CMSSchemaProperties, r as CachedItem, t as BaseContentItem } from "./content-BrwEY2_p.mjs";
+import { i as InvalidateScope, n as DocumentCacheAdapter, r as ImageCacheAdapter, t as CacheConfig } from "./cache-B-MG4yyg.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-DCSAQkST.mjs";
+import { MemoryDocumentCacheOptions, MemoryImageCacheOptions, memoryCache, memoryDocumentCache, memoryImageCache } from "./cache/memory.mjs";
+import { noopDocumentCache, noopImageCache } from "./cache/noop.mjs";
+import { CMSError, CMSErrorCode, CMSErrorContext, isCMSError, isCMSErrorInNamespace } from "./errors.mjs";
+
+//#region src/content/blocks.d.ts
+/**
+ * CMS 本文の中間表現 (AST)。
+ *
+ * DataSource が本文をこの配列にノーマライズして返す。
+ * レンダラー (`blocksToHtml`) やカスタム React コンポーネントは
+ * この型だけを扱えばよい。
+ *
+ * 対応が難しいブロック (Notion の column / synced block など) は
+ * `{ type: "raw", html }` にフォールバックする。
+ */
+type ContentBlock = {
+  type: "paragraph";
+  children: InlineNode[];
+} | {
+  type: "heading";
+  level: 1 | 2 | 3;
+  children: InlineNode[];
+} | {
+  type: "image";
+  src: string;
+  alt?: string;
+  cachedHash?: string;
+} | {
+  type: "code";
+  lang?: string;
+  value: string;
+} | {
+  type: "list";
+  ordered: boolean;
+  items: ContentBlock[][];
+} | {
+  type: "quote";
+  children: ContentBlock[];
+} | {
+  type: "divider";
+} | {
+  type: "raw";
+  html: string;
+};
+/** paragraph / heading 等の子に並ぶインラインノード。 */
+type InlineNode = {
+  type: "text";
+  value: string;
+  bold?: boolean;
+  italic?: boolean;
+  code?: boolean;
+} | {
+  type: "link";
+  url: string;
+  children: InlineNode[];
+} | {
+  type: "break";
+};
+/**
+ * `getItem({ include: { content: true } })` で返される本文。
+ * blocks は常に同梱。html / markdown は遅延生成。
+ */
+interface ContentResult {
+  /** 本文の AST (第一級)。 */
+  blocks: ContentBlock[];
+  /** 遅延 HTML。renderer が必要な場合のみ呼ぶ。 */
+  html(): Promise<string>;
+  /** 遅延 Markdown。 */
+  markdown(): Promise<string>;
+}
+/** 画像参照 (DataSource.resolveImageUrl に渡す)。 */
+interface ImageRef {
+  /** 元の Notion 画像 URL (期限切れの可能性あり)。 */
+  originalUrl: string;
+  /** 関連するアイテム ID。 */
+  itemId?: string;
+}
+//#endregion
+//#region src/types/collection.d.ts
+/** 並び順指定。 */
+interface SortOption<T extends BaseContentItem = BaseContentItem> {
+  /** ソートするプロパティ名。 */
+  by: keyof T & string;
+  /** 昇順 / 降順。デフォルト "desc"。 */
+  direction?: "asc" | "desc";
+}
+/** `getList` のフィルタ / ソート / ページング。 */
+interface GetListOptions<T extends BaseContentItem = BaseContentItem> {
+  /** ステータス絞り込み (`publishedStatuses` を上書き)。 */
+  statuses?: string[];
+  /** プロパティ一致フィルタ (in-memory フィルタ)。 */
+  where?: Partial<Record<keyof T, unknown>>;
+  /** タグ絞り込み (schema に tags: string[] フィールドがある場合)。 */
+  tag?: string;
+  /** ソート。デフォルトは publishedAt の降順。 */
+  sort?: SortOption<T>;
+  /** 最大件数。 */
+  limit?: number;
+  /** スキップ件数。 */
+  skip?: number;
+}
+/** `adjacent` の並び順指定。 */
+interface AdjacencyOptions<T extends BaseContentItem = BaseContentItem> {
+  sort?: SortOption<T>;
+}
+/** `getItem` の返り値 (本文常時同梱)。 */
+type ItemWithContent<T extends BaseContentItem> = T & {
+  content: ContentResult;
+};
+/**
+ * コレクション別の CMS クライアント。
+ * `cms.posts.getItem(slug)` のようにアクセスする。
+ */
+interface CollectionClient<T extends BaseContentItem = BaseContentItem> {
+  /** スラッグで単件取得 (本文込み)。キャッシュを経由 (SWR)。 */
+  getItem(slug: string): Promise<ItemWithContent<T> | null>;
+  /** 公開済みアイテム一覧 (本文なし、一覧ページ向け)。 */
+  getList(opts?: GetListOptions<T>): Promise<T[]>;
+  /** Next App Router の `generateStaticParams` 向け。 */
+  getStaticParams(): Promise<{
+    slug: string;
+  }[]>;
+  /** SSG のパス一覧 (スラッグ配列)。 */
+  getStaticPaths(): Promise<string[]>;
+  /** 前後記事のナビゲーション。 */
+  adjacent(slug: string, opts?: AdjacencyOptions<T>): Promise<{
+    prev: T | null;
+    next: T | null;
+  }>;
+  /** 指定スコープのキャッシュを無効化する。 */
+  revalidate(scope?: "all" | {
+    slug: string;
+  }): Promise<void>;
+  /** 全コンテンツをプリフェッチしてキャッシュに保存。 */
+  prefetch(opts?: {
+    concurrency?: number;
+    onProgress?: (done: number, total: number) => void;
+  }): Promise<{
+    ok: number;
+    failed: number;
+  }>;
+}
+//#endregion
+//#region src/types/data-source.d.ts
+/**
+ * キャッシュ無効化のスコープ (DataSource 層で参照する形)。
+ */
+type InvalidateScope$1 = "all" | {
+  collection: string;
+} | {
+  collection: string;
+  slug: string;
+};
+/**
+ * Webhook 受信時の検証設定。
+ */
+interface WebhookConfig {
+  /** 署名検証用シークレット。 */
+  secret?: string;
+}
+/**
+ * コンテンツソースを抽象化する v1 インターフェース。
+ *
+ * ユーザーは直接実装しない。`notion-orm` 等の ORM パッケージが実装する。
+ * core は Notion 固有の知識を持たず、このインターフェース経由でのみデータを扱う。
+ * 将来 `googledocs-orm` 等の別ソースもこの I/F を満たせば差し替え可能。
+ */
+interface DataSource<T extends BaseContentItem = BaseContentItem> {
+  /** ソース識別子 (ロギング・デバッグ用)。 */
+  readonly name: string;
+  /** 公開扱いするステータス値 (ORM 側デフォルト)。 */
+  readonly publishedStatuses?: readonly string[];
+  /** アクセス許可するステータス値 (ORM 側デフォルト)。 */
+  readonly accessibleStatuses?: readonly string[];
+  /** 公開済みアイテム一覧を取得する。 */
+  list(opts?: {
+    publishedStatuses?: readonly string[];
+  }): Promise<T[]>;
+  /** スラッグで単件取得。見つからなければ null。 */
+  findBySlug(slug: string): Promise<T | null>;
+  /** アイテム本文を ContentBlock 配列で返す。 */
+  loadBlocks(item: T): Promise<ContentBlock[]>;
+  /** アイテム本文を Markdown 文字列で返す (html() 生成の元ソース)。 */
+  loadMarkdown(item: T): Promise<string>;
+  /** SWR 鮮度判定用。item の最終更新タイムスタンプ。 */
+  getLastModified(item: T): string;
+  /** リスト全体のバージョン文字列 (例: 最新 last_edited_time)。 */
+  getListVersion(items: T[]): string;
+  /** 期限切れ画像 URL の再取得 (Notion の署名 URL 対応)。 */
+  resolveImageUrl?(ref: ImageRef): Promise<string>;
+  /**
+   * Webhook リクエストをパースして無効化スコープを返す。
+   * 実装していない場合は `$handler` が body の `{ slug }` にフォールバック。
+   */
+  parseWebhook?(req: Request, config: WebhookConfig): Promise<InvalidateScope$1>;
+}
+/**
+ * `nhcSchema` の各コレクション設定エントリ。
+ * ユーザーは CLI 生成の `nhcSchema` を渡すだけで、
+ * この型は `createCMS` 内部で DataSource のファクトリに渡される。
+ */
+interface CollectionConfig<T extends BaseContentItem = BaseContentItem> {
+  /** Notion データソース (database) ID。 */
+  databaseId: string;
+  /** スキーマ情報 (ORM が解釈する不透明データ)。 */
+  schema?: any;
+  /** 公開扱いするステータス値。 */
+  publishedStatuses?: string[];
+  /** アクセス許可するステータス値。 */
+  accessibleStatuses?: string[];
+  /** `T` を型レベルで持ち回るためのマーカー (ランタイム値なし)。 */
+  __itemType?: T;
+}
+/**
+ * `nhc generate` が生成する `nhcSchema` の型。
+ * コレクション名をキーとして、各コレクションの設定を保持する。
+ */
+type NHCSchema = Record<string, CollectionConfig<any>>;
+/** `CollectionConfig<T>` から `T` を抽出するユーティリティ型。 */
+type InferCollectionItem<C> = C extends CollectionConfig<infer T> ? T : BaseContentItem;
+/**
+ * DataSource を生成するファクトリ関数の型。
+ * `createCMS` はコレクション名 → この関数 → DataSource の経路で組み立てる。
+ *
+ * ユーザーコードは直接呼ばない。`@notion-headless-cms/notion-orm` 等が provide する。
+ */
+type DataSourceFactory = <T extends BaseContentItem>(args: {
+  collection: string;
+  config: CollectionConfig<T>;
+  notionToken: string;
+}) => DataSource<T>;
+//#endregion
+//#region src/types/config.d.ts
+/**
+ * renderer プラグインの不透明型。
+ * core は unified / remark / rehype に依存せず、このリストをそのまま renderer に渡すだけ。
+ */
+type RendererPluginList = any[];
+/**
+ * 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;
+}
+/** レートリミット・リトライ設定。 */
+interface RateLimiterConfig {
+  /** 同時実行数の上限。デフォルト: 3 */
+  maxConcurrent?: number;
+  /** リトライ対象の HTTP ステータスコード。デフォルト: [429, 502, 503] */
+  retryOn?: number[];
+  /** 最大リトライ回数。デフォルト: 4 */
+  maxRetries?: number;
+  /** リトライ時の基準待機時間（ミリ秒）。デフォルト: 1000 */
+  baseDelayMs?: number;
+}
+/** `createCMS({ dataSources })` の map 型。 */
+type DataSourceMap = Record<string, DataSource<any>>;
+/** `DataSourceMap` から各 T を抽出するユーティリティ型。 */
+type InferDataSourceItem<D> = D extends DataSource<infer T> ? T : BaseContentItem;
+/**
+ * `createCMS()` に渡すオプション。v1 の正式な入力シグネチャ。
+ * ユーザーは `nhc generate` が生成した `nhcDataSources` を渡すだけ。
+ */
+interface CreateCMSOptions<D extends DataSourceMap = DataSourceMap> {
+  /** コレクション名 → DataSource のマップ (CLI 生成の `nhcDataSources`)。 */
+  dataSources: D;
+  /** レンダラー関数。未指定時は @notion-headless-cms/renderer の renderMarkdown を使用。 */
+  renderer?: RendererFn;
+  /** キャッシュ設定。未設定時はキャッシュなし。 */
+  cache?: CacheConfig;
+  /** レンダリング・コンテンツ処理設定。 */
+  content?: ContentConfig;
+  /** Cloudflare Workers の waitUntil に相当する非同期処理の登録関数。 */
+  waitUntil?: (p: Promise<unknown>) => void;
+  /** ライフサイクルフック (全コレクション共通)。 */
+  hooks?: CMSHooks<any>;
+  /** プラグイン配列。 */
+  plugins?: CMSPlugin<any>[];
+  /** ロガー。 */
+  logger?: Logger;
+  /** レートリミット・リトライ設定。 */
+  rateLimiter?: RateLimiterConfig;
+}
+//#endregion
+//#region src/cache.d.ts
+/** 文字列をSHA-256でハッシュ化し、16進数文字列として返す。画像キーの生成に使用。 */
+declare function sha256Hex(input: string): Promise<string>;
+/**
+ * キャッシュが有効期限切れかどうかを判定する。
+ * ttlMs が未指定の場合は常に false（無期限有効）を返す。
+ */
+declare function isStale(cachedAt: number, ttlMs?: number): boolean;
+//#endregion
+//#region src/handler.d.ts
+/** `$handler()` の挙動設定。 */
+interface HandlerOptions {
+  /** マウントするベースパス。デフォルト `/api/cms`。 */
+  basePath?: string;
+  /** 画像プロキシのパス (basePath 相対)。デフォルト `/images/:hash`。 */
+  imagesPath?: string;
+  /** revalidate webhook のパス (basePath 相対)。デフォルト `/revalidate`。 */
+  revalidatePath?: string;
+  /** Webhook 署名検証用シークレット (未指定なら検証スキップ)。 */
+  webhookSecret?: string;
+  /** デフォルト実装を無効化する場合 true。 */
+  disabled?: boolean;
+}
+/** `$handler()` が内部で依存する CMS 機能の最小セット。 */
+interface HandlerAdapter {
+  imageCache: ImageCacheAdapter;
+  /** コレクション名で DataSource を取り出し parseWebhook にフォワードする。 */
+  parseWebhook(req: Request, webhookSecret: string | undefined): Promise<InvalidateScope$1 | null>;
+  revalidate(scope: InvalidateScope$1): Promise<void>;
+}
+/**
+ * Web Standard な Request → Response ルーター。
+ * Next.js / React Router / Hono / Cloudflare Workers いずれでも使える。
+ *
+ * ルート:
+ * - GET  `{basePath}/images/:hash` — 画像プロキシ
+ * - POST `{basePath}/revalidate`   — Webhook 受信 + $revalidate()
+ */
+declare function createHandler(adapter: HandlerAdapter, opts?: HandlerOptions): (req: Request) => Promise<Response>;
+//#endregion
+//#region src/cms.d.ts
+/** `CMSClient<D>` — コレクション別アクセス + グローバル操作の合成型。 */
+type CMSClient<D extends DataSourceMap> = { [K in keyof D]: CollectionClient<InferDataSourceItem<D[K]>> } & CMSGlobalOps<D>;
+/** `CMSClient` のグローバル名前空間。`$` プレフィックス。 */
+interface CMSGlobalOps<D extends DataSourceMap> {
+  /** 登録されているコレクション名の一覧。 */
+  readonly $collections: readonly (keyof D & string)[];
+  /** 全コレクションまたは特定コレクションのキャッシュを無効化する。 */
+  $revalidate(scope?: InvalidateScope$1): Promise<void>;
+  /** Web Standard なルーティングハンドラ (画像プロキシ / webhook) を生成する。 */
+  $handler(opts?: HandlerOptions): (req: Request) => Promise<Response>;
+  /** ハッシュキーでキャッシュ画像を取得する。 */
+  $getCachedImage(hash: string): ReturnType<ImageCacheAdapter["get"]>;
+}
+/**
+ * 複数の DataSource を束ねた CMS クライアントを生成する。
+ *
+ * @example
+ * const cms = createCMS({
+ *   dataSources: {
+ *     posts: createNotionCollection({ token, databaseId, schema }),
+ *   },
+ *   cache: { document, image, ttlMs: 60_000 },
+ * });
+ * const post = await cms.posts.getItem("my-slug");
+ */
+declare function createCMS<D extends DataSourceMap>(opts: CreateCMSOptions<D>): CMSClient<D>;
+//#endregion
+//#region src/rendering.d.ts
+/** `buildCachedItem` に必要な CMS の依存を束ねたコンテキスト。 */
+interface RenderContext<T extends BaseContentItem> {
+  source: DataSource<T>;
+  rendererFn: RendererFn | undefined;
+  imgCache: ImageCacheAdapter;
+  hasImageCache: boolean;
+  imageProxyBase: string;
+  contentConfig: ContentConfig | undefined;
+  hooks: CMSHooks<T>;
+  logger: Logger | undefined;
+}
+//#endregion
+//#region src/retry.d.ts
+interface RetryConfig {
+  retryOn: number[];
+  maxRetries: number;
+  baseDelayMs: number;
+  /** true のとき指数バックオフにランダムジッターを加える（Thundering Herd 対策）。デフォルト: true */
+  jitter?: boolean;
+  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>;
+//#endregion
+//#region src/collection.d.ts
+/**
+ * コレクション別キャッシュキーを生成する。
+ * item: `{collection}:{slug}` / list: `{collection}`
+ */
+declare function collectionKey(collection: string, slug?: string): string;
+/** 単一コレクションの DataSource + SWR キャッシュ依存を束ねたコンテキスト。 */
+interface CollectionContext<T extends BaseContentItem> {
+  collection: string;
+  source: DataSource<T>;
+  docCache: DocumentCacheAdapter<T>;
+  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;
+}
+/** CollectionClient の実装。ユーザーは `createCMS` 経由でインスタンスを受け取る。 */
+declare class CollectionClientImpl<T extends BaseContentItem> implements CollectionClient<T> {
+  private readonly ctx;
+  constructor(ctx: CollectionContext<T>);
+  getItem(slug: string): Promise<ItemWithContent<T> | null>;
+  getList(opts?: GetListOptions<T>): Promise<T[]>;
+  getStaticParams(): Promise<{
+    slug: string;
+  }[]>;
+  getStaticPaths(): Promise<string[]>;
+  adjacent(slug: string, opts?: AdjacencyOptions<T>): Promise<{
+    prev: T | null;
+    next: T | null;
+  }>;
+  revalidate(scope?: "all" | {
+    slug: string;
+  }): Promise<void>;
+  prefetch(opts?: {
+    concurrency?: number;
+    onProgress?: (done: number, total: number) => void;
+  }): Promise<{
+    ok: number;
+    failed: number;
+  }>;
+  private attachContent;
+  private fetchList;
+  private fetchListRaw;
+  private findRaw;
+}
+//#endregion
+export { type AdjacencyOptions, type BaseContentItem, type CMSClient, CMSError, type CMSErrorCode, type CMSErrorContext, type CMSGlobalOps, type CMSHooks, type CMSPlugin, type CMSSchemaProperties, type CacheConfig, type InvalidateScope as CacheInvalidateScope, type CachedItem, type CachedItemList, type CollectionClient, CollectionClientImpl, type CollectionConfig, type CollectionContext, type ContentBlock, type ContentConfig, type ContentResult, type CreateCMSOptions, DEFAULT_RETRY_CONFIG, type DataSource, type DataSourceFactory, type DataSourceMap, type DocumentCacheAdapter, type GetListOptions, type HandlerAdapter, type HandlerOptions, type ImageCacheAdapter, type ImageRef, type InferCollectionItem, type InferDataSourceItem, type InlineNode, type InvalidateScope$1 as InvalidateScope, type ItemWithContent, type Logger, type MaybePromise, type MemoryDocumentCacheOptions, type MemoryImageCacheOptions, type NHCSchema, type RateLimiterConfig, type RenderOptions, type RendererFn, type RendererPluginList, type RetryConfig, type SortOption, type StorageBinary, type WebhookConfig, collectionKey, createCMS, createHandler, definePlugin, isCMSError, isCMSErrorInNamespace, isStale, memoryCache, memoryDocumentCache, memoryImageCache, mergeHooks, mergeLoggers, noopDocumentCache, noopImageCache, sha256Hex, withRetry };
+//# sourceMappingURL=index.d.mts.map