File

src/api/request.ts

Description

Class representing a request. Instances of this class can be accepted, paid, refunded, etc. Use the member function getData to access the properties of the Request.

Requests should be created with RequestNetwork.createRequest().

Index

Properties
Methods

Constructor

constructor(requestLogic: RequestLogicTypes.IRequestLogic, requestId: RequestLogicTypes.RequestId, paymentNetwork?: Types.IPaymentNetwork | null, contentDataExtension?: ContentDataExtension | null)

Creates an instance of Request

Parameters :
Name Type Optional Description
requestLogic RequestLogicTypes.IRequestLogic No

Instance of the request-logic layer

requestId RequestLogicTypes.RequestId No

ID of the Request

paymentNetwork Types.IPaymentNetwork | null Yes

Instance of a payment network to manage the request

contentDataExtension ContentDataExtension | null Yes

Properties

Public Readonly requestId
Type : RequestLogicTypes.RequestId

Unique ID of the request

Methods

Public Async accept
accept(signerIdentity: IdentityTypes.IIdentity, refundInformation?: any)

Accepts a request

Parameters :
Name Type Optional Description
signerIdentity IdentityTypes.IIdentity No

Identity of the signer. The identity type must be supported by the signature provider.

refundInformation any Yes

Refund information to add (any because it is specific to the payment network used by the request)

The updated request

Public Async addPaymentInformation
addPaymentInformation(paymentInformation: any, signerIdentity: IdentityTypes.IIdentity)

Adds payment information

Parameters :
Name Type Optional Description
paymentInformation any No

Payment information to add (any because it is specific to the payment network used by the request)

signerIdentity IdentityTypes.IIdentity No

Identity of the signer. The identity type must be supported by the signature provider.

The updated request

Public Async addRefundInformation
addRefundInformation(refundInformation: any, signerIdentity: IdentityTypes.IIdentity)

Adds refund information

Parameters :
Name Type Optional Description
refundInformation any No

Refund information to add (any because it is specific to the payment network used by the request)

signerIdentity IdentityTypes.IIdentity No

Identity of the signer. The identity type must be supported by the signature provider.

The updated request

Public Async cancel
cancel(signerIdentity: IdentityTypes.IIdentity, refundInformation?: any)

Cancels a request

Parameters :
Name Type Optional Description
signerIdentity IdentityTypes.IIdentity No

Identity of the signer. The identity type must be supported by the signature provider.

refundInformation any Yes

refund information to add (any because it is specific to the payment network used by the request)

The updated request

Public Async declareReceivedPayment
declareReceivedPayment(amount: string, note: string, signerIdentity: IdentityTypes.IIdentity)

Declare a payment is received for the declarative payment network

Parameters :
Name Type Optional Description
amount string No

Amount received

note string No

Note from payee about the received payment

signerIdentity IdentityTypes.IIdentity No

Identity of the signer. The identity type must be supported by the signature provider.

The updated request

Public Async declareReceivedRefund
declareReceivedRefund(amount: string, note: string, signerIdentity: IdentityTypes.IIdentity)

Declare a refund is received for the declarative payment network

Parameters :
Name Type Optional Description
amount string No

Amount received

note string No

Note from payer about the received refund

signerIdentity IdentityTypes.IIdentity No

Identity of the signer. The identity type must be supported by the signature provider.

The updated request

Public Async declareSentPayment
declareSentPayment(amount: string, note: string, signerIdentity: IdentityTypes.IIdentity)

Declare a payment is sent for the declarative payment network

Parameters :
Name Type Optional Description
amount string No

Amount sent

note string No

Note from payer about the sent payment

signerIdentity IdentityTypes.IIdentity No

Identity of the signer. The identity type must be supported by the signature provider.

The updated request

Public Async declareSentRefund
declareSentRefund(amount: string, note: string, signerIdentity: IdentityTypes.IIdentity)

Declare a refund is sent for the declarative payment network

Parameters :
Name Type Optional Description
amount string No

Amount sent

note string No

Note from payee about the sent refund

signerIdentity IdentityTypes.IIdentity No

Identity of the signer. The identity type must be supported by the signature provider.

The updated request

Public getData
getData()

Gets the request data

Returns : Types.IRequestData

The updated request data

