Add IssuingStockRule resource

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

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=["[email protected]"],
+        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.

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
 

starkinfra/issuingstockrule/__init__.py

@@ -0,0 +1 @@
+from .__issuingstockrule import create, get, query, page, update, cancel

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: ["[email protected]"]
+    - 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: ["[email protected]"]
+    - 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)

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()

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=["[email protected]"],
+    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