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

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 };

package/dist/es/order-view-buttons/index.mjs

@@ -0,0 +1,119 @@
+/**
+ * @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/order-view-buttons/acl-resource-id.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.
+*/
+function getOrderViewButtonAclResourceId(metadataId, buttonId) {
+	const appRoot = getAclResourceId(metadataId);
+	if (appRoot === "") return "";
+	return `${appRoot}_order_viewbuttons_${sanitizeSegment(buttonId)}`;
+}
+
+//#endregion
+//#region source/order-view-buttons/schema.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.
+*/
+const OrderViewButtonRequestSchema = v.object({
+	id: nonEmptyStringValueSchema("id"),
+	orderId: nonEmptyStringValueSchema("orderId"),
+	requestId: nonEmptyStringValueSchema("requestId")
+});
+
+//#endregion
+//#region source/order-view-buttons/presets.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
+*   // ...
+* }
+* ```
+*/
+function parseOrderViewButtonRequest(input) {
+	return parseOrThrow(OrderViewButtonRequestSchema, input, "Invalid order view button request");
+}
+/**
+* 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();
+* ```
+*/
+function okOrderViewButtonResponse() {
+	return ok({ body: {} });
+}
+/**
+* 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");
+* ```
+*/
+function orderViewButtonErrorResponse(statusCode, errorMessage) {
+	return buildErrorResponse(statusCode, { body: { message: errorMessage } });
+}
+
+//#endregion
+export { OrderViewButtonRequestSchema, getOrderViewButtonAclResourceId, okOrderViewButtonResponse, orderViewButtonErrorResponse, parseOrderViewButtonRequest };

package/dist/es/schemas-BFT8ys8P.mjs

@@ -0,0 +1,34 @@
+/**
+ * @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";
+
+//#region ../../packages-private/common-utils/source/valibot/schemas.ts
+/**
+* A schema for a string value.
+* @param name The name of the field this schema refers to.
+*/
+function stringValueSchema(name) {
+	return v.string(`Expected a string value for '${name}'`);
+}
+/**
+* A schema for a non-empty string value.
+* @param name The name of the field this schema refers to.
+*/
+function nonEmptyStringValueSchema(name) {
+	return v.pipe(stringValueSchema(name), v.nonEmpty(`The value of "${name}" must not be empty`));
+}
+
+//#endregion
+export { nonEmptyStringValueSchema as t };

package/dist/es/utils-COPGW1HO.mjs

@@ -0,0 +1,32 @@
+/**
+ * @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 { CommerceSdkValidationError } from "@adobe/aio-commerce-lib-core/error";
+import * as v from "valibot";
+
+//#region ../../packages-private/common-utils/source/valibot/utils.ts
+/**
+* Parses the input using the provided schema and throws a {@link CommerceSdkValidationError} error if the input is invalid.
+* @param schema - The schema to use for parsing.
+* @param input - The input to parse.
+* @param message - Optional custom error message for the validation error.
+*/
+function parseOrThrow(schema, input, message) {
+	const result = v.safeParse(schema, input);
+	if (!result.success) throw new CommerceSdkValidationError(message ?? "Invalid input", { issues: result.issues });
+	return result.output;
+}
+
+//#endregion
+export { parseOrThrow as t };

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

