diff --git a/CHANGELOG.md b/CHANGELOG.md index 5359ff3..a232dec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ Given a version number MAJOR.MINOR.PATCH, increment: ## [Unreleased] +### Added +- IssuingStockRule resource ## [0.25.0] - 2026-04-08 ### Added diff --git a/README.md b/README.md index d5fb6fd..b6ae0aa 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ This SDK version is compatible with the Stark Infra API v2. - [EmbossingKit](#query-issuingembossingkits): View your current embossing kits - [Stock](#query-issuingstocks): View your current stock of a certain IssuingDesign linked to an Embosser on the workspace - [Restock](#create-issuingrestocks): Create restock orders of a specific IssuingStock object + - [StockRule](#create-issuingstockrules): Get notified when a specific IssuingStock reaches a minimum balance - [EmbossingRequest](#create-issuingembossingrequests): Create embossing requests - [TokenRequest](#create-an-issuingtokenrequest): Generate the payload to create the token - [Token](#process-token-authorizations): Authorize and manage your tokens @@ -751,6 +752,82 @@ log = starkinfra.issuingrestock.log.get("6310318875607040") print(log) ``` +### Create IssuingStockRules + +You can create rules to be notified whenever a specific IssuingStock reaches a minimum balance. + +```python +import starkinfra + +rules = starkinfra.issuingstockrule.create([ + starkinfra.IssuingStockRule( + minimum_balance=10000, + stock_id="5136459887542272", + emails=["john.doe@enterprise.com"], + phones=["+55 (11) 91234 5678"] + ) +]) + +for rule in rules: + print(rule) +``` + +### Query IssuingStockRules + +You can get a list of created stock rules given some filters. + +```python +import starkinfra +from datetime import date + +rules = starkinfra.issuingstockrule.query( + after=date(2022, 11, 1), + before=date(2022, 12, 1) +) + +for rule in rules: + print(rule) +``` + +### Get an IssuingStockRule + +After its creation, information on a stock rule may be retrieved by its id. + +```python +import starkinfra + +rule = starkinfra.issuingstockrule.get("5664445921492992") + +print(rule) +``` + +### Update an IssuingStockRule + +You can update a specific IssuingStockRule by its id. + +```python +import starkinfra + +rule = starkinfra.issuingstockrule.update( + id="5664445921492992", + minimum_balance=20000 +) + +print(rule) +``` + +### Cancel an IssuingStockRule + +You can also cancel a specific IssuingStockRule by its id. + +```python +import starkinfra + +rule = starkinfra.issuingstockrule.cancel("5664445921492992") + +print(rule) +``` + ### Create IssuingEmbossingRequests You can create a request to emboss a physical card. diff --git a/starkinfra/__init__.py b/starkinfra/__init__.py index e77ce55..14f7115 100644 --- a/starkinfra/__init__.py +++ b/starkinfra/__init__.py @@ -120,6 +120,9 @@ from . import issuingrestock from .issuingrestock.__issuingrestock import IssuingRestock +from . import issuingstockrule +from .issuingstockrule.__issuingstockrule import IssuingStockRule + from . import issuingdesign from .issuingdesign.__issuingdesign import IssuingDesign diff --git a/starkinfra/issuingstockrule/__init__.py b/starkinfra/issuingstockrule/__init__.py new file mode 100644 index 0000000..1679325 --- /dev/null +++ b/starkinfra/issuingstockrule/__init__.py @@ -0,0 +1 @@ +from .__issuingstockrule import create, get, query, page, update, cancel diff --git a/starkinfra/issuingstockrule/__issuingstockrule.py b/starkinfra/issuingstockrule/__issuingstockrule.py new file mode 100644 index 0000000..c2683de --- /dev/null +++ b/starkinfra/issuingstockrule/__issuingstockrule.py @@ -0,0 +1,162 @@ +from starkcore.utils.resource import Resource +from starkcore.utils.checks import check_date, check_datetime +from ..utils import rest + + +class IssuingStockRule(Resource): + """# IssuingStockRule object + The IssuingStockRule object displays the notification rules of a specific IssuingStock. + When the stock balance reaches the minimum balance, the recipients informed in the rule are notified. + ## Parameters (required): + - minimum_balance [integer]: stock balance threshold that triggers a notification. ex: 10000 + - stock_id [string]: IssuingStock unique id to which the rule is linked. ex: "5656565656565656" + ## Parameters (optional): + - tags [list of strings, default None]: list of strings for tagging. ex: ["card", "corporate"] + - emails [list of strings, default None]: list of emails to be notified when the stock reaches the minimum balance. ex: ["john.doe@enterprise.com"] + - phones [list of strings, default None]: list of phones to be notified when the stock reaches the minimum balance. ex: ["+55 (11) 91234 5678"] + ## Attributes (return-only): + - id [string]: unique id returned when IssuingStockRule is created. ex: "5656565656565656" + - status [string]: current IssuingStockRule status. ex: "active", "canceled" + - updated [datetime.datetime]: latest update datetime for the IssuingStockRule. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0) + - created [datetime.datetime]: creation datetime for the IssuingStockRule. ex: datetime.datetime(2020, 3, 10, 10, 30, 0, 0) + """ + + def __init__(self, minimum_balance, stock_id, tags=None, emails=None, phones=None, id=None, + status=None, created=None, updated=None): + Resource.__init__(self, id=id) + + self.minimum_balance = minimum_balance + self.stock_id = stock_id + self.tags = tags + self.emails = emails + self.phones = phones + self.status = status + self.updated = check_datetime(updated) + self.created = check_datetime(created) + + +_resource = {"class": IssuingStockRule, "name": "IssuingStockRule"} + + +def create(rules, user=None): + """# Create IssuingStockRules + Send a list of IssuingStockRule objects for creation at the Stark Infra API + ## Parameters (required): + - rules [list of IssuingStockRule objects]: list of IssuingStockRule objects to be created in the API + ## Parameters (optional): + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkinfra.user was set before function call. + ## Return: + - list of IssuingStockRule objects with updated attributes + """ + return rest.post_multi(resource=_resource, entities=rules, user=user) + + +def get(id, user=None): + """# Retrieve a specific IssuingStockRule + Receive a single IssuingStockRule object previously created in the Stark Infra API by its id + ## Parameters (required): + - id [string]: object unique id. ex: "5656565656565656" + ## Parameters (optional): + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkinfra.user was set before function call. + ## Return: + - IssuingStockRule object with updated attributes + """ + return rest.get_id(resource=_resource, id=id, user=user) + + +def query(limit=None, after=None, before=None, status=None, stock_ids=None, ids=None, + tags=None, user=None): + """# Retrieve IssuingStockRules + Receive a generator of IssuingStockRule objects previously created in the Stark Infra API + ## Parameters (optional): + - limit [integer, default None]: maximum number of objects to be retrieved. Unlimited if None. ex: 35 + - after [datetime.date or string, default None] date filter for objects created only after specified date. ex: datetime.date(2020, 3, 10) + - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10) + - status [list of strings, default None]: filter for status of retrieved objects. ex: ["active", "canceled"] + - stock_ids [list of strings, default None]: list of stock_ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - ids [list of strings, default None]: list of ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - tags [list of strings, default None]: tags to filter retrieved objects. ex: ["card", "corporate"] + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkinfra.user was set before function call. + ## Return: + - generator of IssuingStockRule objects with updated attributes + """ + return rest.get_stream( + resource=_resource, + limit=limit, + after=check_date(after), + before=check_date(before), + status=status, + stock_ids=stock_ids, + ids=ids, + tags=tags, + user=user, + ) + + +def page(cursor=None, limit=None, after=None, before=None, status=None, stock_ids=None, + ids=None, tags=None, user=None): + """# Retrieve paged IssuingStockRules + Receive a list of up to 100 IssuingStockRule objects previously created in the Stark Infra API and the cursor to the next page. + Use this function instead of query if you want to manually page your requests. + ## Parameters (optional): + - cursor [string, default None]: cursor returned on the previous page function call. + - limit [integer, default 100]: maximum number of objects to be retrieved. Max = 100. ex: 35 + - after [datetime.date or string, default None] date filter for objects created only after specified date. ex: datetime.date(2020, 3, 10) + - before [datetime.date or string, default None] date filter for objects created only before specified date. ex: datetime.date(2020, 3, 10) + - status [list of strings, default None]: filter for status of retrieved objects. ex: ["active", "canceled"] + - stock_ids [list of strings, default None]: list of stock_ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - ids [list of strings, default None]: list of ids to filter retrieved objects. ex: ["5656565656565656", "4545454545454545"] + - tags [list of strings, default None]: tags to filter retrieved objects. ex: ["card", "corporate"] + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkinfra.user was set before function call. + ## Return: + - list of IssuingStockRule objects with updated attributes + - cursor to retrieve the next page of IssuingStockRule objects + """ + return rest.get_page( + resource=_resource, + cursor=cursor, + limit=limit, + after=check_date(after), + before=check_date(before), + status=status, + stock_ids=stock_ids, + ids=ids, + tags=tags, + user=user, + ) + + +def update(id, minimum_balance=None, tags=None, emails=None, phones=None, user=None): + """# Update IssuingStockRule entity + Update an IssuingStockRule by passing its id. + ## Parameters (required): + - id [string]: IssuingStockRule id. ex: '5656565656565656' + ## Parameters (optional): + - minimum_balance [integer, default None]: stock balance threshold that triggers a notification. ex: 10000 + - tags [list of strings, default None]: list of strings for tagging. ex: ["card", "corporate"] + - emails [list of strings, default None]: list of emails to be notified when the stock reaches the minimum balance. ex: ["john.doe@enterprise.com"] + - phones [list of strings, default None]: list of phones to be notified when the stock reaches the minimum balance. ex: ["+55 (11) 91234 5678"] + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkinfra.user was set before function call. + ## Return: + - target IssuingStockRule with updated attributes + """ + payload = { + "minimum_balance": minimum_balance, + "tags": tags, + "emails": emails, + "phones": phones, + } + return rest.patch_id(resource=_resource, id=id, user=user, payload=payload) + + +def cancel(id, user=None): + """# Cancel an IssuingStockRule entity + Cancel an IssuingStockRule entity previously created in the Stark Infra API + ## Parameters (required): + - id [string]: IssuingStockRule unique id. ex: "5656565656565656" + ## Parameters (optional): + - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkinfra.user was set before function call. + ## Return: + - canceled IssuingStockRule object + """ + return rest.delete_id(resource=_resource, id=id, user=user) diff --git a/tests/sdk/testIssuingStockRule.py b/tests/sdk/testIssuingStockRule.py new file mode 100644 index 0000000..a2bfd5f --- /dev/null +++ b/tests/sdk/testIssuingStockRule.py @@ -0,0 +1,61 @@ +import starkinfra +from unittest import TestCase, main +from datetime import date, timedelta +from tests.utils.user import exampleProject +from tests.utils.issuingStockRule import generateExampleStockRulesJson + +starkinfra.user = exampleProject + + +class TestIssuingStockRuleQuery(TestCase): + + def test_success(self): + rules = starkinfra.issuingstockrule.query( + limit=10, + after=date.today() - timedelta(days=100), + before=date.today(), + ) + for rule in rules: + self.assertEqual(rule.id, str(rule.id)) + + +class TestIssuingStockRulePage(TestCase): + + def test_success(self): + cursor = None + ids = [] + for _ in range(2): + rules, cursor = starkinfra.issuingstockrule.page( + limit=2, + after=date.today() - timedelta(days=100), + before=date.today(), + cursor=cursor + ) + for rule in rules: + self.assertFalse(rule.id in ids) + ids.append(rule.id) + if cursor is None: + break + + +class TestIssuingStockRuleGet(TestCase): + + def test_success(self): + rules = starkinfra.issuingstockrule.query(limit=1) + rule = starkinfra.issuingstockrule.get(id=next(rules).id) + self.assertEqual(rule.id, str(rule.id)) + + +class TestIssuingStockRulePostPatchAndDelete(TestCase): + + def test_success(self): + rules = starkinfra.issuingstockrule.create(generateExampleStockRulesJson(n=1)) + rule_id = rules[0].id + rule = starkinfra.issuingstockrule.update(id=rule_id, minimum_balance=20000) + self.assertEqual(20000, rule.minimum_balance) + rule = starkinfra.issuingstockrule.cancel(id=rule_id) + self.assertEqual("canceled", rule.status) + + +if __name__ == '__main__': + main() diff --git a/tests/utils/issuingStockRule.py b/tests/utils/issuingStockRule.py new file mode 100644 index 0000000..35b2836 --- /dev/null +++ b/tests/utils/issuingStockRule.py @@ -0,0 +1,21 @@ +from copy import deepcopy +from random import randint +from starkinfra import IssuingStockRule, issuingstock + + +example_stock_rule = IssuingStockRule( + minimum_balance=10000, + stock_id="6526579068895232", + tags=["test"], + emails=["john.doe@enterprise.com"], + phones=["+55 (11) 1234-5678"], +) + + +def generateExampleStockRulesJson(n=1): + rules = [] + for _ in range(n): + example_stock_rule.minimum_balance = randint(1000, 100000) + example_stock_rule.stock_id = next(issuingstock.query(limit=1)).id + rules.append(deepcopy(example_stock_rule)) + return rules