Skip to content

Commit 8cb1373

Browse files
authored
fix: read me generation (#415)
* fix: read me generation * Revert "fix: read me generation" This reverts commit bcca69f. * fix: default gen readme
1 parent d02d739 commit 8cb1373

File tree

1 file changed

+64
-134
lines changed

1 file changed

+64
-134
lines changed

packages/sdks/shopper/README.md

Lines changed: 64 additions & 134 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# @epcc-sdk/sdks-shopper SDK
22

3-
Below you'll find instructions on how to install, set up, and use the client, along with a list of available operations.
3+
Below youll find instructions on how to install, set up, and use the client, along with a list of available operations.
44

55
## Features
66

@@ -26,6 +26,7 @@ yarn add @epcc-sdk/sdks-shopper
2626

2727
## Client Usage
2828

29+
2930
Clients are responsible for sending the actual HTTP requests.
3031

3132
The Fetch client is built as a thin wrapper on top of Fetch API, extending its functionality. If you're already familiar with Fetch, configuring your client will feel like working directly with Fetch API.
@@ -37,22 +38,23 @@ You can configure the client in two ways:
3738

3839
**When using the operation function to make requests, by default the global client will be used unless another is provided.**
3940

41+
4042
### 1. Configure the internal `client` instance directly
4143

4244
This is the simpler approach. You can call the setConfig() method at the beginning of your application or anytime you need to update the client configuration. You can pass any Fetch API configuration option to setConfig(), and even your own Fetch implementation.
4345

4446
```ts
45-
import { client } from "@epcc-sdk/sdks-shopper"
47+
import { client } from "@epcc-sdk/sdks-shopper";
4648

4749
client.setConfig({
48-
// set default base url for requests
49-
baseUrl: "https://euwest.api.elasticpath.com",
50+
// set default base url for requests
51+
baseUrl: 'https://euwest.api.elasticpath.com',
5052

51-
// set default headers for requests
52-
headers: {
53-
Authorization: "Bearer YOUR_AUTH_TOKEN",
54-
},
55-
})
53+
// set default headers for requests
54+
headers: {
55+
Authorization: 'Bearer YOUR_AUTH_TOKEN',
56+
},
57+
});
5658
```
5759

5860
The disadvantage of this approach is that your code may call the client instance before it's configured for the first time. Depending on your use case, you might need to use the second approach.
@@ -62,27 +64,27 @@ The disadvantage of this approach is that your code may call the client instance
6264
This is useful when you want to use a different instance of the client for different parts of your application or when you want to use different configurations for different parts of your application.
6365

6466
```ts
65-
import { createClient } from "@epcc-sdk/sdks-shopper"
67+
import { createClient } from "@epcc-sdk/sdks-shopper";
6668

6769
// Create the client with your API base URL.
6870
const client = createClient({
69-
// set default base url for requests
70-
baseUrl: "https://euwest.api.elasticpath.com",
71-
/**
72-
* Set default headers only for requests made by this client.
73-
*/
74-
headers: {
75-
"Custom-Header": "My Value",
76-
},
77-
})
71+
// set default base url for requests
72+
baseUrl: "https://euwest.api.elasticpath.com",
73+
/**
74+
* Set default headers only for requests made by this client.
75+
*/
76+
headers: {
77+
"Custom-Header": 'My Value',
78+
},
79+
});
7880
```
7981

8082
You can also pass this instance to any SDK function through the client option. This will override the default instance from `import { client } from "@epcc-sdk/sdks-shopper>".
8183

8284
```ts
8385
const response = await getByContextProduct({
84-
client: myClient,
85-
})
86+
client: myClient,
87+
});
8688
```
8789

8890
### Direct configuration
@@ -91,43 +93,44 @@ Alternatively, you can pass the client configuration options to each SDK functio
9193

9294
```ts
9395
const response = await getByContextProduct({
94-
baseUrl: "https://example.com", // <-- override default configuration
95-
})
96+
baseUrl: 'https://example.com', // <-- override default configuration
97+
});
9698
```
9799

98100
## Interceptors (Middleware)
99101

100102
Interceptors (middleware) can be used to modify requests before they're sent or responses before they're returned to your application. They can be added with use and removed with eject. Below is an example request interceptor
101103

102104
```ts
103-
import { client } from "@epcc-sdk/sdks-shopper"
105+
import { client } from "@epcc-sdk/sdks-shopper";
104106

105107
// Supports async functions
106108
client.interceptors.request.use(async (request) => {
107-
// do something
108-
return request
109-
})
109+
// do something
110+
return request;
111+
});
110112

111113
client.interceptors.request.eject((request) => {
112-
// do something
113-
return request
114-
})
114+
// do something
115+
return request;
116+
});
117+
115118
```
116119

117120
and an example response interceptor
118121

119122
```ts
120-
import { client } from "@epcc-sdk/sdks-shopper"
123+
import { client } from "@epcc-sdk/sdks-shopper";
121124

122125
client.interceptors.response.use((response) => {
123-
// do something
124-
return response
125-
})
126+
// do something
127+
return response;
128+
});
126129

127130
client.interceptors.response.eject((response) => {
128-
// do something
129-
return response
130-
})
131+
// do something
132+
return response;
133+
});
131134
```
132135

133136
> **_Tip:_** To eject, you must provide a reference to the function that was passed to use().
@@ -137,78 +140,49 @@ client.interceptors.response.eject((response) => {
137140
We are working to provide helpers to handle auth easier for you but for now using an interceptor is the easiest method.
138141

139142
```ts
140-
import { client } from "@epcc-sdk/sdks-shopper"
143+
import { client } from "@epcc-sdk/sdks-shopper";
141144

