@adobe/aio-commerce-lib-admin-ui 0.1.0 → 0.2.0-alpha-20260722091448

package/dist/es/api/index.mjs

@@ -0,0 +1,262 @@
+/**
+ * @license
+ *
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { t as getAclResourceId } from "../acl-resource-id-pryVxI_c.mjs";
+import { t as parseOrThrow } from "../utils-COPGW1HO.mjs";
+import { CommerceSdkErrorBase } from "@adobe/aio-commerce-lib-core/error";
+import { AdobeCommerceHttpClient, ApiClient } from "@adobe/aio-commerce-lib-api";
+import * as v from "valibot";
+import { HTTPError } from "ky";
+
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (!no_symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
+//#region source/errors.ts
+/** Base error for Admin UI SDK permission helper failures. */
+var AdminUiPermissionError = class extends CommerceSdkErrorBase {};
+/** Error thrown when the current user is denied access to an Admin UI SDK ACL resource. */
+var AdminUiPermissionDeniedError = class extends AdminUiPermissionError {
+	resource;
+	constructor(resource, options) {
+		super(`Admin UI SDK permission denied for resource: ${resource}`, options);
+		this.resource = resource;
+	}
+};
+
+//#endregion
+//#region source/api/config/endpoints.ts
+var endpoints_exports$1 = /* @__PURE__ */ __exportAll({ enableAdminUiSdk: () => enableAdminUiSdk });
+/**
+* Enables the Admin UI SDK in Commerce via PUT /V1/adminuisdk/config.
+*
+* This must be called before {@link registerExtension} so that Commerce accepts
+* the extension registration; registering an extension while the SDK is disabled
+* leaves the extension unavailable in the Admin UI.
+*
+* @param httpClient - The {@link AdobeCommerceHttpClient} to use to make the request.
+* @param fetchOptions - Optional Ky fetch options.
+*
+* @throws An `HTTPError` if the status code is not 2XX.
+*/
+async function enableAdminUiSdk(httpClient, fetchOptions) {
+	return httpClient.put("adminuisdk/config", {
+		...fetchOptions,
+		json: { enableAdminUiSdk: true }
+	}).json();
+}
+
+//#endregion
+//#region source/api/extensions/schema.ts
+/** Parameters for POST /V1/adminuisdk/extension. */
+const ExtensionRegistrationParamsSchema = v.object({
+	extensionName: v.pipe(v.string(), v.minLength(1)),
+	extensionTitle: v.pipe(v.string(), v.minLength(1)),
+	extensionWorkspace: v.pipe(v.string(), v.minLength(1))
+});
+/** Parameters for DELETE /V1/adminuisdk/extension/{workspaceName}/{extensionName}. */
+const UnregisterExtensionParamsSchema = v.object({
+	extensionName: v.pipe(v.string(), v.minLength(1)),
+	workspaceName: v.pipe(v.string(), v.minLength(1))
+});
+
+//#endregion
+//#region source/api/extensions/endpoints.ts
+var endpoints_exports = /* @__PURE__ */ __exportAll({
+	registerExtension: () => registerExtension,
+	unregisterExtension: () => unregisterExtension
+});
+/**
+* Registers an Admin UI extension with Commerce via POST /V1/adminuisdk/extension.
+*
+* @param httpClient - The {@link AdobeCommerceHttpClient} to use to make the request.
+* @param params - The extension registration parameters.
+* @param fetchOptions - Optional Ky fetch options.
+*
+* @throws A `CommerceSdkValidationError` if the parameters are invalid.
+* @throws An `HTTPError` if the status code is not 2XX.
+*/
+async function registerExtension(httpClient, params, fetchOptions) {
+	const extension = parseOrThrow(ExtensionRegistrationParamsSchema, params);
+	return httpClient.post("adminuisdk/extension", {
+		...fetchOptions,
+		json: { extension }
+	}).json();
+}
+/**
+* Unregisters an Admin UI extension from Commerce via DELETE /V1/adminuisdk/extension/{workspaceName}/{extensionName}.
+*
+* @param httpClient - The {@link AdobeCommerceHttpClient} to use to make the request.
+* @param params - The workspace and extension names.
+* @param fetchOptions - Optional Ky fetch options.
+*
+* @throws A `CommerceSdkValidationError` if the parameters are invalid.
+* @throws An `HTTPError` if the status code is not 2XX.
+*/
+async function unregisterExtension(httpClient, params, fetchOptions) {
+	const { workspaceName, extensionName } = parseOrThrow(UnregisterExtensionParamsSchema, params);
+	return httpClient.delete(`adminuisdk/extension/${workspaceName}/${extensionName}`, fetchOptions).then((_res) => {});
+}
+
+//#endregion
+//#region source/api/lib/api-client.ts
+/**
+* Creates a new API client for the Admin UI API with all available operations.
+*
+* @param params - The parameters to build the Commerce HTTP client.
+*/
+function createAdminUiApiClient(params) {
+	return ApiClient.create(new AdobeCommerceHttpClient(params), {
+		...endpoints_exports$1,
+		...endpoints_exports
+	});
+}
+
+//#endregion
+//#region source/api/permissions/schema.ts
+/** Response shape returned by the Admin UI SDK permission check endpoint. */
+const permissionCheckResponseSchema = v.object({ allowed: v.boolean() });
+
+//#endregion
+//#region source/api/permissions/endpoints.ts
+/**
+* Checks whether the current user has the given ACL resource granted via POST /V1/adminuisdk/permission/check.
+* This is the raw HTTP call — prefer {@link getAdminUiPermissionClient} for caching and deduplication.
+*
+* @param httpClient - The {@link AdobeCommerceHttpClient} to use to make the request.
+* @param params - The resource to check.
+*
+* @throws {@link HTTPError} if the response status is not in the 2xx range.
+*/
+async function checkPermission(httpClient, params) {
+	return parseOrThrow(permissionCheckResponseSchema, await httpClient.post("adminuisdk/permission/check", { json: { resource: params.resource } }).json());
+}
+
+//#endregion
+//#region source/api/lib/permission-client.ts
+const DEFAULT_CACHE_TTL_MS = 3e5;
+/** Returns true when the error is an HTTP 401 Unauthorized response from ky. */
+function isUnauthorizedError(error) {
+	return error instanceof HTTPError && error.response.status === 401;
+}
+/** Wraps an arbitrary thrown value in an `AdminUiPermissionError`, passing through instances that are already one. */
+function toPermissionError(error) {
+	return error instanceof AdminUiPermissionError ? error : new AdminUiPermissionError("Permission check failed", { cause: error });
+}
+/**
+* Creates a client for checking Admin UI SDK ACL resources.
+*
+* @param options - Client configuration; see {@link AdminUiPermissionClientOptions}.
+* @returns An {@link AdminUiPermissionClient} for checking and requiring ACL resources.
+*/
+function getAdminUiPermissionClient(options) {
+	const { httpClient, appId, cacheTtlMs = DEFAULT_CACHE_TTL_MS, denyOnError = true } = options;
+	const cache = /* @__PURE__ */ new Map();
+	const inFlight = /* @__PURE__ */ new Map();
+	/**
+	* Performs the network request for `resource` and maps the outcome to a `PermissionCheckResult`.
+	* Always throws `AdminUiPermissionError` on 401. On other errors, returns a non-cacheable error
+	* result when `denyOnError` is true, or re-throws otherwise.
+	*/
+	async function fetchCheck(resource) {
+		try {
+			return {
+				allowed: (await checkPermission(httpClient, { resource })).allowed,
+				cacheable: true
+			};
+		} catch (error) {
+			if (isUnauthorizedError(error)) throw new AdminUiPermissionError("Unauthorized", { cause: error });
+			if (denyOnError) return {
+				cacheable: false,
+				error: toPermissionError(error)
+			};
+			throw toPermissionError(error);
+		}
+	}
+	/**
+	* Returns a permission check result for `resource`, serving from the TTL cache or an
+	* in-flight request when available, and falling back to a fresh `fetchCheck` call otherwise.
+	* Successful cacheable results are written to the TTL cache once the in-flight promise settles.
+	*/
+	function resolveCheck(resource) {
+		if (cacheTtlMs > 0) {
+			const cached = cache.get(resource);
+			if (cached !== void 0 && cached.expiresAt > Date.now()) return {
+				allowed: cached.value,
+				cacheable: true
+			};
+		}
+		const existing = inFlight.get(resource);
+		if (existing !== void 0) return existing;
+		const trackedPromise = fetchCheck(resource).then((result) => {
+			if (cacheTtlMs > 0 && result.cacheable && inFlight.get(resource) === trackedPromise) cache.set(resource, {
+				expiresAt: Date.now() + cacheTtlMs,
+				value: result.allowed
+			});
+			return result;
+		}).finally(() => {
+			if (inFlight.get(resource) === trackedPromise) inFlight.delete(resource);
+		});
+		inFlight.set(resource, trackedPromise);
+		return trackedPromise;
+	}
+	/**
+	* Resolves the ACL resource id for a call: uses the explicit argument when provided,
+	* otherwise derives it from `appId`. Returns an empty string when neither source yields a
+	* valid id, which callers interpret as "no resource available."
+	*/
+	function resolveResource(resource) {
+		return resource ?? getAclResourceId(appId ?? "");
+	}
+	return {
+		async check(resource) {
+			const resolved = resolveResource(resource);
+			if (resolved === "") return false;
+			const result = await resolveCheck(resolved);
+			return "error" in result ? false : result.allowed;
+		},
+		invalidate(resource) {
+			if (resource === void 0) {
+				cache.clear();
+				inFlight.clear();
+				return;
+			}
+			cache.delete(resource);
+			inFlight.delete(resource);
+		},
+		async require(resource) {
+			const resolved = resolveResource(resource);
+			if (resolved === "") throw new AdminUiPermissionError("No ACL resource ID could be resolved: provide a resource argument or set appId in options");
+			const result = await resolveCheck(resolved);
+			if ("error" in result) throw result.error;
+			if (!result.allowed) throw new AdminUiPermissionDeniedError(resolved);
+		}
+	};
+}
+
+//#endregion
+export { AdminUiPermissionDeniedError, AdminUiPermissionError, createAdminUiApiClient, getAclResourceId, getAdminUiPermissionClient };

