/**
 * PayPal Server SDKLib
 *
 * This file was automatically generated by APIMATIC v3.0 ( https://www.apimatic.io ).
 */

import { ApiResponse, RequestOptions } from '../core.js';
import {
  ActivateSubscriptionRequest,
  activateSubscriptionRequestSchema,
} from '../models/activateSubscriptionRequest.js';
import { BillingPlan, billingPlanSchema } from '../models/billingPlan.js';
import {
  CancelSubscriptionRequest,
  cancelSubscriptionRequestSchema,
} from '../models/cancelSubscriptionRequest.js';
import {
  CaptureSubscriptionRequest,
  captureSubscriptionRequestSchema,
} from '../models/captureSubscriptionRequest.js';
import {
  CreateSubscriptionRequest,
  createSubscriptionRequestSchema,
} from '../models/createSubscriptionRequest.js';
import {
  ModifySubscriptionRequest,
  modifySubscriptionRequestSchema,
} from '../models/modifySubscriptionRequest.js';
import {
  ModifySubscriptionResponse,
  modifySubscriptionResponseSchema,
} from '../models/modifySubscriptionResponse.js';
import { Patch, patchSchema } from '../models/patch.js';
import {
  PlanCollection,
  planCollectionSchema,
} from '../models/planCollection.js';
import { PlanRequest, planRequestSchema } from '../models/planRequest.js';
import { Subscription, subscriptionSchema } from '../models/subscription.js';
import {
  SubscriptionCollection,
  subscriptionCollectionSchema,
} from '../models/subscriptionCollection.js';
import {
  SubscriptionTransactionDetails,
  subscriptionTransactionDetailsSchema,
} from '../models/subscriptionTransactionDetails.js';
import {
  SuspendSubscription,
  suspendSubscriptionSchema,
} from '../models/suspendSubscription.js';
import {
  TransactionsList,
  transactionsListSchema,
} from '../models/transactionsList.js';
import {
  UpdatePricingSchemesRequest,
  updatePricingSchemesRequestSchema,
} from '../models/updatePricingSchemesRequest.js';
import {
  array,
  boolean,
  nullable,
  number,
  optional,
  string,
} from '../schema.js';
import { BaseController } from './baseController.js';
import { SubscriptionError } from '../errors/subscriptionError.js';

export class SubscriptionsController extends BaseController {
  /**
   * Creates a plan that defines pricing and billing cycle details for subscriptions.
   *
   * @param prefer            The preferred server response upon successful completion of the
   *                                                request. Value is: return=minimal. The server returns a minimal
   *                                                response to optimize communication between the API caller and the
   *                                                server. A minimal response includes the id, status and HATEOAS
   *                                                links. return=representation. The server returns a complete
   *                                                resource representation, including the current state of the
   *                                                resource.
   * @param paypalRequestId   The server stores keys for 72 hours.
   * @param body
   * @return Response from the API call
   */
  async createBillingPlan(
    {
      prefer,
      paypalRequestId,
      body,
    }: {
      prefer?: string;
      paypalRequestId?: string;
      body?: PlanRequest;
    },
    requestOptions?: RequestOptions
  ): Promise<ApiResponse<BillingPlan>> {
    const req = this.createRequest('POST', '/v1/billing/plans');
    const mapped = req.prepareArgs({
      prefer: [prefer, optional(string())],
      paypalRequestId: [paypalRequestId, optional(string())],
      body: [body, optional(planRequestSchema)],
    });
    req.header('Content-Type', 'application/json');
    req.header('Prefer', mapped.prefer);
    req.header('PayPal-Request-Id', mapped.paypalRequestId);
    req.json(mapped.body);
    req.throwOn(
      400,
      SubscriptionError,
      'Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.'
    );
    req.throwOn(
      401,
      SubscriptionError,
      'Authentication failed due to missing authorization header, or invalid authentication credentials.'
    );
    req.throwOn(
      403,
      SubscriptionError,
      'Authorization failed due to insufficient permissions.'
    );
    req.throwOn(
      422,
      SubscriptionError,
      'The requested action could not be performed, semantically incorrect, or failed business validation.'
    );
    req.throwOn(
      500,
      SubscriptionError,
      'An internal server error has occurred.'
    );
    req.defaultToError(SubscriptionError, 'The error response.');
    req.authenticate([{ oauth2: true }]);
    return req.callAsJson(billingPlanSchema, requestOptions);
  }

