granga / etsy-ts

Etsy API wrapper written in typescript

etsy-ts

Etsy API wrapper written in TypeScript. Includes types for all Etsy API endpoints.

Installation:

npm install etsy-ts --save
yarn add etsy-ts

Etsy API v3

See example in examples/run.ts
Find full API v3 documentation on Etsy.

Breaking changes when migrating from 3.x.x to 4.x.x

• Support for Etsy APIv2 is removed
• All v3 modules are now imported from the root of the package, e.g. import { Etsy } from 'etsy-ts' instead of import { Etsy } from 'etsy-ts/v3'
• Etsy class constructor now requires SecurityDataStorage instance that implements ISecurityDataStorage interface. See a sample implementation in examples/v3/SecurityDataStorage.ts.
• You should remove the refresh token logic from your code - now that's included within this client
• For methods that require oauth, now you need to pass etsyUserId instead of accessToken. This client will use SecurityDataStorage instance to get, refresh and save accessToken for the given etsyUserId.

Credits

Most of the code is generated from Etsy APIv3 Swagger specs, fed to swagger-typescript-api.

etsy-ts's Issues

I am trying to run the example but get "Missing authorization header". What am I missing? thx!

Use reply of ApiMethod.getMethodTable() to improve the wrapper

ApiMethod.getMethodTable() returns clear results among which are

• results type
• parameters and their type

Use all the available info to generate better wrapper.

Unable to upload Images

"Content-Type":"multipart/form-data"

Working with resources

Etsy API supports ability to query data related to a certain entity, all within one request.
https://www.etsy.com/developers/documentation/getting_started/resources

Currently, we can use the "include" parameter as an array of strings. However each of these strings is a name of an entity and there should be some restrictions / types what this array can accept.

Etsy API allows retrieving up to 3 nested associations with this syntax:
?includes=Association[(fieldname[,fieldname...])][:scope][:limit[:offset]][,Assocation...]

Research how other typed Etsy API wrappers have achieved this. If there are no examples find a good solution that allows easy creation of these queries. The query should be typed and it should also predict the exact result type.

Way to fetch ALL (as opposed to limited to 100) records

When there is a paginated data Etsy returns max of 100 records even though sometimes there can be thousands.

Create a way to iterate from 0 to results.count and accumulate all records and return them in one big array. Make use of offset parameter.

Typed `fields` parameter

Etsy API allows specifying the exact entity fields to be retrieved.
https://www.etsy.com/developers/documentation/getting_started/resources

/v2/listings/active?fields=listing_id,title,price

1. Let the fields parameter be typed and accept only the names of properties that exist in the entity
2. If possible, predict the results type according to the properties listed in fields.

There is no way to use updateInventory

oauth_problem=signature_invalid&debug_sbs=PUT&https%3A%2F%2Fopenapi.etsy.com%2Fv2%2Flistings%2F964345818%2Finventory&oauth_consumer_key%3Dfxpjow81qxm1ullsdvi0item%26oauth_nonce%3DjBL2EoZXHQyHTaSBC8VxIYDmjcpNWmqG%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1615410408%26oauth_token%3Db203a290d6696ba022d55579138e3a%26oauth_version%3D1.0%26products%3D%255B%257B%2522property_values%2522%253A%255B%257B%2522property_id%2522%253A513%252C%2522ott_value_qualifier%2522%253A1%252C%2522property_name%2522%253A%2522Bracelet%2520length%2522%252C%2522scale_id%2522%253Anull%252C%2522scale_name%2522%253Anull%252C%2522value_id%2522%253A7%252C%2522values%2522%253A%255B%252216%2520cm%2522%255D%257D%255D%252C%2522offerings%2522%253A%255B%257B%2522price%2522%253A99%252C%2522quantity%2522%253A100%257D%255D%257D%255D

[V3] Tags for createDraftListing / updateListing: string[] vs string

Hello 👋

There is a confusion in the api documentation for the createDraftListing and updateListing methods.
The tags property must be a string (each tag separated by a comma) and not an Array of strings.

🚀

How to use?

Is this supposed to be used in node or in browser?

Etsy API for createReceiptShipment uses application/x-www-form-urlencoded

The code currently works with a JSON encoded body. The body should actually use application/x-www-form-urlencoded. Maybe it can be changed here.

Working code for createReceiptShipment:

            var urlencoded = new URLSearchParams();
            urlencoded.append("tracking_code", data.tracking_code);
            urlencoded.append("carrier_name", data.carrier_name);
            urlencoded.append("send_bcc", data.send_bcc);
            return _this.http.request((0, tslib_1.__assign)({ path: "/v3/application/shops/" + shopId + "/receipts/" + receiptId + "/tracking", method: "POST", body: urlencoded, secure: true, type: http_client_1.ContentType.UrlEncoded, format: "json" }, params));

Solution

• see if we can switch to JSON based connection
• update requests to url encode if needed

axios package version

Thanks for the useful package. I've noticed the axios package is out-dated. axios-auth-refresh latest version now uses ^1.2.2. Is there plans to upgrading the one here?

Add changelog/releases

Can't really see what's going on from version to version. Release notes would be good

Generate documenetation

Find a good tool for typescript documentation generation.
Generate and publish the documentation on GitHub pages.