@rancher/shell 3.0.12-rc.2 → 3.0.12-rc.3

package/apis/impl/apis.ts

@@ -1,6 +1,7 @@
 import { throttle } from 'lodash';
 import { createExtensionManager } from '@shell/core/extension-manager-impl';
 import { ShellApiImpl } from '@shell/apis/shell';
+import { ResourcesApiImpl } from '@shell/apis/resources';
 
 /**
  * Initialise the APIs that are available in the shell
@@ -21,6 +22,11 @@ export function initUiApis(context: any, inject: any, vueApp: any) {
   // Shell API
   // ======================================================================================================================
   registerApi('shell', new ShellApiImpl(context.store), inject, vueApp);
+
+  // ======================================================================================================================
+  // Resources API
+  // ======================================================================================================================
+  registerApi('resources', new ResourcesApiImpl(context.store), inject, vueApp);
 }
 
 // ======================================================================================================================

package/apis/index.ts

@@ -3,11 +3,16 @@
 import { inject } from 'vue';
 import { ExtensionManager } from '@shell/types/extension-manager';
 import { ShellApi as ShellApiImport } from '@shell/apis/intf/shell';
+import { ResourcesApiProvider as ResourcesApiProviderImport } from '@shell/apis/intf/resources';
 
 // Re-export the types for the APIs, so they appear in this module
 export type ShellApi = ShellApiImport;
+export type ResourcesApiProvider = ResourcesApiProviderImport;
 export type ExtensionManagerApi = ExtensionManager;
 
+// Re-export resource types and constants
+export * from '@shell/apis/intf/resources';
+
 /**
  * Returns an object that can be used to access the registered extension manager instance.
  *
@@ -26,6 +31,27 @@ export const useShell = (): ShellApi => {
   return getApi<ShellApi>('$shell', 'useShell');
 };
 
+/**
+ * Returns an object that implements the ResourcesApiProvider interface.
+ * Provides type-safe access to cluster and management resources.
+ *
+ * @returns Returns an object that implements the ResourcesApiProvider interface
+ *
+ * @example
+ * ```ts
+ * import { useResources, K8S } from '@shell/apis';
+ *
+ * // Cluster-scoped resources (current cluster context)
+ * const pod = await resources.cluster.find(K8S.POD, 'default/my-pod-123');
+ *
+ * // Management/global resources
+ * const user = await resources.mgmt.find(K8S.USER, 'u-xyz789');
+ * ```
+ */
+export const useResources = (): ResourcesApiProvider => {
+  return getApi<ResourcesApiProvider>('$resources', 'useResources');
+};
+
 // =================================================================================================================
 // Internal helper to get any API by key with error handling
 // =================================================================================================================

package/apis/intf/resources-api/cluster-api.ts

@@ -0,0 +1,18 @@
+import { ResourcesApi } from './resources-api';
+
+/**
+ * @interface
+ * Provides access to the Cluster API which can be used for managing cluster resources in Rancher UI
+ *
+ * @example
+ * ```ts
+ * import { useResources, K8S } from '@shell/apis';
+ *
+ * // Cluster-scoped resources (current cluster context)
+ * const pod = await resources.cluster.find(K8S.POD, 'default/my-pod-123');
+ *
+ * // Management/global resources
+ * const user = await resources.mgmt.find(K8S.USER, 'u-xyz789');
+ * ```
+ */
+export type ClusterApi = ResourcesApi

package/apis/intf/resources-api/mgmt-api.ts

@@ -0,0 +1,15 @@
+import { ResourcesApi } from './resources-api';
+
+/**
+ * @interface
+ * Provides access to the Management layer in Rancher UI (users, global settings, etc.)
+ *
+ * @example
+ * ```ts
+ * import { useResources, K8S } from '@shell/apis';
+ * const resources = useResources();
+ *
+ * const user = await resources.mgmt.find(K8S.USER, 'u-xyz789');
+ * ```
+ */
+export type MgmtApi = ResourcesApi

package/apis/intf/resources-api/resource-base.ts

