@3dlook/saia-sdk

JS SDK for SAIA Perfect Fit

Usage no npm install needed!

<script type="module">
  import 3dlookSaiaSdk from 'https://cdn.skypack.dev/@3dlook/saia-sdk';
</script>

README

SAIA Javascript SDK

Build Status Version Dependencies

Installing

To install SAIA SDK as npm package into your project, use the following command using npm:

npm install --save @3dlook/saia-sdk

Building

To build SAIA SDK, clone repository to your local machine

with https:

git clone https://github.com/3dlook-me/saia-sdk.git

or with ssh:

git clone git@github.com:3dlook-me/saia-sdk.git

and then enter into the cloned project directory in the terminal:

cd saia-sdk

and build it:

npm run build:prod

Usage

SAIA Javascript SDK works as an API wrapper. To use it, you only need to create a new instance of the SAIA class and then call methods that you need.

Example:

const frontImage, sideImage;

const saia = new SAIA({
  key: '<your api key>',
});

saia.api.person.create({
  gender: 'female',
  height: 180,
  frontImage: frontImage,
  sideImage: sideImage,
})
  .then((taskSetId) => saia.api.queue.getResults(taskSetId))
  .then(results => console.log(results))
  .catch(err => console.error(err));

API

Classes

API

API wrapper class

MTMClient

MTMClient class

Person

Person class

Product

Product class

Queue

Queue class

Sizechart

Product class

SAIA

Functions

getBase64(file)Promise.<string>

Convert File or Blob object to base64 string

getFileName(blob)

Get file name with extension for Blob

getTaskError(tasks)string

Get error description

API

API wrapper class

Kind: global class

new API(options)

Class constructor

Param Type Description
options Object options
options.host string API url
options.key string API key

Example

const api = new API({
  key: '<your key>',
  host: '<api host url>',
});

MTMClient

MTMClient class

Kind: global class

new MTMClient(host, axios)

MTMClient's class constructor

Param Type Description
host string host url
axios Axios axios instance

mtmClient.create(params) ⇒ Promise.<number>

Create mtm client

Kind: instance method of MTMClient
Returns: Promise.<number> - mtm client's id

Param Type Description
params object mtm client's parameters
params.firstName string mtm client's first name
[params.lastName] string mtm client's last name
params.unit string mtm client's unit - cm or in
[params.phone] string mtm client's phone number - cm or in
[params.email] string mtm client's email - cm or in
[params.source] string the source of the request - dashboard, widget
[params.notes] string additional information about mtm client
[params.widgetId] string widget object id

Example

const saia = new SAIA({
  key: '<your key>',
});

// create person only with metadata
// and get its id
saia.api.mtmClient.create({
  firstName: 'Stephen',
  lastName: 'King',
  unit: 'in',
})
  .then(mtmClientId => console.log(mtmClientId))
  .catch(err => console.log(err));

mtmClient.update(params) ⇒ Promise.<number>

Update mtm client

Kind: instance method of MTMClient
Returns: Promise.<number> - mtm client's id

Param Type Description
params object mtm client's parameters
params.firstName string mtm client's first name
[params.lastName] string mtm client's last name
params.unit string mtm client's unit - cm or in
[params.phone] string mtm client's phone number - cm or in
[params.email] string mtm client's email - cm or in
[params.source] string the source of the request - dashboard, widget
[params.notes] string additional information about mtm client
[params.widgetId] string widget object id

Example

const saia = new SAIA({
  key: '<your key>',
});

// update person only with metadata
// and get its id
const existingMtmClientId = 1;

saia.api.mtmClient.update(existingMtmClientId, {
  firstName: 'Stephen',
  lastName: 'King',
  unit: 'in',
})
  .then(mtmClientId => console.log(mtmClientId))
  .catch(err => console.log(err));

mtmClient.createPerson(mtmClientId, params) ⇒ Promise.<(string|number)>

Create person for mtm client only with metadata (gender and height) or with photos (gender, height, frontImage, sideImage).

If you create Person only with metadata, then you will get Person's ID. If you create Person with metadata and images, you will get Taskset ID

Kind: instance method of MTMClient
Returns: Promise.<(string|number)> - person's id or taskset id

Param Type Description
mtmClientId number mtm client id
params object person's parameters
params.gender string person's gender
params.height number person's height
[params.measurementsType] string type of measurements - all
[params.frontImage] string person's Base64 encoded front photo
[params.sideImage] string person's Base64 encoded side photo
[params.weight] string person's weight in kg
[params.weightTopBorder] string person's top weight border in kg
[params.weightBottomBorder] string person's bottom weight border in kg

Example

const saia = new SAIA({
  key: '<your key>',
});

// create person only with metadata
// and get its id
saia.api.mtmClient.createPerson(mtmClientId, {
  gender: 'male',
  height: 180,
})
  .then(personId => console.log(personId))
  .catch(err => console.log(err));