  /**
   * Lists billing plans.
   *
   * @param prefer         The preferred server response upon successful completion of the request. Value
   *                                  is: return=minimal. The server returns a minimal response to optimize
   *                                  communication between the API caller and the server. A minimal response includes
   *                                  the id, name, description and HATEOAS links. return=representation. The server
   *                                  returns a complete resource representation, including the current state of the
   *                                  resource.
   * @param productId      Filters the response by a Product ID.
   * @param pageSize       The number of items to return in the response.
   * @param page           A non-zero integer which is the start index of the entire list of items to
   *                                  return in the response. The combination of `page=1` and `page_size=20` returns
   *                                  the first 20 items. The combination of `page=2` and `page_size=20` returns the
   *                                  next 20 items.
   * @param totalRequired  Indicates whether to show the total count in the response.
   * @return Response from the API call
   */
  async listBillingPlans(
    {
      prefer,
      productId,
      pageSize,
      page,
      totalRequired,
    }: {
      prefer?: string;
      productId?: string;
      pageSize?: number;
      page?: number;
      totalRequired?: boolean;
    },
    requestOptions?: RequestOptions
  ): Promise<ApiResponse<PlanCollection>> {
    const req = this.createRequest('GET', '/v1/billing/plans');
    const mapped = req.prepareArgs({
      prefer: [prefer, optional(string())],
      productId: [productId, optional(string())],
      pageSize: [pageSize, optional(number())],
      page: [page, optional(number())],
      totalRequired: [totalRequired, optional(boolean())],
    });
    req.header('Prefer', mapped.prefer);
    req.query('product_id', mapped.productId);
    req.query('page_size', mapped.pageSize);
    req.query('page', mapped.page);
    req.query('total_required', mapped.totalRequired);
    req.throwOn(
      400,
      SubscriptionError,
      'Request is not well-formed, syntactically incorrect, or violates schema.'
    );
    req.throwOn(
      401,
      SubscriptionError,
      'Authentication failed due to missing authorization header, or invalid authentication credentials.'
    );
    req.throwOn(
      403,
      SubscriptionError,
      'Authorization failed due to insufficient permissions.'
    );
    req.throwOn(
      404,
      SubscriptionError,
      'The specified resource does not exist.'
    );
    req.throwOn(
      500,
      SubscriptionError,
      'An internal server error has occurred.'
    );
    req.defaultToError(SubscriptionError, 'The error response.');
    req.authenticate([{ oauth2: true }]);
    return req.callAsJson(planCollectionSchema, requestOptions);
  }

  /**
   * Shows details for a plan, by ID.
   *
   * @param id The ID of the plan.
   * @return Response from the API call
   */
  async getBillingPlan(
    id: string,
    requestOptions?: RequestOptions
  ): Promise<ApiResponse<BillingPlan>> {
    const req = this.createRequest('GET');
    const mapped = req.prepareArgs({ id: [id, string()] });
    req.appendTemplatePath`/v1/billing/plans/${mapped.id}`;
    req.throwOn(
      401,
      SubscriptionError,
      'Authentication failed due to missing authorization header, or invalid authentication credentials.'
    );
    req.throwOn(
      403,
      SubscriptionError,
      'Authorization failed due to insufficient permissions.'
    );
    req.throwOn(
      404,
      SubscriptionError,
      'The specified resource does not exist.'
    );
    req.throwOn(
      500,
      SubscriptionError,
      'An internal server error has occurred.'
    );
    req.defaultToError(SubscriptionError, 'The error response.');
    req.authenticate([{ oauth2: true }]);
    return req.callAsJson(billingPlanSchema, requestOptions);
  }

