kirimel-python 0.1.7__tar.gz → 2.0.0__tar.gz

{kirimel_python-0.1.7 → kirimel_python-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kirimel-python
-Version: 0.1.7
+Version: 2.0.0
 Summary: Official KiriMel Python SDK
 Author-email: KiriMel <support@kirimel.com>
 License: MIT
@@ -30,7 +30,15 @@ Dynamic: license-file
 
 # KiriMel Python SDK
 
-Official Python SDK for KiriMel Email Marketing API.
+Official Python SDK for KiriMel Email Marketing API & Loyalty API.
+
+## Features
+
+- **Email API**: Manage campaigns, subscribers, lists, templates, forms, workflows & more
+- **Loyalty API**: Customer loyalty with points, vouchers, tiers, and wallet management
+- **Unified Client**: Single SDK for both APIs with different authentication methods
+- **Type Hints**: Full type annotations for Python 3.8+
+- **Retry Logic**: Built-in exponential backoff for failed requests
 
 ## Installation
 
@@ -454,6 +462,199 @@ node_types = client.workflows.node_types()
 data = client.workflows.get_data(id)
 ```
 
+### Email (Transactional)
+
+Send transactional emails with attachment support:
+
+```python
+# Send transactional email
+result = client.email.send({
+    'to': 'user@example.com',
+    'subject': 'Welcome to our service!',
+    'html': '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
+    'text': 'Welcome! Thanks for signing up.',
+    'from_name': 'My App',
+    'reply_to': 'support@example.com',
+    'cc': 'cc@example.com',
+    'bcc': ['bcc1@example.com', 'bcc2@example.com'],
+    'attachments': [
+        {
+            'name': 'invoice.pdf',
+            'content': base64.b64encode(open('/path/to/invoice.pdf', 'rb').read()).decode()
+        },
+        {
+            'name': 'report.csv',
+            'content': base64.b64encode(open('/path/to/report.csv', 'rb').read()).decode()
+        }
+    ]
+})
+
+# Response includes message_id and tracking_id
+print(f"Message ID: {result['message_id']}")
+print(f"Tracking ID: {result['tracking_id']}")
+
+# Send to multiple recipients
+result = client.email.send({
+    'to': ['user1@example.com', 'user2@example.com'],
+    'subject': 'Team update',
+    'html': '<p>Here is the latest update.</p>'
+})
+
+# Get SES send quota
+quota = client.email.quota()
+print(f"Remaining: {quota['remaining']}")
+print(f"Max 24h: {quota['max_24_hour_send']}")
+print(f"Utilization: {quota['utilization_percent']}%")
+
+# Get verified emails
+verified = client.email.verified_emails()
+
+# Verify a new email address
+result = client.email.verify_email('new@example.com')
+```
+
+## Loyalty API
+
+The Loyalty API uses HMAC SHA256 signature authentication for secure POS integration. The SDK handles signature calculation automatically.
+
+### Authentication
+
+```python
+# Email API credentials (required)
+client = kirimel.KiriMel(api_key='sk_test_xxx')
+
+# Loyalty API credentials (optional - only if using loyalty features)
+client = kirimel.KiriMel(
+    api_key='sk_test_xxx',
+    client_key='cli_test_xxx',        # Or KIRIMEL_LOYALTY_CLIENT_KEY env var
+    client_secret='your_secret_here'  # Or KIRIMEL_LOYALTY_CLIENT_SECRET env var
+)
+```
+
+### Customers
+
+```python
+# Register a new customer
+customer = client.loyalty_customers.register({
+    'phone': '+60123456789',
+    'name': 'John Doe',
+    'email': 'john@example.com',
+    'birth_date': '1990-05-15',  # Optional
+    'qr_code': 'CUSTOMER_123'     # Optional
+})
+
+# Look up customer by phone
+customer = client.loyalty_customers.lookup({
+    'phone': '+60123456789'
+})
+
+# Get customer profile
+profile = client.loyalty_customers.get(customer_id)
+
+# Get customer transactions
+transactions = client.loyalty_customers.transactions(customer_id)
+
+# Manually adjust points
+adjustment = client.loyalty_customers.adjust(customer_id, {
+    'points': 50,
+    'reference': 'MANUAL_ADJUST_001',
+    'description': 'Goodwill gesture',
+    'adjusted_by': 'Admin'
+})
+
+# Get customer tier
+tier = client.loyalty_customers.tier(customer_id)
+
+# List customers
+customers = client.loyalty_customers.list({
+    'page': 1,
+    'per_page': 50,
+    'tier': 'gold'
+})
+```
+
+### Points & Wallet
+
+```python
+# Award points
+earn = client.loyalty_points.earn({
+    'customer_id': customer_id,
+    'points': 100,
+    'amount': 50.50,
+    'reference_id': 'ORDER_123',
+    'description': 'Purchase reward'
+})
+
+# Preview redemption (check before confirming)
+preview = client.loyalty_points.preview_redeem({
+    'customer_id': customer_id,
+    'points_to_redeem': 100
+})
+# Returns: points_value, max_redeemable, amount_discount
+
+# Confirm redemption
+redeem = client.loyalty_points.commit_redeem({
+    'customer_id': customer_id,
+    'points_to_redeem': 100,
+    'reference_id': 'BILL_456'
+})
+
+# Reverse transaction (if needed)
+reverse = client.loyalty_points.reverse({
+    'transaction_id': transaction_id,
+    'reason': 'Customer return',
+    'reference_id': 'RETURN_123'
+})
+
+# Get wallet balance
+balance = client.loyalty_wallet.balance({
+    'customer_id': customer_id
+})
+
+# Recalculate balance from ledger
+recalc = client.loyalty_wallet.recalculate({
+    'customer_id': customer_id
+})
+```
+
+### Vouchers
+
+```python
+# Create voucher batch
+batch = client.loyalty_vouchers.create_batch({
+    'name': 'Grand Opening Promo',
+    'type': 'PERCENT',  # or 'FIXED'
+    'value': 10,
+    'quantity': 100,
+    'valid_from': '2024-06-01',
+    'valid_until': '2024-12-31',
+    'min_purchase': 50.00,
+    'max_discount': 25.00
+})
+
+# List voucher batches
+batches = client.loyalty_vouchers.list_batches()
+
+# Issue voucher to customer
+issue = client.loyalty_vouchers.issue({
+    'voucher_batch_id': batch_id,
+    'customer_id': customer_id,
+    'delivered_via': 'email',  # or 'sms'
+    'reference_id': 'PROMO_001'
+})
+
+# Redeem voucher
+redeem = client.loyalty_vouchers.redeem({
+    'code': 'VOUCHER_A1B2C3D4E5F6',
+    'customer_id': customer_id,
+    'purchase_amount': 75.00,
+    'reference_id': 'ORDER_789'
+})
+
+# Get voucher details
+voucher = client.loyalty_vouchers.get('VOUCHER_A1B2C3D4E5F6')
+```
+
 ## Error Handling
 
 ```python
@@ -502,6 +703,6 @@ MIT License
 
 ## Support
 
-- Documentation: https://docs.kirimel.com
+- Documentation: https://kirimel.com/api-docs
 - GitHub: https://github.com/hualiglobal/kirimel-python-sdk
 - Issues: https://github.com/hualiglobal/kirimel-python-sdk/issues

{kirimel_python-0.1.7 → kirimel_python-2.0.0}/README.md

@@ -1,6 +1,14 @@
 # KiriMel Python SDK
 
-Official Python SDK for KiriMel Email Marketing API.
+Official Python SDK for KiriMel Email Marketing API & Loyalty API.
+
+## Features
+
+- **Email API**: Manage campaigns, subscribers, lists, templates, forms, workflows & more
+- **Loyalty API**: Customer loyalty with points, vouchers, tiers, and wallet management
+- **Unified Client**: Single SDK for both APIs with different authentication methods
+- **Type Hints**: Full type annotations for Python 3.8+
+- **Retry Logic**: Built-in exponential backoff for failed requests
 
 ## Installation
 
@@ -424,6 +432,199 @@ node_types = client.workflows.node_types()
 data = client.workflows.get_data(id)
 ```
 
+### Email (Transactional)
+
+Send transactional emails with attachment support:
+
+```python
+# Send transactional email
+result = client.email.send({
+    'to': 'user@example.com',
+    'subject': 'Welcome to our service!',
+    'html': '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
+    'text': 'Welcome! Thanks for signing up.',
+    'from_name': 'My App',
+    'reply_to': 'support@example.com',
+    'cc': 'cc@example.com',
+    'bcc': ['bcc1@example.com', 'bcc2@example.com'],
+    'attachments': [
+        {
+            'name': 'invoice.pdf',
+            'content': base64.b64encode(open('/path/to/invoice.pdf', 'rb').read()).decode()
+        },
+        {
+            'name': 'report.csv',
+            'content': base64.b64encode(open('/path/to/report.csv', 'rb').read()).decode()
+        }
+    ]
+})
+
+# Response includes message_id and tracking_id
+print(f"Message ID: {result['message_id']}")
+print(f"Tracking ID: {result['tracking_id']}")
+
+# Send to multiple recipients
+result = client.email.send({
+    'to': ['user1@example.com', 'user2@example.com'],
+    'subject': 'Team update',
+    'html': '<p>Here is the latest update.</p>'
+})
+
+# Get SES send quota
+quota = client.email.quota()
+print(f"Remaining: {quota['remaining']}")
+print(f"Max 24h: {quota['max_24_hour_send']}")
+print(f"Utilization: {quota['utilization_percent']}%")
+
+# Get verified emails
+verified = client.email.verified_emails()
+
+# Verify a new email address
+result = client.email.verify_email('new@example.com')
+```
+
+## Loyalty API
+
+The Loyalty API uses HMAC SHA256 signature authentication for secure POS integration. The SDK handles signature calculation automatically.
+
+### Authentication
+
+```python
+# Email API credentials (required)
+client = kirimel.KiriMel(api_key='sk_test_xxx')
+
+# Loyalty API credentials (optional - only if using loyalty features)
+client = kirimel.KiriMel(
+    api_key='sk_test_xxx',
+    client_key='cli_test_xxx',        # Or KIRIMEL_LOYALTY_CLIENT_KEY env var
+    client_secret='your_secret_here'  # Or KIRIMEL_LOYALTY_CLIENT_SECRET env var
+)
+```
+
+### Customers
+
+```python
+# Register a new customer
+customer = client.loyalty_customers.register({
+    'phone': '+60123456789',
+    'name': 'John Doe',
+    'email': 'john@example.com',
+    'birth_date': '1990-05-15',  # Optional
+    'qr_code': 'CUSTOMER_123'     # Optional
+})
+
+# Look up customer by phone
+customer = client.loyalty_customers.lookup({
+    'phone': '+60123456789'
+})
+
+# Get customer profile
+profile = client.loyalty_customers.get(customer_id)
+
+# Get customer transactions
+transactions = client.loyalty_customers.transactions(customer_id)
+
+# Manually adjust points
+adjustment = client.loyalty_customers.adjust(customer_id, {
+    'points': 50,
+    'reference': 'MANUAL_ADJUST_001',
+    'description': 'Goodwill gesture',
+    'adjusted_by': 'Admin'
+})
+
+# Get customer tier
+tier = client.loyalty_customers.tier(customer_id)
+
+# List customers
+customers = client.loyalty_customers.list({
+    'page': 1,
+    'per_page': 50,
+    'tier': 'gold'
+})
+```
+
+### Points & Wallet
+
+```python
+# Award points
+earn = client.loyalty_points.earn({
+    'customer_id': customer_id,
+    'points': 100,
+    'amount': 50.50,
+    'reference_id': 'ORDER_123',
+    'description': 'Purchase reward'
+})
+
+# Preview redemption (check before confirming)
+preview = client.loyalty_points.preview_redeem({
+    'customer_id': customer_id,
+    'points_to_redeem': 100
+})
+# Returns: points_value, max_redeemable, amount_discount
+
+# Confirm redemption
+redeem = client.loyalty_points.commit_redeem({
+    'customer_id': customer_id,
+    'points_to_redeem': 100,
+    'reference_id': 'BILL_456'
+})
+
+# Reverse transaction (if needed)
+reverse = client.loyalty_points.reverse({
+    'transaction_id': transaction_id,
+    'reason': 'Customer return',
+    'reference_id': 'RETURN_123'
+})
+
+# Get wallet balance
+balance = client.loyalty_wallet.balance({
+    'customer_id': customer_id
+})
+
+# Recalculate balance from ledger
+recalc = client.loyalty_wallet.recalculate({
+    'customer_id': customer_id
+})
+```
+
+### Vouchers
+
+```python
+# Create voucher batch
+batch = client.loyalty_vouchers.create_batch({
+    'name': 'Grand Opening Promo',
+    'type': 'PERCENT',  # or 'FIXED'
+    'value': 10,
+    'quantity': 100,
+    'valid_from': '2024-06-01',
+    'valid_until': '2024-12-31',
+    'min_purchase': 50.00,
+    'max_discount': 25.00
+})
+
+# List voucher batches
+batches = client.loyalty_vouchers.list_batches()
+
+# Issue voucher to customer
+issue = client.loyalty_vouchers.issue({
+    'voucher_batch_id': batch_id,
+    'customer_id': customer_id,
+    'delivered_via': 'email',  # or 'sms'
+    'reference_id': 'PROMO_001'
+})
+
+# Redeem voucher
+redeem = client.loyalty_vouchers.redeem({
+    'code': 'VOUCHER_A1B2C3D4E5F6',
+    'customer_id': customer_id,
+    'purchase_amount': 75.00,
+    'reference_id': 'ORDER_789'
+})
+
+# Get voucher details
+voucher = client.loyalty_vouchers.get('VOUCHER_A1B2C3D4E5F6')
+```
+
 ## Error Handling
 
 ```python
@@ -472,6 +673,6 @@ MIT License
 
 ## Support
 
-- Documentation: https://docs.kirimel.com
+- Documentation: https://kirimel.com/api-docs
 - GitHub: https://github.com/hualiglobal/kirimel-python-sdk
 - Issues: https://github.com/hualiglobal/kirimel-python-sdk/issues

{kirimel_python-0.1.7 → kirimel_python-2.0.0}/kirimel/__init__.py

@@ -3,6 +3,7 @@ KiriMel Python SDK
 
 Official Python SDK for KiriMel Email Marketing API.
 """
+
 from .client import KiriMel
 from .exceptions import (
     ApiException,

{kirimel_python-0.1.7 → kirimel_python-2.0.0}/kirimel/client.py

@@ -1,8 +1,11 @@
 """
 KiriMel Python SDK Client
 """
+
+import os
 from typing import Optional
 from .http_client import HttpClient
+from .loyalty_http_client import LoyaltyHttpClient
 from .resources import (
     Campaigns,
     Subscribers,
@@ -14,6 +17,13 @@ from .resources import (
     LandingPages,
     Workflows,
     Webhooks,
+    Email,
+)
+from .resources.loyalty import (
+    Customers as LoyaltyCustomers,
+    Points as LoyaltyPoints,
+    Vouchers as LoyaltyVouchers,
+    Wallet as LoyaltyWallet,
 )
 
 
@@ -33,6 +43,8 @@ class KiriMel:
         base_url: str = "https://kirimel.com/api",
         timeout: int = 30,
         retries: int = 3,
+        client_key: Optional[str] = None,
+        client_secret: Optional[str] = None,
     ):
         """
         Create a new API client
@@ -42,6 +54,8 @@ class KiriMel:
             base_url: Base URL (default: https://kirimel.com/api)
             timeout: Request timeout in seconds (default: 30)
             retries: Number of retries (default: 3)
+            client_key: Loyalty API client key (or use KIRIMEL_LOYALTY_CLIENT_KEY env var)
+            client_secret: Loyalty API client secret (or use KIRIMEL_LOYALTY_CLIENT_SECRET env var)
         """
         self._http_client = HttpClient(
             api_key=api_key,
@@ -59,6 +73,32 @@ class KiriMel:
         self._landing_pages: Optional[LandingPages] = None
         self._workflows: Optional[Workflows] = None
         self._webhooks: Optional[Webhooks] = None
+        self._email: Optional[Email] = None
+
+        # Loyalty API clients
+        self._loyalty_http_client: Optional[LoyaltyHttpClient] = None
+        self._loyalty_customers: Optional[LoyaltyCustomers] = None
+        self._loyalty_points: Optional[LoyaltyPoints] = None
+        self._loyalty_vouchers: Optional[LoyaltyVouchers] = None
+        self._loyalty_wallet: Optional[LoyaltyWallet] = None
+
+        # Store credentials for lazy initialization
+        self._loyalty_base_url = base_url.replace("/api", "")
+        self._loyalty_client_key = client_key or os.getenv("KIRIMEL_LOYALTY_CLIENT_KEY")
+        self._loyalty_client_secret = client_secret or os.getenv("KIRIMEL_LOYALTY_CLIENT_SECRET")
+        self._loyalty_timeout = timeout
+        self._loyalty_retries = retries
+
+    def _init_loyalty_client(self) -> None:
+        """Initialize loyalty HTTP client (lazy initialization)"""
+        if self._loyalty_http_client is None:
+            self._loyalty_http_client = LoyaltyHttpClient(
+                client_key=self._loyalty_client_key,
+                client_secret=self._loyalty_client_secret,
+                base_url=self._loyalty_base_url,
+                timeout=self._loyalty_timeout,
+                retries=self._loyalty_retries,
+            )
 
     @property
     def campaigns(self) -> Campaigns:
@@ -129,3 +169,42 @@ class KiriMel:
         if self._webhooks is None:
             self._webhooks = Webhooks(self._http_client)
         return self._webhooks
+
+    @property
+    def email(self) -> Email:
+        """Get email resource client for transactional emails"""
+        if self._email is None:
+            self._email = Email(self._http_client)
+        return self._email
+
+    @property
+    def loyalty_customers(self) -> LoyaltyCustomers:
+        """Get loyalty customers resource client"""
+        self._init_loyalty_client()
+        if self._loyalty_customers is None:
+            self._loyalty_customers = LoyaltyCustomers(self._loyalty_http_client)
+        return self._loyalty_customers
+
+    @property
+    def loyalty_points(self) -> LoyaltyPoints:
+        """Get loyalty points resource client"""
+        self._init_loyalty_client()
+        if self._loyalty_points is None:
+            self._loyalty_points = LoyaltyPoints(self._loyalty_http_client)
+        return self._loyalty_points
+
+    @property
+    def loyalty_vouchers(self) -> LoyaltyVouchers:
+        """Get loyalty vouchers resource client"""
+        self._init_loyalty_client()
+        if self._loyalty_vouchers is None:
+            self._loyalty_vouchers = LoyaltyVouchers(self._loyalty_http_client)
+        return self._loyalty_vouchers
+
+    @property
+    def loyalty_wallet(self) -> LoyaltyWallet:
+        """Get loyalty wallet resource client"""
+        self._init_loyalty_client()
+        if self._loyalty_wallet is None:
+            self._loyalty_wallet = LoyaltyWallet(self._loyalty_http_client)
+        return self._loyalty_wallet

{kirimel_python-0.1.7 → kirimel_python-2.0.0}/kirimel/exceptions.py

@@ -2,11 +2,18 @@
 KiriMel SDK Exception Classes
 """
 
+from typing import Optional, Dict, Any
+
 
 class ApiException(Exception):
     """Base API exception"""
 
-    def __init__(self, message: str, status_code: int = None, errors: dict = None):
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        errors: Optional[Dict[str, Any]] = None,
+    ):
         self.message = message
         self.status_code = status_code
         self.errors = errors
@@ -27,7 +34,13 @@ class RateLimitException(ApiException):
 
     error_type = "rate_limit_error"
 
-    def __init__(self, message: str, status_code: int = None, errors: dict = None, retry_after: int = None):
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        errors: Optional[Dict[str, Any]] = None,
+        retry_after: Optional[int] = None,
+    ):
         super().__init__(message, status_code, errors)
         self.retry_after = retry_after
 

{kirimel_python-0.1.7 → kirimel_python-2.0.0}/kirimel/http_client.py

@@ -1,13 +1,19 @@
 """
 HTTP Client for KiriMel API
 """
+
 import os
 import time
 import logging
-from typing import Optional, Dict, Any, List
-import requests
+from typing import Optional, Dict, Any, List, cast
+import requests  # type: ignore
 
-from .exceptions import ApiException, AuthenticationException, RateLimitException, ValidationException
+from .exceptions import (
+    ApiException,
+    AuthenticationException,
+    RateLimitException,
+    ValidationException,
+)
 
 
 class HttpClient:
@@ -53,6 +59,7 @@ class HttpClient:
         url = f"{self.base_url}/{path.lstrip('/')}"
         if params:
             import urllib.parse
+
             query_string = urllib.parse.urlencode(params)
             url = f"{url}?{query_string}"
         return url
@@ -88,7 +95,7 @@ class HttpClient:
         if response.status_code >= 400:
             self._handle_error(response, url, attempt)
 
-        return response.json()
+        return cast(Dict[str, Any], response.json())
 
     def _build_headers(self) -> Dict[str, str]:
         """Build request headers"""