@espressif/rainmaker-admin-sdk 1.0.0 → 1.1.0

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

@@ -3,16 +3,20 @@
  *
  * SPDX-License-Identifier: Apache-2.0
  */
-import { RetriggerOTAJobRequest } from "../../types/ota.js";
-import { ESPAPISuccessResponse } from "../../types/api.js";
+import { OTAJobRetriggerResponse, RetriggerOTAJobRequest } from "../../types/ota.js";
 declare module "../../ESPRMAdminOTAJob.js" {
     interface ESPRMAdminOTAJob {
         /**
-         * Retriggers a previously created OTA job for failed or pending nodes.
+         * Retriggers an OTA job, pushing it again to every node still pending.
+         *
+         * The backend rejects this for jobs that are not active, that have expired,
+         * that require user approval, or that were created with an auto-selected
+         * signing key. Delivery is dispatched asynchronously, so a success means
+         * the retrigger was accepted, not that any node has received it.
          *
          * @param params - Parameters including the OTA job ID to retrigger.
-         * @returns A success response confirming the job was retriggered.
+         * @returns The job ID and the status of the retrigger operation.
          */
-        retriggerJob(params: RetriggerOTAJobRequest): Promise<ESPAPISuccessResponse>;
+        retriggerJob(params: RetriggerOTAJobRequest): Promise<OTAJobRetriggerResponse>;
     }
 }

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

@@ -6,7 +6,8 @@
 import "./CreateJob.js";
 import "./GetJob.js";
 import "./UpdateJob.js";
-import "./DeleteJob.js";
+import "./CancelJob.js";
+import "./ArchiveJob.js";
 import "./GetJobStatus.js";
 import "./GetJobStatusSummary.js";
 import "./RetriggerJob.js";

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, GetOTAImageUploadUrlParams, ConfirmOTAImageUploadRequest, GetOTAPackageUploadUrlParams, ConfirmOTAPackageUploadRequest, CreateOTAJobRequest, CreateOTAJobQueryOptions, OtaJobDownloadWindow, OtaJobValidity, OtaJobMetadata, OtaSecureBoot, OtaNetworkSerialisation, GetOTAJobParams, UpdateOTAJobParams, GetOTAJobStatusParams, GetOTAJobStatusSummaryParams, RetriggerOTAJobRequest, } from "./ota.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 { CreateAdminGroupRequest, UpdateAdminGroupRequest, GetAdminGroupsParams, } from "./group.js";
 export type { GetAdminTagsParams, AttachDetachTagsParams, GetTagNamesParams, } from "./tag.js";
 export type { GetCommandRequestsParams, AddCommandRequestBody, } from "./command_response.js";

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

