@rancher/shell 3.0.12-rc.4 → 3.0.12-rc.6

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

@@ -3,8 +3,9 @@ import {
   ActionFindAllArgs, ActionFindArgs,
   ActionFindMatchingArgs,
   ActionFindPageArgs,
-  ActionFindPageResponse, ActionFindMatchingResponse
+  ActionFindPageResponse, ActionFindMatchingResponse,
 } from '@shell/types/store/dashboard-store.types';
+import { SteveListResponse, SteveGetResponse } from '@shell/types/rancher/steve.api';
 
 /**
  * @interface
@@ -23,6 +24,30 @@ import {
  */
 export type ResourceType = K8SResourceType | string;
 
+/**
+ * @interface
+ * Data object for creating a new resource. Must include a `type` property.
+ *
+ * @example
+ * ```ts
+ * import { useResources, K8S } from '@shell/apis';
+ *
+ * const resources = useResources();
+ *
+ * const newConfigMap: CreateResourceData = {
+ *   type: K8S.CONFIG_MAP,
+ *   metadata: { name: 'my-config', namespace: 'default' },
+ *   data: { key: 'value' }
+ * };
+ *
+ * await resources.cluster.create(newConfigMap);
+ * ```
+ */
+export type CreateResourceData = {
+  [key: string]: any,
+  type: ResourceType,
+};
+
 /**
  * @interface
  * Resources API "findAll" options
@@ -87,6 +112,7 @@ export type FindFilteredLabelSelectorOptions = Omit<ActionFindMatchingArgs, 'dep
 // @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 {}
+export interface FindFilteredPageOptionsTransient extends ActionFindPageArgs { transient: true }
 
 /**
  * @interface
@@ -104,4 +130,18 @@ export type FindFilteredPageResponse<T = any> = ActionFindPageResponse<T>;
  * 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>;
+export type FindFilteredLabelSelectorResponse<T = Record<string, any>> = ActionFindMatchingResponse<T>;
+
+/**
+ * @interface
+ * Steve API JSON response for GET requests for a resource
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export type SteveResource<T = Record<string, any>> = T & SteveGetResponse;
+
+/**
+ * @interface
+ * Steve API JSON response for LIST resource requests
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export type SteveList<T = Record<string, any>> = SteveListResponse<T & SteveGetResponse>;

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

@@ -0,0 +1,101 @@
+import { SteveResource } from '@shell/apis/intf/resources-api/resource-base';
+
+/**
+ * Instance-level operations available on resources returned by the Resources API.
+ *
+ * These methods operate on a specific resource that has already been fetched.
+ */
+export interface ResourceInstanceApi {
+  /**
+   * Applies a partial update to a resource using HTTP PATCH
+   * with merge-patch semantics (`application/strategic-merge-patch+json`).
+   *
+   * Only the fields provided in `data` are sent to the server — the rest of the resource
+   * remains unchanged. The server response is merged back into this instance.
+   *
+   * Requires edit permissions (`canEdit`).
+   *
+   * @param data - An object containing only the fields to update.
+   * @returns a resource instance, updated with the server response.
+   *
+   * @example
+   * ```ts
+   * import { useResources, K8S } from '@shell/apis';
+   *
+   * const resources = useResources();
+   * const configMap = await resources.cluster.find(K8S.CONFIG_MAP, 'default/my-config');
+   *
+   * await configMap.update({ newKey: 'newValue' });
+   *
+   * const result = configMap.newKey === 'newValue' // true
+
+   * ```
+   */
+  update(data: Record<string, any>): Promise<this>;
+
+  /**
+   * Performs a full replacement update of a resource using HTTP PUT.
+   *
+   * Sends the entire current state of the resource to the server.
+   *
+   * Requires edit permissions (`canEdit`).
+   *
+   * @returns a resource instance, updated with the server response.
+   *
+   * @example
+   * ```ts
+   * import { useResources, K8S } from '@shell/apis';
+   *
+   * const resources = useResources();
+   * const configMap = await resources.cluster.find(K8S.CONFIG_MAP, 'default/my-config');
+   *
+   * configMap.data.myKey = 'updatedValue';
+   * await configMap.replace();
+   * ```
+   */
+  replace(): Promise<this>;
+
+  /**
+   * Deletes a resource instance.
+   *
+   * Requires delete permissions (`canDelete`).
+   *
+   * @returns A promise that resolves when the resource has been deleted.
+   *
+   * @example
+   * ```ts
+   * import { useResources, K8S } from '@shell/apis';
+   *
+   * const resources = useResources();
+   * const pod = await resources.cluster.find(K8S.POD, 'default/my-pod-123');
+   *
+   * await pod.delete();
+   * ```
+   */
+  delete(): Promise<void>;
+}
+
+/**
+ * Represents a single resource instance returned from the Resources API.
+ *
+ * Provides instance-level operations such as deleting or updating a resource instance.
+ * The resource data (metadata, spec, status, etc.) is accessible directly on the instance.
+ *
+ * @template T - Your specific resource type. Rancher will supplement the response with additional properties and methods
+ * @template I - The shape of the underlying resource data (defaults to SteveResource)
+ *
+ * @example
+ * ```ts
+ * import { useResources, K8S } from '@shell/apis';
+ *
+ * const resources = useResources();
+ * const pod = await resources.cluster.find(K8S.POD, 'default/my-pod-123');
+ *
+ * // Access resource data directly
+ * console.log(pod.metadata.name);
+ *
+ * // Use instance operations
+ * await pod.delete();
+ * ```
+ */
+export type ResourceInstance<T = any, I = SteveResource<T>> = I & ResourceInstanceApi;

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

