Add Visitor

Author: Volo

README.md

@@ -1067,6 +1067,54 @@ const response = await client.teams.find({
 const response = await client.teams.list();
 ```
 
+### Visitors
+
+#### [Retrieve a Visitor](https://developers.intercom.com/intercom-api-reference/reference/view-a-visitor)
+
+```typescript
+const response = await client.visitors.find({ id: '123' });
+```
+
+OR
+
+```typescript
+const response = await client.visitors.find({ userId: '123' });
+```
+
+#### [Update a Visitor](https://developers.intercom.com/intercom-api-reference/reference/update-a-visitor)
+
+```typescript
+const response = await client.visitors.update({
+    userId: '123',
+    name: 'anonymous bruh',
+    customAttributes: {
+        paid_subscriber: true,
+    },
+});
+```
+
+#### [Delete a Visitor](https://developers.intercom.com/intercom-api-reference/reference/delete-a-visitor)
+
+```typescript
+const response = await client.visitors.delete({
+    id,
+});
+```
+
+#### [Convert a Visitor](https://developers.intercom.com/intercom-api-reference/reference/convert-a-visitor-to-a-user)
+
+```typescript
+const response = await client.visitors.mergeToContact({
+    visitor: {
+        id: '123',
+    },
+    user: {
+        userId: '123',
+    },
+    type: Role.USER,
+});
+```
+
 ### Identity verification
 
 `intercom-node` provides a helper for using [identity verification](https://docs.intercom.com/configure-intercom-for-your-product-or-site/staying-secure/enable-identity-verification-on-your-web-product):

lib/client.ts

@@ -14,6 +14,7 @@ import Segment from './segment';
 import Message from './message';
 import Team from './team';
 import Tag from './tag';
+import Visitor from './visitor';
 
 import * as packageJson from '../package.json';
 
@@ -66,6 +67,7 @@ export default class Client {
     teams: Team;
     usebaseURL: (baseURL: string) => this;
     usernamePart?: string;
+    visitors: Visitor;
 
     constructor(args: Constructor) {
         const [usernamePart, passwordPart] = Client.getAuthDetails(args);
@@ -91,6 +93,7 @@ export default class Client {
         this.segments = new Segment(this);
         this.tags = new Tag(this);
         this.teams = new Team(this);
+        this.visitors = new Visitor(this);
         this.requestOpts = {
             baseURL: 'https://api.intercom.io',
         };

lib/index.ts

@@ -38,6 +38,7 @@ export * from './segment/segment.types';
 export * from './subscription/subscription.types';
 export * from './tag/tag.types';
 export * from './team/team.types';
+export * from './visitor/visitor.types';
 
 // Export enums needed for requests
 export { SearchContactOrderBy } from './contact';
@@ -55,3 +56,9 @@ export {
     RedactConversationPartType,
 } from './conversation';
 export { RecepientType } from './message';
+export {
+    ContactObjectForMerge,
+    MergeVisitorToContactData,
+    VisitorObjectForMerge,
+    IdentificationForVisitor,
+} from './visitor';

lib/visitor.ts

@@ -0,0 +1,87 @@
+import { Client, ContactObject } from '.';
+import { Role } from './common/common.types';
+import { VisitorObject } from './visitor/visitor.types';
+
+export default class Visitor {
+    public readonly baseUrl = 'visitors';
+
+    constructor(private readonly client: Client) {
+        this.client = client;
+    }
+
+    find({ id, userId }: FindVisitorByIdData) {
+        const query = userId ? { user_id: userId } : {};
+        const url = `/${this.baseUrl}${id ? `/${id}` : ''}`;
+
+        return this.client.get<VisitorObject>({
+            url,
+            params: query,
+        });
+    }
+    update({ id, userId, name, customAttributes }: UpdateVisitorData) {
+        const data = {
+            id,
+            user_id: userId,
+            name,
+            custom_attributes: customAttributes,
+        };
+
+        return this.client.put<VisitorObject>({
+            url: `/${this.baseUrl}`,
+            data,
+        });
+    }
+    delete({ id }: DeleteVisitorByIdData) {
+        return this.client.delete<VisitorObject>({
+            url: `/${this.baseUrl}/${id}`,
+        });
+    }
+    mergeToContact({ visitor, user, type }: MergeVisitorToContactData) {
+        const data = {
+            visitor: {
+                id: visitor.id,
+                user_id: visitor.userId,
+                email: visitor.email,
+            },
+            user: {
+                id: user.id,
+                user_id: user.userId,
+                email: user.email,
+            },
+            type,
+        };
+
+        return this.client.post<ContactObject>({
+            url: `/${this.baseUrl}/convert`,
+            data,
+        });
+    }
+}
+
+export type IdentificationForVisitor =
+    | { id: string; userId?: never }
+    | { id?: never; userId: string };
+
+type FindVisitorByIdData = IdentificationForVisitor;
+
+type UpdateVisitorData = IdentificationForVisitor & {
+    name?: string;
+    customAttributes?: VisitorObject['custom_attributes'];
+};
+
+type DeleteVisitorByIdData = { id: string };
+
+export type MergeVisitorToContactData = {
+    visitor: VisitorObjectForMerge;
+    user: ContactObjectForMerge;
+    type: Role;
+};
+
+export type VisitorObjectForMerge =
+    | { id: string; userId?: never; email?: never }
+    | { id?: never; userId: string; email?: never }
+    | { id?: never; userId?: never; email: string };
+
+export type ContactObjectForMerge = IdentificationForVisitor & {
+    email?: string;
+};

lib/visitor/visitor.types.ts

@@ -0,0 +1,18 @@
+import { JavascriptObject, SegmentObject, TagObject, Timestamp } from '..';
+
+export type VisitorObject = {
+    type: 'visitor';
+    id: string;
+    created_at: Timestamp;
+    updated_at: Timestamp;
+    user_id: string;
+    name: string;
+    custom_attributes: JavascriptObject;
+    last_request_at: Timestamp;
+    avatar: string | { url: string };
+    unsubscribed_from_emails: boolean;
+    location_data: JavascriptObject;
+    social_profiles: JavascriptObject[];
+    segments: SegmentObject[];
+    tags: TagObject[];
+};

test/visitor.ts

@@ -0,0 +1,85 @@
+import assert from 'assert';
+import { Client, Role } from '../lib';
+import nock from 'nock';
+
+describe('visitors', () => {
+    const client = new Client({
+        usernameAuth: { username: 'foo', password: 'bar' },
+    });
+    it('retrieves a visitor by id', async () => {
+        const id = 'baz';
+
+        nock('https://api.intercom.io').get(`/visitors/${id}`).reply(200, {});
+
+        const response = await client.visitors.find({ id });
+
+        assert.deepStrictEqual({}, response);
+    });
+    it('retrieves a visitor by user id', async () => {
+        const userId = 'baz';
+
+        nock('https://api.intercom.io')
+            .get('/visitors')
+            .query({ user_id: userId })
+            .reply(200, {});
+
+        const response = await client.visitors.find({ userId });
+
+        assert.deepStrictEqual({}, response);
+    });
+    it('updates a visitor by id', async () => {
+        const requestData = {
+            user_id: '124',
+            name: 'Winston Smith',
+            custom_attributes: {
+                paid_subscriber: true,
+                monthly_spend: 155.5,
+                team_mates: 9,
+            },
+        };
+        nock('https://api.intercom.io').put('/visitors').reply(200, {});
+        const response = await client.visitors.update({
+            userId: requestData.user_id,
+            name: requestData.name,
+            customAttributes: requestData.custom_attributes,
+        });
+
+        assert.deepStrictEqual({}, response);
+    });
+    it('deletes a visitor', async () => {
+        const id = 'baz';
+
+        nock('https://api.intercom.io')
+            .delete(`/visitors/${id}`)
+            .reply(200, {});
+
+        const response = await client.visitors.delete({
+            id,
+        });
+
+        assert.deepStrictEqual({}, response);
+    });
+    it('converts a visitor into contact', async () => {
+        const requestData = {
+            visitor: { id: 'baz' },
+            user: { user_id: 'bez' },
+            type: Role.USER,
+        };
+
+        nock('https://api.intercom.io')
+            .post('/visitors/convert', requestData)
+            .reply(200, {});
+
+        const response = await client.visitors.mergeToContact({
+            visitor: {
+                id: requestData.visitor.id,
+            },
+            user: {
+                userId: requestData.user.user_id,
+            },
+            type: requestData.type,
+        });
+
+        assert.deepStrictEqual({}, response);
+    });
+});