  /**
   * Updates a plan with the `CREATED` or `ACTIVE` status. For an `INACTIVE` plan, you can make only
   * status updates. You can patch these attributes and objects: Attribute or object Operations
   * description replace payment_preferences.auto_bill_outstanding replace taxes.percentage replace
   * payment_preferences.payment_failure_threshold replace payment_preferences.setup_fee replace
   * payment_preferences.setup_fee_failure_action replace name replace
   *
   * @param id           The ID of the plan.
   * @param body
   * @return Response from the API call
   */
  async patchBillingPlan(
    {
      id,
      body,
    }: {
      id: string;
      body?: Patch[];
    },
    requestOptions?: RequestOptions
  ): Promise<ApiResponse<void>> {
    const req = this.createRequest('PATCH');
    const mapped = req.prepareArgs({
      id: [id, string()],
      body: [body, optional(array(patchSchema))],
    });
    req.header('Content-Type', 'application/json');
    req.json(mapped.body);
    req.appendTemplatePath`/v1/billing/plans/${mapped.id}`;
    req.throwOn(
      400,
      SubscriptionError,
      'Request is not well-formed, syntactically incorrect, or violates schema.'
    );
    req.throwOn(
      401,
      SubscriptionError,
      'Authentication failed due to missing authorization header, or invalid authentication credentials.'
    );
    req.throwOn(
      403,
      SubscriptionError,
      'Authorization failed due to insufficient permissions.'
    );
    req.throwOn(
      404,
      SubscriptionError,
      'The specified resource does not exist.'
    );
    req.throwOn(
      422,
      SubscriptionError,
      'The requested action could not be performed, semantically incorrect, or failed business validation.'
    );
    req.throwOn(
      500,
      SubscriptionError,
      'An internal server error has occurred.'
    );
    req.defaultToError(SubscriptionError, 'The error response.');
    req.authenticate([{ oauth2: true }]);
    return req.call(requestOptions);
  }

  /**
   * Activates a plan, by ID.
   *
   * @param id The ID of the plan.
   * @return Response from the API call
   */
  async activateBillingPlan(
    id: string,
    requestOptions?: RequestOptions
  ): Promise<ApiResponse<void>> {
    const req = this.createRequest('POST');
    const mapped = req.prepareArgs({ id: [id, string()] });
    req.appendTemplatePath`/v1/billing/plans/${mapped.id}/activate`;
    req.throwOn(
      401,
      SubscriptionError,
      'Authentication failed due to missing authorization header, or invalid authentication credentials.'
    );
    req.throwOn(
      403,
      SubscriptionError,
      'Authorization failed due to insufficient permissions.'
    );
    req.throwOn(
      404,
      SubscriptionError,
      'The specified resource does not exist.'
    );
    req.throwOn(
      422,
      SubscriptionError,
      'The requested action could not be performed, semantically incorrect, or failed business validation.'
    );
    req.throwOn(
      500,
      SubscriptionError,
      'An internal server error has occurred.'
    );
    req.defaultToError(SubscriptionError, 'The error response.');
    req.authenticate([{ oauth2: true }]);
    return req.call(requestOptions);
  }

  /**
   * Deactivates a plan, by ID.
   *
   * @param id The ID of the plan.
   * @return Response from the API call
   */
  async deactivateBillingPlan(
    id: string,
    requestOptions?: RequestOptions
  ): Promise<ApiResponse<void>> {
    const req = this.createRequest('POST');
    const mapped = req.prepareArgs({ id: [id, string()] });
    req.appendTemplatePath`/v1/billing/plans/${mapped.id}/deactivate`;
    req.throwOn(
      401,
      SubscriptionError,
      'Authentication failed due to missing authorization header, or invalid authentication credentials.'
    );
    req.throwOn(
      403,
      SubscriptionError,
      'Authorization failed due to insufficient permissions.'
    );
    req.throwOn(
      404,
      SubscriptionError,
      'The specified resource does not exist.'
    );
    req.throwOn(
      422,
      SubscriptionError,
      'The requested action could not be performed, semantically incorrect, or failed business validation.'
    );
    req.throwOn(
      500,
      SubscriptionError,
      'An internal server error has occurred.'
    );
    req.defaultToError(SubscriptionError, 'The error response.');
    req.authenticate([{ oauth2: true }]);
    return req.call(requestOptions);
  }