@@ -26,16 +26,31 @@ export interface GetOTAImagesParams {
     type?: string;
     /** Filter by node model. */
     model?: string;
-    /** Filter by firmware version. */
+    /**
+     * Filter by firmware version.
+     *
+     * @deprecated Ignored by the backend, which has no `fw_version` filter on this endpoint.
+     */
     fw_version?: string;
     /** Maximum number of records to return. */
     num_records?: string;
     /** Image ID to start pagination from. */
     start_id?: string;
-    /** Substring filter for image name. */
+    /**
+     * Substring filter for image name, as the string `"true"`. Applies to `image_name`
+     * only; without it the name lookup is an exact match.
+     */
     contains?: string;
-    /** Filter by archived status. */
+    /**
+     * Return only archived images. Honoured by the unfiltered listing only — the
+     * `ota_image_id`, `image_name`, `type` and `model` lookups span both states.
+     */
     archived?: boolean;
+    /**
+     * Return archived and unarchived images alike. Same listing-only caveat as
+     * `archived`, and takes precedence over it.
+     */
+    all?: boolean;
 }
 /** Parameters for archiving or unarchiving an OTA image. */
 export interface ArchiveOTAImageParams {
@@ -44,6 +59,16 @@ export interface ArchiveOTAImageParams {
     /** Whether to archive (true) or unarchive (false). */
     archive: boolean;
 }
+/** Parameters for deleting an OTA image or the package it came from. */
+export interface DeleteOTAImageParams {
+    /** ID of the OTA image to delete. */
+    ota_image_id: string;
+    /**
+     * Delete an image that is still referenced by OTA jobs. Never overrides a
+     * reference from an *active* job, which is rejected regardless of this flag.
+     */
+    force_delete?: boolean;
+}
 /** Time window (minutes past midnight) during which the node may apply the OTA. */
 export interface OtaJobDownloadWindow {
     /** Window start, in minutes past midnight (0-1439). */
@@ -150,6 +175,21 @@ export interface UpdateOTAJobParams {
     /** Additional update fields. */
     [key: string]: unknown;
 }
+/** Request body for cancelling an in-flight OTA job. */
+export interface CancelOTAJobRequest {
+    /** ID of the OTA job to cancel. */
+    ota_job_id: string;
+}
+/**
+ * Request body for archiving an OTA job.
+ *
+ * The `archive` flag is supplied by `archiveJob` itself and is deliberately not
+ * part of this type: archiving is one-way, so there is no `archive: false`.
+ */
+export interface ArchiveOTAJobRequest {
+    /** ID of the OTA job to archive. */
+    ota_job_id: string;
+}
 /** Parameters for fetching OTA job status. */
 export interface GetOTAJobStatusParams {
     /** ID of the OTA job to check status for. */
@@ -180,12 +220,13 @@ export interface OTAJobStatusSummaryResponse {
     failed?: number;
     total?: number;
 }
-/** Request body for retriggering a failed OTA job. */
+/**
+ * Request body for retriggering an OTA job, pushing it to every node that is
+ * still pending. The backend accepts no other fields.
+ */
 export interface RetriggerOTAJobRequest {
     /** ID of the OTA job to retrigger. */
     ota_job_id: string;
-    /** List of node IDs to retrigger the job for. */
-    node_ids?: string[];
 }
 /** Related artifact bundled with an OTA image (e.g. bootloader). */
 export interface OTAImageRelatedFile {
@@ -212,12 +253,28 @@ export interface OTAImageInfo {
     fw_version: string;
     /** Size of the image file in bytes. */
     file_size?: number;
-    /** Current status of the image. */
+    /**
+     * Current status of the image.
+     *
+     * @deprecated Never returned for OTA images; carried over from the OTA job type.
+     */
     status?: string;
-    /** Timestamp when the image was created. */
+    /**
+     * Timestamp when the image was created.
+     *
+     * @deprecated Never returned for OTA images; use `upload_timestamp`.
+     */
     timestamp?: number;
-    /** Whether the image is archived. */
+    /**
+     * Whether the image is archived. Omitted entirely rather than set to `false` for
+     * images that have never been archived.
+     */
     archived?: boolean;
+    /**
+     * Name of the package archive this image was extracted from, when it was uploaded
+     * as a package. Such images can only be removed via `deletePackage`.
+     */
+    package?: string;
     /** Presigned or public URL for the main firmware binary (detail responses). */
     image_url?: string;
     /** MD5 checksum of the main image file (detail responses). */
@@ -248,7 +305,11 @@ export interface GetOTAImagesResponse {
     ota_images?: OTAImageInfo[];
     /** ID to use for fetching the next page. */
     next_id?: string;
-    /** Total number of images matching the query. */
+    /**
+     * Total number of images matching the query.
+     *
+     * @deprecated Never sent by the backend for OTA images.
+     */
     total?: number;
 }
 /** OTA job response. */
@@ -269,9 +330,21 @@ export interface OTAJobInfo {
     additional_info?: string;
     /** Whether the job is continuous / recurring when returned by the API. */
     continuous?: boolean;
+    /**
+     * Present and `true` once the job has been archived. Archiving is one-way,
+     * so the attribute is absent rather than `false` on unarchived jobs.
+     */
+    archived?: boolean;
     /** Additional job properties. */
     [key: string]: unknown;
 }
+/**
+ * Response returned by the cancel and archive operations.
+ *
+ * The backend re-reads the job after applying the update and returns its full
+ * record, so this is the updated job itself rather than a bare acknowledgement.
+ */
+export type OTAJobUpdateResponse = OTAJobInfo;
 /** Response returned after creating an OTA job. */
 export interface OTAJobCreateResponse {
     /** ID assigned to the newly created job. */
@@ -281,6 +354,18 @@ export interface OTAJobCreateResponse {
     /** Human-readable description of the result. */
     description: string;
 }
+/**
+ * Response returned after retriggering an OTA job.
+ *
+ * Delivery is dispatched asynchronously, so a success here means the retrigger
+ * was accepted — not that any node has received the update yet.
+ */
+export interface OTAJobRetriggerResponse {
+    /** ID of the job that was retriggered. */
+    ota_job_id: string;
+    /** Status of the retrigger operation. */
+    status: string;
+}
 /** Paginated response containing a list of OTA jobs. */
 export interface GetOTAJobsResponse {
     /** List of OTA job objects. */

package/dist/types/types/output.d.ts

@@ -7,7 +7,7 @@ export type { ESPAPIError, ESPAPISuccessResponse } from "./api.js";
 export type { LoginWithPasswordResponse, ExtendSessionResponse, LoginWithoutPasswordResponse, GetUserInfoResponse, } from "./auth.js";
 export type { AdminUserInfo, GetAdminUsersResponse } from "./admin_user.js";
 export type { AdminNodeInfo, AdminNodeListResponse, GetNodeTagsResponse, NodeStatusSummaryResponse, } from "./node.js";
-export type { OTAImageInfo, OTAImageRelatedFile, OTAImageCreateResponse, GetOTAImagesResponse, OTAImageUploadUrlResponse, ConfirmOTAImageUploadResponse, OTAPackageUploadUrlResponse, ConfirmOTAPackageUploadResponse, OTAJobInfo, OTAJobCreateResponse, GetOTAJobsResponse, NodeOTAJobStatusEntry, OTAJobStatusResponse, OTAJobStatusSummaryResponse, } from "./ota.js";
+export type { OTAImageInfo, OTAImageRelatedFile, OTAImageCreateResponse, GetOTAImagesResponse, OTAImageUploadUrlResponse, ConfirmOTAImageUploadResponse, OTAPackageUploadUrlResponse, ConfirmOTAPackageUploadResponse, OTAJobInfo, OTAJobCreateResponse, OTAJobUpdateResponse, OTAJobRetriggerResponse, GetOTAJobsResponse, NodeOTAJobStatusEntry, OTAJobStatusResponse, OTAJobStatusSummaryResponse, } from "./ota.js";
 export type { AdminGroupInfo, CreateAdminGroupResponse, GetAdminGroupsResponse, } from "./group.js";
 export type { TagResourceInfo, GetAdminTagsResponse, GetTagNamesResponse, } from "./tag.js";
 export type { CommandRequestInfo, GetCommandRequestsResponse, AddCommandRequestResponse, } from "./command_response.js";

package/dist/types/utils/constants.d.ts

@@ -27,7 +27,7 @@ declare const APIEndpoints: {
     readonly ADMIN_OTA_JOB: "admin/otajob";
     readonly ADMIN_OTA_JOB_STATUS: "admin/otajob/status";
     readonly ADMIN_OTA_JOB_STATUS_SUMMARY: "admin/otajob/status/summary";
-    readonly ADMIN_OTA_JOB_ACTION: "admin/otajob";
+    readonly ADMIN_OTA_JOB_RETRIGGER: "admin/otajob/retrigger";
     readonly ADMIN_NODE_GROUP: "admin/node_group";
     readonly ADMIN_TAGS: "admin/tags";
     readonly ADMIN_TAG_NAMES: "admin/tags/names";
@@ -115,6 +115,7 @@ declare const StorageAdapterErrorCodes: {
 declare const APICallValidationErrorCodes: {
     readonly MISSING_NODE_ID: "MISSING_NODE_ID";
     readonly MISSING_OTA_IMAGE_ID: "MISSING_OTA_IMAGE_ID";
+    readonly MISSING_ARCHIVE_FLAG: "MISSING_ARCHIVE_FLAG";
     readonly MISSING_OTA_JOB_ID: "MISSING_OTA_JOB_ID";
     readonly MISSING_GROUP_ID: "MISSING_GROUP_ID";
     readonly MISSING_GROUP_NAME: "MISSING_GROUP_NAME";

package/dist/types/utils/error/errorMessages.d.ts

@@ -19,6 +19,7 @@ declare const storageAdapterErrorMessages: {
 declare const apiCallValidationErrorMessages: {
     MISSING_NODE_ID: string;
     MISSING_OTA_IMAGE_ID: string;
+    MISSING_ARCHIVE_FLAG: string;
     MISSING_OTA_JOB_ID: string;
     MISSING_GROUP_ID: string;
     MISSING_GROUP_NAME: string;

package/dist/types-cjs/methods/ESPRMAdminOTAImage/ArchiveImage.d.cts

@@ -8,10 +8,13 @@ import { ESPAPISuccessResponse } from "../../types/api.cjs";
 declare module "../../ESPRMAdminOTAImage.cjs" {
     interface ESPRMAdminOTAImage {
         /**
-         * Archives an OTA firmware image by its image ID.
+         * Archives or unarchives an OTA firmware image by its image ID.
          *
-         * @param params - Parameters including the OTA image ID to archive.
-         * @returns A success response confirming the image was archived.
+         * Unlike OTA jobs, image archiving is two-way: pass `archive: false` to restore
+         * an archived image.
+         *
+         * @param params - The OTA image ID and the desired archived state.
+         * @returns A success response confirming the new archived state.
          */
         archiveImage(params: ArchiveOTAImageParams): Promise<ESPAPISuccessResponse>;
     }

package/dist/types-cjs/methods/ESPRMAdminOTAImage/DeleteImage.d.cts

@@ -3,15 +3,19 @@
  *
  * SPDX-License-Identifier: Apache-2.0
  */
+import { DeleteOTAImageParams } from "../../types/ota.cjs";
 import { ESPAPISuccessResponse } from "../../types/api.cjs";
 declare module "../../ESPRMAdminOTAImage.cjs" {
     interface ESPRMAdminOTAImage {
         /**
          * Deletes an OTA firmware image by its image ID.
          *
-         * @param otaImageId - The ID of the OTA image to delete.
+         * Images uploaded as part of a package are rejected by this endpoint and must
+         * be removed with {@link ESPRMAdminOTAImage.deletePackage} instead.
+         *
+         * @param params - The OTA image ID, and optionally `force_delete`.
          * @returns A success response confirming the image was deleted.
          */
-        deleteImage(otaImageId: string): Promise<ESPAPISuccessResponse>;
+        deleteImage(params: DeleteOTAImageParams): Promise<ESPAPISuccessResponse>;
     }
 }

package/dist/types-cjs/methods/ESPRMAdminOTAImage/DeletePackage.d.cts

@@ -0,0 +1,22 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { DeleteOTAImageParams } from "../../types/ota.cjs";
+import { ESPAPISuccessResponse } from "../../types/api.cjs";
+declare module "../../ESPRMAdminOTAImage.cjs" {
+    interface ESPRMAdminOTAImage {
+        /**
+         * Deletes an OTA image that was uploaded as part of a package, removing both the
+         * image and the package archive it came from.
+         *
+         * Images uploaded as a standalone binary should use
+         * {@link ESPRMAdminOTAImage.deleteImage} instead.
+         *
+         * @param params - The OTA image ID, and optionally `force_delete`.
+         * @returns A success response confirming the package was deleted.
+         */
+        deletePackage(params: DeleteOTAImageParams): Promise<ESPAPISuccessResponse>;
+    }
+}

package/dist/types-cjs/methods/ESPRMAdminOTAImage/deleteParams.d.cts

@@ -0,0 +1,13 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { DeleteOTAImageParams } from "../../types/ota.cjs";
+/**
+ * Builds the query string shared by the image and package delete endpoints.
+ *
+ * `force_delete` is sent only when requested: the backend reads it as a string and
+ * treats any value other than "true" as false, so omitting it keeps the URL clean.
+ */
+export declare function buildDeleteOTAImageParams(params: DeleteOTAImageParams): Record<string, string>;

package/dist/types-cjs/methods/ESPRMAdminOTAImage/index.d.cts

@@ -11,3 +11,4 @@ import "./ConfirmPackageUpload.cjs";
 import "./GetImages.cjs";
 import "./ArchiveImage.cjs";
 import "./DeleteImage.cjs";
+import "./DeletePackage.cjs";

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

@@ -0,0 +1,22 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ArchiveOTAJobRequest, OTAJobUpdateResponse } from "../../types/ota.cjs";
+declare module "../../ESPRMAdminOTAJob.cjs" {
+    interface ESPRMAdminOTAJob {
+        /**
+         * Archives an OTA job so it no longer appears in the default job listing.
+         *
+         * Only jobs that have finished, been cancelled or expired can be archived,
+         * and only once: archiving is one-way and the backend rejects an already
+         * archived job. Archived jobs are retrieved by listing with `archived` or
+         * `all` set.
+         *
+         * @param params - Parameters including the OTA job ID to archive.
+         * @returns The updated OTA job record.
+         */
+        archiveJob(params: ArchiveOTAJobRequest): Promise<OTAJobUpdateResponse>;
+    }
+}

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

@@ -0,0 +1,21 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CancelOTAJobRequest, OTAJobUpdateResponse } from "../../types/ota.cjs";
+declare module "../../ESPRMAdminOTAJob.cjs" {
+    interface ESPRMAdminOTAJob {
+        /**
+         * Cancels an in-flight OTA job, marking it and all of its pending nodes as
+         * cancelled.
+         *
+         * Only jobs that are still active can be cancelled; the backend rejects
+         * jobs that are already finished, cancelled, failed or expired.
+         *
+         * @param params - Parameters including the OTA job ID to cancel.
+         * @returns The updated OTA job record.
+         */
+        cancelJob(params: CancelOTAJobRequest): Promise<OTAJobUpdateResponse>;
+    }
+}

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

@@ -3,16 +3,20 @@
  *
  * SPDX-License-Identifier: Apache-2.0
  */
-import { RetriggerOTAJobRequest } from "../../types/ota.cjs";
-import { ESPAPISuccessResponse } from "../../types/api.cjs";
+import { OTAJobRetriggerResponse, RetriggerOTAJobRequest } from "../../types/ota.cjs";
 declare module "../../ESPRMAdminOTAJob.cjs" {
     interface ESPRMAdminOTAJob {
         /**
-         * Retriggers a previously created OTA job for failed or pending nodes.
+         * Retriggers an OTA job, pushing it again to every node still pending.
+         *
+         * The backend rejects this for jobs that are not active, that have expired,
+         * that require user approval, or that were created with an auto-selected
+         * signing key. Delivery is dispatched asynchronously, so a success means
+         * the retrigger was accepted, not that any node has received it.
          *
          * @param params - Parameters including the OTA job ID to retrigger.
-         * @returns A success response confirming the job was retriggered.
+         * @returns The job ID and the status of the retrigger operation.
          */
-        retriggerJob(params: RetriggerOTAJobRequest): Promise<ESPAPISuccessResponse>;
+        retriggerJob(params: RetriggerOTAJobRequest): Promise<OTAJobRetriggerResponse>;
     }
 }

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

@@ -6,7 +6,8 @@
 import "./CreateJob.cjs";
 import "./GetJob.cjs";
 import "./UpdateJob.cjs";
-import "./DeleteJob.cjs";
+import "./CancelJob.cjs";
+import "./ArchiveJob.cjs";
 import "./GetJobStatus.cjs";
 import "./GetJobStatusSummary.cjs";
 import "./RetriggerJob.cjs";

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, GetOTAImageUploadUrlParams, ConfirmOTAImageUploadRequest, GetOTAPackageUploadUrlParams, ConfirmOTAPackageUploadRequest, CreateOTAJobRequest, CreateOTAJobQueryOptions, OtaJobDownloadWindow, OtaJobValidity, OtaJobMetadata, OtaSecureBoot, OtaNetworkSerialisation, GetOTAJobParams, UpdateOTAJobParams, GetOTAJobStatusParams, GetOTAJobStatusSummaryParams, RetriggerOTAJobRequest, } from "./ota.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 { CreateAdminGroupRequest, UpdateAdminGroupRequest, GetAdminGroupsParams, } from "./group.cjs";
 export type { GetAdminTagsParams, AttachDetachTagsParams, GetTagNamesParams, } from "./tag.cjs";
 export type { GetCommandRequestsParams, AddCommandRequestBody, } from "./command_response.cjs";

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

@@ -26,16 +26,31 @@ export interface GetOTAImagesParams {
     type?: string;
     /** Filter by node model. */
     model?: string;
-    /** Filter by firmware version. */
+    /**
+     * Filter by firmware version.
+     *
+     * @deprecated Ignored by the backend, which has no `fw_version` filter on this endpoint.
+     */
     fw_version?: string;
     /** Maximum number of records to return. */
     num_records?: string;
     /** Image ID to start pagination from. */
     start_id?: string;
-    /** Substring filter for image name. */
+    /**
+     * Substring filter for image name, as the string `"true"`. Applies to `image_name`
+     * only; without it the name lookup is an exact match.
+     */
     contains?: string;
-    /** Filter by archived status. */
+    /**
+     * Return only archived images. Honoured by the unfiltered listing only — the
+     * `ota_image_id`, `image_name`, `type` and `model` lookups span both states.
+     */
     archived?: boolean;
+    /**
+     * Return archived and unarchived images alike. Same listing-only caveat as
+     * `archived`, and takes precedence over it.
+     */
+    all?: boolean;
 }
 /** Parameters for archiving or unarchiving an OTA image. */
 export interface ArchiveOTAImageParams {
@@ -44,6 +59,16 @@ export interface ArchiveOTAImageParams {
     /** Whether to archive (true) or unarchive (false). */
     archive: boolean;
 }
+/** Parameters for deleting an OTA image or the package it came from. */
+export interface DeleteOTAImageParams {
+    /** ID of the OTA image to delete. */
+    ota_image_id: string;
+    /**
+     * Delete an image that is still referenced by OTA jobs. Never overrides a
+     * reference from an *active* job, which is rejected regardless of this flag.
+     */
+    force_delete?: boolean;
+}
 /** Time window (minutes past midnight) during which the node may apply the OTA. */
 export interface OtaJobDownloadWindow {
     /** Window start, in minutes past midnight (0-1439). */
@@ -150,6 +175,21 @@ export interface UpdateOTAJobParams {
     /** Additional update fields. */
     [key: string]: unknown;
 }
+/** Request body for cancelling an in-flight OTA job. */
+export interface CancelOTAJobRequest {
+    /** ID of the OTA job to cancel. */
+    ota_job_id: string;
+}
+/**
+ * Request body for archiving an OTA job.
+ *
+ * The `archive` flag is supplied by `archiveJob` itself and is deliberately not
+ * part of this type: archiving is one-way, so there is no `archive: false`.
+ */
+export interface ArchiveOTAJobRequest {
+    /** ID of the OTA job to archive. */
+    ota_job_id: string;
+}
 /** Parameters for fetching OTA job status. */
 export interface GetOTAJobStatusParams {
     /** ID of the OTA job to check status for. */
@@ -180,12 +220,13 @@ export interface OTAJobStatusSummaryResponse {
     failed?: number;
     total?: number;
 }
-/** Request body for retriggering a failed OTA job. */
+/**
+ * Request body for retriggering an OTA job, pushing it to every node that is
+ * still pending. The backend accepts no other fields.
+ */
 export interface RetriggerOTAJobRequest {
     /** ID of the OTA job to retrigger. */
     ota_job_id: string;
-    /** List of node IDs to retrigger the job for. */
-    node_ids?: string[];
 }
 /** Related artifact bundled with an OTA image (e.g. bootloader). */
 export interface OTAImageRelatedFile {
@@ -212,12 +253,28 @@ export interface OTAImageInfo {
     fw_version: string;
     /** Size of the image file in bytes. */
     file_size?: number;
-    /** Current status of the image. */
+    /**
+     * Current status of the image.
+     *
+     * @deprecated Never returned for OTA images; carried over from the OTA job type.
+     */
     status?: string;
-    /** Timestamp when the image was created. */
+    /**
+     * Timestamp when the image was created.
+     *
+     * @deprecated Never returned for OTA images; use `upload_timestamp`.
+     */
     timestamp?: number;
-    /** Whether the image is archived. */
+    /**
+     * Whether the image is archived. Omitted entirely rather than set to `false` for
+     * images that have never been archived.
+     */
     archived?: boolean;
+    /**
+     * Name of the package archive this image was extracted from, when it was uploaded
+     * as a package. Such images can only be removed via `deletePackage`.
+     */
+    package?: string;
     /** Presigned or public URL for the main firmware binary (detail responses). */
     image_url?: string;
     /** MD5 checksum of the main image file (detail responses). */
@@ -248,7 +305,11 @@ export interface GetOTAImagesResponse {
     ota_images?: OTAImageInfo[];
     /** ID to use for fetching the next page. */
     next_id?: string;
-    /** Total number of images matching the query. */
+    /**
+     * Total number of images matching the query.
+     *
+     * @deprecated Never sent by the backend for OTA images.
+     */
     total?: number;
 }
 /** OTA job response. */
@@ -269,9 +330,21 @@ export interface OTAJobInfo {
     additional_info?: string;
     /** Whether the job is continuous / recurring when returned by the API. */
     continuous?: boolean;
+    /**
+     * Present and `true` once the job has been archived. Archiving is one-way,
+     * so the attribute is absent rather than `false` on unarchived jobs.
+     */
+    archived?: boolean;
     /** Additional job properties. */
     [key: string]: unknown;
 }
+/**
+ * Response returned by the cancel and archive operations.
+ *
+ * The backend re-reads the job after applying the update and returns its full
+ * record, so this is the updated job itself rather than a bare acknowledgement.
+ */
+export type OTAJobUpdateResponse = OTAJobInfo;
 /** Response returned after creating an OTA job. */
 export interface OTAJobCreateResponse {
     /** ID assigned to the newly created job. */
@@ -281,6 +354,18 @@ export interface OTAJobCreateResponse {
     /** Human-readable description of the result. */
     description: string;
 }
+/**
+ * Response returned after retriggering an OTA job.
+ *
+ * Delivery is dispatched asynchronously, so a success here means the retrigger
+ * was accepted — not that any node has received the update yet.
+ */
+export interface OTAJobRetriggerResponse {
+    /** ID of the job that was retriggered. */
+    ota_job_id: string;
+    /** Status of the retrigger operation. */
+    status: string;
+}
 /** Paginated response containing a list of OTA jobs. */
 export interface GetOTAJobsResponse {
     /** List of OTA job objects. */

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

@@ -7,7 +7,7 @@ export type { ESPAPIError, ESPAPISuccessResponse } from "./api.cjs";
 export type { LoginWithPasswordResponse, ExtendSessionResponse, LoginWithoutPasswordResponse, GetUserInfoResponse, } from "./auth.cjs";
 export type { AdminUserInfo, GetAdminUsersResponse } from "./admin_user.cjs";
 export type { AdminNodeInfo, AdminNodeListResponse, GetNodeTagsResponse, NodeStatusSummaryResponse, } from "./node.cjs";
-export type { OTAImageInfo, OTAImageRelatedFile, OTAImageCreateResponse, GetOTAImagesResponse, OTAImageUploadUrlResponse, ConfirmOTAImageUploadResponse, OTAPackageUploadUrlResponse, ConfirmOTAPackageUploadResponse, OTAJobInfo, OTAJobCreateResponse, GetOTAJobsResponse, NodeOTAJobStatusEntry, OTAJobStatusResponse, OTAJobStatusSummaryResponse, } from "./ota.cjs";
+export type { OTAImageInfo, OTAImageRelatedFile, OTAImageCreateResponse, GetOTAImagesResponse, OTAImageUploadUrlResponse, ConfirmOTAImageUploadResponse, OTAPackageUploadUrlResponse, ConfirmOTAPackageUploadResponse, OTAJobInfo, OTAJobCreateResponse, OTAJobUpdateResponse, OTAJobRetriggerResponse, GetOTAJobsResponse, NodeOTAJobStatusEntry, OTAJobStatusResponse, OTAJobStatusSummaryResponse, } from "./ota.cjs";
 export type { AdminGroupInfo, CreateAdminGroupResponse, GetAdminGroupsResponse, } from "./group.cjs";
 export type { TagResourceInfo, GetAdminTagsResponse, GetTagNamesResponse, } from "./tag.cjs";
 export type { CommandRequestInfo, GetCommandRequestsResponse, AddCommandRequestResponse, } from "./command_response.cjs";

package/dist/types-cjs/utils/constants.d.cts

@@ -27,7 +27,7 @@ declare const APIEndpoints: {
     readonly ADMIN_OTA_JOB: "admin/otajob";
     readonly ADMIN_OTA_JOB_STATUS: "admin/otajob/status";
     readonly ADMIN_OTA_JOB_STATUS_SUMMARY: "admin/otajob/status/summary";
-    readonly ADMIN_OTA_JOB_ACTION: "admin/otajob";
+    readonly ADMIN_OTA_JOB_RETRIGGER: "admin/otajob/retrigger";
     readonly ADMIN_NODE_GROUP: "admin/node_group";
     readonly ADMIN_TAGS: "admin/tags";
     readonly ADMIN_TAG_NAMES: "admin/tags/names";
@@ -115,6 +115,7 @@ declare const StorageAdapterErrorCodes: {
 declare const APICallValidationErrorCodes: {
     readonly MISSING_NODE_ID: "MISSING_NODE_ID";
     readonly MISSING_OTA_IMAGE_ID: "MISSING_OTA_IMAGE_ID";
+    readonly MISSING_ARCHIVE_FLAG: "MISSING_ARCHIVE_FLAG";
     readonly MISSING_OTA_JOB_ID: "MISSING_OTA_JOB_ID";
     readonly MISSING_GROUP_ID: "MISSING_GROUP_ID";
     readonly MISSING_GROUP_NAME: "MISSING_GROUP_NAME";

package/dist/types-cjs/utils/error/errorMessages.d.cts

@@ -19,6 +19,7 @@ declare const storageAdapterErrorMessages: {
 declare const apiCallValidationErrorMessages: {
     MISSING_NODE_ID: string;
     MISSING_OTA_IMAGE_ID: string;
+    MISSING_ARCHIVE_FLAG: string;
     MISSING_OTA_JOB_ID: string;
     MISSING_GROUP_ID: string;
     MISSING_GROUP_NAME: string;