Vendasta Node SDK

Installation

npm install --save vendasta-sdk

Usage

Note: The authentication mechanism is likely to change. Currently, it's done via a static oauth token (ask us for one). The SDK has 3 environments available. Test is intended for Vendasta development. Demo is intended for partners to test their integration against, and Production is the end customer facing environment.

Creating a Client

You'll use the client to interact with either our demo or production servers. Create the client with the appropriate environment:

• Environment.DEMO
• Environment.PRODUCTION

Creating the client is easy:

Typescript

import {Client, Environment} from "vendasta-sdk/src/index"
client: Client = new Client(Environment.DEMO, "my-access-token");

Javascript

var vendastaSdk = require("vendasta-sdk");
var client = new vendastaSdk.Client(vendastaSdk.Environment.DEMO, "my-access-token");

Saving a Listing

client.putListing(listing, callback);

This will either save a new listing, or update the existing one with the given listing_id, or external_id.

NOTE: When a listing is created the server will generate a listing_id for the listing. Do not set this value. The external_id is the ID from your system.

Arguments

• listing: Listing
• callback: any => Runs when the call completes. Signature is callback(error: string, listing: Listing)

Typescript

import {Listing} from "vendasta-sdk/src/index";
listing: Listing = new Listing();
listing.address = "123 Test Dr.";
listing.external_id = "externalId";
listing.url = "http://www.vendasta.com";
client.putListing(listing, callback);

Javascript

var listing = new vendastaSdk.Listing();
listing.address = "123 Test Dr.";
listing.external_id = "externalId";
listing.url = "http://www.vendasta.com";
client.putListing(listing, callback);

Retrieving a Listing

Retrieve a listing with:

client.getListing(listingId, null, callback);
client.getListing(null, externalId, callback);

Arguments

• listingId: string => This is available from the Listing object after it has been saved.
• externalId: string => This is the external id specified in create or update of a listing. This allows you to use the id's already in use in your system.
  • You MUST supply either the listingId or externalId, not both.
• callback: any => Runs when the call completes. Signature is callback(error: string, listing: Listing)

Typescript

// assume an existing listing at this point ...
import {Listing} from "vendasta-sdk/src/index";
let listing: Listing = client.getListing("listing-id", null, callback);

Javascript

// assume an existing listing at this point ...
var listing = client.getListing("listing-id", null, callback);

Deleting a Listing

Delete a listing with:

client.deleteListing(listingId, null, callback);
client.deleteListing(null, externalId, callback);

Arguments

• listingId: string => This is available from the Listing object after it has been saved.
• externalId: string => This is the external id specified in create or update of a listing. This allows you to use the id's already in use in your system.
  • You MUST supply either the listingId or externalId, not both.
• callback: any => Runs when the call completes. Signature is callback(error: string, empty: Empty)

Typescript

// assume an existing listing at this point ...
client.deleteListing("listing-id", null, callback);

Javascript

// assume an existing listing at this point ...
client.deleteListing("listing-id", null, callback)

Saving a Review

client.putReview(review, callback);

Arguments

• review: Review
  • NOTE: If you supply a review ID, that ID will be used to update an existing review, if it exists. If you do not supply an ID, it will create a new review. The review is returned upon success. You MUST supply either the listing_id or listing_external_id that the review is associated with, not both.
• callback: any => Runs when the call completes. Signature is callback(error: string, review: Review)

Typescript

// assume an existing listing at this point ...
import {Review} from "vendasta-sdk/src/index";
review: Review = new Review();
review.listing_id = listing.listing_id;
review.star_rating = 5.0;
review.content = "Review content";
client.putReview(review, callback);

Javascript

// assume an existing listing at this point ...
var review = new vendastaSdk.Review();
review.listing_id = listing.listing_id;
review.star_rating = 5.0;
review.content = "Review content";
client.putReview(review, callback);

Retrieving a Review

Retrieve a review with:

client.getReview(reviewId, callback);

Arguments

• reviewId: string => This is available from the Review object after it has been saved.
• callback: any => Runs when the call completes. Signature is callback(error: string, review: Review)

Typescript

// assume an existing review at this point ...
import {Review} from "vendasta-sdk/src/index";
let review: Review = client.getReview("review-id", callback);

Javascript

// assume an existing review at this point ...
var review = client.getReview("review-id", callback);

Deleting a Review

Delete a review with:

client.deleteReview(reviewId, callback);

Arguments

• reviewId: string => This is available from the Review object after it has been saved.
• callback: any => Runs when the call completes. Signature is callback(error: string, empty: Empty)

