@fitanalytics/stylefinder-sdk NPM | npm.io

1.1.0-rc1 • Published 2 years ago

Install

Weekly downloads

-

License

ISC

Repository

Last release

2 years ago

StyleFinder SDK

This project serves to simplify integration for our clients with the Stylefinder API. It is written in Typescript and is built using Node 14.

Reference

The following provides a reference for the public-facing part of the Style Finder SDK request library. For documentation of our Style Finder API, please visit the Style Finder API Guide.

Note that all ids, secrets, tokens, and passwords in this file are gibberish and only serve as examples.

Basic usage

The main entry point is the styleFinder function provided by the stylefinder-sdk package:

import styleFinder from '@fitanalytics/stylefinder-sdk';

const sf = styleFinder('kb09g1ib7labkze9u923b');

It takes one argument:

apiToken string (required): The API token (1,2) for the current user.

Resources and resource methods

Every API endpoint represents a resource. This includes resources like products as well as all the different types of style recommendations.

Resources are interacted with via so-called resource methods. Depending on the type of resource, one or several of these methods are available to the developer. For example, to get a list of products, sf.products.list() needs to be called.

The generalized syntax for calling request methods is the following:

sf.[RESOURCE].[RESOURCE_METHOD]().

Resource methods

Each resource can come with up to five different resource methods, which are:

retrieve() Promise<Resource>: Fetches a single instance of Resource from the API.
list() Promise<Resource[]>: Fetches multiple instances of Resource from the API.
create() Promise<Resource>: Creates an instance of Resource and returns it.
update() Promise<Resource>: Changes the properties of an existing instance of Resource and returns it.
delete() Promise<any>: Deletes an instance of Resource.

Resource reference

Below you will find documentation for all resources and their respective resource methods, along with the data that they consume.

Profiles

This endpoint allows for the retrieval and manipulation of user profiles.

Retrieve

const profile = await sf.profiles.retrieve({
    profileId: '01FVYER542AXMNWH2XC89B9XS8'
});

// => {"gender":"m","isPrimary":true,"id":"01FVYER542AXMNWH2XC89B9XS8"}

This method takes the following parameters:

profileId string (required): ID of a user profile associated with the current user.
includePurchases boolean: Include list of past purchasse of the current user in the response.
purchasesGender Gender: Filter past purchases by the specified gender.
purchasesCategory Category: Filter past purchases by the specified category.

List

const profiles = await sf.profiles.list({
    ids: ['01FVW6FZP218QTNNGJVKSVYY4H', '01FVW6GCX2RE4ATTPJN30XZTRG']
});

// => [{"gender":"m","isPrimary":false,"id":"01FVW6FZP218QTNNGJVKSVYY4H"},{"gender":"m","isPrimary":true,"id":"01FVW6GCX2RE4ATTPJN30XZTRG"}]

This method takes the following parameters:

ids string[]: Filter profiles by the specified ID.
gender Gender: Filter profiles by the specified gender.
includePurchases boolean: Include list of past purchasse of the current user in the response.
purchasesGender Gender: Filter past purchases by the specified gender.
purchasesCategory Category: Filter past purchases by the specified category.
limit number: Limits the amount of objects returned to the number provided.

Create

const profile = await sf.profiles.create({
    gender: 'w',
    isPrimary: true,
    age: 34
});

// => {"gender":"w","isPrimary":true,age:34,"id":"01FVYER542AXMNWH2XC89B9XS8"}

This method takes the following parameters:

gender Gender (required): Gender of the profile to be created.
isPrimary boolean (required): If true, the profile to be created will be the default profile for the current user and gender.
height number: Body height in cm.
weight number: Body weight in kg.
age number: Age in years.

Update

const profile = await sf.profiles.update({
    profileId: '01FVYER542AXMNWH2XC89B9XS8',
    age: 35
});

// => {"gender":"w","isPrimary":true,age:35,"id":"01FVYER542AXMNWH2XC89B9XS8"}

This method takes the following parameters:

