headless-js-api

@lightspeed/headless-js-api

@lightspeed/headless-js-api is a client-side JavaScript/TypeScript library for interacting with the Ecwid resources. It provides a strongly-typed, modern interface to access store data and trigger UI functionalities within third-party applications, themes, or custom integrations.

This library is designed for both browser and Node.js environments.

Key Features

• TypeScript First: Strong typing for a better developer experience.
• npm Package: Easy to integrate via @lightspeed/headless-js-api.
• Read-Only Data Access: Securely access Products, Categories, Store Profile, etc.
• Modern JS: ESM, tree-shakable, using axios for HTTP requests.
• Cross-Platform: Works in modern browsers and Node.js.

Installation

yarn add @lightspeed/headless-js-api

Usage

Here's a base example of how to initialize the API client and retrieve a store profile:

import { initStorefrontApi, getStoreProfile, GetStoreProfileResponse } from '@lightspeed/headless-js-api/api';
import { getStoreId } from '@lightspeed/headless-js-api/storefront';

initStorefrontApi({
  publicToken: 'YOUR_PUBLIC_TOKEN',
  storeId: 'YOUR_STORE_ID',
  baseURL: 'https://app.ecwid.com/api/v3/'
});

const storeId = await getStoreId();
const response: GetStoreProfileResponse = await getStoreProfile({ storeId });

API Overview

This library provides a client-side interface for a subset of the functionalities available in the Ecwid REST API. For a complete list of all available backend API endpoints and their detailed documentation, refer to the official Ecwid API Reference.

The underlying HTTP client is axios. The library focuses on fetching fresh data and does not implement persistent caching.

Key Exports and Functionalities

• Configuration:
  • getApiConfig(): ApiConfig – Retrieves or sets the current API configuration.
• Products:
  • searchProducts(params?: SearchProductsParams): Promise<SearchProductsResponse> – Searches for products based on various criteria.
  • getProduct(params: GetProductParams): Promise<GetProductResponse> – Fetches a single product by its ID.
  • (Other product-related methods are available and exported from src/api/products/ as implemented.)
• Shared Types:
  • PaginatedResponse<T> – Generic type for API responses that include pagination details.
  • SearchParams – Basic type for search parameter objects.
  • SortBy – Enum for available product sort orders.
  • All product-specific types under Product, ProductAttribute, etc., are available and exported from src/api/products/types/.

(The list of available methods will expand as more API endpoints are implemented and exported from the root index.ts file.)

Request Handling

Each call to an API method will result in a new HTTP request. The library does not implement request deduplication or persistent caching.

Error Handling

Methods that return Promises will reject in case of errors (e.g., network issues, invalid parameters, API errors from the backend). Errors will typically be instances of Error or a custom error type derived from it, containing relevant information about the failure. Use try...catch blocks for asynchronous operations.

Security

All API methods provided by this library are public and read-only. Access requires a valid public token, which is used to authenticate requests. The library does not handle or store authentication tokens beyond what is required for public API access. All data transmission is performed over HTTPS.

Platform Compatibility

• Browsers: Designed for and tested in modern web browser environments (e.g., latest versions of Chrome, Firefox, Safari, Edge).
• Node.js: Suitable for use in Node.js environments for server-side interactions or scripting. axios provides HTTP request capabilities in Node.js.

Versioning & Changelog

This library adheres to Semantic Versioning (SemVer). A CHANGELOG.md file is maintained in the package root to document changes, additions, and fixes for each version.