Metadata-Version: 2.4
Name: device2sms-sdk
Version: 0.1.1
Summary: Device2SMS Python SDK (E2EE via Google Tink)
Author-email: The Codefather <support@thecodefather.ie>
License-Expression: MIT
Project-URL: Homepage, https://device2sms.ie
Project-URL: Documentation, https://docs.device2sms.ie
Keywords: sms,e2ee,tink,device2sms
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: tink>=1.9.0
Dynamic: license-file

# Device2SMS Python SDK (End-to-End Encrypted SMS)

The official **Python SDK** for **Device2SMS**.

This SDK allows you to send SMS messages through your paired Android devices using
**end-to-end encryption (E2EE)** powered by **Google Tink**.  
Message content is encrypted **before it leaves your application** and is only
decrypted on the paired Android device.

---

## 🚀 Features

- 🔐 End-to-end encrypted SMS (E2EE)
- 📱 Uses your own Android devices to send SMS
- 🔑 Simple API-key authentication
- ♻️ Idempotent message sending
- 🧩 No key management required by the user
- 🐍 Pythonic API with minimal dependencies

---

## 📦 Requirements

- **Python 3.11 or newer**
- A **Device2SMS account**
- At least one **paired Android device**
- An **API key** created in the Device2SMS dashboard

---

## 📥 Installation

### From PyPI (recommended)

```bash
pip install device2sms-sdk
```

### Local development install

```bash
cd sdk/python
python -m venv .venv
.venv\Scripts\activate
pip install -e .
```
# Linux / macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

---

## 🔑 Authentication

Create an API key in the Device2SMS dashboard and store it securely:

```bash
export DEVICE2SMS_API_KEY="your_api_key_here"
```

---

## ✉️ Sending an SMS (E2EE)

```python
from device2sms_sdk import Device2SmsClient

client = Device2SmsClient(
    base_url="https://api.device2sms.ie",
    api_key="YOUR_API_KEY",
)

result = client.send_sms(
    to="+353000000000",
    message="Hello from Device2SMS!",
    idempotency_key="order-123"
)

print(result)
```

### Response example

```json
{
  "job_id": "f1d1b4e6-3c9a-4d6a-8b9e-1c8a9e2d1234",
  "status": "queued"
}
```

---

## 🔐 How End-to-End Encryption Works

1. The SDK calls `/v1/sms/prepare`.
2. The backend selects an online device and returns its **public encryption key**.
3. The SDK encrypts the message locally using **Google Tink**.
4. Only ciphertext is sent to the backend.
5. The Android device decrypts the message and sends the SMS.

At no point does Device2SMS intentionally store or log plaintext message content.

---

## 🧪 Idempotency

To safely retry requests, pass an `idempotency_key`:

```python
client.send_sms(
    to="+353000000000",
    message="Hello again",
    idempotency_key="order-123"
)
```

Repeated requests with the same key will **not** send duplicate messages.

---

## ⚠️ System Messages

Verification and test messages may be sent without E2EE for operational reasons.
All **user-initiated SMS messages sent via the SDK are always end-to-end encrypted**.

---

## 🧯 Error Handling

All SDK errors raise `Device2SmsError`:

```python
from device2sms_sdk import Device2SmsClient, Device2SmsError

try:
    client.send_sms(...)
except Device2SmsError as e:
    print("SMS failed:", e)
```

---

## 📚 Documentation & Support

- Homepage: https://device2sms.ie  
- API reference: https://docs.device2sms.ie 
- Support: support@device2sms.ie 

---

## 🛡 Security Model Summary

| Component             | Access to plaintext |
|----------------------|---------------------|
| Your application     | ✅ Yes              |
| Device2SMS backend   | ❌ No               |
| Android device       | ✅ Yes              |
| Database / logs      | ❌ No               |
