@gooddata/sdk-pluggable-application-model 11.37.0-alpha.0 → 11.37.0-alpha.2

package/esm/__version.js

@@ -1,7 +1,7 @@
 // (C) 2026 GoodData Corporation
 // DO NOT CHANGE THIS FILE, IT IS RE-GENERATED ON EVERY BUILD
 /** @alpha */
-export const LIB_VERSION = "11.37.0-alpha.0";
+export const LIB_VERSION = "11.37.0-alpha.2";
 /** @alpha */
 export const LIB_DESCRIPTION = "GoodData SDK model contracts for pluggable applications";
 /** @alpha */

package/esm/index.d.ts

@@ -5,7 +5,7 @@
  */
 export { DefaultApplicationId } from "./defaultPlatformApplications.js";
 export { LIB_VERSION, LIB_DESCRIPTION, LIB_NAME } from "./__version.js";
-export { type EmbeddingMode, type IApiTokenAuthCredentials, type IAuthCredentials, type IContextDeferredAuthCredentials, type IJwtAuthCredentials, type IOrganization, type IOrganizationPermissions, type IPlatformContext, type IPlatformContextV1, type IPluggableApplicationNavigation, PantherTier, isPlatformContextV1, } from "./platformContext.js";
+export { type EmbeddingMode, type IApiTokenAuthCredentials, type IAuthCredentials, type IContextDeferredAuthCredentials, type IEffectiveSettings, type IJwtAuthCredentials, type IOrganization, type IOrganizationPermissions, type IPlatformContext, type IPlatformContextV1, type IPluggableApplicationNavigation, PantherTier, isPlatformContextV1, isWorkspaceScopedSettings, } from "./platformContext.js";
 export { type ILocale } from "@gooddata/sdk-model";
 export { type IAppHeaderOptions, type IAppInstance, type KnownPluggableAppEventTypeName, type IPluggableApp, type IPluggableApplicationMountHandle, type IPluggableApplicationMountOptions, type IPluggableAppEvent, type IPluggableAppTelemetryCallbacks, type IReloadPlatformContextRequestedEvent, type ITelemetryEventOptions, isReloadPlatformContextRequestedEvent, type PluggableApplicationMount, PluggableAppEventType, type PluggableAppEventTypeName, reloadPlatformContextRequested, type TelemetryChannel, } from "./mount.js";
 export { type IHostUiModule, type IHostUiMountHandle, type IHostUiMountOptions, type IHostUiNotification, type INewDeploymentAvailableHostUiNotification, type HostUiMount, } from "./hostUi.js";

package/esm/index.js

@@ -7,5 +7,5 @@
  */
 export { DefaultApplicationId } from "./defaultPlatformApplications.js";
 export { LIB_VERSION, LIB_DESCRIPTION, LIB_NAME } from "./__version.js";
-export { PantherTier, isPlatformContextV1, } from "./platformContext.js";
+export { PantherTier, isPlatformContextV1, isWorkspaceScopedSettings, } from "./platformContext.js";
 export { isReloadPlatformContextRequestedEvent, PluggableAppEventType, reloadPlatformContextRequested, } from "./mount.js";

package/esm/platformContext.d.ts