  /**
   * Updates pricing for a plan. For example, you can update a regular billing cycle from $5 per month to
   * $7 per month.
   *
   * @param id           The ID for the plan.
   * @param body
   * @return Response from the API call
   */
  async updateBillingPlanPricingSchemes(
    {
      id,
      body,
    }: {
      id: string;
      body?: UpdatePricingSchemesRequest;
    },
    requestOptions?: RequestOptions
  ): Promise<ApiResponse<void>> {
    const req = this.createRequest('POST');
    const mapped = req.prepareArgs({
      id: [id, string()],
      body: [body, optional(updatePricingSchemesRequestSchema)],
    });
    req.header('Content-Type', 'application/json');
    req.json(mapped.body);
    req.appendTemplatePath`/v1/billing/plans/${mapped.id}/update-pricing-schemes`;
    req.throwOn(
      400,
      SubscriptionError,
      'Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.'
    );
    req.throwOn(
      401,
      SubscriptionError,
      'Authentication failed due to missing authorization header, or invalid authentication credentials.'
    );
    req.throwOn(
      403,
      SubscriptionError,
      'Authorization failed due to insufficient permissions.'
    );
    req.throwOn(
      404,
      SubscriptionError,
      'The specified resource does not exist.'
    );
    req.throwOn(
      422,
      SubscriptionError,
      'The requested action could not be performed, semantically incorrect, or failed business validation.'
    );
    req.throwOn(
      500,
      SubscriptionError,
      'An internal server error has occurred.'
    );
    req.defaultToError(SubscriptionError, 'The error response.');
    req.authenticate([{ oauth2: true }]);
    return req.call(requestOptions);
  }

  /**
   * Creates a subscription.
   *
   * @param prefer                    The preferred server response upon
   *                                                                      successful completion of the request. Value
   *                                                                      is: return=minimal. The server returns a
   *                                                                      minimal response to optimize communication
   *                                                                      between the API caller and the server. A
   *                                                                      minimal response includes the id, status and
   *                                                                      HATEOAS links. return=representation. The
   *                                                                      server returns a complete resource
   *                                                                      representation, including the current state
   *                                                                      of the resource.
   * @param paypalRequestId           The server stores keys for 72 hours.
   * @param paypalClientMetadataId    The PayPal Client Metadata Id(CMID) is used
   *                                                                      to provide device-specific information to
   *                                                                      PayPal's risk engine. This is crucial for
   *                                                                      transactions that require device-specific
   *                                                                      risk assessments. Merchants typically use the
   *                                                                      Paypal SDK that automatically submits the
   *                                                                      CMID or they use tools like Fraudnet JS for
   *                                                                      web or Magnes JS for mobile to generate the
   *                                                                      CMID on the frontend and then pass it to the
   *                                                                      API as part of the request headers.
   * @param body
   * @return Response from the API call
   */
  async createSubscription(
    {
      prefer,
      paypalRequestId,
      paypalClientMetadataId,
      body,
    }: {
      prefer?: string;
      paypalRequestId?: string;
      paypalClientMetadataId?: string;
      body?: CreateSubscriptionRequest;
    },
    requestOptions?: RequestOptions
  ): Promise<ApiResponse<Subscription>> {
    const req = this.createRequest('POST', '/v1/billing/subscriptions');
    const mapped = req.prepareArgs({
      prefer: [prefer, optional(string())],
      paypalRequestId: [paypalRequestId, optional(string())],
      paypalClientMetadataId: [paypalClientMetadataId, optional(string())],
      body: [body, optional(createSubscriptionRequestSchema)],
    });
    req.header('Content-Type', 'application/json');
    req.header('Prefer', mapped.prefer);
    req.header('PayPal-Request-Id', mapped.paypalRequestId);
    req.header('PayPal-Client-Metadata-Id', mapped.paypalClientMetadataId);
    req.json(mapped.body);
    req.throwOn(
      400,
      SubscriptionError,
      'Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.'
    );
    req.throwOn(
      401,
      SubscriptionError,
      'Authentication failed due to missing authorization header, or invalid authentication credentials.'
    );
    req.throwOn(
      403,
      SubscriptionError,
      'Authorization failed due to insufficient permissions.'
    );
    req.throwOn(
      422,
      SubscriptionError,
      'The requested action could not be performed, semantically incorrect, or failed business validation.'
    );
    req.throwOn(
      500,
      SubscriptionError,
      'An internal server error has occurred.'
    );
    req.defaultToError(SubscriptionError, 'The error response.');
    req.authenticate([{ oauth2: true }]);
    return req.callAsJson(subscriptionSchema, requestOptions);
  }

