@emporix/api-calls

@emporix/api-calls

Framework-agnostic TypeScript helpers for calling the Emporix REST API. The package wraps axios requests used by the Emporix Management Dashboard and can be reused in other Node.js or browser applications.

Install

npm install @emporix/api-calls

Quick start

Configure a shared axios client once, then call any exported API helper:

import { createApiClient, fetchBrands } from '@emporix/api-calls'

createApiClient({
  baseURL: 'https://api.emporix.io',
  getAccessToken: () => localStorage.getItem('accessToken'),
  getTenant: () => localStorage.getItem('tenant'),
})

const { values, totalRecords } = await fetchBrands({ page: 0, rows: 20 })

Obtain a service access token with the OAuth Service before calling protected endpoints. See Tokens and Scopes for authorization details.

Client configuration

Function	Description
createApiClient(config)	Creates axios with interceptors and registers it globally.
setApiClient(instance)	Registers a preconfigured axios instance.
getApiClient()	Returns the registered instance (throws if not configured).
resetApiClient()	Clears the singleton (tests only).

createApiClient automatically adds these headers to every request:

• Authorization: Bearer <token> (empty string when no token is available)
• Emporix-Tenant: <tenant> (only when a non-empty tenant is configured; otherwise the header is removed)
• Accept-Language: *
• Content-Language: *

Package layout

Path	Purpose
src/client/	Axios singleton (createApiClient, getApiClient, …)
src/calls/	One module per Emporix API service; each exports *Call functions
src/models/	Domain types shared across calls (e.g. Product, Category)
src/types/	Cross-cutting types and constants (errors, pagination helpers)
src/utils/	Internal helpers (formatting, query params); not all are re-exported

Import everything from the package entry point:

import {
  createApiClient,
  fetchProducts,
  ProductRow,
  ValidationError,
} from '@emporix/api-calls'

Do not deep-import from src/calls/… in consumers; only the root export is part of the public API.

Shared exports (non-call helpers)

Besides REST *Call functions, the package exports types and utilities used by multiple apps:

API error handling

Export	Description
ValidationError	Thrown when the API returns validation_violation (HTTP 400)
ErrorResponse	Standard Emporix error body (type, message, details)
FieldError	Single field validation error (field, message)
MultiStatusResponse	Bulk-operation result item (used by segments, custom instances, …)

Example — axios interceptor in a host app:

import {
  getApiClient,
  ValidationError,
  type ErrorResponse,
} from '@emporix/api-calls'
import type { AxiosError } from 'axios'

getApiClient().interceptors.response.use(
  (response) => response,
  (error: AxiosError<ErrorResponse>) => {
    if (
      error.response?.status === 400 &&
      error.response.data?.type === 'validation_violation'
    ) {
      return Promise.reject(new ValidationError(error.response.data.details))
    }
    return Promise.reject(error)
  }
)

Constants

Export	Value	Usage
ID_SORTING_ASCENDING	'id:ASC'	Default sort for category tree and similar list endpoints

Configuration keys

Management-dashboard configuration entries stored in the Configuration Service:

Export	Configuration key
KEY_EXT_APPS	md_extensibility_apps
KEY_NAVIGATION_NODES	md_navigation_nodes
KEY_PERSPECTIVES	md_perspectives

Related types: Config, TableConfig (table column visibility and mixin layout).

Product table view models

categoryProductRow.ts maps API Product / CategoryProduct entities to a ProductRow shape for data tables:

Export	Description
ProductRow	Table row type (id, name, code, price, image, mixins, …)
mapProductToProductRow	Maps a Product plus resolved price/currency
mapMissingProductToProductRow	Placeholder row when a referenced product no longer exists

formatCurrency inside the mapper defaults to locale 'en'. Pass a formatted price from the host app if you need i18n-aware display.

Product service extras

Export	Description
deleteProductWithForceCall	DELETE /product/{tenant}/products/{id}?force=true for forced deletion
triggerDynamicVariantRecalculationCall	POST /product/{tenant}/products/recalculate for dynamic variant jobs
DynamicVariantRecalculationResponse	Job list and skipped product IDs returned by recalculation

Management Dashboard integration

The Management Dashboard consumes this package as follows:

• Bootstrap — createApiClient() is called once at startup with VITE_API_URL, auth token, and tenant from app storage (src/api/bootstrap.ts).
• API calls and types — imported directly from @emporix/api-calls (no re-export layer in src/api/).
• React hooks — use*Api hooks in src/hooks/api/ wrap package calls with tenant context and UI-specific logic.

Host applications should configure the client once, then call exported helpers; framework-specific hooks stay in the host repo.

Emporix documentation

Official documentation lives on the Emporix Documentation Portal.

Getting started

Topic	Link
Documentation portal	developer.emporix.io
API overview	Emporix API introduction
API references hub	API Documentation
List of API services	List of API Services
Developer Portal	Developer Portal guide
Management Dashboard	Management Dashboard introduction
API base URL	https://api.emporix.io
API status	Emporix Status Page

Authentication and authorization

Topic	Link
Tokens and scopes	Tokens and Scopes
OAuth service access tokens	OAuth Tutorial
Customer authentication overview	Customer Authentication
Manage API keys	Manage API Keys

Standard practices

Many helpers in this package use Emporix pagination, filtering, and sorting conventions:

Topic	Link
Query parameter (q)	Standard Practices — Query parameter
Mixins	Standard Practices — Mixins

Package modules and API guides

