tampl-ecommerce-sdk

Framework-agnostic npm package for wrapping Tampl ecommerce API services.

This package exposes a public SDK shape plus a thin API-call layer. Service methods call endpoints with fetch and return the response body directly; they do not transform, normalize, or otherwise treat response data.

The SDK is designed for modern ESM runtimes that provide fetch, including browsers, Node 18+, Next.js, Vite, Remix, Astro, SvelteKit, Bun, Deno, Workers, and similar fetch-compatible environments.

Install

npm install @tampl-io/tampl-ecommerce-sdk

Usage

The root package is the universal entrypoint. It does not import Node-only APIs, React, Next.js, or framework adapters, so it can be used from browser or server code in any modern ESM runtime.

import { createTamplEcommerceSdk } from '@tampl-io/tampl-ecommerce-sdk';

const tampl = await createTamplEcommerceSdk({
  apiKey: process.env.TAMPL_API_KEY,
  bookingApiKey: process.env.TAMPL_BOOKING_API_KEY,
  marketplaceId: 'marketplace_123',
  paymentApiKey: process.env.TAMPL_PAYMENT_API_KEY,
  searchApiKey: process.env.TAMPL_SEARCH_API_KEY,
});

await tampl.payment.createPaymentIntent({
  amount: 1000,
  currency: 'USD',
  description: 'Cart cart_123',
  solution_id: 'solution_123',
  metadata: { cartId: 'cart_123' },
});

The SDK routes calls to Tampl's built-in service URLs, so applications do not need to pass baseUrl or serviceBaseUrls during initialization:

| SDK service | Built-in API URL | | --- | --- | | catalog | https://mbv-ecommerce-catalog-api-stag.herokuapp.com | | nomenclature | https://mbv-common-nomenclature-stagin.herokuapp.com | | customers (account routes) | https://mbv-common-account-api-stag.herokuapp.com | | carts, ordering | https://mbv-ecommerce-order-api-acbaac3885e6.herokuapp.com | | payment | https://mbv-ecommerce-pay-api-3ca66d3f4ffc.herokuapp.com | | marketplaces | https://mbv-ecommerce-branding-api.herokuapp.com | | search | https://mbv-common-search-api-732016afef66.herokuapp.com | | booking | https://tamp-booking-api-staging-f56961764926.herokuapp.com | | content | https://mbv-ecommerce-content-api-6699d0a9a77b.herokuapp.com | | shipping | https://mbv-ecommerce-shipping-api-68a94270e529.herokuapp.com |

The URL constants and frozen DEFAULT_SERVICE_BASE_URLS map are exported from the package. Explicit baseUrl and serviceBaseUrls values still override the defaults for tests and custom deployments.

The SDK uses optional generic bearer apiKey credentials and global fetch by default. Payment, search, and booking operations additionally require paymentApiKey, searchApiKey, and bookingApiKey respectively; the SDK sends each key only to its matching service as the protected x-api-key header. Keep these keys in server-only code or behind an application-owned proxy. You can pass a custom fetch implementation for tests or specialized runtimes.

Per-request fetch options

Every service and direct API method accepts the configured fetcher's request-init options in its existing options argument. The SDK forwards these fields without interpreting them, so framework and runtime extensions remain available without adding a framework dependency.

In Next.js, the default globalThis.fetch type includes the framework's cache configuration:

import { createServerTamplEcommerceSdk } from '@tampl-io/tampl-ecommerce-sdk/server';

const tampl = await createServerTamplEcommerceSdk();

const products = await tampl.catalog.listProducts(
  { page: 1, size: 12 },
  {
    cache: 'force-cache',
    next: {
      revalidate: 300,
      tags: ['products'],
    },
  },
);

When a custom fetcher is configured, its second parameter determines the available request options automatically:

import {
  createTamplEcommerceSdk,
  type FetchLike,
} from '@tampl-io/tampl-ecommerce-sdk';

interface TracedRequestInit extends RequestInit {
  trace?: { requestId: string };
}

