@fye/xservices-client/lib/transaction.js

FYE Micros Xservices Client

/*!
 * twec-xservices-client
 * Copyright(c) 2014-2020 F.Y.E
 * Created by Nicholas Penree
 */

/**
 * Module dependencies.
 */

var XService = require('./xservice');
var inherits = require('util').inherits;

/**
 * Creates an instance of an `TransactionService`.
 *
 * @constructor
 * @augments XService
 * @this {TransactionService}
 * @param {Object} opts
 * @api public
 */

function TransactionService(opts, conns) {
  XService.call(this, opts, conns);
  this.serviceName = 'TransServices';
}

/**
 * Inherit from  `XService`.
 */

inherits(TransactionService, XService);

/**
 * Transforms a raw transaction, converting any required data types.
 *
 * @param {Object} trans
 * @return {Object}
 * @api private
 */

TransactionService.prototype._formatTransaction = function(trans) {
  trans = this._convertFields({
    obj: trans,
    dates: [ 'businessDate' ],
    bools: [ 'changed' , 'giftReceiptFlag' ],
    numbers: [
      'amountDue',
      'totalItemSold',
      'totalTaxAmt',
      'totalTenderAmt',
      'transSeq',
      'transSubTotal',
      'transTotal'
    ]
  });

  // single transactions are going to be an object not an array
  if (trans.saleLines && !Array.isArray(trans.saleLines)) {
    trans.saleLines = [ trans.saleLines ];
  }

  // single tenders are going to be an object not an array
  if (trans.tenderLines && !Array.isArray(trans.tenderLines)) {
    trans.tenderLines = [ trans.tenderLines ];
  }

  // Convert line items if there are any
  if (trans.saleLines) {
    trans.saleLines = trans.saleLines.map(function(line) {
      if (line.item) {
        line.item = this._convertFields({
          obj: line.item,
          bools: [
            'disallowSendSale',
            'giftCard',
            'promptForDescription',
            'promptForPrice',
            'promptForQty',
            'promptForWeight',
            'serializeItem'
          ],
          numbers: [
            'minAgeRequired',
            'qtyScale',
            'quantityOnHand'
          ]
        });
      }

      // 2015-03-11 NJP: handle line properties
      if (!line.properties) line.properties = [];
      if (!Array.isArray(line.properties)) {
        line.properties = [ line.properties ];
      }

      line.properties = line.properties.map(function(prop) {
        return this._convertFields({
          obj: prop,
          bools: [
            'changed',
            'voidFlag'
          ],
          numbers: [
            'totalPropertyAmt',
            'lineNumber',
            'unitAmt'
          ]
        });
      }, this);

      return this._convertFields({
        obj: line,
        bools: [
          'changed',
          'voidFlag',
          'giftReceiptFlag'
        ],
        numbers: [
          'qty',
          'lineNumber',
          'totalLineDiscountAmount',
          'totalLinePrice',
          'unitPrice'
        ]
      });
    }, this);
  }

  if (trans.tenderLines) {
    trans.tenderLines = trans.tenderLines.map(function(line) {
      return this._convertFields({
        obj: line,
        bools: [
          'changed',
          'voidFlag'
        ],
        numbers: [
          'lineNumber',
          'amount'
        ]
      });
    }, this);
  }

  return trans;
};

/**
 * Perform a web service action and return a transaction object.
 *
 * @param {Object} opts
 * @return {TransactionService}
 * @api private
 */

var transMethod = function() {
  return function(opts, fn) {
    this.invoke(this._locals(opts), function(err, res) {
      if (err) return fn(err);

      var trans;

      try {
        trans = (res || {}).PosTrans;

        if (trans) {
          if (trans.failureMessage) {
            err = new Error(trans.failureMessage);
            return fn(err, null);
          }

          trans = this._formatTransaction(trans);
        }
      } catch (e) {
        err = e;
        trans = null;
      }

      fn(err, trans);
    }.bind(this));
    return this;
  }
};

/**
 * Perform a web service action and return a boolean indicating success.
 *
 * @param {Object} opts
 * @return {TransactionService}
 * @api private
 */

var actionMethod = function() {
  return function(opts, fn) {
    this.invoke(opts, function(err, res) {
      if (err) return fn(err);

      res = (res || {}).StatusServiceResponse || {};
      fn(null, (res.status === 'SUCCESS'));
    }.bind(this));
    return this;
  }
};

/**
 * Creates a new retail transaction in the system.
 *
 * Options:
 *  `serviceContext` - required
 *
 * @param {Object} opts
 * @param {Function} fn
 * @return {TransactionService}
 * @api public
 */

TransactionService.prototype.createNewRetailTransaction = transMethod();

/**
 * Adds a customer to a transaction.
 *
 * Options:
 *  - `transSeq` - required
 *  - `serviceContext` - required
 *  - `partyId` - required
 *
 * @param {Object} opts
 * @param {Function} fn
 * @return {TransactionService}
 * @api public
 */

TransactionService.prototype.addCustomerToRetailTrans = transMethod();

/**
 * Adds a customer card to a transaction.
 *
 * Options:
 *  - `transSeq` - required
 *  - `serviceContext` - required
 *  - `cards` or `customerCardInputs` - required
 *
 * @param {Object} opts
 * @param {Function} fn
 * @return {TransactionService}
 * @api public
 */

TransactionService.prototype.selectLoyaltyCard = transMethod();

/**
 * Cancels a previously performed retail transaction.
 *
 * Options:
 *  - `transSeq` - required
 *  - `serviceContext` - required
 *  - `reasonCode` - optional
 *  - `comment` - optional
 *  - `reasonCodePromptProperties` - optional
 *  - `receiptPrinter` - optional
 *
 * @param {Object} opts
 * @param {Function} fn
 * @return {TransactionService}
 * @api public
 */