@@ -0,0 +1,107 @@
+import { K8SResourceType } from './resource-constants';
+import {
+  ActionFindAllArgs, ActionFindArgs,
+  ActionFindMatchingArgs,
+  ActionFindPageArgs,
+  ActionFindPageResponse, ActionFindMatchingResponse
+} from '@shell/types/store/dashboard-store.types';
+
+/**
+ * @interface
+ * The type of the resource - can be a **string** (for CRDs) or a constant from **{@link K8S}**
+ *
+ * @example
+ * ```ts
+ * import { K8S } from '@shell/apis';
+ *
+ * // Using constants (recommended)
+ * resources.cluster.findAll(K8S.POD);
+ *
+ * // Using strings (for CRDs or dynamic resources)
+ * resources.cluster.findAll('mycompany.io.customresource');
+ * ```
+ */
+export type ResourceType = K8SResourceType | string;
+
+/**
+ * @interface
+ * Resources API "findAll" options
+ */
+export type FindAllMethodOptions = Omit<ActionFindAllArgs, 'hasManualRefresh' | 'depaginate' | 'saveCountAs' | 'incremental'>;
+
+/**
+ * @interface
+ * Resources API "find" options
+ */
+export type FindMethodOptions = Omit<ActionFindArgs, 'invalidatePageCache' | 'method' | 'headers'>;
+
+/**
+ * @interface
+ * Options for `findFiltered` when using label selector matching (label selector mode).
+ *
+ * Filters resources by `labelSelector` (matchLabels / matchExpressions).
+ * The store automatically handles pagination:
+ * - If `ui-sql-cache` is enabled: uses server-side pagination
+ * - Otherwise: uses native Kubernetes API pagination
+ *
+ * @example
+ * ```ts
+ * import { useResources, K8S } from '@shell/apis';
+ *
+ * const resources = useResources();
+ *
+ * const pods = await resources.cluster.findFiltered(K8S.POD, {
+ *   labelSelector: { matchLabels: { type: 'my-type' } }
+ * });
+ * ```
+ */
+export type FindFilteredLabelSelectorOptions = Omit<ActionFindMatchingArgs, 'depaginate'>;
+
+/**
+ * @interface
+ * Options for `findFiltered` when using server-side pagination (pagination mode).
+ *
+ * Requires `pagination` settings for server-side filtering, sorting, and pagination
+ * via the Steve API's pagination cache. **Only available when `ui-sql-cache` is enabled.**
+ *
+ * @example
+ * ```ts
+ * import { useResources, K8S } from '@shell/apis';
+ *
+ * const resources = useResources();
+ *
+ * const pods = await resources.cluster.findFiltered(K8S.POD, {
+ *   pagination: {
+ *     page: 1,
+ *     pageSize: 10,
+ *     projectsOrNamespaces: [],
+ *     filters: [],
+ *     sort: []
+ *   }
+ * });
+ * ```
+ *
+ * See {@link ActionFindPageArgs} for complete pagination options.
+ */
+
+// @internal We use an interface instead of a type alias so the documentation generator
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface FindFilteredPageOptions extends ActionFindPageArgs {}
+
+/**
+ * @interface
+ * Response type for `findFiltered` when using pagination mode.
+ *
+ * Aligns with the response type of the underlying `findPage` store action.
+ * Can be either a transient response object (with data and pagination) or an array of resources.
+ */
+export type FindFilteredPageResponse<T = any> = ActionFindPageResponse<T>;
+
+/**
+ * @interface
+ * Response type for `findFiltered` when using label selector mode.
+ *
+ * Aligns with the response type of the underlying `findMatching` store action via `findLabelSelector`.
+ * Can be either a transient response object (with data and pagination) or an array of resources.
+ */
+export type FindFilteredLabelSelectorResponse<T = any> = ActionFindMatchingResponse<T>;

package/apis/intf/resources-api/resource-constants.ts

