@sweepbright/api-client

SweepBright SDK

Node package to access the SweepBright API programmatically.

This is is a work in progress and only some endpoints are supported. Feel free to extend it as required

Getting started

To install this package run

yarn add @sweepbright/api-client

Usage:

const { createClient } = require('@sweepbright/api-client');

const client = await createClient({
  clientId: 'CLIENT_ID',
  clientSecret: 'CLIENT_SECRET',
}).authorize({ scopes: ['companies:read'] });

const estate = await client.estates.getOne({ estateId: 'abcd-1234-fbgh' });

Authorization

As shown in the example below, before you can call any endpoint, you need to authenticate using against the private API. This is done by call the authorize function of the client and option parameter.

Options object

• scopes - required - an list of the scopes to be granted. only resources with this scopes will be accessible afterwards

NOTE Some endpoints require to have a user token authorization. Currently this library does not provide a way to acquire such tokens. It assumes you already have one. To set a user token the method withUserToken on the client is available

NOTE In the SweepbrightOAuthManager method getAccessTokenBySessionData, we use a mutex to prevent concurrent access-token requests for the same session. We ran into issues with the Redis client under parallel execution: if multiple auth calls fire at once, they can race when setting the token and end up hitting the private API or Redis multiple times. To fix this, we introduced the async-mutex library and wrap our authorization logic in a runExclusive block so it only ever runs once per session.

Estates - getOne

Takes a single options parameter and returns a promise with the estate data

Options object

• estateId - required - the id of the estate to get
• includes - optional - a array of strings with extra subresources to include as part of the response

Estates - getAll

Takes a single options parameter and returns a paginated list of estates for a given company

Options object

• companyId - required - the id of the company the estates are in
• page - optional - when paginating the request, allows you specify the page you want to get
• limit - optional - when paginating the request, allows you specify the number of items per page (defaults to 10)
• archive - optional - when true, also archived properties will be returned, by default only non archived properties will be returned

Estates - getUnits

Allows to the units of a project.

Estates - createPublication

Allows to publish a property for a channel account, requires to be authorized with a user token. Takes a single options parameter and returns an empty response if the publication was scheduled successfully

Options object

• estateId - required - the id of the estate that is going to be published
• channelAccountId - required - the id of the channel account that is going to be used for publishing, needs to be in the same company the estate is
• config - required - a configuration object, specific for each channel account type, which information about the publication config [link](link missing)

Estates - updatePublication

Allows to update an existing property publication to a channel account, requires to be authorized with a user token. Takes a single options parameter and returns an empty response if the publication change was scheduled successfully

Options object

• estateId - required - the id of the estate who's publication is going to be updated
• channelAccountId - required - the id of the channel account of the publication
• config - required - a configuration object, specific for each channel account type, which information about the publication config [link](link missing)

Estates - unpublishPublication

Allows to remove an existing property publication, requires to be authorized with a user token. Takes a single options parameter and returns an empty response if the publication change was scheduled successfully

Options object

• estateId - required - the id of the estate who's publication is going to be updated
• channelAccountId - required - the id of the channel account of the publication

Contacts - getOne

Takes a single options parameter and returns a promise with the contact data

Options object

• contactId - required - the id of the contact to return

Contacts - getAll

Takes a single options parameter and returns a promise with a paginated list of contacts for a specific company

Options object

• companyId - required - the id of the company from which to get the contacts
• page - optional - when paginating the request, allows you specify the page you want to get
• limit - optional - when paginating the request, allows you specify the number of items per page (defaults to 10)

Leads - createLead

Creates a buyer lead which is assigned to the office of the property it was interested in and an interaction is recorded. Takes a single options parameter and returns a promise with the created lead data

Options object

• firstName - optional - the given name of the lead
• lastName - required - the family name of the lead
• email - required without phone - the email of the lead
• phone - required without email - the phone number of the lead
• message - required - a string with extra info
• location_preference.country - required with location_preference - the country code of the preferred location
• location_preference.postal_codes - required with location_preference - array of postal_codes

Leads - createUnassignedLead

Creates a unassigned lead in a given company. Takes a single options parameter and returns a promise with the created lead data

Options object

• companyId - required - the id of the company the lead belongs to

• attributes.first_name -required - the given name of the lead

• attributes.last_name - required - the family name of the lead

• attributes.phone - required - the phone number of the lead

• attributes.email - required - the phone number of the lead

• attributes.message - required - a string with extra info

• attributes.source_type - required - one of `["channel", (some other not documented and really difficult to get an answer from the backend)]

• attributes.external_source - required - a string with the name of the external source

• attributes.preferences.negotiation - required - the type of transaction the lead wants

• attributes.preferences.condition - required - the minimum condition required (one of ['poor', 'fair',' good', 'mint', 'new'])

• attributes.preferences.min_price - optional - number, the min. price of the property

• attributes.preferences.max_price - optional - number, the max. price of the property

• attributes.preferences.min_rooms - optional - number - the minimum number of rooms

• attributes.preferences.locale - optional - the locale of the user

• attributes.location_preference.country - required - the country code of the preferred location

• attributes.location_preference.postal_codes - required - array of postal_codes

Companies - get

Returns a company. Takes a single options parameter and returns a promise with the company data

Options object

• companyId - required - the id of the company to return
• includes - optional - a list of includes to return

Development

This repository was initialized using TSDX. Check their docs for information about the different commands available.

Publication

Publication is configured in Github Actions. The flow is the following: "Version Tag -> Github Release".

In master branch:

• run yarn version and select a new version
• yarn will create a commit and a version tag
• push the changes together with tag
• go to Releases / Tags
• find your new tag and click "Create Release From Tag" button
• save the release
• go to Actions and make sure the NPM package is being published