woocommerce/packages/js/api
Adrian Moldovan 13ab9007f6
[testing workflows] Add workflow_call trigger in CI workflow - support daily and other types of runs (#47612)
* Add workflow_call event

* Add tests-daily-run.yml

* Remove workflow version

* Update input value

* Remove secrets from caller workflow

* Rename job

* Check context

* Check context

* Check workflow_call inputs

* Override github.event_name with inputs.trigger

* Fix input name

* Add config for daily e2e tests with Gutenberg

* Update env commands for Gutenberg run

* Add disableHpos env variable in ci-utils

* Revert the trigger to push

* Revert the env variable setting in ci-jobs

* Revert the env variable setting in ci-jobs

* Rebuild utils

* Update test env start command

* Define the Gutenberg Playwright project

* Use path relative to workspace root

* Update events for test projects

* Update events for test projects

* Add changelogs

* Remove the e2e tests with Gutenberg tests from daily runs

* Set the schedule and workflow_dispatch triggers

* Add --project default flag to only run the default tests in CI

* Renamed snapshots to match the new Playwright project name
2024-05-22 11:04:44 -07:00
..
changelog [testing workflows] Add workflow_call trigger in CI workflow - support daily and other types of runs (#47612) 2024-05-22 11:04:44 -07:00
src Fix no-use-before-define lint rule violation 2023-11-16 19:26:24 +08:00
.eslintignore Fix and consolidate linting across the monorepo (#35012) 2022-10-12 15:05:01 +13:00
.eslintrc.js fix: fixed all instances of no-use-before-define lint rule violations 2023-11-16 19:21:30 +08:00
CHANGELOG.md Update CHANGELOG.md 2021-12-20 11:51:43 -05:00
NEXT_CHANGELOG.md js packages next changelogs 2021-11-11 16:34:50 +13:00
README.md PR Review 2022-03-29 15:04:37 +01:00
composer.json bump php version in packages/js/*/composer.json (#42020) 2024-01-04 10:18:34 -04:00
composer.lock Update changelogger to 3.3.0 to support PR number capturing with merge (#36266) 2023-01-05 14:42:51 +05:30
jest.config.js Fix Jest Preset (#42707) 2023-12-12 09:58:13 -08:00
package.json [testing workflows] Add workflow_call trigger in CI workflow - support daily and other types of runs (#47612) 2024-05-22 11:04:44 -07:00
tsconfig.json Upgrade TypeScript to v5.1 (#39531) 2023-08-08 16:35:31 +12:00

README.md

WooCommerce API Client

An API client for interacting with WooCommerce installations that works both in the browser and in Node environments. Here are the current and planned features:

  • TypeScript Definitions *
  • Axios API Client with support for OAuth & basic auth
  • Partial support to Repositories, to simplify interaction with basic data types *
  • Service classes for common activities such as changing settings

* TypeScript Definitions and Repositories are currently only supported for Products, and partially supported for Orders.

Differences from @woocommerce/woocomerce-rest-api

WooCommerce has two API clients in JavaScript for interacting with a WooCommerce installation's RESTful API. This package, and the @woocommerce/woocomerce-rest-api package.

The main difference between them is the Repositories and the TypeScript definitions for the supported endpoints. When using Axios directly, as you can do with both libraries, you query the WooCommerce API in a raw object format, following the API documentation parameters. Comparatively, with the Repositories provided in this package, you have the parameters as properties of an object, which gives you the benefits of auto-complete and strict types, for instance.

Usage

npm install @woocommerce/api --save-dev

Depending on what you're intending to get out of the API client there are a few different ways of using it.

REST API

The simplest way to use the client is directly:

import { HTTPClientFactory } from '@woocommerce/api';

// You can create an API client using the client factory with pre-configured middleware for convenience.
let client = HTTPClientFactory.build( 'https://example.com' )
    .withBasicAuth( 'username', 'password' )
    .create();

// You can also create an API client configured for requests using OAuth.
client = HTTPClientFactory.build( 'https://example.com' )
    .withOAuth( 'consumer_secret', 'consumer_password' )
    .create();

// You can then use the client to make API requests.
client.get( '/wc/v3/products' ).then( ( response ) => {
  // Access the status code from the response.
  response.status;
  // Access the headers from the response.
  response.headers;
  // Access the data from the response, in this case, the products.
  response.data;
}, ( error ) => {
  // Handle errors that may have come up.
} );

Repositories

As a convenience utility we've created repositories for core data types that can simplify interacting with the API:

Parent/Base Repositories

  • SimpleProduct
  • ExternalProduct
  • GroupedProduct
  • VariableProduct
  • Coupon
  • Order
  • SettingsGroup

Child Repositories

  • ProductVariation
  • Setting

These repositories provide CRUD methods for ease-of-use:

import { HTTPClientFactory, SimpleProduct } from '@woocommerce/api';

// Prepare the HTTP client that will be consumed by the repository.
// This is necessary so that it can make requests to the REST API.
const httpClient = HTTPClientFactory.build( 'https://example.com' )
    .withBasicAuth( 'username', 'password' )
    .create();

const repository = SimpleProduct.restRepository( httpClient );

// The repository can now be used to create models.
const product = repository.create( { name: 'Simple Product', regularPrice: '9.99' } );

// The response will be one of the models with structured properties and TypeScript support.
product.id;

Repository Methods

The following methods are available on all repositories if the corresponding method is available on the API endpoint:

  • create( {...properties} ) - Create a single object of the model type
  • delete( objectId ) - Delete a single object of the model type
  • list( {...parameters} ) - Retrieve a list of the existing objects of that model type
  • read( objectId ) - Read a single object of the model type
  • update( objectId, {...properties} ) - Update a single object of the model type

Child Repositories

In child model repositories, each method requires the parentId as the first parameter:

import { HTTPClientFactory, VariableProduct, ProductVariation } from '@woocommerce/api';

const httpClient = HTTPClientFactory.build( 'https://example.com' )
    .withBasicAuth( 'username', 'password' )
    .withIndexPermalinks()
    .create();

const productRepository = VariableProduct.restRepository( httpClient );
const variationRepository = ProductVariation.restRepository( httpClient );

const product = await productRepository.create({
    "name": "Variable Product with Three Attributes",
    "defaultAttributes": [
    {
     "id": 0,
     "name": "Size",
     "option": "Medium"
    },
    {
     "id": 0,
     "name": "Colour",
     "option": "Blue"
    }
    ],
    "attributes": [
    {
     "id": 0,
     "name": "Colour",
     "isVisibleOnProductPage": true,
     "isForVariations": true,
     "options": [
       "Red",
       "Green",
       "Blue"
     ],
     "sortOrder": 0
    },
    {
     "id": 0,
     "name": "Size",
     "isVisibleOnProductPage": true,
     "isForVariations": true,
     "options": [
       "Small",
       "Medium",
       "Large"
     ],
     "sortOrder": 0
   }
  ]
});

const variation = await variationRepository.create( product.id, {
    "regularPrice": "19.99",
    "attributes": [
      {
        "name": "Size",
        "option": "Large"
      },
      {
        "name": "Colour",
        "option": "Red"
      }
    ]
});