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

package/dist/cjs/web/index.d.cts

@@ -0,0 +1,206 @@
+/**
+ * @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 { attach } from "@adobe/uix-guest";
+import { NavigateOptions, ToOptions } from "@tanstack/react-router";
+
+//#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/result.d.ts
+/** The result of reading data that might not be available in the current host context. */
+type Result<T, E = Error> = {
+  data: T;
+  error: null;
+} | {
+  data: null;
+  error: E;
+};
+type ActionMap = {
+  [key: string]: (...args: unknown[]) => PromiseLike<unknown>;
+};
+/** The result of exposing an API that might not be available in the current host context. */
+type ActionsResult<T extends ActionMap, E = Error> = {
+  actions: T;
+  error: null;
+} | {
+  actions: null;
+  error: E;
+};
+//#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.
+ *
+ * Returns an error when no host provides credentials.
+ */
+declare function useIms(): Result<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.
+ *
+ * @example
+ * ```tsx
+ * import { useSharedContext } from "@adobe/aio-commerce-lib-admin-ui/web";
+ *
+ * function ImsTokenLabel() {
+ *   const { data, error } = useSharedContext();
+ *   if (error) return null;
+ *   return <span>{data.sharedContext.get("imsToken")}</span>;
+ * }
+ * ```
+ */
+declare function useSharedContext(): Result<SharedContext>;
+//#endregion
+//#region source/web/react/commerce/hooks/use-commerce.d.ts
+type CommerceData = {
+  commerceHost: string;
+};
+/** Drops a failed Commerce host resolution for `extensionId`, so a later render retries it. */
+/**
+ * Returns the host (domain) of the Commerce Admin the extension is embedded in, resolving it over
+ * the guest connection.
+ *
+ * Returns an error when used outside a Commerce Admin UI frame, when the host does not expose the
+ * Commerce integration API, or when resolving the host fails.
+ */
+declare function useCommerce(): Result<CommerceData>;
+//#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.
+ *
+ * Returns an error outside the Commerce shared context, or when the mass-action selection is
+ * missing, empty, or contains a non-string row ID.
+ */
+declare function useMassActionContext(): Result<MassActionContext>;
+/**
+ * Returns the context for an order view-button extension point: the order ID the button was
+ * triggered from.
+ *
+ * Returns an error when no order ID is present in the page URL.
+ */
+declare function useOrderViewButtonContext(): Result<OrderViewButtonContext>;
+//#endregion
+//#region source/web/react/commerce/hooks/use-host-connection.d.ts
+/**
+ * Returns typed helpers for interacting with the Commerce Admin host.
+ *
+ * @example
+ * ```tsx
+ * import { useHostConnection } from "@adobe/aio-commerce-lib-admin-ui/web";
+ *
+ * function DoneButton() {
+ *   const { actions, error } = useHostConnection();
+ *   if (error) return null;
+ *   return <button onClick={actions.close}>Done</button>;
+ * }
+ * ```
+ */
+declare function useHostConnection(): ActionsResult<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 exists at a given path. */
+type ExtensionRoute = {
+  /** The path for the route. */path: string; /** The React element to render for the route. */
+  element: ReactNode;
+};
+//#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;
+  }; /** The optional app page opened from the Commerce Admin menu and by default in Experience Cloud Shell. */
+  menu?: ReactNode; /** Optional root element where the app will be mounted. */
+  root?: HTMLElement; /** Additional path-based routes for the extension app. */
+  routes?: ExtensionRoute[];
+};
+/**
+ * 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" },
+ *   menu: <MainPage />,
+ * });
+ * ```
+ */
+declare function createExtensionApp({
+  menu,
+  metadata,
+  routes,
+  root: customRoot
+}: CreateExtensionAppOptions): void;
+//#endregion
+export { type CreateExtensionAppOptions, type ExtensionRoute, type HostConnection, type ImsContext, type MassActionContext, type OrderViewButtonContext, type SharedContext, createExtensionApp, useCommerce, useHostConnection, useIms, useMassActionContext, useOrderViewButtonContext, useSharedContext };

package/dist/es/acl-resource-id-DBlYU0DE.d.mts

