amazon-ads-api-v1 0.11.0__py3-none-any.whl

ads_api/__init__.py

@@ -0,0 +1,25 @@
+"""Amazon Ads API package (Synchronous)."""
+
+from ads_api.base import ClientContext
+from ads_api.client import AdsClient
+from ads_api.client.v0 import AdsClientV0
+from ads_api.client.v1 import AdsClientV1
+from ads_api.config.region import Region
+from ads_api.config.settings import AmazonAdsConfig
+from ads_api.config.token_cache import BaseTokenCache, FileTokenCache, RedisTokenCache
+from ads_api.config.token_manager import TokenCredentials, TokenManager
+
+__all__ = [
+    "AdsClient",
+    "AdsClientV0",
+    "AdsClientV1",
+    "AmazonAdsConfig",
+    "BaseTokenCache",
+    "ClientContext",
+    "FileTokenCache",
+    "RedisTokenCache",
+    "Region",
+    "TokenCredentials",
+    "TokenManager",
+]
+__version__ = "0.11.0"

ads_api/base.py

@@ -0,0 +1,208 @@
+"""Shared HTTP session and base resource class (Synchronous)."""
+
+from __future__ import annotations
+
+import email.utils
+import logging
+import random
+import time
+from collections.abc import Sequence
+from datetime import UTC, datetime
+from typing import Any, Literal, cast, overload
+
+import httpx
+from pydantic import BaseModel, TypeAdapter, ValidationError
+
+from ads_api.config.settings import AmazonAdsConfig
+from ads_api.errors import raise_for_status
+
+logger = logging.getLogger(__name__)
+
+type ResponseMode = Literal["dict", "pydantic", "raw"]
+
+
+def _parse_retry_after(resp: httpx.Response | None, fallback_seconds: float, max_wait: float = 60.0) -> float:
+    """Parse the Retry-After header as seconds or HTTP-Date with fallback."""
+    if resp is None:
+        return fallback_seconds
+    headers = getattr(resp, "headers", None)
+    if headers is None:
+        return fallback_seconds
+    raw = headers.get("Retry-After")
+    if not raw:
+        return fallback_seconds
+    try:
+        seconds = float(raw)
+        if seconds >= 0:
+            return min(seconds + random.uniform(0, 0.5), max_wait)
+    except (ValueError, TypeError):
+        pass
+    try:
+        target_dt = email.utils.parsedate_to_datetime(str(raw))
+        now_dt = datetime.now(UTC)
+        delta = (target_dt - now_dt).total_seconds()
+        if delta > 0:
+            return min(delta + random.uniform(0, 0.5), max_wait)
+    except Exception:
+        pass
+    return fallback_seconds
+
+
+class ClientContext:
+    """Shared HTTP state for all resource instances."""
+
+    __slots__ = ("config", "_client")
+
+    def __init__(self, config: AmazonAdsConfig) -> None:
+        self.config: AmazonAdsConfig = config
+        self._client: httpx.Client | None = None
+
+    def get_client(self) -> httpx.Client:
+        if self._client is None:
+            self._client = httpx.Client(base_url=self.config.base_url, timeout=httpx.Timeout(self.config.timeout))
+        return self._client
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+        if self.config._token_manager is not None:
+            self.config._token_manager.close()
+
+    def __enter__(self) -> ClientContext:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class BaseResource:
+    """HTTP helpers shared by generated resource classes."""
+
+    __slots__ = ("_ctx", "exclude_unset", "exclude_none")
+
+    def __init__(self, ctx: ClientContext, exclude_unset: bool = True, exclude_none: bool = True) -> None:
+        self._ctx: ClientContext = ctx
+        self.exclude_unset = exclude_unset
+        self.exclude_none = exclude_none
+
+    @overload
+    def dump_json(self, body: None) -> dict[str, Any]: ...
+    @overload
+    def dump_json(self, body: BaseModel) -> dict[str, Any]: ...
+    @overload
+    def dump_json(self, body: Sequence[BaseModel]) -> list[Any]: ...
+    def dump_json(self, body: BaseModel | Sequence[BaseModel] | None) -> dict[str, Any] | list[Any]:
+        """Serialize a request body. ``None`` becomes ``{}`` so optional OpenAPI bodies omit fields."""
+        if isinstance(body, BaseModel):
+            return body.model_dump(mode="json", exclude_unset=self.exclude_unset, exclude_none=self.exclude_none)
+        if body is None:
+            return {}
+        return [
+            item.model_dump(mode="json", exclude_unset=self.exclude_unset, exclude_none=self.exclude_none)
+            for item in body
+        ]
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | list[Any] | None = None,
+        headers: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        client = self._ctx.get_client()
+        if self._ctx.config._token_manager is not None:
+            token: str = self._ctx.config.refresh_access_token()
+        else:
+            token = self._ctx.config.access_token or ""
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/json",
+            "Amazon-Ads-ClientId": self._ctx.config.client_id,
+            "Amazon-Advertising-API-ClientId": self._ctx.config.client_id,
+            **(headers or {}),
+        }
+        if self._ctx.config.profile_id is not None:
+            headers["Amazon-Advertising-API-Scope"] = self._ctx.config.profile_id
+        if self._ctx.config.account_id is not None:
+            headers["Amazon-Ads-AccountId"] = self._ctx.config.account_id
+        for attempt in range(self._ctx.config.max_retries):
+            try:
+                resp = client.request(
+                    method=method,
+                    url=path,
+                    params=params,
+                    json=json,
+                    headers=headers,
+                )
+                if resp.is_error:
+                    if resp.status_code == 401 and self._ctx.config._token_manager is not None and attempt == 0:
+                        token = self._ctx.config.refresh_access_token(force=True)
+                        headers["Authorization"] = f"Bearer {token}"
+                        continue
+                    if resp.status_code in (429, 503, 504) and attempt < self._ctx.config.max_retries - 1:
+                        fallback = 2**attempt + random.uniform(0, 1)
+                        wait_time = _parse_retry_after(resp, fallback_seconds=fallback)
+                        logger.warning("Rate limit exceeded, retrying in %.2f seconds %s", wait_time, resp.status_code)
+                        time.sleep(wait_time)
+                        continue
+                    logger.error("%s %s", resp.status_code, resp.text)
+                    raise_for_status(resp)
+                return resp
+            except (httpx.ConnectError, httpx.TimeoutException, httpx.RemoteProtocolError):
+                if attempt < self._ctx.config.max_retries - 1:
+                    time.sleep(2**attempt + random.uniform(0, 1))
+                    continue
+                raise
+        raise RuntimeError("Retry loop exited unexpectedly")
+
+    @overload
+    def _response[T: BaseModel](
+        self, model_cls: type[T], resp: httpx.Response, *, mode: Literal["dict"] = "dict"
+    ) -> dict[str, Any]: ...
+    @overload
+    def _response[T: BaseModel](self, model_cls: type[T], resp: httpx.Response, *, mode: Literal["pydantic"]) -> T: ...
+    @overload
+    def _response[T: BaseModel](
+        self, model_cls: type[T], resp: httpx.Response, *, mode: Literal["raw"]
+    ) -> httpx.Response: ...
+    def _response[T: BaseModel](
+        self, model_cls: type[T], resp: httpx.Response, *, mode: ResponseMode = "dict"
+    ) -> T | dict[str, Any] | httpx.Response:
+        if mode == "raw":
+            return resp
+        if mode == "dict":
+            return cast(dict[str, Any], resp.json())
+        try:
+            return model_cls.model_validate_json(resp.text)
+        except ValidationError:
+            logger.error("Failed to parse response as %s: %s", model_cls.__name__, resp.text)
+            raise
+
+    @overload
+    def _response_list[T: BaseModel](
+        self, model_cls: type[T], resp: httpx.Response, *, mode: Literal["dict"] = "dict"
+    ) -> list[dict[str, Any]]: ...
+    @overload
+    def _response_list[T: BaseModel](
+        self, model_cls: type[T], resp: httpx.Response, *, mode: Literal["pydantic"]
+    ) -> list[T]: ...
+    @overload
+    def _response_list[T: BaseModel](
+        self, model_cls: type[T], resp: httpx.Response, *, mode: Literal["raw"]
+    ) -> httpx.Response: ...
+    def _response_list[T: BaseModel](
+        self, model_cls: type[T], resp: httpx.Response, *, mode: ResponseMode = "dict"
+    ) -> list[T] | list[dict[str, Any]] | httpx.Response:
+        if mode == "raw":
+            return resp
+        if mode == "dict":
+            return cast(list[dict[str, Any]], resp.json())
+        try:
+            list_type: Any = list[model_cls]  # type: ignore[valid-type]
+            return TypeAdapter[list[T]](list_type).validate_json(resp.text)
+        except ValidationError:
+            logger.error("Failed to parse response list as %s: %s", model_cls.__name__, resp.text)
+            raise