const tracedFetch: FetchLike<TracedRequestInit> = async (input, init) => {
  const { trace, ...requestInit } = init ?? {};
  recordRequestTrace(trace);
  return fetch(input, requestInit);
};

const tampl = await createTamplEcommerceSdk({
  fetch: tracedFetch,
});

await tampl.catalog.listProducts({}, {
  trace: { requestId: 'request_123' },
});

The exported FetchRequestInit<TFetcher> utility exposes the derived second-argument type. Endpoint methods and bodies remain SDK-owned and cannot be overridden through service request options. Caller headers accept any HeadersInit value and are normalized before the SDK applies its authorization, idempotency, and marketplace-header rules.

Marketplace discovery

The read-only marketplaces service provides marketplace, store, configuration, timeslot, slug, and template data. It preserves the upstream API's route and snake_case wire contracts while using capability-focused SDK naming.

createTamplEcommerceSdk is asynchronous. When marketplaceId is configured, initialization fetches /market-place-config/by-marketplace/:id and exposes the returned configuration on the client.

const marketplaceId = 'marketplace_123';
const tampl = await createTamplEcommerceSdk({
  marketplaceId,
});

const [marketplace, stores] = await Promise.all([
  tampl.marketplaces.getMarketplace(marketplaceId),
  tampl.marketplaces.listStores({
    market_place_external_id: marketplaceId,
    active: true,
  }),
]);

console.log(tampl.marketplaceConfiguration?.dns);

The same functions are available through @tampl-io/tampl-ecommerce-sdk/marketplaces and the lower-level @tampl-io/tampl-ecommerce-sdk/api/marketplaces module. IDs and marketplace filters remain explicit and are never replaced with config.marketplaceId.

The fetched configuration is available as sdk.marketplaceConfiguration. When it includes a non-empty dns, that value is also stored under the active marketplace ID in sdk.config.marketplaceDomains as metadata. Missing DNS values do not prevent initialization.

Marketplace and store administration, organizations, franchise demands, device tokens, bulk operations, and test-only timeslot routes are intentionally outside this storefront-oriented surface. Secret marketplace configuration retrieval is also excluded.

Storefront content

The marketplace-bound content service reads legal pages, menus, topics, articles, FAQs, article-home selections, homepages, search-page settings, registration pages, and onboarding pages from tampl-ecommerce-content-api. It also submits customer support forms.

const tampl = await createTamplEcommerceSdk({
  marketplaceId: 'marketplace_123',
});

const [homepage, menu, terms] = await Promise.all([
  tampl.content.listHomePages({ category: 'marketplace' }),
  tampl.content.listMenus({ page: 1 }),
  tampl.content.getLegalPage('terms-and-conditions'),
]);

await tampl.content.createSupport({
  email: '[email protected]',
  topic: 'Order assistance',
  content: 'I need help with my order.',
});

List operations, article and FAQ slug lookups, legal-page lookups, and support submissions require marketplaceId. The SDK injects it using each route's exact backend field (marketplace_external_id, market_place_external_id, related_external_id, or related_id) and does not allow a call-level override. Direct ID getters whose routes do not accept marketplace scope remain available without it.

The same service helpers are exported from @tampl-io/tampl-ecommerce-sdk/content; low-level functions with explicit wire queries are available from @tampl-io/tampl-ecommerce-sdk/api/content. CMS create/update/delete operations, support-ticket administration, /initialize-marketplace/:id, and /clone are intentionally excluded from the storefront SDK.

Localized country options

The initialized SDK can build country options for forms and selectors. Each value is the official English country name, while displayName uses the explicitly selected language. When no language is passed, the SDK uses the marketplace's default_language, then English.

const tampl = await createTamplEcommerceSdk({
  marketplaceId: 'marketplace_123',
});

const countries = tampl.getCountries('fr-FR');
const germany = countries.find(country => country.value === 'Germany');

console.log(germany);
// { value: 'Germany', displayName: 'Allemagne' }

Marketplace host validation

Each marketplace frontend should pass the marketplace ID from its own environment/config system. The SDK does not read process.env, import.meta.env, or framework-specific globals directly.

