meshtrade 0.0.8__py3-none-any.whl → 0.0.10__py3-none-any.whl

meshtrade/iam/api_user/v1/__init__.py

@@ -0,0 +1,99 @@
+"""Api User v1 package."""
+
+# ===================================================================
+# AUTO-GENERATED SECTION - ONLY EDIT BELOW THE CLOSING COMMENT BLOCK
+# ===================================================================
+# This section is automatically managed by protoc-gen-meshpy.
+#
+# DO NOT EDIT ANYTHING IN THIS SECTION MANUALLY!
+# Your changes will be overwritten during code generation.
+#
+# To add custom imports and exports, scroll down to the
+# "MANUAL SECTION" indicated below.
+# ===================================================================
+
+# Generated protobuf imports
+from .api_credentials_pb2 import APICredentials
+from .api_user_pb2 import APIUser, APIUserAction, APIUserState
+from .service_pb2 import (
+    ActivateApiUserRequest,
+    CreateApiUserRequest,
+    DeactivateApiUserRequest,
+    GetApiUserByKeyHashRequest,
+    GetApiUserRequest,
+    ListApiUsersRequest,
+    ListApiUsersResponse,
+    SearchApiUsersRequest,
+    SearchApiUsersResponse,
+)
+
+# Generated service imports
+from .service_meshpy import (
+    ApiUserService,
+    ApiUserServiceGRPCClient,
+    ApiUserServiceGRPCClientInterface,
+)
+from .service_options_meshpy import ClientOptions
+
+# ===================================================================
+# END OF AUTO-GENERATED SECTION
+# ===================================================================
+#
+# MANUAL SECTION - ADD YOUR CUSTOM IMPORTS AND EXPORTS BELOW
+#
+# You can safely add your own imports, functions, classes, and exports
+# in this section. They will be preserved across code generation.
+#
+# Example:
+#   from my_custom_module import my_function
+#
+# ===================================================================
+
+from meshtrade.common import (
+    DEFAULT_GRPC_PORT,
+    DEFAULT_GRPC_URL,
+    DEFAULT_TLS,
+    GRPCClient,
+    create_auth_metadata,
+)
+
+# Import credentials functions from local module
+from .api_credentials import (
+    MESH_API_CREDENTIALS_ENV_VAR,
+    api_credentials_from_environment,
+    load_api_credentials_from_file,
+)
+
+# ===================================================================
+# MODULE EXPORTS
+# ===================================================================
+# Combined auto-generated and manual exports
+__all__ = [
+    # Generated exports
+    "APICredentials",
+    "APIUser",
+    "APIUserAction",
+    "APIUserState",
+    "ActivateApiUserRequest",
+    "ApiUserService",
+    "ApiUserServiceGRPCClient",
+    "ApiUserServiceGRPCClientInterface",
+    "ClientOptions",
+    "CreateApiUserRequest",
+    "DeactivateApiUserRequest",
+    "GetApiUserByKeyHashRequest",
+    "GetApiUserRequest",
+    "ListApiUsersRequest",
+    "ListApiUsersResponse",
+    "SearchApiUsersRequest",
+    "SearchApiUsersResponse",
+    # Manual exports
+    "DEFAULT_GRPC_PORT",
+    "DEFAULT_GRPC_URL",
+    "DEFAULT_TLS",
+    "GRPCClient",
+    "MESH_API_CREDENTIALS_ENV_VAR",
+    "api_credentials_from_environment",
+    "create_auth_metadata",
+    "load_api_credentials_from_file",
+]

meshtrade/iam/api_user/v1/api_credentials.py

