@sp-api-sdk/common/dist/index.d.cts

Selling Parner API common library

import * as axios from 'axios';
import { AxiosError, Method } from 'axios';
import { requestLogger, responseLogger, errorLogger } from 'axios-logger';
import { SellingPartnerApiAuth } from '@sp-api-sdk/auth';

/** Selling Partner API region identifier. */
type SellingPartnerRegion = 'na' | 'eu' | 'fe';
interface RegionConfiguration {
    awsRegion: string;
    endpoints: {
        production: string;
        sandbox: string;
    };
}
/** AWS region and endpoint mapping for each Selling Partner API region. */
declare const sellingPartnerRegions: Record<SellingPartnerRegion, RegionConfiguration>;

type RequestLogConfig = Exclude<Parameters<typeof requestLogger>[1], undefined>;
type ResponseLogConfig = Exclude<Parameters<typeof responseLogger>[1], undefined>;
type ErrorLogConfig = Exclude<Parameters<typeof errorLogger>[1], undefined>;
/** Per-endpoint rate limit definition used for retry delay calculation. */
interface RateLimit {
    /** Regular expression matched against the request URL pathname. */
    urlRegex: RegExp;
    /** Sustained request rate in requests per second. */
    rate: number;
    /** Maximum burst size (number of requests allowed before throttling). */
    burst: number;
    /** HTTP method this rate limit applies to. */
    method: Method;
}
/** Parameters passed to the {@link ClientConfiguration.rateLimiting} `onRetry` callback. */
interface OnRetryParameters {
    /** Delay in milliseconds before the next retry attempt. */
    delay: number;
    /** Rate limit (requests per second) used to calculate the delay, if available. */
    rateLimit?: number;
    /** Number of retry attempts so far. */
    retryCount: number;
    /** The Axios error that triggered the retry. */
    error: AxiosError;
}
/** Configuration options for creating a Selling Partner API Axios instance. */
interface ClientConfiguration {
    /** Authentication handler that provides LWA access tokens. */
    auth: SellingPartnerApiAuth;
    /** Restricted Data Token to use instead of the standard access token. */
    restrictedDataToken?: string;
    /** Selling Partner API region to send requests to. */
    region: SellingPartnerRegion;
    /** Custom `User-Agent` header value. */
    userAgent?: string;
    /** When `true`, requests are sent to the sandbox endpoint. Defaults to `false`. */
    sandbox?: boolean;
    /** Rate-limiting and retry configuration for 429 responses. */
    rateLimiting?: {
        /** When `true`, automatically retries throttled (HTTP 429) requests. */
        retry: boolean;
        /** Optional callback invoked before each retry attempt. */
        onRetry?: (retryInfo: OnRetryParameters) => void;
    };
    /** Axios request/response/error logging configuration. Pass `true` to use defaults. */
    logging?: {
        /** Log outgoing requests. */
        request?: RequestLogConfig | true;
        /** Log incoming responses. */
        response?: ResponseLogConfig | true;
        /** Log request errors. */
        error?: ErrorLogConfig | true;
    };
}
/**
 * Creates a pre-configured Axios instance for a Selling Partner API client.
 *
 * The instance handles authentication, rate-limit retries, error wrapping,
 * and optional request/response logging.
 *
 * @param configuration - Client configuration options.
 * @param rateLimits - Per-endpoint rate limits used for retry delay calculation.
 * @returns An object containing the configured Axios instance and the resolved API endpoint.
 */
declare function createAxiosInstance({ auth, restrictedDataToken, region, userAgent, sandbox, rateLimiting, logging, }: ClientConfiguration, rateLimits: RateLimit[]): {
    axios: axios.AxiosInstance;
    endpoint: string;
};

/**
 * Error thrown when a Selling Partner API request fails.
 *
 * Wraps the underlying Axios error with a message that includes the API name,
 * version, and HTTP status code (or "No response" for network errors).
 */
declare class SellingPartnerApiError<T = unknown, D = any> extends AxiosError<T, D> {
    /** The original error message from the failed HTTP request. */
    readonly innerMessage: string;
    /** The API name extracted from the request URL path (e.g. `"orders"`). */
    readonly apiName?: string;
    /** The API version extracted from the request URL path (e.g. `"v0"`). */
    readonly apiVersion?: string;
    constructor(error: AxiosError<T, D>);
}

export { type ClientConfiguration, type OnRetryParameters, type RateLimit, SellingPartnerApiError, type SellingPartnerRegion, createAxiosInstance, sellingPartnerRegions };