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

import { experimentsCreate } from "../funcs/experimentsCreate.js";
import { experimentsCreateIteration } from "../funcs/experimentsCreateIteration.js";
import { experimentsGet } from "../funcs/experimentsGet.js";
import { experimentsGetExperimentsAnyEnv } from "../funcs/experimentsGetExperimentsAnyEnv.js";
import { experimentsList } from "../funcs/experimentsList.js";
import { experimentsPatch } from "../funcs/experimentsPatch.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 Experiments extends ClientSDK {
  /**
   * Get experiments
   *
   * @remarks
   * Get details about all experiments in an environment.
   *
   * ### Filtering experiments
   *
   * LaunchDarkly supports the `filter` query param for filtering, with the following fields:
   *
   * - `flagKey` filters for only experiments that use the flag with the given key.
   * - `metricKey` filters for only experiments that use the metric with the given key.
   * - `status` filters for only experiments with an iteration with the given status. An iteration can have the status `not_started`, `running` or `stopped`.
   *
   * For example, `filter=flagKey:my-flag,status:running,metricKey:page-load-ms` filters for experiments for the given flag key and the given metric key which have a currently running iteration.
   *
   * ### Expanding the experiments response
   *
   * LaunchDarkly supports five fields for expanding the "Get experiments" response. By default, these fields are **not** included in the response.
   *
   * To expand the response, append the `expand` query parameter and add a comma-separated list with any of the following fields:
   *
   * - `previousIterations` includes all iterations prior to the current iteration. By default only the current iteration is included in the response.
   * - `draftIteration` includes the iteration which has not been started yet, if any.
   * - `secondaryMetrics` includes secondary metrics. By default only the primary metric is included in the response.
   * - `treatments` includes all treatment and parameter details. By default treatment data is not included in the response.
   * - `analysisConfig` includes the analysis configuration for the experiment, such as the Bayesian threshold or significance threshold.
   *
   * For example, `expand=draftIteration,treatments` includes the `draftIteration` and `treatments` fields in the response. If fields that you request with the `expand` query parameter are empty, they are not included in the response.
   */
  async list(
    request: operations.GetExperimentsRequest,
    options?: RequestOptions,
  ): Promise<components.ExperimentCollectionRep> {
    return unwrapAsync(experimentsList(
      this,
      request,
      options,
    ));
  }

  /**
   * Create experiment
   *
   * @remarks
   * Create an experiment.
   *
   * To run this experiment, you'll need to [create an iteration](https://launchdarkly.com/docs/api/experiments/create-iteration) and then [update the experiment](https://launchdarkly.com/docs/api/experiments/patch-experiment) with the `startIteration` instruction.
   *
   * ### Experiment types
   *
   * Use the `type` field to specify the experiment type: `experiment` (default), `mab` (multi-armed bandit), or `holdout`.
   *
   * For multi-armed bandit experiments, set `reallocationFrequencyMillis` on the iteration to control how often traffic is reallocated across variations.
   *
   * ### Results analysis
   *
   * Use the `methodology` field to specify the results analysis approach: `frequentist` (default) or `bayesian`. Multi-armed bandit experiments support only `bayesian`, which is their default.
   *
   * Use the `dataSource` field to specify the source of metric data: `launchdarkly` (default), `snowflake`, or `databricks`.
   *
   * Use the `analysisConfig` field to customize analysis settings such as the Bayesian threshold, significance threshold, or multiple comparison correction method.
   *
   * To learn more, read [Creating experiments](https://launchdarkly.com/docs/home/experimentation/create).
   */
  async create(
    request: operations.CreateExperimentRequest,
    options?: RequestOptions,
  ): Promise<components.Experiment> {
    return unwrapAsync(experimentsCreate(
      this,
      request,
      options,
    ));
  }

  /**
   * Get experiment
   *
   * @remarks
   * Get details about an experiment.
   *
   * ### Expanding the experiment response
   *
   * LaunchDarkly supports five fields for expanding the "Get experiment" response. By default, these fields are **not** included in the response.
   *
   * To expand the response, append the `expand` query parameter and add a comma-separated list with any of the following fields:
   *
   * - `previousIterations` includes all iterations prior to the current iteration. By default only the current iteration is included in the response.
   * - `draftIteration` includes the iteration which has not been started yet, if any.
   * - `secondaryMetrics` includes secondary metrics. By default only the primary metric is included in the response.
   * - `treatments` includes all treatment and parameter details. By default treatment data is not included in the response.
   * - `analysisConfig` includes the analysis configuration for the experiment, such as the Bayesian threshold or significance threshold.
   *
   * For example, `expand=draftIteration,treatments` includes the `draftIteration` and `treatments` fields in the response. If fields that you request with the `expand` query parameter are empty, they are not included in the response.
   */
  async get(
    request: operations.GetExperimentRequest,
    options?: RequestOptions,
  ): Promise<components.Experiment> {
    return unwrapAsync(experimentsGet(
      this,
      request,
      options,
    ));
  }

  /**
   * Patch experiment
   *
   * @remarks
   * Update an experiment. Updating an experiment uses the semantic patch format.
   *
   * To make a semantic patch request, you must append `domain-model=launchdarkly.semanticpatch` to your `Content-Type` header. To learn more, read [Updates using semantic patch](https://launchdarkly.com/docs/api#updates-using-semantic-patch).
   *
   * ### Instructions
   *
   * Semantic patch requests support the following `kind` instructions for updating experiments.
   *
   * #### updateName
   *
   * > **Deprecated**: `updateName` will be removed in a future version. Use `updateExperimentFields` instead.
   *
   * Updates the experiment name.
   *
   * ##### Parameters
   *
   * - `value`: The new name.
   *
   * Here's an example:
   *
   * ```json
   * {
   *   "instructions": [{
   *     "kind": "updateName",
   *     "value": "Example updated experiment name"
   *   }]
   * }
   * ```
   *
   * #### updateDescription
   *
   * > **Deprecated**: `updateDescription` will be removed in a future version. Use `updateExperimentFields` instead.
   *
   * Updates the experiment description.
   *
   * ##### Parameters
   *
   * - `value`: The new description.
   *
   * Here's an example:
   *
   * ```json
   * {
   *   "instructions": [{
   *     "kind": "updateDescription",
   *     "value": "Example updated description"
   *   }]
   * }
   * ```
   *
   * #### updateExperimentFields
   *
   * Updates one or more fields on an experiment or its current iteration. Each field update specifies an operation (`add`, `update`, or `remove`) and an optional value.
   *
   * Which fields are mutable depends on the current iteration status. To discover which fields and operations are allowed, expand `mutableFieldsByStatus` on the [Get experiment](https://launchdarkly.com/docs/api/experiments/get-experiment) response.
   *
   * ##### Parameters
   *
   * - `value`: An object mapping field names to field updates. Each field update has the following properties:
   *   - `operation`: The operation to perform. One of `add`, `update`, or `remove`.
   *   - `value`: The new value for the field. Required for `add` and `update` operations.
   *
   * To find which fields are supported and which operations are allowed for each iteration status, expand `mutableFieldsByStatus` on the [Get experiment](https://launchdarkly.com/docs/api/experiments/get-experiment) response.
   *
   * Here's an example:
   *
   * ```json
   * {
   *   "instructions": [{
   *     "kind": "updateExperimentFields",
   *     "value": {
   *       "name": {
   *         "operation": "update",
   *         "value": "Updated experiment name"
   *       },
   *       "tags": {
   *         "operation": "add",
   *         "value": ["tag1", "tag2"]
   *       }
   *     }
   *   }]
   * }
   * ```
   *
   * #### saveAndStartNewIteration
   *
   * Stops the current running iteration, creates a new iteration from it, optionally applies field updates, and starts the new iteration. This is a convenience instruction that combines stopping, updating, and starting in a single operation.
   *
   * ##### Parameters
   *
   * - `changeJustification`: (Optional) The reason for stopping and starting a new iteration.
   * - `value`: (Optional) An object mapping field names to field updates, using the same format as `updateExperimentFields`. These updates are applied to the new iteration before it is started.
   *
   * Here's an example:
   *
   * ```json
   * {
   *   "instructions": [{
   *     "kind": "saveAndStartNewIteration",
   *     "changeJustification": "Adjusting hypothesis based on early results",
   *     "value": {
   *       "hypothesis": {
   *         "operation": "update",
   *         "value": "Updated hypothesis text"
   *       }
   *     }
   *   }]
   * }
   * ```
   *
   * #### startIteration
   *
   * Starts a new iteration for this experiment. You must [create a new iteration](https://launchdarkly.com/docs/api/experiments/create-iteration) before calling this instruction.
   *
   * An iteration may not be started until it meets the following criteria:
   *
   * * Its associated flag is toggled on and is not archived
   * * Its `randomizationUnit` is set
   * * At least one of its `treatments` has a non-zero `allocationPercent`
   *
   * ##### Parameters
   *
   * - `changeJustification`: The reason for starting a new iteration. Required when you call `startIteration` on an already running experiment, otherwise optional.
   *
   * Here's an example:
   *
   * ```json
   * {
   *   "instructions": [{
   *     "kind": "startIteration",
   *     "changeJustification": "It's time to start a new iteration"
   *   }]
   * }
   * ```
   *
   * #### stopIteration
   *
   * Stops the current iteration for this experiment.
   *
   * ##### Parameters
   *
   * - `winningTreatmentId`: The ID of the winning treatment. Treatment IDs are returned as part of the [Get experiment](https://launchdarkly.com/docs/api/experiments/get-experiment) response. They are the `_id` of each element in the `treatments` array.
   * - `winningReason`: The reason for the winner
   *
   * Here's an example:
   *
   * ```json
   * {
   *   "instructions": [{
   *     "kind": "stopIteration",
   *     "winningTreatmentId": "3a548ec2-72ac-4e59-8518-5c24f5609ccf",
   *     "winningReason": "Example reason to stop the iteration"
   *   }]
   * }
   * ```
   *
   * #### archiveExperiment
   *
   * Archives this experiment. Archived experiments are hidden by default in the LaunchDarkly user interface. You cannot start new iterations for archived experiments.
   *
   * Here's an example:
   *
   * ```json
   * {
   *   "instructions": [{ "kind": "archiveExperiment" }]
   * }
   * ```
   *
   * #### restoreExperiment
   *
   * Restores an archived experiment. After restoring an experiment, you can start new iterations for it again.
   *
   * Here's an example:
   *
   * ```json
   * {
   *   "instructions": [{ "kind": "restoreExperiment" }]
   * }
   * ```
   */
  async patch(
    request: operations.PatchExperimentRequest,
    options?: RequestOptions,
  ): Promise<components.Experiment> {
    return unwrapAsync(experimentsPatch(
      this,
      request,
      options,
    ));
  }

  /**
   * Create iteration
   *
   * @remarks
   * > **Deprecated**: This endpoint will be removed in a future version. Use the `updateExperimentFields` and `saveAndStartNewIteration` instructions on [Update experiment](https://launchdarkly.com/docs/api/experiments/patch-experiment) instead.
   *
   * Create an experiment iteration.
   *
   * Experiment iterations let you record experiments in individual blocks of time. Initially, iterations are created with a status of `not_started` and appear in the `draftIteration` field of an experiment. To start or stop an iteration, [update the experiment](https://launchdarkly.com/docs/api/experiments/patch-experiment) with the `startIteration` or `stopIteration` instruction.
   *
   * To learn more, read [Start experiment iterations](https://launchdarkly.com/docs/home/experimentation/create#start-an-experiment-iteration).
   *
   * @deprecated method: This will be removed in a future release, please migrate away from it as soon as possible.
   */
  async createIteration(
    request: operations.CreateIterationRequest,
    options?: RequestOptions,
  ): Promise<components.IterationRep> {
    return unwrapAsync(experimentsCreateIteration(
      this,
      request,
      options,
    ));
  }

  /**
   * Get experiments any environment
   *
   * @remarks
   * Get a list of experiments from across all environments in the project
   */
  async getExperimentsAnyEnv(
    request: operations.GetExperimentsAnyEnvRequest,
    options?: RequestOptions,
  ): Promise<components.ExperimentCollectionRep> {
    return unwrapAsync(experimentsGetExperimentsAnyEnv(
      this,
      request,
      options,
    ));
  }
}