@@ -0,0 +1,192 @@
+/**
+ * @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 { ReactNode } from "react";
+import { NavigateOptions, ToOptions } from "@tanstack/react-router";
+import { attach } from "@adobe/uix-guest";
+
+//#region source/web/react/auth/types.d.ts
+/** The IMS credentials provided by the host (Commerce Admin or Experience Cloud shell). */
+type ImsContext = {
+  imsToken: string;
+  imsOrgId: string;
+};
+//#endregion
+//#region source/web/react/auth/context/ims-context.d.ts
+/**
+ * Returns the IMS credentials provided by the host. Works inside the Commerce Admin and the
+ * Experience Cloud shell.
+ *
+ * @throws If no host provides credentials (e.g. the app is running standalone, outside both the
+ * Commerce Admin and the Experience Cloud shell).
+ */
+declare function useIms(): ImsContext;
+//#endregion
+//#region source/web/react/commerce/types.d.ts
+/** The guest connection that shares the context between the extension and the Admin UI host. */
+type GuestConnection = Awaited<ReturnType<typeof attach>>;
+/**
+ * The Commerce shared context for a mounted Admin UI iframe app.
+ *
+ * This only exists when the app runs inside the Commerce Admin: it is provided by the Commerce UIX
+ * host over the guest connection. It is distinct from the IMS credentials ({@link ImsContext}),
+ * which are also available in the Experience Cloud shell.
+ */
+type SharedContext = {
+  /** The extension ID of the app. */extensionId: string; /** The live `sharedContext` object provided by the host. */
+  sharedContext: NonNullable<GuestConnection["sharedContext"]>; /** The host proxy, used by `useHostConnection` to invoke host-frame actions (close/onError). */
+  host: NonNullable<GuestConnection["host"]>;
+};
+/** Actions for closing the extension iframe and returning control to the Commerce Admin. */
+type HostConnection = {
+  /** Closes the iframe and navigates back to the originating grid or order. */close: () => Promise<void>; /** Closes the iframe and navigates back, flagging the originating page that an error occurred. */
+  closeWithError: () => Promise<void>;
+};
+/** The context shared with mass-action extension points. */
+type MassActionContext = {
+  selectedIds: string[];
+};
+/** The context shared with order view-button extension points. */
+type OrderViewButtonContext = {
+  orderId: string;
+};
+//#endregion
+//#region source/web/react/commerce/context/shared-context.d.ts
+/**
+ * Returns the current Commerce shared context. The guest connection is already established by
+ * the time this can be called (see {@link SharedContextProvider}).
+ *
+ * This is a low-level escape hatch that exposes the raw `sharedContext` and `host` objects.
+ * Prefer a purpose-built hook ({@link useCommerce}, {@link useMassActionContext},
+ * {@link useOrderViewButtonContext}) when one covers what you need.
+ *
+ * @throws If used outside a {@link SharedContextProvider}.
+ *
+ * @example
+ * ```tsx
+ * import { useSharedContext } from "@adobe/aio-commerce-lib-admin-ui/web";
+ *
+ * function ImsTokenLabel() {
+ *   const { sharedContext } = useSharedContext();
+ *   return <span>{sharedContext.get("imsToken")}</span>;
+ * }
+ * ```
+ */
+declare function useSharedContext(): SharedContext;
+//#endregion
+//#region source/web/react/commerce/hooks/use-commerce.d.ts
+/**
+ * Returns the host (domain) of the Commerce Admin the extension is embedded in, resolving it over
+ * the guest connection.
+ *
+ * @throws If used outside a Commerce Admin UI frame, or when the host does not expose the
+ * Commerce integration API.
+ */
+declare function useCommerce(): {
+  commerceHost: string;
+};
+//#endregion
+//#region source/web/react/commerce/hooks/use-extension-context.d.ts
+/**
+ * Returns the context for a mass-action extension point: the selected row IDs the action was
+ * triggered with. The value is read from the host-provided Commerce context.
+ *
+ * @throws If used outside the Commerce shared context, or when that context does not include a
+ * mass-action selection.
+ */
+declare function useMassActionContext(): MassActionContext;
+/**
+ * Returns the context for an order view-button extension point: the order ID the button was
+ * triggered from.
+ *
+ * @throws If no order ID is present in the page URL.
+ */
+declare function useOrderViewButtonContext(): OrderViewButtonContext;
+//#endregion
+//#region source/web/react/commerce/hooks/use-host-connection.d.ts
+/**
+ * Returns typed helpers for interacting with the Commerce Admin host.
+ *
+ * @throws If called before the guest connection is established, or when the host frame actions
+ * are unavailable.
+ *
+ * @example
+ * ```tsx
+ * import { useHostConnection } from "@adobe/aio-commerce-lib-admin-ui/web";
+ *
+ * function DoneButton() {
+ *   const { close } = useHostConnection();
+ *   return <button onClick={() => void close()}>Done</button>;
+ * }
+ * ```
+ */
+declare function useHostConnection(): HostConnection;
+//#endregion
+//#region source/web/react/routing/types.d.ts
+declare module "@react-spectrum/s2/Provider" {
+  interface RouterConfig {
+    href: ToOptions;
+    routerOptions: Omit<NavigateOptions, keyof ToOptions>;
+  }
+}
+/** Defines a route that is marked as the index (entrypoint) */
+type IndexRoute = {
+  index: true; /** The React element to render for the index route. */
+  element: ReactNode;
+};
+/** Defines a route that exists at a given path. */
+type ExtensionRoute = {
+  /** The path for the route. */path: string; /** The React element to render for the route. */
+  element: ReactNode;
+};
+/** Defines the routes for an extension app, which must include at least one index route (first item). */
+type ExtensionAppRoutes = [IndexRoute, ...ExtensionRoute[]];
+//#endregion
+//#region source/web/react/extension/create-app.d.ts
+/** Configuration options when instantiating an extension app. */
+type CreateExtensionAppOptions = {
+  /** General metadata about the extension app. */metadata: {
+    /** The unique identifier for the extension app. */extensionId: string;
+  }; /** Optional root element where the app will be mounted. */
+  root?: HTMLElement; /** A list of routes for the extension app, specifying an index route is mandatory. */
+  routes: ExtensionAppRoutes;
+};
+/**
+ * Mounts a Commerce Admin UI iframe app and handles Experience Cloud Shell, UIX
+ * registration, shared-context attachment, routing, and Spectrum setup.
+ *
+ * The app is wrapped in React's `<StrictMode>`, so in development builds (e.g. when
+ * served via `aio app dev` or `aio app run`) components render twice and effects run
+ * an extra setup + cleanup cycle on mount. Production builds are unaffected.
+ *
+ * @param options - App bootstrap options.
+ *
+ * @example
+ * ```tsx
+ * import { createExtensionApp } from "@adobe/aio-commerce-lib-admin-ui/web";
+ * import { MainPage } from "./pages/main-page.jsx";
+ *
+ * createExtensionApp({
+ *   metadata: { extensionId: "my-extension-id" },
+ *   routes: [{ index: true, element: <MainPage /> }],
+ * });
+ * ```
+ */
+declare function createExtensionApp({
+  metadata,
+  routes,
+  root: customRoot
+}: CreateExtensionAppOptions): void;
+//#endregion
+export { type CreateExtensionAppOptions, type ExtensionAppRoutes, type ExtensionRoute, type HostConnection, type ImsContext, type IndexRoute, type MassActionContext, type OrderViewButtonContext, type SharedContext, createExtensionApp, useCommerce, useHostConnection, useIms, useMassActionContext, useOrderViewButtonContext, useSharedContext };