dx-delivery-sdk

Determine whether the request is for entries, assets, taxonomy, references, Live Preview, or a reusable helper. Ask only for missing UIDs, locale, references, or return shape when needed.

Use the Delivery SDK Spec as the source of truth for method names, supported options, and chain order. If the request depends on SDK behavior, confirm the exact API before answering.

Prefer TypeScript and the current @contentstack/delivery-sdk API. Use safe environment-based credentials and avoid hardcoded tokens or host values unless they are documented defaults.

Apply references before .query(), use QueryOperation for filters, use orderByAscending() / orderByDescending() for sorting, and add pagination for collection queries.

For SSR or Visual Builder, create a new stack per request and apply live preview configuration before fetching. Do not reuse a Live Preview stack across requests.

Never expose deployment tokens or environment secrets. Validate deployment targets before triggering. Require confirmation for production deployments. Never auto-deploy to production without review. Never hardcode Contentstack credentials in examples. Avoid sharing preview tokens or other secrets in responses. For SSR Live Preview, do not reuse a stack instance across requests.

This skill does not perform destructive actions. If a request implies deleting, publishing, or mutating production content, require explicit confirmation and verify the target before proceeding.

Use environment variables for all credentials and tokens. Never print, infer, or echo secrets. If a secret is missing, request the variable name or show a placeholder only.

Use process.env placeholders in examples. Prefer required non-null assertions only when the surrounding code clearly validates configuration. Do not suggest committing secrets to source control.

• Source: Official Docs (https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/typescript/reference.md)
• Summary: Contentstack offers the TypeScript Delivery SDK for building applications. Below, is an in-depth guide and valuable resources to initiate your journey with our TypeScript Delivery SDK. Additionally, the SDK supports the creating applications for Node.js and React Native environments.
• Read: references/delivery-sdk-spec.md

User: Set up the Contentstack Delivery SDK in TypeScript.

Assistant: ```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",
    },
  });
}

Per-request factory for SSR or Visual Builder.

User: Fetch one blog post by UID.

Assistant: ```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;

Use query().find() for collections.

User: Include author and category references.

Assistant: ```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();

Use QueryOperation names exactly.

User: Sort by publish date descending.

Assistant: ```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();

Mention the 100-item default limit when pagination is omitted.

User: Only fetch title and url.

Assistant: ```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();

Support both direct fetch and asset queries.

User: Create reusable helpers for fetching entries.

Assistant: ```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.*