Ecommerce Adapter SDK

TypeScript npm package for React ecommerce applications to integrate with headless microservices.

What this package does

• Fetches and caches bearer tokens from auth service
• Provides typed clients for customer, product, cart, and order domains
• Supports customer signup/login flows
• Handles token injection, timeout, and base header configuration

Supported services

• Auth service: https://localhost:3001
• Customer service: https://localhost:3002
• Product service: https://localhost:3003
• Cart service: https://localhost:3004
• Order service: https://localhost:3005

Installation

npm install @platform-x-shp/shp-adapter

Quick start

import { createEcommerceAdapter } from "@platform-x-shp/shp-adapter";

const adapter = createEcommerceAdapter({
  // Required — all five backend services are multi-tenant and reject any
  // request with no sitename/sitehost header. Sent as `sitename` on every
  // request this adapter makes.
  siteName: "KIWI",
  auth: {
    baseUrl: "https://localhost:3001",
    tokenPath: "/api/auth/token", // optional (default)
    username: "admin",
    password: "admin123"
  },
  customerService: {
    baseUrl: "https://localhost:3002",
    apiPrefix: "/api" // required for current customer service
  },
  productService: {
    baseUrl: "https://localhost:3003",
    apiPrefix: "/api" // required for current product service
  },
  cartService: {
    baseUrl: "https://localhost:3004",
    apiPrefix: "/api"
  },
  orderService: {
    baseUrl: "https://localhost:3005",
    apiPrefix: "/api"
  },
  request: {
    timeoutMs: 10000,
    headers: {
      "X-Client": "web-store"
    }
  },
  tokenRefreshSkewMs: 10000
});

async function bootstrap() {
  const [customers, products] = await Promise.all([
    adapter.listCustomers({ page: 1, limit: 20 }),
    adapter.listProducts({ page: 1, limit: 20 })
  ]);

  return { customers, products };
}

Configuration

interface AdapterConfig {
  siteName: string; // required — sent as the `sitename` header to all backend services
  auth: {
    baseUrl: string;
    username: string;
    password: string;
    tokenPath?: string; // default: /api/auth/token
  };
  customerService: {
    baseUrl: string;
    apiPrefix?: string;
  };
  productService: {
    baseUrl: string;
    apiPrefix?: string;
  };
  cartService?: {
    baseUrl: string;
    apiPrefix?: string;
  };
  orderService?: {
    baseUrl: string;
    apiPrefix?: string;
  };
  request?: {
    timeoutMs?: number;
    headers?: Record<string, string>;
  };
  tokenRefreshSkewMs?: number; // default: 10000
}

API surface

Auth token controls

• setAccessToken(accessToken) URL: local token override in SDK (no HTTP call)
• refreshAccessToken() URL: POST https://localhost:3001/api/auth/token

Auth service endpoints (backend reference)

• POST /api/auth/token URL: POST https://localhost:3001/api/auth/token Purpose: authenticate admin credentials and issue a JWT SDK support: refreshAccessToken()
• POST /api/auth/verify URL: POST https://localhost:3001/api/auth/verify Purpose: verify a JWT and return its payload SDK support: verifyAuthToken(payload)
• GET /api/auth/me URL: GET https://localhost:3001/api/auth/me Purpose: return authenticated principal from bearer token SDK support: getAuthPrincipal(accessToken)

Customer

• getCustomer(customerId) URL: GET https://localhost:3002/api/customers/{customerId}
• listCustomers(query) URL: GET https://localhost:3002/api/customers
• createCustomer(payload) URL: POST https://localhost:3002/api/customers
• updateCustomer(customerId, payload) URL: PUT https://localhost:3002/api/customers/{customerId}
• searchCustomers(searchTerm, limit?) URL: GET https://localhost:3002/api/customers/search?q={searchTerm}&limit={limit}
• getMyCustomerProfile() URL: GET https://localhost:3002/api/customers/me
• getCustomerOrders(customerId) URL: GET https://localhost:3002/api/customers/{customerId}/orders
• getCustomerAddresses(customerId) URL: GET https://localhost:3002/api/customers/{customerId}/addresses
• getCustomerAddressById(customerId, addressId) URL: GET https://localhost:3002/api/customers/{customerId}/addresses/{addressId}
• createCustomerAddress(customerId, payload) URL: POST https://localhost:3002/api/customers/{customerId}/addresses
• updateCustomerAddress(customerId, addressId, payload) URL: PUT https://localhost:3002/api/customers/{customerId}/addresses/{addressId}
• deleteCustomerAddress(customerId, addressId) URL: DELETE https://localhost:3002/api/customers/{customerId}/addresses/{addressId}
• setDefaultCustomerAddress(customerId, addressId) URL: PUT https://localhost:3002/api/customers/{customerId}/addresses/{addressId}/default

Customer auth

• customerSignup(payload) URL: POST https://localhost:3001/api/customers/signup
• customerLogin(payload) URL: POST https://localhost:3001/api/customers/login
• verifyAuthToken(payload) URL: POST https://localhost:3001/api/auth/verify
• getAuthPrincipal(accessToken) URL: GET https://localhost:3001/api/auth/me
• changeCustomerPassword(accessToken, payload) URL: POST https://localhost:3001/api/customers/password/change
• requestCustomerPasswordReset(payload) URL: POST https://localhost:3001/api/customers/password/reset/request
• confirmCustomerPasswordReset(payload) URL: POST https://localhost:3001/api/customers/password/reset/confirm