@@ -0,0 +1,39 @@
+/**
+ * @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/api/lib/acl-resource-id.d.ts
+/**
+ * Derives the deterministic Commerce ACL resource id for an app from its metadata id.
+ *
+ * The id is assembled as {@link PREFIX} + sanitized `metadataId`, where sanitization trims
+ * whitespace, lowercases, and replaces every character outside `[a-z0-9_]` with `_`.
+ * `"Magento_CommerceBackendUix::adminuisdk_app_"` is that fixed constant prefix — not a
+ * placeholder — so the example below is fully reproducible from the given argument:
+ *
+ * @example
+ * ```
+ * getAclResourceId("approval-dashboard-app")
+ * // PREFIX                                    + sanitize("approval-dashboard-app")
+ * // "Magento_CommerceBackendUix::adminuisdk_app_" + "approval_dashboard_app"
+ * // → "Magento_CommerceBackendUix::adminuisdk_app_approval_dashboard_app"
+ * ```
+ *
+ * @param metadataId - The application's `metadata.id` value (e.g. `"approval-dashboard-app"`).
+ * @returns The full Commerce ACL resource id, or an empty string when `metadataId` is blank.
+ */
+declare function getAclResourceId(metadataId: string): string;
+/** Commerce entity an Admin UI component is attached to. */
+type AdminUiEntity = "order" | "product" | "customer";
+//#endregion
+export { getAclResourceId as n, AdminUiEntity as t };

package/dist/es/acl-resource-id-pryVxI_c.mjs

@@ -0,0 +1,57 @@
+/**
+ * @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/api/lib/acl-resource-id.ts
+/**
+* Fixed, constant prefix that every Admin UI SDK ACL resource id starts with.
+* It is owned by Commerce and is a stable part of the cross-repo id contract.
+*
+* @internal Exported for use by domain ACL helpers only — not part of the public API.
+*/
+const PREFIX = "Magento_CommerceBackendUix::adminuisdk_app_";
+/**
+* Sanitizes a single ACL id segment: trims whitespace, lowercases, and replaces every
+* character outside [a-z0-9_] with an underscore.
+*
+* @internal Exported for use by domain ACL helpers only — not part of the public API.
+*/
+function sanitizeSegment(segment) {
+	return segment.trim().toLowerCase().replace(/[^a-z0-9_]/g, "_");
+}
+/**
+* Derives the deterministic Commerce ACL resource id for an app from its metadata id.
+*
+* The id is assembled as {@link PREFIX} + sanitized `metadataId`, where sanitization trims
+* whitespace, lowercases, and replaces every character outside `[a-z0-9_]` with `_`.
+* `"Magento_CommerceBackendUix::adminuisdk_app_"` is that fixed constant prefix — not a
+* placeholder — so the example below is fully reproducible from the given argument:
+*
+* @example
+* ```
+* getAclResourceId("approval-dashboard-app")
+* // PREFIX                                    + sanitize("approval-dashboard-app")
+* // "Magento_CommerceBackendUix::adminuisdk_app_" + "approval_dashboard_app"
+* // → "Magento_CommerceBackendUix::adminuisdk_app_approval_dashboard_app"
+* ```
+*
+* @param metadataId - The application's `metadata.id` value (e.g. `"approval-dashboard-app"`).
+* @returns The full Commerce ACL resource id, or an empty string when `metadataId` is blank.
+*/
+function getAclResourceId(metadataId) {
+	if (metadataId.trim() === "") return "";
+	return `${PREFIX}${sanitizeSegment(metadataId)}`;
+}
+
+//#endregion
+export { sanitizeSegment as n, getAclResourceId as t };

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