@@ -1,8 +1,10 @@
+import { ActionFindPageTransientResponse } from '@shell/types/store/dashboard-store.types';
 import {
-  ResourceType, FindMethodOptions, FindAllMethodOptions, FindFilteredPageOptions, FindFilteredLabelSelectorOptions,
-  FindFilteredPageResponse, FindFilteredLabelSelectorResponse
+  ResourceType, CreateResourceData, FindMethodOptions, FindAllMethodOptions, FindFilteredPageOptions, FindFilteredLabelSelectorOptions,
+  FindFilteredLabelSelectorResponse, SteveResource,
+  FindFilteredPageOptionsTransient,
 } from './resource-base';
-import { SteveListResponse, SteveGetResponse } from '@shell/types/rancher/steve.api';
+import { ResourceInstance } from './resource-instance';
 
 /**
  * Base interface for all resource API operations.
@@ -24,8 +26,9 @@ 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}.
+   * @template T - Your specific resource type. Rancher will supplement the response with additional properties and methods
+   * @template I - An override for the response type. By default this uses T and supplements the response, or by supplying a value ignores T
+   * @param resourceType - The type of the resource to find (examples in **{@link K8S}**). 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.
@@ -43,21 +46,60 @@ export interface ResourcesApi {
    * const node = await resources.cluster.find(K8S.NODE, 'worker-1');
    * ```
    */
-  find<T = SteveGetResponse>(
+  find<T = Record<string, any>, I = ResourceInstance<T>>(
     resourceType: ResourceType,
     resourceId: string,
     options?: FindMethodOptions
-  ): Promise<T | null>;
+  ): Promise<I | null>;
 
   /**
    * Finds resources using pagination mode with server-side filtering, sorting, and pagination.
    *
+   * The response is not cached
+   *
    * 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}.
+   * @template T - Your specific resource type. Rancher will supplement the response with additional properties and methods
+   * @template I - An override for the response type. By default this uses T and supplements the response, or by supplying a value ignores T
+   * @param resourceType - The type of the resources to find (examples in **{@link K8S}**). 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).
+   * @returns Response containing resource items
+   * @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, {
+   *   transient: true,
+   *   pagination: {
+   *     page: 1,
+   *     pageSize: 10,
+   *     filters: [],
+   *     sort: []
+   *   }
+   * });
+   * ```
+   */
+  findFiltered<T = Record<string, any>, I = ActionFindPageTransientResponse<ResourceInstance<T>>>(
+    resourceType: ResourceType,
+    options: FindFilteredPageOptionsTransient
+  ): Promise<I>;
+
+  /**
+   * Finds resources using pagination mode with server-side filtering, sorting, and pagination.
+   *
+   * The response is cached.
+   *
+   * Requires `ui-sql-cache` to be enabled.
+   *
+   * @template T - Your specific resource type. Rancher will supplement the response with additional properties and methods
+   * @template I - An override for the response type. By default this uses T and supplements the response, or by supplying a value ignores T
+   * @param resourceType - The type of the resources to find (examples in **{@link K8S}**). 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
    * @throws Error if pagination mode is requested but `ui-sql-cache` is not enabled.
    *
    * @example
@@ -76,10 +118,10 @@ export interface ResourcesApi {
    * });
    * ```
    */
