Usage

Create a client

const { SpmClient } = require('@shopimind/sdk-shopimind');

const client = SpmClient.getClient('v1', process.env.SHOPIMIND_API_KEY);

All options

const client = SpmClient.getClient('v1', 'your-api-key', {
  baseUrl: 'https://core-staging.shopimind.com',
  headers: { 'x-trace-id': 'abc-123' },
  timeout: 60000,
  labelSource: 'web',
  retry: { maxRetries: 3 },
});

Option	Type	Default	Role
baseUrl	string	https://core.shopimind.com	API base URL
headers	Record<string,string>	{}	Additional headers
timeout	number	30000	Request timeout (ms)
labelSource	string | null	'web'	Injected as label_source on sync POST/PUT requests. null disables it.
retry	SpmRetryOptions | false	see Resilience	Retry policy

The base URL can also come from the SHOPIMIND_CORE_API_BASE environment variable. Priority: options.baseUrl > SHOPIMIND_CORE_API_BASE > default.

The response envelope

Every method returns the same object, whether it succeeds or fails. The SDK never throws an exception on an HTTP error.

{
  ok: true | false,
  statusCode: 200 | 4xx | 5xx | 0,
  data: {/* API body */} | null,
  error: null | {
    message: string,
    code: string,        // 'HTTP_503', 'ETIMEDOUT', …
    retryable: boolean,
    attempts: number,
    details?: any,
  },
}

const res = await SpmCustomers.bulkSave(client, items);

if (res.ok) {
  console.log(res.data.sent_count, res.data.rejected_count);
} else if (res.error.retryable) {
  console.warn('Transient failure — API temporarily unavailable');
} else {
  console.error('Permanent failure', res.error.message);
}

Reading data

// Paginated list — the query is serialized into a query string
const page = await SpmCustomers.list(client, { limit: 50, offset: 0 });

// A single item by identifier (+ optional field projection)
const customer = await SpmCustomers.get(client, 'cust_1', ['email', 'first_name']);
const order    = await SpmOrders.get(client, 'ord_123');
const byRef    = await SpmOrders.getByReference(client, 'CMD-2024-0001');

// Sub-resources of a parent
const addresses = await SpmCustomersAddresses.list(client, 'cust_1', { limit: 20 });
const groups    = await SpmCustomers.listGroups(client, 'cust_1');

Writing data

Static — bulk operations (recommended for sync)

await SpmCustomers.bulkSave(client, items, { chunk: true });
await SpmCustomers.bulkUpdate(client, items, { chunk: true });
await SpmCustomers.delete(client, 'cust_1');
await SpmCustomers.bulkDelete(client, ['cust_1', 'cust_2']);

Instance — one item at a time

const { SpmCustomers } = require('@shopimind/sdk-shopimind');

const customer = new SpmCustomers(client);
customer.customer_id = 'cust_1';
customer.email = 'foo@bar.com';
customer.first_name = 'Foo';
customer.last_name = 'Bar';
customer.lang = 'fr';
customer.is_active = true;
customer.created_at = '2026-01-01T00:00:00Z';
customer.updated_at = '2026-01-01T00:00:00Z';

const res = await customer.save();   // or .update()

Nested resources (addresses, images, variations)

The constructor takes the parent; static methods take the parent as their 2nd argument:

const { SpmCustomersAddresses } = require('@shopimind/sdk-shopimind');

await SpmCustomersAddresses.bulkSave(client, 'cust_1', addresses, { chunk: true });
await SpmCustomersAddresses.bulkDelete(client, 'cust_1', [42, 43]);

Flat bulkSaveAll endpoint

Flat payload with the parent embedded in each item (multi-parent batch):

await SpmCustomersAddresses.bulkSaveAll(client, [
  { customer_id: 'cust_1', address_id: 1, /* ... */ },
  { customer_id: 'cust_2', address_id: 2, /* ... */ },
], { chunk: true });

Associate a data source (data_source)

Synchronization resources optionally accept a source identifier or label:

customer.id_data_source = 3;
customer.source_label = 'Magasin Paris';
await customer.save();

Register a shop

const { SpmShopConnection } = require('@shopimind/sdk-shopimind');

// POST /shop/connection expects 3 headers: client-id, client-version, current-build
const client = SpmClient.getClient('v1', apiKey, {
  headers: { 'client-id': clientId, 'client-version': '5.0.0', 'current-build': '1' },
});

await SpmShopConnection.saveConfiguration(client, {
  default_currency: 'EUR',
  default_lang: 'fr',
  langs: ['fr', 'en'],
  timezone: 'Europe/Paris',
  url_client: 'https://myshop.example.com',
  ecommerce_version: '2.7.0',
  module_version: '5.0.0',
});

Next: Resilience (retry, chunking, helpers).