SAIA Javascript SDK

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 [email protected]: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

Functions

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

• MTMClient
  • new MTMClient(host, axios)
  • .create(params) ⇒ Promise.<number>
  • .update(params) ⇒ Promise.<number>
  • .createPerson(mtmClientId, params) ⇒ Promise.<(string|number)>

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

• Person
  • new Person(host, axios)
  • .create(params) ⇒ Promise.<(string|number)>
  • .get(id) ⇒ Promise.<Object>
  • .update(id, params) ⇒ Promise.<Object>
  • .updateAndCalculate(id, params) ⇒ Promise.<string>
  • .calculate(id, hasVirtualTryOn, product) ⇒ Promise.<string>
  • .virtualTryOn(id, product) ⇒ Promise.<Object>

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, hasVirtualTryOn, product) ⇒ 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 | | hasVirtualTryOn | boolean | should process virtual try on | | product | any | product sku for virtual try on |

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

• Product
  • new Product(host, axios)
  • .get(url) ⇒ Promise.<(Object|Array)>
  • .getSize(params) ⇒ Promise.<object>
  • .getRecommendations(params) ⇒ Promise.<object>

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

• Queue
  • new Queue(host, axios)
  • .get(id) ⇒ Promise.<object>
  • .getResults(id, [delay], [personId]) ⇒ Promise.<object>

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

• Sizechart
  • new Sizechart(host, axios)
  • .getSize(params) ⇒ Promise.<object>

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