python-amazon-ad-api 1.1.1__py3-none-any.whl → 1.1.3__py3-none-any.whl

ad_api/api/sb/__init__.py

@@ -20,6 +20,7 @@ from .media import Media
 from .reports import Reports
 from .benchmarks import Benchmarks
 from .themes import Themes
+from .budget_rules import BudgetRules
 
 __all__ = [
     "Brands",
@@ -43,5 +44,6 @@ __all__ = [
     "Media",
     "Reports",
     "Benchmarks",
-    "Themes"
+    "Themes",
+    "BudgetRules",
 ]

ad_api/api/sb/budget_rules.py

@@ -0,0 +1,235 @@
+from ad_api.base import Client, sp_endpoint, fill_query_params, ApiResponse, Utils
+
+
+class BudgetRules(Client):
+    """Sponsored Brands budget rules.
+
+    Documentation: https://advertising.amazon.com/API/docs/en-us/sponsored-brands/4-0/openapi
+
+    Read routes were probed against the live service; the write routes are built
+    from the contract and not exercised, because they change campaign budgets.
+
+    .. note::
+        ``budget_recommendations`` only answers with the versioned media type.
+        Sending ``application/json`` makes the router answer ``404 Could not find
+        resource``, as if the route did not exist. Amazon routes on media type.
+
+    .. note::
+        An unknown ``budgetRuleId`` answers ``400 InvalidParameterValue`` with
+        ``errorCode 240002``, not a 404. The identifier is validated before it is
+        looked up.
+    """
+
+    _MEDIA_JSON = 'application/json'
+    _MEDIA_USAGE = 'application/vnd.sbcampaignbudgetusage.v1+json'
+    _MEDIA_RECS = 'application/vnd.sbbudgetrecommendation.v4+json'
+
+    @sp_endpoint('/sb/budgetRules', method='GET')
+    def list_budget_rules(self, pageSize, **kwargs) -> ApiResponse:
+        """
+        Gets the budget rules of the advertiser.
+
+        Keyword Args
+            | query **pageSize** (number): [required] Results per page.
+            | query **nextToken** (string): Pagination token. [optional]
+
+        Returns:
+            | ApiResponse, with the rules under ``budgetRulesForAdvertiserResponse``
+              and a ``nextToken``.
+        """
+        return self._request(kwargs.pop('path'), params=kwargs,
+                             headers={'Accept': self._MEDIA_JSON})
+
+    @sp_endpoint('/sb/budgetRules/{}', method='GET')
+    def get_budget_rule(self, budgetRuleId, **kwargs) -> ApiResponse:
+        """
+        Gets one budget rule by identifier.
+
+        Keyword Args
+            | path **budgetRuleId** (string): [required]
+        """
+        return self._request(fill_query_params(kwargs.pop('path'), budgetRuleId),
+                             params=kwargs, headers={'Accept': self._MEDIA_JSON})
+
+    @sp_endpoint('/sb/budgetRules/{}/campaigns', method='GET')
+    def list_rule_campaigns(self, budgetRuleId, pageSize, **kwargs) -> ApiResponse:
+        """
+        Gets the campaigns associated with a budget rule.
+
+        Keyword Args
+            | path **budgetRuleId** (string): [required]
+            | query **pageSize** (number): [required]
+            | query **nextToken** (string): [optional]
+        """
+        return self._request(fill_query_params(kwargs.pop('path'), budgetRuleId),
+                             params=kwargs, headers={'Accept': self._MEDIA_JSON})
+
+    @sp_endpoint('/sb/campaigns/{}/budgetRules', method='GET')
+    def list_campaign_rules(self, campaignId, **kwargs) -> ApiResponse:
+        """
+        Gets the budget rules associated with a campaign.
+
+        Keyword Args
+            | path **campaignId** (number): [required]
+
+        Returns:
+            | ApiResponse, with the rules under ``associatedRules``.
+        """
+        return self._request(fill_query_params(kwargs.pop('path'), campaignId),
+                             params=kwargs, headers={'Accept': self._MEDIA_JSON})
+
+    @sp_endpoint('/sb/budgetRules', method='POST')
+    def create_budget_rules(self, budgetRulesDetails, **kwargs) -> ApiResponse:
+        """
+        Creates budget rules.
+
+        Request Body [Required]
+            | **budgetRulesDetails** (array): One entry per rule.
+                | **name** (string): Rule name.
+                | **ruleType** (string): ``SCHEDULE`` or ``PERFORMANCE``.
+                | **budgetIncreaseBy** ({}): ``type`` (``PERCENT``) and ``value``.
+                | **performanceMeasureCondition** ({}): ``metricName`` (``IS``,
+                  ``NTB`` or ``ROAS``), ``comparisonOperator`` (``GREATER_THAN``,
+                  ``LESS_THAN``, ``LESS_THAN_OR_EQUAL_TO``,
+                  ``GREATER_THAN_OR_EQUAL_TO``) and ``threshold``.
+                | **duration** ({}): ``eventTypeRuleDuration`` with ``eventId``, or
+                  ``dateRangeTypeRuleDuration`` with ``startDate``.
+                | **recurrence** ({}): ``type`` (``DAILY`` or ``WEEKLY``),
+                  ``daysOfWeek`` and ``intraDaySchedule``.
+
+        Returns:
+            | ApiResponse, status ``207``.
+
+        .. note::
+            Not probed: creates budget rules on the account.
+        """
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body({'budgetRulesDetails': budgetRulesDetails}, False),
+                             params=kwargs, headers={'Accept': self._MEDIA_JSON,
+                                                     'Content-Type': self._MEDIA_JSON})
+
+    @sp_endpoint('/sb/budgetRules', method='PUT')
+    def update_budget_rules(self, budgetRulesDetails, **kwargs) -> ApiResponse:
+        """
+        Updates budget rules.
+
+        Request Body [Required]
+            | **budgetRulesDetails** (array): Each entry needs ``ruleId`` and may
+              carry ``ruleState`` (``ACTIVE`` or ``PAUSED``) and ``ruleDetails``
+              with the same shape used on creation.
+
+        Returns:
+            | ApiResponse, status ``207``.
+
+        .. note::
+            Not probed: updates live budget rules.
+        """
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body({'budgetRulesDetails': budgetRulesDetails}, False),
+                             params=kwargs, headers={'Accept': self._MEDIA_JSON,
+                                                     'Content-Type': self._MEDIA_JSON})
+
+    @sp_endpoint('/sb/campaigns/{}/budgetRules', method='POST')
+    def associate_budget_rules(self, campaignId, budgetRuleIds, **kwargs) -> ApiResponse:
+        """
+        Associates budget rules with a campaign.
+
+        Keyword Args
+            | path **campaignId** (number): [required]
+
+        Request Body [Required]
+            | **budgetRuleIds** (array of string): [required]
+
+        Returns:
+            | ApiResponse, status ``207``.
+
+        .. note::
+            Not probed: changes which rules apply to a live campaign.
+        """
+        return self._request(fill_query_params(kwargs.pop('path'), campaignId),
+                             data=Utils.convert_body({'budgetRuleIds': budgetRuleIds}, False),
+                             params=kwargs, headers={'Accept': self._MEDIA_JSON,
+                                                     'Content-Type': self._MEDIA_JSON})
+
+    @sp_endpoint('/sb/campaigns/{}/budgetRules/{}', method='DELETE')
+    def disassociate_budget_rule(self, campaignId, budgetRuleId, **kwargs) -> ApiResponse:
+        """
+        Disassociates one budget rule from a campaign.
+
+        Keyword Args
+            | path **campaignId** (number): [required]
+            | path **budgetRuleId** (string): [required]
+
+        Returns:
+            | ApiResponse, status ``200``.
+
+        .. note::
+            Not probed: changes which rules apply to a live campaign.
+        """
+        path = fill_query_params(kwargs.pop('path'), campaignId)
+        return self._request(fill_query_params(path, budgetRuleId),
+                             params=kwargs, headers={'Accept': self._MEDIA_JSON})
+
+    @sp_endpoint('/sb/campaigns/budget/usage', method='POST')
+    def get_budget_usage(self, campaignIds, **kwargs) -> ApiResponse:
+        """
+        Gets budget usage for campaigns.
+
+        Request Body [Required]
+            | **campaignIds** (array of string): [required]
+
+        Returns:
+            | ApiResponse, with per-campaign entries under ``success`` and failures
+              under ``error``. Each success entry carries ``budget``,
+              ``budgetUsagePercent``, ``campaignId``, ``index`` and
+              ``usageUpdatedTimestamp``.
+
+        Example::
+
+            {"success": [{"budget": 10.0, "budgetUsagePercent": 0.0,
+                          "campaignId": "95988386496299", "index": 0,
+                          "usageUpdatedTimestamp": "2026-10-25T00:00:00Z"}],
+             "error": []}
+        """
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body({'campaignIds': campaignIds}, False),
+                             params=kwargs, headers={'Accept': self._MEDIA_USAGE,
+                                                     'Content-Type': self._MEDIA_USAGE})
+
+    @sp_endpoint('/sb/campaigns/budgetRecommendations', method='POST')
+    def get_budget_recommendations(self, campaignIds, **kwargs) -> ApiResponse:
+        """
+        Gets budget recommendations for campaigns.
+
+        Request Body [Required]
+            | **campaignIds** (array of string): [required]
+
+        Returns:
+            | ApiResponse, status ``207``.
+
+        .. warning::
+            This route only answers with its versioned media type. With
+            ``application/json`` the service answers ``404 Could not find
+            resource``, which reads like a missing route but is only the wrong
+            media type.
+        """
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body({'campaignIds': campaignIds}, False),
+                             params=kwargs, headers={'Accept': self._MEDIA_RECS,
+                                                     'Content-Type': self._MEDIA_RECS})
+
+    @sp_endpoint('/sb/campaigns/budgetRules/recommendations', method='POST')
+    def get_budget_rules_recommendation(self, **kwargs) -> ApiResponse:
+        """
+        Gets budget rule recommendations.
+
+        Returns:
+            | ApiResponse
+
+        .. note::
+            Declared in the 3.0 contract, not in 4.0. Not probed.
+        """
+        return self._request(kwargs.pop('path'),
+                             data=Utils.convert_body(kwargs.pop('body', {}), False),
+                             params=kwargs, headers={'Accept': self._MEDIA_JSON,
+                                                     'Content-Type': self._MEDIA_JSON})

