@omnixdp/delivery

TypeScript SDK for the Omni xDP Delivery Content API.

The package wraps the read-only /v1/delivery/:spaceSlug/:environmentSlug/... API with request builders, response parsing, typed data shapes, and a small fetch client that works in browsers, Next.js Client Components, and React Server Components.

Install

npm install @omnixdp/delivery

Create a client

import { createDeliveryClient } from "@omnixdp/delivery";

const delivery = createDeliveryClient({
  baseUrl: "https://api.example.com/v1",
  deliveryToken: process.env.OMNIXDP_DELIVERY_TOKEN!,
  spaceSlug: "marketing",
  environmentSlug: "prod"
});

baseUrl can be either the API host root or the /v1 root. The SDK normalizes both forms.

Environment variables

For Next.js and similar apps, the SDK can create a client from Omni xDP Delivery environment variables:

import { createDeliveryClientFromEnv } from "@omnixdp/delivery";

export const delivery = createDeliveryClientFromEnv();

The helper reads these variables:

• NEXT_PUBLIC_OMNIXDP_API_URL or OMNIXDP_API_URL
• NEXT_PUBLIC_OMNIXDP_DELIVERY_TOKEN or OMNIXDP_DELIVERY_TOKEN
• NEXT_PUBLIC_OMNIXDP_CMS_SPACE or OMNIXDP_CMS_SPACE
• NEXT_PUBLIC_OMNIXDP_CMS_ENVIRONMENT or OMNIXDP_CMS_ENVIRONMENT

When both public and private variants are set, the NEXT_PUBLIC_OMNIXDP_* value takes precedence. Use public variables only when the Delivery token and content are intentionally public; otherwise keep private OMNIXDP_* variables in server code.

React Server Components

Keep delivery tokens on the server when possible. The token may be a callback so you can resolve it from server-only configuration at request time.

import { createDeliveryClient, type DeliveryEntry } from "@omnixdp/delivery";

type ArticleFields = {
  title: string;
  slug: string;
  summary?: string;
};

const delivery = createDeliveryClient({
  baseUrl: process.env.OMNIXDP_API_URL!,
  deliveryToken: () => process.env.OMNIXDP_DELIVERY_TOKEN!,
  spaceSlug: "marketing",
  environmentSlug: "prod"
});

