partnermax 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (179) hide show
  1. package/CHANGELOG.md +75 -47
  2. package/LICENSE +201 -201
  3. package/README.md +394 -370
  4. package/api-promise.js +1 -1
  5. package/client.d.mts +9 -3
  6. package/client.d.mts.map +1 -1
  7. package/client.d.ts +9 -3
  8. package/client.d.ts.map +1 -1
  9. package/client.js +12 -2
  10. package/client.js.map +1 -1
  11. package/client.mjs +12 -2
  12. package/client.mjs.map +1 -1
  13. package/core/api-promise.js +1 -1
  14. package/core/api-promise.mjs +1 -1
  15. package/core/pagination.d.mts +57 -0
  16. package/core/pagination.d.mts.map +1 -0
  17. package/core/pagination.d.ts +57 -0
  18. package/core/pagination.d.ts.map +1 -0
  19. package/core/pagination.js +108 -0
  20. package/core/pagination.js.map +1 -0
  21. package/core/pagination.mjs +102 -0
  22. package/core/pagination.mjs.map +1 -0
  23. package/error.js +1 -1
  24. package/index.d.mts +1 -0
  25. package/index.d.mts.map +1 -1
  26. package/index.d.ts +1 -0
  27. package/index.d.ts.map +1 -1
  28. package/index.js +3 -1
  29. package/index.js.map +1 -1
  30. package/index.mjs +1 -0
  31. package/index.mjs.map +1 -1
  32. package/internal/tslib.js +17 -17
  33. package/package.json +19 -15
  34. package/pagination.d.mts +3 -0
  35. package/pagination.d.mts.map +1 -0
  36. package/pagination.d.ts +3 -0
  37. package/pagination.d.ts.map +1 -0
  38. package/pagination.js +6 -0
  39. package/pagination.js.map +1 -0
  40. package/pagination.mjs +3 -0
  41. package/pagination.mjs.map +1 -0
  42. package/resource.js +1 -1
  43. package/resources/dealers/dealers.d.mts +7 -71
  44. package/resources/dealers/dealers.d.mts.map +1 -1
  45. package/resources/dealers/dealers.d.ts +7 -71
  46. package/resources/dealers/dealers.d.ts.map +1 -1
  47. package/resources/dealers/dealers.js +3 -16
  48. package/resources/dealers/dealers.js.map +1 -1
  49. package/resources/dealers/dealers.mjs +2 -15
  50. package/resources/dealers/dealers.mjs.map +1 -1
  51. package/resources/dealers/index.d.mts +2 -2
  52. package/resources/dealers/index.d.mts.map +1 -1
  53. package/resources/dealers/index.d.ts +2 -2
  54. package/resources/dealers/index.d.ts.map +1 -1
  55. package/resources/dealers/index.js.map +1 -1
  56. package/resources/dealers/index.mjs.map +1 -1
  57. package/resources/dealers/nlt/index.d.mts +1 -1
  58. package/resources/dealers/nlt/index.d.mts.map +1 -1
  59. package/resources/dealers/nlt/index.d.ts +1 -1
  60. package/resources/dealers/nlt/index.d.ts.map +1 -1
  61. package/resources/dealers/nlt/nlt.d.mts +2 -2
  62. package/resources/dealers/nlt/nlt.d.mts.map +1 -1
  63. package/resources/dealers/nlt/nlt.d.ts +2 -2
  64. package/resources/dealers/nlt/nlt.d.ts.map +1 -1
  65. package/resources/dealers/nlt/nlt.js +1 -1
  66. package/resources/dealers/nlt/offers.d.mts +55 -78
  67. package/resources/dealers/nlt/offers.d.mts.map +1 -1
  68. package/resources/dealers/nlt/offers.d.ts +55 -78
  69. package/resources/dealers/nlt/offers.d.ts.map +1 -1
  70. package/resources/dealers/nlt/offers.js +9 -11
  71. package/resources/dealers/nlt/offers.js.map +1 -1
  72. package/resources/dealers/nlt/offers.mjs +9 -11
  73. package/resources/dealers/nlt/offers.mjs.map +1 -1
  74. package/resources/dealers/nlt-settings.d.mts +24 -64
  75. package/resources/dealers/nlt-settings.d.mts.map +1 -1
  76. package/resources/dealers/nlt-settings.d.ts +24 -64
  77. package/resources/dealers/nlt-settings.d.ts.map +1 -1
  78. package/resources/dealers/nlt-settings.js +4 -13
  79. package/resources/dealers/nlt-settings.js.map +1 -1
  80. package/resources/dealers/nlt-settings.mjs +4 -13
  81. package/resources/dealers/nlt-settings.mjs.map +1 -1
  82. package/resources/dealers/nlt.js +1 -1
  83. package/resources/dealers/vehicles/images.d.mts +3 -2
  84. package/resources/dealers/vehicles/images.d.mts.map +1 -1
  85. package/resources/dealers/vehicles/images.d.ts +3 -2
  86. package/resources/dealers/vehicles/images.d.ts.map +1 -1
  87. package/resources/dealers/vehicles/images.js +3 -2
  88. package/resources/dealers/vehicles/images.js.map +1 -1
  89. package/resources/dealers/vehicles/images.mjs +3 -2
  90. package/resources/dealers/vehicles/images.mjs.map +1 -1
  91. package/resources/dealers/vehicles/index.d.mts +1 -1
  92. package/resources/dealers/vehicles/index.d.mts.map +1 -1
  93. package/resources/dealers/vehicles/index.d.ts +1 -1
  94. package/resources/dealers/vehicles/index.d.ts.map +1 -1
  95. package/resources/dealers/vehicles/index.js.map +1 -1
  96. package/resources/dealers/vehicles/index.mjs.map +1 -1
  97. package/resources/dealers/vehicles/vehicles.d.mts +57 -70
  98. package/resources/dealers/vehicles/vehicles.d.mts.map +1 -1
  99. package/resources/dealers/vehicles/vehicles.d.ts +57 -70
  100. package/resources/dealers/vehicles/vehicles.d.ts.map +1 -1
  101. package/resources/dealers/vehicles/vehicles.js +19 -19
  102. package/resources/dealers/vehicles/vehicles.js.map +1 -1
  103. package/resources/dealers/vehicles/vehicles.mjs +18 -18
  104. package/resources/dealers/vehicles/vehicles.mjs.map +1 -1
  105. package/resources/dealers/vehicles.js +1 -1
  106. package/resources/dealers.js +1 -1
  107. package/resources/index.d.mts +1 -1
  108. package/resources/index.d.mts.map +1 -1
  109. package/resources/index.d.ts +1 -1
  110. package/resources/index.d.ts.map +1 -1
  111. package/resources/index.js.map +1 -1
  112. package/resources/index.mjs.map +1 -1
  113. package/resources/keys.d.mts +7 -6
  114. package/resources/keys.d.mts.map +1 -1
  115. package/resources/keys.d.ts +7 -6
  116. package/resources/keys.d.ts.map +1 -1
  117. package/resources/keys.js +7 -6
  118. package/resources/keys.js.map +1 -1
  119. package/resources/keys.mjs +7 -6
  120. package/resources/keys.mjs.map +1 -1
  121. package/resources.js +1 -1
  122. package/src/api-promise.ts +2 -2
  123. package/src/client.ts +868 -841
  124. package/src/core/README.md +3 -3
  125. package/src/core/api-promise.ts +92 -92
  126. package/src/core/error.ts +130 -130
  127. package/src/core/pagination.ts +170 -0
  128. package/src/core/resource.ts +11 -11
  129. package/src/core/uploads.ts +2 -2
  130. package/src/error.ts +2 -2
  131. package/src/index.ts +23 -22
  132. package/src/internal/README.md +3 -3
  133. package/src/internal/builtin-types.ts +93 -93
  134. package/src/internal/detect-platform.ts +196 -196
  135. package/src/internal/errors.ts +33 -33
  136. package/src/internal/headers.ts +97 -97
  137. package/src/internal/parse.ts +56 -56
  138. package/src/internal/request-options.ts +91 -91
  139. package/src/internal/shim-types.ts +26 -26
  140. package/src/internal/shims.ts +107 -107
  141. package/src/internal/to-file.ts +154 -154
  142. package/src/internal/types.ts +93 -93
  143. package/src/internal/uploads.ts +187 -187
  144. package/src/internal/utils/base64.ts +40 -40
  145. package/src/internal/utils/bytes.ts +32 -32
  146. package/src/internal/utils/env.ts +18 -18
  147. package/src/internal/utils/log.ts +128 -128
  148. package/src/internal/utils/path.ts +88 -88
  149. package/src/internal/utils/query.ts +23 -23
  150. package/src/internal/utils/sleep.ts +3 -3
  151. package/src/internal/utils/uuid.ts +17 -17
  152. package/src/internal/utils/values.ts +105 -105
  153. package/src/internal/utils.ts +9 -9
  154. package/src/lib/.keep +4 -4
  155. package/src/pagination.ts +2 -0
  156. package/src/resource.ts +2 -2
  157. package/src/resources/dealers/dealers.ts +260 -348
  158. package/src/resources/dealers/index.ts +28 -28
  159. package/src/resources/dealers/nlt/index.ts +11 -11
  160. package/src/resources/dealers/nlt/nlt.ts +29 -29
  161. package/src/resources/dealers/nlt/offers.ts +403 -427
  162. package/src/resources/dealers/nlt-settings.ts +229 -269
  163. package/src/resources/dealers/nlt.ts +3 -3
  164. package/src/resources/dealers/vehicles/images.ts +154 -153
  165. package/src/resources/dealers/vehicles/index.ts +26 -25
  166. package/src/resources/dealers/vehicles/vehicles.ts +786 -796
  167. package/src/resources/dealers/vehicles.ts +3 -3
  168. package/src/resources/dealers.ts +3 -3
  169. package/src/resources/index.ts +11 -12
  170. package/src/resources/keys.ts +129 -128
  171. package/src/resources.ts +1 -1
  172. package/src/tsconfig.json +11 -11
  173. package/src/uploads.ts +2 -2
  174. package/src/version.ts +1 -1
  175. package/uploads.js +1 -1
  176. package/version.d.mts +1 -1
  177. package/version.d.ts +1 -1
  178. package/version.js +1 -1
  179. package/version.mjs +1 -1
