Skip to content

Commit 30911a2

Browse files
joeluong-sfccjoeluong-sfcc
authored
Release v4.1.0 (@W-20127396@) (#250)
* update docs * bump version * update docs
1 parent dad1974 commit 30911a2

File tree

12 files changed

+193
-128
lines changed

12 files changed

+193
-128
lines changed

‎CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,9 @@
4242
- Remove API version from client config
4343
- Use `ShopperBasketsV2` API class to use V2 of Shopper Baskets
4444

45+
**NOTE: The Shopper-Consents API is experimental and will not be available for consumption until October 21st, 2025.
46+
DO NOT use Shopper-Consents API in production, this api might be subject to change.**
47+
4548
## v3.4.0
4649

4750
### API Changes

‎docs/assets/js/search.json‎

Lines changed: 1 addition & 1 deletion
Large diffs are not rendered by default.

‎docs/classes/clientconfig.clientconfig-1.html‎

Lines changed: 25 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,7 @@ <h3>Constructors</h3>
112112
<h3>Properties</h3>
113113
<ul class="tsd-index-list">
114114
<li class="tsd-kind-property tsd-parent-kind-class"><a href="clientconfig.clientconfig-1.html#baseuri" class="tsd-kind-icon">base<wbr>Uri</a></li>
115+
<li class="tsd-kind-property tsd-parent-kind-class"><a href="clientconfig.clientconfig-1.html#fetch" class="tsd-kind-icon">fetch</a></li>
115116
<li class="tsd-kind-property tsd-parent-kind-class"><a href="clientconfig.clientconfig-1.html#fetchoptions" class="tsd-kind-icon">fetch<wbr>Options</a></li>
116117
<li class="tsd-kind-property tsd-parent-kind-class"><a href="clientconfig.clientconfig-1.html#headers" class="tsd-kind-icon">headers</a></li>
117118
<li class="tsd-kind-property tsd-parent-kind-class"><a href="clientconfig.clientconfig-1.html#parameters" class="tsd-kind-icon">parameters</a></li>
@@ -141,7 +142,7 @@ <h3>constructor</h3>
141142
<li class="tsd-description">
142143
<aside class="tsd-sources">
143144
<ul>
144-
<li>Defined in src/lib/clientConfig.ts:62</li>
145+
<li>Defined in src/lib/clientConfig.ts:65</li>
145146
</ul>
146147
</aside>
147148
<h4 class="tsd-parameters-title">Parameters</h4>
@@ -164,7 +165,18 @@ <h3><span class="tsd-flag ts-flagOptional">Optional</span> base<wbr>Uri</h3>
164165
<aside class="tsd-sources">
165166
<p>Implementation of <a href="../interfaces/clientconfig.clientconfiginit.html">ClientConfigInit</a>.<a href="../interfaces/clientconfig.clientconfiginit.html#baseuri">baseUri</a></p>
166167
<ul>
167-
<li>Defined in src/lib/clientConfig.ts:48</li>
168+
<li>Defined in src/lib/clientConfig.ts:49</li>
169+
</ul>
170+
</aside>
171+
</section>
172+
<section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-class">
173+
<a name="fetch" class="tsd-anchor"></a>
174+
<h3><span class="tsd-flag ts-flagOptional">Optional</span> fetch</h3>
175+
<div class="tsd-signature tsd-kind-icon">fetch<span class="tsd-signature-symbol">:</span> <a href="../modules/clientconfig.html#fetchfunction" class="tsd-signature-type">FetchFunction</a></div>
176+
<aside class="tsd-sources">
177+
<p>Implementation of <a href="../interfaces/clientconfig.clientconfiginit.html">ClientConfigInit</a>.<a href="../interfaces/clientconfig.clientconfiginit.html#fetch">fetch</a></p>
178+
<ul>
179+
<li>Defined in src/lib/clientConfig.ts:59</li>
168180
</ul>
169181
</aside>
170182
</section>
@@ -175,7 +187,7 @@ <h3>fetch<wbr>Options</h3>
175187
<aside class="tsd-sources">
176188
<p>Implementation of <a href="../interfaces/clientconfig.clientconfiginit.html">ClientConfigInit</a>.<a href="../interfaces/clientconfig.clientconfiginit.html#fetchoptions">fetchOptions</a></p>
177189
<ul>
178-
<li>Defined in src/lib/clientConfig.ts:56</li>
190+
<li>Defined in src/lib/clientConfig.ts:57</li>
179191
</ul>
180192
</aside>
181193
</section>
@@ -186,7 +198,7 @@ <h3>headers</h3>
186198
<aside class="tsd-sources">
187199
<p>Implementation of <a href="../interfaces/clientconfig.clientconfiginit.html">ClientConfigInit</a>.<a href="../interfaces/clientconfig.clientconfiginit.html#headers">headers</a></p>
188200
<ul>
189-
<li>Defined in src/lib/clientConfig.ts:52</li>
201+
<li>Defined in src/lib/clientConfig.ts:53</li>
190202
</ul>
191203
</aside>
192204
<div class="tsd-type-declaration">
@@ -205,7 +217,7 @@ <h3>parameters</h3>
205217
<aside class="tsd-sources">
206218
<p>Implementation of <a href="../interfaces/clientconfig.clientconfiginit.html">ClientConfigInit</a>.<a href="../interfaces/clientconfig.clientconfiginit.html#parameters">parameters</a></p>
207219
<ul>
208-
<li>Defined in src/lib/clientConfig.ts:54</li>
220+
<li>Defined in src/lib/clientConfig.ts:55</li>
209221
</ul>
210222
</aside>
211223
</section>
@@ -216,7 +228,7 @@ <h3><span class="tsd-flag ts-flagOptional">Optional</span> proxy</h3>
216228
<aside class="tsd-sources">
217229
<p>Implementation of <a href="../interfaces/clientconfig.clientconfiginit.html">ClientConfigInit</a>.<a href="../interfaces/clientconfig.clientconfiginit.html#proxy">proxy</a></p>
218230
<ul>
219-
<li>Defined in src/lib/clientConfig.ts:50</li>
231+
<li>Defined in src/lib/clientConfig.ts:51</li>
220232
</ul>
221233
</aside>
222234
</section>
@@ -227,7 +239,7 @@ <h3>throw<wbr>OnBad<wbr>Response</h3>
227239
<aside class="tsd-sources">
228240
<p>Implementation of <a href="../interfaces/clientconfig.clientconfiginit.html">ClientConfigInit</a>.<a href="../interfaces/clientconfig.clientconfiginit.html#throwonbadresponse">throwOnBadResponse</a></p>
229241
<ul>
230-
<li>Defined in src/lib/clientConfig.ts:62</li>
242+
<li>Defined in src/lib/clientConfig.ts:65</li>
231243
</ul>
232244
</aside>
233245
</section>
@@ -238,7 +250,7 @@ <h3>transform<wbr>Request</h3>
238250
<aside class="tsd-sources">
239251
<p>Implementation of <a href="../interfaces/clientconfig.clientconfiginit.html">ClientConfigInit</a>.<a href="../interfaces/clientconfig.clientconfiginit.html#transformrequest">transformRequest</a></p>
240252
<ul>
241-
<li>Defined in src/lib/clientConfig.ts:58</li>
253+
<li>Defined in src/lib/clientConfig.ts:61</li>
242254
</ul>
243255
</aside>
244256
</section>
@@ -251,7 +263,7 @@ <h3><span class="tsd-flag ts-flagStatic">Static</span> <span class="tsd-flag ts-
251263
<div class="tsd-signature tsd-kind-icon">defaults<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">object</span></div>
252264
<aside class="tsd-sources">
253265
<ul>
254-
<li>Defined in src/lib/clientConfig.ts:88</li>
266+
<li>Defined in src/lib/clientConfig.ts:93</li>
255267
</ul>
256268
</aside>
257269
<section class="tsd-panel tsd-member tsd-kind-function tsd-parent-kind-object-literal">
@@ -264,7 +276,7 @@ <h3>transform<wbr>Request</h3>
264276
<li class="tsd-description">
265277
<aside class="tsd-sources">
266278
<ul>
267-
<li>Defined in src/lib/clientConfig.ts:100</li>
279+
<li>Defined in src/lib/clientConfig.ts:105</li>
268280
</ul>
269281
</aside>
270282
<div class="tsd-comment tsd-typography">
@@ -381,6 +393,9 @@ <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">string</s
381393
<li class=" tsd-kind-property tsd-parent-kind-class">
382394
<a href="clientconfig.clientconfig-1.html#baseuri" class="tsd-kind-icon">base<wbr>Uri</a>
383395
</li>
396+
<li class=" tsd-kind-property tsd-parent-kind-class">
397+
<a href="clientconfig.clientconfig-1.html#fetch" class="tsd-kind-icon">fetch</a>
398+
</li>
384399
<li class=" tsd-kind-property tsd-parent-kind-class">
385400
<a href="clientconfig.clientconfig-1.html#fetchoptions" class="tsd-kind-icon">fetch<wbr>Options</a>
386401
</li>

‎docs/index.html‎

Lines changed: 105 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -121,17 +121,29 @@ <h2>Getting Started</h2>
121121
<h3>Requirements</h3>
122122
</a>
123123
<ul>
124-
<li>Node <code>^12.x</code>, <code>^14.x</code>, <code>^16.x</code>, <code>^18.x</code></li>
124+
<li>Node <code>^20.x</code> or <code>^22.x</code></li>
125125
<li>The SDK requires B2C Commerce API (SCAPI) to be configured. For more info see <a href="https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html">Getting started with SCAPI</a>.</li>
126126
</ul>
127127
<a href="#installation" id="installation" style="color: inherit; text-decoration: none;">
128128
<h3>Installation</h3>
129129
</a>
130-
<pre><code class="language-bash">npm install commerce-sdk-isomorphic</code></pre>
130+
<pre><code class="language-bash"><span class="hljs-comment"># This package uses yarn, if you don&#x27;t have yarn:</span>
131+
<span class="hljs-comment"># npm install -g yarn</span>
132+
yarn install commerce-sdk-isomorphic</code></pre>
131133
<a href="#usage" id="usage" style="color: inherit; text-decoration: none;">
132134
<h3>Usage</h3>
133135
</a>
134-
<pre><code class="language-javascript"><span class="hljs-keyword">import</span> {helpers, ShopperLogin, ShopperSearch} <span class="hljs-keyword">from</span> <span class="hljs-string">&#x27;commerce-sdk-isomorphic&#x27;</span>;
136+
<pre><code class="language-javascript"><span class="hljs-keyword">import</span> ocapi <span class="hljs-keyword">from</span> <span class="hljs-string">&#x27;commerce-sdk-isomorphic&#x27;</span>;
137+
<span class="hljs-keyword">const</span> { helpers, ShopperLogin, ShopperSearch } = ocapi;
138+
139+
<span class="hljs-comment">// Named imports also work</span>
140+
<span class="hljs-comment">// import {helpers, ShopperLogin, ShopperSearch} from &#x27;commerce-sdk-isomorphic&#x27;;</span>
141+
142+
<span class="hljs-comment">// Alternatively, you can use subpath imports to import a single API at a time instead of the entire SDK</span>
143+
<span class="hljs-comment">// Useful for when you want a slimmer bundle size and only need a single API</span>
144+
<span class="hljs-comment">// import * as helpers from &#x27;commerce-sdk-isomorphic/helpers&#x27;</span>
145+
<span class="hljs-comment">// import { ShopperProducts } from &#x27;commerce-sdk-isomorphic/shopperProducts&#x27;;</span>
146+
<span class="hljs-comment">// import { ShopperSearch } from &#x27;commerce-sdk-isomorphic/shopperSearch&#x27;;</span>
135147

136148
<span class="hljs-keyword">const</span> config = {
137149
<span class="hljs-comment">// SCAPI does not support CORS, so client side requests must use a reverse proxy.</span>
@@ -157,6 +169,78 @@ <h3>Usage</h3>
157169
<span class="hljs-keyword">const</span> searchResult = <span class="hljs-keyword">await</span> shopperSearch.productSearch({
158170
<span class="hljs-attr">parameters</span>: {<span class="hljs-attr">q</span>: <span class="hljs-string">&#x27;shirt&#x27;</span>},
159171
});</code></pre>
172+
<a href="#import-strategies" id="import-strategies" style="color: inherit; text-decoration: none;">
173+
<h4>Import Strategies</h4>
174+
</a>
175+
<p>The SDK supports multiple import patterns to accommodate different use cases:</p>
176+
<p><strong>Default Import (Full SDK)</strong></p>
177+
<pre><code class="language-javascript"><span class="hljs-keyword">import</span> ocapi <span class="hljs-keyword">from</span> <span class="hljs-string">&#x27;commerce-sdk-isomorphic&#x27;</span>;
178+
<span class="hljs-keyword">const</span> { helpers, ShopperLogin, ShopperSearch } = ocapi;</code></pre>
179+
<p><strong>Named Imports (Full SDK)</strong></p>
180+
<pre><code class="language-javascript"><span class="hljs-keyword">import</span> { helpers, ShopperLogin, ShopperSearch } <span class="hljs-keyword">from</span> <span class="hljs-string">&#x27;commerce-sdk-isomorphic&#x27;</span>;</code></pre>
181+
<p><strong>Subpath Imports (Individual APIs and Common dependencies)</strong></p>
182+
<p><em>ESM (ES Modules):</em></p>
183+
<pre><code class="language-javascript"><span class="hljs-keyword">import</span> { ShopperLogin } <span class="hljs-keyword">from</span> <span class="hljs-string">&#x27;commerce-sdk-isomorphic/shopperLogin&#x27;</span>;
184+
<span class="hljs-keyword">import</span> * <span class="hljs-keyword">as</span> helpers <span class="hljs-keyword">from</span> <span class="hljs-string">&#x27;commerce-sdk-isomorphic/helpers&#x27;</span>;</code></pre>
185+
<p><em>CommonJS:</em></p>
186+
<pre><code class="language-javascript"><span class="hljs-keyword">const</span> { ShopperLogin } = <span class="hljs-built_in">require</span>(<span class="hljs-string">&#x27;commerce-sdk-isomorphic/shopperLogin&#x27;</span>);
187+
<span class="hljs-keyword">const</span> helpers = <span class="hljs-built_in">require</span>(<span class="hljs-string">&#x27;commerce-sdk-isomorphic/helpers&#x27;</span>);</code></pre>
188+
<a href="#choosing-the-right-import-strategy" id="choosing-the-right-import-strategy" style="color: inherit; text-decoration: none;">
189+
<h4>Choosing the Right Import Strategy</h4>
190+
</a>
191+
<p><strong>Use Default/Named Imports when:</strong></p>
192+
<ul>
193+
<li>You need multiple APIs from the SDK</li>
194+
<li>You want the smallest overall bundle size for comprehensive usage</li>
195+
<li>The entire SDK is optimized and maximally compressed as a single bundle</li>
196+
</ul>
197+
<p><strong>Note:</strong> Default and named imports load the entire SDK, including all APIs, helpers, and dependencies.</p>
198+
<p><strong>Use Subpath Imports when:</strong></p>
199+
<ul>
200+
<li>You only need specific APIs</li>
201+
<li>You want to minimize initial bundle size</li>
202+
<li>You&#39;re implementing dynamic loading for better page performance</li>
203+
<li>You need granular control over which APIs are loaded</li>
204+
</ul>
205+
<p><strong>Note:</strong> While subpath imports reduce initial bundle size, using them for all APIs will result in a larger total bundle size due to duplicated dependencies required for standalone operation.</p>
206+
<a href="#custom-fetch-function" id="custom-fetch-function" style="color: inherit; text-decoration: none;">
207+
<h4>Custom Fetch function</h4>
208+
</a>
209+
<p>You can provide your own custom fetch function to intercept, log, or modify all SDK requests. This is useful for:</p>
210+
<ul>
211+
<li><strong>Request/Response Logging</strong>: Track all API calls for debugging and monitoring</li>
212+
<li><strong>Request Interception</strong>: Add custom headers, modify request URLs, or implement custom retry logic</li>
213+
<li><strong>Error Handling</strong>: Add custom error processing or transformation before responses reach your application</li>
214+
<li><strong>Performance Monitoring</strong>: Measure request/response times and track API performance metrics</li>
215+
</ul>
216+
<p><strong>Example with Logging:</strong></p>
217+
<pre><code class="language-javascript"><span class="hljs-comment">// Custom fetch function with detailed logging</span>
218+
<span class="hljs-keyword">const</span> customFetch = <span class="hljs-keyword">async</span> (url, options) =&gt; {
219+
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`[SDK Request] <span class="hljs-subst">${options?.method || <span class="hljs-string">&#x27;GET&#x27;</span>}</span> <span class="hljs-subst">${url}</span>`</span>);
220+
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">&#x27;[SDK Request Headers]&#x27;</span>, options?.headers);
221+
<span class="hljs-keyword">if</span> (options?.body) {
222+
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">&#x27;[SDK Request Body]&#x27;</span>, options.body);
223+
}
224+
225+
<span class="hljs-keyword">const</span> startTime = <span class="hljs-built_in">Date</span>.now();
226+
<span class="hljs-keyword">const</span> response = <span class="hljs-keyword">await</span> fetch(url, options);
227+
<span class="hljs-keyword">const</span> duration = <span class="hljs-built_in">Date</span>.now() - startTime;
228+
229+
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">`[SDK Response] <span class="hljs-subst">${response.status}</span> <span class="hljs-subst">${response.statusText}</span> (<span class="hljs-subst">${duration}</span>ms)`</span>);
230+
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">&#x27;[SDK Response Headers]&#x27;</span>, <span class="hljs-built_in">Object</span>.fromEntries(response.headers.entries()));
231+
232+
<span class="hljs-keyword">return</span> response;
233+
};
234+
235+
<span class="hljs-keyword">const</span> config = {
236+
<span class="hljs-attr">parameters</span>: {
237+
<span class="hljs-attr">clientId</span>: <span class="hljs-string">&#x27;&lt;your-client-id&gt;&#x27;</span>,
238+
<span class="hljs-attr">organizationId</span>: <span class="hljs-string">&#x27;&lt;your-org-id&gt;&#x27;</span>,
239+
<span class="hljs-attr">shortCode</span>: <span class="hljs-string">&#x27;&lt;your-short-code&gt;&#x27;</span>,
240+
<span class="hljs-attr">siteId</span>: <span class="hljs-string">&#x27;&lt;your-site-id&gt;&#x27;</span>,
241+
},
242+
<span class="hljs-attr">fetch</span>: customFetch,
243+
};</code></pre>
160244
<a href="#fetch-options" id="fetch-options" style="color: inherit; text-decoration: none;">
161245
<h4>Fetch Options</h4>
162246
</a>
@@ -331,6 +415,24 @@ <h4>Encoding special characters</h4>
331415

332416
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">&quot;categoriesResult: &quot;</span>, categoriesResult);</code></pre>
333417
<p><strong>NOTE: In the next major version release, path parameters will be single encoded by default</strong></p>
418+
<a href="#unstable-releases" id="unstable-releases" style="color: inherit; text-decoration: none;">
419+
<h2>Unstable Releases</h2>
420+
</a>
421+
<p><strong>⚠️ Important: Unstable/preview releases are experimental and not officially supported.</strong></p>
422+
<p>Preview releases (e.g., preview, unstable, or pre-release versions) are provided for experimental purposes and early testing of upcoming features. These releases:</p>
423+
<ul>
424+
<li><strong>Are not intended for production use</strong> - Do not use unstable releases in production environments</li>
425+
<li><strong>May contain breaking changes</strong> - API signatures, behavior, and structure may change without notice</li>
426+
<li><strong>Are not officially supported</strong> - No support, bug fixes, or security patches are guaranteed</li>
427+
<li><strong>May have incomplete features</strong> - Functionality may be partially implemented or subject to change</li>
428+
</ul>
429+
<p><strong>Use stable releases for production applications.</strong> Only use unstable releases for:</p>
430+
<ul>
431+
<li>Testing upcoming features in development environments</li>
432+
<li>Providing feedback on new functionality before official release</li>
433+
<li>Experimental integrations that are not mission-critical</li>
434+
</ul>
435+
<p>For production deployments, always use the latest stable release version available on npm.</p>
334436
<a href="#license-information" id="license-information" style="color: inherit; text-decoration: none;">
335437
<h2>License Information</h2>
336438
</a>

0 commit comments

Comments
 (0)