Storefront DNS validation is currently disabled in every environment. Initialization and API calls do not require a storefront host, inspect marketplaceDomains, or invoke hostDomainResolver. The environment, hostDomain, hostDomainResolver, and marketplaceDomains config fields remain available for compatibility but do not restrict requests.

import { createTamplEcommerceSdk } from '@tampl-io/tampl-ecommerce-sdk';

const marketplaceId = process.env.TAMPL_MARKETPLACE_ID;

const tampl = await createTamplEcommerceSdk({
  marketplaceId,
});

The exported isHostDomainAllowedForMarketplace and deprecated isUrlAllowedForMarketplace compatibility helpers always return true. Their assertion counterparts are no-ops while validation remains disabled.

If your backend expects the marketplace ID on every request, set marketplaceHeaderName to the header your API supports:

const tampl = await createTamplEcommerceSdk({
  marketplaceId: 'marketplace_a',
  marketplaceHeaderName: 'X-Marketplace-Id',
});

Customer, payment, and shipping calls default to the x-marketplace-id header expected by their Tampl APIs. A configured marketplaceHeaderName replaces that default, and the SDK always sends the configured marketplaceId rather than a call-level override.

Cart and ordering services also require marketplaceId. They use the order API's wire contract rather than a framework or session convention: cart creation and order listings receive marketplace_external_id, while cart and user-cart lookups receive marketplace_id. Service methods always replace caller-supplied marketplace values with SDK configuration.

The booking service also requires marketplaceId. It supplies the booking API's exact market_place_external_id field for calendars, booking configurations, reservations, quotation forms, and quotations, while reservation messages use the backend's separate marketplace_external_id spelling.

Catalog and nomenclature

The public catalog service unites product catalog data from tampl-ecommerce-catalog-api with shared classification and location data from tampl-common-nomenclature-api. Consumers keep one sdk.catalog namespace and one pair of import paths even when the backends are deployed separately.

const tampl = await createTamplEcommerceSdk();

const [products, brands, categories] = await Promise.all([
  tampl.catalog.listProducts({ page: 1, size: 12 }),
  tampl.catalog.listBrands({ marketplace_external_id: 'marketplace_123' }),
  tampl.catalog.listProductCategories({
    marketplace_external_id: 'marketplace_123',
    pagination: true,
  }),
]);

const suggestions = await tampl.catalog.suggestLocations({ keyword: 'tunis' });

The nomenclature-backed surface includes CRUD calls for brands, product categories, marketplace sectors, and dynamic zones; location suggestions; location list, lookup, create, bulk-create, update, and delete calls. Methods preserve the API's exact snake_case and camelCase wire fields, update-mask names, HTTP methods, and response objects. The operational location seed route /admin/locations/all-locations is intentionally excluded.

These methods are also available through @tampl-io/tampl-ecommerce-sdk/catalog and @tampl-io/tampl-ecommerce-sdk/api/catalog. Nomenclature-backed methods use the built-in nomenclature URL; product and inventory methods use the built-in catalog URL.

Customer accounts

The customer service implements the storefront account flows from tampl-common-account-api: registration, confirmation, confirmation resend, customer login, password reset, and current-customer profile reads and updates. It also exposes customer-owned wishlist CRUD operations; those routes are hosted by tampl-ecommerce-order-api and therefore use the ordering service URL.

const marketplaceId = getMarketplaceIdFromAppConfig();

const tampl = await createTamplEcommerceSdk({
  marketplaceId,
});

const session = await tampl.customers.loginCustomer({
  login: '[email protected]',
  password: 'customer-password',
});

const customer = await tampl.customers.getCurrentCustomer({
  accessToken: session.token,
});

registerCustomer injects type: "customer" and the configured marketplace ID into the account API payload. The SDK returns login and registration data without storing tokens, cookies, or session state. For authenticated profile calls, pass accessToken per request or provide an explicit Authorization header; an explicit header takes precedence.

await tampl.customers.registerCustomer({
  user: {
    email: '[email protected]',
    firstName: 'Ada',
    lastName: 'Lovelace',
  },
  password: 'customer-password',
});

