WooCommerce REST API - TypeScript Library

This is alternative library which provides a set of TypeScript classes that can be used to interact with the WooCommerce REST API. However, it is not a complete implementation of the API, but rather a subset of the API that is useful for.

New TypeScript library for WooCommerce REST API. Supports CommonJS (CJS) and ECMAScript (ESM)

Fixing the issues [Triggered Date: 2022-11-15]

1. This new package was to fixe the issue with the official WooCommerce REST API JavaScript library, which is not compatible with the security features for some packages used for.
2. Axios package used by them, had a Cricital vulnerability which seems not beeing updated often.

Requests are made with Axios library with support to promises.

Installation

npm install --save woocommerce-rest-ts-api

Getting started

Generate API credentials (Consumer Key & Consumer Secret) following this instructions http://docs.woocommerce.com/document/woocommerce-rest-api/ .

Check out the WooCommerce API endpoints and data that can be manipulated in http://woocommerce.github.io/woocommerce-rest-api-docs/.

Setup

ESM example:

import WooCommerceRestApi,{WooRestApiOptions} from "woocommerce-rest-ts-api";
const opt:WooRestApiOptions = {
    url: "http://example.com" ,
    consumerKey:  "ck_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    consumerSecret:  "cs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    version: "wc/v3",
    queryStringAuth: false // Force Basic Authentication as query string true and using under
}
const api = new WooCommerceRestApi(opt);

CJS example:

const WooCommerceRestApi = require("woocommerce-rest-ts-api").default;

const api = new WooCommerceRestApi({
  url: "http://example.com",
  consumerKey: "ck_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  consumerSecret: "cs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  version: "wc/v3",
  queryStringAuth: false // Force Basic Authentication as query string true and using under HTTPS
});

Options

| Option | Type | Required | Description | |-------------------|-----------|----------|---------------------------------------------------------------------------------------------------------------------| | url | String | yes | Your Store URL, example: http://woo.dev/ | | consumerKey | String | yes | Your API consumer key | | consumerSecret | String | yes | Your API consumer secret | | wpAPIPrefix | String | no | Custom WP REST API URL prefix, used to support custom prefixes created with the rest_url_prefix filter | | version | String | no | API version, default is v3 | | encoding | String | no | Encoding, default is 'utf-8' | | queryStringAuth | Bool | no | When true and using under HTTPS force Basic Authentication as query string, default is false | | port | string | no | Provide support for URLs with ports, eg: 8080 | | timeout | Integer | no | Define the request timeout | | axiosConfig | Object | no | Define the custom Axios config, also override this library options |

Methods

GET

• .get(endpoint)
• .get(endpoint, params)
• params?: Partial

| Params | Type | Description | |------------|----------|---------------------------------------------------------------| | endpoint | String | WooCommerce API endpoint, example: customers or orders/12 | | params | Object | Query strings params, example: { per_page: 20 } |

POST

• .post(endpoint, data)
• .post(endpoint, data, params)
• data: Record<string, unknown>
• params?: Partial

| Params | Type | Description | |------------|----------|-------------------------------------------------------------| | endpoint | String | WooCommerce API endpoint, example: customers or orders | | data | Object | JS object to be converted into JSON and sent in the request | | params | Object | Query strings params |

PUT

• .put(endpoint, data)
• .put(endpoint, data, params)
• data: Record<string, unknown>
• params?: Partial

| Params | Type | Description | |------------|----------|-------------------------------------------------------------------| | endpoint | String | WooCommerce API endpoint, example: customers/1 or orders/1234 | | data | Object | JS object to be converted into JSON and sent in the request | | params | Object | Query strings params |

DELETE

• .delete(endpoint)
• .delete(endpoint, params)
• data: Pick<WooRestApiParams, "force">,
• params: Pick<WooRestApiParams, "id">

| Params | Type | Description | |------------|----------|-----------------------------------------------------------------| | endpoint | String | WooCommerce API endpoint, example: customers/2 or orders/12 | | params | Object | Query strings params, example: { force: true } |

OPTIONS

• .options(endpoint)
• .options(endpoint, params)
• params?: Partial

| Params | Type | Description | |------------|----------|-----------------------------------------------------------------| | endpoint | String | WooCommerce API endpoint, example: customers/2 or orders/12 | | params | Object | Query strings params |

Example of use

import WooCommerceRestApi,{CouponsParams, ProductsMainParams, OrdersMainParams, WooRestApiOptions} from "woocommerce-rest-ts-api";
// const WooCommerceRestApi = require("woocommerce-rest-ts-api").default;

const api = new WooCommerceRestApi({
  url: "http://example.com",
  consumerKey: "ck_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  consumerSecret: "cs_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  version: "wc/v3",
  queryStringAuth: false // Force Basic Authentication as query string true and using under HTTPS
});