@@ -0,0 +1,147 @@
+/**
+ * Resource type constants for Kubernetes and Rancher resources.
+ * Use these constants instead of string literals for type safety and autocomplete.
+ *
+ *
+ * @example
+ * ```ts
+ * import { useResources, K8S } from '@shell/apis';
+ *
+ * const resources = useResources();
+ *
+ * resources.cluster.find(K8S.POD, 'default/my-pod');
+ * resources.cluster.findAll(K8S.DEPLOYMENT);
+ * resources.mgmt.findAll(K8S.USER);
+ * ```
+ */
+
+import {
+  POD,
+  SERVICE,
+  CONFIG_MAP,
+  SECRET,
+  NAMESPACE,
+  NODE,
+  PV,
+  PVC,
+  SERVICE_ACCOUNT,
+  EVENT,
+  ENDPOINTS,
+  LIMIT_RANGE,
+  RESOURCE_QUOTA,
+  WORKLOAD_TYPES,
+  HPA,
+  INGRESS,
+  NETWORK_POLICY,
+  INGRESS_CLASS,
+  RBAC,
+  STORAGE_CLASS,
+  CSI_DRIVER,
+  POD_DISRUPTION_BUDGET,
+  MANAGEMENT,
+} from '@shell/config/types';
+
+/**
+ * Kubernetes core and common resource types
+ */
+export const K8S = {
+  // Core resources
+  /** Kubernetes Pod resource - `pod` */
+  POD,
+  /** Kubernetes Service resource - `service` */
+  SERVICE,
+  /** Kubernetes ConfigMap resource - `configmap` */
+  CONFIG_MAP,
+  /** Kubernetes Secret resource - `secret` */
+  SECRET,
+  /** Kubernetes Namespace resource - `namespace` */
+  NAMESPACE,
+  /** Kubernetes Node resource - `node` */
+  NODE,
+  /** Kubernetes PersistentVolume resource - `persistentvolume` */
+  PV,
+  /** Kubernetes PersistentVolumeClaim resource - `persistentvolumeclaim` */
+  PVC,
+  /** Kubernetes ServiceAccount resource - `serviceaccount` */
+  SERVICE_ACCOUNT,
+  /** Kubernetes Event resource - `event` */
+  EVENT,
+  /** Kubernetes Endpoints resource - `endpoints` */
+  ENDPOINTS,
+  /** Kubernetes LimitRange resource - `limitrange` */
+  LIMIT_RANGE,
+  /** Kubernetes ResourceQuota resource - `resourcequota` */
+  RESOURCE_QUOTA,
+
+  // Apps/Workloads
+  /** Kubernetes Deployment workload - `apps.deployment` */
+  DEPLOYMENT:             WORKLOAD_TYPES.DEPLOYMENT,
+  /** Kubernetes StatefulSet workload - `apps.statefulset` */
+  STATEFUL_SET:           WORKLOAD_TYPES.STATEFUL_SET,
+  /** Kubernetes DaemonSet workload - `apps.daemonset` */
+  DAEMON_SET:             WORKLOAD_TYPES.DAEMON_SET,
+  /** Kubernetes ReplicaSet workload - `apps.replicaset` */
+  REPLICA_SET:            WORKLOAD_TYPES.REPLICA_SET,
+  /** Kubernetes ReplicationController workload - `replicationcontroller` */
+  REPLICATION_CONTROLLER: WORKLOAD_TYPES.REPLICATION_CONTROLLER,
+
+  // Batch
+  /** Kubernetes Job batch resource - `batch.job` */
+  JOB:      WORKLOAD_TYPES.JOB,
+  /** Kubernetes CronJob batch resource - `batch.cronjob` */
+  CRON_JOB: WORKLOAD_TYPES.CRON_JOB,
+
+  // Networking
+  /** Kubernetes Ingress networking resource - `networking.k8s.io.ingress` */
+  INGRESS,
+  /** Kubernetes NetworkPolicy resource - `networking.k8s.io.networkpolicy` */
+  NETWORK_POLICY,
+  /** Kubernetes IngressClass resource - `networking.k8s.io.ingressclass` */
+  INGRESS_CLASS,
+
+  // RBAC
+  /** Kubernetes Role RBAC resource - `rbac.authorization.k8s.io.role` */
+  ROLE:                 RBAC.ROLE,
+  /** Kubernetes RoleBinding RBAC resource - `rbac.authorization.k8s.io.rolebinding` */
+  ROLE_BINDING:         RBAC.ROLE_BINDING,
+  /** Kubernetes ClusterRole RBAC resource - `rbac.authorization.k8s.io.clusterrole` */
+  CLUSTER_ROLE:         RBAC.CLUSTER_ROLE,
+  /** Kubernetes ClusterRoleBinding RBAC resource - `rbac.authorization.k8s.io.clusterrolebinding` */
+  CLUSTER_ROLE_BINDING: RBAC.CLUSTER_ROLE_BINDING,
+
+  // Storage
+  /** Kubernetes StorageClass storage resource - `storage.k8s.io.storageclass` */
+  STORAGE_CLASS,
+  /** Kubernetes CSIDriver storage resource - `storage.k8s.io.csidriver` */
+  CSI_DRIVER,
+
+  // Policy
+  /** Kubernetes PodDisruptionBudget policy resource - `policy.poddisruptionbudget` */
+  POD_DISRUPTION_BUDGET,
+
+  // Autoscaling
+  /** Kubernetes HorizontalPodAutoscaler resource - `autoscaling.horizontalpodautoscaler` */
+  HPA,
+
+  // Management/Rancher resources (public API: https://ranchermanager.docs.rancher.com/api/api-reference)
+  /** Rancher User management resource - `management.cattle.io.user` */
+  USER:                          MANAGEMENT.USER,
+  /** Rancher Project management resource - `management.cattle.io.project` */
+  PROJECT:                       MANAGEMENT.PROJECT,
+  /** Rancher RoleTemplate management resource - `management.cattle.io.roletemplate` */
+  ROLE_TEMPLATE:                 MANAGEMENT.ROLE_TEMPLATE,
+  /** Rancher GlobalRole management resource - `management.cattle.io.globalrole` */
+  GLOBAL_ROLE:                   MANAGEMENT.GLOBAL_ROLE,
+  /** Rancher GlobalRoleBinding management resource - `management.cattle.io.globalrolebinding` */
+  GLOBAL_ROLE_BINDING:           MANAGEMENT.GLOBAL_ROLE_BINDING,
+  /** Rancher ClusterRoleTemplateBinding management resource - `management.cattle.io.clusterroletemplatebinding` */
+  CLUSTER_ROLE_TEMPLATE_BINDING: MANAGEMENT.CLUSTER_ROLE_TEMPLATE_BINDING,
+  /** Rancher ProjectRoleTemplateBinding management resource - `management.cattle.io.projectroletemplatebinding` */
+  PROJECT_ROLE_TEMPLATE_BINDING: MANAGEMENT.PROJECT_ROLE_TEMPLATE_BINDING,
+} as const;
+
+/**
+ * Type helper to extract resource type values from K8S constants.
+ * Check **{@link K8S}** constant documentation
+ */
+export type K8SResourceType = typeof K8S[keyof typeof K8S];