package/README.md CHANGED
@@ -1,370 +1,394 @@
1
- # Partnermax TypeScript API Library
2
-
3
- [![NPM version](<https://img.shields.io/npm/v/partnermax.svg?label=npm%20(stable)>)](https://npmjs.org/package/partnermax) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/partnermax)
4
-
5
- This library provides convenient access to the Partnermax REST API from server-side TypeScript or JavaScript.
6
-
7
- The REST API documentation can be found on [developers.dealermax.app](https://developers.dealermax.app). The full API of this library can be found in [api.md](api.md).
8
-
9
- It is generated with [Stainless](https://www.stainless.com/).
10
-
11
- ## Installation
12
-
13
- ```sh
14
- npm install partnermax
15
- ```
16
-
17
- ## Usage
18
-
19
- The full API of this library can be found in [api.md](api.md).
20
-
21
- <!-- prettier-ignore -->
22
- ```js
23
- import Partnermax from 'partnermax';
24
-
25
- const client = new Partnermax({
26
- apiKey: process.env['PARTNERMAX_API_KEY'], // This is the default and can be omitted
27
- environment: 'sandbox', // defaults to 'production'
28
- });
29
-
30
- const dealerDetail = await client.dealers.create({
31
- address: 'xx',
32
- business_name: 'Rossi Automobili S.R.L.',
33
- city: 'xx',
34
- contact_email: 'info@rossi-auto.it',
35
- contact_phone: 'xxxxx',
36
- postal_code: '20121',
37
- primary_domain: 'rossi-auto.it',
38
- province_code: 'MI',
39
- vat_number: 'IT01234567890',
40
- });
41
-
42
- console.log(dealerDetail.dealer_id);
43
- ```
44
-
45
- ### Request & Response types
46
-
47
- This library includes TypeScript definitions for all request params and response fields. You may import and use them like so:
48
-
49
- <!-- prettier-ignore -->
50
- ```ts
51
- import Partnermax from 'partnermax';
52
-
53
- const client = new Partnermax({
54
- apiKey: process.env['PARTNERMAX_API_KEY'], // This is the default and can be omitted
55
- environment: 'sandbox', // defaults to 'production'
56
- });
57
-
58
- const dealers: Partnermax.DealerListResponse = await client.dealers.list();
59
- ```
60
-
61
- Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.
62
-
63
- ## Handling errors
64
-
65
- When the library is unable to connect to the API,
66
- or if the API returns a non-success status code (i.e., 4xx or 5xx response),
67
- a subclass of `APIError` will be thrown:
68
-
69
- <!-- prettier-ignore -->
70
- ```ts
71
- const dealers = await client.dealers.list().catch(async (err) => {
72
- if (err instanceof Partnermax.APIError) {
73
- console.log(err.status); // 400
74
- console.log(err.name); // BadRequestError
75
- console.log(err.headers); // {server: 'nginx', ...}
76
- } else {
77
- throw err;
78
- }
79
- });
80
- ```
81
-
82
- Error codes are as follows:
83
-
84
- | Status Code | Error Type |
85
- | ----------- | -------------------------- |
86
- | 400 | `BadRequestError` |
87
- | 401 | `AuthenticationError` |
88
- | 403 | `PermissionDeniedError` |
89
- | 404 | `NotFoundError` |
90
- | 422 | `UnprocessableEntityError` |
91
- | 429 | `RateLimitError` |
92
- | >=500 | `InternalServerError` |
93
- | N/A | `APIConnectionError` |
94
-
95
- ### Retries
96
-
97
- Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
98
- Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,
99
- 429 Rate Limit, and >=500 Internal errors will all be retried by default.
100
-
101
- You can use the `maxRetries` option to configure or disable this:
102
-
103
- <!-- prettier-ignore -->
104
- ```js
105
- // Configure the default for all requests:
106
- const client = new Partnermax({
107
- maxRetries: 0, // default is 2
108
- });
109
-
110
- // Or, configure per-request:
111
- await client.dealers.list({
112
- maxRetries: 5,
113
- });
114
- ```
115
-
116
- ### Timeouts
117
-
118
- Requests time out after 1 minute by default. You can configure this with a `timeout` option:
119
-
120
- <!-- prettier-ignore -->
121
- ```ts
122
- // Configure the default for all requests:
123
- const client = new Partnermax({
124
- timeout: 20 * 1000, // 20 seconds (default is 1 minute)
125
- });
126
-
127
- // Override per-request:
128
- await client.dealers.list({
129
- timeout: 5 * 1000,
130
- });
131
- ```
132
-
133
- On timeout, an `APIConnectionTimeoutError` is thrown.
134
-
135
- Note that requests which time out will be [retried twice by default](#retries).
136
-
137
- ## Advanced Usage
138
-
139
- ### Accessing raw Response data (e.g., headers)
140
-
141
- The "raw" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return.
142
- This method returns as soon as the headers for a successful response are received and does not consume the response body, so you are free to write custom parsing or streaming logic.
143
-
144
- You can also use the `.withResponse()` method to get the raw `Response` along with the parsed data.
145
- Unlike `.asResponse()` this method consumes the body, returning once it is parsed.
146
-
147
- <!-- prettier-ignore -->
148
- ```ts
149
- const client = new Partnermax();
150
-
151
- const response = await client.dealers.list().asResponse();
152
- console.log(response.headers.get('X-My-Header'));
153
- console.log(response.statusText); // access the underlying Response object
154
-
155
- const { data: dealers, response: raw } = await client.dealers.list().withResponse();
156
- console.log(raw.headers.get('X-My-Header'));
157
- console.log(dealers.data);
158
- ```
159
-
160
- ### Logging
161
-
162
- > [!IMPORTANT]
163
- > All log messages are intended for debugging only. The format and content of log messages
164
- > may change between releases.
165
-
166
- #### Log levels
167
-
168
- The log level can be configured in two ways:
169
-
170
- 1. Via the `PARTNERMAX_LOG` environment variable
171
- 2. Using the `logLevel` client option (overrides the environment variable if set)
172
-
173
- ```ts
174
- import Partnermax from 'partnermax';
175
-
176
- const client = new Partnermax({
177
- logLevel: 'debug', // Show all log messages
178
- });
179
- ```
180
-
181
- Available log levels, from most to least verbose:
182
-
183
- - `'debug'` - Show debug messages, info, warnings, and errors
184
- - `'info'` - Show info messages, warnings, and errors
185
- - `'warn'` - Show warnings and errors (default)
186
- - `'error'` - Show only errors
187
- - `'off'` - Disable all logging
188
-
189
- At the `'debug'` level, all HTTP requests and responses are logged, including headers and bodies.
190
- Some authentication-related headers are redacted, but sensitive data in request and response bodies
191
- may still be visible.
192
-
193
- #### Custom logger
194
-
195
- By default, this library logs to `globalThis.console`. You can also provide a custom logger.
196
- Most logging libraries are supported, including [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale), and [@std/log](https://jsr.io/@std/log). If your logger doesn't work, please open an issue.
197
-
198
- When providing a custom logger, the `logLevel` option still controls which messages are emitted, messages
199
- below the configured level will not be sent to your logger.
200
-
201
- ```ts
202
- import Partnermax from 'partnermax';
203
- import pino from 'pino';
204
-
205
- const logger = pino();
206
-
207
- const client = new Partnermax({
208
- logger: logger.child({ name: 'Partnermax' }),
209
- logLevel: 'debug', // Send all messages to pino, allowing it to filter
210
- });
211
- ```
212
-
213
- ### Making custom/undocumented requests
214
-
215
- This library is typed for convenient access to the documented API. If you need to access undocumented
216
- endpoints, params, or response properties, the library can still be used.
217
-
218
- #### Undocumented endpoints
219
-
220
- To make requests to undocumented endpoints, you can use `client.get`, `client.post`, and other HTTP verbs.
221
- Options on the client, such as retries, will be respected when making these requests.
222
-
223
- ```ts
224
- await client.post('/some/path', {
225
- body: { some_prop: 'foo' },
226
- query: { some_query_arg: 'bar' },
227
- });
228
- ```
229
-
230
- #### Undocumented request params
231
-
232
- To make requests using undocumented parameters, you may use `// @ts-expect-error` on the undocumented
233
- parameter. This library doesn't validate at runtime that the request matches the type, so any extra values you
234
- send will be sent as-is.
235
-
236
- ```ts
237
- client.dealers.create({
238
- // ...
239
- // @ts-expect-error baz is not yet public
240
- baz: 'undocumented option',
241
- });
242
- ```
243
-
244
- For requests with the `GET` verb, any extra params will be in the query, all other requests will send the
245
- extra param in the body.
246
-
247
- If you want to explicitly send an extra argument, you can do so with the `query`, `body`, and `headers` request
248
- options.
249
-
250
- #### Undocumented response properties
251
-
252
- To access undocumented response properties, you may access the response object with `// @ts-expect-error` on
253
- the response object, or cast the response object to the requisite type. Like the request params, we do not
254
- validate or strip extra properties from the response from the API.
255
-
256
- ### Customizing the fetch client
257
-
258
- By default, this library expects a global `fetch` function is defined.
259
-
260
- If you want to use a different `fetch` function, you can either polyfill the global:
261
-
262
- ```ts
263
- import fetch from 'my-fetch';
264
-
265
- globalThis.fetch = fetch;
266
- ```
267
-
268
- Or pass it to the client:
269
-
270
- ```ts
271
- import Partnermax from 'partnermax';
272
- import fetch from 'my-fetch';
273
-
274
- const client = new Partnermax({ fetch });
275
- ```
276
-
277
- ### Fetch options
278
-
279
- If you want to set custom `fetch` options without overriding the `fetch` function, you can provide a `fetchOptions` object when instantiating the client or making a request. (Request-specific options override client options.)
280
-
281
- ```ts
282
- import Partnermax from 'partnermax';
283
-
284
- const client = new Partnermax({
285
- fetchOptions: {
286
- // `RequestInit` options
287
- },
288
- });
289
- ```
290
-
291
- #### Configuring proxies
292
-
293
- To modify proxy behavior, you can provide custom `fetchOptions` that add runtime-specific proxy
294
- options to requests:
295
-
296
- <img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/node.svg" align="top" width="18" height="21"> **Node** <sup>[[docs](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)]</sup>
297
-
298
- ```ts
299
- import Partnermax from 'partnermax';
300
- import * as undici from 'undici';
301
-
302
- const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
303
- const client = new Partnermax({
304
- fetchOptions: {
305
- dispatcher: proxyAgent,
306
- },
307
- });
308
- ```
309
-
310
- <img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/bun.svg" align="top" width="18" height="21"> **Bun** <sup>[[docs](https://bun.sh/guides/http/proxy)]</sup>
311
-
312
- ```ts
313
- import Partnermax from 'partnermax';
314
-
315
- const client = new Partnermax({
316
- fetchOptions: {
317
- proxy: 'http://localhost:8888',
318
- },
319
- });
320
- ```
321
-
322
- <img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/deno.svg" align="top" width="18" height="21"> **Deno** <sup>[[docs](https://docs.deno.com/api/deno/~/Deno.createHttpClient)]</sup>
323
-
324
- ```ts
325
- import Partnermax from 'npm:partnermax';
326
-
327
- const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
328
- const client = new Partnermax({
329
- fetchOptions: {
330
- client: httpClient,
331
- },
332
- });
333
- ```
334
-
335
- ## Frequently Asked Questions
336
-
337
- ## Semantic versioning
338
-
339
- This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:
340
-
341
- 1. Changes that only affect static types, without breaking runtime behavior.
342
- 2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_
343
- 3. Changes that we do not expect to impact the vast majority of users in practice.
344
-
345
- We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
346
-
347
- We are keen for your feedback; please open an [issue](https://www.github.com/DealerMax-app/partnermax-node/issues) with questions, bugs, or suggestions.
348
-
349
- ## Requirements
350
-
351
- TypeScript >= 4.9 is supported.
352
-
353
- The following runtimes are supported:
354
-
355
- - Web browsers (Up-to-date Chrome, Firefox, Safari, Edge, and more)
356
- - Node.js 20 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.
357
- - Deno v1.28.0 or higher.
358
- - Bun 1.0 or later.
359
- - Cloudflare Workers.
360
- - Vercel Edge Runtime.
361
- - Jest 28 or greater with the `"node"` environment (`"jsdom"` is not supported at this time).
362
- - Nitro v2.6 or greater.
363
-
364
- Note that React Native is not supported at this time.
365
-
366
- If you are interested in other runtime environments, please open or upvote an issue on GitHub.
367
-
368
- ## Contributing
369
-
370
- See [the contributing documentation](./CONTRIBUTING.md).
1
+ # Partnermax TypeScript API Library
2
+
3
+ [![NPM version](<https://img.shields.io/npm/v/partnermax.svg?label=npm%20(stable)>)](https://npmjs.org/package/partnermax) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/partnermax)
4
+
5
+ This library provides convenient access to the Partnermax REST API from server-side TypeScript or JavaScript.
6
+
7
+ The REST API documentation can be found on [developers.dealermax.app](https://developers.dealermax.app). The full API of this library can be found in [api.md](api.md).
8
+
9
+ It is generated with [Stainless](https://www.stainless.com/).
10
+
11
+ ## Installation
12
+
13
+ ```sh
14
+ npm install partnermax
15
+ ```
16
+
17
+ ## Usage
18
+
19
+ The full API of this library can be found in [api.md](api.md).
20
+
21
+ <!-- prettier-ignore -->
22
+ ```js
23
+ import Partnermax from 'partnermax';
24
+
25
+ const client = new Partnermax({
26
+ apiKey: process.env['PARTNERMAX_API_KEY'], // This is the default and can be omitted
27
+ environment: 'sandbox', // defaults to 'production'
28
+ });
29
+
30
+ const page = await client.dealers.list({ limit: 10, status: 'active' });
31
+ const dealerSummary = page.data[0];
32
+
33
+ console.log(dealerSummary.dealer_id);
34
+ ```
35
+
36
+ ### Request & Response types
37
+
38
+ This library includes TypeScript definitions for all request params and response fields. You may import and use them like so:
39
+
40
+ <!-- prettier-ignore -->
41
+ ```ts
42
+ import Partnermax from 'partnermax';
43
+
44
+ const client = new Partnermax({
45
+ apiKey: process.env['PARTNERMAX_API_KEY'], // This is the default and can be omitted
46
+ environment: 'sandbox', // defaults to 'production'
47
+ });
48
+
49
+ const [dealerSummary]: [Partnermax.DealerSummary] = await client.dealers.list();
50
+ ```
51
+
52
+ Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.
53
+
54
+ ## Handling errors
55
+
56
+ When the library is unable to connect to the API,
57
+ or if the API returns a non-success status code (i.e., 4xx or 5xx response),
58
+ a subclass of `APIError` will be thrown:
59
+
60
+ <!-- prettier-ignore -->
61
+ ```ts
62
+ const page = await client.dealers.list().catch(async (err) => {
63
+ if (err instanceof Partnermax.APIError) {
64
+ console.log(err.status); // 400
65
+ console.log(err.name); // BadRequestError
66
+ console.log(err.headers); // {server: 'nginx', ...}
67
+ } else {
68
+ throw err;
69
+ }
70
+ });
71
+ ```
72
+
73
+ Error codes are as follows:
74
+
75
+ | Status Code | Error Type |
76
+ | ----------- | -------------------------- |
77
+ | 400 | `BadRequestError` |
78
+ | 401 | `AuthenticationError` |
79
+ | 403 | `PermissionDeniedError` |
80
+ | 404 | `NotFoundError` |
81
+ | 422 | `UnprocessableEntityError` |
82
+ | 429 | `RateLimitError` |
83
+ | >=500 | `InternalServerError` |
84
+ | N/A | `APIConnectionError` |
85
+
86
+ ### Retries
87
+
88
+ Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
89
+ Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,
90
+ 429 Rate Limit, and >=500 Internal errors will all be retried by default.
91
+
92
+ You can use the `maxRetries` option to configure or disable this:
93
+
94
+ <!-- prettier-ignore -->
95
+ ```js
96
+ // Configure the default for all requests:
97
+ const client = new Partnermax({
98
+ maxRetries: 0, // default is 2
99
+ });
100
+
101
+ // Or, configure per-request:
102
+ await client.dealers.list({
103
+ maxRetries: 5,
104
+ });
105
+ ```
106
+
107
+ ### Timeouts
108
+
109
+ Requests time out after 1 minute by default. You can configure this with a `timeout` option:
110
+
111
+ <!-- prettier-ignore -->
112
+ ```ts
113
+ // Configure the default for all requests:
114
+ const client = new Partnermax({
115
+ timeout: 20 * 1000, // 20 seconds (default is 1 minute)
116
+ });
117
+
118
+ // Override per-request:
119
+ await client.dealers.list({
120
+ timeout: 5 * 1000,
121
+ });
122
+ ```
123
+
124
+ On timeout, an `APIConnectionTimeoutError` is thrown.
125
+
126
+ Note that requests which time out will be [retried twice by default](#retries).
127
+
128
+ ## Auto-pagination
129
+
130
+ List methods in the Partnermax API are paginated.
131
+ You can use the `for await … of` syntax to iterate through items across all pages:
132
+
133
+ ```ts
134
+ async function fetchAllDealerSummaries(params) {
135
+ const allDealerSummaries = [];
136
+ // Automatically fetches more pages as needed.
137
+ for await (const dealerSummary of client.dealers.list({ limit: 10, status: 'active' })) {
138
+ allDealerSummaries.push(dealerSummary);
139
+ }
140
+ return allDealerSummaries;
141
+ }
142
+ ```
143
+
144
+ Alternatively, you can request a single page at a time:
145
+
146
+ ```ts
147
+ let page = await client.dealers.list({ limit: 10, status: 'active' });
148
+ for (const dealerSummary of page.data) {
149
+ console.log(dealerSummary);
150
+ }
151
+
152
+ // Convenience methods are provided for manually paginating:
153
+ while (page.hasNextPage()) {
154
+ page = await page.getNextPage();
155
+ // ...
156
+ }
157
+ ```
158
+
159
+ ## Advanced Usage
160
+
161
+ ### Accessing raw Response data (e.g., headers)
162
+
163
+ The "raw" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return.
164
+ This method returns as soon as the headers for a successful response are received and does not consume the response body, so you are free to write custom parsing or streaming logic.
165
+
166
+ You can also use the `.withResponse()` method to get the raw `Response` along with the parsed data.
167
+ Unlike `.asResponse()` this method consumes the body, returning once it is parsed.
168
+
169
+ <!-- prettier-ignore -->
170
+ ```ts
171
+ const client = new Partnermax();
172
+
173
+ const response = await client.dealers.list().asResponse();
174
+ console.log(response.headers.get('X-My-Header'));
175
+ console.log(response.statusText); // access the underlying Response object
176
+
177
+ const { data: page, response: raw } = await client.dealers.list().withResponse();
178
+ console.log(raw.headers.get('X-My-Header'));
179
+ for await (const dealerSummary of page) {
180
+ console.log(dealerSummary.dealer_id);
181
+ }
182
+ ```
183
+
184
+ ### Logging
185
+
186
+ > [!IMPORTANT]
187
+ > All log messages are intended for debugging only. The format and content of log messages
188
+ > may change between releases.
189
+
190
+ #### Log levels
191
+
192
+ The log level can be configured in two ways:
193
+
194
+ 1. Via the `PARTNERMAX_LOG` environment variable
195
+ 2. Using the `logLevel` client option (overrides the environment variable if set)
196
+
197
+ ```ts
198
+ import Partnermax from 'partnermax';
199
+
200
+ const client = new Partnermax({
201
+ logLevel: 'debug', // Show all log messages
202
+ });
203
+ ```
204
+
205
+ Available log levels, from most to least verbose:
206
+
207
+ - `'debug'` - Show debug messages, info, warnings, and errors
208
+ - `'info'` - Show info messages, warnings, and errors
209
+ - `'warn'` - Show warnings and errors (default)
210
+ - `'error'` - Show only errors
211
+ - `'off'` - Disable all logging
212
+
213
+ At the `'debug'` level, all HTTP requests and responses are logged, including headers and bodies.
214
+ Some authentication-related headers are redacted, but sensitive data in request and response bodies
215
+ may still be visible.
216
+
217
+ #### Custom logger
218
+
219
+ By default, this library logs to `globalThis.console`. You can also provide a custom logger.
220
+ Most logging libraries are supported, including [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale), and [@std/log](https://jsr.io/@std/log). If your logger doesn't work, please open an issue.
221
+
222
+ When providing a custom logger, the `logLevel` option still controls which messages are emitted, messages
223
+ below the configured level will not be sent to your logger.
224
+
225
+ ```ts
226
+ import Partnermax from 'partnermax';
227
+ import pino from 'pino';
228
+
229
+ const logger = pino();
230
+
231
+ const client = new Partnermax({
232
+ logger: logger.child({ name: 'Partnermax' }),
233
+ logLevel: 'debug', // Send all messages to pino, allowing it to filter
234
+ });
235
+ ```
236
+
237
+ ### Making custom/undocumented requests
238
+
239
+ This library is typed for convenient access to the documented API. If you need to access undocumented
240
+ endpoints, params, or response properties, the library can still be used.
241
+
242
+ #### Undocumented endpoints
243
+
244
+ To make requests to undocumented endpoints, you can use `client.get`, `client.post`, and other HTTP verbs.
245
+ Options on the client, such as retries, will be respected when making these requests.
246
+
247
+ ```ts
248
+ await client.post('/some/path', {
249
+ body: { some_prop: 'foo' },
250
+ query: { some_query_arg: 'bar' },
251
+ });
252
+ ```
253
+
254
+ #### Undocumented request params
255
+
256
+ To make requests using undocumented parameters, you may use `// @ts-expect-error` on the undocumented
257
+ parameter. This library doesn't validate at runtime that the request matches the type, so any extra values you
258
+ send will be sent as-is.
259
+
260
+ ```ts
261
+ client.dealers.list({
262
+ // ...
263
+ // @ts-expect-error baz is not yet public
264
+ baz: 'undocumented option',
265
+ });
266
+ ```
267
+
268
+ For requests with the `GET` verb, any extra params will be in the query, all other requests will send the
269
+ extra param in the body.
270
+
271
+ If you want to explicitly send an extra argument, you can do so with the `query`, `body`, and `headers` request
272
+ options.
273
+
274
+ #### Undocumented response properties
275
+
276
+ To access undocumented response properties, you may access the response object with `// @ts-expect-error` on
277
+ the response object, or cast the response object to the requisite type. Like the request params, we do not
278
+ validate or strip extra properties from the response from the API.
279
+
280
+ ### Customizing the fetch client
281
+
282
+ By default, this library expects a global `fetch` function is defined.
283
+
284
+ If you want to use a different `fetch` function, you can either polyfill the global:
285
+
286
+ ```ts
287
+ import fetch from 'my-fetch';
288
+
289
+ globalThis.fetch = fetch;
290
+ ```
291
+
292
+ Or pass it to the client:
293
+
294
+ ```ts
295
+ import Partnermax from 'partnermax';
296
+ import fetch from 'my-fetch';
297
+
298
+ const client = new Partnermax({ fetch });
299
+ ```
300
+
301
+ ### Fetch options
302
+
303
+ If you want to set custom `fetch` options without overriding the `fetch` function, you can provide a `fetchOptions` object when instantiating the client or making a request. (Request-specific options override client options.)
304
+
305
+ ```ts
306
+ import Partnermax from 'partnermax';
307
+
308
+ const client = new Partnermax({
309
+ fetchOptions: {
310
+ // `RequestInit` options
311
+ },
312
+ });
313
+ ```
314
+
315
+ #### Configuring proxies
316
+
317
+ To modify proxy behavior, you can provide custom `fetchOptions` that add runtime-specific proxy
318
+ options to requests:
319
+
320
+ <img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/node.svg" align="top" width="18" height="21"> **Node** <sup>[[docs](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)]</sup>
321
+
322
+ ```ts
323
+ import Partnermax from 'partnermax';
324
+ import * as undici from 'undici';
325
+
326
+ const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
327
+ const client = new Partnermax({
328
+ fetchOptions: {
329
+ dispatcher: proxyAgent,
330
+ },
331
+ });
332
+ ```
333
+
334
+ <img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/bun.svg" align="top" width="18" height="21"> **Bun** <sup>[[docs](https://bun.sh/guides/http/proxy)]</sup>
335
+
336
+ ```ts
337
+ import Partnermax from 'partnermax';
338
+
339
+ const client = new Partnermax({
340
+ fetchOptions: {
341
+ proxy: 'http://localhost:8888',
342
+ },
343
+ });
344
+ ```
345
+
346
+ <img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/deno.svg" align="top" width="18" height="21"> **Deno** <sup>[[docs](https://docs.deno.com/api/deno/~/Deno.createHttpClient)]</sup>
347
+
348
+ ```ts
349
+ import Partnermax from 'npm:partnermax';
350
+
351
+ const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
352
+ const client = new Partnermax({
353
+ fetchOptions: {
354
+ client: httpClient,
355
+ },
356
+ });
357
+ ```
358
+
359
+ ## Frequently Asked Questions
360
+
361
+ ## Semantic versioning
362
+
363
+ This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:
364
+
365
+ 1. Changes that only affect static types, without breaking runtime behavior.
366
+ 2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_
367
+ 3. Changes that we do not expect to impact the vast majority of users in practice.
368
+
369
+ We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
370
+
371
+ We are keen for your feedback; please open an [issue](https://www.github.com/DealerMax-app/partnermax-node/issues) with questions, bugs, or suggestions.
372
+
373
+ ## Requirements
374
+
375
+ TypeScript >= 4.9 is supported.
376
+
377
+ The following runtimes are supported:
378
+
379
+ - Web browsers (Up-to-date Chrome, Firefox, Safari, Edge, and more)
380
+ - Node.js 20 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.
381
+ - Deno v1.28.0 or higher.
382
+ - Bun 1.0 or later.
383
+ - Cloudflare Workers.
384
+ - Vercel Edge Runtime.
385
+ - Jest 28 or greater with the `"node"` environment (`"jsdom"` is not supported at this time).
386
+ - Nitro v2.6 or greater.
387
+
388
+ Note that React Native is not supported at this time.
389
+
390
+ If you are interested in other runtime environments, please open or upvote an issue on GitHub.
391
+
392
+ ## Contributing
393
+
394
+ See [the contributing documentation](./CONTRIBUTING.md).