MonochromeMemory.Notion 5.1.3

MonochromeMemory.Notion

Notion DB を型付きクラスで扱うための軽量ラッパー。

インストール/依存

• .NET 8
• NuGet: MonochromeMemory.ResultSharp 1.0.0

できること

• モデルクラスにカラム名属性を付けて Notion DB を CRUD。
• Notion API の生 PropertyValue を意識せず、INotionRepository<T> を通じて利用。

使い方（最小例）

public class TaskPage : DatabasePage
{
    [DatabasePropertyType(NotionPropertyType.Title)]
    [DatabaseColumnName("Name")]
    public string Title { get; set; } = string.Empty;

    [DatabasePropertyType(NotionPropertyType.Checkbox)]
    [DatabaseColumnName("Done")]
    public bool Done { get; set; }
}

// DI 等で組み立て
using var httpClient = new HttpClient();
var client = new NotionApiClient(httpClient, new NotionApiClientOptions { AuthToken = token });
var mapper = new PropertyValueMapper();
var repo = new NotionRepository<TaskPage>(dataSourceId, client, mapper);

var created = await repo.CreateAsync(new TaskPage { Title = "やること", Done = false });
if (created.TryGetValue(out var page))
{
    var fetched = await repo.GetAsync(page.Id!);
    // fetched.TryGetValue(...) で取り出す
}

※ dataSourceId は Notion Database の data_sources[0].id を使用します。

サンプルプロジェクト

• パス: MonochromeMemory.Notion.Sample
• 必要な環境変数: NOTION_TOKEN, NOTION_DATA_SOURCE_ID
• 必要なカラム: Name(Title), Done(Checkbox), Score(Number), Tags(Select/MultiSelect/Status), Due(Date), Files(Files), Rel(Relation)
• 実行: dotnet run --project MonochromeMemory.Notion.Sample

E2E テスト（実 API）

• プロジェクト: MonochromeMemory.Notion.E2ETests
• 対象: INotionApiClient の実装済み API（Pages/DataSources/Databases）+ ページングや filter_properties などの追加パス
• 実行ごとに新規 DB を作成し、必要データを投入して検証します。終了時は archived=true で後始末します（Notion-Version: 2025-09-03）。
• API キーは dotnet test の引数で指定します（TestRunParameters）。
• GitHub Actions の通常CIでは実行しません（MonochromeMemory.Notion.Tests のみ実行）。

PowerShell 例:

dotnet test MonochromeMemory.Notion.E2ETests --filter "TestCategory=E2E" -- `
  TestRunParameters.Parameter(name="NotionApiKey", value="secret_xxx") `
  TestRunParameters.Parameter(name="NotionParentPageId", value="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

bash 例:

dotnet test MonochromeMemory.Notion.E2ETests --filter "TestCategory=E2E" -- \
  'TestRunParameters.Parameter(name="NotionApiKey", value="secret_xxx")' \
  'TestRunParameters.Parameter(name="NotionParentPageId", value="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")'

補足:

• NotionParentPageId は省略可能です。未指定時は POST /v1/search でアクセス可能な page から自動解決します。
• E2E は 3 req/s 制限を超えないよう約 350ms 間隔で API を実行します。
• フィルター型の網羅は Title/RichText/Url/Email/Phone/Number/Checkbox/Date/Select/MultiSelect/Relation を毎回検証します。Status は Notion API 側で新規作成制約があるため、対象 DataSource に存在する場合のみ検証します。

制約と備考

• 添付は External URL（Files に List<FileEntry> をマップ）に対応。アップロード型は未対応（URL を渡す想定）。
• Date は DateTimeOffset? で開始のみ対応。開始/終了を分けたい場合は同一カラムに 2 プロパティを割り当て、DatabasePropertyTypeAttribute.DateComponent を Start/End で指定。
• Select/Status/MultiSelect/Relation などは DatabasePropertyTypeAttribute で型を指定すると安全。未指定の場合、List<string> が 1 件なら Select、複数なら MultiSelect、カラム名が Relation のとき Relation として扱います。
• クエリ DSL（式木）の未対応: NOT、未サポート演算子（NotContains/Between/IsEmpty など）、未対応型（People/Rollup/Upload Files 等）、型ヒント不足プロパティ、Skip は Err で返します。
• Archive/Unarchive: INotionRepository に ArchiveAsync / UnarchiveAsync を用意（公開 API 上は InTrash の true/false）。送信時は Notion-Version に応じて 2026-03-11 以降では in_trash、それ以前では archived を使用する。クエリで Trash を除外する場合は QueryOptions.SkipTrashed=true を使い、取得結果をクライアント側で除外する。

モデル自動生成 CLI（ドラフト）

• プロジェクト: MonochromeMemory.Notion.Tools
• コマンド例: dotnet run --project MonochromeMemory.Notion.Tools -- --db <databaseId> --output src/Generated
• Token: NOTION_TOKEN 環境変数（または --token）
• 生成物: <DbName>Page.g.cs（auto-generated, DatabasePage 継承, DatabaseColumnName/DatabasePropertyType 属性付き）。未対応型は TODO コメントを出力してスキップ。

dataSourceId 取得 CLI

• プロジェクト: MonochromeMemory.Notion.DataSourceIdTool
• コマンド例: dotnet run --project MonochromeMemory.Notion.DataSourceIdTool -- <token> <databaseId>
• 代替: dotnet run --project MonochromeMemory.Notion.DataSourceIdTool -- --db <databaseId> --token <token>
• URL 対応: Notion の database URL 全体をそのまま渡しても、URL 内の database ID を抽出して使える
• Token: NOTION_TOKEN 環境変数でも指定可
• 出力: 先頭の dataSourceId を 1 行だけ標準出力へ出す

ドキュメント

• 設計: docs/design/notion-wrapper.md
• AI コンテキスト: .ai_context/system_spec.yaml, .ai_context/coding_rules.md

設計ドキュメント

• docs/design/notion-wrapper.md