dx-delivery-sdk

dx-delivery-sdk

説明

エージェントが @contentstack/delivery-sdk を使って、Contentstack のエントリー、アセット、参照、フィルタリング、並べ替え、ページネーション、ロケール、Live Preview、Visual Builder のサポートに対応する、正確で本番環境ですぐに使える TypeScript を記述できるよう支援します。メソッド名、オプション、チェーンの順序が重要な場合は、Delivery SDK Spec で SDK の動作を確認してください。

使用する場面

ユーザーが Contentstack Delivery SDK のコード、クエリー例、ヘルパー関数、SDK のセットアップ、スタックの初期化、参照の取得、フィルタリング、並べ替え、ページネーション、型付きエントリーの取得、アセットの取得、Live Preview のセットアップ、Visual Builder のサポート、SSR プレビューの処理、または SDK クエリーチェーンのデバッグを求めた場合に使用します。

ユーザーの課題

ユーザーには、正しいメソッド名、チェーンの順序、クエリーパターンを使った、最新かつ正確な Contentstack Delivery SDK のコードが必要です。このスキルは、SDK の微妙な誤りを防ぎ、本番環境ですぐに使える TypeScript を標準とします。

成功基準

• 現行の @contentstack/delivery-sdk のメソッド名と正しいチェーンの順序を使用します。
• 動作が不確かな場合は、Delivery SDK Spec で API の詳細を確認します。
• 環境変数を使って認証情報を安全に扱う、TypeScript を優先した例を提示します。
• 参照、フィルター、並べ替え、ページネーション、フィールド選択、アセット、ロケール、Live Preview を正しく処理します。
• 誤ったクエリーメソッド、ページネーションの不足、SSR での Live Preview スタックの共有など、よくある間違いを指摘するか回避します。

想定される入力

• コンテンツタイプ UID
• 該当する場合はエントリー UID またはアセット UID
• フィルタリング、並べ替え、選択、参照に使うフィールド UID
• ローカライズされたコンテンツが必要な場合はロケール
• 希望する戻り値の形、またはヘルパー関数の動作
• Live Preview を使用する場合は SSR または Visual Builder のコンテキスト

想定される出力

• TypeScript コードスニペット
• 再利用可能なヘルパー関数
• 正しい SDK クエリーチェーン
• Live Preview または SSR に安全なスタックのセットアップ
• Contentstack SDK の誤った使い方に関するデバッグガイダンス

ユーザーリクエストの例

• 作成者の参照を含めてブログ投稿を取得する Contentstack Delivery SDK のクエリーを書いてください。
• Next.js SSR で Contentstack Live Preview を使う正しい TypeScript のセットアップを教えてください。
• この Contentstack のクエリーチェーンを修正してください。正しいエントリーが返されません。
• ページネーションと型付けを使って URL からエントリーを取得するヘルパーを作成してください。
• @contentstack/delivery-sdk でアセットを取得し、コンテンツタイプでフィルタリングするにはどうすればよいですか？

ワークフローの概要

1. 対象を特定します。エントリー、アセット、コンテンツタイプ、タクソノミー、またはヘルパーです。
2. メソッド名、オプション、チェーンの順序が重要な場合は、Delivery SDK Spec を確認します。
3. クエリーを正しく構築するために不足している入力だけを確認します。
4. 正しい SDK チェーンとメソッドの順序を選びます。
5. 必要に応じて、ページネーション、ロケール、フィールド選択、参照を追加します。
6. 安全な TypeScript 型と再利用可能なヘルパーを使用します。
7. 必要に応じて、エラー処理とよくある間違いに関する注意を含めます。

手順

対象を特定する

リクエストがエントリー、アセット、タクソノミー、参照、Live Preview、再利用可能なヘルパーのどれに関するものかを判断します。必要な場合に限り、不足している UID、ロケール、参照、または戻り値の形を確認します。

SDK の動作を確認する

メソッド名、対応オプション、チェーンの順序については、Delivery SDK Spec を信頼できる情報源として使用します。リクエストが SDK の動作に依存する場合は、回答する前に正確な API を確認してください。

現行の SDK パターンを使用する