// create person only with metadata and images
// and get taskset id. You can use it to track
// calculation process by using saia.api.queue.getResults(taskSetId)
saia.api.mtmClient.createPerson(mtmClientId, {
  gender: 'male',
  height: 180,
  frontImage: <frontImage>,
  sideImage: <sideImage>,
})
  .then(taskSetId => console.log(taskSetId))
  .catch(err => console.log(err));

Person

Person class

Kind: global class

new Person(host, axios)

Person's class constructor

Param Type Description
host string host url
axios Axios axios instance

person.create(params) ⇒ Promise.<(string|number)>

Create person only with metadata (gender and height) or with photos (gender, height, frontImage, sideImage).

If you create Person only with metadata, then you will get Person's ID. If you create Person with metadata and images, you will get Taskset ID

Kind: instance method of Person
Returns: Promise.<(string|number)> - person's id or taskset id

Param Type Description
params object person's parameters
params.gender string person's gender
params.height number person's height
[params.measurementsType] string type of measurements - all
[params.hasVirtualTryOn] boolean should apply virtual try on
[params.product] any product sku which would be used for virtual try on
[params.frontImage] string person's Base64 encoded front photo
[params.sideImage] string person's Base64 encoded side photo
[params.weight] string person's weight in kg
[params.weightTopBorder] string person's top weight border in kg
[params.weightBottomBorder] string person's bottom weight border in kg
[params.deviceCoordinates] Object user device x, y, z coordinates during photos
params.deviceCoordinates.frontPhoto Object user device x, y, z coordinates during Front photo
params.deviceCoordinates.frontPhoto.betaX number value represents the motion of the device around the x axis, represented in degrees with values ranging from -180 to 180. This represents a front to back motion of the device.
params.deviceCoordinates.frontPhoto.gammaY number value represents the motion of the device around the y axis, represented in degrees with values ranging from -90 to 90. This represents a left to right motion of the device.
params.deviceCoordinates.frontPhoto.alphaZ number value represents the motion of the device around the z axis, represented in degrees with values ranging from 0 to 360.
params.deviceCoordinates.sidePhoto Object user device x, y, z coordinates during Side photo
params.deviceCoordinates.sidePhoto.betaX number value represents the motion of the device around the x axis, represented in degrees with values ranging from -180 to 180. This represents a front to back motion of the device.
params.deviceCoordinates.sidePhoto.gammaY number value represents the motion of the device around the y axis, represented in degrees with values ranging from -90 to 90. This represents a left to right motion of the device.
params.deviceCoordinates.sidePhoto.alphaZ number value represents the motion of the device around the z axis, represented in degrees with values ranging from 0 to 360.
params.photoFlowType string photo flow type ("friend" or "hand").

Example

const saia = new SAIA({
  key: '<your key>',
});

// create person only with metadata
// and get its id
saia.api.person.create({
  gender: 'male',
  height: 180,
})
  .then(personId => console.log(personId))
  .catch(err => console.log(err));

// create person only with metadata and images
// and get taskset id. You can use it to track
// calculation process by using saia.api.queue.getResults(taskSetId)
saia.api.person.create({
  gender: 'male',
  height: 180,
  frontImage: <frontImage>,
  sideImage: <sideImage>,
})
  .then(taskSetId => console.log(taskSetId))
  .catch(err => console.log(err));

person.get(id) ⇒ Promise.<Object>

Get a specific Person by ID

Kind: instance method of Person
Returns: Promise.<Object> - Person

Param Type Description
id number Person's ID

Example

const saia = new SAIA({
  key: '<your key>',
});

saia.api.person.get(40)
  .then(person => console.log(person))
  .catch(err => console.log(err));

person.update(id, params) ⇒ Promise.<Object>

Full or Partial update Person by ID. Returns person's object with metadate.

Kind: instance method of Person
Returns: Promise.<Object> - updated parameters