ads_api/client/__init__.py

@@ -0,0 +1,103 @@
+"""Amazon Ads API synchronous clients."""
+
+from __future__ import annotations
+
+from typing import Any, overload
+
+from ads_api.base import ClientContext
+from ads_api.client.v0 import AdsClientV0
+from ads_api.client.v1 import AdsClientV1
+from ads_api.config.settings import AmazonAdsConfig
+from ads_api.errors import MissingConfigError
+
+__all__ = ["AdsClient", "AdsClientV0", "AdsClientV1"]
+
+
+class AdsClient:
+    """Unified synchronous client for Amazon Ads API v0 and v1.
+
+    v0 and v1 share one HTTP session and token. Use the version clients
+    directly when you only need one API generation:
+
+        with AdsClient(config) as ads:
+            ads.v0.accounts.profiles.list_profiles()
+            ads.v1.sp.campaigns.create_campaign(body)
+    """
+
+    @overload
+    def __init__(self, config: AmazonAdsConfig) -> None: ...
+
+    @overload
+    def __init__(self, *, ctx: ClientContext) -> None: ...
+
+    def __init__(self, config: AmazonAdsConfig | None = None, *, ctx: ClientContext | None = None) -> None:
+        if ctx is not None:
+            self._ctx = ctx
+            self._owns_ctx = False
+        elif config is not None:
+            self._ctx = ClientContext(config)
+            self._owns_ctx = True
+        else:
+            raise MissingConfigError()
+        self.__v0: AdsClientV0 | None = None
+        self.__v1: AdsClientV1 | None = None
+
+    def __enter__(self) -> AdsClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._owns_ctx:
+            self._ctx.close()
+
+    @property
+    def config(self) -> AmazonAdsConfig:
+        return self._ctx.config
+
+    @property
+    def context(self) -> ClientContext:
+        return self._ctx
+
+    @property
+    def account_id(self) -> str | None:
+        """Get the advertiser account ID bound to this client."""
+        return self._ctx.config.account_id
+
+    @property
+    def profile_id(self) -> str | None:
+        """Get the profile ID bound to this client."""
+        return self._ctx.config.profile_id
+
+    @property
+    def account_type(self) -> str | None:
+        """Get the account type bound to this client (e.g. 'seller' or 'vendor')."""
+        return self._ctx.config.account_type
+
+    @property
+    def is_seller(self) -> bool:
+        """Whether the bound account is a seller account."""
+        return self._ctx.config.account_type == "seller"
+
+    @property
+    def is_vendor(self) -> bool:
+        """Whether the bound account is a vendor account."""
+        return self._ctx.config.account_type == "vendor"
+
+    @property
+    def is_agency(self) -> bool:
+        """Whether the bound account is an agency account."""
+        return self._ctx.config.account_type == "agency"
+
+    @property
+    def v0(self) -> AdsClientV0:
+        if self.__v0 is None:
+            self.__v0 = AdsClientV0(ctx=self._ctx)
+        return self.__v0
+
+    @property
+    def v1(self) -> AdsClientV1:
+        if self.__v1 is None:
+            self.__v1 = AdsClientV1(ctx=self._ctx)
+        return self.__v1