Public Async increaseExpectedAmountRequest
increaseExpectedAmountRequest(deltaAmount: RequestLogicTypes.Amount, signerIdentity: IdentityTypes.IIdentity, refundInformation?: any)

Increases the expected amount of the request.

Parameters :
Name Type Optional Description
deltaAmount RequestLogicTypes.Amount No

Amount by which to increase the expected amount

signerIdentity IdentityTypes.IIdentity No

Identity of the signer. The identity type must be supported by the signature provider.

refundInformation any Yes

Refund information to add (any because it is specific to the payment network used by the request)

The updated request

Public Async reduceExpectedAmountRequest
reduceExpectedAmountRequest(deltaAmount: RequestLogicTypes.Amount, signerIdentity: IdentityTypes.IIdentity, paymentInformation?: any)

Reduces the expected amount of the request. This can be called by the payee e.g. to apply discounts or special offers.

Parameters :
Name Type Optional Description
deltaAmount RequestLogicTypes.Amount No

Amount by which to reduce the expected amount

signerIdentity IdentityTypes.IIdentity No

Identity of the signer. The identity type must be supported by the signature provider.

paymentInformation any Yes

Payment information to add (any because it is specific to the payment network used by the request)

The updated request

Public Async refresh
refresh()

Refresh the request data and balance from the network (check if new events happened - e.g: accept, payments etc..) and return these data

Refreshed request data

import { IdentityTypes, RequestLogicTypes } from '@requestnetwork/types';
import Utils from '@requestnetwork/utils';
import * as Types from '../types';
import ContentDataExtension from './content-data-extension';
import { currencyToString } from './currency';
import PaymentNetworkDeclarative from './payment-network/declarative';
import localUtils from './utils';

/**
 * Class representing a request.
 * Instances of this class can be accepted, paid, refunded, etc.
 * Use the member function `getData` to access the properties of the Request.
 *
 * Requests should be created with `RequestNetwork.createRequest()`.
 */
export default class Request {
  /**
   * Unique ID of the request
   */
  public readonly requestId: RequestLogicTypes.RequestId;

  private requestLogic: RequestLogicTypes.IRequestLogic;
  private paymentNetwork: Types.IPaymentNetwork | null = null;
  private contentDataExtension: ContentDataExtension | null;

  /**
   * Data of the request (see request-logic)
   */
  private requestData: RequestLogicTypes.IRequest | null = null;

  /**
   * Content data parsed from the extensions data
   */
  private contentData: any | null = null;

  /**
   * Meta data of the request (e.g: where the data have been retrieved from)
   */
  private requestMeta: RequestLogicTypes.IReturnMeta | null = null;

  /**
   * Balance and payments/refund events
   */
  private balance: Types.IBalanceWithEvents | null = null;

  /**
   * Creates an instance of Request
   *
   * @param requestLogic Instance of the request-logic layer
   * @param requestId ID of the Request
   * @param paymentNetwork Instance of a payment network to manage the request
   * @param contentDataManager Instance of content data manager
   */
  constructor(
    requestLogic: RequestLogicTypes.IRequestLogic,
    requestId: RequestLogicTypes.RequestId,
    paymentNetwork?: Types.IPaymentNetwork | null,
    contentDataExtension?: ContentDataExtension | null,
  ) {
    this.requestLogic = requestLogic;
    this.requestId = requestId;
    this.contentDataExtension = contentDataExtension || null;
    this.paymentNetwork = paymentNetwork || null;
  }

  /**
   * Accepts a request
   *
   * @param signerIdentity Identity of the signer. The identity type must be supported by the signature provider.
   * @param refundInformation Refund information to add (any because it is specific to the payment network used by the request)
   * @returns The updated request
   */
  public async accept(
    signerIdentity: IdentityTypes.IIdentity,
    refundInformation?: any,
  ): Promise<Types.IRequestData> {
    const extensionsData: any[] = [];
    if (refundInformation) {
      if (!this.paymentNetwork) {
        throw new Error('Cannot add refund information without payment network');
      }
      extensionsData.push(
        this.paymentNetwork.createExtensionsDataForAddRefundInformation(refundInformation),
      );
    }
    const parameters: RequestLogicTypes.IAcceptParameters = {
      extensionsData,
      requestId: this.requestId,
    };

    await this.requestLogic.acceptRequest(parameters, signerIdentity, true);

    // refresh the local request data and return it
    return this.refresh();
  }