package/dist/es/grid-columns/index.d.mts

@@ -0,0 +1,146 @@
+/**
+ * @license
+ *
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { t as AdminUiEntity } from "../acl-resource-id-DBlYU0DE.mjs";
+import * as v from "valibot";
+import { ErrorResponse, SuccessResponse } from "@adobe/aio-commerce-lib-core/responses";
+
+//#region source/grid-columns/acl-resource-id.d.ts
+/**
+ * Derives the deterministic Commerce ACL resource id for a grid column.
+ *
+ * The id is assembled as: `getAclResourceId(metadataId)` + `"_<entity>_gridcolumns_"` +
+ * sanitized `columnId`. The `entity` value is used verbatim (it is already `[a-z]`); the
+ * `columnId` is sanitized (trimmed, lowercased, non-`[a-z0-9_]` → `_`). `"Magento_CommerceBackendUix::adminuisdk_app_"`
+ * in the example is the fixed constant prefix (not a placeholder), and `"_gridcolumns_"` is the
+ * literal keyword separator for this component:
+ *
+ * @example
+ * ```
+ * getGridColumnAclResourceId("approval-dashboard-app", "order", "order_status")
+ * // getAclResourceId("approval-dashboard-app")                          + "_order_gridcolumns_" + sanitize("order_status")
+ * // "Magento_CommerceBackendUix::adminuisdk_app_approval_dashboard_app" + "_order_gridcolumns_" + "order_status"
+ * // → "Magento_CommerceBackendUix::adminuisdk_app_approval_dashboard_app_order_gridcolumns_order_status"
+ * ```
+ *
+ * @param metadataId - The application's `metadata.id` value (e.g. `"approval-dashboard-app"`).
+ * @param entity - The grid's Commerce entity (`"order"`, `"product"`, or `"customer"`).
+ * @param columnId - The column's `id` value from `adminUi.<entity>.gridColumns.columns[].id`.
+ * @returns The full Commerce ACL resource id for the grid-column leaf node, or an empty string
+ *   when `metadataId` is blank.
+ */
+declare function getGridColumnAclResourceId(metadataId: string, entity: AdminUiEntity, columnId: string): string;
+//#endregion
+//#region source/grid-columns/requests/schema.d.ts
+/**
+ * Grid identifier sent by Commerce on the `commerce/backend-ui/2` wire contract.
+ *
+ * @see {@link https://github.com/magento-commerce/adobe-commerce-backend-uix Magento module reference}
+ */
+declare const GridTypeSchema: v.PicklistSchema<["order", "product", "customer"], undefined>;
+/**
+ * Schema for the JSON body Commerce POSTs to a grid column handler.
+ *
+ * Commerce sends one request per chunk of grid rows (currently up to 1000 IDs
+ * per request). The upper bound is the Commerce side's contract and is not
+ * enforced here.
+ */
+declare const GridRequestSchema: v.ObjectSchema<{
+  readonly gridType: v.PicklistSchema<["order", "product", "customer"], undefined>;
+  readonly ids: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>, undefined>, v.MinLengthAction<string[], 1, "The value of \"ids\" must contain at least one entry">]>;
+  readonly requestId: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
+}, undefined>;
+//#endregion
+//#region source/grid-columns/requests/types.d.ts
+/** Grid identifier sent on the wire. */
+type GridType = v.InferOutput<typeof GridTypeSchema>;
+/** Parsed request body sent by Commerce to a grid column handler. */
+type GridRequest = v.InferOutput<typeof GridRequestSchema>;
+//#endregion
+//#region source/grid-columns/requests/presets.d.ts
+/**
+ * Parses and validates the JSON body Commerce POSTs to a grid column handler.
+ *
+ * Throws a `CommerceSdkValidationError` if the input is malformed.
+ *
+ * @example
+ * ```ts
+ * import { parseGridRequest } from "@adobe/aio-commerce-lib-admin-ui/grid-columns";
+ *
+ * export async function main(params: unknown) {
+ *   const { requestId, gridType, ids } = parseGridRequest(params);
+ *   // ...
+ * }
+ * ```
+ */
+declare function parseGridRequest(input: unknown): GridRequest;
+//#endregion
+//#region source/grid-columns/responses/types.d.ts
+/** Cell values returned for a single row, keyed by `id`. */
+type GridRow = Record<string, unknown>;
+/**
+ * Success body returned to Commerce.
+ *
+ * The `"*"` entry supplies default cell values that Commerce applies to IDs
+ * missing from `data` and to cells whose returned value does not satisfy the
+ * declared `type` on the registration.
+ */
+type GridSuccessBody = {
+  data: Record<string, GridRow> & {
+    "*"?: GridRow;
+  };
+};
+/** Failure body returned to Commerce. */
+type GridErrorBody = {
+  message: string;
+};
+//#endregion
+//#region source/grid-columns/responses/presets.d.ts
+/**
+ * Builds an HTTP 200 success response carrying the grid column data envelope
+ * Commerce expects on the `commerce/backend-ui/2` wire contract.
+ *
+ * @param data - Per-row cell values, keyed by entity ID.
+ * @param defaults - Default cell values applied by Commerce to IDs missing from
+ *   `data` and to cells whose value does not satisfy the declared `type` on the
+ *   registration.
+ *
+ * @example
+ * ```ts
+ * return okGridResponse(
+ *   {
+ *     "000000001": { fulfillment_status: "shipped", risk_score: 12 },
+ *     "000000002": { fulfillment_status: "pending", risk_score: 47 },
+ *   },
+ *   { fulfillment_status: "unknown", risk_score: 0 },
+ * );
+ * ```
+ */
+declare function okGridResponse(data: Record<string, GridRow>, defaults?: GridRow): SuccessResponse<GridSuccessBody>;
+/**
+ * Builds an error response for a grid column handler with the given HTTP status code.
+ *
+ * Commerce uses the HTTP status code to distinguish success from failure.
+ *
+ * @param statusCode - The HTTP status code to return.
+ * @param errorMessage - Error message included in the response body as `{ message }`.
+ *
+ * @example
+ * ```ts
+ * return errorGridResponse(500, "Could not reach inventory service");
+ * ```
+ */
+declare function errorGridResponse(statusCode: number, errorMessage: string): ErrorResponse<GridErrorBody>;
+//#endregion
+export { type AdminUiEntity, type GridErrorBody, type GridRequest, GridRequestSchema, type GridRow, type GridSuccessBody, type GridType, GridTypeSchema, errorGridResponse, getGridColumnAclResourceId, okGridResponse, parseGridRequest };