-  findFiltered<T = SteveListResponse>(
+  findFiltered<T = Record<string, any>, I = ResourceInstance<T>>(
     resourceType: ResourceType,
     options: FindFilteredPageOptions
-  ): Promise<FindFilteredPageResponse<T>>;
+  ): Promise<I[]>;
 
   /**
    * Finds resources using label selector matching.
@@ -88,8 +130,9 @@ export interface ResourcesApi {
    * - 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}.
+   * @template T - Your specific resource type. Rancher will supplement the response with additional properties and methods
+   * @template I - An override for the response type. By default this uses T and supplements the response, or by supplying a value ignores T
+   * @param resourceType - The type of the resources to find (examples in **{@link K8S}**). 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).
    *
@@ -104,25 +147,26 @@ export interface ResourcesApi {
    * });
    * ```
    */
-  findFiltered<T = SteveListResponse>(
+  findFiltered<T = Record<string, any>, I = FindFilteredLabelSelectorResponse<ResourceInstance<T>>>(
     resourceType: ResourceType,
     options: FindFilteredLabelSelectorOptions
-  ): Promise<FindFilteredLabelSelectorResponse<T>>;
+  ): Promise<I>;
 
   /**
    * @internal Implementation - use one of the overloads above
    */
-  findFiltered<T = SteveListResponse>(
+  findFiltered<T = Record<string, any>, I = ResourceInstance<T>>(
     resourceType: ResourceType,
-    options: FindFilteredPageOptions | FindFilteredLabelSelectorOptions
-  ): Promise<FindFilteredPageResponse<T> | FindFilteredLabelSelectorResponse<T>>;
+    options: FindFilteredPageOptions | FindFilteredPageOptionsTransient | FindFilteredLabelSelectorOptions
+  ): Promise<I[] | ResourceInstance<T>[] | ActionFindPageTransientResponse<ResourceInstance<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}.
+   * @template T - Your specific resource type. Rancher will supplement the response with additional properties and methods
+   * @template I - An override for the response type. By default this uses T and supplements the response, or by supplying a value ignores T
+   * @param resourceType - The type of the resources to find (examples in **{@link K8S}**). 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.
    *