package/apis/intf/resources-api/resources-api.ts

@@ -0,0 +1,143 @@
+import {
+  ResourceType, FindMethodOptions, FindAllMethodOptions, FindFilteredPageOptions, FindFilteredLabelSelectorOptions,
+  FindFilteredPageResponse, FindFilteredLabelSelectorResponse
+} from './resource-base';
+import { SteveListResponse, SteveGetResponse } from '@shell/types/rancher/steve.api';
+
+/**
+ * Base interface for all resource API operations.
+ *
+ * Provides type-safe methods for interacting with Kubernetes and Rancher resources.
+ * Used by both cluster-scoped and management-scoped APIs, and can be extended
+ * by custom store implementations (e.g. Harvester, Epinio).
+ *
+ * @example
+ * ```ts
+ * import { useResources, K8S } from '@shell/apis';
+ *
+ * const resources = useResources();
+ *
+ * const deployment = await resources.cluster.find(K8S.DEPLOYMENT, 'default/my-app');
+ * ```
+ */
+export interface ResourcesApi {
+  /**
+   * Finds a specific resource by its type and ID.
+   *
+   * @template T - The type of the resource (defaults to SteveGetResponse)
+   * @param resourceType - The type of the resource to find (use **{@link K8S}** constant). See also {@link ResourceType}.
+   * @param resourceId - The unique identifier of the resource to find. If the resource is namespaced, this should be in the format `namespace/name`.
+   * @param options - Optional find arguments
+   * @returns The found resource item or null if not found.
+   *
+   * @example
+   * ```ts
+   * import { useResources, K8S } from '@shell/apis';
+   *
+   * const resources = useResources();
+   *
+   * // Namespaced resource - ID must be in "namespace/name" format
+   * const pod = await resources.cluster.find(K8S.POD, 'default/my-pod-123');
+   *
+   * // Cluster-scoped resource - ID is just the name
+   * const node = await resources.cluster.find(K8S.NODE, 'worker-1');
+   * ```
+   */
+  find<T = SteveGetResponse>(
+    resourceType: ResourceType,
+    resourceId: string,
+    options?: FindMethodOptions
+  ): Promise<T | null>;
+
+  /**
+   * Finds resources using pagination mode with server-side filtering, sorting, and pagination.
+   *
+   * Requires `ui-sql-cache` to be enabled.
+   *
+   * @template T - The type of the resources (defaults to SteveListResponse)
+   * @param resourceType - The type of the resources to find (use **{@link K8S}** constant). See also {@link ResourceType}.
+   * @param options - Pagination options with server-side filtering and sorting via the Steve API's pagination cache. See {@link FindFilteredPageOptions}.
+   * @returns Response containing resource items (may be transient if requested, otherwise cached array).
+   * @throws Error if pagination mode is requested but `ui-sql-cache` is not enabled.
+   *
+   * @example
+   * ```ts
+   * import { useResources, K8S } from '@shell/apis';
+   *
+   * const resources = useResources();
+   *
+   * const pods = await resources.cluster.findFiltered(K8S.POD, {
+   *   pagination: {
+   *     page: 1,
+   *     pageSize: 10,
+   *     filters: [],
+   *     sort: []
+   *   }
+   * });
+   * ```
+   */
+  findFiltered<T = SteveListResponse>(
+    resourceType: ResourceType,
+    options: FindFilteredPageOptions
+  ): Promise<FindFilteredPageResponse<T>>;
+
+  /**
+   * Finds resources using label selector matching.
+   *
+   * Filters resources by Kubernetes labels. The store automatically handles pagination:
+   * - If `ui-sql-cache` is enabled: uses server-side pagination
+   * - Otherwise: uses native Kubernetes API pagination
+   *
+   * @template T - The type of the resources (defaults to SteveListResponse)
+   * @param resourceType - The type of the resources to find (use **{@link K8S}** constant). See also {@link ResourceType}.
+   * @param options - Label selector options for filtering. See {@link FindFilteredLabelSelectorOptions}.
+   * @returns Response containing resource items (may be transient if requested, otherwise cached array).
+   *
+   * @example
+   * ```ts
+   * import { useResources, K8S } from '@shell/apis';
+   *
+   * const resources = useResources();
+   *
+   * const pods = await resources.cluster.findFiltered(K8S.POD, {
+   *   labelSelector: { matchLabels: { type: 'my-type' } }
+   * });
+   * ```
+   */
+  findFiltered<T = SteveListResponse>(
+    resourceType: ResourceType,
+    options: FindFilteredLabelSelectorOptions
+  ): Promise<FindFilteredLabelSelectorResponse<T>>;
+
+  /**
+   * @internal Implementation - use one of the overloads above
+   */
+  findFiltered<T = SteveListResponse>(
+    resourceType: ResourceType,
+    options: FindFilteredPageOptions | FindFilteredLabelSelectorOptions
+  ): Promise<FindFilteredPageResponse<T> | FindFilteredLabelSelectorResponse<T>>;
+
+  /**
+   * Fetches all resources of a specific type with advanced options.
+   * This method provides additional capabilities like incremental loading and namespace filtering.
+   *
+   * @template T - The type of the resources (defaults to SteveListResponse)
+   * @param resourceType - The type of the resources to find (use **{@link K8S}** constant). See also {@link ResourceType}.
+   * @param options - Optional advanced fetch options (incremental loading, namespace filtering, etc.)
+   * @returns An array of resource items or an empty array if none are found.
+   *
+   * @example
+   * ```ts
+   * import { useResources, K8S } from '@shell/apis';
+   *
+   * const resources = useResources();
+   * const allPods = await resources.cluster.findAll(K8S.POD, {
+   *   namespaced: ['default', 'kube-system']
+   * });
+   * ```
+   */
+  findAll<T = SteveListResponse>(
+    resourceType: ResourceType,
+    options?: FindAllMethodOptions
+  ): Promise<T[]>;
+}