Wishlist payloads preserve the order API's snake_case wire format. The customer identifier is explicit because the SDK does not decode or retain customer identity from access tokens.

const customerExternalId = getCustomerExternalIdFromSession();

const wishlist = await tampl.customers.createWishlist({
  user_external_id: customerExternalId,
  title: 'Favorites',
  target_type: 'product',
  target_external_id: 'product_123',
}, {
  accessToken: session.token,
});

const wishlists = await tampl.customers.listWishlists({
  user_external_id: customerExternalId,
  page: 1,
  size: 10,
});

await tampl.customers.updateWishlist(wishlist.external_id, {
  wishlist: { title: 'Top picks' },
  update_masks: ['title'],
}, {
  accessToken: session.token,
});

Storefront search

The search service mirrors the storefront routes from tampl-common-search-api: product, package, and store search plus marketplace-scoped suggestions. It returns the backend's products, packages, stores, metas, and facets fields directly without converting packages into products or otherwise normalizing results.

import { createServerTamplEcommerceSdk } from '@tampl-io/tampl-ecommerce-sdk/server';

const tampl = await createServerTamplEcommerceSdk({
  marketplaceId: process.env.TAMPL_MARKETPLACE_ID,
  searchApiKey: process.env.TAMPL_SEARCH_API_KEY,
});

const products = await tampl.search.searchProducts({
  query: 'laptop',
  page: 1,
  pageSize: 20,
  filters: {
    'brand_info.name': ['Tampl'],
  },
  rangeFilters: {
    price: { min: '500', max: '2000' },
  },
  sortBy: '-price',
});

const suggestions = await tampl.search.suggest('lap');

Search service methods require marketplaceId. The SDK overwrites filters["market_places.external_id"] for product and package searches, marketplace_id for store searches, and the suggestion route's marketplaceID query value with the configured marketplace. Lower-level functions remain available through @tampl-io/tampl-ecommerce-sdk/api/search, while direct scoped methods are exported from @tampl-io/tampl-ecommerce-sdk/search.

Search API keys are server credentials and should not be exposed in browser bundles. Health checks and destructive index-management routes are intentionally outside the storefront SDK surface.

Carts and orders

The cart service implements the storefront flow exposed by tampl-ecommerce-order-api. Orders are created when a paid cart is submitted; there is no direct createOrder endpoint.

import { createTamplEcommerceSdk } from '@tampl-io/tampl-ecommerce-sdk';

const marketplaceId = process.env.TAMPL_MARKETPLACE_ID!;
const tampl = await createTamplEcommerceSdk({
  marketplaceId,
});

const cart = await tampl.carts.createCart({
  customer: 'customer_123',
  currency: 'EUR',
  session_id: 'storefront-session-123',
});

await tampl.carts.addCartLineItem(cart.external_id!, {
  quantity: 1,
  type: 'product',
  product: { external_id: 'product_123' },
  store_external_id: 'store_123',
});

const completedCart = await tampl.carts.submitCart(cart.external_id!, {
  remote_id: 'payment_123',
  amount: 49.9,
  currency_code: 'EUR',
  status: 'success',
});

const orders = await tampl.ordering.listOrders({
  cart_id: completedCart.external_id,
  customer_id: 'customer_123',
});

Cart mutation payloads and order updates use the backend's update_masks contract. Coupons are encoded as form data internally because the order API reads them with PostForm. All responses are returned without normalization, and request options such as accessToken, cache, next, and signal remain available.

await tampl.ordering.updateOrder('order_123', {
  order: { status: 'cancelled' },
  update_masks: ['status'],
}, {
  accessToken: customerAccessToken,
  cache: 'no-store',
});

Payments

The payment service mirrors the marketplace-commerce routes from tampl-ecommerce-pay-api. It creates checkout sessions and payment intents, retrieves payment intents and payout records, discovers payment solutions, reads marketplace solution configuration, and refunds an order. The SDK removes the fictional capture and cancel operations because the backend exposes neither route.

