@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 axios

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

3. 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.