@espressif/rainmaker-admin-sdk 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -3,6 +3,32 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and follows the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.
 
+## [1.3.1] - 2026-10-07
+
+Patch release that corrects the OTA job list types in `ESPRMAdminOTAJob.getJob`
+to match what the backend accepts and returns. No runtime behaviour changes:
+the SDK already forwarded every query parameter and returned the backend's
+response as-is. Only the types were wrong.
+
+### Added
+
+- `GetOTAJobParams` now declares the filters the backend accepts:
+  `ota_job_name` (case-sensitive "contains" search), `ota_image_id`,
+  `archived` and `all`. Callers no longer need a cast to search.
+- `GetOTAJobsResponse.otaJobs`, the key the backend actually returns the job
+  list under.
+- `GetOTAJobByIdParams` and a `getJob({ ota_job_id })` overload that returns
+  `OTAJobInfo`. The backend answers an ID lookup with the job itself, not a
+  list.
+
+### Deprecated
+
+- `GetOTAJobsResponse.ota_update_jobs` and `GetOTAJobsResponse.total`. The
+  backend has never returned either; read `otaJobs` instead. Both will be
+  removed in the next minor release.
+- `GetOTAJobParams.ota_job_id`. Pass `GetOTAJobByIdParams` to get the
+  correctly typed single-job response.
+
 ## [1.3.0] - 2026-10-06
 
 Minor release that adds node deletion, node claiming through the standalone

package/dist/types/methods/ESPRMAdminOTAJob/GetJob.d.ts

@@ -3,12 +3,21 @@
  *
  * SPDX-License-Identifier: Apache-2.0
  */