@@ -0,0 +1,156 @@
+"""
+API Credentials loading functionality for Meshtrade SDK.
+"""
+
+import json
+import os
+from pathlib import Path
+
+import platformdirs
+
+from .api_credentials_pb2 import APICredentials
+
+MESH_API_CREDENTIALS_ENV_VAR = "MESH_API_CREDENTIALS"
+
+
+def load_api_credentials_from_file(path: str) -> APICredentials:
+    """Load API credentials from a JSON file.
+
+    Args:
+        path: Path to the credentials JSON file
+
+    Returns:
+        APICredentials object with loaded credentials
+
+    Raises:
+        FileNotFoundError: If the credentials file doesn't exist
+        ValueError: If the credentials file is invalid or missing required fields
+    """
+    try:
+        with open(path) as f:
+            data = json.load(f)
+    except FileNotFoundError as e:
+        raise FileNotFoundError(f"Failed to read API credentials file: {path}") from e
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Failed to parse API credentials file: {e}") from e
+
+    api_key = data.get("api_key")
+    group = data.get("group")
+
+    if not api_key:
+        raise ValueError("api_key is required in API credentials file")
+
+    if not group:
+        raise ValueError("group is required in API credentials file")
+
+    if not group.startswith("groups/"):
+        raise ValueError(f"group must be in format groups/{{group_id}}, got: {group}")
+
+    creds = APICredentials()
+    creds.api_key = api_key
+    creds.group = group
+
+    return creds
+
+
+def api_credentials_from_environment() -> APICredentials | None:
+    """Load API credentials from the file path specified in MESH_API_CREDENTIALS environment variable.
+
+    Returns:
+        APICredentials object if environment variable is set and file exists, None otherwise
+
+    Raises:
+        ValueError: If the credentials file is invalid
+    """
+    path = os.getenv(MESH_API_CREDENTIALS_ENV_VAR)
+    if not path:
+        return None
+
+    return load_api_credentials_from_file(path)
+
+
+def default_credentials_path() -> str:
+    """
+    Calculates the OS-specific default path for Mesh API credentials.
+
+    This function determines the standard user configuration directory based on
+    the operating system's conventions and returns the full path to the
+    'credentials.json' file within a 'mesh' subdirectory. It is a Pythonic
+    implementation of the equivalent Go function.
+
+    The target path is constructed as follows:
+    - **Linux**:   `$XDG_CONFIG_HOME/mesh/credentials.json` or fallback to `$HOME/.config/mesh/credentials.json`
+    - **macOS**:   `$HOME/Library/Application Support/mesh/credentials.json`
+    - **Windows**: `C:\\Users\\<user>\\AppData\\Roaming\\mesh\\credentials.json`
+
+    Returns:
+        A string representing the full, absolute path to the credentials file.
+        If the user's home or config directory cannot be determined, it returns
+        an empty string to match the original Go function's behavior.
+    """
+    try:
+        # Use platformdirs to find the appropriate user config directory for the 'mesh' app.
+        # This correctly handles all OS-specific paths and environment variables.
+        # e.g., on Linux, it returns '~/.config/mesh'
+        mesh_config_dir = platformdirs.user_config_dir(appname="mesh")
+
+        # Use the modern `pathlib` to reliably construct the final file path.
+        # The '/' operator is overloaded for joining path components.
+        credentials_path = Path(mesh_config_dir) / "credentials.json"
+
+        # Return the path as a string.
+        return str(credentials_path)
+
+    except Exception as e:
+        # If platformdirs raises an error (e.g., HOME directory not found),
+        # catch it and return an empty string, mimicking the Go function's
+        # behavior on failure.
+        print(f"Warning: Could not determine credentials path. Error: {e}")
+        return ""
+
+
+def load_default_credentials() -> APICredentials | None:
+    """Load API credentials from the default location if the file exists.
+
+    Returns:
+        APICredentials object if default file exists and is valid, None otherwise
+
+    Raises:
+        ValueError: If the credentials file exists but is invalid
+    """
+    path = default_credentials_path()
+
+    # Check if file exists before attempting to load
+    if not os.path.isfile(path):
+        return None
+
+    return load_api_credentials_from_file(path)
+
+
+def find_credentials() -> APICredentials | None:
+    """Search for API credentials using the standard discovery hierarchy.
+
+    Discovery order:
+    1. MESH_API_CREDENTIALS environment variable (if set)
+    2. Default credential file location
+    - **Linux**:   `$XDG_CONFIG_HOME/mesh/credentials.json` or fallback to `$HOME/.config/mesh/credentials.json`
+    - **macOS**:   `$HOME/Library/Application Support/mesh/credentials.json`
+    - **Windows**: `C:\\Users\\<user>\\AppData\\Roaming\\mesh\\credentials.json`
+
+    Returns:
+        APICredentials object if found using any method, None if no credentials found
+
+    Raises:
+        ValueError: If a credentials file is found but is invalid
+    """
+    # Try environment variable first (existing behavior)
+    creds = api_credentials_from_environment()
+    if creds:
+        return creds
+
+    # Try default file location
+    creds = load_default_credentials()
+    if creds:
+        return creds
+
+    return None

