@orizm/cli 3.1.0 → 3.3.0-beta.0

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

@@ -0,0 +1,603 @@
+<!-- source: docs/src/app/features/consumer-sdk/fetch-contents/page.mdx -->
+
+# コンテンツの取得
+
+Consumer SDKを使用したコンテンツ取得の方法を説明します。このドキュメントでは以下の内容を解説します。
+
+## 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` オプションで制御します。  
+デフォルトは `false` で、公開されているコンテンツのみ取得します。
+
+下書きコンテンツを取得するには、`draft` オプションを `true` に設定します。
+
+> [!WARNING]
+> 下書きコンテンツ取得の権限を持った Consumer API Key を使用する必要があります。
+> Consumer API Key は、開発者コンソールで生成できます。詳細は
+> [APIキーの生成](../console/generate-api-key.md#consumer-api-key)
+> を参照してください。
+
+```ts copy
+const data = await client.tables.blog.get(id, {
+  draft: true,
+});
+```
+
+### fetchのオプション設定
+
+パラメータで `RequestInit` を指定できます。
+
+例えば、Next.js App Router で `revalidateTag()` を使用するために fetch リクエストにタグを付けたい場合は以下のように設定できます。
+
+```ts copy {6-8}
+const data = await client.tables.blog.get(
+  id,
+  {
+    include: { category: true },
+  },
+  {
+    next: { tags: ["blog", `blog-${id}`] },
+  },
+);
+```
+
+## ユニークキーによる検索
+
+ユニークキーを使用してデータを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` オプションで制御します。  
+デフォルトは `false` で、公開されているコンテンツのみ取得します。
+
+下書きコンテンツを取得するには、`draft` オプションを `true` に設定します。
+
+> [!WARNING]
+> 下書きコンテンツ取得の権限を持った Consumer API Key を使用する必要があります。
+> Consumer API Key は、開発者コンソールで生成できます。詳細は
+> [APIキーの生成](../console/generate-api-key.md#consumer-api-key)
+> を参照してください。
+
+```ts copy
+const data = await client.tables.blog.getByUnique(
+  {
+    slug: "my-first-blog-post",
+  },
+  {
+    draft: false,
+  },
+);
+```
+
+### fetchのオプション設定
+
+パラメータで `RequestInit` を指定できます。
+
+例えば、Next.js App Router で `revalidateTag()` を使用するために fetch リクエストにタグを付けたい場合は以下のように設定できます。
+
+```ts copy {8-10}
+const data = await client.tables.blog.getByUnique(
+  {
+    slug: "my-first-blog-post",
+  },
+  {
+    include: { category: true },
+  },
+  {
+    next: { tags: ["blog", `blog-slug-my-first-blog-post`] },
+  },
+);
+```
+
+## 複数件の検索
+
+複数のコンテンツを取得します。
+
+```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` オプションで制御します。  
+デフォルトは `false` で、公開されているコンテンツのみ取得します。
+
+下書きコンテンツを取得するには、`draft` オプションを `true` に設定します。
+
+> [!WARNING]
+> 下書きコンテンツ取得の権限を持った Consumer API Key を使用する必要があります。
+> Consumer API Key は、開発者コンソールで生成できます。詳細は
+> [APIキーの生成](../console/generate-api-key.md#consumer-api-key)
+> を参照してください。
+
+```ts copy
+const data = await client.tables.blog.list({
+  draft: false,
+});
+```
+
+### fetchのオプション設定
+
+パラメータで `RequestInit` を指定できます。
+
+例えば、Next.js App Router で `revalidateTag()` を使用するために fetch リクエストにタグを付けたい場合は以下のように設定できます。
+
+```ts copy {7-9}
+const data = await client.tables.blog.list(
+  {
+    filter: { category: "book" },
+  },
+  {
+    next: { tags: ["blog"] },
+  },
+);
+```
+
+## 全文検索
+
+> [!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` パラメータは使用できません。検索結果は関連度順で固定されます。
+
+### fetchのオプション設定
+
+パラメータで `RequestInit` を指定できます。
+
+例えば、Next.js App Router で `revalidateTag()` を使用するために fetch リクエストにタグを付けたい場合は以下のように設定できます。
+
+```ts copy {8-10}
+const data = await client.tables.blog.search(
+  {
+    query: "JavaScript",
+  },
+  {
+    next: { tags: ["blog"] },
+  },
+);
+```

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

@@ -0,0 +1,90 @@
+<!-- source: docs/src/app/features/consumer-sdk/install/page.mdx -->
+
+# Consumer SDKのインストール
+
+> [!NOTE]
+> このドキュメントは `@orizm/consumer-sdk` の **v2.6.0-beta.0**
+> に対応しています。プロジェクトにインストールされているバージョンが異なる場合、記載内容と実際の挙動が一致しないことがあります。
+
+Consumer SDKはOrizmのデータにアクセスするためのJavaScriptライブラリです。WebサイトやアプリケーションからOrizmのコンテンツを取得する際に使用します。
+
+## Consumer SDKとは
+
+Consumer SDKは `@orizm/consumer-sdk` というパッケージ名でNPMレジストリから配布されているJavaScriptライブラリです。
+
+## 導入方法
+
+Consumer SDKは以下のコマンドでインストールできます。
+
+```bash
+pnpm add @orizm/consumer-sdk @orizm/common
+```
+
+## クライアントのセットアップ
+
+Consumer SDKを使用するには、以下の手順でセットアップを行います。
+
+### Consumer API Keyの取得
+
+Consumer API KeyはOrizmのコンテンツにアクセスするための認証キーです。
+
+1. 開発者コンソールにログインしてプロジェクトを開く
+2. **Settings**メニューから**Consumer Keys**を選択
+3. 「新規作成」ボタンをクリックして新しいConsumer Keyを作成
+4. `Description of the key`を入力し、必要に応じて`Allow reading draft content with this key`オプションを有効にする
+   - このオプションを有効にすると、このキーで下書き状態のコンテンツにアクセスできます
+5. `Generate`ボタンをクリックする
+
+### 環境変数の設定
+
+Consumer SDKの設定は環境変数で行います。
+
+環境変数として以下の内容を記述してください。
+`<プロジェクト名>` や `<取得したConsumer API Key>` はそれぞれ取得した値に置き換えてください。
+
+```plaintext copy filename=".env"
+NEXT_PUBLIC_ORIZM_BASE_URL=https://app.orizm.com
+NEXT_PUBLIC_ORIZM_PROJECT=<プロジェクト名>
+ORIZM_CONSUMER_KEY=<取得したConsumer API Key>
+```
+
+### クライアントコードの生成
+
+Consumer SDKを使用するには、プロジェクトのスキーマ情報に基づいたクライアントコードを生成する必要があります。
+
+### クライアントの初期化と使用
+
+生成されたクライアントを使用して、Orizmのデータにアクセスできるようになります。
+
+```typescript
+import { OrizmClient } from "@repo/orizm/client";
+
+// クライアントの初期化
+const serverSideCmsClient = new OrizmClient({
+  orizmRoot: process.env.NEXT_PUBLIC_ORIZM_BASE_URL,
+  project: process.env.NEXT_PUBLIC_ORIZM_PROJECT,
+  consumerKey: process.env.ORIZM_CONSUMER_KEY,
+});
+
+// データの取得例
+async function fetchArticles() {
+  return await serverSideCmsClient.tables.article.list({});
+}
+```
+
+## 設定オプション
+
+### 下書きコンテンツへのアクセス
+
+下書きコンテンツにアクセスする場合は、以下の条件を満たす必要があります：
+
+1. Consumer API Key作成時に`Allow reading draft content with this key`オプションを有効にする
+2. APIリクエスト時にdraftパラメータを指定する
+
+```typescript
+const draftArticles = await client.tables.article.list({ draft: true });
+```
+
+## 関連ドキュメント
+
+- [スキーマについて](../schema/about.md)