[ON HOLD] CEXT-6151: Add ACL admin UI schema and helper to check permissions by oshmyheliuk · Pull Request #426 · adobe/aio-commerce-sdk

oshmyheliuk · 2026-05-05T20:00:12Z

Description

https://jira.corp.adobe.com/browse/CEXT-6151

Update adminUISdk schema to support ACL fields for menu items
Add a public helper that extensions can call from the SPA and from runtime actions to check whether the current user is allowed to use a given ACL resource.

Related Issue

https://github.com/magento-commerce/adobe-commerce-backend-uix/pull/352

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

I have signed the Adobe Open Source CLA.
My code follows the code style of this project.
My change requires a change to the documentation.
I have updated the documentation accordingly.
I have read the CONTRIBUTING document.
I have read the DEVELOPMENT document.
I have added tests to cover my changes.
All new and existing tests passed.

changeset-bot · 2026-05-05T20:00:20Z

🦋 Changeset detected

Latest commit: d222a25

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@adobe/aio-commerce-lib-admin-ui	Minor
@adobe/aio-commerce-sdk	Minor
@adobe/aio-commerce-lib-app	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

…XT-6151

Update require() JSDoc to document fail-closed behavior when denyOnError: true. Add test case verifying require() throws AdminUiSdkPermissionError on 401. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

obarcelonap · 2026-05-14T17:23:44Z

Lib-api is designed as generic Commerce API utility library, this PR adds Admin UI SDK code.

The precedent is Commerce Events: eventing is wired up during installation (lib-app), the actual API client lives in its own dedicated lib-events package. Admin UI SDK is the same pattern, lib-app owns the config schema and the installation step, but the permission client is a standalone API concern.

I'd spawn a new package dedicated for Admin UI SDK.

The cost is another package to maintain, but given that Admin UI SDK is still growing and under refinement, doing the split now is lower effort than after more surface has accumulated across lib-app and lib-api.

obarcelonap · 2026-05-14T17:38:11Z

+}
+
+/** Client for checking the current user's Admin UI SDK resource permissions. */
+export interface AdminUiSdkPermissionClient {


Wouldn't be better to do not limit the scope to just permissions? What if we need to add in the future an operation for AdminUiSdk but not related to permissions? We will create a new client?

I'd propose to open the scope of the client, so other concepts fit in:

interface AdminUiSdkClient { checkPermission() invalidatePermission() requirePermission() }

We already have an admin ui sdk related operation, but they are using the Commerce Client directly.
https://github.com/adobe/aio-commerce-sdk/blob/main/packages/aio-commerce-lib-app/source/management/installation/admin-ui-sdk/helpers.ts#L36
Probably can be moved to the "new Client" as well.

obarcelonap · 2026-05-14T17:39:24Z

+} as const;
+
+/** Wraps an App Builder action handler with an Admin UI SDK permission check. */
+export function withAdminUiSdkPermission<


I like this idea but not sure if we have this kind of wrappers anywhere else

Yeah, I wasn't too sure whether I should add this. This wrapper is optional, I can remove it.

Maybe we could just create a require helper function instead of wrapping.

requireAdminUiSdkPermission("Acme_Promotions::edit", client)

Does it make sense change resource as array? In case of multiple permissions are allowed? Or even multiple permissions could be required?

obarcelonap

LGTM but I'd like to hear your opinion about spawning a new package before approving.

oshmyheliuk · 2026-05-14T18:29:07Z

Creating a new package sounds like a logical step to me, to align with what we already have for eventing/webhooks.
I can update this PR with related changes.

obarcelonap · 2026-05-15T07:45:08Z