@@ -97,6 +97,30 @@ export interface IJwtAuthCredentials {
  * @alpha
  */
 export type IAuthCredentials = IContextDeferredAuthCredentials | IApiTokenAuthCredentials | IJwtAuthCredentials;
+/**
+ * Effective settings for the active application scope.
+ *
+ * @remarks
+ * - On workspace-scoped routes this is `IUserWorkspaceSettings`, which the backend
+ *   produces from the org → workspace → user cascade.
+ * - On organization-scoped routes this is `IUserSettings`, which the backend
+ *   produces from the org → user cascade.
+ *
+ * Prefer reading {@link IPlatformContextV1.settings} for feature flags, locale, theme keys
+ * and other values whose source can be overridden at the workspace level.
+ *
+ * Read the raw {@link IPlatformContextV1.userSettings} or {@link IPlatformContextV1.workspaceSettings}
+ * only when you specifically need a field from one shape (e.g. the workspace identifier).
+ *
+ * @alpha
+ */
+export type IEffectiveSettings = IUserSettings | IUserWorkspaceSettings;
+/**
+ * Narrows {@link IEffectiveSettings} to the workspace-scoped shape.
+ *
+ * @alpha
+ */
+export declare function isWorkspaceScopedSettings(settings: IEffectiveSettings): settings is IUserWorkspaceSettings;
 /**
  * Platform context contract version 1.0.
  *
@@ -120,19 +144,36 @@ export interface IPlatformContextV1 {
     organizationPermissions?: IOrganizationPermissions;
     workspacePermissions?: IWorkspacePermissions;
     entitlements?: IEntitlementDescriptor[];
+    /**
+     * Raw user-level settings (org → user cascade).
+     *
+     * @remarks
+     * Prefer {@link IPlatformContextV1.settings} for reads that may be overridden at
+     * the workspace level (feature flags, locale, theme). Use this raw view only
+     * when you specifically need a user-scoped field such as `userId`.
+     */
     userSettings: IUserSettings;
     /**
-     * Effective workspace-scoped settings for the current user.
+     * Raw workspace-scoped settings for the current user (org → workspace → user cascade).
      *
      * @remarks
-     * Populated by the host when the active route is workspace-scoped.
-     * Merges workspace-level overrides with user-level defaults — use this
-     * for workspace feature flags (e.g. `enableAIKnowledge`) instead of
-     * `userSettings`, which only contains user-level values.
+     * Populated by the host when the active route is workspace-scoped, `undefined` otherwise.
      *
-     * `undefined` when no workspace is active (organization-scoped routes).
+     * Prefer {@link IPlatformContextV1.settings} for general reads. Use this raw view only
+     * when you specifically need a workspace-scoped field (e.g. the `workspace` identifier).
      */
     workspaceSettings?: IUserWorkspaceSettings;
+    /**
+     * Effective settings for the active application scope.
+     *
+     * @remarks
+     * - Workspace-scoped routes: equals `workspaceSettings` (org → workspace → user cascade).
+     * - Organization-scoped routes: equals `userSettings` (org → user cascade).
+     *
+     * This is the canonical read path for feature flags, locale, theme, and other
+     * values whose source can be overridden at the workspace level.
+     */
+    settings: IEffectiveSettings;
     whiteLabeling: IWhiteLabeling | undefined;
     preferredLocale?: ILocale;
     pantherTier?: PantherTier;

package/esm/platformContext.js

@@ -13,6 +13,14 @@ var PantherTier;
     PantherTier["LABS"] = "LABS";
     PantherTier["DEMO"] = "DEMO";
 })(PantherTier || (PantherTier = {}));