profileId string (required): ID of a user profile associated with the current user.
isPrimary boolean : If true, the profile to be updated will be the default profile for the current user and gender.
height number: Body height in cm.
weight number: Body weight in kg.
age number: Age in years.

Note that updating the gender of a user profile is not possible.

Delete

const response = await sf.profiles.delete({
    gender: 'm'
});

// => {"meta":{"count":2,"debug":{"syncRecords":false}}}

This method takes the following parameters:

ids string[]: IDs of the user profiles associated with the current user.
gender Gender: Gender of the profiles to be deleted.

Topsellers

this endpoint allows for the retrieval of your shop's top selling garments.

List

const topsellers = await sf.topsellers.list({
    shopLanguage: 'da',
    shopCountry: 'DK',
    includeProduct: true
});

// => [{ "score": 0.5, "product": { "id": "yourshop-12345-678", "category": "lower", "gender": "m", ... }, "id": "01FC8TKP1T0Z3K0GF794BBV12Y" }, ...]

This method takes the following parameters:

shopCountry string (required): An ISO 3166-1 alpha-2 country code representing the currently selected country of your shop.
shopLanguage string (required): An ISO 639-1 language code representing the currently selected language of your shop.
gender Gender: Limits recommendations to the gender provided.
categories Category[]: Limits recommendations to the categories provided.
includeProduct boolean: If true, replaces the product serial product with a rich representation of the corresponding product.
includeGarment boolean: If true and if includeProduct is true, it replaces the garment ID with a rich representation of the corresponding garment.
limit number: Limits the amount of objects returned to the number provided.

Shop recommendations

this endpoint allows for the retrieval of generic recommendations for your shop.

List

const shopRecommendations = await sf.shopRecommendations.list({
    shopLanguage: 'es',
    shopCountry: 'ES',
    gender: 'm',
    includeProduct: true
});

// => [{ "score": 0.5, "product": { "id": "yourshop-12345-678", "category": "lower", "gender": "m", ... }, "id": "01FC8TKP1T0Z3K0GF794BBV12Y" }, ...]

This method takes the following parameters:

shopCountry string (required): An ISO 3166-1 alpha-2 country code representing the currently selected country of your shop.
shopLanguage string (required): An ISO 639-1 language code representing the currently selected language of your shop.
gender Gender (required): Limits recommendations to the gender provided.
categories Category[]: Limits recommendations to the categories provided.
includeProduct boolean: If true, replaces the product serial product with a rich representation of the corresponding product.
includeGarment boolean: If true and if includeProduct is true, it replaces the garment ID with a rich representation of the corresponding garment.
limit number: Limits the amount of objects returned to the number provided.

User recommendations

this endpoint allows for the retrieval of user-based recommendations based on the user's past purchases.

List

const userRecommendations = await sf.userRecommendations.list({
    shopLanguage: 'es',
    shopCountry: 'ES',
    gender: 'w',
    includeProduct: true
});

// => [{ "score": 0.5, "product": { "id": "yourshop-12345-678", "category": "lower", "gender": "w", ... }, "id": "01FC8TKP1T0Z3K0GF794BBV12Y" }, ...]

This method takes the following parameters:

shopCountry string (required): An ISO 3166-1 alpha-2 country code representing the currently selected country of your shop.
shopLanguage string (required): An ISO 639-1 language code representing the currently selected language of your shop.
gender Gender: Limits recommendations to the gender provided.
categories Category[]: Limits recommendations to the categories provided.
includeProduct boolean: If true, replaces the product serial product with a rich representation of the corresponding product.
includeGarment boolean: If true and if includeProduct is true, it replaces the garment ID with a rich representation of the corresponding garment.
limit number: Limits the amount of objects returned to the number provided.

Product recommendations

this endpoint allows for the retrieval of similar items to a reference product provided.

List

const productRecommendations = await sf.productRecommendations.list({
    serial: 'yourshop-98765-432',
    shopLanguage: 'cs',
    shopCountry: 'CZ',
    includeProduct: true
});

