Update the company.update method (#375)

* Update the company.update method

Makes it clearer that this endpoint uses the Intercom ID for a company,
and not the companyID that is optionally provided during creation

closes #356

* Add a createOrUpdate company method

This method actually creates or updates, so add a more appropriately named method and mark the old one as deprecated/

Author: colmdoyle

lib/company.ts

@@ -21,6 +21,9 @@ export default class Company {
         this.client = client;
         this.scroll = new Scroll<Company>(this.client, this.baseUrl);
     }
+    /**
+     * @deprecated Use `client.companies.createOrUpdate()` instead.
+     */
     create({
         createdAt,
         companyId,
@@ -31,6 +34,34 @@ export default class Company {
         website,
         industry,
         customAttributes,
+    }: CreateCompanyData) {
+        return this.createOrUpdate({
+            createdAt,
+            companyId,
+            name,
+            monthlySpend,
+            plan,
+            size,
+            website,
+            industry,
+            customAttributes,
+        });
+    }
+    /**
+     * Create or update a company by its `companyId`.
+     *
+     * Companies are looked up via the `companyId` field. If a company with the given `companyId` does not exist, it will be created. If a company with the given `companyId` does exist, it will be updated.
+     **/
+    createOrUpdate({
+        createdAt,
+        companyId,
+        name,
+        monthlySpend,
+        plan,
+        size,
+        website,
+        industry,
+        customAttributes,
     }: CreateCompanyData) {
         const data = {
             remote_created_at: createdAt,
@@ -49,9 +80,23 @@ export default class Company {
             data,
         });
     }
+
+    /**
+     * Update a single company by its `id`.
+     * @param id - The `id` field is required for updating a company. This is distinct from the `companyId` field on the Company object , which is an identifier for the company in your database.
+     * @param createdAt - The time the company was created by you.
+     * @param name - The name of the company.
+     * @param monthlySpend - The amount the company spends on your product each month. How much revenue the company generates for your business.
+     * Note that this will truncate floats. i.e. it only allow for whole integers, 155.98 will be truncated to 155. Note that this has an upper limit of 2**31-1 or 2147483647..
+     * @param plan - The name of the plan you have associated with the company.
+     * @param size - The number of employees the company has.
+     * @param website -The URL for this company's website. Please note that the value specified here is not validated. Accepts any string.
+     * @param industry - The industry the company operates in.
+     * @param customAttributes - A hash of key/value pairs containing any other data about the company you want Intercom to store.
+     */
     update({
+        id,
         createdAt,
-        companyId,
         name,
         monthlySpend,
         plan,
@@ -72,7 +117,7 @@ export default class Company {
         };
 
         return this.client.put<CompanyObject>({
-            url: `/${this.baseUrl}/${companyId}`,
+            url: `/${this.baseUrl}/${id}`,
             data,
         });
     }
@@ -160,7 +205,9 @@ interface CreateCompanyData {
     customAttributes?: JavascriptObject;
 }
 //
-type UpdateCompanyData = CreateCompanyData;
+interface UpdateCompanyData extends Omit<CreateCompanyData, 'companyId'> {
+    id: string;
+}
 //
 interface FindCompanyData {
     companyId?: string;

test/integration/companies.test.ts

@@ -34,10 +34,27 @@ describe('Companies', () => {
 
         assert.notEqual(response, undefined);
     });
+    it('createOrUpdate', async () => {
+        const response = await client.companies.createOrUpdate({
+            createdAt: dateToUnixTimestamp(new Date()),
+            companyId: '46029',
+            name: 'BestCompanyInc.',
+            monthlySpend: 9001,
+            plan: '1. Get pizzaid',
+            size: 62049,
+            website: 'http://the-best.one',
+            industry: 'The Best One',
+            customAttributes: {},
+        });
+
+        createdCompany = response;
+
+        assert.notEqual(response, undefined);
+    });
     it('update', async () => {
         const response = await client.companies.update({
             createdAt: dateToUnixTimestamp(new Date()),
-            companyId: createdCompany.id,
+            id: createdCompany.id,
             name: 'BestCompanyInc',
             monthlySpend: 9001,
             plan: '1. Get pizzaid',

test/unit/company.test.ts

@@ -64,7 +64,7 @@ describe('companies', () => {
         assert.deepStrictEqual({}, response);
     });
     it('should be updated', async () => {
-        const company_id = '46029';
+        const id = '625e90fc55ab113b6d92175f';
         const requestBody = {
             remote_created_at: dateToUnixTimestamp(new Date()),
             name: 'BestCompanyInc.',
@@ -77,12 +77,12 @@ describe('companies', () => {
         };
 
         nock('https://api.intercom.io')
-            .put(`/companies/${company_id}`, requestBody)
+            .put(`/companies/${id}`, requestBody)
             .reply(200, {});
 
         const response = await client.companies.update({
             createdAt: requestBody.remote_created_at,
-            companyId: company_id,
+            id: id,
             name: requestBody.name,
             monthlySpend: requestBody.monthly_spend,
             plan: requestBody.plan,