Metadata-Version: 2.4
Name: loyaltylt-sdk
Version: 1.0.0
Summary: Official Python SDK for Loyalty.lt Partner API
Home-page: https://github.com/Loyalty-lt/sdk-python
Author: Loyalty.lt
Author-email: developers@loyalty.lt
Project-URL: Bug Tracker, https://github.com/Loyalty-lt/sdk-python/issues
Project-URL: Documentation, https://docs.loyalty.lt/sdk/python
Project-URL: Homepage, https://loyalty.lt
Keywords: loyalty,points,rewards,sdk,api,pos,qr-login
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Loyalty.lt Python SDK

Official Python SDK for [Loyalty.lt](https://loyalty.lt) Partner API.

[![PyPI version](https://badge.fury.io/py/loyaltylt-sdk.svg)](https://badge.fury.io/py/loyaltylt-sdk)
[![Python Version](https://img.shields.io/pypi/pyversions/loyaltylt-sdk.svg)](https://pypi.org/project/loyaltylt-sdk/)
[![License](https://img.shields.io/pypi/l/loyaltylt-sdk.svg)](https://pypi.org/project/loyaltylt-sdk/)

## Installation

```bash
pip install loyaltylt-sdk
```

## Requirements

- Python 3.8+
- requests

## Quick Start

```python
from loyalty_sdk import LoyaltySDK

sdk = LoyaltySDK(
    api_key='lty_your_api_key',
    api_secret='your_api_secret',
    environment='production',  # or 'staging'
    locale='lt'
)

# Get shops
shops = sdk.get_shops()
print(shops['data'])
```

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `api_key` | str | required | Partner API Key |
| `api_secret` | str | required | Partner API Secret |
| `environment` | str | `production` | `production` or `staging` |
| `locale` | str | `lt` | API locale (`lt`, `en`) |
| `timeout` | int | `30` | Request timeout in seconds |
| `retries` | int | `3` | Number of retry attempts |
| `debug` | bool | `False` | Enable debug logging |

## Features

### QR Login

```python
# Generate QR login session
session = sdk.generate_qr_login('POS Terminal #1', shop_id=1)

print(session['session_id'])
print(session['qr_code'])  # Deep link for QR code
print(session['expires_at'])

# Poll for status
status = sdk.poll_qr_login(session['session_id'])

if status['status'] == 'authenticated':
    user = status['user']
    print(f"Welcome, {user['name']}")
```

### QR Card Scan (POS Customer Identification)

```python
# Generate QR card scan session
session = sdk.generate_qr_card_session('POS Terminal')

# Poll for customer identification
result = sdk.poll_qr_card_status(session['session_id'])

if result['status'] == 'completed':
    card = result['card_data']
    print(f"Customer: {card['user']['name']}")
    print(f"Points: {card['points_balance']}")
```

### Real-time Updates with Ably

```python
# Get Ably token
ably_token = sdk.get_ably_token(session['session_id'])

# Use with Ably client
print(ably_token['token'])
print(ably_token['channel'])
```

### Shops

```python
# Get all shops
shops = sdk.get_shops()

# Filter shops
shops = sdk.get_shops(is_active=True, is_virtual=False)
```

### Loyalty Cards

```python
# Get cards
cards = sdk.get_loyalty_cards()

# Get single card
card = sdk.get_loyalty_card(123)

# Get card by number
card_info = sdk.get_loyalty_card_info(card_number='LOYALTY123456')

# Get points balance
balance = sdk.get_points_balance(card_id=123)
```

### Transactions & Points

```python
# Award points
transaction = sdk.create_transaction(
    card_id=123,
    amount=50.00,
    points=50,
    transaction_type='earn',
    description='Purchase reward',
    reference='ORDER-12345'
)

# Deduct points
sdk.deduct_points(card_id=123, points=100, description='Points redemption')

# Get transactions
transactions = sdk.get_transactions(card_id=123, type='earn')
```

### Offers

```python
# Get offers
offers = sdk.get_offers(is_active=True)

# Create offer
offer = sdk.create_offer(
    title='Summer Sale',
    description='20% off all items',
    discount_type='percentage',
    discount_value=20,
    start_date='2024-06-01',
    end_date='2024-08-31'
)

# Get categories
categories = sdk.get_categories()
```

### XML Import

```python
# Import offers from XML
result = sdk.import_from_url(
    'https://example.com/offers.xml',
    auto_publish=True
)

# Validate XML
validation = sdk.validate_xml('https://example.com/offers.xml')

# Get import stats
stats = sdk.get_import_stats()
```

## Error Handling

```python
from loyalty_sdk import LoyaltySDKError, LoyaltyAPIError

try:
    result = sdk.deduct_points(card_id=123, points=10000)
except LoyaltyAPIError as e:
    print(f"Error: {e.message}")
    print(f"Code: {e.code}")
    print(f"HTTP Status: {e.http_status}")
except LoyaltySDKError as e:
    print(f"SDK Error: {e}")
```

## Django Integration

```python
# settings.py
LOYALTY_API_KEY = os.environ.get('LOYALTY_API_KEY')
LOYALTY_API_SECRET = os.environ.get('LOYALTY_API_SECRET')

# services.py
from loyalty_sdk import LoyaltySDK
from django.conf import settings

def get_loyalty_sdk():
    return LoyaltySDK(
        api_key=settings.LOYALTY_API_KEY,
        api_secret=settings.LOYALTY_API_SECRET
    )

# views.py
from .services import get_loyalty_sdk

def award_points(request):
    sdk = get_loyalty_sdk()
    transaction = sdk.create_transaction(
        card_id=request.POST['card_id'],
        amount=request.POST['amount'],
        points=int(request.POST['amount'])
    )
    return JsonResponse(transaction)
```

## Flask Integration

```python
from flask import Flask, jsonify, request
from loyalty_sdk import LoyaltySDK
import os

app = Flask(__name__)

sdk = LoyaltySDK(
    api_key=os.environ['LOYALTY_API_KEY'],
    api_secret=os.environ['LOYALTY_API_SECRET']
)

@app.route('/award-points', methods=['POST'])
def award_points():
    data = request.json
    transaction = sdk.create_transaction(
        card_id=data['card_id'],
        amount=data['amount'],
        points=data['points']
    )
    return jsonify(transaction)
```

## API Documentation

Full API documentation: [docs.loyalty.lt](https://docs.loyalty.lt)

## Support

- Email: developers@loyalty.lt
- Documentation: https://docs.loyalty.lt
- Issues: https://github.com/Loyalty-lt/sdk-python/issues

## License

MIT License - see [LICENSE](LICENSE) for details.