-import { GetOTAJobParams } from "../../types/ota.js";
-import { GetOTAJobsResponse } from "../../types/ota.js";
+import { GetOTAJobByIdParams, GetOTAJobParams, GetOTAJobsResponse, OTAJobInfo } from "../../types/ota.js";
 declare module "../../ESPRMAdminOTAJob.js" {
     interface ESPRMAdminOTAJob {
         /**
-         * Retrieves OTA jobs with optional filtering parameters.
+         * Retrieves a single OTA job by ID.
+         *
+         * @param params - The ID of the job to fetch.
+         * @returns The OTA job. The backend returns the job itself, not a list.
+         */
+        getJob(params: GetOTAJobByIdParams): Promise<OTAJobInfo>;
+        /**
+         * Retrieves a page of OTA jobs, optionally filtered by name or image.
+         *
+         * When nothing matches, the backend rejects with HTTP 404 and error code
+         * `105012` rather than returning an empty list.
          *
          * @param params - Optional query parameters to filter the job list.
          * @returns The list of OTA jobs matching the specified criteria.

package/dist/types/types/input.d.ts

@@ -8,7 +8,7 @@ export type { ESPRMBaseConfig, ESPRMAPIManagerConfig, UserTokensData } from "./c
 export type { SignUpRequest, ConfirmUserRequest, ChangePasswordRequest, ForgotPasswordRequest, ForgotPasswordConfirmRequest, LogoutRequest, UpdateUserProfileRequest, DeleteAccountParams, } from "./auth.js";
 export type { CreateAdminUserRequest, UpdateAdminUserRequest, GetAdminUsersParams, DeleteAdminUserParams, } from "./admin_user.js";
 export type { GetAdminNodesParams, ActivateDeactivateNodesParams, GetNodeTagsParams, NodeAttachTagsRequest, } from "./node.js";
-export type { CreateOTAImageRequest, GetOTAImagesParams, ArchiveOTAImageParams, DeleteOTAImageParams, GetOTAImageUploadUrlParams, ConfirmOTAImageUploadRequest, GetOTAPackageUploadUrlParams, ConfirmOTAPackageUploadRequest, CreateOTAJobRequest, CreateOTAJobQueryOptions, OtaJobDownloadWindow, OtaJobValidity, OtaJobMetadata, OtaSecureBoot, OtaNetworkSerialisation, GetOTAJobParams, UpdateOTAJobParams, CancelOTAJobRequest, ArchiveOTAJobRequest, GetOTAJobStatusParams, GetOTAJobStatusSummaryParams, RetriggerOTAJobRequest, } from "./ota.js";
+export type { CreateOTAImageRequest, GetOTAImagesParams, ArchiveOTAImageParams, DeleteOTAImageParams, GetOTAImageUploadUrlParams, ConfirmOTAImageUploadRequest, GetOTAPackageUploadUrlParams, ConfirmOTAPackageUploadRequest, CreateOTAJobRequest, CreateOTAJobQueryOptions, OtaJobDownloadWindow, OtaJobValidity, OtaJobMetadata, OtaSecureBoot, OtaNetworkSerialisation, GetOTAJobParams, GetOTAJobByIdParams, UpdateOTAJobParams, CancelOTAJobRequest, ArchiveOTAJobRequest, GetOTAJobStatusParams, GetOTAJobStatusSummaryParams, RetriggerOTAJobRequest, } from "./ota.js";
 export type { CreateAdminGroupRequest, UpdateAdminGroupRequest, GetAdminGroupsParams, } from "./group.js";
 export type { GetAdminTagsParams, AttachDetachTagsParams, GetTagNamesParams, } from "./tag.js";
 export type { GetCommandRequestsParams, AddCommandRequestBody, CancelCommandRequestsParams, CommandRequestStatus, } from "./command_response.js";

package/dist/types/types/ota.d.ts

@@ -159,14 +159,40 @@ export interface CreateOTAJobQueryOptions {
     /** Serialise OTA delivery per local network. */
     network_serialised?: boolean;
 }
-/** Parameters for listing OTA jobs. */
+/**
+ * Parameters for listing or searching OTA jobs.
+ *
+ * Without a filter the backend returns a page of jobs, scoped by `archived`
+ * and `all`. `ota_job_name` and `ota_image_id` switch it to a search.
+ */
 export interface GetOTAJobParams {
-    /** Filter by specific OTA job ID. */
+    /**
+     * Filter by specific OTA job ID.
+     *
+     * @deprecated The backend answers an ID lookup with a single job, not a
+     * list. Pass {@link GetOTAJobByIdParams} so `getJob` returns `OTAJobInfo`.
+     */
     ota_job_id?: string;
-    /** Maximum number of records to return. */
+    /**
+     * Return jobs whose name contains this text. Case-sensitive. Covers archived
+     * and unarchived jobs alike: `archived` and `all` are ignored.
+     */
+    ota_job_name?: string;
+    /** Return every job created from this OTA image. Honours `archived`. */
+    ota_image_id?: string;
+    /** Maximum number of records to return (backend default and maximum: 25). */
     num_records?: string;
-    /** Job ID to start pagination from. */
+    /** Job ID to start pagination from (the previous page's `next_id`). */
     start_id?: string;
+    /** List archived jobs instead of unarchived ones. Defaults to `false`. */
+    archived?: boolean;
+    /** List archived and unarchived jobs together. Defaults to `false`. */
+    all?: boolean;
+}
+/** Parameters for fetching a single OTA job by ID. */
+export interface GetOTAJobByIdParams {
+    /** ID of the OTA job to fetch. */
+    ota_job_id: string;
 }
 /** Parameters for updating an OTA job. */
 export interface UpdateOTAJobParams {
@@ -368,11 +394,19 @@ export interface OTAJobRetriggerResponse {
 }
 /** Paginated response containing a list of OTA jobs. */
 export interface GetOTAJobsResponse {
-    /** List of OTA job objects. */
-    ota_update_jobs?: OTAJobInfo[];
-    /** ID to use for fetching the next page. */
+    /** OTA jobs on this page. */
+    otaJobs?: OTAJobInfo[];
+    /** ID to use for fetching the next page. Absent on the last page. */
     next_id?: string;
-    /** Total number of jobs matching the query. */
+    /**
+     * @deprecated Never returned by the backend; read `otaJobs` instead.
+     * Will be removed in the next minor release.
+     */
+    ota_update_jobs?: OTAJobInfo[];
+    /**
+     * @deprecated Never returned by the backend. Will be removed in the next
+     * minor release.
+     */
     total?: number;
 }
 /** Per-node OTA status row (GET admin/otajob/status). */

package/dist/types-cjs/methods/ESPRMAdminOTAJob/GetJob.d.cts

@@ -3,12 +3,21 @@
  *
  * SPDX-License-Identifier: Apache-2.0
  */
-import { GetOTAJobParams } from "../../types/ota.cjs";
-import { GetOTAJobsResponse } from "../../types/ota.cjs";
+import { GetOTAJobByIdParams, GetOTAJobParams, GetOTAJobsResponse, OTAJobInfo } from "../../types/ota.cjs";
 declare module "../../ESPRMAdminOTAJob.cjs" {
     interface ESPRMAdminOTAJob {
         /**
-         * Retrieves OTA jobs with optional filtering parameters.
+         * Retrieves a single OTA job by ID.
+         *
+         * @param params - The ID of the job to fetch.
+         * @returns The OTA job. The backend returns the job itself, not a list.
+         */
+        getJob(params: GetOTAJobByIdParams): Promise<OTAJobInfo>;
+        /**
+         * Retrieves a page of OTA jobs, optionally filtered by name or image.
+         *
+         * When nothing matches, the backend rejects with HTTP 404 and error code
+         * `105012` rather than returning an empty list.
          *
          * @param params - Optional query parameters to filter the job list.
          * @returns The list of OTA jobs matching the specified criteria.

package/dist/types-cjs/types/input.d.cts

@@ -8,7 +8,7 @@ export type { ESPRMBaseConfig, ESPRMAPIManagerConfig, UserTokensData } from "./c
 export type { SignUpRequest, ConfirmUserRequest, ChangePasswordRequest, ForgotPasswordRequest, ForgotPasswordConfirmRequest, LogoutRequest, UpdateUserProfileRequest, DeleteAccountParams, } from "./auth.cjs";
 export type { CreateAdminUserRequest, UpdateAdminUserRequest, GetAdminUsersParams, DeleteAdminUserParams, } from "./admin_user.cjs";
 export type { GetAdminNodesParams, ActivateDeactivateNodesParams, GetNodeTagsParams, NodeAttachTagsRequest, } from "./node.cjs";
-export type { CreateOTAImageRequest, GetOTAImagesParams, ArchiveOTAImageParams, DeleteOTAImageParams, GetOTAImageUploadUrlParams, ConfirmOTAImageUploadRequest, GetOTAPackageUploadUrlParams, ConfirmOTAPackageUploadRequest, CreateOTAJobRequest, CreateOTAJobQueryOptions, OtaJobDownloadWindow, OtaJobValidity, OtaJobMetadata, OtaSecureBoot, OtaNetworkSerialisation, GetOTAJobParams, UpdateOTAJobParams, CancelOTAJobRequest, ArchiveOTAJobRequest, GetOTAJobStatusParams, GetOTAJobStatusSummaryParams, RetriggerOTAJobRequest, } from "./ota.cjs";
+export type { CreateOTAImageRequest, GetOTAImagesParams, ArchiveOTAImageParams, DeleteOTAImageParams, GetOTAImageUploadUrlParams, ConfirmOTAImageUploadRequest, GetOTAPackageUploadUrlParams, ConfirmOTAPackageUploadRequest, CreateOTAJobRequest, CreateOTAJobQueryOptions, OtaJobDownloadWindow, OtaJobValidity, OtaJobMetadata, OtaSecureBoot, OtaNetworkSerialisation, GetOTAJobParams, GetOTAJobByIdParams, UpdateOTAJobParams, CancelOTAJobRequest, ArchiveOTAJobRequest, GetOTAJobStatusParams, GetOTAJobStatusSummaryParams, RetriggerOTAJobRequest, } from "./ota.cjs";
 export type { CreateAdminGroupRequest, UpdateAdminGroupRequest, GetAdminGroupsParams, } from "./group.cjs";
 export type { GetAdminTagsParams, AttachDetachTagsParams, GetTagNamesParams, } from "./tag.cjs";
 export type { GetCommandRequestsParams, AddCommandRequestBody, CancelCommandRequestsParams, CommandRequestStatus, } from "./command_response.cjs";

package/dist/types-cjs/types/ota.d.cts

@@ -159,14 +159,40 @@ export interface CreateOTAJobQueryOptions {
     /** Serialise OTA delivery per local network. */
     network_serialised?: boolean;
 }
-/** Parameters for listing OTA jobs. */
+/**
+ * Parameters for listing or searching OTA jobs.
+ *
+ * Without a filter the backend returns a page of jobs, scoped by `archived`
+ * and `all`. `ota_job_name` and `ota_image_id` switch it to a search.
+ */
 export interface GetOTAJobParams {
-    /** Filter by specific OTA job ID. */
+    /**
+     * Filter by specific OTA job ID.
+     *
+     * @deprecated The backend answers an ID lookup with a single job, not a
+     * list. Pass {@link GetOTAJobByIdParams} so `getJob` returns `OTAJobInfo`.
+     */
     ota_job_id?: string;
-    /** Maximum number of records to return. */
+    /**
+     * Return jobs whose name contains this text. Case-sensitive. Covers archived
+     * and unarchived jobs alike: `archived` and `all` are ignored.
+     */
+    ota_job_name?: string;
+    /** Return every job created from this OTA image. Honours `archived`. */
+    ota_image_id?: string;
+    /** Maximum number of records to return (backend default and maximum: 25). */
     num_records?: string;
-    /** Job ID to start pagination from. */
+    /** Job ID to start pagination from (the previous page's `next_id`). */
     start_id?: string;
+    /** List archived jobs instead of unarchived ones. Defaults to `false`. */
+    archived?: boolean;
+    /** List archived and unarchived jobs together. Defaults to `false`. */
+    all?: boolean;
+}
+/** Parameters for fetching a single OTA job by ID. */
+export interface GetOTAJobByIdParams {
+    /** ID of the OTA job to fetch. */
+    ota_job_id: string;
 }
 /** Parameters for updating an OTA job. */
 export interface UpdateOTAJobParams {
@@ -368,11 +394,19 @@ export interface OTAJobRetriggerResponse {
 }
 /** Paginated response containing a list of OTA jobs. */
 export interface GetOTAJobsResponse {
-    /** List of OTA job objects. */
-    ota_update_jobs?: OTAJobInfo[];
-    /** ID to use for fetching the next page. */
+    /** OTA jobs on this page. */
+    otaJobs?: OTAJobInfo[];
+    /** ID to use for fetching the next page. Absent on the last page. */
     next_id?: string;
-    /** Total number of jobs matching the query. */
+    /**
+     * @deprecated Never returned by the backend; read `otaJobs` instead.
+     * Will be removed in the next minor release.
+     */
+    ota_update_jobs?: OTAJobInfo[];
+    /**
+     * @deprecated Never returned by the backend. Will be removed in the next
+     * minor release.
+     */
     total?: number;
 }
 /** Per-node OTA status row (GET admin/otajob/status). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@espressif/rainmaker-admin-sdk",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Espressif's Rainmaker Admin SDK enables seamless integration of admin applications with the ESP Rainmaker ecosystem.",
   "license": "Apache-2.0",
   "author": "Espressif Systems (Shanghai) CO LTD",