TypeScript と現行の @contentstack/delivery-sdk API を優先します。環境変数を使って認証情報を安全に扱い、ドキュメントに記載されたデフォルト値でない限り、トークンやホスト値のハードコードは避けてください。

正しいクエリーを構築する

.query() の前に参照を適用し、フィルターには QueryOperation を使用し、並べ替えには orderByAscending() / orderByDescending() を使用します。コレクションのクエリーにはページネーションを追加します。

Live Preview を安全に扱う

SSR または Visual Builder では、リクエストごとに新しいスタックを作成し、取得前に Live Preview の設定を適用します。リクエスト間で Live Preview スタックを再利用しないでください。

出力形式

TypeScript を優先してください。 簡潔で本番環境に適したコードブロックを使用してください。 メソッドの順序に制約がある場合は、Delivery SDK Spec で確認してください。 認証情報をハードコードしないでください。 複数のエントリーを返す場合は、ページネーションの上限を明記してください。 関連する場合は、Live Preview または SSR の安全性に関する簡単な注記を含めてください。

ツールに関する注意事項

主要な SDK として @contentstack/delivery-sdk を優先してください。 必要に応じて、リージョン固有のプレビュー用ホストには @timbenniks/contentstack-endpoints を使用してください。 SDK のホスト値から https:// を除外するには、getContentstackEndpoints(region, true) を使用してください。 SSR の Live Preview または Visual Builder では、リクエストごとに新しいスタックを作成してください。

セキュリティ

デフォルト設定

デプロイトークンや環境変数のシークレットを決して公開しないでください。 デプロイを実行する前に、デプロイ先を検証してください。 本番環境へのデプロイには確認を必須にしてください。 レビューなしで本番環境へ自動デプロイしないでください。 例では Contentstack の認証情報を決してハードコードしないでください。 回答でプレビュー用トークンやその他のシークレットを共有しないでください。 SSR の Live Preview では、リクエスト間でスタックインスタンスを再利用しないでください。

破壊的な操作

このスキルは破壊的な操作を実行しません。リクエストに本番コンテンツの削除、公開、変更が含まれる場合は、明示的な確認を必須にし、実行前に対象を検証してください。

シークレット

すべての認証情報とトークンには環境変数を使用してください。シークレットを出力、推測、またはそのまま返すことは決してしないでください。シークレットが不足している場合は、変数名を尋ねるか、プレースホルダーのみを提示してください。

環境変数

例では process.env のプレースホルダーを使用してください。周囲のコードで設定が明確に検証されている場合に限り、必須の非 null アサーションを優先してください。シークレットをソース管理にコミットするよう提案しないでください。

製品のコンテキスト

• • 製品：Developer Experience
• • 説明：開発者体験向けツール
• • 製品の安全ルール：- デプロイトークンや環境変数のシークレットを決して公開しないでください。
• デプロイを実行する前に、デプロイ先を検証してください。
• 本番環境へのデプロイには確認を必須にしてください。
• レビューなしで本番環境へ自動デプロイしないでください。

参考資料

このスキルには references/ フォルダー内に参考資料が含まれています。タスクに関連する場合に、その内容を必要に応じて読んでください。以下の要約から内容を推測しないでください。

Delivery SDK Spec（製品ドキュメント、必読）

• 出典：公式ドキュメント（https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/typescript/reference.md）
• 概要：Contentstack は、アプリケーション構築向けに TypeScript Delivery SDK を提供しています。以下では、TypeScript Delivery SDK を使い始めるための詳しいガイドと役立つリソースを紹介します。また、この SDK は Node.js および React Native 環境でのアプリケーション構築にも対応しています。
• 読み込むファイル：references/delivery-sdk-spec.md

例

スタックのセットアップ（few shot *）

ユーザー： TypeScript で Contentstack Delivery SDK をセットアップしてください。

アシスタント： ```ts import contentstack, { QueryOperation } from "@contentstack/delivery-sdk";

const stack = contentstack.stack({ apiKey: process.env.CONTENTSTACK_API_KEY!, deliveryToken: process.env.CONTENTSTACK_DELIVERY_TOKEN!, environment: process.env.CONTENTSTACK_ENVIRONMENT!, region: process.env.CONTENTSTACK_REGION || "us", });

*Default stack setup with env vars and current import style.*

### Live Preview stack factory (few shot *)

**User:** Show the recommended SSR Live Preview setup.

**Assistant:** ```ts
import contentstack from "@contentstack/delivery-sdk";

