@orizm/cli 3.1.0 → 3.2.0

package/dist/docs/features/cms-sdk/fetch-contents.md

@@ -0,0 +1,608 @@
+<!-- source: docs/src/app/features/cms-sdk/fetch-contents/page.mdx -->
+
+# コンテンツの取得
+
+CMS SDKを使用したコンテンツ取得の方法を説明します。このドキュメントでは以下の内容を解説します。
+
+- IDとユニークキーによる単体コンテンツの検索
+- フィルタ、ページネーション、ソートを使った複数コンテンツの検索
+- 全文検索によるコンテンツの検索
+- 履歴データの取得
+- フォーム受信データの取得
+
+## IDによる検索
+
+指定したIDでコンテンツを1件取得します。
+
+```ts copy
+const data = await client.tables.blog.get(id);
+```
+
+### 関連テーブルの取得
+
+関連テーブルのデータを同時に取得する場合は、`include` オプションを使用します。  
+取得したいテーブルを `true` に設定してください。
+
+```ts copy
+const data = await client.tables.blog.get(id, {
+  include: { category: true },
+});
+```
+
+複数の関連テーブルを取得することも可能です。
+
+```ts copy
+const data = await client.tables.blog.get(id, {
+  include: {
+    category: true,
+    publisher: true,
+  },
+});
+```
+
+関連テーブルのネストも可能です。  
+`relatedArticle` テーブルの `article` フィールドを取得する場合は以下のように記述します。
+
+```ts copy
+const data = await client.tables.blog.get(id, {
+  include: {
+    relatedArticle: {
+      article: true,
+    },
+  },
+});
+```
+
+### 公開コンテンツのみの取得
+
+下書きコンテンツを含めるかは `draft` オプションで制御します。  
+デフォルトは `true` で、下書きコンテンツも含めて取得します。
+
+公開コンテンツのみを取得するには、`draft` オプションを `false` に設定します。
+
+```ts copy
+const data = await client.tables.blog.get(id, {
+  draft: false,
+});
+```
+
+## ユニークキーによる検索
+
+ユニークキーを使用してデータを1件取得します。
+
+```ts copy
+const data = await client.tables.blog.getByUnique({
+  slug: "my-first-blog-post",
+});
+```
+
+### 関連テーブルの取得
+
+関連テーブルのデータを同時に取得する場合は、`include` オプションを使用します。
+
+```ts copy
+const data = await client.tables.blog.getByUnique(
+  {
+    slug: "my-first-blog-post",
+  },
+  {
+    include: { category: true },
+  },
+);
+```
+
+詳細は [関連テーブルの取得](#関連テーブルの取得) を参照してください。
+
+### 公開コンテンツのみの取得
+
+下書きコンテンツを含めるかは `draft` オプションで制御します。  
+デフォルトは `true` で、下書きコンテンツも含めて取得します。
+
+公開コンテンツのみを取得するには、`draft` オプションを `false` に設定します。
+
+```ts copy
+const data = await client.tables.blog.getByUnique(
+  {
+    slug: "my-first-blog-post",
+  },
+  {
+    draft: false,
+  },
+);
+```
+
+## 複数件の検索
+
+複数のコンテンツを取得します。
+
+```ts copy
+const data = await client.tables.blog.list({});
+```
+
+### フィルタ
+
+`filter` パラメータを使用して、特定の条件に一致するコンテンツを取得します。
+
+`slug` が `my-first-blog-post` のブログ記事を取得する例を以下に示します。
+
+```ts copy
+const data = await client.tables.blog.list({
+  filter: {
+    slug: "my-first-blog-post",
+  },
+});
+```
+
+#### 一致
+
+`slug` が `my-first-blog-post` と一致するデータを取得します。
+
+```ts copy
+{
+  slug: "my-first-blog-post",
+}
+```
+
+`=` 演算子を使用して、一致を明示的に指定することも可能です。
+
+```ts copy
+{
+  slug: { "=": "my-first-blog-post" },
+}
+```
+
+#### 不一致
+
+`!=` 演算子を使用して、特定の値と一致しないデータを取得します。  
+`slug` が `my-first-blog-post` ではないデータを取得する例を以下に示します。
+
+```ts copy
+{
+  slug: { "!=": "my-first-blog-post" },
+}
+```
+
+#### 大小比較
+
+以下の演算子を使用して、数値や文字列の大小比較を実行できます。
+
+- `<`: より小さい
+- `>`: より大きい
+- `<=`: 以下
+- `>=`: 以上
+
+`price` の値を比較して条件を満たすデータを取得する例を以下に示します。
+
+```ts copy
+// より小さい
+{ price: { "<": 1000 } }
+
+// より大きい
+{ price: { ">": 1000 } }
+
+// 以下
+{ price: { "<=": 1000 } }
+
+// 以上
+{ price: { ">=": 1000 } }
+```
+
+#### IN, NOT IN
+
+`$in` 演算子を使用して、特定の値のリストに一致するデータを取得します。  
+`slug` が `my-first-blog-post` または `my-second-blog-post` のデータを取得する例を以下に示します。
+
+```ts copy
+{
+  slug: { "$in": ["my-first-blog-post", "my-second-blog-post"] },
+}
+```
+
+`$notIn` 演算子を使用して、特定の値のリストに一致しないデータを取得することも可能です。  
+`slug` が `my-first-blog-post` または `my-second-blog-post` ではないデータを取得する例を以下に示します。
+
+```ts copy
+{
+  slug: { "$notIn": ["my-first-blog-post", "my-second-blog-post"] },
+}
+```
+
+#### 文字列の部分一致
+
+文字列の部分一致検索には `$contains` を使用します。  
+`slug` に `my-` を含むデータを取得する例を以下に示します。
+
+```ts copy
+{
+  slug: { "$contains": "my-" },
+}
+```
+
+`$notContains` を使用すると、文字列が含まれないデータを取得できます。  
+`slug` に `my-` を含まないデータを取得する例を以下に示します。
+
+```ts copy
+{
+  slug: { "$notContains": "my-" },
+}
+```
+
+#### AND, OR
+
+オブジェクトに複数のプロパティを指定することで、AND条件でデータを取得できます。  
+`category` が `book` で、`price` が1000以下のデータを取得する例を以下に示します。
+
+```ts copy
+{
+  category: "book",
+  price: { "<=": 1000 },
+}
+```
+
+明示的に `$and` 演算子を使用することも可能です。
+
+```ts copy
+{
+  $and: [
+    { category: "book" },
+    { price: { "<=": 1000 } },
+  ],
+}
+```
+
+`$or` 演算子を使用して、複数の条件をORで結合することも可能です。  
+以下は、`category` が `book` で `price` が1000以下のデータ、または `category` が `movie` のデータを取得する例です。
+
+```ts copy
+{
+  $or: [
+    { category: "book", price: { "<=": 1000 } },
+    { category: "movie" },
+  ],
+}
+```
+
+ANDやORをネストすることも可能です。  
+以下は、`category` が `book` で `price` が1000以下のデータ、または `category` が `movie` のデータを取得する例です。
+
+```ts copy
+{
+  $or: [
+    { $and: [{ category: "book" }, { price: { "<=": 1000 } }] },
+    { category: "movie" },
+  ],
+}
+```
+
+#### 関連テーブルのフィルタ
+
+関連テーブルのフィルタリングも可能です。
+`relatedArticle` テーブルの `article` フィールドが `my-first-blog-post` のデータを取得する場合は以下のように記述します。
+
+```ts copy
+{
+  relatedArticle: {
+    article: { slug: "my-first-blog-post" },
+  },
+}
+```
+
+#### module-array のフィルタ
+
+[テーブルモジュール](../schema/table-module.md) の `module-array` 型カラムに対して、配列要素を条件にフィルタリングできます。
+`some`、`every`、`none` の3つの module-array フィルター演算子を使用します。
+
+以下の説明では、次のスキーマを前提とします。
+
+```ts copy filename="orizm.config.ts"
+import { defineConfig } from "@orizm/cli/config";
+
+export default defineConfig({
+  tableModules: {
+    tag: {
+      columns: {
+        name: { type: "string", required: true },
+        priority: { type: "integer" },
+      },
+    },
+  },
+  tables: {
+    article: {
+      columns: {
+        title: { type: "string", required: true },
+        tags: {
+          type: "module-array",
+          moduleName: "tag",
+        },
+      },
+    },
+  },
+});
+```
+
+##### some
+
+少なくとも1つの配列要素が条件を満たすコンテンツを取得します。
+
+`tags` の `priority` が4以上の要素を少なくとも1つ持つ記事を取得する例を以下に示します。
+
+```ts copy
+const data = await client.tables.article.list({
+  filter: {
+    tags: {
+      some: {
+        priority: { ">=": 4 },
+      },
+    },
+  },
+});
+```
+
+##### every
+
+すべての配列要素が条件を満たすコンテンツを取得します。
+
+すべての `tags` の `priority` が3以上の記事を取得する例を以下に示します。
+
+```ts copy
+const data = await client.tables.article.list({
+  filter: {
+    tags: {
+      every: {
+        priority: { ">=": 3 },
+      },
+    },
+  },
+});
+```
+
+##### none
+
+どの配列要素も条件を満たさないコンテンツを取得します。
+
+`name` に `"Script"` を含むタグを持たない記事を取得する例を以下に示します。
+
+```ts copy
+const data = await client.tables.article.list({
+  filter: {
+    tags: {
+      none: {
+        name: { $contains: "Script" },
+      },
+    },
+  },
+});
+```
+
+##### 複合条件
+
+同一の `module-array` カラムに対して、複数の module-array フィルター演算子を同時に指定できます。
+条件はANDで結合されます。
+
+`priority` が4以上のタグを少なくとも1つ持ち、かつ `name` に `"Script"` を含むタグを持たない記事を取得する例を以下に示します。
+
+```ts copy
+const data = await client.tables.article.list({
+  filter: {
+    tags: {
+      some: { priority: { ">=": 4 } },
+      none: { name: { $contains: "Script" } },
+    },
+  },
+});
+```
+
+##### 空オブジェクトの挙動
+
+> [!NOTE]
+>
+> module-array フィルター演算子に空オブジェクト `{}` を渡した場合の挙動は以下の通りです。
+>
+> - `some: {}` - 少なくとも1つの配列要素が存在するコンテンツを取得します
+> - `every: {}` - 条件なし（すべてのコンテンツが該当します）
+> - `none: {}` - 配列要素が1つも存在しないコンテンツを取得します
+>
+
+### ページネーション
+
+取得件数とオフセットを指定してデータを分割取得します。
+
+```ts copy
+const data = await client.tables.blog.list({
+  limit: 10,
+  offset: 0,
+});
+```
+
+`limit` パラメータを指定しない場合、デフォルトで100件まで取得されます。
+
+### ソート
+
+指定したカラムでデータを並び替えます。
+
+```ts copy
+const data = await client.tables.blog.list({
+  order: { createdAt: "desc" },
+});
+```
+
+複数のカラムでソートすることも可能です。
+
+```ts copy
+const data = await client.tables.blog.list({
+  order: { status: "asc", createdAt: "desc" },
+});
+```
+
+複数のカラムを指定した場合、先に指定したカラムから順番にソートされます。
+上記の例では、`status` で昇順ソートした後に `createdAt` で降順ソートします。
+
+### 関連テーブルの取得
+
+関連テーブルのデータを同時に取得する場合は `include` オプションを使用します。
+
+```ts copy
+const data = await client.tables.blog.list({
+  include: { category: true },
+});
+```
+
+詳細は [関連テーブルの取得](#関連テーブルの取得) を参照してください。
+
+### 公開データのみの取得
+
+下書きデータを含めるかは `draft` オプションで制御します。  
+デフォルトは `true` で、下書きデータも含めて取得します。
+
+公開データのみを取得するには、`draft` オプションを `false` に設定します。
+
+```ts copy
+const data = await client.tables.blog.list({
+  draft: false,
+});
+```
+
+## 全文検索
+
+> [!NOTE]
+>
+> テーブルの全文検索機能が有効な場合のみ利用可能です。詳細は [全文検索](../full-text-search.md) を参照してください。
+>
+
+`query` パラメータにキーワードを指定して全文検索を実行します。
+
+```ts copy
+const data = await client.tables.blog.search({
+  query: "JavaScript",
+});
+```
+
+### フィルタ
+
+`search()` メソッドは `list()` メソッドと比較して、`filter` オプションで使用できるパラメータに制約があります。
+
+`filter` パラメータでは `group` のみ使用可能です。  
+以下のようなフィルタは `search()` では使用できません。
+
+```ts
+// ❌ searchメソッドでは使用不可
+const data = await client.tables.blog.search({
+  query: "JavaScript",
+  filter: {
+    status: "published",
+    createdAt: { ">=": "2024-01-01" },
+  },
+});
+
+// ✅ listメソッドでは使用可能
+const data = await client.tables.blog.list({
+  filter: {
+    status: "published",
+    createdAt: { ">=": "2024-01-01" },
+  },
+});
+```
+
+グループによる絞り込みのみ使用できます。
+
+```ts copy
+const data = await client.tables.blog.search({
+  query: "JavaScript",
+  filter: {
+    group: "tech-articles",
+  },
+});
+```
+
+### ソート
+
+`order` パラメータは使用できません。検索結果は関連度順で固定されます。
+
+## 履歴の取得
+
+> [!NOTE]
+>
+> テーブルの履歴管理機能が有効な場合のみ利用可能です。
+> 詳細は [履歴管理](../history.md) を参照してください。
+>
+
+特定のコンテンツの編集履歴を取得します。
+
+```ts copy
+const history = await client.tables.blog.listHistory(id);
+```
+
+### ページネーション
+
+デフォルトでは最新の10件が取得されます。  
+ページネーションパラメータで件数とオフセットを指定できます。
+
+```ts copy
+const history = await client.tables.blog.listHistory(id, {
+  limit: 20,
+  offset: 0,
+});
+```
+
+## フォーム受信データの取得
+
+> [!NOTE]
+>
+> テーブルのフォーム管理機能が有効な場合のみ利用可能です。詳細は [フォーム管理](../form/about.md) を参照してください。
+>
+
+フォームから送信された受信データを取得します。
+
+`submissions()` メソッドでフォームIDを指定し、その後 `list()` メソッドで受信データのリストを取得します。
+
+```ts copy
+const submissions = await client.tables.form.submissions(formId).list({});
+```
+
+### フィルタ
+
+`filter` パラメータを使用して、特定の条件に一致する受信データを取得します。
+
+詳細は [複数件の検索](./fetch-contents.md#複数件の検索) を参照してください。
+
+### ページネーション
+
+```ts copy
+const submissions = await client.tables.form.submissions(formId).list({
+  limit: 20,
+  offset: 0,
+});
+```
+
+`limit` パラメータを指定しない場合、デフォルトで100件まで取得されます。
+
+### ソート
+
+```ts copy
+const submissions = await client.tables.form.submissions(formId).list({
+  order: { createdAt: "desc" },
+});
+```
+
+複数のカラムでソートすることも可能です。
+
+```ts copy
+const submissions = await client.tables.form.submissions(formId).list({
+  order: { status: "asc", createdAt: "desc" },
+});
+```
+
+複数のカラムを指定した場合、先に指定したカラムから順番にソートされます。
+上記の例では、`status` で昇順ソートした後に `createdAt` で降順ソートします。
+
+### 関連テーブルの取得
+
+関連テーブルのデータを同時に取得する場合は `include` オプションを使用します。
+
+```ts copy
+const submissions = await client.tables.form.submissions(formId).list({
+  include: { relatedData: true },
+});
+```
+
+詳細は [関連テーブルの取得](#関連テーブルの取得) を参照してください。

package/dist/docs/features/cms-sdk/install.md

@@ -0,0 +1,98 @@
+<!-- source: docs/src/app/features/cms-sdk/install/page.mdx -->
+
+# CMS SDKのインストール
+
+> [!NOTE]
+> このドキュメントは `@orizm/cms-sdk` の **v2.5.0**
+> に対応しています。プロジェクトにインストールされているバージョンが異なる場合、記載内容と実際の挙動が一致しないことがあります。
+
+CMS SDKは、OrizmのCMS機能をWebサイトに組み込むためのJavaScriptライブラリです。このガイドでは、インストール手順とクライアントセットアップの方法を説明します。
+
+## CMS SDKとは
+
+CMS SDKは `@orizm/cms-sdk` というパッケージ名でNPMレジストリから配布されているJavaScriptライブラリです。
+
+## インストール手順
+
+以下のコマンドでCMS SDKをインストールします：
+
+```bash copy
+pnpm add @orizm/cms-sdk @orizm/common
+```
+
+## クライアントのセットアップ
+
+CMS SDKを使用するには、環境に応じたクライアントのセットアップが必要です。`CMSClient` はスキーマの適用時に自動生成されます。
+
+### サーバーサイドの設定(ユーザーセッション)
+
+サーバー側で使用するクライアントは、NextAuthのセッションを使用して以下のように設定します：
+
+```ts
+import { OrizmNextAuthCMSClient } from "@orizm/cms-sdk/next-auth";
+import { CMSClient } from "@repo/orizm/cms";
+import { getServerSession } from "next-auth";
+import { authOptions } from "../auth/auth-options";
+
+const client = new CMSClient(
+  new OrizmNextAuthCMSClient(
+    {
+      projectName: process.env.NEXT_PUBLIC_ORIZM_PROJECT,
+      baseURL: process.env.NEXT_PUBLIC_ORIZM_BASE_URL,
+    },
+    async () => await getServerSession(authOptions),
+  ),
+);
+```
+
+認証設定について詳しくは、[CMS SDKの認証](./auth.md) のページを参照してください。
+
+### サーバーサイドの設定(Management API Key)
+
+#### Management API Keyの設定
+
+以下の手順で取得し設定します：
+
+1. 開発者コンソールにログインする
+2. プロジェクトのトップページを開く
+3. `Settings`メニューに移動する
+4. `API Keys` から `Management API Keys`を選択する
+5. `Description of the key` を入力し、`Generate`ボタンをクリックする
+6. 生成された `Management API Key`をコピーする
+7. 環境変数`ORIZM_API_KEY`に値を設定する
+
+#### クライアントの設定
+
+```ts
+import { OrizmCMSClient_ManagementKey } from "@orizm/cms-sdk";
+import { CMSClient } from "@repo/orizm/cms";
+
+const client = new CMSClient(
+  new OrizmCMSClient_ManagementKey({
+    projectName: process.env.NEXT_PUBLIC_ORIZM_PROJECT,
+    baseURL: process.env.NEXT_PUBLIC_ORIZM_BASE_URL,
+    managementKey: process.env.ORIZM_API_KEY,
+  }),
+);
+```
+
+### クライアントサイドの設定
+
+ブラウザ側で使用するクライアントは、以下のように設定します：
+
+```ts
+import { OrizmNextAuthCMSClient } from "@orizm/cms-sdk/next-auth";
+import { CMSClient } from "@repo/orizm/cms";
+
+const client = new CMSClient(
+  new OrizmNextAuthCMSClient(
+    {
+      projectName: process.env.NEXT_PUBLIC_ORIZM_PROJECT,
+      baseURL: process.env.NEXT_PUBLIC_ORIZM_BASE_URL,
+    },
+    async () => getSession(),
+  ),
+);
+```
+
+これで、CMS SDKのセットアップは完了です。