Param Type Description
id number Person''s ID
params Object Person's parameters
[params.gender] string Person's parameters
[params.height] number Person's height
[params.frontImage] string Person's Base64 encoded frontImage
[params.sideImage] string Person's Base64 encoded sideImage
[params.weight] string person's weight in kg
[params.weightTopBorder] string person's top weight border in kg
[params.weightBottomBorder] string person's bottom weight border in kg
[params.deviceCoordinates] Object user device x, y, z coordinates during photo
params.deviceCoordinates.frontPhoto Object user device x, y, z coordinates during Front photo
params.deviceCoordinates.frontPhoto.betaX number value represents the motion of the device around the x axis, represented in degrees with values ranging from -180 to 180. This represents a front to back motion of the device.
params.deviceCoordinates.frontPhoto.gammaY number value represents the motion of the device around the y axis, represented in degrees with values ranging from -90 to 90. This represents a left to right motion of the device.
params.deviceCoordinates.frontPhoto.alphaZ number value represents the motion of the device around the z axis, represented in degrees with values ranging from 0 to 360.
params.deviceCoordinates.sidePhoto Object user device x, y, z coordinates during Side photo
params.deviceCoordinates.sidePhoto.betaX number value represents the motion of the device around the x axis, represented in degrees with values ranging from -180 to 180. This represents a front to back motion of the device.
params.deviceCoordinates.sidePhoto.gammaY number value represents the motion of the device around the y axis, represented in degrees with values ranging from -90 to 90. This represents a left to right motion of the device.
params.deviceCoordinates.sidePhoto.alphaZ number value represents the motion of the device around the z axis, represented in degrees with values ranging from 0 to 360.
params.photoFlowType string photo flow type ("friend" or "hand").

Example

const saia = new SAIA({
  key: '<your key>',
});

saia.api.person.update(personId, {
  frontImage: <frontImage>,
  sideImage: <sideImage>,
})
  .then(updatedFields => console.log(updatedFields))
  .catch(err => console.log(err));

person.updateAndCalculate(id, params) ⇒ Promise.<string>

Update a new Person by ID with calculation start. Returns person's task set id.

Kind: instance method of Person
Returns: Promise.<string> - task set url

Param Type Description
id number Person''s ID
params Object Person's parameters
[params.measurementsType] string type of measurements - all
[params.hasVirtualTryOn] boolean should apply virtual try on
[params.product] any product sku which would be used for virtual try on
[params.gender] string Person's parameters
[params.height] number Person's height
[params.frontImage] string Person's Base64 encoded frontImage
[params.sideImage] string Person's Base64 encoded sideImage
[params.weight] string person's weight in kg
[params.weightTopBorder] string person's top weight border in kg
[params.weightBottomBorder] string person's bottom weight border in kg
[params.deviceCoordinates] Object user device x, y, z coordinates during photo
params.deviceCoordinates.frontPhoto Object user device x, y, z coordinates during Front photo
params.deviceCoordinates.frontPhoto.betaX number value represents the motion of the device around the x axis, represented in degrees with values ranging from -180 to 180. This represents a front to back motion of the device.
params.deviceCoordinates.frontPhoto.gammaY number value represents the motion of the device around the y axis, represented in degrees with values ranging from -90 to 90. This represents a left to right motion of the device.
params.deviceCoordinates.frontPhoto.alphaZ number value represents the motion of the device around the z axis, represented in degrees with values ranging from 0 to 360.
params.deviceCoordinates.sidePhoto Object user device x, y, z coordinates during Side photo
params.deviceCoordinates.sidePhoto.betaX number value represents the motion of the device around the x axis, represented in degrees with values ranging from -180 to 180. This represents a front to back motion of the device.
params.deviceCoordinates.sidePhoto.gammaY number value represents the motion of the device around the y axis, represented in degrees with values ranging from -90 to 90. This represents a left to right motion of the device.
params.deviceCoordinates.sidePhoto.alphaZ number value represents the motion of the device around the z axis, represented in degrees with values ranging from 0 to 360.
params.photoFlowType string photo flow type ("friend" or "hand").

Example

const saia = new SAIA({
  key: '<your key>',
});

saia.api.person.updateAndCalculate(personId, {
  frontImage: <frontImage>,
  sideImage: <sideImage>,
})
  .then(taskSetUrl => saia.api.queue.getResults(taskSetUrl))
  .then(person => console.log(person))
  .catch(err => console.log(err));

person.calculate(id) ⇒ Promise.<string>

Manual recalculate Person's parameters by ID

Kind: instance method of Person
Returns: Promise.<string> - Taskset id

Param Type Description
id number Person's ID

Example

// in this example we update person's images
// and then manually start recalculation
const saia = new SAIA({
  key: '<your key>',
});

saia.api.person.update({
  frontImage: <frontImage>,
  sideImage: <sideImage>,
})
  .then(updatedFields => saia.api.person.calculate(updatedFields.id))
  .then(taskSetId => console.log(taskSetId))
  .catch(err => console.log(err));

person.virtualTryOn(id, product) ⇒ Promise.<Object>