meshtrade/iam/api_user/v1/api_credentials_pb2.py

@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: meshtrade/iam/api_user/v1/api_credentials.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    31,
+    1,
+    '',
+    'meshtrade/iam/api_user/v1/api_credentials.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from buf.validate import validate_pb2 as buf_dot_validate_dot_validate__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n/meshtrade/iam/api_user/v1/api_credentials.proto\x12\x19meshtrade.iam.api_user.v1\x1a\x1b\x62uf/validate/validate.proto\"\x81\x05\n\x0e\x41PICredentials\x12\xbd\x02\n\x07\x61pi_key\x18\x01 \x01(\tB\xa3\x02\xbaH\x9f\x02r\x18\x32\x13^[A-Za-z0-9_-]{43}$\x98\x01+\xba\x01u\n\x10\x61pi_key.required\x12Oapi_key is required and must be exactly 43 characters (base64 URL-safe encoded)\x1a\x10size(this) == 43\xba\x01\x89\x01\n\x0e\x61pi_key.format\x12Rapi_key must be base64 URL-safe encoded (43 characters, alphanumeric plus _ and -)\x1a#this.matches(\'^[A-Za-z0-9_-]{43}$\')R\x06\x61piKey\x12\xae\x02\n\x05group\x18\x02 \x01(\tB\x97\x02\xbaH\x93\x02r\x1a\x32\x15^groups/[0-9A-Z]{26}$\x98\x01!\xba\x01Y\n\x0egroup.required\x12\x35group is required and must be in format groups/{ulid}\x1a\x10size(this) == 33\xba\x01\x97\x01\n\x0cgroup.format\x12`group must be in format groups/{ulid} where ulid is a 26-character ULID (uppercase alphanumeric)\x1a%this.matches(\'^groups/[0-9A-Z]{26}$\')R\x05groupBZ\n co.meshtrade.api.iam.api_user.v1Z6github.com/meshtrade/api/go/iam/api_user/v1;api_userv1b\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'meshtrade.iam.api_user.v1.api_credentials_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'\n co.meshtrade.api.iam.api_user.v1Z6github.com/meshtrade/api/go/iam/api_user/v1;api_userv1'
+  _globals['_APICREDENTIALS'].fields_by_name['api_key']._loaded_options = None
+  _globals['_APICREDENTIALS'].fields_by_name['api_key']._serialized_options = b'\272H\237\002r\0302\023^[A-Za-z0-9_-]{43}$\230\001+\272\001u\n\020api_key.required\022Oapi_key is required and must be exactly 43 characters (base64 URL-safe encoded)\032\020size(this) == 43\272\001\211\001\n\016api_key.format\022Rapi_key must be base64 URL-safe encoded (43 characters, alphanumeric plus _ and -)\032#this.matches(\'^[A-Za-z0-9_-]{43}$\')'
+  _globals['_APICREDENTIALS'].fields_by_name['group']._loaded_options = None
+  _globals['_APICREDENTIALS'].fields_by_name['group']._serialized_options = b'\272H\223\002r\0322\025^groups/[0-9A-Z]{26}$\230\001!\272\001Y\n\016group.required\0225group is required and must be in format groups/{ulid}\032\020size(this) == 33\272\001\227\001\n\014group.format\022`group must be in format groups/{ulid} where ulid is a 26-character ULID (uppercase alphanumeric)\032%this.matches(\'^groups/[0-9A-Z]{26}$\')'
+  _globals['_APICREDENTIALS']._serialized_start=108
+  _globals['_APICREDENTIALS']._serialized_end=749
+# @@protoc_insertion_point(module_scope)

