@notion-headless-cms/core 0.1.2 → 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,349 @@
+import { a as StorageBinary, i as CachedItemList, n as CMSSchemaProperties, r as CachedItem, t as BaseContentItem } from "./content-BrwEY2_p.mjs";
+import { a as CollectionConfig, c as InferCollectionItem, d as ContentBlock, f as ContentResult, i as CMSSchema, l as InvalidateScope, m as InlineNode, n as DocumentCacheAdapter, o as DataSource, p as ImageRef, r as ImageCacheAdapter, s as DataSourceFactory, t as CacheConfig, u as WebhookConfig } from "./cache-Av7HRw_s.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/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/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` が生成した `cmsDataSources` を渡すだけ。
+ */
+interface CreateCMSOptions<D extends DataSourceMap = DataSourceMap> {
+  /** コレクション名 → DataSource のマップ (CLI 生成の `cmsDataSources`)。 */
+  dataSources: D;
+  /**
+   * ランタイムプリセット。`cache` / `renderer` のデフォルトを自動設定する。
+   *
+   * - `"node"`: Node.js 向け。`memoryDocumentCache` + `memoryImageCache` を有効化。
+   *   `ttlMs` と組み合わせて SWR の TTL を設定できる。
+   * - `"disabled"`: キャッシュを完全無効化する。
+   * - 省略: 従来の動作（`cache` / `renderer` をそのまま使用）。
+   *   `...nodePreset({ ttlMs })` のスプレッドパターンも引き続き動作する。
+   *
+   * `cache` を明示的に指定した場合は `preset` より `cache` が優先される。
+   *
+   * @example
+   * // Before（スプレッドが必要だった）
+   * const cms = createCMS({ ...nodePreset({ ttlMs: 5 * 60_000 }), dataSources });
+   *
+   * // After
+   * const cms = createCMS({ dataSources, preset: "node", ttlMs: 5 * 60_000 });
+   */
+  preset?: "node" | "disabled";
+  /**
+   * SWR キャッシュの有効期間（ミリ秒）。`preset` と組み合わせて使用する。
+   * `cache` オブジェクトを直接渡す場合は `cache.ttlMs` を使用すること。
+   *
+   * @example
+   * const cms = createCMS({ dataSources, preset: "node", ttlMs: 5 * 60_000 });
+   */
+  ttlMs?: number;
+  /** レンダラー関数。未指定時は @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 | null>;
+  revalidate(scope: InvalidateScope): 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): Promise<void>;
+  /** Web Standard なルーティングハンドラ (画像プロキシ / webhook) を生成する。 */
+  $handler(opts?: HandlerOptions): (req: Request) => Promise<Response>;
+  /** ハッシュキーでキャッシュ画像を取得する。 */
+  $getCachedImage(hash: string): ReturnType<ImageCacheAdapter["get"]>;
+}
+/**
+ * 複数の DataSource を束ねた CMS クライアントを生成する。
+ *
+ * @example
+ * // Node.js（preset を使った簡潔な記法）
+ * const cms = createCMS({ dataSources: cmsDataSources, preset: "node", ttlMs: 5 * 60_000 });
+ *
+ * @example
+ * // 従来の spread パターン（引き続き動作する）
+ * const cms = createCMS({ ...nodePreset({ ttlMs: 5 * 60_000 }), dataSources: cmsDataSources });
+ *
+ * @example
+ * // キャッシュを細かく指定する場合
+ * const cms = createCMS({
+ *   dataSources,
+ *   cache: { document, image, ttlMs: 60_000 },
+ * });
+ */
+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
+//#region src/preset-node.d.ts
+/** `nodePreset()` のオプション。 */
+interface NodePresetOptions {
+  /**
+   * キャッシュ設定。
+   * - 省略時: memoryDocumentCache + memoryImageCache をデフォルト有効化
+   * - `"disabled"`: キャッシュを完全無効化
+   * - オブジェクト: 任意の cache adapter を差し込む
+   */
+  cache?: CacheConfig | "disabled";
+  /** SWR の TTL (ミリ秒)。`cache` をオブジェクトで渡した場合はそちらが優先される。 */
+  ttlMs?: number;
+  /** カスタムレンダラー。未指定時は core が @notion-headless-cms/renderer を動的ロード。 */
+  renderer?: RendererFn;
+}
+/**
+ * Node.js ランタイム向けの `createCMS` オプションプリセット。
+ * メモリキャッシュをデフォルト有効にした `{ cache, renderer }` を返す。
+ *
+ * @example
+ * import { createCMS, nodePreset } from "@notion-headless-cms/core";
+ * import { cmsDataSources } from "./generated/cms-schema";
+ *
+ * const cms = createCMS({
+ *   ...nodePreset({ ttlMs: 5 * 60_000 }),
+ *   dataSources: cmsDataSources,
+ * });
+ */
+declare function nodePreset(opts?: NodePresetOptions): Pick<CreateCMSOptions, "cache" | "renderer">;
+//#endregion
+export { type AdjacencyOptions, type BaseContentItem, type CMSClient, CMSError, type CMSErrorCode, type CMSErrorContext, type CMSGlobalOps, type CMSHooks, type CMSPlugin, type CMSSchema, type CMSSchemaProperties, type CacheConfig, 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, type ItemWithContent, type Logger, type MaybePromise, type MemoryDocumentCacheOptions, type MemoryImageCacheOptions, type NodePresetOptions, 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, nodePreset, noopDocumentCache, noopImageCache, sha256Hex, withRetry };
+//# sourceMappingURL=index.d.mts.map