Processing virtual tryon for specific person and product result also would be available in person.get(id).virtual_tryons [ { "id": tryonId, "product_sku": "productSku" "created": 'datetime', "image: "https://url.to.tryon.image.com" } ]

Kind: instance method of Person
Returns: Promise.<Object> - virtual try on Object { "id": tryonId, "product_sku": "productSku" "created": 'datetime', "image: "https://url.to.tryon.image.com" }

Param Type Description
id number Person's ID
product any Product sku

Product

Product class

Kind: global class

new Product(host, axios)

Product's class constructor

Param Type Description
host string host url
axios Axios axios instance

product.get(url) ⇒ Promise.<(Object|Array)>

Get product object/objects by its page url. It can return an array if two or more products have the same url

Kind: instance method of Product

Param Type Description
url string product page url

Example

const saia = new SAIA({
  key: '<your key>',
});

saia.api.product.get('https://saia.3dlook.me/test-product')
  .then(product => console.log(product))
  .catch(err => console.log(err));

product.getSize(params) ⇒ Promise.<object>

Get sizes for product based on person parameters. This method uses old implemendation of a size recommendation method

Kind: instance method of Product

Param Type Description
params Object parameters
params.height number person's height
params.gender string person's gender
params.hips number person's volume_params.hips
params.chest number person's volume_params.chest
params.waist number person's volume_params.waist
params.url string product url

Example

const saia = new SAIA({
  key: '<your key>',
});

saia.api.product.getSize({
  height: 173,
  gender: 'female',
  hips: 89,
  chest: 87,
  waist: 73,
  url: 'https://saia.3dlook.me/test-product',
})
  .then(size => console.log(size))
  .catch(err => console.log(err));

product.getRecommendations(params) ⇒ Promise.<object>

Get size recommendations for a selected product based on user measurements. This method uses new implementation of a size recommendation method.

Kind: instance method of Product

Param Type Description
params Object parameters
params.gender string person's gender
params.hips number person's volume_params.hips
params.chest number person's volume_params.chest
params.waist number person's volume_params.waist
params.url string product url

Example

const saia = new SAIA({
  key: '<your key>',
});

saia.api.product.getRecommendations({
  gender: 'female',
  hips: 89,
  chest: 87,
  waist: 73,
  url: 'https://saia.3dlook.me/test-product',
})
  .then(size => console.log(size))
  .catch(err => console.log(err));

Queue

Queue class

Kind: global class

new Queue(host, axios)

Queue's class constructor

Param Type Description
host string host url
axios Axios axios instance

queue.get(id) ⇒ Promise.<object>

Get information about tasks by taskset id

Kind: instance method of Queue

Param Type Description
id string taskset id

Example

const saia = new SAIA({
  key: '<your key>',
});

saia.api.queue.get('4d563d3f-38ae-4b51-8eab-2b78483b153e')
  .then(task => console.log(task))
  .catch(err => console.log(err));

queue.getResults(id, [delay], [personId]) ⇒ Promise.<object>

Get result of person processing

Kind: instance method of Queue

Param Type Description
id string taskset id
[delay] number delay before next check
[personId] number person id

Example

const saia = new SAIA({
  key: '<your key>',
});

saia.api.queue.getResults('4d563d3f-38ae-4b51-8eab-2b78483b153e')
  .then(person => console.log(person))
  .catch(err => console.log(err));

// you also can specify the delay between checks
saia.api.queue.getResults('4d563d3f-38ae-4b51-8eab-2b78483b153e', 3400)
  .then(person => console.log(person))
  .catch(err => console.log(err));

Sizechart

Product class

Kind: global class

new Sizechart(host, axios)

Product's class constructor

Param Type Description
host string host url
axios Axios axios instance

sizechart.getSize(params) ⇒ Promise.<object>

Get sizes for brand and body part based on person parameters

Kind: instance method of Sizechart

Param Type Description
params Object parameters
params.gender string person's gender
params.hips number person's volume_params.hips
params.chest number person's volume_params.chest
params.waist number person's volume_params.waist
params.body_part number body part
params.brand number brand name
[params.customRecommendation] string custom recommendation url part for our clients. For internal usage only or if you have custom url and you know what you're doing

Example

const saia = new SAIA({
  key: '<your key>',
});

saia.api.sizechart.getSize({
  gender: 'female',
  hips: 89,
  chest: 87,
  waist: 73,
  body_part: 'top',
  brand: 'Nike',
})
  .then(size => console.log(size))
  .catch(err => console.log(err));

SAIA

Kind: global class

new SAIA(options)

SAIA class constructor

Param Type Description
options Object config parameters
options.key string api key
options.host string api host url

Example

const saia = new SAIA({
  key: '<your key>'
});

getBase64(file) ⇒ Promise.<string>

Convert File or Blob object to base64 string

Kind: global function

Param Type Description
file File | Blob image file

getFileName(blob)

Get file name with extension for Blob

Kind: global function

Param Type Description
blob Blob file

getTaskError(tasks) ⇒ string

Get error description

Kind: global function

Param Type Description
tasks Array array of tasks

Testing

To run tests, you need to run this command on terminal/consol:

Linux/macOS

$ export API_KEY='<your api key>' && export API_HOST='<host>' && npm test

Windows

$ set API_KEY='<your api key>' && set API_HOST='<host>' && npm test