@sp-api-sdk/common
Version:
Selling Parner API common library
127 lines (90 loc) • 5.12 kB
Markdown
# `@sp-api-sdk/common`
[](https://www.npmjs.com/package/@sp-api-sdk/common)
[](https://github.com/xojs/xo)
Amazon Selling Partner API common package
[<img src="https://files.bizon.solutions/images/logo/bizon-horizontal.png" alt="Bizon" width="250"/>](https://www.bizon.solutions?utm_source=github&utm_medium=readme&utm_campaign=selling-partner-api-sdk)
## Installing
```sh
npm install @sp-api-sdk/common
```
> **Note:** You typically do not need to install this package directly. It is automatically included as a dependency of every API client package.
## Overview
This package provides the shared infrastructure used by all API client packages:
- **Axios instance factory** with authentication, rate limiting, logging, and error handling
- **Region configuration** for NA, EU, and FE endpoints (production and sandbox)
- **Error handling** with `SellingPartnerApiError`
## Client Configuration
The `ClientConfiguration` interface is used by all API client constructors:
```typescript
import { type ClientConfiguration } from "@sp-api-sdk/common";
```
| Option | Type | Required | Description |
| --------------------- | ----------------------- | -------- | ----------------------------------------------- |
| `auth` | `SellingPartnerApiAuth` | Yes | Authentication instance from `@sp-api-sdk/auth` |
| `region` | `'na' \| 'eu' \| 'fe'` | Yes | Selling Partner API region |
| `sandbox` | `boolean` | No | Use sandbox endpoints (default: `false`) |
| `rateLimiting` | `object` | No | Rate limiting retry configuration |
| `logging` | `object` | No | Request/response/error logging configuration |
| `restrictedDataToken` | `string` | No | Restricted Data Token for accessing PII |
| `userAgent` | `string` | No | Custom user-agent header |
## Regions
Three regions are supported, each with production and sandbox endpoints:
| Region | Code | AWS Region | Production Endpoint |
| ------------- | ---- | ---------- | ----------------------------------------- |
| North America | `na` | us-east-1 | `https://sellingpartnerapi-na.amazon.com` |
| Europe | `eu` | eu-west-1 | `https://sellingpartnerapi-eu.amazon.com` |
| Far East | `fe` | us-west-2 | `https://sellingpartnerapi-fe.amazon.com` |
When `sandbox` is set to `true`, the sandbox variant of the endpoint is used (e.g. `https://sandbox.sellingpartnerapi-eu.amazon.com`).
## Rate Limiting
When `rateLimiting.retry` is enabled, the SDK automatically retries HTTP 429 responses. The retry delay is calculated as follows:
1. If the response includes an `x-amzn-ratelimit-limit` header, the delay is derived from it.
2. Otherwise, the SDK falls back to the documented rate limits for the specific endpoint.
3. If no rate limit information is available, a 60-second default delay is used.
You can optionally provide an `onRetry` callback to be notified on every retry:
```typescript
rateLimiting: {
retry: true,
onRetry: ({delay, rateLimit, retryCount, error}) => {
console.log(`Retry #${retryCount}, waiting ${delay}ms (rate limit: ${rateLimit})`)
},
}
```
## Logging
Logging is powered by [axios-logger](https://github.com/hg-pyun/axios-logger) and can be configured independently for requests, responses, and errors:
```typescript
logging: {
request: true, // or a RequestLogConfig object
response: true, // or a ResponseLogConfig object
error: true, // or an ErrorLogConfig object
}
```
Pass `true` to use sensible defaults (no headers logged for requests, headers logged for responses). Pass a configuration object to customize the behavior.
By default, `request` and `response` loggers use `console.info`, and the `error` logger uses `console.error`.
> **Warning:** Enabling `headers: true` in the request logger will log authentication tokens. This should be disabled in production.
## Error Handling
API errors are wrapped in `SellingPartnerApiError`, which extends `AxiosError` and adds context:
```typescript
import { SellingPartnerApiError } from "@sp-api-sdk/common";
try {
await client.searchOrders({ marketplaceIds: ["A1PA6795UKMFR9"] });
} catch (error) {
if (error instanceof SellingPartnerApiError) {
console.error(error.message); // e.g. "orders (2026-01-01) error: Response code 403"
console.error(error.apiName); // e.g. "orders"
console.error(error.apiVersion); // e.g. "2026-01-01"
console.error(error.innerMessage); // Original axios error message
}
}
```
## License
MIT
## Miscellaneous
```
╚⊙ ⊙╝
╚═(███)═╝
╚═(███)═╝
╚═(███)═╝
╚═(███)═╝
╚═(███)═╝
╚═(███)═╝
```