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

package/dist/es/mass-actions/index.d.mts

@@ -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.mjs";
+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 };

package/dist/es/mass-actions/index.mjs

@@ -0,0 +1,178 @@
+/**
+ * @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/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 = getAclResourceId(metadataId);
+	if (appRoot === "") return "";
+	return `${appRoot}_${entity}_massactions_${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 = v.object({
+	gridType: v.picklist([
+		"order",
+		"product",
+		"customer"
+	]),
+	ids: v.pipe(v.array(nonEmptyStringValueSchema("id")), v.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 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 = v.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 = v.object({
+	gridType: MassActionGridTypeSchema,
+	requestId: nonEmptyStringValueSchema("requestId"),
+	selectedIds: v.pipe(v.array(nonEmptyStringValueSchema("id")), v.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 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 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 buildErrorResponse(statusCode, { body: { message: errorMessage } });
+}
+
+//#endregion
+export { MassActionGridTypeSchema, MassActionRequestSchema, MassActionSelectionSchema, getMassActionAclResourceId, massActionErrorResponse, okMassActionResponse, parseMassActionRequest, parseMassActionSelection };

package/dist/es/menu/index.d.mts

@@ -0,0 +1,63 @@
+/**
+ * @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.
+ */
+
+//#region source/menu/acl-resource-id.d.ts
+/**
+ * Derives the deterministic Commerce ACL resource id for a specific menu item.
+ *
+ * The id is assembled as: `getAclResourceId(metadataId)` + `"_menu_"` + sanitized `menuId`.
+ * Each segment is sanitized independently (trimmed, lowercased, non-`[a-z0-9_]` → `_`).
+ * `"Magento_CommerceBackendUix::adminuisdk_app_"` in the example is the fixed constant prefix
+ * (not a placeholder), and `"_menu_"` is the literal keyword separator for this component:
+ *
+ * @example
+ * ```
+ * getMenuAclResourceId("approval-dashboard-app", "approval_dashboard")
+ * // getAclResourceId("approval-dashboard-app")                          + "_menu_" + sanitize("approval_dashboard")
+ * // "Magento_CommerceBackendUix::adminuisdk_app_approval_dashboard_app" + "_menu_" + "approval_dashboard"
+ * // → "Magento_CommerceBackendUix::adminuisdk_app_approval_dashboard_app_menu_approval_dashboard"
+ * ```
+ *
+ * @param metadataId - The application's `metadata.id` value (e.g. `"approval-dashboard-app"`).
+ * @param menuId - The menu item's `id` value from `adminUi.menu.id` (e.g. `"approval_dashboard"`).
+ * @returns The full Commerce ACL resource id for the menu leaf node, or an empty string
+ *   when `metadataId` is blank.
+ */
+declare function getMenuAclResourceId(metadataId: string, menuId: string): string;
+//#endregion
+//#region source/menu/paths.d.ts
+/** Menu ID for "Catalog" in the Adobe Commerce admin */
+declare const MENU_CATALOG = "catalog";
+/** Menu ID for "Customers" in the Adobe Commerce admin */
+declare const MENU_CUSTOMERS = "customers";
+/** Menu ID for "Marketing" in the Adobe Commerce admin */
+declare const MENU_MARKETING = "marketing";
+/** Menu ID for "Content" in the Adobe Commerce admin */
+declare const MENU_CONTENT = "content";
+/** Menu ID for "Reports" in the Adobe Commerce admin */
+declare const MENU_REPORTS = "reports";
+/** Menu ID for "Sales" in the Adobe Commerce admin */
+declare const MENU_SALES = "sales";
+/** Menu ID for "Stores" in the Adobe Commerce admin */
+declare const MENU_STORES = "stores";
+/** Menu ID for "System" in the Adobe Commerce admin */
+declare const MENU_SYSTEM = "system";
+/** All Commerce Admin menus available for app attachment. */
+declare const COMMERCE_MENUS: readonly ["sales", "catalog", "customers", "marketing", "content", "reports", "stores", "system"];
+/** A union type of all known supported Commerce Admin menu IDs. */
+type CommerceMenu = (typeof COMMERCE_MENUS)[number];
+/** Returns true if the given string is a known Commerce Admin menu ID. */
+declare function isCommerceMenu(menu: string): menu is CommerceMenu;
+//#endregion
+export { COMMERCE_MENUS, CommerceMenu, MENU_CATALOG, MENU_CONTENT, MENU_CUSTOMERS, MENU_MARKETING, MENU_REPORTS, MENU_SALES, MENU_STORES, MENU_SYSTEM, getMenuAclResourceId, isCommerceMenu };