+/**
+ * Narrows {@link IEffectiveSettings} to the workspace-scoped shape.
+ *
+ * @alpha
+ */
+export function isWorkspaceScopedSettings(settings) {
+    return typeof settings.workspace === "string";
+}
 /**
  * Type guard for {@link IPlatformContextV1}.
  *

package/esm/sdk-pluggable-application-model.d.ts

@@ -136,6 +136,25 @@ export declare interface IContextDeferredAuthCredentials {
     externalProviderId?: string;
 }
 
+/**
+ * Effective settings for the active application scope.
+ *
+ * @remarks
+ * - On workspace-scoped routes this is `IUserWorkspaceSettings`, which the backend
+ *   produces from the org → workspace → user cascade.
+ * - On organization-scoped routes this is `IUserSettings`, which the backend
+ *   produces from the org → user cascade.
+ *
+ * Prefer reading {@link IPlatformContextV1.settings} for feature flags, locale, theme keys
+ * and other values whose source can be overridden at the workspace level.
+ *
+ * Read the raw {@link IPlatformContextV1.userSettings} or {@link IPlatformContextV1.workspaceSettings}
+ * only when you specifically need a field from one shape (e.g. the workspace identifier).
+ *
+ * @alpha
+ */
+export declare type IEffectiveSettings = IUserSettings | IUserWorkspaceSettings;
+
 /**
  * Host UI module contract.
  *
@@ -365,19 +384,36 @@ export declare interface IPlatformContextV1 {
     organizationPermissions?: IOrganizationPermissions;
     workspacePermissions?: IWorkspacePermissions;
     entitlements?: IEntitlementDescriptor[];
+    /**
+     * Raw user-level settings (org → user cascade).
+     *
+     * @remarks
+     * Prefer {@link IPlatformContextV1.settings} for reads that may be overridden at
+     * the workspace level (feature flags, locale, theme). Use this raw view only
+     * when you specifically need a user-scoped field such as `userId`.
+     */
     userSettings: IUserSettings;
     /**
-     * Effective workspace-scoped settings for the current user.
+     * Raw workspace-scoped settings for the current user (org → workspace → user cascade).
      *
      * @remarks
-     * Populated by the host when the active route is workspace-scoped.
-     * Merges workspace-level overrides with user-level defaults — use this
-     * for workspace feature flags (e.g. `enableAIKnowledge`) instead of
-     * `userSettings`, which only contains user-level values.
+     * Populated by the host when the active route is workspace-scoped, `undefined` otherwise.
      *
-     * `undefined` when no workspace is active (organization-scoped routes).
+     * Prefer {@link IPlatformContextV1.settings} for general reads. Use this raw view only
+     * when you specifically need a workspace-scoped field (e.g. the `workspace` identifier).
      */
     workspaceSettings?: IUserWorkspaceSettings;
+    /**
+     * Effective settings for the active application scope.
+     *
+     * @remarks
+     * - Workspace-scoped routes: equals `workspaceSettings` (org → workspace → user cascade).
+     * - Organization-scoped routes: equals `userSettings` (org → user cascade).
+     *
+     * This is the canonical read path for feature flags, locale, theme, and other
+     * values whose source can be overridden at the workspace level.
+     */
+    settings: IEffectiveSettings;
     whiteLabeling: IWhiteLabeling | undefined;
     preferredLocale?: ILocale;
     pantherTier?: PantherTier;
@@ -546,6 +582,13 @@ export declare function isPlatformContextV1(context: unknown): context is IPlatf
  */
 export declare function isReloadPlatformContextRequestedEvent(obj: unknown): obj is IReloadPlatformContextRequestedEvent;
 
+/**
+ * Narrows {@link IEffectiveSettings} to the workspace-scoped shape.
+ *
+ * @alpha
+ */
+export declare function isWorkspaceScopedSettings(settings: IEffectiveSettings): settings is IUserWorkspaceSettings;
+
 /**
  * Optional configuration for a telemetry event.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gooddata/sdk-pluggable-application-model",
-  "version": "11.37.0-alpha.0",
+  "version": "11.37.0-alpha.2",
   "description": "GoodData SDK model contracts for pluggable applications",
   "license": "MIT",
   "author": "GoodData Corporation",
@@ -23,7 +23,7 @@
   "dependencies": {
     "ts-invariant": "0.10.3",
     "tslib": "2.8.1",
-    "@gooddata/sdk-model": "11.37.0-alpha.0"
+    "@gooddata/sdk-model": "11.37.0-alpha.2"
   },
   "devDependencies": {
     "@microsoft/api-documenter": "^7.17.0",
@@ -47,8 +47,8 @@
     "oxlint-tsgolint": "0.11.4",
     "typescript": "5.9.3",
     "vitest": "4.1.0",
-    "@gooddata/eslint-config": "11.37.0-alpha.0",
-    "@gooddata/oxlint-config": "11.37.0-alpha.0"
+    "@gooddata/eslint-config": "11.37.0-alpha.2",
+    "@gooddata/oxlint-config": "11.37.0-alpha.2"
   },
   "scripts": {
     "_phase:build": "npm run build",