From e8ceccf9361040989b1266abf56bf54b29555a52 Mon Sep 17 00:00:00 2001 From: Tim Benniks Date: Wed, 1 Jul 2026 10:53:07 +0200 Subject: [PATCH 1/3] feat: expand Contentstack endpoints with LAUNCH and BRAND_KIT URLs --- __test__/uiLocation.test.ts | 2 ++ src/types/api.type.ts | 42 ++++++++++++++++++++++++++++++++++++- 2 files changed, 43 insertions(+), 1 deletion(-) diff --git a/__test__/uiLocation.test.ts b/__test__/uiLocation.test.ts index f51be413..3796660d 100644 --- a/__test__/uiLocation.test.ts +++ b/__test__/uiLocation.test.ts @@ -65,6 +65,8 @@ const initData: IAppConfigInitData = { CMA: "https://api.contentstack.io", APP: "https://app.contentstack.app", DEVELOPER_HUB: "", + LAUNCH: "https://launch-api.contentstack.com", + BRAND_KIT: "https://brand-kit-api.contentstack.com", }, stack: mockStackData, user: {} as any, diff --git a/src/types/api.type.ts b/src/types/api.type.ts index 9ab74ec2..cc941559 100644 --- a/src/types/api.type.ts +++ b/src/types/api.type.ts @@ -2,9 +2,49 @@ import { AxiosRequestConfig, AxiosResponse } from "axios"; export type RequestConfig = AxiosRequestConfig; export type ProxyResponse = AxiosResponse; +/** + * URLs for Contentstack products, keyed by product. + * + * The SDK does not resolve these URLs itself — the host shell (e.g. Developer Hub / + * Marketplace UI) injects the values into the initialization data at init time, and + * the SDK exposes them verbatim via `appSdk.endpoints`. Apps build request URLs from + * `appSdk.endpoints.` and dispatch them with `appSdk.api(url, option)`. + * + * `appSdk.api()` proxies the request to the host shell, which attaches the app's + * OAuth access token. So only Contentstack APIs that accept an OAuth token (the + * management plane — `Authorization: Bearer ` / OAuth `authorization` header) + * can be called through `api()`. This type therefore surfaces only the management-plane + * endpoints. Delivery-plane APIs (Content/GraphQL Delivery, Preview, Image/Asset CDN, + * Personalize Edge) require a separate delivery/preview token and are intentionally + * NOT listed — apps that need them call those endpoints with their own credentials. + * + * `APP`, `CMA` and `DEVELOPER_HUB` are always injected by the host shell, so they are + * required (kept for backward compatibility — `APP` is the web-app URL). Every other + * key is OPTIONAL: it resolves to a URL only when the host shell injects it, and + * availability varies by region (e.g. `ASSET_MANAGEMENT` exists only in the AWS North + * America region). Treat a missing key as "not available in this host / region". + * + * Source of truth for products and per-region URLs: + * https://artifacts.contentstack.com/regions.json + */ export type ContentstackEndpoints = { + /** Application (web app) URL. Always injected by the host shell. */ APP: string; + /** Content Management API URL. OAuth-callable. Always injected by the host shell. */ CMA: string; + /** Developer Hub API URL. OAuth-callable. Always injected by the host shell. */ DEVELOPER_HUB: string; - [key:string]:string; + /** Launch API URL. OAuth-callable (management plane). */ + LAUNCH?: string; + /** Automate (Automations) Management API URL. OAuth-callable (management plane). */ + AUTOMATE?: string; + /** Brand Kit Management API URL. OAuth-callable (management plane). */ + BRAND_KIT?: string; + /** Generative AI API URL. OAuth-callable (management plane). */ + GEN_AI?: string; + /** Personalize Management API URL. OAuth-callable (management plane). */ + PERSONALIZE_MANAGEMENT?: string; + /** Asset Management API URL. OAuth-callable. Available only in the AWS North America region. */ + ASSET_MANAGEMENT?: string; + [key: string]: string | undefined; }; From 2ae26b1f8ec64c934014ff17cae7cab5a0e88c9f Mon Sep 17 00:00:00 2001 From: Tim Benniks Date: Wed, 1 Jul 2026 10:57:49 +0200 Subject: [PATCH 2/3] feat: add getEndpoints method and update API reference for new Contentstack endpoints --- __test__/uiLocation.test.ts | 16 ++++++++++++++++ docs/api-reference.md | 22 ++++++++++++++++++++++ package-lock.json | 4 ++-- package.json | 2 +- 4 files changed, 41 insertions(+), 3 deletions(-) diff --git a/__test__/uiLocation.test.ts b/__test__/uiLocation.test.ts index 3796660d..a45f3c5e 100644 --- a/__test__/uiLocation.test.ts +++ b/__test__/uiLocation.test.ts @@ -390,6 +390,22 @@ describe("UI Location", () => { }); }); + describe("getEndpoints", () => { + it("should return injected required and optional endpoints", () => { + const uiLocation = new UiLocation(initData); + const endpoints = uiLocation.getEndpoints(); + + expect(endpoints).toEqual(initData.endpoints); + expect(endpoints.CMA).toBe("https://api.contentstack.io"); + expect(endpoints.LAUNCH).toBe( + "https://launch-api.contentstack.com" + ); + expect(endpoints.BRAND_KIT).toBe( + "https://brand-kit-api.contentstack.com" + ); + }); + }); + describe("initialize", () => { it("should have static initialize method", () => { expect(UiLocation.initialize).toBeDefined(); diff --git a/docs/api-reference.md b/docs/api-reference.md index 058809dd..a40d07a2 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -148,6 +148,28 @@ ContentstackAppSdk.init().then(function (location) { }); ``` +### **ContentstackAppSdk endpoints** + +The SDK instance exposes Contentstack product URLs through `appSdk.endpoints` and `appSdk.getEndpoints()`. These URLs are injected by the Contentstack host shell during initialization. Apps can build request URLs from these values and send requests through `appSdk.api(url, option)`. + +`APP`, `CMA`, and `DEVELOPER_HUB` are always provided. Product-specific URLs such as `LAUNCH`, `AUTOMATE`, `BRAND_KIT`, `GEN_AI`, `PERSONALIZE_MANAGEMENT`, and `ASSET_MANAGEMENT` are optional because availability can vary by host shell and region. Check that an optional endpoint exists before using it. + +`appSdk.api()` proxies requests through the host shell and uses the app's OAuth access token. Use these endpoints for Contentstack management-plane APIs that accept OAuth authorization. Delivery-plane APIs, including Content Delivery, GraphQL Delivery, Preview, Image or Asset CDN, and Personalize Edge, require their own delivery or preview credentials. + +**Example** + +```js +ContentstackAppSdk.init().then(async function (appSdk) { + var endpoints = appSdk.getEndpoints(); + + if (endpoints.LAUNCH) { + var response = await appSdk.api(endpoints.LAUNCH + "/launches", { + method: "GET", + }); + } +}); +``` + ## **CustomField** It is an object representing the current Custom field reference in the Contentstack UI. diff --git a/package-lock.json b/package-lock.json index 02820f62..604b0928 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@contentstack/app-sdk", - "version": "2.4.1", + "version": "2.4.2", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@contentstack/app-sdk", - "version": "2.4.1", + "version": "2.4.2", "license": "MIT", "dependencies": { "axios": "^1.7.9", diff --git a/package.json b/package.json index 13c2068e..19554fe8 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@contentstack/app-sdk", - "version": "2.4.1", + "version": "2.4.2", "types": "dist/src/index.d.ts", "description": "The Contentstack App SDK allows you to customize your Contentstack applications.", "main": "dist/index.js", From abebcbbff4a6ae1f28b025cd69f8d0a962af7e40 Mon Sep 17 00:00:00 2001 From: Tim Benniks Contentstack Date: Wed, 1 Jul 2026 11:22:40 +0200 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Rahul Chavan --- src/types/api.type.ts | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/types/api.type.ts b/src/types/api.type.ts index cc941559..defd223f 100644 --- a/src/types/api.type.ts +++ b/src/types/api.type.ts @@ -36,6 +36,7 @@ export type ContentstackEndpoints = { DEVELOPER_HUB: string; /** Launch API URL. OAuth-callable (management plane). */ LAUNCH?: string; + LYTICS?: string; /** Automate (Automations) Management API URL. OAuth-callable (management plane). */ AUTOMATE?: string; /** Brand Kit Management API URL. OAuth-callable (management plane). */ @@ -43,8 +44,8 @@ export type ContentstackEndpoints = { /** Generative AI API URL. OAuth-callable (management plane). */ GEN_AI?: string; /** Personalize Management API URL. OAuth-callable (management plane). */ - PERSONALIZE_MANAGEMENT?: string; + PERSONALIZE?: string; /** Asset Management API URL. OAuth-callable. Available only in the AWS North America region. */ - ASSET_MANAGEMENT?: string; + ASSETS?: string; [key: string]: string | undefined; };