feat: expand ContentstackEndpoints with OAuth-callable product endpoints

__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,
@@ -388,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();

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.

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",

src/types/api.type.ts

@@ -2,9 +2,50 @@ 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.<KEY>` 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 <token>` / 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;
+    LYTICS?: 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?: string;
+    /** Asset Management API URL. OAuth-callable. Available only in the AWS North America region. */
+    ASSETS?: string;
+    [key: string]: string | undefined;
 };