meshtrade 1.22.0__tar.gz → 1.23.0__tar.gz

{meshtrade-1.22.0 → meshtrade-1.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshtrade
-Version: 1.22.0
+Version: 1.23.0
 Summary: Integration SDK for Mesh API Services
 Author-email: Bernard Bussy <bernard@meshtrade.co>
 License: LicenseRef-My-Custom-License

{meshtrade-1.22.0 → meshtrade-1.23.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "meshtrade"
-version = "1.22.0"
+version = "1.23.0"
 authors = [
     { name = "Bernard Bussy", email = "bernard@meshtrade.co" },
 ]

meshtrade-1.23.0/python/src/meshtrade/compliance/client/v1/client_roles.py

@@ -0,0 +1,123 @@
+"""Client roles utility functions."""
+
+from meshtrade.compliance.client.v1.client_pb2 import Client
+from meshtrade.iam.role.v1 import role_pb2
+from meshtrade.iam.role.v1.role_pb2 import Role
+
+# Cache for client default roles extracted from protobuf
+_client_default_roles: list[Role] | None = None
+_client_default_roles_error: str | None = None
+
+
+def _initialize_client_default_roles() -> None:
+    """Initialize client default roles from protobuf extensions.
+
+    This function is called once to extract roles from the Client message's
+    message_roles extension. Results are cached for subsequent calls.
+    """
+    global _client_default_roles, _client_default_roles_error
+
+    if _client_default_roles is not None or _client_default_roles_error is not None:
+        return
+
+    try:
+        # Get the Client message descriptor
+        client_descriptor = Client.DESCRIPTOR
+
+        # Get message options
+        options = client_descriptor.GetOptions()
+
+        # Get the message_roles extension descriptor
+        message_roles_ext = role_pb2.message_roles
+
+        # Check if extension is present
+        # Type ignore: protobuf extension API has overly strict type stubs
+        if not options.HasExtension(message_roles_ext):  # type: ignore[arg-type]
+            _client_default_roles_error = f"proto message {client_descriptor.full_name} does not define extension {message_roles_ext.full_name}"
+            return
+
+        # Get the RoleList from the extension
+        # Type ignore: protobuf extension API has overly strict type stubs
+        role_list = options.Extensions[message_roles_ext]  # type: ignore[arg-type]
+
+        # Extract roles and make a copy
+        _client_default_roles = list(role_list.roles)
+
+    except Exception as e:
+        _client_default_roles_error = f"failed to extract roles from Client message: {e}"
+
+
+def get_client_default_roles() -> list[Role]:
+    """Get default roles for a client.
+
+    Returns the roles declared on the meshtrade.compliance.client.v1.Client
+    message via the meshtrade.iam.role.v1.message_roles option. The returned
+    list is a copy so callers can safely mutate it without affecting subsequent reads.
+
+    Returns:
+        List of default Role values for clients
+        Empty list if retrieval fails
+    """
+    try:
+        return must_get_client_default_roles()
+    except ValueError:
+        return []
+
+
+def must_get_client_default_roles() -> list[Role]:
+    """Get default roles for a client, raising error on failure.
+
+    Returns the roles declared on the meshtrade.compliance.client.v1.Client
+    message via the meshtrade.iam.role.v1.message_roles option. The returned
+    list is a copy so callers can safely mutate it without affecting subsequent reads.
+
+    Returns:
+        List of default Role values for clients
+
+    Raises:
+        ValueError: If default roles cannot be determined
+    """
+    _initialize_client_default_roles()
+
+    if _client_default_roles_error is not None:
+        raise ValueError(_client_default_roles_error)
+
+    if _client_default_roles is None:
+        raise ValueError("client default roles not initialized")
+
+    # Return a copy to prevent mutation
+    return list(_client_default_roles)
+
+
+def get_client_default_role_index() -> dict[Role, bool]:
+    """Get default roles as a lookup index.
+
+    Builds a set-like map keyed by roles declared on the
+    meshtrade.compliance.client.v1.Client message. The map's values are always
+    True; the structure is intended for efficient membership checks.
+
+    Returns:
+        Dictionary mapping Role to True for default roles
+        Empty dict if retrieval fails
+    """
+    try:
+        return must_get_client_default_role_index()
+    except ValueError:
+        return {}
+
+
+def must_get_client_default_role_index() -> dict[Role, bool]:
+    """Get default roles as lookup index, raising error on failure.
+
+    Builds a set-like map keyed by roles declared on the
+    meshtrade.compliance.client.v1.Client message. The map's values are always
+    True; the structure is intended for efficient membership checks.
+
+    Returns:
+        Dictionary mapping Role to True for default roles
+
+    Raises:
+        ValueError: If default roles cannot be determined
+    """
+    roles = must_get_client_default_roles()
+    return dict.fromkeys(roles, True)

meshtrade-1.23.0/python/src/meshtrade/iam/api_user/v1/api_user_state_machine.py

@@ -0,0 +1,104 @@
+"""API User state machine validation and transition logic.
+
+This module provides validation and state machine functions for API User states
+and actions, implementing the API User lifecycle management logic.
+"""
+
+from meshtrade.iam.api_user.v1.api_user_pb2 import APIUserAction, APIUserState
+
+
+def api_user_state_is_valid(state: APIUserState | None) -> bool:
+    """Check if the APIUserState is a valid enum value.
+
+    Args:
+        state: The APIUserState to validate (can be None)
+
+    Returns:
+        True if the state is a valid enum value, False otherwise
+
+    None Safety:
+        Returns False if state is None
+
+    Example:
+        >>> api_user_state_is_valid(APIUserState.API_USER_STATE_ACTIVE)
+        True
+        >>> api_user_state_is_valid(999)  # Invalid enum value
+        False
+        >>> api_user_state_is_valid(None)
+        False
+    """
+    if state is None:
+        return False
+    return state in APIUserState.values()
+
+
+def api_user_state_is_valid_and_defined(state: APIUserState) -> bool:
+    """Check if the APIUserState is valid and not unspecified.
+
+    Args:
+        state: The APIUserState to validate
+
+    Returns:
+        True if the state is valid and not UNSPECIFIED, False otherwise
+
+    Example:
+        >>> api_user_state_is_valid_and_defined(APIUserState.API_USER_STATE_ACTIVE)
+        True
+        >>> api_user_state_is_valid_and_defined(APIUserState.API_USER_STATE_UNSPECIFIED)
+        False
+    """
+    return api_user_state_is_valid(state) and state != APIUserState.API_USER_STATE_UNSPECIFIED
+
+
+def api_user_state_can_perform_action_at_state(state: APIUserState | None, action: APIUserAction | None) -> bool:
+    """Check if the given action can be performed at the current state.
+
+    This implements the state machine logic for API User lifecycle management.
+
+    State Transitions:
+    - INACTIVE -> ACTIVATE -> ACTIVE
+    - ACTIVE -> DEACTIVATE -> INACTIVE
+    - UPDATE action allowed in any state
+
+    Args:
+        state: The current APIUserState (can be None)
+        action: The APIUserAction to perform (can be None)
+
+    Returns:
+        True if the action can be performed at the given state, False otherwise
+
+    None Safety:
+        Returns False if either state or action is None
+
+    Example:
+        >>> can_perform_action_at_state(
+        ...     APIUserState.API_USER_STATE_INACTIVE,
+        ...     APIUserAction.API_USER_ACTION_ACTIVATE
+        ... )
+        True
+        >>> can_perform_action_at_state(
+        ...     APIUserState.API_USER_STATE_INACTIVE,
+        ...     APIUserAction.API_USER_ACTION_DEACTIVATE
+        ... )
+        False
+    """
+    if state is None or action is None:
+        return False
+
+    # Define actions that are allowed regardless of state (update operations)
+    general_update_actions = {
+        APIUserAction.API_USER_ACTION_UPDATE: True,
+    }
+
+    if state == APIUserState.API_USER_STATE_INACTIVE:
+        if action == APIUserAction.API_USER_ACTION_ACTIVATE:
+            return True
+        return general_update_actions.get(action, False)
+
+    elif state == APIUserState.API_USER_STATE_ACTIVE:
+        if action == APIUserAction.API_USER_ACTION_DEACTIVATE:
+            return True
+        return general_update_actions.get(action, False)
+
+    else:
+        return False

{meshtrade-1.22.0 → meshtrade-1.23.0}/python/src/meshtrade/iam/role/v1/__init__.py

@@ -29,7 +29,7 @@ from .role_pb2 import Role, RoleList
 #
 # ===================================================================
 
-from .role import full_resource_name_from_group_name
+from .role import role_full_resource_name_from_group
 
 # ===================================================================
 # MODULE EXPORTS
@@ -40,5 +40,5 @@ __all__ = [
     "Role",
     "RoleList",
     # Manual exports
-    "full_resource_name_from_group_name",
+    "role_full_resource_name_from_group",
 ]

meshtrade-1.23.0/python/src/meshtrade/iam/role/v1/role.py

@@ -0,0 +1,174 @@
+"""Role utility functions for Mesh API.
+
+This module provides helper functions for working with Role enums and their resource names.
+All functions use the 3-part integer format: groups/{groupID}/{roleNumber}
+for cross-language compatibility.
+"""
+
+from meshtrade.iam.role.v1.role_pb2 import Role
+
+
+def role_is_valid(role: Role) -> bool:
+    """Check if role value is valid (within enum range).
+
+    Args:
+        role: Role enum value (integer)
+
+    Returns:
+        True if role is a valid enum value
+
+    Example:
+        >>> role_is_valid(Role.ROLE_IAM_ADMIN)
+        True
+        >>> role_is_valid(99999999)
+        False
+    """
+    return role in Role.values()
+
+
+def role_is_valid_and_specified(role: Role) -> bool:
+    """Check if role is valid and not UNSPECIFIED.
+
+    Args:
+        role: Role enum value (integer)
+
+    Returns:
+        True if role is valid and not ROLE_UNSPECIFIED
+
+    Example:
+        >>> role_is_valid_and_specified(Role.ROLE_IAM_ADMIN)
+        True
+        >>> role_is_valid_and_specified(Role.ROLE_UNSPECIFIED)
+        False
+    """
+    return role_is_valid(role) and role != Role.ROLE_UNSPECIFIED
+
+
+def role_full_resource_name_from_group_id(role: Role, group_id: str) -> str:
+    """Generate full resource name from role and group ID.
+
+    Format: groups/{group_id}/{role_int}
+
+    Args:
+        role: Role enum value (integer)
+        group_id: Group ID (UUID)
+
+    Returns:
+        Full resource name string using integer format
+
+    Example:
+        >>> role_full_resource_name_from_group_id(Role.ROLE_IAM_ADMIN, "01DD32GZ7R0000000000000001")
+        'groups/01DD32GZ7R0000000000000001/3000000'
+    """
+    return f"groups/{group_id}/{int(role)}"
+
+
+def role_full_resource_name_from_group(role: Role, group: str) -> str:
+    """Generate full resource name from role and group resource name.
+
+    Args:
+        role: Role enum value (integer)
+        group: Group resource name (e.g., "groups/{id}")
+
+    Returns:
+        Full resource name string using integer format
+
+    Raises:
+        ValueError: If group format is invalid
+
+    Example:
+        >>> role_full_resource_name_from_group(Role.ROLE_IAM_ADMIN, "groups/01DD32GZ7R0000000000000001")
+        'groups/01DD32GZ7R0000000000000001/3000000'
+    """
+    if not group.startswith("groups/"):
+        raise ValueError(f"invalid group format, expected groups/{{groupID}}, got: {group}")
+
+    group_id = group[len("groups/") :]
+    if not group_id:
+        raise ValueError(f"group ID cannot be empty in group resource name: {group}")
+
+    return role_full_resource_name_from_group_id(role, group_id)
+
+
+def role_from_full_resource_name(full_resource_name: str) -> Role:
+    """Extract Role from full resource name.
+
+    Args:
+        full_resource_name: Full resource name (e.g., "groups/{id}/{role_int}")
+
+    Returns:
+        Role enum value (integer), or ROLE_UNSPECIFIED if parsing fails
+
+    Example:
+        >>> role_from_full_resource_name("groups/01DD32GZ7R0000000000000001/3000000")
+        3000000
+        >>> role_from_full_resource_name("invalid/format")
+        0
+    """
+    from typing import cast
+
+    try:
+        _, role_int = parse_role_parts(full_resource_name)
+        # Python protobuf enums are integers, safe to cast
+        return cast(Role, role_int)
+    except ValueError:
+        return Role.ROLE_UNSPECIFIED
+
+
+def parse_role_parts(role_full_resource_name: str) -> tuple[str, int]:
+    """Parse full resource name into group ID and Role.
+
+    Expected format: groups/{group_id}/{role_int}
+
+    Args:
+        role_full_resource_name: Full resource name
+
+    Returns:
+        Tuple of (group_id, role_int)
+
+    Raises:
+        ValueError: If format is invalid or role number cannot be parsed
+
+    Example:
+        >>> parse_role_parts("groups/01DD32GZ7R0000000000000001/3000000")
+        ('01DD32GZ7R0000000000000001', 3000000)
+    """
+    parts = role_full_resource_name.split("/")
+    if len(parts) != 3 or parts[0] != "groups":
+        raise ValueError(f"invalid role format, expected groups/{{groupID}}/{{role}}, got {role_full_resource_name}")
+
+    group_id = parts[1]
+    if not group_id:
+        raise ValueError("group ID cannot be empty")
+
+    try:
+        role_int = int(parts[2])
+    except ValueError as e:
+        raise ValueError(f"error parsing role enum value '{parts[2]}'") from e
+
+    if role_int < 0:
+        raise ValueError(f"invalid role number in full resource name: {role_full_resource_name}")
+
+    return group_id, role_int
+
+
+def must_parse_role_parts(role_full_resource_name: str) -> tuple[str, int]:
+    """Parse role parts, raising error on failure.
+
+    This is an alias for parse_role_parts.
+    Both functions raise ValueError on parsing errors.
+
+    Args:
+        role_full_resource_name: Full resource name
+
+    Returns:
+        Tuple of (group_id, role_int)
+
+    Raises:
+        ValueError: If format is invalid
+
+    Example:
+        >>> must_parse_role_parts("groups/01DD32GZ7R0000000000000001/3000000")
+        ('01DD32GZ7R0000000000000001', 3000000)
+    """
+    return parse_role_parts(role_full_resource_name)

meshtrade-1.23.0/python/src/meshtrade/ledger/transaction/v1/transaction_state_machine.py

@@ -0,0 +1,75 @@
+"""Transaction state machine validation and transition logic.
+
+This module provides state machine functions for transaction states and actions,
+implementing the transaction lifecycle management logic.
+"""
+
+from meshtrade.ledger.transaction.v1.transaction_action_pb2 import TransactionAction
+from meshtrade.ledger.transaction.v1.transaction_state_pb2 import TransactionState
+
+
+def transaction_state_can_perform_action_at_state(state: TransactionState | None, action: TransactionAction | None) -> bool:
+    """Check if the given action can be performed at the current transaction state.
+
+    This implements the state machine logic for transaction lifecycle management.
+
+    State Transitions:
+    - DRAFT -> BUILD/COMMIT -> SIGNING_IN_PROGRESS
+    - SIGNING_IN_PROGRESS -> SIGN/MARK_PENDING -> PENDING
+    - PENDING -> SUBMIT -> SUBMISSION_IN_PROGRESS
+    - SUBMISSION_IN_PROGRESS -> SUBMIT (retry) -> INDETERMINATE or SUCCESS/FAILED
+    - INDETERMINATE -> SUBMIT (retry) -> SUCCESS/FAILED
+    - FAILED/SUCCESSFUL -> No further actions allowed (terminal states)
+
+    Args:
+        state: The current TransactionState (can be None)
+        action: The TransactionAction to perform (can be None)
+
+    Returns:
+        True if the action can be performed at the given state, False otherwise
+
+    None Safety:
+        Returns False if either state or action is None
+
+    Example:
+        >>> transaction_state_can_perform_action_at_state(
+        ...     TransactionState.TRANSACTION_STATE_DRAFT,
+        ...     TransactionAction.TRANSACTION_ACTION_BUILD
+        ... )
+        True
+        >>> transaction_state_can_perform_action_at_state(
+        ...     TransactionState.TRANSACTION_STATE_SUCCESSFUL,
+        ...     TransactionAction.TRANSACTION_ACTION_SUBMIT
+        ... )
+        False
+    """
+    if state is None or action is None:
+        return False
+
+    if state == TransactionState.TRANSACTION_STATE_DRAFT:
+        return action in {
+            TransactionAction.TRANSACTION_ACTION_BUILD,
+            TransactionAction.TRANSACTION_ACTION_COMMIT,
+        }
+
+    elif state == TransactionState.TRANSACTION_STATE_SIGNING_IN_PROGRESS:
+        return action in {
+            TransactionAction.TRANSACTION_ACTION_SIGN,
+            TransactionAction.TRANSACTION_ACTION_MARK_PENDING,
+        }
+
+    elif state in {
+        TransactionState.TRANSACTION_STATE_PENDING,
+        TransactionState.TRANSACTION_STATE_SUBMISSION_IN_PROGRESS,
+        TransactionState.TRANSACTION_STATE_INDETERMINATE,
+    }:
+        return action == TransactionAction.TRANSACTION_ACTION_SUBMIT
+
+    elif state in {
+        TransactionState.TRANSACTION_STATE_FAILED,
+        TransactionState.TRANSACTION_STATE_SUCCESSFUL,
+    }:
+        return False
+
+    else:
+        return False

meshtrade-1.23.0/python/src/meshtrade/reporting/account_report/v1/income_entry.py

@@ -0,0 +1,35 @@
+"""Income entry utility functions."""
+
+from meshtrade.reporting.account_report.v1.income_entry_pb2 import IncomeNarrative
+
+
+def income_narrative_pretty_string(narrative: IncomeNarrative) -> str:
+    """Generate human-readable string for income narrative.
+
+    Converts enum values to concise, display-friendly strings suitable for
+    reports and user interfaces.
+
+    Args:
+        narrative: IncomeNarrative enum value
+
+    Returns:
+        Pretty-printed string representation:
+        - "-" for unspecified narratives
+        - Descriptive names for known types (e.g., "Yield", "Dividend")
+        - Empty string for unknown values
+    """
+    if narrative == IncomeNarrative.INCOME_NARRATIVE_UNSPECIFIED:
+        return "-"
+    if narrative == IncomeNarrative.INCOME_NARRATIVE_YIELD:
+        return "Yield"
+    if narrative == IncomeNarrative.INCOME_NARRATIVE_DIVIDEND:
+        return "Dividend"
+    if narrative == IncomeNarrative.INCOME_NARRATIVE_INTEREST:
+        return "Interest"
+    if narrative == IncomeNarrative.INCOME_NARRATIVE_PRINCIPAL:
+        return "Principal"
+    if narrative == IncomeNarrative.INCOME_NARRATIVE_DISTRIBUTION:
+        return "Distribution"
+    if narrative == IncomeNarrative.INCOME_NARRATIVE_PROFIT_DISTRIBUTION:
+        return "Profit Distribution"
+    return ""