Metadata-Version: 2.4
Name: flaxon-mobile
Version: 0.1.1
Summary: Mobile integration plugin for Flaxon with Android + iOS support
Author-email: Aldane Hutchinson <aldanehutchinson5@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/aldanedev-create/flaxon-mobile
Project-URL: Repository, https://github.com/aldanedev-create/flaxon-mobile
Project-URL: Issues, https://github.com/aldanedev-create/flaxon-mobile/issues
Project-URL: Documentation, https://flaxon.io/docs/plugins/mobile
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: Android
Classifier: Operating System :: iOS
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flaxon>=0.1.7
Requires-Dist: httpx[http2]>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyjwt[crypto]>=2.8.0
Provides-Extra: fcm
Requires-Dist: firebase-admin>=6.0.0; extra == "fcm"
Requires-Dist: google-auth>=2.0.0; extra == "fcm"
Provides-Extra: apns
Requires-Dist: pyjwt[crypto]>=2.8.0; extra == "apns"
Requires-Dist: h2>=4.0.0; extra == "apns"
Provides-Extra: android
Requires-Dist: chaquopy>=14.0.0; extra == "android"
Provides-Extra: ios
Requires-Dist: pyobjc-framework-UIKit>=10.0; extra == "ios"
Provides-Extra: all
Requires-Dist: flaxon-mobile[android,apns,fcm,ios]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: license-file

# Flaxon Mobile

<p align="center">
  <img src="https://raw.githubusercontent.com/aldanedev-create/Flaxon-Backend-Framework/main/assets/flaxon.png" alt="Flaxon Logo" width="200"/>
</p>

<p align="center">
  <a href="https://pypi.org/project/flaxon/"><img src="https://img.shields.io/pypi/v/flaxon.svg" alt="PyPI version"></a>
  <a href="https://github.com/aldanedev-create/Flaxon-Backend-Framework/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/badge/code%20style-ruff-000000.svg" alt="Code style: ruff"></a>
</p>

**Mobile integration plugin for Flaxon framework** with push notifications, device management, and Android native bridge.

## Table of Contents

* [Features](#features)
* [Installation](#installation)
* [Quick Start](#quick-start)
* [Configuration](#configuration)

  * [Environment Variables](#environment-variables)
  * [With Flaxon Config](#with-flaxon-config)
* [Usage Examples](#usage-examples)

  * [Device Registration](#device-registration)
  * [Send Push Notification](#send-push-notification)
  * [Mobile-Only Endpoint](#mobile-only-endpoint)
  * [Android Native Bridge (On-Device)](#android-native-bridge-on-device)
* [Pre-built Routes](#pre-built-routes)
* [Security Best Practices](#security-best-practices)
* [Roadmap](#roadmap)
* [License](#license)

## Features

* 📱 **Device Registration** — Register and manage mobile devices
* 🔔 **Push Notifications** — Firebase Cloud Messaging (FCM) integration
* 📡 **Mobile Middleware** — Auto-detect mobile clients from headers
* 🤖 **Android Native Bridge** — On-device Python execution via Chaquopy
* 👤 **Device Management** — Track devices per user
* 🚀 **Pre-built Routes** — `/api/mobile/register`, `/api/mobile/devices`, etc.
* 🎯 **Platform Detection** — Auto-detect Android/iOS clients
* 🔐 **Decorators** — `@mobile_required`, `@platform_required`

## Installation

```bash
# Basic installation
pip install flaxon-mobile

# With FCM support
pip install flaxon-mobile[fcm]

# With Android native support
pip install flaxon-mobile[android]

# With all features
pip install flaxon-mobile[all]
```

## Quick Start

```python
from flaxon import Flaxon
from flaxon_mobile import FlaxonMobilePlugin

app = Flaxon("my-app")

# Load plugin
app.plugins.load_plugin(FlaxonMobilePlugin(
    fcm_api_key=os.environ.get("FCM_API_KEY"),
    enable_device_middleware=True,
))

# Mobile endpoint
@app.get("/api/hello")
async def hello(request):
    mobile_info = request.scope.get("mobile_device", {})
    return {
        "message": "Hello from Flaxon!",
        "is_mobile": mobile_info.get("is_mobile", False),
        "platform": mobile_info.get("platform", "unknown"),
    }
```

## Configuration

### Environment Variables

```bash
# FCM API Key
FCM_API_KEY=your-firebase-api-key

# Device settings
MOBILE_DEVICE_EXPIRY_DAYS=30
MOBILE_MAX_DEVICES_PER_USER=5

# Platform settings
MOBILE_SUPPORTED_PLATFORMS=android,ios
```

### With Flaxon Config

```python
app = Flaxon("my-app", config={
    "FCM_API_KEY": os.environ.get("FCM_API_KEY"),
    "MOBILE_DEVICE_EXPIRY_DAYS": 60,
    "MOBILE_MAX_DEVICES_PER_USER": 3,
})

plugin = FlaxonMobilePlugin.from_config(app.config)
app.plugins.load_plugin(plugin)
```

## Usage Examples

### Device Registration

```python
@app.post("/api/mobile/register")
async def register_device(request):
    data = await request.json()
    
    device = await app.state.mobile.device_manager.register_device(
        user_id=request.user.id,
        device_id=data["device_id"],
        fcm_token=data["fcm_token"],
        platform=data.get("platform", "android"),
        app_version=data.get("app_version"),
        os_version=data.get("os_version"),
    )
    
    return {"success": True, "device": device}
```

### Send Push Notification

```python
@app.post("/api/notify")
async def notify(request):
    data = await request.json()
    
    success = await app.state.mobile.send_push(
        device_id=data["device_id"],
        title=data["title"],
        body=data["body"],
        data={"type": "notification", "timestamp": str(time.time())}
    )
    
    return {"success": success}
```

### Mobile-Only Endpoint

```python
from flaxon_mobile import mobile_required

@app.get("/api/mobile-only")
@mobile_required
async def mobile_only_endpoint(request):
    device_info = request.mobile_device
    return {
        "message": "This is a mobile-only endpoint",
        "device": device_info.to_dict(),
    }
```

### Android Native Bridge (On-Device)

```python
from flaxon_mobile import AndroidBridge

# Running inside Android app via Chaquopy
android = AndroidBridge()

if android.is_android:
    # Get device info
    info = android.get_device_info()
    print(f"Running on {info['manufacturer']} {info['model']}")
    
    # Show native toast
    android.show_toast("Python code running on Android!")
```

## Pre-built Routes

| Route                    | Method | Description           |
| ------------------------ | ------ | --------------------- |
| `/api/mobile/register`   | POST   | Register device       |
| `/api/mobile/unregister` | POST   | Unregister device     |
| `/api/mobile/devices`    | GET    | Get user devices      |
| `/api/mobile/push-token` | POST   | Update FCM token      |
| `/api/mobile/health`     | GET    | Mobile service health |

## Security Best Practices

✅ Always validate device registration

✅ Rate limit device registration endpoints

✅ Encrypt FCM tokens in transit

✅ Rotate FCM API keys regularly

✅ Implement device expiry and cleanup

✅ Authenticate push notification sends

✅ Use HTTPS for all API calls

## Roadmap

| Version | Features                                      |
| ------- | --------------------------------------------- |
| 0.1.0   | Basic plugin, device registration, middleware |
| 0.2.0   | Push notifications (FCM)                      |
| 0.3.0   | Android native bridge (Chaquopy)              |
| 0.4.0   | iOS support (APNs)                            |
| 0.5.0   | Device management, analytics                  |
| 0.6.0   | Offline sync support                          |

## License

MIT License - See LICENSE file for details.