package/dist/es/menu/index.mjs

@@ -0,0 +1,80 @@
+/**
+ * @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";
+
+//#region source/menu/acl-resource-id.ts
+/**
+* Derives the deterministic Commerce ACL resource id for a specific menu item.
+*
+* The id is assembled as: `getAclResourceId(metadataId)` + `"_menu_"` + sanitized `menuId`.
+* Each segment is sanitized independently (trimmed, lowercased, non-`[a-z0-9_]` → `_`).
+* `"Magento_CommerceBackendUix::adminuisdk_app_"` in the example is the fixed constant prefix
+* (not a placeholder), and `"_menu_"` is the literal keyword separator for this component:
+*
+* @example
+* ```
+* getMenuAclResourceId("approval-dashboard-app", "approval_dashboard")
+* // getAclResourceId("approval-dashboard-app")                          + "_menu_" + sanitize("approval_dashboard")
+* // "Magento_CommerceBackendUix::adminuisdk_app_approval_dashboard_app" + "_menu_" + "approval_dashboard"
+* // → "Magento_CommerceBackendUix::adminuisdk_app_approval_dashboard_app_menu_approval_dashboard"
+* ```
+*
+* @param metadataId - The application's `metadata.id` value (e.g. `"approval-dashboard-app"`).
+* @param menuId - The menu item's `id` value from `adminUi.menu.id` (e.g. `"approval_dashboard"`).
+* @returns The full Commerce ACL resource id for the menu leaf node, or an empty string
+*   when `metadataId` is blank.
+*/
+function getMenuAclResourceId(metadataId, menuId) {
+	const appRoot = getAclResourceId(metadataId);
+	if (appRoot === "") return "";
+	return `${appRoot}_menu_${sanitizeSegment(menuId)}`;
+}
+
+//#endregion
+//#region source/menu/paths.ts
+/** Menu ID for "Catalog" in the Adobe Commerce admin */
+const MENU_CATALOG = "catalog";
+/** Menu ID for "Customers" in the Adobe Commerce admin */
+const MENU_CUSTOMERS = "customers";
+/** Menu ID for "Marketing" in the Adobe Commerce admin */
+const MENU_MARKETING = "marketing";
+/** Menu ID for "Content" in the Adobe Commerce admin */
+const MENU_CONTENT = "content";
+/** Menu ID for "Reports" in the Adobe Commerce admin */
+const MENU_REPORTS = "reports";
+/** Menu ID for "Sales" in the Adobe Commerce admin */
+const MENU_SALES = "sales";
+/** Menu ID for "Stores" in the Adobe Commerce admin */
+const MENU_STORES = "stores";
+/** Menu ID for "System" in the Adobe Commerce admin */
+const MENU_SYSTEM = "system";
+/** All Commerce Admin menus available for app attachment. */
+const COMMERCE_MENUS = [
+	MENU_SALES,
+	MENU_CATALOG,
+	MENU_CUSTOMERS,
+	MENU_MARKETING,
+	MENU_CONTENT,
+	MENU_REPORTS,
+	MENU_STORES,
+	MENU_SYSTEM
+];
+/** Returns true if the given string is a known Commerce Admin menu ID. */
+function isCommerceMenu(menu) {
+	return COMMERCE_MENUS.includes(menu);
+}
+
+//#endregion
+export { COMMERCE_MENUS, MENU_CATALOG, MENU_CONTENT, MENU_CUSTOMERS, MENU_MARKETING, MENU_REPORTS, MENU_SALES, MENU_STORES, MENU_SYSTEM, getMenuAclResourceId, isCommerceMenu };

package/dist/es/order-view-buttons/index.d.mts