@@ -136,8 +180,118 @@ export interface ResourcesApi {
    * });
    * ```
    */
-  findAll<T = SteveListResponse>(
+  findAll<T = Record<string, any>, I = ResourceInstance<T>>(
     resourceType: ResourceType,
     options?: FindAllMethodOptions
-  ): Promise<T[]>;
+  ): Promise<I[]>;
+
+  /**
+   * Creates a new resource.
+   *
+   * The `data` object must include a `type` property identifying the resource type.
+   * This is a raw HTTP operation — it does not check permissions or update the store cache.
+   *
+   * @template T - Your specific resource type. Rancher will supplement the response with additional properties and methods
+   * @template I - An override for the response type. By default this uses T and supplements the response, or by supplying a value ignores T
+   * @param data - The resource data to create. Must include a `type` property (examples in **{@link K8S}**). See also {@link CreateResourceData}.
+   * @returns The created resource instance.
+   *
+   * @example
+   * ```ts
+   * import { useResources, K8S } from '@shell/apis';
+   *
+   * const resources = useResources();
+   *
+   * const configMap = await resources.cluster.create({
+   *   type:     K8S.CONFIG_MAP,
+   *   metadata: { name: 'my-config', namespace: 'default' },
+   *   data:     { key: 'value' }
+   * });
+   * ```
+   */
+  create<T = Record<string, any>, I = SteveResource<T>>(
+    data: CreateResourceData
+  ): Promise<I>;
+
+  /**
+   * Applies a partial update to a resource using HTTP PATCH (merge-patch).
+   *
+   * Only the fields provided in `data` are sent to the server.
+   * This is a raw HTTP operation — it does not check permissions or update the store cache.
+   *
+   * @template T - Your specific resource type. Rancher will supplement the response with additional properties and methods
+   * @template I - An override for the response type. By default this uses T and supplements the response, or by supplying a value ignores T
+   * @param resourceType - The type of the resource (examples in **{@link K8S}**). See also {@link ResourceType}.
+   * @param resourceId - The unique identifier. If namespaced, use `namespace/name` format.
+   * @param data - An object containing only the fields to update.
+   * @returns The server response.
+   *
+   * @example
+   * ```ts
+   * import { useResources, K8S } from '@shell/apis';
+   *
+   * const resources = useResources();
+   *
+   * const result = await resources.cluster.update(K8S.CONFIG_MAP, 'default/my-config', {
+   *   someField: { newKey: 'newValue' }
+   * });
+   * ```
+   */
+  update<T = Record<string, any>, I = SteveResource<T>>(
+    resourceType: ResourceType,
+    resourceId: string,
+    data: Record<string, any>
+  ): Promise<I>;
+
+  /**
+   * Performs a full replacement update of a resource using HTTP PUT.
+   *
+   * Runs `cleanForSave` on the data before sending.
+   * This is a raw HTTP operation — it does not check permissions or update the store cache.
+   *
+   * @template T - Your specific resource type. Rancher will supplement the response with additional properties and methods
+   * @template I - An override for the response type. By default this uses T and supplements the response, or by supplying a value ignores T
+   * @param resourceType - The type of the resource (examples in **{@link K8S}**). See also {@link ResourceType}.
+   * @param resourceId - The unique identifier. If namespaced, use `namespace/name` format.
+   * @param data - The complete resource data to send as the replacement.
+   * @returns The server response.
+   *
+   * @example
+   * ```ts
+   * import { useResources, K8S } from '@shell/apis';
+   *
+   * const resources = useResources();
+   * const configMapData = await resources.cluster.find(K8S.CONFIG_MAP, 'default/my-config');
+   * configMapData.someField = { newKey: 'newValue' };
+   *
+   * const result = await resources.cluster.replace(K8S.CONFIG_MAP, 'default/my-config', configMapData);
+   * ```
+   */
+  replace<T = Record<string, any>, I = SteveResource<T>>(
+    resourceType: ResourceType,
+    resourceId: string,
+    data: Record<string, any>
+  ): Promise<I>;
+
+  /**
+   * Deletes a resource by type and ID using HTTP DELETE.
+   *
+   * This is a raw HTTP operation — it does not check permissions or update the store cache.
+   *
+   * @param resourceType - The type of the resource (examples in **{@link K8S}**). See also {@link ResourceType}.
+   * @param resourceId - The unique identifier. If namespaced, use `namespace/name` format.
+   *
+   * @example
+   * ```ts
+   * import { useResources, K8S } from '@shell/apis';
+   *
+   * const resources = useResources();
+   *
+   * await resources.cluster.delete(K8S.CONFIG_MAP, 'default/my-config');
+   * ```
+   */
+  delete(
+    resourceType: ResourceType,
+    resourceId: string
+  ): Promise<void>;
 }

package/apis/intf/resources.ts

@@ -5,16 +5,18 @@ 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
+export type {
+  ResourceType, CreateResourceData, FindMethodOptions, FindAllMethodOptions, FindFilteredPageOptions, FindFilteredLabelSelectorOptions,
+  FindFilteredPageResponse, FindFilteredLabelSelectorResponse, SteveResource, SteveList
 } 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 * from '@shell/apis/intf/resources-api/resource-instance';
+
+export type { KubeLabelSelector, KubeLabelSelectorExpression } from '@shell/types/kube/kube-api';
+export type { PaginationSort } from '@shell/types/store/pagination.types';
 export {
-  PaginationSort, PaginationParamFilter, PaginationParamProjectOrNamespace, PaginationFilterField
+  PaginationParamFilter, PaginationParamProjectOrNamespace, PaginationFilterField
 } from '@shell/types/store/pagination.types';
 
 /**