  /**
   * List all subscriptions for merchant account.
   *
   * @param planIds               Filters the response by list of plan IDs. Filter supports upto 70 plan
   *                                          IDs. URLs should not exceed a length of 2000 characters.
   * @param statuses              Filters the response by list of subscription statuses.
   * @param createdAfter          Filters the response by subscription creation start time for a range of
   *                                          subscriptions.
   * @param createdBefore         Filters the response by subscription creation end time for a range of
   *                                          subscriptions.
   * @param statusUpdatedBefore   Filters the response by status update start time for a range of
   *                                          subscriptions.
   * @param statusUpdatedAfter    Filters the response by status update end time for a range of
   *                                          subscriptions.
   * @param filter                Filter the response using complex expressions that could use comparison
   *                                          operators like ge, gt, le, lt and logical operators such as 'and' and
   *                                          'or'.
   * @param pageSize              The number of items to return in the response.
   * @param page                  A non-zero integer which is the start index of the entire list of items
   *                                          to return in the response. The combination of `page=1` and `page_size=20`
   *                                          returns the first 20 items. The combination of `page=2` and
   *                                          `page_size=20` returns the next 20 items.
   * @param customerIds           Filters the response by comma separated vault customer IDs (FSS
   *                                          subscriptions only).
   * @return Response from the API call
   */
  async listSubscriptions(
    {
      planIds,
      statuses,
      createdAfter,
      createdBefore,
      statusUpdatedBefore,
      statusUpdatedAfter,
      filter,
      pageSize,
      page,
      customerIds,
    }: {
      planIds?: string;
      statuses?: string;
      createdAfter?: string;
      createdBefore?: string;
      statusUpdatedBefore?: string;
      statusUpdatedAfter?: string;
      filter?: string;
      pageSize?: number;
      page?: number;
      customerIds?: string[];
    },
    requestOptions?: RequestOptions
  ): Promise<ApiResponse<SubscriptionCollection>> {
    const req = this.createRequest('GET', '/v1/billing/subscriptions');
    const mapped = req.prepareArgs({
      planIds: [planIds, optional(string())],
      statuses: [statuses, optional(string())],
      createdAfter: [createdAfter, optional(string())],
      createdBefore: [createdBefore, optional(string())],
      statusUpdatedBefore: [statusUpdatedBefore, optional(string())],
      statusUpdatedAfter: [statusUpdatedAfter, optional(string())],
      filter: [filter, optional(string())],
      pageSize: [pageSize, optional(number())],
      page: [page, optional(number())],
      customerIds: [customerIds, optional(array(string()))],
    });
    req.query('plan_ids', mapped.planIds);
    req.query('statuses', mapped.statuses);
    req.query('created_after', mapped.createdAfter);
    req.query('created_before', mapped.createdBefore);
    req.query('status_updated_before', mapped.statusUpdatedBefore);
    req.query('status_updated_after', mapped.statusUpdatedAfter);
    req.query('filter', mapped.filter);
    req.query('page_size', mapped.pageSize);
    req.query('page', mapped.page);
    req.query('customer_ids', mapped.customerIds);
    req.throwOn(
      400,
      SubscriptionError,
      'Request is not well-formed, syntactically incorrect, or violates schema.'
    );
    req.throwOn(
      401,
      SubscriptionError,
      'Authentication failed due to missing authorization header, or invalid authentication credentials.'
    );
    req.throwOn(
      403,
      SubscriptionError,
      'Authorization failed due to insufficient permissions.'
    );
    req.throwOn(
      500,
      SubscriptionError,
      'An internal server error has occurred.'
    );
    req.defaultToError(SubscriptionError, 'The error response.');
    req.authenticate([{ oauth2: true }]);
    return req.callAsJson(subscriptionCollectionSchema, requestOptions);
  }

  /**
   * Shows details for a subscription, by ID.
   *
   * @param id     The ID of the subscription.
   * @param fields List of fields that are to be returned in the response. Possible value for fields are
   *                         last_failed_payment and plan.
   * @return Response from the API call
   */
  async getSubscription(
    {
      id,
      fields,
    }: {
      id: string;
      fields?: string;
    },
    requestOptions?: RequestOptions
  ): Promise<ApiResponse<Subscription>> {
    const req = this.createRequest('GET');
    const mapped = req.prepareArgs({
      id: [id, string()],
      fields: [fields, optional(string())],
    });
    req.query('fields', mapped.fields);
    req.appendTemplatePath`/v1/billing/subscriptions/${mapped.id}`;
    req.throwOn(
      401,
      SubscriptionError,
      'Authentication failed due to missing authorization header, or invalid authentication credentials.'
    );
    req.throwOn(
      403,
      SubscriptionError,
      'Authorization failed due to insufficient permissions.'
    );
    req.throwOn(
      404,
      SubscriptionError,
      'The specified resource does not exist.'
    );
    req.throwOn(
      500,
      SubscriptionError,
      'An internal server error has occurred.'
    );
    req.defaultToError(SubscriptionError, 'The error response.');
    req.authenticate([{ oauth2: true }]);
    return req.callAsJson(subscriptionSchema, requestOptions);
  }