const paymentIntent = await tampl.payment.createPaymentIntent({
  amount: 49.9,
  currency: 'EUR',
  description: 'Cart cart_123',
  solution_id: 'solution_123',
  metadata: {
    cartId: 'cart_123',
    email: '[email protected]',
    firstname: 'Ada',
    lastname: 'Lovelace',
  },
});

const refreshedIntent = await tampl.payment.getPaymentIntent(
  paymentIntent.id,
  'solution_123',
  { cache: 'no-store' },
);

await tampl.payment.refundPayment('order_123');

The service injects the configured marketplace into checkout-session, payment-intent, marketplace-history, solution-config, and refund operations. getPaymentIntent sends its solution ID through the backend's required x-solution-id header. Payment-solution config responses can contain private provider credentials; call config-read methods only from trusted server code and never serialize their results into browser props.

Shipping

The shipping service mirrors the shipping-method and parcel routes from tampl-ecommerce-shipping-api. It supports marketplace-scoped method discovery, address validation, cart-specific method calculation, Sendcloud lookups, parcel creation and retrieval, active-parcel lookup, tracking fields, updates, and cancellation.

const available = await tampl.shipping.listShippingMethods({
  store_external_id: 'store_123',
  enabled: true,
});

const methodsForCart = await tampl.shipping.getOrderShippingMethods(cart, {
  global: false,
});

const parcel = await tampl.shipping.getOrderActiveShippingParcel('order_123', {
  cache: 'no-store',
});

console.log(parcel.tracking_number, parcel.tracking_url);

The service overrides marketplace_external_id when listing methods and when sending a cart to /order_shipping_methods. Provider credential management, inbound webhooks, hard deletes, and shipping-service administration are intentionally not part of this frontend-oriented surface.

Booking

The booking service mirrors the storefront workflows from tampl-ecommerce-booking-api. It provides calendar and policy discovery, reservation creation and status updates, reservation conversations, quotation-form discovery, and quotation submission and updates.

import { createServerTamplEcommerceSdk } from '@tampl-io/tampl-ecommerce-sdk/server';

const tampl = await createServerTamplEcommerceSdk({
  bookingApiKey: process.env.TAMPL_BOOKING_API_KEY,
  marketplaceId: process.env.TAMPL_MARKETPLACE_ID,
});

const calendars = await tampl.booking.listCalendars({
  product_external_id: 'product_123',
  date: '2026-08-01',
});

const reservation = await tampl.booking.createReservation({
  vendor_external_id: 'store_123',
  product_external_id: 'product_123',
  reservation_start: { year: 2026, month: 8, day: 1, hour: 10, minute: 0 },
  reservation_end: { year: 2026, month: 8, day: 1, hour: 11, minute: 0 },
  reservation_by: {
    external_id: 'customer_123',
    email: '[email protected]',
  },
  reservation_type: 'service',
});

await tampl.booking.updateReservation(reservation.external_id!, {
  reservation: { reservation_status: 'cancelled_by_customer' },
  update_masks: ['reservation_status'],
});

listReservationMessages({ original_message: true }) returns messages enriched with their customer snapshot; omitting the flag or setting it to false returns ordinary reservation messages. All payloads and responses preserve the API's snake_case wire shape and are returned without normalization.

The same methods are available from @tampl-io/tampl-ecommerce-sdk/booking and the lower-level @tampl-io/tampl-ecommerce-sdk/api/booking module. The low-level functions preserve explicit marketplace fields; the high-level service always replaces them with the configured marketplace. Calendar writes, booking-configuration writes, quotation-form writes, and all delete routes are intentionally excluded. Cancellation uses updateReservation with reservation_status.

For explicit runtime boundaries, import from the browser or server entry points. These are convenience exports for frameworks that separate client and server bundles; they do not add a framework dependency.

'use client';

import { createBrowserTamplEcommerceSdk } from '@tampl-io/tampl-ecommerce-sdk/browser';

const appMarketplaceId = getMarketplaceIdFromAppConfig();

const tampl = await createBrowserTamplEcommerceSdk({
  baseUrl: '/api/tampl',
  marketplaceId: appMarketplaceId,
});

