Metadata-Version: 2.2
Name: django-spaday
Version: 0.1.4
Summary: A Django package that provides 'out-of-the-box' JWT auth, user, group, and permission APIs for use in Single Page Apps (eg - Vue, React).
Author-email: Tim Santor <tsantor@xstudios.com>
Project-URL: Repository, https://github.com/tsantor/django-spaday.git
Project-URL: Issues, https://github.com/tsantor/django-spaday/issues
Project-URL: Changelog, https://github.com/tsantor/django-spaday/blob/master/HISTORY.md
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
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.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: django<5.0,>=4.0
Requires-Dist: drf-spectacular
Requires-Dist: django-auditlog
Requires-Dist: django-celery-results
Requires-Dist: django-filter
Requires-Dist: django-perm-filter
Provides-Extra: dev

# Django SPA Day

![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)

<!-- ![Code Style](https://img.shields.io/badge/code_style-ruff-black) -->

A Django package that provides "out-of-the-box" basic auth, user, group, and permission APIs for use in Single Page Apps (eg - Vue, React).

So easy, you can take a SPA day!

`django-spaday` deliberately stays below version 1.x.x to signal that every new version may potentially have breaking changes.

> NOTE: `django-spaday` is _very_ opinionated as its for internal use.

## Features

- Auth (login/logout/change password)
- User management w/permissions
- Group management w/permissions
- Audit Log (optional)
- Django Celery Results (optional)

## Requirements

Assumes you have started from this [cookiecutter-django](https://github.com/tsantor/cookiecutter-django) template which leverages the following.

- dj-rest-auth
- django-auditlog
- django-celery-results
- django-cors-headers
- django-filter
- djangorestframework
- djangorestframework-simplejwt
- django-perm-filter

## Quickstart

Install Django SPA Day:

```bash
python3 -m pip install django-spaday
```

Add it to your `INSTALLED_APPS`:

```python
INSTALLED_APPS = (
    ...
    'django_spaday',
)
```

### Settings

In `config/urls.py` add the urls:

```python
urlpatterns = [
    path(r"djadmin/", admin.site.urls),
    ...
    path("", include("django_spaday.urls")),
]
```

In `config/api_router.py` add the API urls:

```python
urlpatterns = [
    path("", include("django_spaday.api.urls")),
    # Place all your app's API URLS here.
    ...
    path("auth/", include("dj_rest_auth.urls")),
]
```

In `config/settings/base.py` ensure your `dj-rest-auth` settings include the following:

```python
REST_AUTH = {
    "USE_JWT": True,
    "SESSION_LOGIN": False,
    "TOKEN_MODEL": None,
    "USER_DETAILS_SERIALIZER": "django_spaday.api.serializers.UserAuthSerializer",
    "JWT_AUTH_HTTPONLY": False,  # False means js can access the cookie
}
```

> NOTE: This is imporatant as it will provide the frontend app with the logged in User's permissions, etc.

### Overrides

These are the `SPA_DAY` defaults and do not need to be specified in `settings` unless you wish to override.

```python
SPA_DAY = {
    "PERMISSION_SERIALIZER": "django_spaday.api.serializers.PermissionListSerializer",
    "USER_SERIALIZER": "django_spaday.api.serializers.UserSerializer",
    "GROUP_SERIALIZER": "django_spaday.api.serializers.GroupSerializer",
    "CHANGE_PASSWORD_SERIALIZER": "django_spaday.api.serializers.ChangePasswordSerializer",
    "USER_AUTH_SERIALIZER": "django_spaday.api.serializers.UserAuthSerializer",
    "LAST_LOGIN_SERIALIZER": "django_spaday.api.serializers.LastLoginSerializer",
}
```

```bash
make env
make pip_install
make migrations
make migrate
make superuser
make serve
```

or simply `make from_scratch`

- Visit `http://127.0.0.1:8000/djadmin/` for the Django Admin
- Visit `http://127.0.0.1:8000/api/docs/` for the API docs

### Testing

```bash
make pytest
make coverage
make open_coverage
```

## Issues

If you experience any issues, please create an [issue](https://github.com/tsantor/django-spaday/issues) on Github.

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.1.4] - 2025-02-20

- Override dj_rest_auth LoginView to trigger Django's built in `user_logged_in` signal.

## [0.1.3] - 2024-04-02

- Moved to `ruff` and added tests

## [0.1.2] - 2024-03-07

- Added missing template example (assumes your Vue project has been built to `project/static/vue-frontend`)

## [0.1.1] - 2024-03-07

- Added test coverage

## [0.1.0] - 2022-04-19

- First release on PyPI.