package/dist/es/grid-columns/index.mjs

@@ -0,0 +1,143 @@
+/**
+ * @license
+ *
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { n as sanitizeSegment, t as getAclResourceId } from "../acl-resource-id-pryVxI_c.mjs";
+import { t as nonEmptyStringValueSchema } from "../schemas-BFT8ys8P.mjs";
+import { t as parseOrThrow } from "../utils-COPGW1HO.mjs";
+import * as v from "valibot";
+import { buildErrorResponse, ok } from "@adobe/aio-commerce-lib-core/responses";
+
+//#region source/grid-columns/acl-resource-id.ts
+/**
+* Derives the deterministic Commerce ACL resource id for a grid column.
+*
+* The id is assembled as: `getAclResourceId(metadataId)` + `"_<entity>_gridcolumns_"` +
+* sanitized `columnId`. The `entity` value is used verbatim (it is already `[a-z]`); the
+* `columnId` is sanitized (trimmed, lowercased, non-`[a-z0-9_]` → `_`). `"Magento_CommerceBackendUix::adminuisdk_app_"`
+* in the example is the fixed constant prefix (not a placeholder), and `"_gridcolumns_"` is the
+* literal keyword separator for this component:
+*
+* @example
+* ```
+* getGridColumnAclResourceId("approval-dashboard-app", "order", "order_status")
+* // getAclResourceId("approval-dashboard-app")                          + "_order_gridcolumns_" + sanitize("order_status")
+* // "Magento_CommerceBackendUix::adminuisdk_app_approval_dashboard_app" + "_order_gridcolumns_" + "order_status"
+* // → "Magento_CommerceBackendUix::adminuisdk_app_approval_dashboard_app_order_gridcolumns_order_status"
+* ```
+*
+* @param metadataId - The application's `metadata.id` value (e.g. `"approval-dashboard-app"`).
+* @param entity - The grid's Commerce entity (`"order"`, `"product"`, or `"customer"`).
+* @param columnId - The column's `id` value from `adminUi.<entity>.gridColumns.columns[].id`.
+* @returns The full Commerce ACL resource id for the grid-column leaf node, or an empty string
+*   when `metadataId` is blank.
+*/
+function getGridColumnAclResourceId(metadataId, entity, columnId) {
+	const appRoot = getAclResourceId(metadataId);
+	if (appRoot === "") return "";
+	return `${appRoot}_${entity}_gridcolumns_${sanitizeSegment(columnId)}`;
+}
+
+//#endregion
+//#region source/grid-columns/requests/schema.ts
+/**
+* Grid identifier sent by Commerce on the `commerce/backend-ui/2` wire contract.
+*
+* @see {@link https://github.com/magento-commerce/adobe-commerce-backend-uix Magento module reference}
+*/
+const GridTypeSchema = v.picklist([
+	"order",
+	"product",
+	"customer"
+]);
+/**
+* Schema for the JSON body Commerce POSTs to a grid column handler.
+*
+* Commerce sends one request per chunk of grid rows (currently up to 1000 IDs
+* per request). The upper bound is the Commerce side's contract and is not
+* enforced here.
+*/
+const GridRequestSchema = v.object({
+	gridType: GridTypeSchema,
+	ids: v.pipe(v.array(nonEmptyStringValueSchema("id")), v.minLength(1, "The value of \"ids\" must contain at least one entry")),
+	requestId: nonEmptyStringValueSchema("requestId")
+});
+
+//#endregion
+//#region source/grid-columns/requests/presets.ts
+/**
+* Parses and validates the JSON body Commerce POSTs to a grid column handler.
+*
+* Throws a `CommerceSdkValidationError` if the input is malformed.
+*
+* @example
+* ```ts
+* import { parseGridRequest } from "@adobe/aio-commerce-lib-admin-ui/grid-columns";
+*
+* export async function main(params: unknown) {
+*   const { requestId, gridType, ids } = parseGridRequest(params);
+*   // ...
+* }
+* ```
+*/
+function parseGridRequest(input) {
+	return parseOrThrow(GridRequestSchema, input, "Invalid grid column request");
+}
+
+//#endregion
+//#region source/grid-columns/responses/presets.ts
+/**
+* Builds an HTTP 200 success response carrying the grid column data envelope
+* Commerce expects on the `commerce/backend-ui/2` wire contract.
+*
+* @param data - Per-row cell values, keyed by entity ID.
+* @param defaults - Default cell values applied by Commerce to IDs missing from
+*   `data` and to cells whose value does not satisfy the declared `type` on the
+*   registration.
+*
+* @example
+* ```ts
+* return okGridResponse(
+*   {
+*     "000000001": { fulfillment_status: "shipped", risk_score: 12 },
+*     "000000002": { fulfillment_status: "pending", risk_score: 47 },
+*   },
+*   { fulfillment_status: "unknown", risk_score: 0 },
+* );
+* ```
+*/
+function okGridResponse(data, defaults) {
+	return ok({ body: { data: defaults ? {
+		...data,
+		"*": defaults
+	} : data } });
+}
+/**
+* Builds an error response for a grid column handler with the given HTTP status code.
+*
+* Commerce uses the HTTP status code to distinguish success from failure.
+*
+* @param statusCode - The HTTP status code to return.
+* @param errorMessage - Error message included in the response body as `{ message }`.
+*
+* @example
+* ```ts
+* return errorGridResponse(500, "Could not reach inventory service");
+* ```
+*/
+function errorGridResponse(statusCode, errorMessage) {
+	return buildErrorResponse(statusCode, { body: { message: errorMessage } });
+}
+
+//#endregion
+export { GridRequestSchema, GridTypeSchema, errorGridResponse, getGridColumnAclResourceId, okGridResponse, parseGridRequest };