import { createServerTamplEcommerceSdk } from '@tampl-io/tampl-ecommerce-sdk/server';

const tampl = await createServerTamplEcommerceSdk({
  apiKey: process.env.TAMPL_API_KEY,
  bookingApiKey: process.env.TAMPL_BOOKING_API_KEY,
  paymentApiKey: process.env.TAMPL_PAYMENT_API_KEY,
});

Direct domain imports are also available:

import { listOrders } from '@tampl-io/tampl-ecommerce-sdk/ordering';

await listOrders({ customer_id: 'customer_123' }, {
  clientConfig: {
    apiKey: process.env.TAMPL_API_KEY,
    marketplaceId: 'marketplace_123',
  },
});

Direct service/API imports are lower-level calls and do not run the asynchronous client initializer. Marketplace-scoped direct calls must therefore receive a clientConfig; prefer await createTamplEcommerceSdk(...) for application clients.

Lower-level API functions are available from the api subpath:

import { payment } from '@tampl-io/tampl-ecommerce-sdk/api';

const data = await payment.createPaymentIntent({
  apiKey: process.env.TAMPL_API_KEY,
  marketplaceId: 'marketplace_123',
  paymentApiKey: process.env.TAMPL_PAYMENT_API_KEY,
}, {
  amount: 1000,
  currency: 'USD',
  description: 'Cart cart_123',
  marketplace_id: 'marketplace_123',
  solution_id: 'solution_123',
  metadata: { cartId: 'cart_123' },
});

Structure

src/
  client.js
  errors.js
  browser.js
  server.js
  index.js
  api/
    booking-types.d.ts
    booking.js
    content-types.d.ts
    content.js
    carts.js
    catalog.js
    catalog-types.d.ts
    customer-types.d.ts
    customers.js
    marketplace-types.d.ts
    marketplaces.js
    order-types.d.ts
    ordering.js
    payment-types.d.ts
    payment.js
    search-types.d.ts
    search.js
    request.js
    shipping-types.d.ts
    shipping.js
  services/
    booking.js
    content.js
    carts.js
    catalog.js
    customers.js
    marketplaces.js
    ordering.js
    payment.js
    search.js
    shipping.js
tests/
  booking.test.js
  content.test.js
  carts-ordering.test.js
  customers.test.js
  exports.test.js
  marketplaces.test.js
  payment.test.js
  search.test.js
  shipping.test.js

Current service surfaces

• payment: checkout sessions, payment intents, payout reads, payment-solution discovery and config reads, and order refunds.
• ordering: fetch, list, and update orders created by cart submission.
• catalog: products and merchandising data from the catalog API, plus brands, product categories, marketplace sectors, dynamic zones, and locations from the nomenclature API.
• customers: register, confirm, resend confirmation, log in, reset passwords, read or update the current customer profile, and manage customer wishlists.
• carts: create and update carts, manage user carts and line items, apply coupons, select shipping and delivery options, verify checkout, and submit paid carts.
• shipping: marketplace methods, address validation, order-specific methods, Sendcloud lookups, and parcel lifecycle operations.
• marketplaces: read-only marketplace and store discovery, public configurations, store slugs, delivery/pickup timeslots, and marketplace templates.
• search: marketplace-scoped product, package, and store search plus suggestions.
• booking: marketplace-scoped calendar/config discovery plus reservation, message, and quotation create/read/list/update workflows.
• content: marketplace-scoped storefront content reads plus customer support submission.

Framework compatibility

• The package is ESM-only and targets modern fetch runtimes. CommonJS require() support is intentionally out of scope for now.
• The root export is the framework-neutral SDK entrypoint.
• @tampl-io/tampl-ecommerce-sdk/browser includes a "use client" directive so it works cleanly in React Server Component environments such as Next.js App Router.
• @tampl-io/tampl-ecommerce-sdk/server is a server-runtime convenience entrypoint for server components, handlers, actions, jobs, or API layers in any framework.
• Runtime modules avoid Node built-ins, framework request/response objects, cookies, sessions, and other framework-specific globals.
• Keep secrets such as API keys in server-only code. Browser code should use public configuration or call your own backend/API route.
• Storefront DNS validation is currently disabled; enforce any required host authorization in your application or backend.