export default async function ArticlePage({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const article: DeliveryEntry<ArticleFields> = await delivery.getEntryBySlug("article", slug, {
    language: "en-US",
    references: ["author"],
    fields: ["this.title", "this.slug", "author.name"],
    expand: ["this.updatedAt", "this.language", "author.updatedAt"],
    fetchOptions: {
      next: { revalidate: 60 }
    }
  });

  return <h1>{article.publishedData.title}</h1>;
}

Client Components

Only use a delivery token in a Client Component when that token is intentionally public for the target environment.

"use client";

import { createDeliveryClient } from "@omnixdp/delivery";

const delivery = createDeliveryClient({
  baseUrl: process.env.NEXT_PUBLIC_OMNIXDP_API_URL!,
  deliveryToken: process.env.NEXT_PUBLIC_OMNIXDP_DELIVERY_TOKEN!,
  spaceSlug: process.env.NEXT_PUBLIC_OMNIXDP_CMS_SPACE!,
  environmentSlug: process.env.NEXT_PUBLIC_OMNIXDP_CMS_ENVIRONMENT!
});

export async function loadArticles() {
  return delivery.listEntries("article", {
    page: 1,
    limit: 10,
    search: "launch",
    filters: {
      category: "press"
    },
    taxonomy: {
      main_navigation: ["term_1", "term_2"]
    },
    fields: ["this.title", "this.summary"],
    expand: ["this.publishedAt"]
  });
}

Methods

• listEntries(contentTypeApiId, options)
• getEntryById(contentTypeApiId, entryId, options)
• getEntryBySlug(contentTypeApiId, slug, options)
• getEntryByUrl(contentTypeApiId, url, options)
• getEntriesByIds(contentTypeApiId, ids, options)
• getEntriesBySlugs(contentTypeApiId, slugs, options)
• getTaxonomy(taxonomyTypeApiId, taxonomyId, options)
• getTaxonomyTermById(taxonomyTypeApiId, taxonomyId, termId, options)
• batchGetTaxonomyTermsById(taxonomyTypeApiId, taxonomyId, ids, options)

Common entry options include language, references, fields, expand, descendants, ascenders, spaceSlug, environmentSlug, and fetchOptions. language accepts one language code or an array of language codes. fields accepts selectors such as this.title, this.seo.meta_description, this.taxonomySelections, author.name, or author.taxonomySelections for fields inside requested references. For referenced DataTree fields, select node data with <referenceName>.<dataTreeField>.nodes.<fieldName>, for example rr_bank.reviews.nodes.date. expand controls optional system metadata with scoped selectors: use this.updatedAt for entry metadata and <referenceName>.updatedAt for requested reference metadata. Entry system fields include publishedVersion, publishedAt, updatedAt, language, and contentType; reference objects always include id and data, with other system fields expanded on demand. Referenced DataTree nodes always include id and data; expand children or __fieldMeta with selectors such as rr_bank.reviews.nodes.__fieldMeta. DataTree aggregation is expanded with selectors such as rr_bank.reviews.aggregation.likes.sum, rr_bank.reviews.aggregation.likes (both sum and average), or rr_bank.reviews.aggregation (all aggregation fields).

Use descendants to limit a referenced DataTree response to selected nodes and their full subtrees. Each selector uses <referenceName>.<dataTreeField>.<nodeId>, for example rr_bank.reviews.4dc8a660-6114-44f6-a8a4-cce967feb809. Use ascenders with <referenceName>.<dataTreeField> to add a parents array next to nodes; parents are returned from root to direct parent for the node IDs selected through descendants, without their children, and with the same node field selection applied.

List requests also support page, limit, sort, search, filters, and taxonomy. sort accepts updatedAt, id, or a top-level content field API identifier that is enabled for the Delivery API and marked Sortable on the content type; prefix the value with - for descending order, for example sort: "-date". Field filters are serialized as filter.<fieldApiIdentifier> query parameters. Taxonomy filters are serialized as taxonomy.<taxonomyApiIdentifier> query parameters and accept a term ID or an array of term IDs.

Delivery entry publishedData.taxonomySelections is keyed by taxonomy API identifier:

{
  "main_navigation": {
    "id": "taxonomy_123",
    "terms": ["term_123"]
  }
}

When fields is supplied, include this.taxonomySelections to keep taxonomy selections on the entry payload, or <referenceName>.taxonomySelections to keep them on a requested CMS reference.

getTaxonomy, getTaxonomyTermById, and batchGetTaxonomyTermsById also support language, references, fields, expand, descendants, ascenders, spaceSlug, environmentSlug, and fetchOptions. Taxonomy fields selectors apply to term data with entry-style syntax such as this.title, this.slug, this.url, or this.seo.meta_description; reference selectors such as author.name apply to objects requested through references. Taxonomy expand uses this.* for taxonomy metadata on tree requests (this.taxonomyType, this.language, this.updatedAt), term.* for term metadata (term.names, term.version), and <referenceName>.* for referenced object metadata. descendants and ascenders apply to requested BO/RR references the same way they do on entry routes.

getTaxonomy returns each taxonomy term as a tree node with id, title, data, and children by default. getTaxonomyTermById and batchGetTaxonomyTermsById return flat term payloads with the same term id, title, data, optional references, and requested term.* metadata, but without descendants or children. Term slug and url are regular Delivery API fields inside data when those taxonomy type fields have Delivery API enabled.

Generated response types

Use @omnixdp/typegen to regenerate exact content response types after content types or taxonomy types change in the admin.

npx omnixdp-typegen \
  --api-url https://api.example.com \
  --management-token "$OMNIXDP_MANAGEMENT_TOKEN" \
  --cms-space marketing \
  --out src/omnixdp.generated.ts

Then bind the generated client alias to the delivery client:

import { createDeliveryClientFromEnv, createTypedDeliveryClient } from "@omnixdp/delivery";
import type { CmsDeliveryClient } from "./omnixdp.generated";

const delivery: CmsDeliveryClient = createTypedDeliveryClient(createDeliveryClientFromEnv());

const article = await delivery.getEntryBySlug("article", "hello-world", {
  fields: ["this.title"],
  expand: ["this.updatedAt"]
});
article.publishedData.title;

Passing CmsDeliveryOptions narrows contentTypeApiId, taxonomyTypeApiId, and option selectors for listEntries, getEntryById, getEntryBySlug, getEntryByUrl, getEntriesByIds, getEntriesBySlugs, getTaxonomy, getTaxonomyTermById, and batchGetTaxonomyTermsById. For example, fields, references, filters, taxonomy, sort, and expand values are checked against the generated CMS schema.

Request and response helpers

Use the lower-level helpers when you need to integrate with your own fetch layer.

import { buildDeliveryRequest, parseDeliveryResponse } from "@omnixdp/delivery";

const request = buildDeliveryRequest({
  baseUrl: "https://api.example.com",
  deliveryToken: "dlv_...",
  spaceSlug: "marketing",
  environmentSlug: "prod",
  resourceApiIdentifier: "article",
  pathSegments: ["entry", "slug", "hello-world"]
});

const response = await fetch(request.url, request.init);
const entry = await parseDeliveryResponse(response);

Failed Delivery API responses throw DeliveryApiError with status, code, details, and the parsed response body when available.