lunartools-sdk 1.0.6
Official SDK for Lunar Tools API
Requires Python: >=3.7
Keywords: lunar tools sdk api inventory orders profile analytics task checkout

# 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"
    }
)
```

### Add Task Analytics

```python
client.add_task(
    token="user-access-token",
    bot="LunarAIO",
    site="Nike",
    mode="Fast",
    input="DM0121-001",
    profile={
        "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"
        }
    },
    proxy="http://username:password@proxy.example.com:8080",
    account="john.doe@example.com",
    success=True
)
```

### 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

#### add_task

Add task analytics data for tracking checkout attempts and generating AI-powered setup suggestions.

```python
client.add_task(
    token: str,
    bot: str,
    site: str,
    mode: str,
    input: str,
    profile: Dict[str, Any],
    proxy: str,
    account: str,
    success: bool
) -> None
```

**Parameters:**
- `token` (str, required) - User's access token
- `bot` (str, required) - Bot name (e.g., "LunarAIO", "Stellar", "Valor")
- `site` (str, required) - Site/retailer name (e.g., "Nike", "Walmart", "Target")
- `mode` (str, required) - Checkout mode (e.g., "Fast", "Safe", "Guest")
- `input` (str, required) - Product input (SKU, URL, keywords, etc.)
- `profile` (dict, required) - Profile information used for checkout
- `proxy` (str, required) - Proxy used for the task
- `account` (str, required) - Account email/username (empty string if guest checkout)
- `success` (bool, required) - Whether the checkout was successful

**Profile Dictionary:**
- `billing` (dict, required) - Billing address (same structure as add_profile)
- `shipping` (dict, required) - Shipping address (same structure as add_profile)
- `payment` (dict, required) - Payment method (same structure as add_profile)

**Example:**

```python
client.add_task(
    token="user-access-token",
    bot="LunarAIO",
    site="Nike",
    mode="Fast",
    input="DM0121-001",
    profile={
        "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"
        }
    },
    proxy="http://user:pass@proxy.example.com:8080",
    account="john.doe@gmail.com",
    success=True
)
```

**Use Case:**

The `add_task` method powers Lunar Tools' AI-driven setup suggestion system. By reporting checkout attempts, the platform:
- Analyzes success/failure patterns across addresses, payment methods, proxies, and accounts
- Identifies burned profiles with high failure rates
- Recommends optimal configurations based on historical performance
- Provides actionable insights to improve checkout success rates

Users can view personalized setup suggestions in the Lunar Tools app under Profiles > Setups.

**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 task analytics
    client.add_task(
        token=user_token,
        bot="MyBot",
        site="Nike",
        mode="Fast",
        input="DM0121-001",
        profile={
            "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"
            }
        },
        proxy="http://user:pass@proxy.example.com:8080",
        account="john.doe@gmail.com",
        success=True
    )
    print("✅ Task analytics added")

    # 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 legacy 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 checkout attempt
client.add_task(
    token=user_token,
    bot="MyBot",
    site="Nike",
    mode="Fast",
    input=product_sku,
    profile={
        "billing": billing_info,
        "shipping": shipping_info,
        "payment": payment_info
    },
    proxy=proxy_used,
    account=account_email,
    success=checkout_successful
)

# Track order (if successful)
if checkout_successful:
    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 legacy 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