+  return { statusCode: 200, body: { updated: true } };
+}
+
+export const main = async (params) => {


I overlooked the wrapper I thought it was meant to be used wrapping the whole function so you don't need to create the clients.

export const main = withAdminUiSdkPermission( "Acme_Promotions::edit", (params) => { // protected handler here }, )

- code review

- refactor

obarcelonap · 2026-05-22T17:22:55Z

@@ -0,0 +1,111 @@
+# `@adobe/aio-commerce-lib-admin-ui-sdk` Documentation


should we add experimental warning

Added warning to the docs

obarcelonap · 2026-05-22T17:25:06Z

+});
+```
+
+In install/uninstall actions where only a subset of operations is needed, prefer `createCustomAdminUiSdkApiClient` to keep the bundle lean:


While I understand this is to be more performant I don't think it is an issue in the app-management endpoints since they're not in the critical path of the applications. Therefore I'd remove it for the sake of simplicity.

I'd argue against removing it. I don't think it adds that much complexity and enables more flexibility to optimize bundle size. Not a blocker for now as it can be re-added at any time, but wanted to leave my opinion. Also it would be consistent with other packages which also have it.

obarcelonap · 2026-05-22T17:35:23Z

+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "scripts": {


Missing docs script and @aio-commerce-sdk/config-typedoc devDependency

Docs script was has been added

obarcelonap · 2026-05-22T17:37:38Z

review this docs because claude is flagging some ids may not work with the new validations

docs/usage.md in lib-app still has "my-app::menu" — which now fails the new regex packages/aio-commerce-lib-app/docs/usage.md:476 still shows a hyphenated ID. The new id regex /^[A-Za-z0-9/:_]+$/ disallows hyphens, so any user copying from the docs would get an unexpected parse failure. The example needs updating (e.g. "my_app::menu"). If real apps use hyphenated IDs this is potentially a major bump.

Thanks for spotting this, the docs were updated according to the regex, where hyphens are not allowed.

- code review

obarcelonap

No blockers

obarcelonap · 2026-06-02T07:24:17Z

+    "dist",
+    "package.json",
+    "CHANGELOG.md",
+    "README.md"


This is missing, could you add a README to the new package? Something like https://github.com/adobe/aio-commerce-sdk/tree/main/packages/aio-commerce-lib-app

obarcelonap · 2026-06-02T07:29:54Z

-          extensionWorkspace: appData.workspaceName,
-        },
-      },
+  await adminUiSdkClient


I'd probably throw if process.env.__OW_NAMESPACE is not available. I know won't ever happen but using empty string as default feels is not correct.

obarcelonap · 2026-06-02T07:32:34Z

 };

-/** Context shared across Admin UI SDK steps. */
+function createAdminUiSdkClient(params: RuntimeActionParams) {


this is very useful function, I feel we have the same for events clients. Should we export it and add it to usage.md?

If we were to do this I would do it from each respective package, as it has nothing to do with any lib-app concern.

obarcelonap · 2026-06-02T07:35:29Z

@@ -0,0 +1,98 @@
+{
+  "name": "@adobe/aio-commerce-lib-admin-ui-sdk",


In #480 @danipt is suggesting to drop sdk term (see #480 (comment)). I'd rename to this package to @adobe/aio-commerce-lib-admin-ui

Don't have a strong opinion here, but isn't the Commerce module named backend-uix or something like that? Maybe it's not as explicit as "admin-ui", but would help people correlate them more easily.

obarcelonap · 2026-06-02T07:37:56Z

+  id: aclResourceIdSchema("ACL resource ID"),
+  title: nonEmptyStringValueSchema("ACL resource title"),
+  parent: v.optional(aclResourceIdSchema("ACL resource parent")),
+  sortOrder: v.optional(positiveNumberValueSchema("ACL resource sortOrder")),


positiveNumberValueSchema should probably be used in sortOrder of MenuItemSchema

iivvaannxx · 2026-06-02T09:31:01Z

+Add `@adobe/aio-commerce-lib-admin-ui-sdk` library for checking Admin UI SDK ACL resource permissions.
+Add Admin UI SDK API exports to `@adobe/aio-commerce-sdk`.


These should be two separate changesets. Otherwise the CHANGELOG of admin-ui-sdk will include this line about "adding exports to aio-commerce-sdk", which should not.

iivvaannxx · 2026-06-02T09:32:05Z

@@ -0,0 +1,98 @@
+# `@adobe/aio-commerce-lib-admin-ui-sdk` Documentation
+
+> **Experimental:** This package is not yet production-ready. The API may change in future releases.


Just so that it stands out a bit better as a warning.

Suggested change

> **Experimental:** This package is not yet production-ready. The API may change in future releases.

> [!WARNING]

> **Experimental**: This package is not yet production-ready. The API may change in future releases.

iivvaannxx · 2026-06-02T09:38:45Z

+export async function registerExtension(
+  httpClient: AdobeCommerceHttpClient,
+  params: ExtensionRegistrationParams,
+  fetchOptions?: Options,


Probably not urgent, but be aware of #462 which changes this type to decouple our methods from ky (which was blocking a major library update). If the other PR merges first you'll need to update it

iivvaannxx · 2026-06-02T09:40:29Z

+  extensionName: v.string(),
+  extensionTitle: v.string(),
+  extensionUrl: v.string(),
+  extensionWorkspace: v.string(),
+});


Should we add a bit more strict validation? Or is this done by the Commerce module? Such as v.url for the extensionUrl or some regex patterns/length checks for those that we know. I would argue it's useful to catch errors as early as possible (avoiding network round-trips).

iivvaannxx · 2026-06-02T09:43:46Z

+  await httpClient.delete(
+    `adminuisdk/extension/${workspaceName}/${extensionName}`,
+    fetchOptions,
+  );


I did not verify this, but I think that when you want to return Promise<void> you need to use .then(() => {}) with an empty handler, like in here

iivvaannxx · 2026-06-02T09:58:40Z

+    "directory": "packages/aio-commerce-lib-admin-ui-sdk"
+  },
+  "publishConfig": {
+    "exports": {


I believe you're missing the root entrypoint of source/index.ts?

iivvaannxx · 2026-06-02T09:59:27Z

+    "@aio-commerce-sdk/config-vitest": "workspace:*",
+    "@aio-commerce-sdk/scripting-utils": "workspace:*",
+    "@aio-commerce-sdk/scripts": "workspace:*",
+    "msw": "catalog:",


Is this dependency used? I believe it's for integration tests, but I didn't see any of those, only unit.

iivvaannxx · 2026-06-02T10:00:32Z

+import { baseConfig } from "@aio-commerce-sdk/config-vitest/vitest.config.base";
+import { defineConfig, mergeConfig } from "vitest/config";
+
+const BARREL_FILES = ["./source/index.ts"];


This can also use a glob to any index.ts, as there are currently two of them.

iivvaannxx · 2026-06-02T10:01:49Z

 };

-/** Context shared across Admin UI SDK steps. */
+function createAdminUiSdkClient(params: RuntimeActionParams) {


If we were to do this I would do it from each respective package, as it has nothing to do with any lib-app concern.

iivvaannxx · 2026-06-02T10:03:01Z

This is also missing the admin-ui-sdk root entrypoint.

oshmyheliuk · 2026-06-02T19:10:10Z

@obarcelonap @iivvaannxx I extracted the new package creation to a separate pull request: #489.
I addressed all related comments there.
As the ACL may be changed and delayed, the new package part can already be merged, and it would simplify this PR after the merge.

Consolidate admin UI package into renamed @adobe/aio-commerce-lib-admin-ui; port ACL permission-checking feature onto main's refined extensions package. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

iivvaannxx · 2026-06-15T13:29:01Z

This doesn't need to target @adobe/aio-commerce-sdk, we don't do updates in that package for anything that changes in their subpaths, because it's "implicit" that they are always 1:1. Because you're updating admin-ui, the metapackage will also release a patch and get updated automatically.

oshmyheliuk · 2026-06-16T02:00:27Z

Recreated the PR -> #522

oshmyheliuk added 2 commits May 4, 2026 14:12

CEXT-6151: [SDK] Add ACL admin UI schema and helper to check permissions

0ef0a94

CEXT-6151: [SDK] Add ACL admin UI schema and helper to check permissions

a182244

github-actions Bot added with-changeset The PR contains a Changeset file. pkg: aio-commerce-lib-app Includes changes in `packages/aio-commerce-lib-app` labels May 5, 2026

oshmyheliuk and others added 8 commits May 5, 2026 15:12

Merge branch 'main' into CEXT-6151

ea14acd

CEXT-6151: [SDK] Add ACL admin UI schema and helper to check permissions

dcc5c57

Merge branch 'CEXT-6151' of github.com:adobe/aio-commerce-sdk into CE…

9342478

…XT-6151

CEXT-6151: [SDK] Add ACL admin UI schema and helper to check permissions

02f79b2

CEXT-6151: [SDK] Add ACL admin UI schema and helper to check permissions

cef1831

CEXT-6151: Fix require() JSDoc and add 401 test

6cf97a8

Update require() JSDoc to document fail-closed behavior when denyOnError: true. Add test case verifying require() throws AdminUiSdkPermissionError on 401. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CEXT-6151: [SDK] Add ACL admin UI schema and helper to check permissions

f83ad7a

CEXT-6151: [SDK] Add ACL admin UI schema and helper to check permissions

16efa4c

obarcelonap reviewed May 14, 2026

View reviewed changes

Comment thread packages/aio-commerce-lib-app/source/config/schema/admin-ui-sdk.ts

obarcelonap reviewed May 14, 2026

View reviewed changes

obarcelonap reviewed May 15, 2026

View reviewed changes

oshmyheliuk added 3 commits May 15, 2026 17:00

Merge branch 'main' into CEXT-6151

14c8d2a

Merge branch 'main' into CEXT-6151

38c6595

CEXT-6151: [SDK] Add ACL admin UI schema and helper to check permissions

407d8cf

- code review

github-actions Bot added the pkg: aio-commerce-sdk Includes changes in `packages/aio-commerce-sdk` label May 18, 2026

oshmyheliuk added 5 commits May 18, 2026 11:29

CEXT-6151: [SDK] Add ACL admin UI schema and helper to check permissions

f42a608

- code review

CEXT-6151: [SDK] Add ACL admin UI schema and helper to check permissions

92f523d

- code review

CEXT-6151: [SDK] Add ACL admin UI schema and helper to check permissions

a17ddd4

- code review

CEXT-6151: [SDK] Add ACL admin UI schema and helper to check permissions

d33ae24

- refactor

CEXT-6151: [SDK] Add ACL admin UI schema and helper to check permissions

8142c69

- refactor

obarcelonap reviewed May 22, 2026

View reviewed changes

oshmyheliuk added 5 commits May 28, 2026 21:20

Merge branch 'main' into CEXT-6151

5031209

Merge branch 'main' into CEXT-6151

07ebb3e

CEXT-6151: [SDK] Add ACL admin UI schema and helper to check permissions

95add46

- code review

Merge branch 'main' into CEXT-6151

77ff05e

CEXT-6151: [SDK] Add ACL admin UI schema and helper to check permissions

2a16335

- code review

obarcelonap approved these changes Jun 2, 2026

View reviewed changes

iivvaannxx approved these changes Jun 2, 2026

View reviewed changes

Merge branch 'main' into CEXT-6151

623b163

oshmyheliuk mentioned this pull request Jun 2, 2026

CEXT-6318: Create a separate package for Admin UI SDK #489

Merged

11 tasks

Merge branch 'main' into CEXT-6151

d222a25

Consolidate admin UI package into renamed @adobe/aio-commerce-lib-admin-ui; port ACL permission-checking feature onto main's refined extensions package. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions Bot removed the pkg: aio-commerce-sdk Includes changes in `packages/aio-commerce-sdk` label Jun 3, 2026

oshmyheliuk added the hold-merge Needs to wait for something to happen before merging label Jun 3, 2026

oshmyheliuk changed the title ~~CEXT-6151: Add ACL admin UI schema and helper to check permissions~~ [ON HOLDCEXT-6151: Add ACL admin UI schema and helper to check permissions Jun 3, 2026

oshmyheliuk changed the title ~~[ON HOLDCEXT-6151: Add ACL admin UI schema and helper to check permissions~~ [ON HOLD] CEXT-6151: Add ACL admin UI schema and helper to check permissions Jun 3, 2026

iivvaannxx reviewed Jun 15, 2026

View reviewed changes

oshmyheliuk closed this Jun 16, 2026

		@@ -0,0 +1,111 @@
		# `@adobe/aio-commerce-lib-admin-ui-sdk` Documentation

		@@ -0,0 +1,98 @@
		{
		"name": "@adobe/aio-commerce-lib-admin-ui-sdk",

		Add `@adobe/aio-commerce-lib-admin-ui-sdk` library for checking Admin UI SDK ACL resource permissions.
		Add Admin UI SDK API exports to `@adobe/aio-commerce-sdk`.

		@@ -0,0 +1,98 @@
		# `@adobe/aio-commerce-lib-admin-ui-sdk` Documentation

		> Experimental: This package is not yet production-ready. The API may change in future releases.

	> Experimental: This package is not yet production-ready. The API may change in future releases.
	> [!WARNING]
	> Experimental: This package is not yet production-ready. The API may change in future releases.

Conversation

oshmyheliuk commented May 5, 2026

Description

Related Issue

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Types of changes

Checklist:

Uh oh!

changeset-bot Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

obarcelonap commented May 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

obarcelonap left a comment

Choose a reason for hiding this comment

Uh oh!

oshmyheliuk commented May 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

obarcelonap left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

changeset-bot Bot commented May 5, 2026 •

edited

Loading