ads_api/client/v0/__init__.py

@@ -0,0 +1,132 @@
+"""Amazon Ads API v0 synchronous client."""
+
+from __future__ import annotations
+
+from typing import Any, overload
+
+from ads_api.base import ClientContext
+from ads_api.client.v0.accounts import Accounts
+from ads_api.client.v0.ads_data_manager import AdsDataManager
+from ads_api.client.v0.discovery import Discovery
+from ads_api.client.v0.exports import Exports
+from ads_api.client.v0.portfolios import Portfolios
+from ads_api.client.v0.products import Products
+from ads_api.client.v0.reporting import Reporting
+from ads_api.client.v0.sb_v4 import SBV4
+from ads_api.client.v0.sd import SD
+from ads_api.client.v0.sp_v3 import SPV3
+from ads_api.config.settings import AmazonAdsConfig
+from ads_api.errors import MissingConfigError
+
+
+class AdsClientV0:
+    """Synchronous client for Amazon Ads API v0.
+
+    with AdsClientV0(config) as ads:
+        ads.accounts.profiles.list_profiles()
+        ads.reporting.reports.create_async_report(body)
+        ads.portfolios.list_portfolios(body)
+        ads.sp_v3.campaigns.create_sponsored_products_campaigns(body)
+        ads.sd.campaigns.list_campaigns()
+    """
+
+    @overload
+    def __init__(self, config: AmazonAdsConfig) -> None: ...
+
+    @overload
+    def __init__(self, *, ctx: ClientContext) -> None: ...
+
+    def __init__(
+        self,
+        config: AmazonAdsConfig | None = None,
+        *,
+        ctx: ClientContext | None = None,
+    ) -> None:
+        if ctx is not None:
+            self._ctx = ctx
+            self._owns_ctx = False
+        elif config is not None:
+            self._ctx = ClientContext(config)
+            self._owns_ctx = True
+        else:
+            raise MissingConfigError()
+        self.__accounts: Accounts | None = None
+        self.__reporting: Reporting | None = None
+        self.__ads_data_manager: AdsDataManager | None = None
+        self.__exports: Exports | None = None
+        self.__discovery: Discovery | None = None
+        self.__portfolios: Portfolios | None = None
+        self.__products: Products | None = None
+        self.__sp_v3: SPV3 | None = None
+        self.__sb_v4: SBV4 | None = None
+        self.__sd: SD | None = None
+
+    def __enter__(self) -> AdsClientV0:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._owns_ctx:
+            self._ctx.close()
+
+    @property
+    def accounts(self) -> Accounts:
+        if self.__accounts is None:
+            self.__accounts = Accounts(self._ctx)
+        return self.__accounts
+
+    @property
+    def reporting(self) -> Reporting:
+        if self.__reporting is None:
+            self.__reporting = Reporting(self._ctx)
+        return self.__reporting
+
+    @property
+    def ads_data_manager(self) -> AdsDataManager:
+        if self.__ads_data_manager is None:
+            self.__ads_data_manager = AdsDataManager(self._ctx)
+        return self.__ads_data_manager
+
+    @property
+    def exports(self) -> Exports:
+        if self.__exports is None:
+            self.__exports = Exports(self._ctx)
+        return self.__exports
+
+    @property
+    def discovery(self) -> Discovery:
+        if self.__discovery is None:
+            self.__discovery = Discovery(self._ctx)
+        return self.__discovery
+
+    @property
+    def portfolios(self) -> Portfolios:
+        if self.__portfolios is None:
+            self.__portfolios = Portfolios(self._ctx)
+        return self.__portfolios
+
+    @property
+    def products(self) -> Products:
+        if self.__products is None:
+            self.__products = Products(self._ctx)
+        return self.__products
+
+    @property
+    def sp_v3(self) -> SPV3:
+        if self.__sp_v3 is None:
+            self.__sp_v3 = SPV3(self._ctx)
+        return self.__sp_v3
+
+    @property
+    def sb_v4(self) -> SBV4:
+        if self.__sb_v4 is None:
+            self.__sb_v4 = SBV4(self._ctx)
+        return self.__sb_v4
+
+    @property
+    def sd(self) -> SD:
+        if self.__sd is None:
+            self.__sd = SD(self._ctx)
+        return self.__sd