// List products
const products = await api.get("products", {
  per_page: 20, // 20 products per page
});
products.status; // 200
product.headers.get('x-wp-totalpages')
products.headers.get('x-wp-total')
products.headers.forEach((header) => {
  console.log(header);
});
products.data.forEach((product) => {
  console.log(product.name);
});

// Create a product
// See more in https://woocommerce.github.io/woocommerce-rest-api-docs/#product-properties
const data:ProductsMainParams = {
            name: "Premium Quality",
            type: "simple",
            regular_price: "21.99",
            description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
            short_description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
            categories: [
                {
                    id: 9
                },
                {
                    id: 14
                }
            ],
            images: [
                {
                    src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg"
                },
                {
                    src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg"
                }
            ]
        };
const products = await api.post("products", data);
products.status; // 201
products.data; // { id: 11, ... }
products.headers.get('x-wp-totalpages')
products.headers.get('x-wp-total')

// Edit/Update a product
  const data:ProductsMainParams = {
      name: "Premium Quality Updated-" + randomstring.generate({length:4, capitalization:"uppercase", charset: "alphanumeric"}),
      type: "simple",
      regular_price: "30.22",
      description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.",
      short_description: "Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.",
      categories: [
          {
              id: 9
          },
          {
              id: 14
          }
      ],
      images: [
          {
              src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_front.jpg"
          },
          {
              src: "http://demo.woothemes.com/woocommerce/wp-content/uploads/sites/56/2013/06/T_2_back.jpg"
          }
      ]
  };
  const products = await api.put("products", data, {id: 11});
  products.status; // 201
  products.data; // { id: 11, ... }
  products.headers.get('x-wp-totalpages')
  products.headers.get('x-wp-total')

// Delete a product
const products = await wooCommerce.delete("products", {force: true}, {id: 11});
products.status; // 201
products.data; // { id: 11, ... }
products.headers.get('x-wp-totalpages')
products.headers.get('x-wp-total')

// Create a order
const data:OrdersMainParams = {
      payment_method: "bacs",
      payment_method_title: "Direct Bank Transfer",
      set_paid: true,
      billing: {
          first_name: `John ${Math.random()}`,
          last_name: "Doe",
          address_1: "969 Market",
          address_2: "",
          city: "San Francisco",
          state: "CA",
          postcode: "94103",
          country: "US",
          email: "[email protected]",
          phone: "85996859001",
          company: "WooCommerce"
      },
      shipping: {
          first_name: "John",
          last_name: "Doe",
          address_1: "969 Market",
          address_2: "",
          city: "San Francisco",
          state: "CA",
          postcode: "94103",
          country: "US",
          company: "WooCommerce"
      },
      line_items: [
          {
              product_id: 93,
              quantity: 2
          },
          {
              product_id: 22,
              variation_id: 23,
              quantity: 1
          }
      ],
      shipping_lines: [
          {
              method_id: "flat_rate",
              method_title: "Flat Rate",
              total: "10.00"
          }
      ]
  };
const order = await api.post("orders", data);
order.status; // 201
order.data; // { id: 11, ... }
order.headers.get('x-wp-totalpages')
order.headers.get('x-wp-total')

// Edit/Update a order
const data:OrdersMainParams = {
      payment_method: "bacs",
      payment_method_title: "Direct Bank Transfer",
      set_paid: true,
      billing: {
          first_name: `Yuri ${Math.random()}`,
          last_name: "Doe",
          address_1: "969 Market",
          address_2: "",
          city: "San Francisco",
      },
  };
const order = await api.put("orders", data, {id: 11});
order.status; // 201
order.data; // { id: 11, ... }
order.headers.get('x-wp-totalpages')
order.headers.get('x-wp-total')

// Delete a order
const order = await api.delete("orders", {force: true}, {id: 11});
order.status; // 201
order.data; // { id: 11, ... }
order.headers.get('x-wp-totalpages')
order.headers.get('x-wp-total')

Changelog

See changelog for details

Thanks / Credits / Bibliography

• snyk - Best Pratice Guide
• woocommerce
• dennismphil - Updates dependencies
• emojis
• eslint-for-typescript
• Yoni Goldberg’s - Tests
• Ben Awad - Generic Types
• Anthony Fu - Publish ESM and CJS in a single package
• Semantic Releases - egghead
• GH006 Protected Branch Update Failed - paulmowat
• swizec - jest-with-typescript

Contact

Atention If you email me, please use as a email subject, the name of the project, in this case: (WooCommerce TS Library) - INFO

| Name | Email | Mobile/Whatsapp | |-------|--------|---------| | Yuri Lima | [email protected] | +353 83 419.1605 |