/*
 * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
 */

import { maestroWorkflowInstanceManagementCancelWorkflowInstance } from "../funcs/maestroWorkflowInstanceManagementCancelWorkflowInstance.js";
import { maestroWorkflowInstanceManagementGetWorkflowInstance } from "../funcs/maestroWorkflowInstanceManagementGetWorkflowInstance.js";
import { maestroWorkflowInstanceManagementGetWorkflowInstancesList } from "../funcs/maestroWorkflowInstanceManagementGetWorkflowInstancesList.js";
import { ClientSDK, RequestOptions } from "../lib/sdks.js";
import * as components from "../models/components/index.js";
import * as operations from "../models/operations/index.js";
import { unwrapAsync } from "../types/fp.js";

export class WorkflowInstanceManagement extends ClientSDK {
  /**
   * Retrieve All Workflow Instances
   *
   * @remarks
   * This operation retrieves a list of all available Maestro workflow instances. It returns basic information
   * about each workflow instance, including its unique identifier (`id`), name, status, timestamps, and
   * additional metadata.
   *
   * The response provides key details that help users understand what workflow instances are in progress
   * or completed, and the relevant data for each. Each workflow instance entry also includes metadata, such
   * as who started it, when it was last modified, and how many steps have been completed.
   *
   * ### Use Cases:
   * - Listing all available workflow instances for manual or automated review
   * - Monitoring which workflow instances are currently running or have finished
   * - Gathering basic metadata about workflow instances for auditing, logging, or reporting purposes
   *
   * ### Key Features:
   * - **Comprehensive Instance Overview**: Provides a full list of workflow instances, giving visibility
   *
   *   into all ongoing and completed workflows within the Maestro platform
   * - **Metadata for Tracking**: Includes helpful metadata like creation time, last modification date,
   *
   *   and user details to support audit trails
   * - **Scalable and Future-Proof**: Designed to handle growing numbers of workflow instances as the
   *
   *   platform scales
   */
  async getWorkflowInstancesList(
    request: operations.GetWorkflowInstancesListRequest,
    options?: RequestOptions,
  ): Promise<components.WorkflowInstanceCollection> {
    return unwrapAsync(
      maestroWorkflowInstanceManagementGetWorkflowInstancesList(
        this,
        request,
        options,
      ),
    );
  }

  /**
   * Retrieve a Workflow Instance
   *
   * @remarks
   * This operation retrieves a single Maestro workflow instance by its unique identifier (`id`).
   * It returns the primary details of the workflow instance, including its name, status,
   * starting information, and other metadata.
   *
   * The response provides key details that help users understand the current state of the workflow
   * instance, when it was started, and who initiated it. Additional metadata is included to support
   * auditing and reporting within the system.
   *
   * ### Use Cases:
   * - Getting the details of a specific workflow instance for further processing or review
   * - Monitoring the status of a running workflow instance to determine completion or cancellation
   * - Accessing metadata for auditing, logging, or reporting on a single workflow instance
   *
   * ### Key Features:
   * - **Single Workflow Instance**: Provides direct access to a specific workflow instance by `id`
   * - **Detailed Status Information**: Includes the workflow's start and end times, status, and other lifecycle timestamps
   * - **Metadata for Tracking**: Useful metadata like who initiated the workflow (`started_by`) and versioning details
   * - **Future-Proof**: Designed to be extensible if additional fields or nested information are required over time
   */
  async getWorkflowInstance(
    request: operations.GetWorkflowInstanceRequest,
    options?: RequestOptions,
  ): Promise<components.WorkflowInstance> {
    return unwrapAsync(maestroWorkflowInstanceManagementGetWorkflowInstance(
      this,
      request,
      options,
    ));
  }

  /**
   * Cancel a Running Workflow Instance
   *
   * @remarks
   * This operation cancels a running Maestro workflow instance by its unique identifier (`instanceId`).
   * Once canceled, the workflow instance will no longer continue executing any remaining steps.
   *
   * ### Use Cases:
   * - Stopping a workflow execution when it is no longer needed or relevant
   * - Manually intervening in a workflow to prevent it from reaching completion if conditions change
   *
   * ### Key Features:
   * - **Immediate Termination**: Ensures the workflow instance no longer processes subsequent steps
   * - **Clear Feedback**: Returns a confirmation message including both the instance and workflow identifiers
   */
  async cancelWorkflowInstance(
    request: operations.CancelWorkflowInstanceRequest,
    options?: RequestOptions,
  ): Promise<components.CancelWorkflowInstanceResponse> {
    return unwrapAsync(maestroWorkflowInstanceManagementCancelWorkflowInstance(
      this,
      request,
      options,
    ));
  }
}