node-etsy-client

NodeJs Etsy REST API Client V3.

• compatible with JavaScript and TypeScript.

In addition, this library provide an extra

• OAuth2Service to manage oAuth2 workflow:
  • build connect url,
  • handle callback,
  • and manage refresh token.
  • with an oauth.js sample to make some oAuth2 manual tests.

EtsyClientV3

Features

using apiKey:

• findShops
• getShop
• getShopSections
• findAllActiveListingsByShop
• getListing
• getListingVariationImages
• getListingImages
• getListingProperty

using apiKey + OAuth token:

• getListingsByShop
• getListingInventory
• getListingProduct

Quick start

First declare your api key:

export ETSY_API_KEY=xxxxxxxxxxx

install node-etsy-client:

npm install node-etsy-client

then let's go, here is a sample.js:

import { EtsyClientV3 } from 'node-etsy-client';
async function doIt() {
  var client = new EtsyClientV3();
  var shops = await client.findShops({'shop_name':'mony', limit:10});
  console.log(shops);
}
doIt();

You could play Mocha tests to get more examples (cf. next section).

You could avoid using environment variable by using constructor options:

var client = new EtsyClientV3({apiKey:'mSecretHere'});

Advanced usage

Etsy debug mode

To print out in the console the API call and response:

export ETSY_DEBUG=true

Etsy client options

This section describes EtsyClientV2/EtsyClientV3 available options.

Note about options precedence:

• first take option value from constructor if any,
• or else try to retrieve related environment variable,
• or else apply default value.

Options:

Name	Description
apiUrl	Etsy API endpoint - (or env.ETSY_API_ENDPOINT) default value is (v2)https://openapi.etsy.com/v2 / (v3)https://openapi.etsy.com/v3
apiKey	Etsy API key - required (or env.ETSY_API_KEY) without default value. Ask one from Etsy portal
shopId	Etsy shop id - optional (or env.ETSY_SHOP_ID) without default value
lang	Etsy language - optional (or env.ETSY_LANG) without default value. Example: fr
ETSY_DRY_MODE) with default value	false
dryMode	print call instead of making real etsy call - optional (or env.ETSY_DRY_MODE) with default value: false
etsyRateWindowSizeMs	Rate limit windows size in milliseconds - optional (or env.ETSY_RATE_WINDOWS_SIZE_MS) with default value: 1000
etsyRateMaxQueries	Rate limit max query per windows size - optional (or env.ETSY_RATE_MAX_QUERIES) without default value

Note about rate limit options:

• rate limit is recommended for V2 client.

• rate limit is enabled if and only if etsyRateWindowSizeMs and etsyRateMaxQueries are both set.

• if enabled, rate limit on etsy call is max etsyRateMaxQueries per etsyRateWindowSizeMsms.

For more details, cf. susi-rali

Rate limit

According to Open API v2 documentation, Etsy policy was to restricts number of call to 10 per second (and 10k per day).

With Open API v3, there is no such restriction so rate limiter is deprecated and disabled by default.

In order to rate limit calls, node-etsy-client rely on susi-rali and offer an option to rate limit client calls.

To apply rate limit of 10 query per seconds (with wait on unavailable slot), add etsyRateMaxQueries option:

var client = new EtsyClientV2({apiKey:'mSecretHere', etsyRateMaxQueries:10});

Note about ETSY API versions

Starting from 2.0.0 node-etsy-client provide an EtsyClientV3 utility class dedicated to etsy 3 api calls.

For previous version (v2 Open API will be discontinued) please rely on node-etsy-client <2.0.0 versions.

During migration from v2 to v3 #39 some ticket have been created on Etsy OpenAPI side, especially for the getListing api:

• includes related ticket: etsy/open-api#236 (improvement)
• variations values translations related ticket: etsy/open-api#431 (bug)

How to contribute

You're not a dev ? just submit an issue (bug, improvements, questions). Or else:

• Clone
• Install deps
• setup your test environment (cf. initEnv.example.sh)
• Then mocha tests

git clone https://github.com/creharmony/node-etsy-client.git
cd node-etsy-client
npm install
# play test without etsy endpoint
npm run test
# play test with etsy endpoint
. ./env/initEnv.example.sh
npm run test

• you could also fork, feature branch, then submit a pull request.

Services or activated bots

badge	name	description
	Github actions	Continuous tests + coverage using c8.
	Github actions	Continuous vulnerability audit.
	Houndci	JavaScript automated review (configured by .hound.yml)
	gren	Release notes automation
	Github pages host some metrics for the main branch of this project: code coverage