  /**
   * Cancels a request
   *
   * @param signerIdentity Identity of the signer. The identity type must be supported by the signature provider.
   * @param refundInformation refund information to add (any because it is specific to the payment network used by the request)
   * @returns The updated request
   */
  public async cancel(
    signerIdentity: IdentityTypes.IIdentity,
    refundInformation?: any,
  ): Promise<Types.IRequestData> {
    const extensionsData: any[] = [];
    if (refundInformation) {
      if (!this.paymentNetwork) {
        throw new Error('Cannot add refund information without payment network');
      }
      extensionsData.push(
        this.paymentNetwork.createExtensionsDataForAddRefundInformation(refundInformation),
      );
    }

    const parameters: RequestLogicTypes.ICancelParameters = {
      extensionsData,
      requestId: this.requestId,
    };

    await this.requestLogic.cancelRequest(parameters, signerIdentity, true);

    // refresh the local request data and return it
    return this.refresh();
  }

  /**
   * Increases the expected amount of the request.
   *
   * @param deltaAmount Amount by which to increase the expected amount
   * @param signerIdentity Identity of the signer. The identity type must be supported by the signature provider.
   * @param refundInformation Refund information to add (any because it is specific to the payment network used by the request)
   * @returns The updated request
   */
  public async increaseExpectedAmountRequest(
    deltaAmount: RequestLogicTypes.Amount,
    signerIdentity: IdentityTypes.IIdentity,
    refundInformation?: any,
  ): Promise<Types.IRequestData> {
    const extensionsData: any[] = [];
    if (refundInformation) {
      if (!this.paymentNetwork) {
        throw new Error('Cannot add refund information without payment network');
      }
      extensionsData.push(
        this.paymentNetwork.createExtensionsDataForAddRefundInformation(refundInformation),
      );
    }
    const parameters: RequestLogicTypes.IIncreaseExpectedAmountParameters = {
      deltaAmount,
      extensionsData,
      requestId: this.requestId,
    };
    await this.requestLogic.increaseExpectedAmountRequest(parameters, signerIdentity, true);

    // refresh the local request data and return it
    return this.refresh();
  }

  /**
   * Reduces the expected amount of the request. This can be called by the payee e.g. to apply discounts or special offers.
   *
   * @param deltaAmount Amount by which to reduce the expected amount
   * @param signerIdentity Identity of the signer. The identity type must be supported by the signature provider.
   * @param paymentInformation Payment information to add (any because it is specific to the payment network used by the request)
   * @returns The updated request
   */
  public async reduceExpectedAmountRequest(
    deltaAmount: RequestLogicTypes.Amount,
    signerIdentity: IdentityTypes.IIdentity,
    paymentInformation?: any,
  ): Promise<Types.IRequestData> {
    const extensionsData: any[] = [];
    if (paymentInformation) {
      if (!this.paymentNetwork) {
        throw new Error('Cannot add payment information without payment network');
      }
      extensionsData.push(
        this.paymentNetwork.createExtensionsDataForAddPaymentInformation(paymentInformation),
      );
    }

    const parameters: RequestLogicTypes.IReduceExpectedAmountParameters = {
      deltaAmount,
      extensionsData,
      requestId: this.requestId,
    };

    await this.requestLogic.reduceExpectedAmountRequest(parameters, signerIdentity, true);

    // refresh the local request data and return it
    return this.refresh();
  }

  /**
   * Adds payment information
   *
   * @param paymentInformation Payment information to add (any because it is specific to the payment network used by the request)
   * @param signerIdentity Identity of the signer. The identity type must be supported by the signature provider.
   * @returns The updated request
   */
  public async addPaymentInformation(
    paymentInformation: any,
    signerIdentity: IdentityTypes.IIdentity,
  ): Promise<Types.IRequestData> {
    const extensionsData: any[] = [];

    if (!this.paymentNetwork) {
      throw new Error('Cannot add payment information without payment network');
    }

    extensionsData.push(
      this.paymentNetwork.createExtensionsDataForAddPaymentInformation(paymentInformation),
    );

    const parameters: RequestLogicTypes.IAddExtensionsDataParameters = {
      extensionsData,
      requestId: this.requestId,
    };
    await this.requestLogic.addExtensionsDataRequest(parameters, signerIdentity, true);

    // refresh the local request data and return it
    return this.refresh();
  }

