Metadata-Version: 2.4
Name: lunartools-sdk
Version: 1.0.5
Summary: Official SDK for Lunar Tools API
Home-page: https://github.com/lunaraio/lunartools-py-sdk
Author: Lunar Tools
Author-email: support@lunartools.co
Keywords: lunar tools sdk api inventory orders profile analytics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
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
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Lunar Tools Python SDK

Official Python SDK for the Lunar Tools API.

## Installation

```bash
pip install lunartools-sdk
```

## Getting Started

### 1. Obtain Your API Key
Visit the [Lunar Tools Developer Portal](https://www.lunartools.co/developers) to generate your API key.

### 2. Get User Access Tokens
Each API call requires a user's access token. Users can find their access token in the Lunar Tools application under Settings > Developer.

## Usage

### Initialize the Client

```python
from lunartools import Client

client = Client(api_key="your-api-key-here")
```

### Add Product to Inventory

```python
client.add_product(
    token="user-access-token",
    name="Charizard VMAX",
    sku="SWSH-074",
    qty=5,
    value=150.00,
    spent=120.00,
    size="Standard",
    store="TCGPlayer"
)
```

### Add Order

```python
client.add_order(
    token="user-access-token",
    name="Pokemon Booster Box",
    status="shipped",
    order_number="ORD-12345",
    price="120.00",
    order_total="132.00",
    retailer="Amazon",
    tracking="1Z999AA10123456784",
    qty="1"
)
```

### Add Profile Analytics

```python
client.add_profile(
    token="user-access-token",
    success=True,
    billing={
        "name": "John Doe",
        "phone": "5551234567",
        "line1": "123 Main St",
        "line2": "Apt 4B",
        "post_code": "10001",
        "city": "New York",
        "state": "NY",
        "country": "United States"
    },
    shipping={
        "name": "John Doe",
        "phone": "5551234567",
        "line1": "123 Main St",
        "line2": "Apt 4B",
        "post_code": "10001",
        "city": "New York",
        "state": "NY",
        "country": "United States"
    },
    payment={
        "name": "John Doe",
        "type": "Visa",
        "last_four": "4242",
        "exp_month": "12",
        "exp_year": "2025",
        "cvv": "123"
    }
)
```

### Forward Webhook to Discord

```python
response = client.webhook(
    "https://www.lunartools.co/api/webhooks/YOUR_TOKEN_HERE",
    {
        "content": "New product in stock!",
        "embeds": [{
            "title": "Product Alert",
            "description": "Charizard VMAX is now available",
            "color": 0x5865F2,
            "fields": [
                {"name": "Price", "value": "$150.00", "inline": True},
                {"name": "Quantity", "value": "5", "inline": True}
            ],
            "timestamp": "2024-01-01T12:00:00Z"
        }]
    }
)

print(f"Status: {response['status']}, Queue: {response['queueLength']}")
```

## API Reference

### Client

```python
Client(api_key: str, base_url: str = "https://www.lunartools.co")
```

**Parameters:**
- `api_key` (str, required) - Your API key from the Lunar Tools Developer Portal
- `base_url` (str, optional) - Custom API base URL (defaults to https://www.lunartools.co)

### Methods

#### add_product

Add a new product to a user's inventory.

```python
client.add_product(
    token: str,
    name: str,
    sku: str,
    qty: int,
    size: Optional[str] = None,
    store: Optional[str] = None,
    value: Optional[float] = None,
    spent: Optional[float] = None
) -> None
```

**Parameters:**
- `token` (str, required) - User's access token
- `name` (str, required) - Product name
- `sku` (str, required) - Product SKU
- `qty` (int, required) - Quantity
- `size` (str, optional) - Product size
- `store` (str, optional) - Store name
- `value` (float, optional) - Product value
- `spent` (float, optional) - Amount spent

**Example:**

```python
client.add_product(
    token="user-access-token",
    name="Product Name",
    sku="SKU-123",
    qty=10,
    value=50.00
)
```

**Raises:**
- `ValueError` - If required fields are missing or invalid
- `requests.HTTPError` - If the API request fails

#### add_order

Add a new order to a user's orders.

```python
client.add_order(
    token: str,
    name: str,
    status: str,
    order_number: str,
    image: Optional[str] = None,
    tracking: Optional[str] = None,
    date: Optional[str] = None,
    qty: Optional[str] = None,
    price: Optional[str] = None,
    order_total: Optional[str] = None,
    account: Optional[str] = None,
    retailer: Optional[str] = None,
    tags: Optional[str] = None
) -> None
```

**Parameters:**
- `token` (str, required) - User's access token
- `name` (str, required) - Order name
- `status` (str, required) - Order status
- `order_number` (str, required) - Order number
- `image` (str, optional) - Product image URL
- `tracking` (str, optional) - Tracking number
- `date` (str, optional) - Order date (format: MM/DD/YYYY, HH:MM:SS AM/PM)
- `qty` (str, optional) - Quantity
- `price` (str, optional) - Item price
- `order_total` (str, optional) - Total order amount
- `account` (str, optional) - Account name
- `retailer` (str, optional) - Retailer name
- `tags` (str, optional) - Order tags

**Example:**

```python
client.add_order(
    token="user-access-token",
    name="Pokemon Cards",
    status="delivered",
    order_number="ORD-456",
    price="99.99",
    retailer="eBay"
)
```

**Raises:**
- `ValueError` - If required fields are missing or invalid
- `requests.HTTPError` - If the API request fails

#### add_profile

Add profile analytics data for tracking successful/declined checkouts.

```python
client.add_profile(
    token: str,
    success: bool,
    billing: Dict[str, Any],
    shipping: Dict[str, Any],
    payment: Dict[str, Any]
) -> None
```

**Parameters:**
- `token` (str, required) - User's access token
- `success` (bool, required) - Whether the checkout was successful
- `billing` (dict, required) - Billing address information
- `shipping` (dict, required) - Shipping address information
- `payment` (dict, required) - Payment information

**Address Dictionary (billing/shipping):**
- `name` (str, required) - Full name
- `phone` (str, required) - Phone number
- `line1` (str, required) - Address line 1
- `line2` (str, optional) - Address line 2
- `post_code` (str, required) - Postal/ZIP code
- `city` (str, required) - City
- `state` (str, required) - State/province
- `country` (str, required) - Country

**Payment Dictionary:**
- `name` (str, required) - Name on card
- `type` (str, required) - Card type (e.g., Visa, Mastercard)
- `last_four` (str, required) - Last 4 digits of card
- `exp_month` (str, required) - Expiration month (MM)
- `exp_year` (str, required) - Expiration year (YYYY)
- `cvv` (str, optional) - CVV code

**Example:**

```python
client.add_profile(
    token="user-access-token",
    success=True,
    billing={
        "name": "John Doe",
        "phone": "5551234567",
        "line1": "123 Main St",
        "post_code": "10001",
        "city": "New York",
        "state": "NY",
        "country": "United States"
    },
    shipping={
        "name": "John Doe",
        "phone": "5551234567",
        "line1": "456 Oak Ave",
        "post_code": "10002",
        "city": "Brooklyn",
        "state": "NY",
        "country": "United States"
    },
    payment={
        "name": "John Doe",
        "type": "Visa",
        "last_four": "4242",
        "exp_month": "12",
        "exp_year": "2025"
    }
)
```

**Raises:**
- `ValueError` - If required fields are missing or invalid
- `requests.HTTPError` - If the API request fails

#### webhook

Forward a webhook payload to Discord via Lunar Tools.

```python
client.webhook(
    webhook_url: str,
    payload: Dict[str, Any]
) -> Dict[str, Any]
```

**Parameters:**
- `webhook_url` (str, required) - Full Lunar Tools webhook URL
- `payload` (dict, required) - Discord webhook payload

**Payload Structure:**
- `content` (str, optional) - Message content
- `username` (str, optional) - Override webhook username
- `avatar_url` (str, optional) - Override webhook avatar
- `embeds` (list, optional) - Array of embeds (max 10)

**Embed Structure:**
- `title` (str, optional) - Embed title
- `description` (str, optional) - Embed description
- `color` (int, optional) - Embed color (hex)
- `fields` (list, optional) - Array of fields (max 25)
- `timestamp` (str, optional) - Timestamp (ISO 8601)
- `footer` (dict, optional) - Footer object
- `author` (dict, optional) - Author object
- `thumbnail` (dict, optional) - Thumbnail object
- `image` (dict, optional) - Image object

**Example:**

```python
response = client.webhook(
    "https://www.lunartools.co/api/webhooks/TOKEN",
    {
        "content": "Hello!",
        "embeds": [{
            "title": "Alert",
            "description": "Something happened",
            "color": 0xFF0000,
            "fields": [
                {"name": "Field 1", "value": "Value 1", "inline": True}
            ]
        }]
    }
)

print(f"Status: {response['status']}")
```

**Returns:**
- `dict` - Response with `status` and `queueLength` keys

**Raises:**
- `ValueError` - If payload validation fails
- `requests.HTTPError` - If the API request fails

## Authentication

The SDK uses two-level authentication:

1. **API Key**: Your developer API key (passed to Client constructor)
   - Obtain from: [Developer Portal](https://www.lunartools.co/developers)
   - Used in `x-api-key` header for all requests

2. **User Access Token**: Individual user's access token (passed per request)
   - Users find this in: Lunar Tools App > Settings > Developer
   - Identifies which user's data to modify

## Error Handling

The SDK raises exceptions for validation errors and API failures:

```python
try:
    client.add_product(
        token="user-access-token",
        name="",
        sku="SKU-123",
        qty=5
    )
except ValueError as e:
    print(f"Validation error: {e}")
except requests.HTTPError as e:
    print(f"API error: {e}")
```

## Complete Example

```python
from lunartools import Client
from datetime import datetime

# Initialize client
client = Client(api_key="your-api-key-here")

user_token = "user-access-token"

try:
    # Add product
    client.add_product(
        token=user_token,
        name="Limited Edition Sneakers",
        sku="SNKR-001",
        qty=10,
        value=200.00,
        spent=150.00,
        store="Footlocker"
    )
    print("✅ Product added")

    # Add order
    client.add_order(
        token=user_token,
        name="Nike Air Max",
        status="confirmed",
        order_number="ORD-12345",
        price="150.00",
        order_total="165.00",
        retailer="Nike",
        tracking="1Z999AA10123456784"
    )
    print("✅ Order added")

    # Track profile analytics
    client.add_profile(
        token=user_token,
        success=True,
        billing={
            "name": "John Doe",
            "phone": "5551234567",
            "line1": "123 Main St",
            "post_code": "10001",
            "city": "New York",
            "state": "NY",
            "country": "United States"
        },
        shipping={
            "name": "John Doe",
            "phone": "5551234567",
            "line1": "456 Oak Ave",
            "post_code": "10002",
            "city": "Brooklyn",
            "state": "NY",
            "country": "United States"
        },
        payment={
            "name": "John Doe",
            "type": "Visa",
            "last_four": "4242",
            "exp_month": "12",
            "exp_year": "2025"
        }
    )
    print("✅ Profile analytics added")

    # Send Discord notification
    webhook_url = "https://www.lunartools.co/api/webhooks/YOUR_TOKEN"
    response = client.webhook(
        webhook_url,
        {
            "embeds": [{
                "title": "✅ Checkout Success",
                "description": "Successfully checked out Nike Air Max",
                "color": 0x00FF00,
                "fields": [
                    {"name": "Order Number", "value": "ORD-12345", "inline": True},
                    {"name": "Total", "value": "$165.00", "inline": True}
                ],
                "timestamp": datetime.utcnow().isoformat()
            }]
        }
    )
    print(f"✅ Webhook sent: {response['status']} (Queue: {response['queueLength']})")

    print("\n🎉 All operations completed successfully!")

except ValueError as e:
    print(f"❌ Validation error: {e}")
except Exception as e:
    print(f"❌ Error: {e}")
```

## Common Use Cases

### E-commerce Bot Integration

```python
from lunartools import Client

client = Client(api_key="your-api-key-here")
user_token = "user-access-token"

# After successful checkout
client.add_order(
    token=user_token,
    name=product_name,
    status="confirmed",
    order_number=order_number,
    price=price,
    order_total=total,
    retailer="Nike",
    tracking=tracking_number
)

# Track profile analytics
client.add_profile(
    token=user_token,
    success=checkout_successful,
    billing=billing_info,
    shipping=shipping_info,
    payment=payment_info
)
```

### Inventory Management

```python
# Add new inventory
client.add_product(
    token=user_token,
    name="Limited Edition Sneakers",
    sku="SNKR-001",
    qty=10,
    value=200.00,
    spent=150.00,
    store="Footlocker"
)
```

### Discord Notifications

```python
# Send success notification
client.webhook(
    webhook_url,
    {
        "embeds": [{
            "title": "✅ Checkout Success",
            "description": f"Successfully checked out {product_name}",
            "color": 0x00FF00,
            "fields": [
                {"name": "Order Number", "value": order_number, "inline": True},
                {"name": "Total", "value": f"${total}", "inline": True}
            ],
            "timestamp": datetime.utcnow().isoformat()
        }]
    }
)
```

## Type Hints

The SDK uses Python type hints for better IDE support:

```python
from typing import Optional, Dict, Any

client.add_product(
    token="user-access-token",
    name="Product",
    sku="SKU",
    qty=5,
    value=100.00  # Optional[float]
)
```

## Requirements

- Python 3.7+
- requests >= 2.31.0

## Support

For issues, questions, or feature requests:
- Discord: [Join our server](https://discord.gg/lunartools)
- Email: support@lunartools.co
- Documentation: [docs.lunartools.co](https://docs.lunartools.co)

## License

MIT