  /**
   * Updates a subscription which could be in ACTIVE or SUSPENDED status. You can override plan level
   * default attributes by providing customised values for plan path in the patch request. You cannot
   * update attributes that have already completed (Example - trial cycles can’t be updated if completed).
   * Once overridden, changes to plan resource will not impact subscription. Any price update will not
   * impact billing cycles within next 10 days (Applicable only for subscriptions funded by PayPal
   * account). Following are the fields eligible for patch. Attribute or object Operations billing_info.
   * outstanding_balance replace custom_id add,replace plan.billing_cycles[@sequence==n]. pricing_scheme.
   * fixed_price add,replace plan.billing_cycles[@sequence==n]. pricing_scheme.tiers replace plan.
   * billing_cycles[@sequence==n]. total_cycles replace plan.payment_preferences. auto_bill_outstanding
   * replace plan.payment_preferences. payment_failure_threshold replace plan.taxes.inclusive add,replace
   * plan.taxes.percentage add,replace shipping_amount add,replace start_time replace subscriber.
   * shipping_address add,replace subscriber.payment_source (for subscriptions funded by card payments)
   * replace
   *
   * @param id           The ID for the subscription.
   * @param body
   * @return Response from the API call
   */
  async patchSubscription(
    {
      id,
      body,
    }: {
      id: string;
      body?: Patch[];
    },
    requestOptions?: RequestOptions
  ): Promise<ApiResponse<void>> {
    const req = this.createRequest('PATCH');
    const mapped = req.prepareArgs({
      id: [id, string()],
      body: [body, optional(array(patchSchema))],
    });
    req.header('Content-Type', 'application/json');
    req.json(mapped.body);
    req.appendTemplatePath`/v1/billing/subscriptions/${mapped.id}`;
    req.throwOn(
      400,
      SubscriptionError,
      'Request is not well-formed, syntactically incorrect, or violates schema.'
    );
    req.throwOn(
      401,
      SubscriptionError,
      'Authentication failed due to missing authorization header, or invalid authentication credentials.'
    );
    req.throwOn(
      403,
      SubscriptionError,
      'Authorization failed due to insufficient permissions.'
    );
    req.throwOn(
      404,
      SubscriptionError,
      'The specified resource does not exist.'
    );
    req.throwOn(
      422,
      SubscriptionError,
      'The requested action could not be performed, semantically incorrect, or failed business validation.'
    );
    req.throwOn(
      500,
      SubscriptionError,
      'An internal server error has occurred.'
    );
    req.defaultToError(SubscriptionError, 'The error response.');
    req.authenticate([{ oauth2: true }]);
    return req.call(requestOptions);
  }

  /**
   * Updates the quantity of the product or service in a subscription. You can also use this method to
   * switch the plan and update the `shipping_amount`, `shipping_address` values for the subscription.
   * This type of update requires the buyer's consent.
   *
   * @param id           The ID of the subscription.
   * @param body
   * @return Response from the API call
   */
  async reviseSubscription(
    {
      id,
      body,
    }: {
      id: string;
      body?: ModifySubscriptionRequest;
    },
    requestOptions?: RequestOptions
  ): Promise<ApiResponse<ModifySubscriptionResponse>> {
    const req = this.createRequest('POST');
    const mapped = req.prepareArgs({
      id: [id, string()],
      body: [body, optional(modifySubscriptionRequestSchema)],
    });
    req.header('Content-Type', 'application/json');
    req.json(mapped.body);
    req.appendTemplatePath`/v1/billing/subscriptions/${mapped.id}/revise`;
    req.throwOn(
      400,
      SubscriptionError,
      'Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.'
    );
    req.throwOn(
      401,
      SubscriptionError,
      'Authentication failed due to missing authorization header, or invalid authentication credentials.'
    );
    req.throwOn(
      403,
      SubscriptionError,
      'Authorization failed due to insufficient permissions.'
    );
    req.throwOn(
      404,
      SubscriptionError,
      'The specified resource does not exist.'
    );
    req.throwOn(
      422,
      SubscriptionError,
      'The requested action could not be performed, semantically incorrect, or failed business validation.'
    );
    req.throwOn(
      500,
      SubscriptionError,
      'An internal server error has occurred.'
    );
    req.defaultToError(SubscriptionError, 'The error response.');
    req.authenticate([{ oauth2: true }]);
    return req.callAsJson(modifySubscriptionResponseSchema, requestOptions);
  }