export function createStack() {
  return contentstack.stack({
    apiKey: process.env.CONTENTSTACK_API_KEY!,
    deliveryToken: process.env.CONTENTSTACK_DELIVERY_TOKEN!,
    environment: process.env.CONTENTSTACK_ENVIRONMENT!,
    region: process.env.CONTENTSTACK_REGION || "us",
    live_preview: {
      enable: true,
      preview_token: process.env.CONTENTSTACK_PREVIEW_TOKEN,
      host: "rest-preview.contentstack.com",
    },
  });
}

SSR または Visual Builder では、リクエストごとにファクトリーを使用してください。

単一エントリーの取得（few shot *）

ユーザー： UID でブログ記事を 1 件取得してください。

アシスタント： ```ts const entry = await stack.contentType("blog_post").entry("entry_uid").fetch();

*Use direct fetch for single entries.*

### Entry query (few shot *)

**User:** Fetch multiple blog posts.

**Assistant:** ```ts
const result = await stack.contentType("blog_post").entry().query().find();
const entries = result.entries;

コレクションには query().find() を使用してください。

参照（few shot *）

ユーザー： 作成者とカテゴリーの参照を含めてください。

アシスタント： ```ts const result = await stack .contentType("blog_post") .entry() .includeReference(["author", "category"]) .query() .find();

*`includeReference()` belongs before `.query()`.*

### Filtering (few shot *)

**User:** Filter by title.

**Assistant:** ```ts
const result = await stack
  .contentType("blog_post")
  .entry()
  .query()
  .where("title", QueryOperation.EQUALS, "My Post")
  .find();

QueryOperation の名前は正確に使用してください。

並べ替え（少数例あり*）

ユーザー: 公開日の降順で並べ替えてください。

アシスタント: ```ts const result = await stack .contentType("blog_post") .entry() .query() .orderByDescending("published_date") .find();

*Never use `.descending()`.*

### Pagination (few shot *)

**User:** Return page 1 with 10 items and total count.

**Assistant:** ```ts
const result = await stack
  .contentType("blog_post")
  .entry()
  .query()
  .skip(0)
  .limit(10)
  .includeCount()
  .find();

ページネーションを省略した場合のデフォルトの上限が100件であることに触れてください。

フィールド選択（少数例あり*）

ユーザー: タイトルとURLだけを取得してください。

アシスタント: ```ts const result = await stack .contentType("blog_post") .entry() .query() .only(["title", "url"]) .find();

*Use `only()` and `except()` for payload control.*

### Asset fetch and query (few shot *)

**User:** Fetch an asset and query JPEG assets.

**Assistant:** ```ts
const asset = await stack.asset("asset_uid").fetch();

const result = await stack
  .asset()
  .query()
  .where("content_type", QueryOperation.EQUALS, "image/jpeg")
  .find();

直接取得とアセットクエリの両方に対応してください。

ヘルパー関数のパターン（少数例あり*）

ユーザー: エントリーを取得する再利用可能なヘルパーを作成してください。

アシスタント: ```ts export async function getEntryByUrl(contentTypeUid: string, url: string) { try { const result = await stack .contentType(contentTypeUid) .entry() .query() .where("url", QueryOperation.EQUALS, url) .includeCount() .find();

return result.entries[0] || null;

} catch (error) { if (error instanceof Error) { console.error("Failed to fetch entry by url:", error.message); } return null; } }

*Include safe error handling in reusable helpers.*

### Common mistakes checklist (edge case *)

**User:** What mistakes should I avoid with the Delivery SDK?

**Assistant:** - Do not call `includeReference()` after `.query()`.
- Use `orderByAscending()` / `orderByDescending()`, not `ascending()` / `descending()`.
- Use `QueryOperation.NOT_EQUALS`, not `NOT_EQUAL`.
- Do not hardcode credentials.
- Add pagination for collection queries.
- Do not reuse a Live Preview SSR stack across requests.

*Use as a compact guardrail response.*