ads_api/client/v0/accounts/__init__.py

@@ -0,0 +1,77 @@
+"""Accounts resource namespace — v0 Accounts APIs."""
+
+from __future__ import annotations
+
+from ads_api.base import ClientContext
+
+from .advertising_accounts import AdvertisingAccounts
+from .dsp_advertisers import DSPAdvertisers
+from .manager_accounts import ManagerAccounts
+from .profiles import Profiles
+from .terms_token import TermsToken
+from .test_accounts import TestAccounts
+from .user_invitations import UserInvitations
+from .user_permissions import UserPermissions
+
+
+class Accounts:
+    """Lazy Accounts resources."""
+
+    def __init__(self, ctx: ClientContext) -> None:
+        self._ctx = ctx
+        self.__advertising_accounts: AdvertisingAccounts | None = None
+        self.__dsp_advertisers: DSPAdvertisers | None = None
+        self.__manager_accounts: ManagerAccounts | None = None
+        self.__profiles: Profiles | None = None
+        self.__terms_token: TermsToken | None = None
+        self.__test_accounts: TestAccounts | None = None
+        self.__user_invitations: UserInvitations | None = None
+        self.__user_permissions: UserPermissions | None = None
+
+    @property
+    def advertising_accounts(self) -> AdvertisingAccounts:
+        if self.__advertising_accounts is None:
+            self.__advertising_accounts = AdvertisingAccounts(self._ctx)
+        return self.__advertising_accounts
+
+    @property
+    def dsp_advertisers(self) -> DSPAdvertisers:
+        if self.__dsp_advertisers is None:
+            self.__dsp_advertisers = DSPAdvertisers(self._ctx)
+        return self.__dsp_advertisers
+
+    @property
+    def manager_accounts(self) -> ManagerAccounts:
+        if self.__manager_accounts is None:
+            self.__manager_accounts = ManagerAccounts(self._ctx)
+        return self.__manager_accounts
+
+    @property
+    def profiles(self) -> Profiles:
+        if self.__profiles is None:
+            self.__profiles = Profiles(self._ctx)
+        return self.__profiles
+
+    @property
+    def terms_token(self) -> TermsToken:
+        if self.__terms_token is None:
+            self.__terms_token = TermsToken(self._ctx)
+        return self.__terms_token
+
+    @property
+    def test_accounts(self) -> TestAccounts:
+        if self.__test_accounts is None:
+            self.__test_accounts = TestAccounts(self._ctx)
+        return self.__test_accounts
+
+    @property
+    def user_invitations(self) -> UserInvitations:
+        if self.__user_invitations is None:
+            self.__user_invitations = UserInvitations(self._ctx)
+        return self.__user_invitations
+
+    @property
+    def user_permissions(self) -> UserPermissions:
+        if self.__user_permissions is None:
+            self.__user_permissions = UserPermissions(self._ctx)
+        return self.__user_permissions