Cart

• createCart(payload) URL: POST https://localhost:3004/api/carts
• getCart(cartId) URL: GET https://localhost:3004/api/carts/{cartId}
• addCartLines(cartId, payload) URL: POST https://localhost:3004/api/carts/{cartId}/lines
• updateCartLines(cartId, payload) URL: PUT https://localhost:3004/api/carts/{cartId}/lines
• removeCartLines(cartId, payload) URL: DELETE https://localhost:3004/api/carts/{cartId}/lines
• updateCartBuyerIdentity(cartId, payload) URL: PUT https://localhost:3004/api/carts/{cartId}/buyer-identity
• updateCartAttributes(cartId, payload) URL: PUT https://localhost:3004/api/carts/{cartId}/attributes
• updateCartDiscountCodes(cartId, payload) URL: PUT https://localhost:3004/api/carts/{cartId}/discount-codes
• getCartCheckoutUrl(cartId) URL: GET https://localhost:3004/api/carts/{cartId}/checkout-url
• deleteCart(cartId) URL: DELETE https://localhost:3004/api/carts/{cartId}

Order

Requires a bearer token (same auth flow as Customer/Product). Configure orderService to enable.

• getOrder(orderId) URL: GET https://localhost:3005/api/orders/{orderId}
• listOrders(query) URL: GET https://localhost:3005/api/orders

Product

• getProduct(productId) URL: GET https://localhost:3003/api/products/{productId}
• listProducts(query) URL: GET https://localhost:3003/api/products
• searchProducts(searchTerm, query) URL: GET https://localhost:3003/api/products/search?q={searchTerm}
• getProductByHandle(handle) URL: GET https://localhost:3003/api/products/handle/{handle}
• getProductVariants(productId) URL: GET https://localhost:3003/api/products/{productId}/variants
• getProductInventory(productId) URL: GET https://localhost:3003/api/products/{productId}/inventory
• getProductMedia(productId) URL: GET https://localhost:3003/api/products/{productId}/media
• getProductRecommendations(productId) URL: GET https://localhost:3003/api/products/{productId}/recommendations
• getVariantById(variantId) URL: GET https://localhost:3003/api/variants/{variantId}
• getVariantInventory(variantId) URL: GET https://localhost:3003/api/variants/{variantId}/inventory
• getProductFilters() URL: GET https://localhost:3003/api/products/filters
• getProductTags() URL: GET https://localhost:3003/api/products/tags
• getProductTypes() URL: GET https://localhost:3003/api/products/types
• getProductVendors() URL: GET https://localhost:3003/api/products/vendors
• filterProducts(query) URL: GET https://localhost:3003/api/products/filter
• getCollections() URL: GET https://localhost:3003/api/collections
• getCollectionById(collectionId) URL: GET https://localhost:3003/api/collections/{collectionId}
• getCollectionProducts(collectionId) URL: GET https://localhost:3003/api/collections/{collectionId}/products

All product methods support an optional second argument:

{ requiresAuth?: boolean }

Use requiresAuth: false to skip automatic bearer token injection for that call.

Example calls

// Customer auth
await adapter.customerSignup({
  firstName: "Alex",
  lastName: "Doe",
  email: "[email protected]",
  phone: "+1-555-123-4567",
  password: "StrongPassword123"
});

const login = await adapter.customerLogin({
  email: "[email protected]",
  password: "StrongPassword123"
});

adapter.setAccessToken(login.token);

// Product lookup by handle
const product = await adapter.getProductByHandle("classic-white-tee");

// Product lookup without attaching bearer auth
const publicCatalog = await adapter.listProducts(
  { page: 1, limit: 12 },
  { requiresAuth: false }
);

// Order lookup (requires orderService to be configured)
const order = await adapter.getOrder("gid://shopify/Order/123456789");

Error handling

The adapter throws EcommerceAdapterError for HTTP failures and token parsing issues.

import { EcommerceAdapterError } from "@platform-x-shp/shp-adapter";

try {
  await adapter.listProducts({ page: 1, limit: 10 });
} catch (error) {
  if (error instanceof EcommerceAdapterError) {
    console.error(error.message, error.statusCode, error.service, error.details);
  }
}

Development

npm install
npm run build

Available scripts:

• npm run build - compile TypeScript to dist
• npm run clean - remove dist
• npm run prepare - build before publish/install from git

Notes

• Auth token path defaults to /api/auth/token.
• apiPrefix is optional per service and is prepended to all request paths. Customer, product, cart, and order services currently all mount their routes under /api, so set apiPrefix: "/api" for each.
• Customer-service currently returns wrapped payloads such as { success, data, count }; this SDK normalizes those responses to adapter-friendly return types.
• This SDK wraps admin-token fetch plus customer-auth flows including verify, me, and password lifecycle endpoints.
• Cart-service and order-service return wrapped payloads such as { success, data, count }; configure cartService/orderService to use those APIs.
• publishNotification is implemented in the adapter's mapping layer but always rejects with ProviderUnavailableError: shp-notification is queue-only (RabbitMQ) with no HTTP transport, so there is no endpoint for the adapter to call yet.