  /**
   * Suspends the subscription.
   *
   * @param id           The ID of the subscription.
   * @param body
   * @return Response from the API call
   */
  async suspendSubscription(
    {
      id,
      body,
    }: {
      id: string;
      body?: SuspendSubscription;
    },
    requestOptions?: RequestOptions
  ): Promise<ApiResponse<void>> {
    const req = this.createRequest('POST');
    const mapped = req.prepareArgs({
      id: [id, string()],
      body: [body, optional(suspendSubscriptionSchema)],
    });
    req.header('Content-Type', 'application/json');
    req.json(mapped.body);
    req.appendTemplatePath`/v1/billing/subscriptions/${mapped.id}/suspend`;
    req.throwOn(
      400,
      SubscriptionError,
      'Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.'
    );
    req.throwOn(
      401,
      SubscriptionError,
      'Authentication failed due to missing authorization header, or invalid authentication credentials.'
    );
    req.throwOn(
      403,
      SubscriptionError,
      'Authorization failed due to insufficient permissions.'
    );
    req.throwOn(
      404,
      SubscriptionError,
      'The specified resource does not exist.'
    );
    req.throwOn(
      422,
      SubscriptionError,
      'The requested action could not be performed, semantically incorrect, or failed business validation.'
    );
    req.throwOn(
      500,
      SubscriptionError,
      'An internal server error has occurred.'
    );
    req.defaultToError(SubscriptionError, 'The error response.');
    req.authenticate([{ oauth2: true }]);
    return req.call(requestOptions);
  }

  /**
   * Cancels the subscription.
   *
   * @param id           The ID of the subscription.
   * @param body
   * @return Response from the API call
   */
  async cancelSubscription(
    {
      id,
      body,
    }: {
      id: string;
      body?: CancelSubscriptionRequest;
    },
    requestOptions?: RequestOptions
  ): Promise<ApiResponse<void>> {
    const req = this.createRequest('POST');
    const mapped = req.prepareArgs({
      id: [id, string()],
      body: [body, optional(cancelSubscriptionRequestSchema)],
    });
    req.header('Content-Type', 'application/json');
    req.json(mapped.body);
    req.appendTemplatePath`/v1/billing/subscriptions/${mapped.id}/cancel`;
    req.throwOn(
      400,
      SubscriptionError,
      'Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.'
    );
    req.throwOn(
      401,
      SubscriptionError,
      'Authentication failed due to missing authorization header, or invalid authentication credentials.'
    );
    req.throwOn(
      403,
      SubscriptionError,
      'Authorization failed due to insufficient permissions.'
    );
    req.throwOn(
      404,
      SubscriptionError,
      'The specified resource does not exist.'
    );
    req.throwOn(
      422,
      SubscriptionError,
      'The requested action could not be performed, semantically incorrect, or failed business validation.'
    );
    req.throwOn(
      500,
      SubscriptionError,
      'An internal server error has occurred.'
    );
    req.defaultToError(SubscriptionError, 'The error response.');
    req.authenticate([{ oauth2: true }]);
    return req.call(requestOptions);
  }