  /**
   * Adds refund information
   *
   * @param refundInformation Refund information to add (any because it is specific to the payment network used by the request)
   * @param signerIdentity Identity of the signer. The identity type must be supported by the signature provider.
   * @returns The updated request
   */
  public async addRefundInformation(
    refundInformation: any,
    signerIdentity: IdentityTypes.IIdentity,
  ): Promise<Types.IRequestData> {
    const extensionsData: any[] = [];

    if (!this.paymentNetwork) {
      throw new Error('Cannot add refund information without payment network');
    }

    extensionsData.push(
      this.paymentNetwork.createExtensionsDataForAddRefundInformation(refundInformation),
    );

    const parameters: RequestLogicTypes.IAddExtensionsDataParameters = {
      extensionsData,
      requestId: this.requestId,
    };
    await this.requestLogic.addExtensionsDataRequest(parameters, signerIdentity, true);

    // refresh the local request data and return it
    return this.refresh();
  }

  /**
   * Declare a payment is sent for the declarative payment network
   *
   * @param amount Amount sent
   * @param note Note from payer about the sent payment
   * @param signerIdentity Identity of the signer. The identity type must be supported by the signature provider.
   * @returns The updated request
   */
  public async declareSentPayment(
    amount: string,
    note: string,
    signerIdentity: IdentityTypes.IIdentity,
  ): Promise<Types.IRequestData> {
    const extensionsData: any[] = [];

    if (!this.paymentNetwork) {
      throw new Error('Cannot declare sent payment without payment network');
    }

    // We need to cast the object since IPaymentNetwork doesn't implement createExtensionsDataForDeclareSentPayment
    const declarativePaymentNetwork: PaymentNetworkDeclarative = this
      .paymentNetwork as PaymentNetworkDeclarative;

    if (!declarativePaymentNetwork.createExtensionsDataForDeclareSentPayment) {
      throw new Error('Cannot declare sent payment without declarative payment network');
    }

    extensionsData.push(
      declarativePaymentNetwork.createExtensionsDataForDeclareSentPayment({ amount, note }),
    );

    const parameters: RequestLogicTypes.IAddExtensionsDataParameters = {
      extensionsData,
      requestId: this.requestId,
    };
    await this.requestLogic.addExtensionsDataRequest(parameters, signerIdentity, true);

    // refresh the local request data and return it
    return this.refresh();
  }

  /**
   * Declare a refund is sent for the declarative payment network
   *
   * @param amount Amount sent
   * @param note Note from payee about the sent refund
   * @param signerIdentity Identity of the signer. The identity type must be supported by the signature provider.
   * @returns The updated request
   */
  public async declareSentRefund(
    amount: string,
    note: string,
    signerIdentity: IdentityTypes.IIdentity,
  ): Promise<Types.IRequestData> {
    const extensionsData: any[] = [];

    if (!this.paymentNetwork) {
      throw new Error('Cannot declare sent refund without payment network');
    }

    // We need to cast the object since IPaymentNetwork doesn't implement createExtensionsDataForDeclareSentRefund
    const declarativePaymentNetwork: PaymentNetworkDeclarative = this
      .paymentNetwork as PaymentNetworkDeclarative;

    if (!declarativePaymentNetwork.createExtensionsDataForDeclareSentRefund) {
      throw new Error('Cannot declare sent refund without declarative payment network');
    }

    extensionsData.push(
      declarativePaymentNetwork.createExtensionsDataForDeclareSentRefund({
        amount,
        note,
      }),
    );

    const parameters: RequestLogicTypes.IAddExtensionsDataParameters = {
      extensionsData,
      requestId: this.requestId,
    };
    await this.requestLogic.addExtensionsDataRequest(parameters, signerIdentity, true);

    // refresh the local request data and return it
    return this.refresh();
  }