Typescript

// assume an existing review at this point ...
client.deleteReview("review-id", callback);

Javascript

// assume an existing review at this point ...
client.deleteReview("review-id", callback);

Retrieving a list of reviews

List reviews with:

client.listReviews(listingId, listingExternalId, pageSize, cursor, callback);

Arguments

• listingId: The listing_id of the Listing to get the reviews for.
• listingExternalId: The external_id of the Listing to get the reviews for.
  • NOTE: You can either specify listingId or listingExternalId, not both.
• pageSize: The number of reviews to return with each request.
• cursor: Blank for the first page, pass through the cursor returned on the first / previous request to get the next page.
  • NOTE: the cursor returned will be blank once the end of the list is reached.
• callback: any => Runs when the call completes. Signature is callback(error: string, listResponse: ListReviewResponse)

Typescript

// assume a listing with some reviews here ...
let pageSize = 10;
let cursor = "";

var reviews: Review[];
client.listReviews(listingId, null, pageSize, cursor, getAllReviews);

function getAllReviews(error: string, listResponse: ListReviewResponse) {
    reviews = reviews.concat(listResponse.reviews);
    cursor = listResponse.cursor;
    if (cursor == "") {
        return;
    }
    client.listReviews(listingId, null, pageSize, cursor, getAllReviews);
}

Javascript

// assume a listing with some reviews here ...
var pageSize = 10;
var cursor = "";

var reviews = [];
client.listReviews(listingId, null, pageSize, cursor, getAllReviews);

function getAllReviews(error, listResponse) {
    reviews = reviews.concat(listResponse.reviews);
    cursor = listResponse.cursor;
    if (cursor == "") {
        return;
    }
    client.listReviews(listingId, null, pageSize, cursor, getAllReviews);
}

Quickstart

See listingExample.ts and reviewExample.ts in vendasta-sdk/example here

Objects

Listing

The Listing class is used when interacting with the client.

Required Fields

• url: string => The URL where the listing can be found. (Not to be confused with the business’ website, above.)

Optional Fields

• external_id: string => This is your ID for this listing.
• listing_id: string => The ID used to identify the listing. This is set by the system when a new listing is saved.
• company_name: string => The name of the company the listing represents.
• address: string => The address of the company the listing represents.
• city: string => The city the business resides in.
• state: string => The state / province the business resides in.
• country: string => The country the business resides in.
• zip_code: string => The zip code / postal code of the business.
• location: Geo => The latitude and longitude of the business location.
• business_categories: array => A list of categories that describes the business the listing represents.
• phone: string => The primary contact number for the business.
• additional_phone_numbers: Array => Numbers that are registered for the business, but is not the primary contact number.
• website: string => The website owned by the business. Not to be confused with the URL of the listing itself (see url below).

Geo

This class is used to set the location of the listing.

• latitude: number => latitudinal location of the listing.
• longitude: number => longitudinal location of the listing.

Review

The Review class is used when interacting with the client.

Required Fields

One of:

• listing_id: string => The ID of the listing this review belongs to.
• listing_external_id: string => Your ID for the listing.

Optional Fields

• review_id: string => The ID used to identify the review. This will only be set after saving the review.
• url: string => The URL to the review.
• title: string => The title of the review.
• star_rating: number => The rating of the review.
• reviewer_name: string => The name of the reviewer who created the review.
• reviewer_email: string => The email address of the reviewer.
• reviewer_url: string => The URL to the reviewer's profile.
• content: string => The full text content of the review.
• published_date: Timestamp => The date on which the review was published.

Empty

This is an empty object from GRPC.

• It has no fields.

Timestamp

This is a timestamp object from GRPC.

• seconds: number => The number of seconds after (positive) or before (negative) the 1970 epoch.
• nanos: number => The fractional portion of the last second, in nanoseconds. This number must always be positive, even for negative timestamps.

Development

You must clone the repository to use these features

A docker container and a build script is provided to run any Node/NPM related commands without needing to have Node installed on your computer.

By default, the build script will run the typescript compiler in watch mode: tsc -w (you must be running the docker for mac or docker for windows application for watch mode to work).

For example, to compile the typescript, run:

./build.sh tsc # Use the -w flag to have the typescript compiler incrementally compile changes

To install the node_modules folder locally, run:

./build.sh npm install

To install any extra typings, run:

./build.sh typings # (any command typings supports)

To regenerate the documentation, run:

./build.sh jsdoc -c jsdoc_conf.json

Testing

Tests are using jasmine-node-karma. To run the tests, use

npm test