feat(cash): /references finds payment uuid by ref

This commit adds an API route to find a payment UUID by the human
readable reference.  Use it like this:
 1. `GET /cash/references/:reference` - returns the uuid of a cash
 payment matching the reference if it exists.  Otherwise, returns a 404
 NOT FOUND error.

There are accompanying integration tests to demonstrate functionality.

server/config/routes.js

@@ -471,6 +471,7 @@ exports.configure = function (app) {
   app.post('/cash', cash.create);
   app.put('/cash/:uuid', cash.update);
   app.delete('/cash/:uuid', cash.debitNote);
+  app.get('/cash/references/:reference', cash.reference);
 
   /** @todo - classify these */
   app.get('/cashflow/report/', cashflow.getReport);

server/controllers/finance/cash.js

@@ -15,6 +15,24 @@
 var db   = require('../../lib/db');
 var uuid = require('../../lib/guid');
 
+/** retrieves the details of a cash payment */
+exports.detail = detail;
+
+/** retrieves a list of all cash payments */
+exports.list = list;
+
+/** creates cash payments */
+exports.create = create;
+
+/** modifies previous cash payments */
+exports.update = update;
+
+/** searchs for cash payment uuids by their human-readable reference */
+exports.reference = reference;
+
+/** @todo - reverse a cash payment via a journal voucher */
+exports.debitNote = debitNote;
+
 // looks up a single cash record and associated cash_items
 // sets the "canceled" flag if a cash_discard record exists.
 function lookupCashRecord(uuid, codes) {
@@ -76,7 +94,7 @@ function lookupCashRecord(uuid, codes) {
  * Lists the cash payments with optional filtering parameters.
  * @returns payments An array of { uuid, reference, date } JSON objects
  */
-exports.list = function list(req, res, next) {
+function list(req, res, next) {
   'use strict';
 
   // base query
@@ -91,7 +109,7 @@ exports.list = function list(req, res, next) {
   })
   .catch(next)
   .done();
-};
+}
 
 /**
  * GET /cash/:uuid
@@ -106,7 +124,7 @@ exports.list = function list(req, res, next) {
  *   ...
  *  }
  */
-exports.detail = function detail(req, res, next) {
+function detail(req, res, next) {
   'use strict';
 
   var uuid = req.params.uuid;
@@ -117,7 +135,7 @@ exports.detail = function detail(req, res, next) {
   })
   .catch(next)
   .done();
-};
+}
 
 
 /**
@@ -126,7 +144,7 @@ exports.detail = function detail(req, res, next) {
  * API also supports future offline functionality by either accepting a UUID or
  * generating it if it is not present.
  */
-exports.create = function create(req, res, next) {
+function create(req, res, next) {
   'use strict';
 
   var data = req.body.payment;
@@ -191,15 +209,15 @@ exports.create = function create(req, res, next) {
   })
   .catch(next)
   .done();
-};
+}
 
 
 /**
  * PUT /cash/:uuid
  * Updates the non-financial details associated with a cash payment.
  * NOTE - this will not update the cash_item or cash_discard tables.
  */
-exports.update = function update(req, res, next) {
+function update(req, res, next) {
   'use strict';
 
   var uuid = req.params.uuid;
@@ -249,15 +267,41 @@ exports.update = function update(req, res, next) {
   })
   .catch(next)
   .done();
-};
+}
 
 /**
  * DELETE /cash/:uuid
  * Reverses a cash payment using the cash discard table
  * @TODO - should this be implemented as a separate API?
  */
-exports.debitNote = function debitNote(req, res, next) {
+function debitNote(req, res, next) {
   'use strict';
   // TODO
   next();
-};
+}
+
+
+/**
+ * retrieves cash payment uuids from a reference string (e.g. HBB123)
+ * GET /cash/references/:reference
+ */
+function reference(req, res, next) {
+
+  var sql =
+    'SELECT c.uuid FROM (' +
+      'SELECT cash.uuid, CONCAT(project.abbr, cash.reference) AS reference ' +
+      'FROM cash JOIN project ON cash.project_id = project.id' +
+    ')c WHERE c.reference = ?;';
+
+  db.exec(sql, [ req.params.reference ])
+  .then(function (rows) {
+    if (rows.length === 0) {
+      throw new req.codes.ERR_NOT_FOUND();
+    }
+
+    // references should be unique - return the first one
+    res.status(200).json(rows[0]);
+  })
+  .catch(next)
+  .done();
+}

server/test/api/cash.js

@@ -1,3 +1,4 @@
+/* jshint expr:true*/
 var chai = require('chai');
 var expect = chai.expect;
 
@@ -23,6 +24,7 @@ describe('(/cash) Cash Payments Interface ::', function () {
     { sale_uuid : '957e4e79-a6bb-4b4d-a8f7-c42152b2c2f6', amount : 75.0 },
     { sale_uuid : 'c44619e0-3a88-4754-a750-a414fc9567bf', amount : 25.0 }
   ];
+  var REFERENCE = 'TPA1';
 
   /** login before each request */
   beforeEach(helpers.login(agent));
@@ -252,6 +254,29 @@ describe('(/cash) Cash Payments Interface ::', function () {
     });
   });
 
+  // the references API
+  describe('(/cash/references) references for finding cash payment uuids', function () {
+
+    it('GET /cash/references/unknown should return a 404 error', function () {
+      agent.get('/cash/references/unknown')
+        .then(function (res) {
+          helpers.api.errored(res, 404);
+        })
+        .catch(helpers.handler);
+    });
+
+    it('get /cash/references/:reference should return a uuid for a valid payment', function () {
+      agent.get('/cash/references/'.concat(REFERENCE))
+        .then(function (res) {
+          expect(res).to.have.status(200);
+          expect(res).to.be.json;
+          expect(res.body).to.have.property('uuid');
+        })
+        .catch(helpers.handler);
+    });
+  });
+
+
   // The HTTP DELETE verb triggers a cash_discard record, but does not destroy any data
   // (proposed rename: debit_note)
   describe.skip('The Debit Note Interface ::', function () {
@@ -260,4 +285,5 @@ describe('(/cash) Cash Payments Interface ::', function () {
     it('DELETE-d cash records should still be discoverable by GET /cash');
     it('DELETE-d cash records should have the \'canceled\' property set');
   });
+
 });