  /**
   * Declare a payment is received for the declarative payment network
   *
   * @param amount Amount received
   * @param note Note from payee about the received payment
   * @param signerIdentity Identity of the signer. The identity type must be supported by the signature provider.
   * @returns The updated request
   */
  public async declareReceivedPayment(
    amount: string,
    note: string,
    signerIdentity: IdentityTypes.IIdentity,
  ): Promise<Types.IRequestData> {
    const extensionsData: any[] = [];

    if (!this.paymentNetwork) {
      throw new Error('Cannot declare received payment without payment network');
    }

    // We need to cast the object since IPaymentNetwork doesn't implement createExtensionsDataForDeclareReceivedPayment
    const declarativePaymentNetwork: PaymentNetworkDeclarative = this
      .paymentNetwork as PaymentNetworkDeclarative;

    if (!declarativePaymentNetwork.createExtensionsDataForDeclareReceivedPayment) {
      throw new Error('Cannot declare received payment without declarative payment network');
    }

    extensionsData.push(
      declarativePaymentNetwork.createExtensionsDataForDeclareReceivedPayment({
        amount,
        note,
      }),
    );

    const parameters: RequestLogicTypes.IAddExtensionsDataParameters = {
      extensionsData,
      requestId: this.requestId,
    };
    await this.requestLogic.addExtensionsDataRequest(parameters, signerIdentity, true);

    // refresh the local request data and return it
    return this.refresh();
  }

  /**
   * Declare a refund is received for the declarative payment network
   *
   * @param amount Amount received
   * @param note Note from payer about the received refund
   * @param signerIdentity Identity of the signer. The identity type must be supported by the signature provider.
   * @returns The updated request
   */
  public async declareReceivedRefund(
    amount: string,
    note: string,
    signerIdentity: IdentityTypes.IIdentity,
  ): Promise<Types.IRequestData> {
    const extensionsData: any[] = [];

    if (!this.paymentNetwork) {
      throw new Error('Cannot declare received refund without payment network');
    }

    // We need to cast the object since IPaymentNetwork doesn't implement createExtensionsDataForDeclareReceivedRefund
    const declarativePaymentNetwork: PaymentNetworkDeclarative = this
      .paymentNetwork as PaymentNetworkDeclarative;

    if (!declarativePaymentNetwork.createExtensionsDataForDeclareReceivedRefund) {
      throw new Error('Cannot declare received refund without declarative payment network');
    }

    extensionsData.push(
      declarativePaymentNetwork.createExtensionsDataForDeclareReceivedRefund({
        amount,
        note,
      }),
    );

    const parameters: RequestLogicTypes.IAddExtensionsDataParameters = {
      extensionsData,
      requestId: this.requestId,
    };
    await this.requestLogic.addExtensionsDataRequest(parameters, signerIdentity, true);

    // refresh the local request data and return it
    return this.refresh();
  }

  /**
   * Gets the request data
   *
   * @returns The updated request data
   */
  public getData(): Types.IRequestData {
    const requestData: RequestLogicTypes.IRequest = Utils.deepCopy(this.requestData);
    const result: Types.IRequestData = {
      ...requestData,
      balance: this.balance,
      contentData: this.contentData,
      currency: requestData.currency ? currencyToString(requestData.currency) : 'unknown',
      currencyInfo: requestData.currency,
      meta: this.requestMeta,
    };

    return result;
  }

  /**
   * Refresh the request data and balance from the network (check if new events happened - e.g: accept, payments etc..) and return these data
   *
   * @returns Refreshed request data
   */
  public async refresh(): Promise<Types.IRequestData> {
    const requestAndMeta: RequestLogicTypes.IReturnGetRequestFromId = await this.requestLogic.getRequestFromId(
      this.requestId,
    );

    if (!requestAndMeta.result.request) {
      throw new Error(
        `No request found for the id: ${this.requestId} - ${localUtils.formatGetRequestFromIdError(
          requestAndMeta,
        )}`,
      );
    }

    if (this.paymentNetwork) {
      this.balance = await this.paymentNetwork.getBalance(requestAndMeta.result.request);
    }

    if (this.contentDataExtension) {
      this.contentData = await this.contentDataExtension.getContent(requestAndMeta.result.request);
    }

    this.requestData = requestAndMeta.result.request;
    this.requestMeta = requestAndMeta.meta;

    return this.getData();
  }
}

result-matching ""

    No results matching ""