Implement combined API

.gitignore

@@ -26,3 +26,5 @@ node_modules
 
 # Users Environment Variables
 .lock-wscript
+
+example

src/person_company.js

+'use strict';
+
+var assert  = require('assert');
+var _       = require('lodash');
+var Promise = require('bluebird');
+var utils   = require('./utils');
+
+module.exports = function (client) {
+  function PersonCompany (data) {
+    _.extend(this, data);
+  }
+
+  PersonCompany.prototype.pending = utils.pending;
+
+  PersonCompany.find = Promise.method(function (options) {
+    assert(options && options.email, 'An email must be provided');
+    return this.client.request(_.extend({
+      api: 'person',
+      path: '/combined/email/' + options.email,
+      query: _.pick(options, 'subscribe', 'webhook_id')
+    }, options))
+    .bind(this)
+    .then(utils.cast)
+    .catch(utils.isUnknownRecord, function () {
+      throw new this.NotFoundError('PersonCompany not found');
+    });
+  });
+
+  PersonCompany.prototype.client = PersonCompany.client = client;
+  PersonCompany.NotFoundError = utils.NotFoundError;
+
+  return PersonCompany;
+};

test/person_company.js

+'use strict';
+
+var expect = require('chai').use(require('chai-as-promised')).expect;
+var nock   = require('nock');
+var PersonCompany = require('../')('k').PersonCompany;
+
+describe('PersonCompany', function () {
+
+  var mock;
+  before(function () {
+    mock = nock('https://person.clearbit.co');
+  });
+  after(nock.cleanAll);
+  afterEach(function () {
+    mock.done();
+  });
+
+  describe('#pending', function () {
+
+    it('identifies whether the person has an id', function () {
+      var person = new PersonCompany();
+      expect(person.pending()).to.be.true;
+      person.id = 'foo';
+      expect(person.pending()).to.be.false;
+    });
+
+  });
+
+  describe('PersonCompany#find', function () {
+
+    var alex = require('./fixtures/person');
+
+    it('can find a person by email', function () {
+      mock
+        .get('/v1/combined/email/alex@alexmaccaw.com')
+        .reply(200, alex);
+      return PersonCompany.find({email: 'alex@alexmaccaw.com'})
+        .then(function (person) {
+          expect(person)
+            .to.be.an.instanceOf(PersonCompany)
+            .and.have.property('id', alex.id);
+        });
+    });
+
+    it('can handle pending requests', function () {
+      mock
+        .get('/v1/combined/email/alex@alexmaccaw.com')
+        .reply(202);
+      return PersonCompany.find({email: 'alex@alexmaccaw.com'})
+        .then(function (person) {
+          expect(person.pending()).to.be.true;
+        });
+    });
+
+  });
+
+});