@@ -0,0 +1,113 @@
+/**
+ * @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 * as v from "valibot";
+import { ErrorResponse, SuccessResponse } from "@adobe/aio-commerce-lib-core/responses";
+
+//#region source/order-view-buttons/acl-resource-id.d.ts
+/**
+ * Derives the deterministic Commerce ACL resource id for an order view button.
+ *
+ * View buttons exist only on the order entity, so no entity discriminator is needed.
+ * The id is assembled as: `getAclResourceId(metadataId)` + `"_order_viewbuttons_"` +
+ * sanitized `buttonId`. The `buttonId` is sanitized (trimmed, lowercased, non-`[a-z0-9_]` → `_`).
+ * `"Magento_CommerceBackendUix::adminuisdk_app_"` in the example is the fixed constant prefix
+ * (not a placeholder), and `"_order_viewbuttons_"` is the literal keyword separator for this component:
+ *
+ * @example
+ * ```
+ * getOrderViewButtonAclResourceId("approval-dashboard-app", "approve-order")
+ * // getAclResourceId("approval-dashboard-app")                          + "_order_viewbuttons_" + sanitize("approve-order")
+ * // "Magento_CommerceBackendUix::adminuisdk_app_approval_dashboard_app" + "_order_viewbuttons_" + "approve_order"
+ * // → "Magento_CommerceBackendUix::adminuisdk_app_approval_dashboard_app_order_viewbuttons_approve_order"
+ * ```
+ *
+ * @param metadataId - The application's `metadata.id` value (e.g. `"approval-dashboard-app"`).
+ * @param buttonId - The button's `id` value from `adminUi.order.viewButtons[].id`.
+ * @returns The full Commerce ACL resource id for the view-button leaf node, or an empty string
+ *   when `metadataId` is blank.
+ */
+declare function getOrderViewButtonAclResourceId(metadataId: string, buttonId: string): string;
+//#endregion
+//#region source/order-view-buttons/schema.d.ts
+/**
+ * Schema for the JSON body Commerce POSTs to an order view button handler.
+ *
+ * `id` identifies the specific button that was clicked, letting a single
+ * handler serve multiple buttons by branching on it. `orderId` is the
+ * single order currently being viewed.
+ */
+declare const OrderViewButtonRequestSchema: v.ObjectSchema<{
+  readonly id: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
+  readonly orderId: v.SchemaWithPipe<readonly [v.StringSchema<`Expected a string value for '${string}'`>, v.NonEmptyAction<string, `The value of "${string}" must not be empty`>]>;
+  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/order-view-buttons/types.d.ts
+/** Parsed request body sent by Commerce to an order view button handler. */
+type OrderViewButtonRequest = v.InferOutput<typeof OrderViewButtonRequestSchema>;
+/** Success body returned to Commerce — an empty object signals success. */
+type OrderViewButtonSuccessBody = Record<string, never>;
+/** Failure body returned to Commerce when a worker order view button handler fails. */
+type OrderViewButtonErrorBody = {
+  message: string;
+};
+//#endregion
+//#region source/order-view-buttons/presets.d.ts
+/**
+ * Parses and validates the JSON body Commerce POSTs to an order view button handler.
+ *
+ * Throws a `CommerceSdkValidationError` if the input is malformed.
+ *
+ * @example
+ * ```ts
+ * import { parseOrderViewButtonRequest } from "@adobe/aio-commerce-lib-admin-ui/order-view-buttons";
+ *
+ * export async function main(params: unknown) {
+ *   const { requestId, id, orderId } = parseOrderViewButtonRequest(params);
+ *   // id identifies which button was clicked
+ *   // orderId is the order currently being viewed
+ *   // ...
+ * }
+ * ```
+ */
+declare function parseOrderViewButtonRequest(input: unknown): OrderViewButtonRequest;
+/**
+ * Builds an HTTP 200 success response for an order view button handler.
+ *
+ * Commerce renders `notifications.success` from the registration as the
+ * toast body when present, and a default success toast otherwise.
+ *
+ * @example
+ * ```ts
+ * return okOrderViewButtonResponse();
+ * ```
+ */
+declare function okOrderViewButtonResponse(): SuccessResponse<OrderViewButtonSuccessBody>;
+/**
+ * Builds an error response for a worker order view button 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 orderViewButtonErrorResponse(500, "Could not reach inventory service");
+ * ```
+ */
+declare function orderViewButtonErrorResponse(statusCode: number, errorMessage: string): ErrorResponse<OrderViewButtonErrorBody>;
+//#endregion
+export { type OrderViewButtonErrorBody, type OrderViewButtonRequest, OrderViewButtonRequestSchema, type OrderViewButtonSuccessBody, getOrderViewButtonAclResourceId, okOrderViewButtonResponse, orderViewButtonErrorResponse, parseOrderViewButtonRequest };