ad_api/api/sb/recommendations.py

@@ -2,6 +2,6 @@ from ad_api.base import Client, sp_endpoint, ApiResponse, Utils
 
 
 class Recommendations(Client):
-    @sp_endpoint('/sb​/recommendations​/creative​/headline', method='POST')
+    @sp_endpoint('/sb/recommendations/creative/headline', method='POST')
     def list_recommendations(self, **kwargs) -> ApiResponse:
         return self._request(kwargs.pop('path'), data=Utils.convert_body(kwargs.pop('body'), False), params=kwargs)

ad_api/version.py

@@ -1 +1 @@
-__version__ = "1.1.1"
+__version__ = "1.1.3"

{python_amazon_ad_api-1.1.1.dist-info → python_amazon_ad_api-1.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-amazon-ad-api
-Version: 1.1.1
+Version: 1.1.3
 Summary: Python wrapper for the Amazon Advertising API
 Home-page: https://github.com/denisneuf/python-amazon-ad-api
 Author: Daniel Alvaro

{python_amazon_ad_api-1.1.1.dist-info → python_amazon_ad_api-1.1.3.dist-info}/RECORD

@@ -1,5 +1,5 @@
 ad_api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ad_api/version.py,sha256=q8_5C0f-8mHWNb6mMw02zlYPnEGXBqvOmP3z0CEwZKM,22
+ad_api/version.py,sha256=u9ExJqoMv3fQc8WmLTw4I2FnQo6u4xRrBc6DLy6G1IE,22
 ad_api/api/__init__.py,sha256=E9c0ZyK4vplMlKKEBF8CV5u7P4uSkTMSQsAuSQu5bfY,1514
 ad_api/api/account.py,sha256=CmOvCfHoPWaeTUJvtB0pNoNulZVSz4oMMCKIpVTpHos,2931
 ad_api/api/advertising_test_account.py,sha256=btOVbdk2tBDmyKSJaQbcIFyzNG8KFJVUmTe4p9xMhpU,1507
@@ -24,7 +24,7 @@ ad_api/api/reports.py,sha256=gNmDHLULD2uaJgsMpIbCX9kabwhMXRr9WfZBtHUdsOY,6043
 ad_api/api/stores.py,sha256=7W3RJKZyZOQ3nHzInvK9FDhWTXCH6Xe9a6dCBatEZ-o,2484
 ad_api/api/stream.py,sha256=JpnF8SKniOAHiEnEq1RPrh6tNy-Q2-8GPBTmnlxEXqQ,2989
 ad_api/api/validation_configurations.py,sha256=V3o06uWGwvA_Ly1x2lAiCk35Wo7DC_k8AtHgMdpm6wU,3830
-ad_api/api/sb/__init__.py,sha256=Lb7biv_idmsN6SkObBhQS4hZs3rdeQr0ytSvcl2tfSo,1274
+ad_api/api/sb/__init__.py,sha256=1M9GaWMkwb7_0G-JtgAEMjFRpsLs4Ls2-pVtFIyn9LM,1332
 ad_api/api/sb/ad_creatives_v4.py,sha256=86sF2lhSc3AC6d4P5TXyEnJMBjn9HvsJe4bbCQbSWK0,10508
 ad_api/api/sb/ad_groups.py,sha256=W06Fk0CCsuEYen1Bd8obR6aHpOMhk6tGWNWApecw59c,2882
 ad_api/api/sb/ad_groups_v4.py,sha256=f6KpOrJ2RsCa4aznP8vdGbXp0HGsCmLOvC9yXX2pESc,3669
@@ -32,6 +32,7 @@ ad_api/api/sb/ads_v4.py,sha256=EOn-ts0cPqCwt5vdGq6rkDHyYPoT6vbDP8UQE-TFjmE,7931
 ad_api/api/sb/benchmarks.py,sha256=eeWv2rrRf4ttK-oI1EEEiui_rl_sxJk9yXcu6sDSfhg,3645
 ad_api/api/sb/bid_recommendations.py,sha256=ssO9XwYC9wK2GFaLtcsC-D3cZhDpCclcu1r01LTkZAw,2297
 ad_api/api/sb/brands.py,sha256=XIMDzV0tJoPiOcY0KoCKcyIwYLPMlJ-zkB2SeRVMF4Q,1376
+ad_api/api/sb/budget_rules.py,sha256=8hyJ4yD-myR4atYmTm8KsTSB5ZNfASGe2fxgwRv4SRs,10029
 ad_api/api/sb/campaigns.py,sha256=41yRnrgvx4-9Zra7Zdqtzr2Ptq__YD-mHOWbACaEQOk,13674
 ad_api/api/sb/campaigns_v4.py,sha256=_SfEQhHCS90UaSxOq35mm7NAr2BVpqJ4gzAbauVCZiA,7290
 ad_api/api/sb/forecast.py,sha256=qf2ivhGX3_dv_uMGP9cmrt_x3S7QLg-P_5nCI8bAr00,3967
@@ -42,7 +43,7 @@ ad_api/api/sb/media.py,sha256=5LTeM4AHSDKw_58aTB2nEZhIYdWkztH0syBXaovS1rs,2529
 ad_api/api/sb/negative_keywords.py,sha256=ww3IRbawidDHAaYIkX5SsH2OZKJj4UnCylqqFeq3OoY,6918
 ad_api/api/sb/negative_product_targeting.py,sha256=QbK1EhhzmnNOzGtbkrAZ4HS5OqiLU3nZBmsl1scd2D0,5085
 ad_api/api/sb/product_targeting.py,sha256=o6aB3hIh9jKvi_uTXFi--1hpnPFuXzQ-U9N7VUP_Bz4,5362
-ad_api/api/sb/recommendations.py,sha256=Ck4DLAKLTqwodmQJfih9MUD1sujG6LDjRlSoefKmOC4,356
+ad_api/api/sb/recommendations.py,sha256=_21L8tZPuArmJ30XyR1SKQHQH_yswvF0IMqwD9sLhgY,347
 ad_api/api/sb/reports.py,sha256=icw5DpRrqfj0idEo0NN1GPDpIWQun2h_c2Uwc7CpNUA,3801
 ad_api/api/sb/stores.py,sha256=sLdA6Lp37VR-ldu_sTUZIqc8MbMzysPhNOh05VaKBcA,4371
 ad_api/api/sb/targeting_recommendations.py,sha256=_7NxD5kC-Od11QOuLT03qpLVxEOIZgy-BtzniWK4CI8,2862
@@ -104,8 +105,8 @@ ad_api/base/exceptions.py,sha256=9D3M40ZIlLS0fA-aQh1BTWPOW-Nvf0tRhbA85jFnDJ4,438
 ad_api/base/helpers.py,sha256=naUkDLK466x_OBCPXxMlzRc2nPC6iQ6H_vyUji0MJJ0,2282
 ad_api/base/marketplaces.py,sha256=44lvCcluXNpqTprWQ80e3weSQmQbJoWL-WDSOWVbCyQ,4657
 ad_api/base/utils.py,sha256=_qnCBOvyJTLgaZjJzUWTi38GGLHkQszXELs79133Rb4,5618
-python_amazon_ad_api-1.1.1.dist-info/licenses/LICENSE,sha256=h2rpqlmmLy-4l1tN6KpWAFxx1JEMYeEFrMrZUbx_B_o,1105
-python_amazon_ad_api-1.1.1.dist-info/METADATA,sha256=1fucVhQrMK2AAFptVgk7GJhULzGQMGA4qpReJa7JQUw,20486
-python_amazon_ad_api-1.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python_amazon_ad_api-1.1.1.dist-info/top_level.txt,sha256=nN9twUos-8pkP514ZwpvRU9YL9L2XyQyHsMQFfudGTU,7
-python_amazon_ad_api-1.1.1.dist-info/RECORD,,
+python_amazon_ad_api-1.1.3.dist-info/licenses/LICENSE,sha256=h2rpqlmmLy-4l1tN6KpWAFxx1JEMYeEFrMrZUbx_B_o,1105
+python_amazon_ad_api-1.1.3.dist-info/METADATA,sha256=RB8aZ0VWmVNwW0nR_21GuKzyeNZQFCgFXSQgnKYIxdk,20486
+python_amazon_ad_api-1.1.3.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_amazon_ad_api-1.1.3.dist-info/top_level.txt,sha256=nN9twUos-8pkP514ZwpvRU9YL9L2XyQyHsMQFfudGTU,7
+python_amazon_ad_api-1.1.3.dist-info/RECORD,,