meshtrade/iam/api_user/v1/api_credentials_pb2.pyi

@@ -0,0 +1,14 @@
+from buf.validate import validate_pb2 as _validate_pb2
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from typing import ClassVar as _ClassVar, Optional as _Optional
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class APICredentials(_message.Message):
+    __slots__ = ("api_key", "group")
+    API_KEY_FIELD_NUMBER: _ClassVar[int]
+    GROUP_FIELD_NUMBER: _ClassVar[int]
+    api_key: str
+    group: str
+    def __init__(self, api_key: _Optional[str] = ..., group: _Optional[str] = ...) -> None: ...

meshtrade/iam/api_user/v1/api_credentials_pb2_grpc.py

@@ -0,0 +1,4 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+

meshtrade/iam/api_user/v1/api_user_pb2.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: meshtrade/iam/api_user/v1/api_user.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    31,
+    1,
+    '',
+    'meshtrade/iam/api_user/v1/api_user.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from buf.validate import validate_pb2 as buf_dot_validate_dot_validate__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n(meshtrade/iam/api_user/v1/api_user.proto\x12\x19meshtrade.iam.api_user.v1\x1a\x1b\x62uf/validate/validate.proto\"\xd9\x06\n\x07\x41PIUser\x12\x12\n\x04name\x18\x01 \x01(\tR\x04name\x12\xfd\x02\n\x05owner\x18\x02 \x01(\tB\xe6\x02\xbaH\xe2\x02r4\x10\x01\x32\x30^groups/[a-zA-Z0-9]([a-zA-Z0-9_-]*[a-zA-Z0-9])?$\xba\x01[\n\x0eowner.required\x12\x39owner is required and must be in format groups/{group_id}\x1a\x0esize(this) > 0\xba\x01\xca\x01\n\x0cowner.format\x12xowner must be in format groups/{group_id} where group_id contains only alphanumeric characters, underscores, and hyphens\x1a@this.matches(\'^groups/[a-zA-Z0-9]([a-zA-Z0-9_-]*[a-zA-Z0-9])?$\')R\x05owner\x12\x16\n\x06owners\x18\x03 \x03(\tR\x06owners\x12\xb1\x01\n\x0c\x64isplay_name\x18\x04 \x01(\tB\x8d\x01\xbaH\x89\x01r\x05\x10\x01\x18\xff\x01\xba\x01\x7f\n\x15\x64isplay_name.required\x12\x41\x64isplay name is required and must be between 1 and 255 characters\x1a#size(this) > 0 && size(this) <= 255R\x0b\x64isplayName\x12\xbe\x01\n\x05state\x18\x05 \x01(\x0e\x32\'.meshtrade.iam.api_user.v1.APIUserStateB\x7f\xbaH|\x82\x01\x02\x10\x01\xba\x01t\n\x0bstate.valid\x12/state must be a valid APIUserState if specified\x1a\x34int(this) == 0 || (int(this) >= 1 && int(this) <= 2)R\x05state\x12\x14\n\x05roles\x18\x06 \x03(\tR\x05roles\x12\x17\n\x07\x61pi_key\x18\x07 \x01(\tR\x06\x61piKey*f\n\x0c\x41PIUserState\x12\x1e\n\x1a\x41PI_USER_STATE_UNSPECIFIED\x10\x00\x12\x19\n\x15\x41PI_USER_STATE_ACTIVE\x10\x01\x12\x1b\n\x17\x41PI_USER_STATE_INACTIVE\x10\x02*\xa6\x01\n\rAPIUserAction\x12\x1f\n\x1b\x41PI_USER_ACTION_UNSPECIFIED\x10\x00\x12\x1c\n\x18\x41PI_USER_ACTION_ACTIVATE\x10\x01\x12\x1e\n\x1a\x41PI_USER_ACTION_DEACTIVATE\x10\x02\x12\x1a\n\x16\x41PI_USER_ACTION_CREATE\x10\x03\x12\x1a\n\x16\x41PI_USER_ACTION_UPDATE\x10\x04\x42Z\n co.meshtrade.api.iam.api_user.v1Z6github.com/meshtrade/api/go/iam/api_user/v1;api_userv1b\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'meshtrade.iam.api_user.v1.api_user_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'\n co.meshtrade.api.iam.api_user.v1Z6github.com/meshtrade/api/go/iam/api_user/v1;api_userv1'
+  _globals['_APIUSER'].fields_by_name['owner']._loaded_options = None
+  _globals['_APIUSER'].fields_by_name['owner']._serialized_options = b'\272H\342\002r4\020\00120^groups/[a-zA-Z0-9]([a-zA-Z0-9_-]*[a-zA-Z0-9])?$\272\001[\n\016owner.required\0229owner is required and must be in format groups/{group_id}\032\016size(this) > 0\272\001\312\001\n\014owner.format\022xowner must be in format groups/{group_id} where group_id contains only alphanumeric characters, underscores, and hyphens\032@this.matches(\'^groups/[a-zA-Z0-9]([a-zA-Z0-9_-]*[a-zA-Z0-9])?$\')'
+  _globals['_APIUSER'].fields_by_name['display_name']._loaded_options = None
+  _globals['_APIUSER'].fields_by_name['display_name']._serialized_options = b'\272H\211\001r\005\020\001\030\377\001\272\001\177\n\025display_name.required\022Adisplay name is required and must be between 1 and 255 characters\032#size(this) > 0 && size(this) <= 255'
+  _globals['_APIUSER'].fields_by_name['state']._loaded_options = None
+  _globals['_APIUSER'].fields_by_name['state']._serialized_options = b'\272H|\202\001\002\020\001\272\001t\n\013state.valid\022/state must be a valid APIUserState if specified\0324int(this) == 0 || (int(this) >= 1 && int(this) <= 2)'
+  _globals['_APIUSERSTATE']._serialized_start=960
+  _globals['_APIUSERSTATE']._serialized_end=1062
+  _globals['_APIUSERACTION']._serialized_start=1065
+  _globals['_APIUSERACTION']._serialized_end=1231
+  _globals['_APIUSER']._serialized_start=101
+  _globals['_APIUSER']._serialized_end=958
+# @@protoc_insertion_point(module_scope)

