Skip to main content

SDK services

Package: @propeller-commerce/propeller-sdk-v2

The SDK is the data layer of the Storefront SDK. It is a typed GraphQL client that ships a service for every supported query and mutation, with the GraphQL documents bundled per operation so you never write or maintain GraphQL yourself. It runs in any JavaScript or TypeScript project (Node.js, React, Vue, server scripts) and has no runtime dependency on the graphql package.

Create a client​

createClient() is the entry point. It defaults to proxy mode, which keeps your API key server-side.

import { createClient } from '@propeller-commerce/propeller-sdk-v2';

export const graphqlClient = createClient({
  endpoint: '/api/graphql',     // your endpoint or proxy route
  securityMode: 'proxy',        // default; keeps the API key server-side
  defaultLanguage: 'NL',        // optional fallback for calls without a language
  getAccessToken: () => readMyToken(),   // current bearer token, sync or async
});

Key configuration fields:

FieldPurpose
endpointRequired. Your GraphQL URL or proxy route.
securityMode'proxy' (default, recommended) or 'direct'. Direct exposes the API key client-side.
getAccessTokenReturns the current bearer token for authenticated requests.
defaultLanguageFallback language for calls that do not pass one.
headersExtra headers merged into every request.
timeoutRequest timeout in milliseconds (default 30000).

For the full configuration (clientId, orderEditorApiKey, partial-error handling, per-call cache hints) see the SDK documentation site.

Call a service​

Each service is a factory that takes the client and returns typed methods. Import only the services you use; the rest are tree-shaken away.

import { productService, categoryService, cartService } from '@propeller-commerce/propeller-sdk-v2';

const products = productService(graphqlClient);
const product = await products.getProduct({ productId: 42, language: 'NL' });

product.sku;
product.price?.gross;   // read with optional chaining (see note below)

The SDK covers catalog, cart, order, user, B2B, media and admin domains across more than 50 services, including productService, categoryService, cartService, userService, loginService, orderService, paymentService, menuService, addressService and favoriteListService. For the complete list and every method signature, read the package on npm and the types in your editor.

A service method returns the operation's named type (for example getProduct returns Product), but only the fields the operation selects are populated. Treat any field outside the selection as possibly absent and use optional chaining.

Localized fields​

Many fields are arrays of localized strings (for example product.names). Resolve them with the getLocalized helper:

import { getLocalized } from '@propeller-commerce/propeller-sdk-v2';

const name = getLocalized(product.names, 'EN', 'NL'); // EN, fall back to NL, then first

The GraphQL proxy pattern​

In the default proxy mode the SDK posts to a server-side route (for example /api/graphql) instead of calling Propeller directly. The route injects the API key server-side, so it never reaches the browser. When a user is signed in, getAccessToken() supplies the bearer token and the route forwards it upstream.

Browser                         Your server route           Propeller API
───────                         ─────────────────           ─────────────
productService.getProduct()
  → POST /api/graphql           → adds the API key
                                → forwards the request   → returns data
                                ← passes the response back
  ← receives the typed result

The Accelerator boilerplates ship this route ready to use. See Accelerator.

Error handling​

Service methods throw GraphQLOperationError only on a hard failure (the server returned errors and no data). On a partial response they return the data and surface the errors through the client's debug log. Call client.execute() directly if you need the raw { data, errors }.

See also​