  /**
   * Activates the subscription.
   *
   * @param id           The ID of the subscription.
   * @param body
   * @return Response from the API call
   */
  async activateSubscription(
    {
      id,
      body,
    }: {
      id: string;
      body?: ActivateSubscriptionRequest;
    },
    requestOptions?: RequestOptions
  ): Promise<ApiResponse<void>> {
    const req = this.createRequest('POST');
    const mapped = req.prepareArgs({
      id: [id, string()],
      body: [body, optional(activateSubscriptionRequestSchema)],
    });
    req.header('Content-Type', 'application/json');
    req.json(mapped.body);
    req.appendTemplatePath`/v1/billing/subscriptions/${mapped.id}/activate`;
    req.throwOn(
      400,
      SubscriptionError,
      'Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.'
    );
    req.throwOn(
      401,
      SubscriptionError,
      'Authentication failed due to missing authorization header, or invalid authentication credentials.'
    );
    req.throwOn(
      403,
      SubscriptionError,
      'Authorization failed due to insufficient permissions.'
    );
    req.throwOn(
      404,
      SubscriptionError,
      'The specified resource does not exist.'
    );
    req.throwOn(
      422,
      SubscriptionError,
      'The requested action could not be performed, semantically incorrect, or failed business validation.'
    );
    req.throwOn(
      500,
      SubscriptionError,
      'An internal server error has occurred.'
    );
    req.defaultToError(SubscriptionError, 'The error response.');
    req.authenticate([{ oauth2: true }]);
    return req.call(requestOptions);
  }

  /**
   * Captures an authorized payment from the subscriber on the subscription.
   *
   * @param id                The ID of the subscription.
   * @param paypalRequestId   The server stores keys for 72 hours.
   * @param body
   * @return Response from the API call
   */
  async captureSubscription(
    {
      id,
      paypalRequestId,
      body,
    }: {
      id: string;
      paypalRequestId?: string;
      body?: CaptureSubscriptionRequest;
    },
    requestOptions?: RequestOptions
  ): Promise<ApiResponse<SubscriptionTransactionDetails | null>> {
    const req = this.createRequest('POST');
    const mapped = req.prepareArgs({
      id: [id, string()],
      paypalRequestId: [paypalRequestId, optional(string())],
      body: [body, optional(captureSubscriptionRequestSchema)],
    });
    req.header('Content-Type', 'application/json');
    req.header('PayPal-Request-Id', mapped.paypalRequestId);
    req.json(mapped.body);
    req.appendTemplatePath`/v1/billing/subscriptions/${mapped.id}/capture`;
    req.throwOn(
      400,
      SubscriptionError,
      'Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.'
    );
    req.throwOn(
      401,
      SubscriptionError,
      'Authentication failed due to missing authorization header, or invalid authentication credentials.'
    );
    req.throwOn(
      403,
      SubscriptionError,
      'Authorization failed due to insufficient permissions.'
    );
    req.throwOn(
      404,
      SubscriptionError,
      'The specified resource does not exist.'
    );
    req.throwOn(
      422,
      SubscriptionError,
      'The requested action could not be performed, semantically incorrect, or failed business validation.'
    );
    req.throwOn(
      500,
      SubscriptionError,
      'An internal server error has occurred.'
    );
    req.defaultToError(SubscriptionError, 'The error response.');
    req.authenticate([{ oauth2: true }]);
    return req.callAsJson(
      nullable(subscriptionTransactionDetailsSchema),
      requestOptions
    );
  }

  /**
   * Lists transactions for a subscription.
   *
   * @param id         The ID of the subscription.
   * @param startTime  The start time of the range of transactions to list.
   * @param endTime    The end time of the range of transactions to list.
   * @return Response from the API call
   */
  async listSubscriptionTransactions(
    {
      id,
      startTime,
      endTime,
    }: {
      id: string;
      startTime: string;
      endTime: string;
    },
    requestOptions?: RequestOptions
  ): Promise<ApiResponse<TransactionsList>> {
    const req = this.createRequest('GET');
    const mapped = req.prepareArgs({
      id: [id, string()],
      startTime: [startTime, string()],
      endTime: [endTime, string()],
    });
    req.query('start_time', mapped.startTime);
    req.query('end_time', mapped.endTime);
    req.appendTemplatePath`/v1/billing/subscriptions/${mapped.id}/transactions`;
    req.throwOn(
      400,
      SubscriptionError,
      'Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.'
    );
    req.throwOn(
      401,
      SubscriptionError,
      'Authentication failed due to missing authorization header, or invalid authentication credentials.'
    );
    req.throwOn(
      403,
      SubscriptionError,
      'Authorization failed due to insufficient permissions.'
    );
    req.throwOn(
      404,
      SubscriptionError,
      'The specified resource does not exist.'
    );
    req.throwOn(
      500,
      SubscriptionError,
      'An internal server error has occurred.'
    );
    req.defaultToError(SubscriptionError, 'The error response.');
    req.authenticate([{ oauth2: true }]);
    return req.callAsJson(transactionsListSchema, requestOptions);
  }
}