Each file under src/calls/ maps to one or more Emporix API services. Use the guides below for endpoint details, required scopes, request/response schemas, and tutorials.

Package module	Emporix service	Documentation
ai.ts	AI Service	AI Tutorials
authAdapter.ts	Developer Portal / tenant auth	Developer Portal
automation.ts	Automation (newsletter)	Developer Portal
availability.ts	Availability Service	Availability Service
brands.ts	Brand Service	Brand Tutorial
carts.ts	Cart Service	Cart Tutorial
catalogs.ts	Catalog Service	Catalog Tutorial
categories.ts	Category Service	Category Tutorial
categoryProductRow.ts	(view-model helpers)	Used with Product Service data in tables; see Product Tutorial
configuration.ts	Configuration Service	Configuration Service Tutorial
countries.ts	Country Service	Country Tutorial
coupons.ts	Coupon Service	Coupon Tutorial
currencies.ts	Currency Service	Currency Tutorial
customEntities.ts, customInstances.ts, mixins.ts, schema.ts	Schema Service	Schema Tutorial
customerManagement.ts	Client Management Service	Customer Management Tutorial
customers.ts	Customer Service (tenant-managed)	Customer Service (Tenant Managed) Tutorial
delivery.ts, shipping.ts	Delivery & Shipping	Delivery and Shipping Tutorial
globalConfig.ts	Configuration Service	Configuration Service Tutorial
iam.ts	IAM Service	IAM Tutorial
invoice.ts	Invoice Service	Invoice Tutorial
labels.ts	Label Service	Label Service
mediaAssets.ts	Media Service	Media Tutorial
orders.ts	Order Service	Order Tutorial
paymentGateway.ts	Payment Gateway Service	Payment-gateway Service
picklists.ts	Pick-Pack Service	Pick-pack Service
priceLists.ts, priceModels.ts, prices.ts, prices_v2.ts	Price Service	Price Tutorials
products.ts, productsMedia.ts	Product Service	Product Tutorial. Includes force-delete and dynamic-variant recalculation.
quotes.ts	Quote Service	Quote Tutorial
returns.ts	Returns Service	Returns Tutorial
segments.ts	Customer Segments Service	Segments Tutorial
sepa.ts	SEPA Export Service	SEPA Export Service
sites.ts	Site-Settings Service	Site Settings Tutorial
statistics.ts	Dashboard analytics / IAM	IAM Tutorial
suppliers.ts	Supplier API	List of API Services
taxes.ts	Tax Service	Tax Service
units.ts	Unit-Handling Service	Unit Handling Tutorial
vendors.ts	Vendor Service	Vendor Tutorial
webhooks.ts	Webhook Service	Webhook Service
types/constants.ts, types/errors.ts	(shared types)	ID_SORTING_ASCENDING, ValidationError, ErrorResponse, FieldError, MultiStatusResponse

OpenAPI specifications for all services are listed on the List of API Services page and in the Emporix GitHub repository.

All public symbols are listed in src/index.ts and published in dist/index.d.ts.

Development

npm install
npm run lint
npm run typecheck
npm test
npm run build
npm run pack:verify

Publishing

Releases are published to npm automatically when a version tag is pushed to GitHub. The workflow is defined in .github/workflows/publish.yml.

One-time setup

Configure npm trusted publishing for @emporix/api-calls:

1. Sign in to npmjs.com with an account that can publish to the @emporix scope.
2. Open the package settings for @emporix/api-calls.
3. Add a trusted publisher:
   • Provider: GitHub Actions
   • Repository: emporix/emporix-api-calls
   • Workflow filename: publish.yml

No NPM_TOKEN GitHub secret is required when trusted publishing is configured.

Release checklist

Before tagging a release, make sure:

• Changes are merged to the default branch.
• version in package.json is bumped (follow semver).
• Local quality checks pass:

npm run lint
npm run typecheck
npm test
npm run build
npm run pack:verify

Publish a new version

1. Update the version in package.json, for example 0.2.0.
2. Commit the change:

git add package.json
git commit -m "chore: release v0.2.0"
git push origin main

1. Create and push a tag that matches the version exactly (prefix with v):

git tag v0.2.0
git push origin v0.2.0

Pushing the tag triggers the Publish to npm workflow.

What the workflow does

On every v* tag push, GitHub Actions:

1. Validates the tag format (v1.2.3 or v1.2.3-beta.1).
2. Checks that the tag matches package.json (tag v0.2.0 requires version 0.2.0).
3. Publishes to npm with npm publish (the prepublishOnly script runs lint, typecheck, clean, build, and test automatically).

Formatting is enforced by the CI workflow on pull requests and branch pushes.

Monitor progress under Actions in the GitHub repository. If publish fails, fix the reported issue, bump the version if needed, and push a new tag.

Verify the release

After the workflow succeeds:

npm view @emporix/api-calls version

Or install the published version in another project:

npm install @emporix/api-calls@latest

Dry run locally (optional)

To inspect the tarball without publishing:

npm run pack:verify
npm pack --dry-run

Common issues

Problem	Likely cause
Tag validation failed	Tag is not v{version} or does not match package.json.
Publish failed with 403	Trusted publishing is not configured for this repo/workflow.
Version already exists on npm	Bump package.json and create a new tag; npm versions cannot be overwritten.

CI

• ci.yml — runs on push/PR: format, lint, typecheck, test, build, npm pack --dry-run.
• publish.yml — runs on version tags (v*), publishes to npm.