// => [{ "score": 0.5, "product": { "id": "yourshop-12345-678", "category": "lower", "gender": "w", ... }, "id": "01FC8TKP1T0Z3K0GF794BBV12Y" }, ...]

This method takes the following parameters:

serial string (required): The serial of a reference product.
shopCountry string (required): An ISO 3166-1 alpha-2 country code representing the currently selected country of your shop.
shopLanguage string (required): An ISO 639-1 language code representing the currently selected language of your shop.
includeProduct boolean: If true, replaces the product serial product with a rich representation of the corresponding product.
includeGarment boolean: If true and if includeProduct is true, it replaces the garment ID with a rich representation of the corresponding garment.
limit number: Limits the amount of objects returned to the number provided.

Co-purchases

this endpoint allows for the retrieval of items that have been purchased alongside a reference product provided.

List

const copurchases = await sf.copurchases.list({
    serial: 'yourshop-98765-432',
    shopLanguage: 'cs',
    shopCountry: 'CZ',
    includeProduct: true
});

// => [{ "score": 0.5, "product": { "id": "yourshop-12345-678", "category": "lower", "gender": "w", ... }, "id": "01FC8TKP1T0Z3K0GF794BBV12Y" }, ...]

This method takes the following parameters:

serial string (required): The serial of a reference product.
shopCountry string (required): An ISO 3166-1 alpha-2 country code representing the currently selected country of your shop.
shopLanguage string (required): An ISO 639-1 language code representing the currently selected language of your shop.
includeProduct boolean: If true, replaces the product serial product with a rich representation of the corresponding product.
includeGarment boolean: If true and if includeProduct is true, it replaces the garment ID with a rich representation of the corresponding garment.
limit number: Limits the amount of objects returned to the number provided.

Products

This endpoint allows for the retrieval of product information.

Retrieve

const product = await sf.products.retrieve({
    id: 'yourshop-123456-001',
    shopLanguage: 'de',
    shopCountry: 'DE'
});

// => { "id": "yourshop-123456-001", "category":"upper", "gender":"w", ... }

This method takes the following parameters:

id string (required): The serial of the product to be requested.
shopCountry string (required): An ISO 3166-1 alpha-2 country code representing the currently selected country of your shop.
shopLanguage string (required): An ISO 639-1 language code representing the currently selected language of your shop.
shopSizingSystem string: ID of the preferred sizing system, e.g. "EU", part of the product locale (language and country); the locale may affect the support status, as some may be supported only in certain locales.
includeShopConfig boolean: If true, the Shop Config - an object containing configuration options for your shop - will be appended to the response.

List

const products = await sf.products.list({
    ids: ['yourshop-123456-001', 'yourshop-123456-002', 'yourshop-987654-321'],
    shopLanguage: 'en',
    shopCountry: 'GB'
});

// => [{ "id": "yourshop-123456-001", "category":"upper", "gender":"w", ... }, ...]

This method takes the following parameters:

ids string[] (required): The serials of the products to be requested.
shopCountry string (required): An ISO 3166-1 alpha-2 country code representing the currently selected country of your shop.
shopLanguage string (required): An ISO 639-1 language code representing the currently selected language of your shop.
shopSizingSystem string: ID of the preferred sizing system, e.g. "EU", part of the product locale (language and country); the locale may affect the support status, as some may be supported only in certain locales.
includeShopConfig boolean: If true, the Shop Config - an object containing configuration options for your shop - will be appended to the response.
limit number: Limits the amount of objects returned to the number provided.

Purchases

this endpoint allows for the retrieval of past purchases of the current user.

List

const purchases = await sf.purchases.list({
    category: 'upper',
    includeProduct: true
});

// => [{ "sizeCode": "5XL", "price":" €8.99","purchaseDate": "2020-02-18T05:38:21Z", "product": { "category":"upper", "gender":"m", ... }, "id": "yourshop-595212-253|5XL"}, ...]

This method takes the following parameters:

ids string[]: Filter past purchases of the user by sepecified IDs.
category Category: Filter past purchases of the user by category.
gender Gender: Filter past purchases of the user by gender.
includeProduct boolean: If true, replaces the product serial product with a rich representation of the corresponding product.
limit: number: number: Limits the amount of objects returned to the number provided.

Error types

For the purpose of error type guarding and disambiguation, we expose our custom error classes under the errors namespace:

import { errors } from `stylefinder-sdk`;

This gives you access to the following error types.

ValidationError: Thrown when a client-side validation error has occured, e.g. when a required field is left empty.
APIError: Thrown when an error has been returned by the API which is not captured by any of the more specific API error types.
APIAuthenticationError: Thrown when authentication with the API was unsuccessful.
APIBadRequestError: Thrown when the request was faulty, e.g. when a field is missing that hasn't been detected on the client side.
APINotFoundError: Thrown when a resource wasn't found.
APIServerError: Thrown when an Internal Server Error has occurred.
HttpRequestError: Thrown when a request was unsuccessful before even hitting the API.
HttpRequestError: Thrown for non-API error responses (unlikely to occur).

A word on authentication / authorization

In order to communicate with our API, you will need to create an API token. These tokens are to be created per user/session because they allow for the retrieval of user/session-specific information, such as user profiles, user-specific recommendations, or past purchases.

Note that all ids, secrets, tokens, and passwords in this file are gibberish and only serve as examples.

IMPORTANT: The creation of API tokens involves the usage of an API secret. Thus, token generation must take place in your back-end. DO NOT expose API secrets to a user's device. API tokens can be used safely on user devices.

Creating Key ID and API Secrets

Prerequisites: Your client partner at Fit Analytics should have provided you or the respective person of contact on your end with log-in credentials for our client portal. These consist of an e-mail address and a password.

With these credentials at hand, you can request the creation of an API token for our authorization API:

$ curl -X POST -d '{ "data": { "email": "your.name@yourcompany.com", "password": "supersecretpassword" } }' -H "Content-Type: application/json" -H "Accept: application/json" "https://auth.fitanalytics.com/api/v1/tokens/login"

>>>
{
    "data": {
        "user_id": 1234,
        "shop0_id": "yourshop",
        "expires_in": "2032-04-14T10:31:34.929Z",
        "id": "ey...",
        ...
    }
}

The value under id will be your token for the authorization API.

You can now use this token to create a pair of Key ID and API secret:

$ curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer ey..." "https://auth.fitanalytics.com/api/v1/keys"

>>>
{
   "data" : {
      "created_at" : "2032-04-12T10:37:50.848Z",
      "expired_at" : null,
      "secret" : "93g09ufUI29iihcHcg3001"
      "id" : "mC92hd2id2i9ht2xiHObsaih"
   }
}

The value under id will be your Key ID, the one under secret your API secret.

Creating API tokens

With a valid Key ID and API secret pair at your disposal, you will now be able to request an API token to be used with the Style Finder & Fit Finder API (and, by extension, the Style Finder SDK).

For user or session identification, you can pass a shopUserId or a shopSessionId as optional arguments, but these are not strictly necessary in order to receive some sort of valid token.

$ curl -X POST -d '{ "data": { "key_id": "mC92hd2id2i9ht2xiHObsaih", "secret": "93g09ufUI29iihcHcg3001", "shopUserId": "user123456" } }' -H "Content-Type: application/json" -H "Accept: application/json" "https://auth.fitanalytics.com/api/v1/tokens/client/ffa"

>>>
{
   "data" : {
      "id" : "eyJra...",
      "key_id" : "mC92hd2id2i9ht2xiHObsaih",
      "issued_at" : "2032-04-12T10:48:00.791Z"
   }
}

The value under id will be the API token to be used for authorization on your clients' devices.

axios dotenv qs rollup-plugin-inject-process-env sirv-cli

@everything-registry/sub-chunk-326

2 years ago

2 years ago

2 years ago

2 years ago