backtests.ts

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../../resource';
import * as Core from '../../../core';

export class Backtests extends APIResource {
  /**
   * Initiates a request to asynchronously generate a backtest for an authorization
   * rule. During backtesting, both the active version (if one exists) and the draft
   * version of the Authorization Rule are evaluated by replaying historical
   * transaction data against the rule's conditions. This process allows customers to
   * simulate and understand the effects of proposed rule changes before deployment.
   * The generated backtest report provides detailed results showing whether the
   * draft version of the Auth Rule would have approved or declined historical
   * transactions which were processed during the backtest period. These reports help
   * evaluate how changes to rule configurations might affect overall transaction
   * approval rates.
   *
   * The generated backtest report will be delivered asynchronously through a webhook
   * with `event_type` = `auth_rules.backtest_report.created`. See the docs on
   * setting up [webhook subscriptions](https://docs.lithic.com/docs/events-api). It
   * is also possible to request backtest reports on-demand through the
   * `/v2/auth_rules/{auth_rule_token}/backtests/{auth_rule_backtest_token}`
   * endpoint.
   *
   * Lithic currently supports backtesting for `CONDITIONAL_BLOCK` rules. Backtesting
   * for `VELOCITY_LIMIT` rules is generally not supported. In specific cases (i.e.
   * where Lithic has pre-calculated the requested velocity metrics for historical
   * transactions), a backtest may be feasible. However, such cases are uncommon and
   * customers should not anticipate support for velocity backtests under most
   * configurations. If a historical transaction does not feature the required inputs
   * to evaluate the rule, then it will not be included in the final backtest report.
   */
  create(
    authRuleToken: string,
    body: BacktestCreateParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<BacktestCreateResponse> {
    return this._client.post(`/v2/auth_rules/${authRuleToken}/backtests`, { body, ...options });
  }

  /**
   * Returns the backtest results of an authorization rule (if available).
   *
   * Backtesting is an asynchronous process that requires time to complete. If a
   * customer retrieves the backtest results using this endpoint before the report is
   * fully generated, the response will return null for `results.current_version` and
   * `results.draft_version`. Customers are advised to wait for the backtest creation
   * process to complete (as indicated by the webhook event
   * auth_rules.backtest_report.created) before retrieving results from this
   * endpoint.
   *
   * Backtesting is an asynchronous process, while the backtest is being processed,
   * results will not be available which will cause `results.current_version` and
   * `results.draft_version` objects to contain `null`. The entries in `results` will
   * also always represent the configuration of the rule at the time requests are
   * made to this endpoint. For example, the results for `current_version` in the
   * served backtest report will be consistent with which version of the rule is
   * currently activated in the Auth Stream, regardless of which version of the rule
   * was active in the Auth Stream at the time a backtest is requested.
   */
  retrieve(
    authRuleToken: string,
    authRuleBacktestToken: string,
    options?: Core.RequestOptions,
  ): Core.APIPromise<BacktestResults> {
    return this._client.get(`/v2/auth_rules/${authRuleToken}/backtests/${authRuleBacktestToken}`, options);
  }
}

export interface BacktestResults {
  /**
   * Auth Rule Backtest Token
   */
  backtest_token: string;

  results: BacktestResults.Results;

  simulation_parameters: BacktestResults.SimulationParameters;
}

export namespace BacktestResults {
  export interface Results {
    current_version?: Results.CurrentVersion | null;

    draft_version?: Results.DraftVersion | null;
  }

  export namespace Results {
    export interface CurrentVersion {
      /**
       * The total number of historical transactions approved by this rule during the
       * backtest period, or the number of transactions that would have been approved if
       * the rule was evaluated in shadow mode.
       */
      approved?: number;

      /**
       * The total number of historical transactions declined by this rule during the
       * backtest period, or the number of transactions that would have been declined if
       * the rule was evaluated in shadow mode.
       */
      declined?: number;

      /**
       * Example authorization request events that would have been approved or declined.
       */
      examples?: Array<CurrentVersion.Example>;

      /**
       * The version of the rule, this is incremented whenever the rule's parameters
       * change.
       */
      version?: number;
    }

    export namespace CurrentVersion {
      export interface Example {
        /**
         * Whether the rule would have approved the authorization request.
         */
        approved?: boolean;

        /**
         * The authorization request event token.
         */
        event_token?: string;

        /**
         * The timestamp of the authorization request event.
         */
        timestamp?: string;
      }
    }

    export interface DraftVersion {
      /**
       * The total number of historical transactions approved by this rule during the
       * backtest period, or the number of transactions that would have been approved if
       * the rule was evaluated in shadow mode.
       */
      approved?: number;

      /**
       * The total number of historical transactions declined by this rule during the
       * backtest period, or the number of transactions that would have been declined if
       * the rule was evaluated in shadow mode.
       */
      declined?: number;

      /**
       * Example authorization request events that would have been approved or declined.
       */
      examples?: Array<DraftVersion.Example>;

      /**
       * The version of the rule, this is incremented whenever the rule's parameters
       * change.
       */
      version?: number;
    }

    export namespace DraftVersion {
      export interface Example {
        /**
         * Whether the rule would have approved the authorization request.
         */
        approved?: boolean;

        /**
         * The authorization request event token.
         */
        event_token?: string;

        /**
         * The timestamp of the authorization request event.
         */
        timestamp?: string;
      }
    }
  }

  export interface SimulationParameters {
    /**
     * Auth Rule Token
     */
    auth_rule_token?: string;

    /**
     * The end time of the simulation.
     */
    end?: string;

    /**
     * The start time of the simulation.
     */
    start?: string;
  }
}

export interface BacktestCreateResponse {
  /**
   * Auth Rule Backtest Token
   */
  backtest_token?: string;
}

export interface BacktestCreateParams {
  /**
   * The end time of the backtest.
   */
  end?: string;

  /**
   * The start time of the backtest.
   */
  start?: string;
}

export declare namespace Backtests {
  export {
    type BacktestResults as BacktestResults,
    type BacktestCreateResponse as BacktestCreateResponse,
    type BacktestCreateParams as BacktestCreateParams,
  };
}