meshtrade 1.22.0__tar.gz → 1.23.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshtrade
-Version: 1.22.0
+Version: 1.23.1
 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.1}/pyproject.toml

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

{meshtrade-1.22.0 → meshtrade-1.23.1}/python/src/meshtrade/compliance/client/v1/__init__.py

@@ -55,6 +55,13 @@ from .service_meshpy import (
 #
 # ===================================================================
 
+from .client_roles import (
+    get_client_default_role_index,
+    get_client_default_roles,
+    must_get_client_default_role_index,
+    must_get_client_default_roles,
+)
+
 # ===================================================================
 # MODULE EXPORTS
 # ===================================================================
@@ -84,4 +91,9 @@ __all__ = [
     "TaxResidency",
     "Trust",
     "VerificationStatus",
+    # Manual exports
+    "get_client_default_role_index",
+    "get_client_default_roles",
+    "must_get_client_default_role_index",
+    "must_get_client_default_roles",
 ]

meshtrade-1.23.1/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.22.0 → meshtrade-1.23.1}/python/src/meshtrade/compliance/client/v1/service_meshpy.py

@@ -9,6 +9,7 @@ the service interface with resource management capabilities, providing authentic
 timeouts, and proper connection handling.
 """
 
+from collections.abc import Iterator
 from datetime import timedelta
 from typing import Optional
 

{meshtrade-1.22.0 → meshtrade-1.23.1}/python/src/meshtrade/iam/api_user/v1/__init__.py

@@ -62,7 +62,10 @@ from meshtrade.common import (
 from .api_credentials import (
     MESH_API_CREDENTIALS_ENV_VAR,
     api_credentials_from_environment,
+    default_credentials_path,
+    find_credentials,
     load_api_credentials_from_file,
+    load_default_credentials,
 )
 
 # ===================================================================
@@ -97,5 +100,8 @@ __all__ = [
     "MESH_API_CREDENTIALS_ENV_VAR",
     "api_credentials_from_environment",
     "create_auth_metadata",
+    "default_credentials_path",
+    "find_credentials",
     "load_api_credentials_from_file",
+    "load_default_credentials",
 ]

meshtrade-1.23.1/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.1}/python/src/meshtrade/iam/api_user/v1/service_meshpy.py

@@ -9,6 +9,7 @@ the service interface with resource management capabilities, providing authentic
 timeouts, and proper connection handling.
 """
 
+from collections.abc import Iterator
 from datetime import timedelta
 from typing import Optional
 

{meshtrade-1.22.0 → meshtrade-1.23.1}/python/src/meshtrade/iam/group/v1/service_meshpy.py

@@ -9,6 +9,7 @@ the service interface with resource management capabilities, providing authentic
 timeouts, and proper connection handling.
 """
 
+from collections.abc import Iterator
 from datetime import timedelta
 from typing import Optional
 

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

@@ -29,7 +29,15 @@ from .role_pb2 import Role, RoleList
 #
 # ===================================================================
 
-from .role import full_resource_name_from_group_name
+from .role import (
+    must_parse_role_parts,
+    parse_role_parts,
+    role_from_full_resource_name,
+    role_full_resource_name_from_group,
+    role_full_resource_name_from_group_id,
+    role_is_valid,
+    role_is_valid_and_specified,
+)
 
 # ===================================================================
 # MODULE EXPORTS
@@ -40,5 +48,11 @@ __all__ = [
     "Role",
     "RoleList",
     # Manual exports
-    "full_resource_name_from_group_name",
+    "must_parse_role_parts",
+    "parse_role_parts",
+    "role_from_full_resource_name",
+    "role_full_resource_name_from_group",
+    "role_full_resource_name_from_group_id",
+    "role_is_valid",
+    "role_is_valid_and_specified",
 ]

meshtrade-1.23.1/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.22.0 → meshtrade-1.23.1}/python/src/meshtrade/iam/user/v1/service_meshpy.py

@@ -9,6 +9,7 @@ the service interface with resource management capabilities, providing authentic
 timeouts, and proper connection handling.
 """
 
+from collections.abc import Iterator
 from datetime import timedelta
 from typing import Optional
 

{meshtrade-1.22.0 → meshtrade-1.23.1}/python/src/meshtrade/ledger/transaction/v1/__init__.py

@@ -43,6 +43,8 @@ from .service_meshpy import (
 #
 # ===================================================================
 
+from .transaction_state_machine import transaction_state_can_perform_action_at_state
+
 # ===================================================================
 # MODULE EXPORTS
 # ===================================================================
@@ -58,4 +60,6 @@ __all__ = [
     "TransactionServiceGRPCClient",
     "TransactionServiceGRPCClientInterface",
     "TransactionState",
+    # Manual exports
+    "transaction_state_can_perform_action_at_state",
 ]

{meshtrade-1.22.0 → meshtrade-1.23.1}/python/src/meshtrade/ledger/transaction/v1/service_meshpy.py

@@ -9,6 +9,7 @@ the service interface with resource management capabilities, providing authentic
 timeouts, and proper connection handling.
 """
 
+from collections.abc import Iterator
 from datetime import timedelta
 from typing import Optional
 
@@ -147,7 +148,7 @@ class TransactionService(BaseGRPCClient):
         """
         return self._execute_method("GetTransactionState", request, timeout)
 
-    def monitor_transaction_state(self, request: MonitorTransactionStateRequest, timeout: Optional[timedelta] = None):
+    def monitor_transaction_state(self, request: MonitorTransactionStateRequest, timeout: Optional[timedelta] = None) -> Iterator[MonitorTransactionStateResponse]:
         """MonitorTransactionState server-side streaming method with authentication and validation.
 
         Args:

meshtrade-1.23.1/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.22.0 → meshtrade-1.23.1}/python/src/meshtrade/reporting/account_report/v1/__init__.py

@@ -41,6 +41,8 @@ from .service_meshpy import (
 #
 # ===================================================================
 
+from .income_entry import income_narrative_pretty_string
+
 # ===================================================================
 # MODULE EXPORTS
 # ===================================================================
@@ -59,4 +61,6 @@ __all__ = [
     "IncomeEntry",
     "IncomeNarrative",
     "TradingStatementEntry",
+    # Manual exports
+    "income_narrative_pretty_string",
 ]