@adobe/aio-commerce-lib-admin-ui 0.1.0 → 0.2.0-beta-20260714082406

package/dist/cjs/grid-columns/index.cjs

@@ -0,0 +1,151 @@
+/**
+ * @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.
+ */
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_rolldown_runtime = require('../rolldown-runtime-Cx6hovH8.cjs');
+const require_acl_resource_id = require('../acl-resource-id-D_hCU1Qg.cjs');
+const require_schemas = require('../schemas-Ce10uBzN.cjs');
+const require_utils = require('../utils-B59fjd_w.cjs');
+let valibot = require("valibot");
+valibot = require_rolldown_runtime.__toESM(valibot, 1);
+let _adobe_aio_commerce_lib_core_responses = require("@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 = require_acl_resource_id.getAclResourceId(metadataId);
+	if (appRoot === "") return "";
+	return `${appRoot}_${entity}_gridcolumns_${require_acl_resource_id.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 = valibot.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 = valibot.object({
+	gridType: GridTypeSchema,
+	ids: valibot.pipe(valibot.array(require_schemas.nonEmptyStringValueSchema("id")), valibot.minLength(1, "The value of \"ids\" must contain at least one entry")),
+	requestId: require_schemas.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 require_utils.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 (0, _adobe_aio_commerce_lib_core_responses.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 (0, _adobe_aio_commerce_lib_core_responses.buildErrorResponse)(statusCode, { body: { message: errorMessage } });
+}
+
+//#endregion
+exports.GridRequestSchema = GridRequestSchema;
+exports.GridTypeSchema = GridTypeSchema;
+exports.errorGridResponse = errorGridResponse;
+exports.getGridColumnAclResourceId = getGridColumnAclResourceId;
+exports.okGridResponse = okGridResponse;
+exports.parseGridRequest = parseGridRequest;

package/dist/cjs/grid-columns/index.d.cts

@@ -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.cjs";
+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/cjs/mass-actions/index.cjs

@@ -0,0 +1,188 @@
+/**
+ * @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.
+ */
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_rolldown_runtime = require('../rolldown-runtime-Cx6hovH8.cjs');
+const require_acl_resource_id = require('../acl-resource-id-D_hCU1Qg.cjs');
+const require_schemas = require('../schemas-Ce10uBzN.cjs');
+const require_utils = require('../utils-B59fjd_w.cjs');
+let valibot = require("valibot");
+valibot = require_rolldown_runtime.__toESM(valibot, 1);
+let _adobe_aio_commerce_lib_core_responses = require("@adobe/aio-commerce-lib-core/responses");
+
+//#region source/mass-actions/acl-resource-id.ts
+/**
+* Derives the deterministic Commerce ACL resource id for a mass action.
+*
+* The id is assembled as: `getAclResourceId(metadataId)` + `"_<entity>_massactions_"` +
+* sanitized `actionId`. The `entity` value is used verbatim; the `actionId` is sanitized
+* (trimmed, lowercased, non-`[a-z0-9_]` → `_`). `"Magento_CommerceBackendUix::adminuisdk_app_"`
+* in the example is the fixed constant prefix (not a placeholder), and `"_massactions_"` is the
+* literal keyword separator for this component:
+*
+* @example
+* ```
+* getMassActionAclResourceId("approval-dashboard-app", "order", "bulk-approve")
+* // getAclResourceId("approval-dashboard-app")                          + "_order_massactions_" + sanitize("bulk-approve")
+* // "Magento_CommerceBackendUix::adminuisdk_app_approval_dashboard_app" + "_order_massactions_" + "bulk_approve"
+* // → "Magento_CommerceBackendUix::adminuisdk_app_approval_dashboard_app_order_massactions_bulk_approve"
+* ```
+*
+* @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 actionId - The action's `id` value from `adminUi.<entity>.massActions[].id`.
+* @returns The full Commerce ACL resource id for the mass-action leaf node, or an empty string
+*   when `metadataId` is blank.
+*/
+function getMassActionAclResourceId(metadataId, entity, actionId) {
+	const appRoot = require_acl_resource_id.getAclResourceId(metadataId);
+	if (appRoot === "") return "";
+	return `${appRoot}_${entity}_massactions_${require_acl_resource_id.sanitizeSegment(actionId)}`;
+}
+
+//#endregion
+//#region source/mass-actions/view/schema.ts
+/**
+* Schema for the `selection` query parameter Commerce appends to the iframe URL
+* of a view mass action.
+*
+* Commerce serializes the selection as a JSON-encoded string:
+* `?selection={"ids":["000000001"],"gridType":"customer"}`
+*/
+const MassActionSelectionSchema = valibot.object({
+	gridType: valibot.picklist([
+		"order",
+		"product",
+		"customer"
+	]),
+	ids: valibot.pipe(valibot.array(require_schemas.nonEmptyStringValueSchema("id")), valibot.minLength(1, "The value of \"ids\" must contain at least one entry"))
+});
+
+//#endregion
+//#region source/mass-actions/view/presets.ts
+/**
+* Parses the `selection` query parameter Commerce appends to the iframe URL of
+* a view mass action.
+*
+* Commerce serializes the selection as a JSON string:
+* `?selection={"ids":["000000001","000000002"],"gridType":"customer"}`
+*
+* Throws a `CommerceSdkValidationError` if the input is missing, not valid
+* JSON, or does not match the expected shape.
+*
+* @param rawSelection - The raw string value of the `selection` query parameter.
+*
+* @example
+* ```ts
+* import { parseMassActionSelection } from "@adobe/aio-commerce-lib-admin-ui/mass-actions";
+*
+* // In your SPA route handler:
+* const raw = new URLSearchParams(window.location.search).get("selection");
+* const { ids, gridType } = parseMassActionSelection(raw);
+* ```
+*/
+function parseMassActionSelection(rawSelection) {
+	if (rawSelection === null || rawSelection === void 0) throw new Error("Invalid mass action selection: the selection query parameter is missing.");
+	let parsed;
+	try {
+		parsed = JSON.parse(String(rawSelection));
+	} catch (error) {
+		throw new Error(`Invalid mass action selection: expected a JSON string, got: ${String(rawSelection)}`, { cause: error });
+	}
+	return require_utils.parseOrThrow(MassActionSelectionSchema, parsed, "Invalid mass action selection");
+}
+
+//#endregion
+//#region source/mass-actions/worker/schema.ts
+/**
+* Grid identifier sent by Commerce on the `commerce/backend-ui/2` wire contract
+* for worker mass actions.
+*/
+const MassActionGridTypeSchema = valibot.picklist([
+	"order",
+	"product",
+	"customer"
+]);
+/**
+* Schema for the JSON body Commerce POSTs to a worker mass action handler.
+*
+* Commerce sends one request per chunk of selected IDs (currently up to 1000
+* IDs per request). The upper bound is the Commerce side's contract and is not
+* enforced here.
+*/
+const MassActionRequestSchema = valibot.object({
+	gridType: MassActionGridTypeSchema,
+	requestId: require_schemas.nonEmptyStringValueSchema("requestId"),
+	selectedIds: valibot.pipe(valibot.array(require_schemas.nonEmptyStringValueSchema("id")), valibot.minLength(1, "The value of \"selectedIds\" must contain at least one entry"))
+});
+
+//#endregion
+//#region source/mass-actions/worker/presets.ts
+/**
+* Parses and validates the JSON body Commerce POSTs to a worker mass action handler.
+*
+* Throws a `CommerceSdkValidationError` if the input is malformed.
+*
+* @example
+* ```ts
+* import { parseMassActionRequest } from "@adobe/aio-commerce-lib-admin-ui/mass-actions";
+*
+* export async function main(params: unknown) {
+*   const { requestId, gridType, selectedIds } = parseMassActionRequest(params);
+*   // process selectedIds...
+* }
+* ```
+*/
+function parseMassActionRequest(input) {
+	return require_utils.parseOrThrow(MassActionRequestSchema, input, "Invalid mass action request");
+}
+/**
+* Builds an HTTP 200 success response for a worker mass action.
+*
+* Commerce determines success from the HTTP status code. You may optionally
+* include any fields in `body` for your own logging or auditing purposes.
+*
+* @example
+* ```ts
+* return okMassActionResponse();
+* return okMassActionResponse({ exported: selectedIds.length });
+* ```
+*/
+function okMassActionResponse(body = {}) {
+	return (0, _adobe_aio_commerce_lib_core_responses.ok)({ body });
+}
+/**
+* Builds an error response for a worker mass action with the given HTTP status code.
+*
+* @param statusCode - The HTTP status code to return.
+* @param errorMessage - Error message included in the response body as `{ message }`.
+*
+* @example
+* ```ts
+* return massActionErrorResponse(422, "Request entity is unprocessable");
+* ```
+*/
+function massActionErrorResponse(statusCode, errorMessage) {
+	return (0, _adobe_aio_commerce_lib_core_responses.buildErrorResponse)(statusCode, { body: { message: errorMessage } });
+}
+
+//#endregion
+exports.MassActionGridTypeSchema = MassActionGridTypeSchema;
+exports.MassActionRequestSchema = MassActionRequestSchema;
+exports.MassActionSelectionSchema = MassActionSelectionSchema;
+exports.getMassActionAclResourceId = getMassActionAclResourceId;
+exports.massActionErrorResponse = massActionErrorResponse;
+exports.okMassActionResponse = okMassActionResponse;
+exports.parseMassActionRequest = parseMassActionRequest;
+exports.parseMassActionSelection = parseMassActionSelection;

package/dist/cjs/mass-actions/index.d.cts

@@ -0,0 +1,160 @@
+/**
+ * @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.cjs";
+import * as v from "valibot";
+import { ErrorResponse, SuccessResponse } from "@adobe/aio-commerce-lib-core/responses";
+
+//#region source/mass-actions/acl-resource-id.d.ts
+/**
+ * Derives the deterministic Commerce ACL resource id for a mass action.
+ *
+ * The id is assembled as: `getAclResourceId(metadataId)` + `"_<entity>_massactions_"` +
+ * sanitized `actionId`. The `entity` value is used verbatim; the `actionId` is sanitized
+ * (trimmed, lowercased, non-`[a-z0-9_]` → `_`). `"Magento_CommerceBackendUix::adminuisdk_app_"`
+ * in the example is the fixed constant prefix (not a placeholder), and `"_massactions_"` is the
+ * literal keyword separator for this component:
+ *
+ * @example
+ * ```
+ * getMassActionAclResourceId("approval-dashboard-app", "order", "bulk-approve")
+ * // getAclResourceId("approval-dashboard-app")                          + "_order_massactions_" + sanitize("bulk-approve")
+ * // "Magento_CommerceBackendUix::adminuisdk_app_approval_dashboard_app" + "_order_massactions_" + "bulk_approve"
+ * // → "Magento_CommerceBackendUix::adminuisdk_app_approval_dashboard_app_order_massactions_bulk_approve"
+ * ```
+ *
+ * @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 actionId - The action's `id` value from `adminUi.<entity>.massActions[].id`.
+ * @returns The full Commerce ACL resource id for the mass-action leaf node, or an empty string
+ *   when `metadataId` is blank.
+ */
+declare function getMassActionAclResourceId(metadataId: string, entity: AdminUiEntity, actionId: string): string;
+//#endregion
+//#region source/mass-actions/view/schema.d.ts
+/**
+ * Schema for the `selection` query parameter Commerce appends to the iframe URL
+ * of a view mass action.
+ *
+ * Commerce serializes the selection as a JSON-encoded string:
+ * `?selection={"ids":["000000001"],"gridType":"customer"}`
+ */
+declare const MassActionSelectionSchema: 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">]>;
+}, undefined>;
+//#endregion
+//#region source/mass-actions/view/types.d.ts
+/** Parsed `selection` query parameter appended by Commerce to the iframe URL. */
+type MassActionSelection = v.InferOutput<typeof MassActionSelectionSchema>;
+//#endregion
+//#region source/mass-actions/view/presets.d.ts
+/**
+ * Parses the `selection` query parameter Commerce appends to the iframe URL of
+ * a view mass action.
+ *
+ * Commerce serializes the selection as a JSON string:
+ * `?selection={"ids":["000000001","000000002"],"gridType":"customer"}`
+ *
+ * Throws a `CommerceSdkValidationError` if the input is missing, not valid
+ * JSON, or does not match the expected shape.
+ *
+ * @param rawSelection - The raw string value of the `selection` query parameter.
+ *
+ * @example
+ * ```ts
+ * import { parseMassActionSelection } from "@adobe/aio-commerce-lib-admin-ui/mass-actions";
+ *
+ * // In your SPA route handler:
+ * const raw = new URLSearchParams(window.location.search).get("selection");
+ * const { ids, gridType } = parseMassActionSelection(raw);
+ * ```
+ */
+declare function parseMassActionSelection(rawSelection: unknown): MassActionSelection;
+//#endregion
+//#region source/mass-actions/worker/schema.d.ts
+/**
+ * Grid identifier sent by Commerce on the `commerce/backend-ui/2` wire contract
+ * for worker mass actions.
+ */
+declare const MassActionGridTypeSchema: v.PicklistSchema<["order", "product", "customer"], undefined>;
+/**
+ * Schema for the JSON body Commerce POSTs to a worker mass action handler.
+ *
+ * Commerce sends one request per chunk of selected IDs (currently up to 1000
+ * IDs per request). The upper bound is the Commerce side's contract and is not
+ * enforced here.
+ */
+declare const MassActionRequestSchema: v.ObjectSchema<{
+  readonly gridType: v.PicklistSchema<["order", "product", "customer"], undefined>;
+  readonly requestId: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
+  readonly selectedIds: 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 \"selectedIds\" must contain at least one entry">]>;
+}, undefined>;
+//#endregion
+//#region source/mass-actions/worker/types.d.ts
+/** Grid identifier sent on the wire by a worker mass action request. */
+type MassActionGridType = v.InferOutput<typeof MassActionGridTypeSchema>;
+/** Parsed request body sent by Commerce to a worker mass action handler. */
+type MassActionRequest = v.InferOutput<typeof MassActionRequestSchema>;
+/** Response body returned to Commerce after a worker mass action completes. */
+type MassActionResponseBody = Record<string, unknown>;
+/** Error body returned to Commerce when a worker mass action fails. */
+type MassActionErrorBody = {
+  message: string;
+};
+//#endregion
+//#region source/mass-actions/worker/presets.d.ts
+/**
+ * Parses and validates the JSON body Commerce POSTs to a worker mass action handler.
+ *
+ * Throws a `CommerceSdkValidationError` if the input is malformed.
+ *
+ * @example
+ * ```ts
+ * import { parseMassActionRequest } from "@adobe/aio-commerce-lib-admin-ui/mass-actions";
+ *
+ * export async function main(params: unknown) {
+ *   const { requestId, gridType, selectedIds } = parseMassActionRequest(params);
+ *   // process selectedIds...
+ * }
+ * ```
+ */
+declare function parseMassActionRequest(input: unknown): MassActionRequest;
+/**
+ * Builds an HTTP 200 success response for a worker mass action.
+ *
+ * Commerce determines success from the HTTP status code. You may optionally
+ * include any fields in `body` for your own logging or auditing purposes.
+ *
+ * @example
+ * ```ts
+ * return okMassActionResponse();
+ * return okMassActionResponse({ exported: selectedIds.length });
+ * ```
+ */
+declare function okMassActionResponse(body?: MassActionResponseBody): SuccessResponse<MassActionResponseBody>;
+/**
+ * Builds an error response for a worker mass action with the given HTTP status code.
+ *
+ * @param statusCode - The HTTP status code to return.
+ * @param errorMessage - Error message included in the response body as `{ message }`.
+ *
+ * @example
+ * ```ts
+ * return massActionErrorResponse(422, "Request entity is unprocessable");
+ * ```
+ */
+declare function massActionErrorResponse(statusCode: number, errorMessage: string): ErrorResponse<MassActionErrorBody>;
+//#endregion
+export { type AdminUiEntity, type MassActionErrorBody, type MassActionGridType, MassActionGridTypeSchema, type MassActionRequest, MassActionRequestSchema, type MassActionResponseBody, type MassActionSelection, MassActionSelectionSchema, getMassActionAclResourceId, massActionErrorResponse, okMassActionResponse, parseMassActionRequest, parseMassActionSelection };