@@ -0,0 +1,126 @@
+/**
+ * @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 getAclResourceId, t as AdminUiEntity } from "../acl-resource-id-DBlYU0DE.mjs";
+import { CommerceSdkErrorBase, CommerceSdkErrorOptions } from "@adobe/aio-commerce-lib-core/error";
+import { AdobeCommerceHttpClient, CommerceHttpClientParams } from "@adobe/aio-commerce-lib-api";
+import * as v from "valibot";
+
+//#region source/errors.d.ts
+/** Base error for Admin UI SDK permission helper failures. */
+declare class AdminUiPermissionError extends CommerceSdkErrorBase {}
+/** Options for {@link AdminUiPermissionDeniedError}. */
+type AdminUiPermissionDeniedErrorOptions = CommerceSdkErrorOptions;
+/** Error thrown when the current user is denied access to an Admin UI SDK ACL resource. */
+declare class AdminUiPermissionDeniedError extends AdminUiPermissionError {
+  readonly resource: string;
+  constructor(resource: string, options?: AdminUiPermissionDeniedErrorOptions);
+}
+//#endregion
+//#region source/api/lib/api-client.d.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.
+ */
+declare function createAdminUiApiClient(params: CommerceHttpClientParams): import("@adobe/aio-commerce-lib-api").ApiClientRecord<AdobeCommerceHttpClient, {
+  registerExtension(httpClient: AdobeCommerceHttpClient, params: ExtensionRegistrationParams, fetchOptions?: import("ky").Options): Promise<RegisterExtensionResponse>;
+  unregisterExtension(httpClient: AdobeCommerceHttpClient, params: UnregisterExtensionParams, fetchOptions?: import("ky").Options): Promise<void>;
+  enableAdminUiSdk(httpClient: AdobeCommerceHttpClient, fetchOptions?: import("ky").Options): Promise<boolean>;
+}>;
+/**
+ * An API client for the Admin UI API with all operations.
+ * @see {@link createAdminUiApiClient}
+ */
+type AdminUiApiClient = ReturnType<typeof createAdminUiApiClient>;
+//#endregion
+//#region source/api/lib/permission-client.d.ts
+/** Options used to create an Admin UI SDK permission client. */
+type AdminUiPermissionClientOptions = {
+  /** The application's `metadata.id` value. When provided, `check()` and `require()` can be called with no resource argument. */appId?: string;
+  /**
+   * Milliseconds to cache a permission result. Default: 300_000 (5 minutes).
+   * Set to 0 to disable result caching. Note: in-flight deduplication of concurrent identical
+   * requests is independent of this setting and remains active even when caching is disabled.
+   */
+  cacheTtlMs?: number; /** Return false instead of throwing when a network or parse error occurs. Default: true. */
+  denyOnError?: boolean; /** Commerce HTTP client used to call the Admin UI SDK permission endpoint. */
+  httpClient: AdobeCommerceHttpClient;
+};
+/** Client for checking the current user's Admin UI SDK resource permissions. */
+type AdminUiPermissionClient = {
+  /**
+   * Checks whether the current user has the given ACL resource granted.
+   *
+   * @param resource - The ACL resource id to check. When omitted, defaults to the id derived from `appId`.
+   * @returns `true` when granted; `false` when denied, on network or parse errors while `denyOnError` is
+   *   `true` (the default), or immediately when neither `resource` nor a valid `appId` is available.
+   * @throws {@link AdminUiPermissionError} on HTTP 401, regardless of `denyOnError`.
+   */
+  check: (resource?: string) => Promise<boolean>;
+  /**
+   * Clears cached permission results.
+   *
+   * @param resource - The ACL resource id whose cached result to clear. When omitted, clears all cached
+   *   entries and in-flight tracking without aborting outstanding HTTP requests.
+   */
+  invalidate: (resource?: string) => void;
+  /**
+   * Resolves when the current user has the given ACL resource granted.
+   *
+   * @param resource - The ACL resource id to require. When omitted, defaults to the id derived from `appId`.
+   * @throws {@link AdminUiPermissionDeniedError} when the resource is explicitly denied.
+   * @throws {@link AdminUiPermissionError} on HTTP 401, on network or parse errors while `denyOnError` is
+   *   `false`, or immediately when neither `resource` nor a valid `appId` is available.
+   */
+  require: (resource?: string) => Promise<void>;
+};
+/**
+ * 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.
+ */
+declare function getAdminUiPermissionClient(options: AdminUiPermissionClientOptions): AdminUiPermissionClient;
+//#endregion
+//#region source/api/extensions/schema.d.ts
+/** Parameters for POST /V1/adminuisdk/extension. */
+declare const ExtensionRegistrationParamsSchema: v.ObjectSchema<{
+  readonly extensionName: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+  readonly extensionTitle: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+  readonly extensionWorkspace: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+}, undefined>;
+/** Parameters for DELETE /V1/adminuisdk/extension/{workspaceName}/{extensionName}. */
+declare const UnregisterExtensionParamsSchema: v.ObjectSchema<{
+  readonly extensionName: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+  readonly workspaceName: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+}, undefined>;
+/** The parameters accepted by POST /V1/adminuisdk/extension. */
+type ExtensionRegistrationParams = v.InferInput<typeof ExtensionRegistrationParamsSchema>;
+/** The parameters accepted by DELETE /V1/adminuisdk/extension/{workspaceName}/{extensionName}. */
+type UnregisterExtensionParams = v.InferInput<typeof UnregisterExtensionParamsSchema>;
+/** The response returned by POST /V1/adminuisdk/extension. */
+type RegisterExtensionResponse = {
+  extensionId: string;
+};
+//#endregion
+//#region source/api/permissions/schema.d.ts
+/** Response shape returned by the Admin UI SDK permission check endpoint. */
+declare const permissionCheckResponseSchema: v.ObjectSchema<{
+  readonly allowed: v.BooleanSchema<undefined>;
+}, undefined>;
+/** Parsed Admin UI SDK permission check response. */
+type PermissionCheckResponse = v.InferOutput<typeof permissionCheckResponseSchema>;
+//#endregion
+export { AdminUiApiClient, type AdminUiEntity, AdminUiPermissionClient, AdminUiPermissionClientOptions, AdminUiPermissionDeniedError, AdminUiPermissionDeniedErrorOptions, AdminUiPermissionError, type ExtensionRegistrationParams, type ExtensionRegistrationParamsSchema, type PermissionCheckResponse, type RegisterExtensionResponse, type UnregisterExtensionParams, type UnregisterExtensionParamsSchema, createAdminUiApiClient, getAclResourceId, getAdminUiPermissionClient, type permissionCheckResponseSchema };