ads_api/client/v0/accounts/advertising_accounts.py

@@ -0,0 +1,96 @@
+"""AdvertisingAccounts resource operations.
+
+Generated from OpenAPI spec (tag: Account).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, overload
+
+import httpx
+
+from ads_api.base import BaseResource
+from ads_api.models.v0.accounts.advertising_accounts import (
+    GetAccountResponseContent,
+    ListAdsAccountsRequestContent,
+    ListAdsAccountsResponseContent,
+    RegisterAdsAccountRequestContent,
+    RegisterAdsAccountResponseContent,
+)
+
+
+class AdvertisingAccounts(BaseResource):
+
+    @overload
+    def get_account(self, advertising_account_id: str, *, mode: Literal["dict"] = "dict") -> dict[str, Any]: ...
+    @overload
+    def get_account(self, advertising_account_id: str, *, mode: Literal["pydantic"]) -> GetAccountResponseContent: ...
+    @overload
+    def get_account(self, advertising_account_id: str, *, mode: Literal["raw"]) -> httpx.Response: ...
+    def get_account(
+        self, advertising_account_id: str, *, mode: Literal["pydantic", "dict", "raw"] = "dict"
+    ) -> GetAccountResponseContent | dict[str, Any] | httpx.Response:
+        """Request attributes of a given advertising account."""
+
+        resp = self._request(
+            "GET",
+            f"/adsAccounts/{advertising_account_id}",
+            headers={"Accept": "application/vnd.accountresource.v1+json"},
+        )
+        return self._response(GetAccountResponseContent, resp, mode=mode)
+
+    @overload
+    def list_ads_accounts(
+        self, body: ListAdsAccountsRequestContent | None = None, *, mode: Literal["dict"] = "dict"
+    ) -> dict[str, Any]: ...
+    @overload
+    def list_ads_accounts(
+        self, body: ListAdsAccountsRequestContent | None = None, *, mode: Literal["pydantic"]
+    ) -> ListAdsAccountsResponseContent: ...
+    @overload
+    def list_ads_accounts(
+        self, body: ListAdsAccountsRequestContent | None = None, *, mode: Literal["raw"]
+    ) -> httpx.Response: ...
+    def list_ads_accounts(
+        self, body: ListAdsAccountsRequestContent | None = None, *, mode: Literal["pydantic", "dict", "raw"] = "dict"
+    ) -> ListAdsAccountsResponseContent | dict[str, Any] | httpx.Response:
+        """List all advertising accounts for the user associated with the access token."""
+
+        resp = self._request(
+            "POST",
+            "/adsAccounts/list",
+            json=self.dump_json(body),
+            headers={
+                "Content-Type": "application/vnd.listaccountsresource.v1+json",
+                "Accept": "application/vnd.listaccountsresource.v1+json",
+            },
+        )
+        return self._response(ListAdsAccountsResponseContent, resp, mode=mode)
+
+    @overload
+    def register_ads_account(
+        self, body: RegisterAdsAccountRequestContent | None = None, *, mode: Literal["dict"] = "dict"
+    ) -> dict[str, Any]: ...
+    @overload
+    def register_ads_account(
+        self, body: RegisterAdsAccountRequestContent | None = None, *, mode: Literal["pydantic"]
+    ) -> RegisterAdsAccountResponseContent: ...
+    @overload
+    def register_ads_account(
+        self, body: RegisterAdsAccountRequestContent | None = None, *, mode: Literal["raw"]
+    ) -> httpx.Response: ...
+    def register_ads_account(
+        self, body: RegisterAdsAccountRequestContent | None = None, *, mode: Literal["pydantic", "dict", "raw"] = "dict"
+    ) -> RegisterAdsAccountResponseContent | dict[str, Any] | httpx.Response:
+        """Create a new advertising account tied to a specific Amazon vendor, seller or author, or to a business who does not sell on Amazon."""
+
+        resp = self._request(
+            "POST",
+            "/adsAccounts",
+            json=self.dump_json(body),
+            headers={
+                "Content-Type": "application/vnd.registeradsaccountresource.v1+json",
+                "Accept": "application/vnd.registeradsaccountresource.v1+json",
+            },
+        )
+        return self._response(RegisterAdsAccountResponseContent, resp, mode=mode)