implement resources API part 2

docusaurus/docs/extensions/resources-api.md

@@ -101,3 +101,4 @@ const customResources = await resources.cluster.findFiltered('mycompany.io.custo
 | :--- | :--- |
 | [Cluster API](./resources-api/interfaces/ClusterApi) | Interact with cluster-scoped Kubernetes resources (Pods, Deployments, Services, etc.) |
 | [Management API](./resources-api/interfaces/MgmtApi) | Interact with global Rancher resources (Users, Clusters, Settings, etc.) |
+| [Resource Instance API](./resources-api/interfaces/ResourceInstanceApi) | Interact any given Kubernetes resource instance |

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

@@ -23,6 +23,25 @@ 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();
+ *
+ * await resources.cluster.create({
+ *   type: K8S.CONFIG_MAP,
+ *   metadata: { name: 'my-config', namespace: 'default' },
+ *   data: { key: 'value' }
+ * });
+ * ```
+ */
+export type CreateResourceData = { type: ResourceType } & Record<string, any>;
+
 /**
  * @interface
  * Resources API "findAll" options

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

@@ -0,0 +1,96 @@
+import { SteveGetResponse } from '@shell/types/rancher/steve.api';
+
+/**
+ * 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 (merge-patch).
+   *
+   * 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.patch({ newKey: 'newValue' });
+   * ```
+   */
+  patch(data: Record<string, any>): Promise<ResourceInstanceApi>;
+
+  /**
+   * 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.update();
+   * ```
+   */
+  update(): Promise<ResourceInstanceApi>;
+
+  /**
+   * 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 - The shape of the underlying resource data (defaults to SteveGetResponse)
+ *
+ * @example
+ * ```ts
+ * import { useResources, K8S } from '@shell/apis';
+ *
+ * const resources = useResources();
+ * const pod = await resources.cluster.find(K8S.POD, 'my-pod-123');
+ *
+ * // Access resource data directly
+ * console.log(pod.metadata.name);
+ *
+ * // Use instance operations
+ * await pod.delete();
+ * ```
+ */
+export type ResourceInstance<T = SteveGetResponse> = T & ResourceInstanceApi;

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

@@ -1,8 +1,9 @@
 import {
-  ResourceType, FindMethodOptions, FindAllMethodOptions, FindFilteredPageOptions, FindFilteredLabelSelectorOptions,
+  ResourceType, CreateResourceData, FindMethodOptions, FindAllMethodOptions, FindFilteredPageOptions, FindFilteredLabelSelectorOptions,
   FindFilteredPageResponse, FindFilteredLabelSelectorResponse
 } from './resource-base';
-import { SteveListResponse, SteveGetResponse } from '@shell/types/rancher/steve.api';
+import { ResourceInstance } from './resource-instance';
+import { SteveListResponse } from '@shell/types/rancher/steve.api';
 
 /**
  * Base interface for all resource API operations.
@@ -24,7 +25,7 @@ export interface ResourcesApi {
   /**
    * Finds a specific resource by its type and ID.
    *
-   * @template T - The type of the resource (defaults to SteveGetResponse)
+   * @template T - The type of the resource (defaults to ResourceInstance)
    * @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
@@ -43,7 +44,7 @@ export interface ResourcesApi {
    * const node = await resources.cluster.find(K8S.NODE, 'worker-1');
    * ```
    */
-  find<T = SteveGetResponse>(
+  find<T = ResourceInstance>(
     resourceType: ResourceType,
     resourceId: string,
     options?: FindMethodOptions
@@ -54,7 +55,7 @@ export interface ResourcesApi {
    *
    * Requires `ui-sql-cache` to be enabled.
    *
-   * @template T - The type of the resources (defaults to SteveListResponse)
+   * @template T - The type of the resources (defaults to ResourceInstance)
    * @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).
@@ -140,4 +141,113 @@ export interface ResourcesApi {
     resourceType: ResourceType,
     options?: FindAllMethodOptions
   ): Promise<T[]>;
+
+  /**
+   * Creates a new resource.
+   *
+   * The `data` object must include a `type` property identifying the resource type.
+   * Checks `canCreate` permissions before saving.
+   *
+   * @template T - The type of the resource (defaults to ResourceInstance)
+   * @param data - The resource data to create. Must include a `type` property (use **{@link K8S}** constant). 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 = ResourceInstance>(
+    data: CreateResourceData
+  ): Promise<T>;
+
+  /**
+   * 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 - The type of the response (defaults to ResourceInstance)
+   * @param resourceType - The type of the resource (use **{@link K8S}** constant). 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.patch(K8S.CONFIG_MAP, 'default/my-config', {
+   *   data: { newKey: 'newValue' }
+   * });
+   * ```
+   */
+  patch<T = ResourceInstance>(
+    resourceType: ResourceType,
+    resourceId: string,
+    data: Record<string, any>
+  ): Promise<T>;
+
+  /**
+   * 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 - The type of the response (defaults to ResourceInstance)
+   * @param resourceType - The type of the resource (use **{@link K8S}** constant). 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 result = await resources.cluster.update(K8S.CONFIG_MAP, 'default/my-config', {
+   *   type:     'configmap',
+   *   metadata: { name: 'my-config', namespace: 'default', resourceVersion: '12345' },
+   *   data:     { key: 'replacedValue' }
+   * });
+   * ```
+   */
+  update<T = ResourceInstance>(
+    resourceType: ResourceType,
+    resourceId: string,
+    data: Record<string, any>
+  ): Promise<T>;
+
+  /**
+   * 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 (use **{@link K8S}** constant). 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>;
 }

shell/apis/intf/resources.ts

@@ -6,11 +6,13 @@ 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,
+  ResourceType, CreateResourceData, FindMethodOptions, FindAllMethodOptions, FindFilteredPageOptions, FindFilteredLabelSelectorOptions,
   FindFilteredPageResponse, FindFilteredLabelSelectorResponse
 } from '@shell/apis/intf/resources-api/resource-base';
 export * from '@shell/apis/intf/resources-api/resource-constants';
 
+export * from '@shell/apis/intf/resources-api/resource-instance';
+
 export { SteveGetResponse, SteveListResponse } from '@shell/types/rancher/steve.api';
 export { KubeLabelSelector, KubeLabelSelectorExpression } from '@shell/types/kube/kube-api';
 export {