Metadata-Version: 2.4
Name: erplora-sdk
Version: 0.1.0
Summary: ERPlora Module SDK — Build modules for ERPlora Hub
Project-URL: Homepage, https://erplora.com
Project-URL: Documentation, https://erplora.com/developers/
Project-URL: Repository, https://github.com/ERPlora/erplora-sdk
Project-URL: Issues, https://github.com/ERPlora/erplora-sdk/issues
Author-email: ERPlora <dev@erplora.com>
License-Expression: MIT
License-File: LICENSE
Keywords: django,erplora,modules,pos,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business
Requires-Python: >=3.12
Requires-Dist: django<7.0,>=6.0
Requires-Dist: djicons>=1.0
Requires-Dist: pillow>=10.0
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-django; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# ERPlora SDK

Build modules for [ERPlora](https://erplora.com) — the modular POS system.

[![PyPI version](https://img.shields.io/pypi/v/erplora-sdk.svg)](https://pypi.org/project/erplora-sdk/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![Django 6.0](https://img.shields.io/badge/django-6.0-green.svg)](https://www.djangoproject.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## How It Works

The ERPlora SDK lets you create modules for ERPlora Hub **locally on your machine**, without needing access to the Hub source code. You develop against the SDK's dev environment (SQLite, built-in templates, PIN login), and your module code runs identically in production.

```
Install SDK → Create module → Develop locally → Push to GitHub → Available in Marketplace
```

---

## Getting Started

### 1. Install the SDK

```bash
pip install erplora-sdk
```

### 2. Create a new module

```bash
erplora startmodule reservations
```

This generates a complete module scaffold:

```
reservations/
├── module.py              # Metadata: name, icon, navigation, permissions
├── models.py              # Django models (extend HubBaseModel)
├── views.py               # Views with @htmx_view, @with_module_nav
├── urls.py                # URL patterns
├── forms.py               # Django forms
├── ai_tools.py            # AI assistant tools
├── templates/reservations/
│   ├── pages/             # Full page templates
│   └── partials/          # HTMX partial templates
├── static/reservations/   # CSS, JS, images
├── migrations/
└── tests/
```

### 3. Start the dev server

```bash
erplora devserver
```

This automatically:
- Creates a **SQLite** database (zero configuration)
- Runs migrations for your models
- Creates a dev user with **PIN: 1234**
- Starts the server at **http://localhost:8000**

### 4. Develop your module

Edit your files — models, views, templates, AI tools — and see changes live at http://localhost:8000.

### 5. Publish when ready

```bash
git init
git add .
git commit -m "Initial module"
git remote add origin https://github.com/your-user/module-reservations.git
git push -u origin main
```

Register your module in the [ERPlora Marketplace](https://erplora.com/modules/) and it becomes available to all ERPlora Hubs via automatic sync.

---

## What's Included

| Feature | Description |
|---------|-------------|
| **Base Models** | `HubBaseModel` with UUID primary key, soft delete, audit trail |
| **HTMX Decorators** | `@htmx_view` for SPA navigation without writing JavaScript |
| **Auth Decorators** | `@login_required`, `@permission_required`, `@admin_required` |
| **Navigation** | `@with_module_nav` for automatic tab bar rendering |
| **AI Tools** | `AssistantTool` base class — let users interact with your module via AI chat |
| **Templates** | Base templates with [UX CSS library](https://erplora.com) (161 components, dark mode) |
| **Events** | Signals, hooks (WordPress-style), and UI slots for extensibility |
| **Services** | CSV/Excel export, image handling, file import parsing |
| **Dev Server** | SQLite, auto-migrations, PIN auth, module auto-discovery |

---

## Import Compatibility

Your module code uses the **exact same import paths** as production ERPlora Hubs. The SDK maps them automatically:

```python
# These work identically in the SDK and in production
from apps.core.htmx import htmx_view
from apps.core.models.base import HubBaseModel
from apps.accounts.decorators import login_required, permission_required
from apps.modules_runtime.navigation import with_module_nav
from assistant.tools import AssistantTool, register_tool
```

Write once, run anywhere — no code changes needed when your module goes to production.

---

## View Pattern

Every module view follows this decorator pattern:

```python
from apps.accounts.decorators import login_required, permission_required
from apps.modules_runtime.navigation import with_module_nav
from apps.core.htmx import htmx_view

@login_required
@permission_required('reservations.view')
@with_module_nav('reservations', 'overview')
@htmx_view('reservations/pages/overview.html', 'reservations/partials/overview.html')
def overview(request):
    from .models import Reservation
    return {'reservations': Reservation.objects.all()}
```

- **Normal request** (direct URL) → renders the full page template
- **HTMX request** (`hx-get`) → renders only the partial (SPA navigation)

---

## AI Tools

Give your module AI capabilities by defining tools in `ai_tools.py`:

```python
from assistant.tools import AssistantTool, register_tool
from .models import Reservation

@register_tool
class ListReservations(AssistantTool):
    name = 'reservations_list'
    description = 'List upcoming reservations'
    parameters = {
        'type': 'object',
        'properties': {
            'date': {
                'type': 'string',
                'description': 'Filter by date (YYYY-MM-DD)',
            },
        },
    }

    def execute(self, request, date=None):
        qs = Reservation.objects.filter(is_active=True)
        if date:
            qs = qs.filter(date=date)
        return {'reservations': list(qs.values('id', 'name', 'date', 'time'))}
```

Users can then interact with your module through the AI assistant: *"Show me today's reservations"*.

---

## module.py

Every module has a `module.py` that defines its metadata:

```python
from django.utils.translation import gettext_lazy as _

MODULE_ID = 'reservations'
MODULE_NAME = _('Reservations')

MENU = {
    'label': _('Reservations'),
    'icon': 'calendar-outline',
    'order': 30,
}

NAVIGATION = [
    {'label': _('Overview'), 'icon': 'home-outline', 'id': 'overview'},
    {'label': _('Calendar'), 'icon': 'calendar-outline', 'id': 'calendar'},
    {'label': _('Settings'), 'icon': 'settings-outline', 'id': 'settings'},
]

PERMISSIONS = [
    'reservations.view',
    'reservations.edit',
    'reservations.delete',
]
```

---

## Publishing to the Marketplace

| Type | Description | Revenue |
|------|-------------|---------|
| **Free** | Open source, available to all | — |
| **Premium** | Set your own price | You keep **85%** |

1. Push your module to GitHub (`your-user/module-name`)
2. Register it in the [ERPlora Marketplace](https://erplora.com/modules/)
3. After review, it's available to all ERPlora Hubs
4. The sync pipeline automatically distributes updates when you push

---

## CLI Commands

```bash
erplora startmodule <name>    # Create a new module scaffold
erplora devserver             # Start dev server (SQLite, PIN: 1234)
erplora version               # Show SDK version
erplora help                  # Show help
```

---

## Requirements

- Python 3.12+
- Django 6.0+

Installed automatically: `Django`, `djicons` (icon template tags), `Pillow` (image handling).

---

## Links

- [ERPlora Website](https://erplora.com)
- [Developer Guide](https://erplora.com/developers/)
- [Module Marketplace](https://erplora.com/modules/)
- [Report Issues](https://github.com/ERPlora/erplora-sdk/issues)

## License

MIT