API call layer

• src/api/request.js contains the generic callApi helper.
• src/api/* contains endpoint functions grouped by ecommerce domain.
• API functions only compose the URL, method, headers, query string, and body, then return JSON or text from the response.
• Request options forward the configured fetcher's remaining init fields, including standard options, Next.js cache metadata, and custom fetcher extensions.
• SDK-only metadata is removed before the fetch call, while endpoint methods and bodies remain protected.
• Non-JSON responses are returned as text; 204 No Content returns null.
• HTTP error payloads are returned the same way as successful payloads for now. Error mapping can be added later without changing the service surface.

The catalog service mirrors route groups from two backends. tampl-ecommerce-catalog-api supplies /products, /collections, /seo-listing, /inventories, /suppliers, /packages, /channels, /attributes, /attribute-groups, /places, and /tags. tampl-common-nomenclature-api supplies /brands, /product-categories, /market-place-sector, /dynamic-zones, /suggest, and the supported /admin/locations routes. The SDK routes each group to its built-in API URL.

The customer API calls mirror the storefront routes from tampl-common-account-api: /account/signup, /account/confirm, /account/resend-confirm, /account/customer/login, /account/reset-password/init, /account/reset-password/confirm, and /account/customer/me. Customer-owned wishlist methods mirror the POST, retrieve, list, update, and delete routes under /wishlists from tampl-ecommerce-order-api, and resolve through serviceBaseUrls.ordering.

The payment calls mirror the marketplace-commerce routes from tampl-ecommerce-pay-api: /checkout-sessions, /payment-intents, /payments, /payment-solutions, and /refund. Webhooks, Tampl-plan billing, Stripe Connect administration, provider catalog/subscription management, and payout-generation maintenance are outside this SDK surface.

The shipping calls mirror the marketplace method and parcel routes from tampl-ecommerce-shipping-api: /shipping_methods, /order_shipping_methods, /sendcloud, /orders/:order_id, and /shipping_parcels. Inbound webhooks and provider credential/configuration administration remain server-owned API concerns.

The marketplace discovery calls mirror /market-place, /market-place-config, /store, /storeConfig, and /templates. Only public GET operations are included; dashboard-only secrets and management routes are not exposed.

The search calls mirror POST /search/products, POST /search/packages, POST /search/stores, and GET /suggest. Search responses use the Go service's products, packages, stores, metas, and facets wire shape. Health and /index routes are excluded.

The booking calls mirror supported GET routes under /calendar, /booking-config, and /quotation-form-config, plus POST/GET/PUT routes under /reservation, /message-reservation, and /quotations. Configuration writes and every DELETE route remain server-owned concerns outside the storefront SDK surface.

The content calls mirror storefront GET routes under /legal-pages, /menus, /topics, /articles, /faqs, /article-homes, /home-pages, /search-pages, /registration-pages, and /onboarding-pages, plus POST /supports. CMS mutations, support administration, marketplace initialization, and content cloning remain backend-owned concerns.

Demo applications

Standalone consumer projects live in demo/. Each demo owns its dependencies, scripts, environment example, and lockfile so it can be installed and built from its own directory without a root npm workspace.

The first demo is demo/nextjs, a general Next.js App Router application that uses one lazy server-side SDK instance per Next.js runtime for a marketplace-scoped search-backed product list, a nomenclature-backed brand directory, catalog-backed product details, email-customer accounts, a server-owned cart, and Stripe Elements checkout. Request tokens, cache settings, cookies, and cart identifiers never become client configuration. Product and cart mutations use Server Actions; PaymentIntent preparation uses a server Route Handler and charges the current cart total without the optional marketplace-specific cart verification call. Only Stripe's publishable key and client secret reach the browser, and the payment service's verified webhook submits the paid cart and creates the order. Future framework demos should be added as sibling projects following the same standalone structure.

Development

npm test
npm run test:types