package/apis/intf/resources.ts

@@ -0,0 +1,49 @@
+
+import { ClusterApi } from '@shell/apis/intf/resources-api/cluster-api';
+import { MgmtApi } from '@shell/apis/intf/resources-api/mgmt-api';
+
+export * from '@shell/apis/intf/resources-api/resources-api';
+export * from '@shell/apis/intf/resources-api/cluster-api';
+export * from '@shell/apis/intf/resources-api/mgmt-api';
+export {
+  ResourceType, FindMethodOptions, FindAllMethodOptions, FindFilteredPageOptions, FindFilteredLabelSelectorOptions,
+  FindFilteredPageResponse, FindFilteredLabelSelectorResponse
+} from '@shell/apis/intf/resources-api/resource-base';
+export * from '@shell/apis/intf/resources-api/resource-constants';
+
+export { SteveGetResponse, SteveListResponse } from '@shell/types/rancher/steve.api';
+export { KubeLabelSelector, KubeLabelSelectorExpression } from '@shell/types/kube/kube-api';
+export {
+  PaginationSort, PaginationParamFilter, PaginationParamProjectOrNamespace, PaginationFilterField
+} from '@shell/types/store/pagination.types';
+
+/**
+ * @internal
+ * Top-level provider that exposes scoped resource API instances.
+ *
+ * @example
+ * ```ts
+ * import { useResources, K8S } from '@shell/apis';
+ *
+ * const resources = useResources();
+ *
+ * // Cluster-scoped resources (current cluster context)
+ * const pod = await resources.cluster.find(K8S.POD, 'default/my-pod-123');
+ *
+ * // Management/global resources
+ * const user = await resources.mgmt.find(K8S.USER, 'u-xyz789');
+ * ```
+ */
+export interface ResourcesApiProvider {
+  /**
+   * Provides access to the Cluster API which can be used for managing Kubernetes cluster resources.
+   * This includes Kubernetes native resources like Pods, Deployments, Services, etc.
+   */
+  get cluster(): ClusterApi;
+
+  /**
+   * Provides access to the Management layer in Rancher UI.
+   * This includes global resources like Users, Clusters, Global Settings, etc.
+   */
+  get mgmt(): MgmtApi;
+}

