Resources & methods

This page inventories everything @shopimind/sdk-js exposes: 28 named exports = 6 infrastructure classes + 22 resources (one static class per API domain). The infrastructure classes are SpmClient, SpmClientException, SpmApiError, SpmRequestValidator, SpmWebhookSignature and SpmHelpers; the conventions shared by every method are described below.

As a reminder, the base URL is https://core.shopimind.com/v1 and authentication is done with the shop API key in the spm-api-key header. See also Scope & versions.

How the methods are named

All resource methods are static and take the client as their first argument:

import { SpmClient, SpmCustomers } from '@shopimind/sdk-js';

// Client for API v1, authenticated by the shop API key (spm-api-key header)
const client = SpmClient.getClient('v1', process.env.SHOPIMIND_API_KEY!);

// Read — paginated list
const res = await SpmCustomers.list(client, { limit: 50 });
if (!res.ok) {
  throw new Error(res.error.message); // the SDK never throws: check res.ok
}
console.log(res.data.data); // ⚠️ business payload is double-nested: res.data.data

// Bulk write with automatic chunking
const saved = await SpmCustomers.bulkSave(client, customers, { chunk: true });

No configured instance

You never call client.customers.list(...). The pattern is always SpmResource.method(client, …) — the class is static, the client is an argument.

The 22 resources

The CHUNK_SIZE column shows the default batch size applied by bulkSave / bulkUpdate when you pass { chunk: true }. Resources with no value do not define their own CHUNK_SIZE (generic fallback of 50 if chunking is requested).

Resource	Endpoint	Methods	CHUNK_SIZE
SpmShopConnection	shop/connection	saveConfiguration	—
SpmCustomers	customers	bulkSave · bulkUpdate · delete · bulkDelete · get · list · listGroups · (instance) save · update	50
SpmCustomersAddresses	customers/{customerId}/addresses	bulkSave · bulkSaveAll · bulkUpdate · delete · bulkDelete · list · (instance) save · update	50
SpmCustomersGroups	customers-groups	bulkSave · bulkUpdate · delete · bulkDelete · list · (instance) save · update	100
SpmProducts	products	bulkSave · bulkUpdate · delete · bulkDelete · list · (instance) save · update	50
SpmProductsCategories	products-categories	bulkSave · bulkUpdate · delete · bulkDelete · list · (instance) save · update	100
SpmProductsImages	products/{productId}/images	bulkSave · bulkSaveAll · bulkUpdate · delete · bulkDelete · (instance) save · update · no list	50
SpmProductsManufacturers	products-manufacturers	bulkSave · bulkUpdate · delete · bulkDelete · list · (instance) save · update	100
SpmProductsVariations	products/{productId}/variations	bulkSave · bulkSaveAll · bulkUpdate · delete · bulkDelete · (instance) save · update · no list	50
SpmOrders	orders	bulkSave · bulkUpdate · delete · bulkDelete · get · getByReference · list · (instance) save · update	50
SpmOrdersCarriers	orders-carriers	bulkSave · bulkUpdate · delete · bulkDelete · list · (instance) save · update	100
SpmOrdersStatuses	orders-statuses	bulkSave · bulkUpdate · delete · bulkDelete · list · (instance) save · update	100
SpmVouchers	vouchers	bulkSave · bulkUpdate · delete · bulkDelete · list · (instance) save · update	50
SpmNewsletterSubscribers	newsletter-subscribers	bulkSave · bulkUpdate · (instance) save · update	50
SpmDataSources	data-sources	list · create · update · delete	—
SpmIntegrationConfig	integration-config	get · set	—
SpmCustomDataDefinitions	custom-data-definitions	list · get · create · update (= extend) · extend · activate · deactivate · delete · listOverrides · updateOverrides	—
SpmCustomDataRecords	custom-data-records/{definitionId}	bulkSave · list · update · delete · bulkDelete	20
SpmContacts	contacts, contact-consent-history, contact-messages-reject	get · list · listLists · listTags · listCustomDataDefinitions · listConsentHistory · listMessagesReject — read-only	—
SpmEvents	events	create · update · list · listHistories · get · delete · trigger	—
SpmCarts	carts	list — read-only	—
SpmLists	lists	list · get · create · update · delete · listContacts	—

Batch chunking

Chunking is active only if you pass { chunk: true } and the data is an array; otherwise the array is sent in a single request. The default batch follows the resource's CHUNK_SIZE, overridable via { chunkSize: N }. Details and response aggregation in Resilience.

Specifics to know

• SpmProductsImages and SpmProductsVariations have no list method. You push images and variations (including flat via bulkSaveAll, with the parent embedded in each item), but you do not read them back through the SDK.
• SpmCarts and SpmContacts are read-only. Carts are created on the ShopiMind side from the orders you push via SpmOrders; contacts are a consolidated view, fed by your customers.
• SpmCustomDataRecords is asynchronous on the server side: ingestion goes through Kafka. A 200 means "accepted", not "persisted". The batch is capped at 20 records per request (bulkSave and bulkDelete).
• bulkDelete is a POST (to …/bulk-delete), not a DELETE.
• Special routes: SpmOrders.get → orders/id/{id}, SpmOrders.getByReference → orders/reference/{reference}, SpmEvents.trigger → events/trigger/{codeName}. Updates for SpmCustomDataDefinitions, SpmCustomDataRecords, SpmLists and SpmEvents are PATCH (a definition update goes through PATCH …/{id}/extend; a record update goes through PATCH …/{definitionId}/{recordId}).

label_source & id_data_source

label_source is injected automatically into the POST / PUT bodies of the data synchronization resources (customers, products, orders, vouchers and their sub-resources) to trace their origin; it is intentionally omitted for the configuration and read endpoints. id_data_source ties a record to its source. See Data sources.

Infrastructure classes

In addition to the resources, the SDK exports six cross-cutting classes.

Export	Role
SpmClient	HTTP client factory: SpmClient.getClient('v1', apiKey, options?). See Installation and Usage.
SpmClientException	Exception type thrown on configuration errors (for example an invalid baseUrl passed to getClient). The SDK never throws it on an HTTP failure — those are encoded in the { ok, statusCode, data, error } envelope.
SpmApiError	Error thrown only by SpmHelpers.unwrapOrThrow (the opt-in exception mode). It carries statusCode, code and the original envelope.
SpmRequestValidator	Security primitive for the connector channel — see the callout below.
SpmWebhookSignature	Security primitive for the integration channel — see the callout below.
SpmHelpers	Grab bag of utilities: chunk, mergeResponses, extractCounts, isRetryable, formatError, unwrapOrThrow — see Resilience.

Two security primitives

The SDK exposes two signature primitives, one per channel.

• SpmRequestValidator — connector channel. This is the security primitive for the CMS connectors, always active. The body is "imploded" (sorted at the top level) then signed with HMAC-SHA256 using a derived key sha256(secret), and compared as md5 in constant time; Shopimind-Token and Shopimind-Client-Identifiant headers.
• SpmWebhookSignature — integration channel. Verifies integration webhooks via a timestamped HMAC-SHA256 over ${timestamp}.${rawBody}, with a replay window and a timing-safe comparison; x-shopimind-timestamp and x-shopimind-signature headers (verifyFromHeaders helper). See Integration webhooks.

Going further

• → Usage — the response envelope, reading the double-nested payload at res.data.data, writing in bulk.
• → Resilience — retries, chunking, aggregation, helpers.
• → TypeScript types — the exact DTOs of each entity.