TransactionService.prototype.cancelRetailTransaction = actionMethod();

/**
 * Suspends a retail transaction.
 *
 * Options:
 *  - `transSeq` - required
 *  - `serviceContext` - required
 *  - `giftRcptLines` - optional
 *  - `transProperty` - optional
 *  - `receiptPrinter` - optional
 *
 * @param {Object} opts
 * @param {Function} fn
 * @return {TransactionService}
 * @api public
 */

TransactionService.prototype.suspendRetailTransaction = actionMethod();

/**
 * Adds a sale line item to a transaction.
 *
 * Options:
 *  - `transSeq` - required
 *  - `serviceContext` - required
 *  - `itemId` - required
 *  - `qty` - required
 *  - `price` - optional
 *  - `itemIdInputType` - optional
 *  - `weight` - optional
 *  - `itemDescription` - optional
 *  - `serialNumber` - optional
 *
 * @param {Object} opts
 * @param {Function} fn
 * @return {TransactionService}
 * @api public
 */

TransactionService.prototype.addSaleLineItem = transMethod();

/**
 * Changes the tax on a sale line item.
 *
 * Options:
 *  - `transSeq` - required
 *  - `serviceContext` - required
 *  - `lineNumber` - required
 *  - `taxAmount` - optional
 *  - `taxPercent` - optional
 *  - `reasonCode` - optional
 *  - `comment` - optional
 *  - `reasonCodePromptProperties` - optional
 *
 * @param {Object} opts
 * @param {Function} fn
 * @return {TransactionService}
 * @api public
 */

TransactionService.prototype.changeLineItemTax = transMethod();

/**
 * Changes the price on a sale line item.
 *
 * Options:
 *  - `transSeq` - required
 *  - `serviceContext` - required
 *  - `lineNumber` - required
 *  - `newPrice` - optional
 *  - `reasonCode` - optional
 *  - `comment` - optional
 *  - `reasonCodePromptProperties` - optional
 *
 * @param {Object} opts
 * @param {Function} fn
 * @return {TransactionService}
 * @api public
 */

TransactionService.prototype.changeLineItemPrice = transMethod();

/**
 * Applies a discount on a sale line item.
 *
 * Options:
 *  - `transSeq` - required
 *  - `serviceContext` - required
 *  - `lineNumber` - required
 *  - `discountCode` - optional
 *  - `discountAmount` - optional
 *  - `discountPercent` - optional
 *  - `newQty` - optional
 *  - `newPrice` - optional
 *  - `discountSerialNumber` - optional
 *  - `reasonCode` - optional
 *  - `comment` - optional
 *  - `reasonCodePromptProperties` - optional
 *
 * @param {Object} opts
 * @param {Function} fn
 * @return {TransactionService}
 * @api public
 */

TransactionService.prototype.discountLineItem = transMethod();

/**
 * Applies a discount on a group of sale line items.
 *
 * Options:
 *  - `transSeq` - required
 *  - `serviceContext` - required
 *  - `lineNumbers` - required
 *  - `discountCode` - optional
 *  - `discountAmount` - optional
 *  - `discountPercent` - optional
 *  - `discountSerialNumber` - optional
 *  - `reasonCode` - optional
 *  - `comment` - optional
 *  - `reasonCodePromptProperties` - optional
 *
 * @param {Object} opts
 * @param {Function} fn
 * @return {TransactionService}
 * @api public
 */

TransactionService.prototype.discountGroupLineItems = transMethod();

/**
 * Adds a coupon line item to a transaction.
 *
 * Options:
 *  - `transSeq` - required
 *  - `serviceContext` - required
 *  - `couponId` - required
 *  - `couponType` - optional
 *  - `couponEntryType` - optional
 *
 * @param {Object} opts
 * @param {Function} fn
 * @return {TransactionService}
 * @api public
 */

TransactionService.prototype.addCouponLineItem = transMethod();

/**
 * Changes the tax applied to a transaction
 *
 * Options:
 *  - `transSeq` - required
 *  - `serviceContext` - required
 *  - `lineNumber` - required
 *  - `taxAmount` - optional
 *  - `taxPercent` - optional
 *  - `reasonCode` - optional
 *  - `comment` - optional
 *  - `reasonCodePromptProperties` - optional
 *
 * @param {Object} opts
 * @param {Function} fn
 * @return {TransactionService}
 * @api public
 */

TransactionService.prototype.changeTransactionTax = transMethod();


/**
 * Sets the properties for a transaction
 *
 * Options:
 *  - `transSeq` - required
 *  - `serviceContext` - required
 *  - `transPromptProperties` - required
 *
 * @param {Object} opts
 * @param {Function} fn
 * @return {TransactionService}
 * @api public
 */

TransactionService.prototype.setTransProperties = transMethod();

/**
 * Retrieves a transaction by a receipt barcode
 *
 * Options:
 *  - `barCode` - required
 *  - `serviceContext` - required
 *
 * @param {Object} opts
 * @param {Function} fn
 * @return {TransactionService}
 * @api public
 */

TransactionService.prototype.lookupTransByBarcode = transMethod();

/**
 * Retrieves a tranaction by store, date, register, and transaction.
 *
 * Options:
 *  - `transSeq` - required
 *  - `businessDate` - required
 *  - `store` or `retailLocationId` - required
 *  - `register` or `workstationId` - required
 *  - `serviceContext` - required
 *
 * @param {Object} opts
 * @param {Function} fn
 * @return {TransactionService}
 * @api public
 */

TransactionService.prototype.lookupTrans = transMethod();

/**
 * Expose `TransactionService`.
 */

module.exports = TransactionService;