142145
client.interceptors.request.use((request, options) => {
143-
request.headers.set("Authorization", "Bearer MY_TOKEN")
144-
return request
145-
})
146-
```
147-
148-
### Local Storage Authentication Interceptor
149-
150-
The SDK provides a built-in local storage authentication interceptor that automatically handles token management:
151-
152-
```ts
153-
import { client } from "@epcc-sdk/sdks-shopper"
154-
import { createAuthLocalStorageInterceptor } from "@epcc-sdk/sdks-shopper"
155-
156-
// Add the interceptor to handle authentication automatically
157-
client.interceptors.request.use(
158-
createAuthLocalStorageInterceptor({
159-
clientId: "YOUR_CLIENT_ID", // Required
160-
autoRefresh: true, // Optional, defaults to true
161-
autoStoreCredentials: true, // Optional, defaults to true
162-
storageKey: "my-custom-storage-key", // Optional, defaults to a predefined key
163-
}),
164-
)
146+
request.headers.set('Authorization', 'Bearer MY_TOKEN');
147+
return request;
148+
});
165149
```
166150

167-
This interceptor:
168-
169-
- Stores authentication tokens in localStorage
170-
- Automatically refreshes tokens when they expire
171-
- Creates a new token if one doesn't exist
172-
- Adds the Authorization header to each request
173-
174-
#### Configuration Options
175-
176-
| Option | Type | Default | Description |
177-
| -------------------- | ------- | ------------ | ----------------------------------------------- |
178-
| clientId | string | (required) | Your storefront client ID |
179-
| autoRefresh | boolean | true | Automatically refresh tokens when they expire |
180-
| autoStoreCredentials | boolean | true | Automatically store credentials in localStorage |
181-
| storageKey | string | (predefined) | Custom localStorage key for storing credentials |
182-
183151
## Build URL
184152

185153
If you need to access the compiled URL, you can use the buildUrl() method. It's loosely typed by default to accept almost any value; in practice, you will want to pass a type hint.
186154

187155
```ts
188156
type FooData = {
189157
path: {
190-
fooId: number
191-
}
158+
fooId: number;
159+
};
192160
query?: {
193-
bar?: string
194-
}
195-
url: "/foo/{fooId}"
196-
}
161+
bar?: string;
162+
};
163+
url: '/foo/{fooId}';
164+
};
197165

198166
const url = client.buildUrl<FooData>({
199167
path: {
200168
fooId: 1,
201169
},
202170
query: {
203-
bar: "baz",
171+
bar: 'baz',
204172
},
205-
url: "/foo/{fooId}",
206-
})
207-
console.log(url) // prints '/foo/1?bar=baz'
173+
url: '/foo/{fooId}',
174+
});
175+
console.log(url); // prints '/foo/1?bar=baz'
208176
```
209177

210-
## Operation Usage
211178

179+
---
180+
181+
182+
183+
184+
185+
## Operation Usage
212186
The following examples demonstrate how to use the operation function to make requests.
213187

214188
```ts
@@ -227,57 +201,11 @@ const product = await getByContextProduct({
227201

228202
---
229203

230-
## Utilities
231-
232-
The SDK provides a set of utility functions that simplify common tasks when building a storefront.
233-
234-
### Cart Initialization
235-
236-
The `initializeCart` utility creates or retrieves a cart ID for the current shopper session:
237-
238-
```ts
239-
import { initializeCart } from "@epcc-sdk/sdks-shopper/utils"
240-
241-
// Initialize cart with default storage key
242-
const cartId = await initializeCart()
243-
244-
// Or with a custom storage key
245-
const cartId = await initializeCart({
246-
storageKey: "my-custom-cart-key",
247-
})
248-
```
249-
250-
#### How it works:
251204

252-
1. Checks localStorage for an existing cart ID
253-
2. If a cart ID exists, returns it immediately
254-
3. If no cart ID exists, creates a new cart via the API
255-
4. Stores the new cart ID in localStorage for future use
256-
5. Returns the cart ID as a string
257205

258-
This utility is useful for implementing guest checkout flows and ensuring the shopper always has an active cart.
259-
260-
### Cart ID Retrieval
261-
262-
The `getCartId` utility provides a simple way to retrieve the current cart ID from localStorage:
263-
264-
```ts
265-
import { getCartId } from "@epcc-sdk/sdks-shopper/utils"
266-
267-
// Get cart ID using default storage key
268-
const cartId = getCartId()
269-
270-
// Or with a custom storage key
271-
const cartId = getCartId({
272-
storageKey: "my-custom-cart-key",
273-
})
274-
```
275-
276-
Use this utility when you need to quickly check if a cart exists or need to pass the current cart ID to operations.
206+
## Available Operations
277207

278-
---
279208

280-
## Available Operations
281209

282210
- **`getByContextRelease`** (`GET /catalog`)
283211

@@ -533,4 +461,6 @@ Use this utility when you need to quickly check if a cart exists or need to pass
533461

534462
- **`getAFile`** (`GET /v2/files/{fileID}`)
535463

464+
465+
536466
---

0 commit comments

Comments
 (0)