package/apis/intf/{modal.ts → shell-api/modal.ts}

@@ -17,36 +17,29 @@ export interface ModalConfig {
    * Example with a callback function:
    *
    * ```ts
+   * import { useShell } from '@shell/apis';
    * import MyCustomModal from './MyCustomModal.vue';
    *
-   * export default {
-   *   methods: {
-   *     myAction() {
-   *       console.log('Performed an action');
-   *     },
-   *     showModal() {
-   *       this.$shell.modal.open(MyCustomModal, {
-   *         props: { onConfirm: this.myAction }
-   *       });
-   *     }
-   *   }
+   * const shell = useShell();
+   *
+   * function myAction() {
+   *   console.log('Performed an action');
+   * }
+   *
+   * function showModal() {
+   *   shell.modal.open(MyCustomModal, {
+   *     props: { onConfirm: myAction }
+   *   });
    * }
    * ```
    *
    * ```ts
-   * export default {
-   *   props: {
-   *     onConfirm: {
-   *       type: Function,
-   *       required: true
-   *     }
-   *   },
-   *   methods:.
-   *     confirm() {
-   *       this.onConfirm();
-   *       this.$emit('close');
-   *     }
-   *   }
+   * const props = defineProps<{ onConfirm: () => void }>();
+   * const emit = defineEmits<{ close: [] }>();
+   *
+   * function confirm() {
+   *   props.onConfirm();
+   *   emit('close');
    * }
    * ```
    */
@@ -108,13 +101,15 @@ export interface ModalApi {
    *
    * Example:
    * ```ts
+   * import { useShell } from '@shell/apis';
    * import MyCustomModal from '@/components/MyCustomModal.vue';
    *
-   * this.$shell.modal.open(MyCustomModal, {
+   * const shell = useShell();
+   *
+   * shell.modal.open(MyCustomModal, {
    *   props: { title: 'Hello Modal' }
    * });
    * ```
-   * For usage with the Composition API check usage guide [here](../../shell-api#using-composition-api-in-vue).
    *
    * @param component
    * The Vue component to be displayed inside the modal.