meshtrade/iam/api_user/v1/api_user_pb2.pyi

@@ -0,0 +1,49 @@
+from buf.validate import validate_pb2 as _validate_pb2
+from google.protobuf.internal import containers as _containers
+from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from collections.abc import Iterable as _Iterable
+from typing import ClassVar as _ClassVar, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class APIUserState(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+    __slots__ = ()
+    API_USER_STATE_UNSPECIFIED: _ClassVar[APIUserState]
+    API_USER_STATE_ACTIVE: _ClassVar[APIUserState]
+    API_USER_STATE_INACTIVE: _ClassVar[APIUserState]
+
+class APIUserAction(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+    __slots__ = ()
+    API_USER_ACTION_UNSPECIFIED: _ClassVar[APIUserAction]
+    API_USER_ACTION_ACTIVATE: _ClassVar[APIUserAction]
+    API_USER_ACTION_DEACTIVATE: _ClassVar[APIUserAction]
+    API_USER_ACTION_CREATE: _ClassVar[APIUserAction]
+    API_USER_ACTION_UPDATE: _ClassVar[APIUserAction]
+API_USER_STATE_UNSPECIFIED: APIUserState
+API_USER_STATE_ACTIVE: APIUserState
+API_USER_STATE_INACTIVE: APIUserState
+API_USER_ACTION_UNSPECIFIED: APIUserAction
+API_USER_ACTION_ACTIVATE: APIUserAction
+API_USER_ACTION_DEACTIVATE: APIUserAction
+API_USER_ACTION_CREATE: APIUserAction
+API_USER_ACTION_UPDATE: APIUserAction
+
+class APIUser(_message.Message):
+    __slots__ = ("name", "owner", "owners", "display_name", "state", "roles", "api_key")
+    NAME_FIELD_NUMBER: _ClassVar[int]
+    OWNER_FIELD_NUMBER: _ClassVar[int]
+    OWNERS_FIELD_NUMBER: _ClassVar[int]
+    DISPLAY_NAME_FIELD_NUMBER: _ClassVar[int]
+    STATE_FIELD_NUMBER: _ClassVar[int]
+    ROLES_FIELD_NUMBER: _ClassVar[int]
+    API_KEY_FIELD_NUMBER: _ClassVar[int]
+    name: str
+    owner: str
+    owners: _containers.RepeatedScalarFieldContainer[str]
+    display_name: str
+    state: APIUserState
+    roles: _containers.RepeatedScalarFieldContainer[str]
+    api_key: str
+    def __init__(self, name: _Optional[str] = ..., owner: _Optional[str] = ..., owners: _Optional[_Iterable[str]] = ..., display_name: _Optional[str] = ..., state: _Optional[_Union[APIUserState, str]] = ..., roles: _Optional[_Iterable[str]] = ..., api_key: _Optional[str] = ...) -> None: ...

meshtrade/iam/api_user/v1/api_user_pb2_grpc.py

@@ -0,0 +1,4 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+

meshtrade/iam/api_user/v1/service.py

@@ -0,0 +1,58 @@
+"""
+ApiUserService interface definition.
+"""
+
+from abc import ABC, abstractmethod
+from datetime import timedelta
+
+from .api_user_pb2 import APIUser
+from .service_pb2 import (
+    ActivateApiUserRequest,
+    CreateApiUserRequest,
+    DeactivateApiUserRequest,
+    GetApiUserByKeyHashRequest,
+    GetApiUserRequest,
+    ListApiUsersRequest,
+    ListApiUsersResponse,
+    SearchApiUsersRequest,
+    SearchApiUsersResponse,
+)
+
+
+class ApiUserService(ABC):
+    """Abstract base class defining the ApiUserService interface."""
+
+    @abstractmethod
+    def get_api_user(self, request: GetApiUserRequest, timeout: timedelta | None = None) -> APIUser:
+        """Get an API user by name."""
+        pass
+
+    @abstractmethod
+    def create_api_user(self, request: CreateApiUserRequest, timeout: timedelta | None = None) -> APIUser:
+        """Create a new API user."""
+        pass
+
+    @abstractmethod
+    def list_api_users(self, request: ListApiUsersRequest, timeout: timedelta | None = None) -> ListApiUsersResponse:
+        """List API users."""
+        pass
+
+    @abstractmethod
+    def search_api_users(self, request: SearchApiUsersRequest, timeout: timedelta | None = None) -> SearchApiUsersResponse:
+        """Search API users by display name."""
+        pass
+
+    @abstractmethod
+    def activate_api_user(self, request: ActivateApiUserRequest, timeout: timedelta | None = None) -> APIUser:
+        """Activate an API user."""
+        pass
+
+    @abstractmethod
+    def deactivate_api_user(self, request: DeactivateApiUserRequest, timeout: timedelta | None = None) -> APIUser:
+        """Deactivate an API user."""
+        pass
+
+    @abstractmethod
+    def get_api_user_by_key_hash(self, request: GetApiUserByKeyHashRequest, timeout: timedelta | None = None) -> APIUser:
+        """Get an API user by key hash."""
+        pass