py-momo-api 1.0.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
pymomo/models.py ADDED
@@ -0,0 +1,322 @@
1
+ from __future__ import annotations
2
+
3
+ from enum import Enum
4
+
5
+ from pydantic import BaseModel, ConfigDict, Field, field_validator
6
+
7
+ from pymomo.utils import validate_amount, validate_currency, validate_header_value
8
+
9
+
10
+ def _validate_external_id(value: str) -> str:
11
+ if not isinstance(value, str) or not value.strip():
12
+ raise ValueError("external_id must be a non-empty string")
13
+ return validate_header_value(value, field_name="external_id")
14
+
15
+
16
+ def _validate_positive_expires_in(value: object) -> object:
17
+ if type(value) is bool:
18
+ raise ValueError("expires_in must be a positive integer")
19
+ if isinstance(value, int) and value <= 0:
20
+ raise ValueError("expires_in must be a positive integer")
21
+ return value
22
+
23
+
24
+ class TransactionStatus(str, Enum):
25
+ pending = "PENDING"
26
+ successful = "SUCCESSFUL"
27
+ failed = "FAILED"
28
+
29
+
30
+ class AccountHolderIdType(str, Enum):
31
+ msisdn = "msisdn"
32
+ email = "email"
33
+ party_code = "party_code"
34
+
35
+
36
+ # --- Request models ---
37
+
38
+
39
+ class Party(BaseModel):
40
+ model_config = ConfigDict(extra="ignore", populate_by_name=True)
41
+
42
+ party_id_type: str = Field(alias="partyIdType")
43
+ party_id: str = Field(alias="partyId")
44
+
45
+
46
+ class RequestToPayRequest(BaseModel):
47
+ model_config = ConfigDict(extra="ignore", populate_by_name=True)
48
+
49
+ amount: str
50
+ currency: str
51
+ external_id: str = Field(alias="externalId")
52
+ payer: Party
53
+ payer_message: str = Field(default="", alias="payerMessage")
54
+ payee_note: str = Field(default="", alias="payeeNote")
55
+
56
+ @field_validator("amount")
57
+ @classmethod
58
+ def _check_amount(cls, value: str) -> str:
59
+ return validate_amount(value)
60
+
61
+ @field_validator("currency")
62
+ @classmethod
63
+ def _check_currency(cls, value: str) -> str:
64
+ return validate_currency(value)
65
+
66
+ @field_validator("external_id")
67
+ @classmethod
68
+ def _check_external_id(cls, value: str) -> str:
69
+ return _validate_external_id(value)
70
+
71
+
72
+ class TransferRequest(BaseModel):
73
+ model_config = ConfigDict(extra="ignore", populate_by_name=True)
74
+
75
+ amount: str
76
+ currency: str
77
+ external_id: str = Field(alias="externalId")
78
+ payee: Party
79
+ payer_message: str = Field(default="", alias="payerMessage")
80
+ payee_note: str = Field(default="", alias="payeeNote")
81
+
82
+ @field_validator("amount")
83
+ @classmethod
84
+ def _check_amount(cls, value: str) -> str:
85
+ return validate_amount(value)
86
+
87
+ @field_validator("currency")
88
+ @classmethod
89
+ def _check_currency(cls, value: str) -> str:
90
+ return validate_currency(value)
91
+
92
+ @field_validator("external_id")
93
+ @classmethod
94
+ def _check_external_id(cls, value: str) -> str:
95
+ return _validate_external_id(value)
96
+
97
+
98
+ class DepositRequest(BaseModel):
99
+ model_config = ConfigDict(extra="ignore", populate_by_name=True)
100
+
101
+ amount: str
102
+ currency: str
103
+ external_id: str = Field(alias="externalId")
104
+ payee: Party
105
+ payer_message: str = Field(default="", alias="payerMessage")
106
+ payee_note: str = Field(default="", alias="payeeNote")
107
+
108
+ @field_validator("amount")
109
+ @classmethod
110
+ def _check_amount(cls, value: str) -> str:
111
+ return validate_amount(value)
112
+
113
+ @field_validator("currency")
114
+ @classmethod
115
+ def _check_currency(cls, value: str) -> str:
116
+ return validate_currency(value)
117
+
118
+ @field_validator("external_id")
119
+ @classmethod
120
+ def _check_external_id(cls, value: str) -> str:
121
+ return _validate_external_id(value)
122
+
123
+
124
+ class RefundRequest(BaseModel):
125
+ model_config = ConfigDict(extra="ignore", populate_by_name=True)
126
+
127
+ amount: str
128
+ currency: str
129
+ external_id: str = Field(alias="externalId")
130
+ reference_id_to_refund: str = Field(alias="referenceIdToRefund")
131
+ payer_message: str = Field(default="", alias="payerMessage")
132
+ payee_note: str = Field(default="", alias="payeeNote")
133
+
134
+ @field_validator("amount")
135
+ @classmethod
136
+ def _check_amount(cls, value: str) -> str:
137
+ return validate_amount(value)
138
+
139
+ @field_validator("currency")
140
+ @classmethod
141
+ def _check_currency(cls, value: str) -> str:
142
+ return validate_currency(value)
143
+
144
+ @field_validator("external_id")
145
+ @classmethod
146
+ def _check_external_id(cls, value: str) -> str:
147
+ return _validate_external_id(value)
148
+
149
+
150
+ class RequestToWithdrawRequest(BaseModel):
151
+ model_config = ConfigDict(extra="ignore", populate_by_name=True)
152
+
153
+ amount: str
154
+ currency: str
155
+ external_id: str = Field(alias="externalId")
156
+ payer: Party
157
+ payer_message: str = Field(default="", alias="payerMessage")
158
+ payee_note: str = Field(default="", alias="payeeNote")
159
+
160
+ @field_validator("amount")
161
+ @classmethod
162
+ def _check_amount(cls, value: str) -> str:
163
+ return validate_amount(value)
164
+
165
+ @field_validator("currency")
166
+ @classmethod
167
+ def _check_currency(cls, value: str) -> str:
168
+ return validate_currency(value)
169
+
170
+ @field_validator("external_id")
171
+ @classmethod
172
+ def _check_external_id(cls, value: str) -> str:
173
+ return _validate_external_id(value)
174
+
175
+
176
+ class BcAuthorizeRequest(BaseModel):
177
+ model_config = ConfigDict(extra="ignore", populate_by_name=True)
178
+
179
+ scope: str = "profile"
180
+ access_type: str = Field(default="offline", alias="access_type")
181
+ login_hint: str = Field(alias="login_hint")
182
+
183
+
184
+ # --- Response models ---
185
+
186
+
187
+ class TokenResponse(BaseModel):
188
+ model_config = ConfigDict(extra="ignore", populate_by_name=True)
189
+
190
+ access_token: str
191
+ token_type: str
192
+ expires_in: int
193
+
194
+ @field_validator("access_token")
195
+ @classmethod
196
+ def _check_access_token(cls, value: str) -> str:
197
+ if not value or not value.strip():
198
+ raise ValueError("access_token must not be empty")
199
+ return validate_header_value(value, field_name="access_token")
200
+
201
+ @field_validator("expires_in", mode="before")
202
+ @classmethod
203
+ def _check_expires_in(cls, value: object) -> object:
204
+ return _validate_positive_expires_in(value)
205
+
206
+ def __repr__(self) -> str:
207
+ return (
208
+ f"TokenResponse(access_token=<redacted>, "
209
+ f"token_type={self.token_type!r}, expires_in={self.expires_in!r})"
210
+ )
211
+
212
+ def __str__(self) -> str:
213
+ return self.__repr__()
214
+
215
+
216
+ class OAuth2TokenResponse(BaseModel):
217
+ model_config = ConfigDict(extra="ignore", populate_by_name=True)
218
+
219
+ access_token: str
220
+ token_type: str
221
+ expires_in: int
222
+ scope: str | None = None
223
+ refresh_token: str | None = None
224
+ refresh_token_expired_in: int | None = None
225
+
226
+ @field_validator("access_token")
227
+ @classmethod
228
+ def _check_access_token(cls, value: str) -> str:
229
+ if not value or not value.strip():
230
+ raise ValueError("access_token must not be empty")
231
+ return validate_header_value(value, field_name="access_token")
232
+
233
+ @field_validator("expires_in", mode="before")
234
+ @classmethod
235
+ def _check_expires_in(cls, value: object) -> object:
236
+ return _validate_positive_expires_in(value)
237
+
238
+ def __repr__(self) -> str:
239
+ refresh_repr = "<redacted>" if self.refresh_token is not None else "None"
240
+ return (
241
+ f"OAuth2TokenResponse(access_token=<redacted>, "
242
+ f"token_type={self.token_type!r}, expires_in={self.expires_in!r}, "
243
+ f"scope={self.scope!r}, refresh_token={refresh_repr})"
244
+ )
245
+
246
+ def __str__(self) -> str:
247
+ return self.__repr__()
248
+
249
+
250
+ class BcAuthorizeResponse(BaseModel):
251
+ model_config = ConfigDict(extra="ignore", populate_by_name=True)
252
+
253
+ auth_req_id: str = Field(alias="auth_req_id")
254
+ expires_in: int = Field(alias="expires_in")
255
+ interval: int | None = Field(default=None, alias="interval")
256
+
257
+
258
+ class Balance(BaseModel):
259
+ model_config = ConfigDict(extra="ignore", populate_by_name=True)
260
+
261
+ available_balance: str = Field(alias="availableBalance")
262
+ currency: str
263
+
264
+
265
+ class TransactionResult(BaseModel):
266
+ model_config = ConfigDict(extra="ignore", populate_by_name=True)
267
+
268
+ financial_transaction_id: str | None = Field(
269
+ default=None, alias="financialTransactionId"
270
+ )
271
+ external_id: str | None = Field(default=None, alias="externalId")
272
+ amount: str | None = None
273
+ currency: str | None = None
274
+ payer: Party | None = None
275
+ payee: Party | None = None
276
+ payer_message: str | None = Field(default=None, alias="payerMessage")
277
+ payee_note: str | None = Field(default=None, alias="payeeNote")
278
+ status: TransactionStatus
279
+ reason: str | None = None
280
+
281
+ def is_successful(self) -> bool:
282
+ return self.status == TransactionStatus.successful
283
+
284
+ def is_pending(self) -> bool:
285
+ return self.status == TransactionStatus.pending
286
+
287
+ def is_failed(self) -> bool:
288
+ return self.status == TransactionStatus.failed
289
+
290
+
291
+ class BasicUserInfo(BaseModel):
292
+ model_config = ConfigDict(extra="ignore", populate_by_name=True)
293
+
294
+ sub: str | None = None
295
+ name: str | None = None
296
+ given_name: str | None = None
297
+ family_name: str | None = None
298
+ birthdate: str | None = None
299
+ locale: str | None = None
300
+ gender: str | None = None
301
+ status: str | None = None
302
+
303
+
304
+ class ApiUserInfo(BaseModel):
305
+ model_config = ConfigDict(extra="ignore", populate_by_name=True)
306
+
307
+ provider_callback_host: str | None = Field(
308
+ default=None, alias="providerCallbackHost"
309
+ )
310
+ target_environment: str | None = Field(default=None, alias="targetEnvironment")
311
+
312
+
313
+ class ApiKeyResult(BaseModel):
314
+ model_config = ConfigDict(extra="ignore", populate_by_name=True)
315
+
316
+ api_key: str = Field(alias="apiKey")
317
+
318
+ def __repr__(self) -> str:
319
+ return "ApiKeyResult(api_key=<redacted>)"
320
+
321
+ def __str__(self) -> str:
322
+ return self.__repr__()
@@ -0,0 +1 @@
1
+ # Nested package products
@@ -0,0 +1,198 @@
1
+ from __future__ import annotations
2
+
3
+ import threading
4
+
5
+ from pymomo.auth import TokenCache
6
+ from pymomo.config import MomoConfig, ProductConfig
7
+ from pymomo.exceptions import AuthenticationError, PyMoMoError
8
+ from pymomo.http import HttpClient, parse_json_dict, parse_model
9
+ from pymomo.models import AccountHolderIdType, Balance, BasicUserInfo, TokenResponse
10
+ from pymomo.utils import (
11
+ build_basic_auth_header,
12
+ encode_path_segment,
13
+ normalise_msisdn,
14
+ validate_account_holder_id_type,
15
+ validate_currency,
16
+ )
17
+
18
+
19
+ class BaseProduct:
20
+ """Shared behaviour for all MoMo product clients."""
21
+
22
+ _product_name: (
23
+ str # Subclasses set this: "collection", "disbursement", "remittance"
24
+ )
25
+ _token_path: str # Subclasses set this: e.g. "/collection/token/"
26
+
27
+ def __init__(
28
+ self,
29
+ config: MomoConfig,
30
+ product_config: ProductConfig,
31
+ http: HttpClient,
32
+ token_cache: TokenCache,
33
+ ) -> None:
34
+ self._config = config
35
+ self._product_config = product_config
36
+ self._http = http
37
+ self._token_cache = token_cache
38
+ self._token_lock = threading.Lock()
39
+
40
+ def _get_token(self) -> str:
41
+ cached = self._token_cache.get(self._product_name)
42
+ if cached:
43
+ return cached
44
+ with self._token_lock:
45
+ cached = self._token_cache.get(self._product_name)
46
+ if cached:
47
+ return cached
48
+ return self._fetch_token()
49
+
50
+ def _fetch_token(self) -> str:
51
+ auth_header = build_basic_auth_header(
52
+ self._product_config.api_user,
53
+ self._product_config.api_key,
54
+ )
55
+ response = self._http.request(
56
+ "POST",
57
+ self._token_path,
58
+ headers={
59
+ "Authorization": auth_header,
60
+ "Ocp-Apim-Subscription-Key": self._product_config.subscription_key,
61
+ "X-Target-Environment": self._config.environment,
62
+ },
63
+ )
64
+ try:
65
+ token = parse_model(response, TokenResponse)
66
+ except PyMoMoError:
67
+ raise AuthenticationError("Invalid token response from API") from None
68
+ self._token_cache.set(
69
+ self._product_name,
70
+ token.access_token,
71
+ token.expires_in,
72
+ )
73
+ return token.access_token
74
+
75
+ def _build_headers(
76
+ self,
77
+ *,
78
+ reference_id: str | None = None,
79
+ include_callback: bool = False,
80
+ ) -> dict[str, str]:
81
+ token = self._get_token()
82
+ headers = {
83
+ "Authorization": f"Bearer {token}",
84
+ "Ocp-Apim-Subscription-Key": self._product_config.subscription_key,
85
+ "X-Target-Environment": self._config.environment,
86
+ "Content-Type": "application/json",
87
+ }
88
+ if reference_id:
89
+ headers["X-Reference-Id"] = reference_id
90
+ if include_callback and self._product_config.callback_url:
91
+ headers["X-Callback-Url"] = self._product_config.callback_url
92
+ return headers
93
+
94
+ def get_balance(self) -> Balance:
95
+ """Get the current account balance for this product.
96
+
97
+ Returns:
98
+ A Balance object containing the available balance and currency.
99
+
100
+ Raises:
101
+ AuthenticationError: If the access token cannot be obtained.
102
+ MomoServerError: If the MTN API returns a 5xx error.
103
+ """
104
+ response = self._http.request(
105
+ "GET",
106
+ f"/{self._product_name}/v1_0/account/balance",
107
+ headers=self._build_headers(),
108
+ product_name=self._product_name,
109
+ token_cache=self._token_cache,
110
+ token_refresher=self._get_token,
111
+ )
112
+ return parse_model(response, Balance)
113
+
114
+ def get_balance_for_currency(self, currency: str) -> Balance:
115
+ """Get the account balance for a specific currency.
116
+
117
+ Args:
118
+ currency: The ISO currency code.
119
+
120
+ Returns:
121
+ A Balance object containing the available balance and currency.
122
+ """
123
+ validated_currency = validate_currency(currency)
124
+ response = self._http.request(
125
+ "GET",
126
+ f"/{self._product_name}/v1_0/account/balance/{validated_currency}",
127
+ headers=self._build_headers(),
128
+ product_name=self._product_name,
129
+ token_cache=self._token_cache,
130
+ token_refresher=self._get_token,
131
+ )
132
+ return parse_model(response, Balance)
133
+
134
+ def is_account_holder_active(
135
+ self,
136
+ account_holder_id: str,
137
+ account_holder_id_type: str | AccountHolderIdType = "msisdn",
138
+ ) -> bool:
139
+ """Check if an account holder is active.
140
+
141
+ Args:
142
+ account_holder_id: The account holder identifier.
143
+ account_holder_id_type: The type of identifier (e.g. msisdn, email).
144
+
145
+ Returns:
146
+ True if the account holder is active, False otherwise.
147
+ """
148
+ id_type = validate_account_holder_id_type(account_holder_id_type)
149
+ if id_type == "msisdn":
150
+ account_holder_id = normalise_msisdn(account_holder_id)
151
+ encoded_id = encode_path_segment(
152
+ account_holder_id, field_name="account_holder_id"
153
+ )
154
+ response = self._http.request(
155
+ "GET",
156
+ f"/{self._product_name}/v1_0/accountholder"
157
+ f"/{id_type}/{encoded_id}/active",
158
+ headers=self._build_headers(),
159
+ product_name=self._product_name,
160
+ token_cache=self._token_cache,
161
+ token_refresher=self._get_token,
162
+ )
163
+ res = parse_json_dict(response)
164
+ result = res.get("result")
165
+ if isinstance(result, str):
166
+ return result.lower() == "true"
167
+ return bool(result)
168
+
169
+ def get_basic_user_info(
170
+ self,
171
+ account_holder_id: str,
172
+ account_holder_id_type: str | AccountHolderIdType = "msisdn",
173
+ ) -> BasicUserInfo:
174
+ """Get basic user info of an account holder.
175
+
176
+ Args:
177
+ account_holder_id: The account holder identifier.
178
+ account_holder_id_type: The type of identifier (e.g. msisdn, email).
179
+
180
+ Returns:
181
+ A BasicUserInfo object containing name, given_name, locale, etc.
182
+ """
183
+ id_type = validate_account_holder_id_type(account_holder_id_type)
184
+ if id_type == "msisdn":
185
+ account_holder_id = normalise_msisdn(account_holder_id)
186
+ encoded_id = encode_path_segment(
187
+ account_holder_id, field_name="account_holder_id"
188
+ )
189
+ response = self._http.request(
190
+ "GET",
191
+ f"/{self._product_name}/v1_0/accountholder"
192
+ f"/{id_type}/{encoded_id}/basicuserinfo",
193
+ headers=self._build_headers(),
194
+ product_name=self._product_name,
195
+ token_cache=self._token_cache,
196
+ token_refresher=self._get_token,
197
+ )
198
+ return parse_model(response, BasicUserInfo)