Metadata-Version: 2.4
Name: BmorricalDjangoWorkflows
Version: 2.1.15
Summary: Reusable Django Workflows
Home-page: https://github.com/Bmorrical/django-workflows
Author: Bradley Morrical
Classifier: Programming Language :: Python :: 3
Classifier: Framework :: Django
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.0
Requires-Dist: djangorestframework>=3.14
Requires-Dist: requests>=2.31.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# django-workflows

Reusable Django service helpers for common account flows:

- Registration and verification-code email flow
- Forgot-password code flow
- Reset-code validation and lockout handling
- Transport-neutral email utility with recipient validation

## Installation

Install the private distribution from the configured package source:

```bash
pip install BmorricalDjangoWorkflows==2.1.8
```

In `requirements.txt`, pin it directly:

```txt
BmorricalDjangoWorkflows==2.1.8
```

Note: distribution name is `BmorricalDjangoWorkflows`, while imports remain under `django_workflows`.

Consumption policy:

- Pin an exact reviewed version in every deployed host.
- Do not deploy from an editable install, sibling path, floating branch, or unpinned VCS reference.
- Keep private-index credentials in developer, CI, and deployment environments rather than dependency files.
- Rebuild and test each host after changing the package pin.

The current tag workflow uploads Python artifacts to public PyPI. That conflicts with a private-distribution policy. Do not push a release tag containing private-only work until the workflow and consuming environments are configured for an approved private Python package source.

## Ledger Application

`django_workflows.ledger` is a concrete reusable Django application for tenant-scoped funds, vendors, line items, budgets, transactions, documents, reports, and history APIs.

The package owns the Ledger models, initial migration, serializers, services, permissions, default views, URL patterns, and admin registrations. The host owns tenant resolution, per-tenant module enablement, audit context and database triggers, structured logging, storage configuration, authentication, and deployment infrastructure.

Required host settings:

```python
LEDGER_TENANT_MODEL = "tenant.Tenant"

LEDGER = {
	"ENABLED": True,
	"DATABASE_ALIAS": "default",
	"TENANT_ID_RESOLVER": "myproject.ledger_adapters.user_tenant_id",
	"TENANT_ENABLED_CHECKER": "myproject.ledger_adapters.tenant_has_ledger_enabled",
	"AUDIT_CONTEXT": "myproject.audit.edit_history_context",
	"EVENT_LOGGER": "myproject.ledger_adapters.log_ledger_event",
	"HISTORY_MODEL": "edit_history.EditHistory",
	"ACCESS_GROUP_NAMES": ("SUPER_USER", "LEDGER_ADMIN", "LEDGER_AUDITOR"),
	"EDIT_GROUP_NAMES": ("SUPER_USER", "LEDGER_ADMIN"),
}
```

Install the app and mount its stable default routes:

```python
INSTALLED_APPS = [
	# Host tenant and history applications must also be installed.
	"django_workflows.ledger.apps.LedgerConfig",
]

urlpatterns = [
	path("api/", include("django_workflows.ledger.urls")),
]
```

The tenant resolver receives the authenticated user and returns one tenant ID. Domain services receive that tenant ID explicitly. The tenant enablement checker receives a tenant ID and returns a boolean.

The default audit adapter is intentionally a no-op so the package can be imported in isolated tooling. A host requiring complete auditability must configure `AUDIT_CONTEXT` and install database triggers for every Ledger table; service hooks alone do not capture direct ORM, admin, or script writes.

The package owns Ledger domain migrations. The `ledger` app label, model names, and existing database table names are compatibility contracts. A host may own later trigger migrations that depend on package migrations because those triggers reference host audit tables. Moving an existing local Ledger app into this package without rebuilding also requires an explicit migration-history takeover plan; sharing the app label alone does not make every in-place upgrade safe.

Ledger stores a recurring fiscal-year start month and day on each tenant's `LedgerConfiguration`. April 1 remains the compatibility default, while valid dates such as January 1 and May 17 are supported. The configured boundary drives default fiscal years, transaction-to-line-item validation, budgets, commissioners reports, and dashboard periods. Fiscal years are named for the calendar year in which they start; for example, a May 17 FY 2026 runs from May 17, 2026 through May 16, 2027.

Dashboard `dateStart` and `dateEnd` filters scope income, expenses, adjustments, and recent transactions. Balance remains cumulative through `dateEnd`; omitting both dates produces All Time results. Hosts should present the fiscal calendar as tenant-scoped Ledger configuration. Currency, locale, terminology, transaction workflow, and storage retention remain product configuration still to be defined.

## Receivables

Receivables are the customer-facing half of Ledger: customers, recorded work
time, recurring services, invoices, payments, and supporting documents. They
live in the `ledger` app and share its tenant resolution, permissions, audit
context, and archive semantics.

### Cash boundary

Ledger is a single-entry cash ledger, and receivables do not change that:

- Issuing an invoice records an obligation and writes **no** `LedgerTransaction`.
- Recording a payment writes one income `LedgerTransaction` and links it to the
  payment, so cash keeps exactly one source of truth.
- Outstanding and overdue amounts are reported from open invoices through
  `build_receivables_summary`, deliberately separate from the cash balance.

This is a controlled cash ledger with a receivables register beside it, not
accrual accounting. There is still no chart of accounts, no journal balancing,
and no period close.

### Enablement

Receivables are controlled per tenant by `LedgerConfiguration.receivables_enabled`
and default to **enabled**, including for tenants that have no configuration row
yet. Disable it per tenant where a customer list does not apply. The gate covers
the receivables APIs and the generic history, archive, and restore routes for
receivables resources.

`upsert_receivables_configuration` intentionally does not require the feature to
be enabled, so an administrator can switch it back on.

### Time

Work time is stored in whole minutes, matching the platform rule that decimal
hours are a presentation value rather than a calculation input. Serializers
expose an `hours` field for display; `minutes` remains the stored unit.

### Retainers

A customer's `retainer_hours` are prepaid hours consumed before billing starts.
An invoice credits `min(retainer_hours, hourly_billed_hours) * hourly_rate` and
never drives a total below zero. Both `retainer_hours_available` and
`retainer_hours_applied` are stored on the invoice, so retainer consumption stays
an answerable question rather than being lost in a floored total.

Because the retainer is expressed in hours, it is consumed against hourly work
only. Flat-priced entries and recurring services bill on top of it.

### Invoice numbering

Numbering is tenant configuration: `invoice_number_prefix`,
`invoice_number_next`, and `invoice_number_padding` shape the suggestion returned
by `suggest_invoice_number`. Callers stay free to supply any number they want. A
supplied number that matches the configured pattern advances the sequence; one
that does not leaves it alone, which keeps free-form and legacy numbers workable.
Numbers are unique per tenant.

### Invoice lifecycle

`draft` -> `issued` -> `partially_paid` -> `paid`, with `void` available from any
open state.

- Only a draft accepts new lines.
- Issuing assigns the number, snapshots the customer name and hourly rate, and
  derives the due date from the customer's payment terms.
- Voiding requires a reason and is refused once payments exist; reverse the
  payments first so the cash ledger stays correct.
- Voiding releases the invoice's billable entries so the work can be rebilled.

### Endpoints

```text
GET  /api/ledger/receivables/configuration/
POST /api/ledger/receivables/configuration/
GET  /api/ledger/receivables/summary/
GET  /api/ledger/customers/
POST /api/ledger/customers/upsert/
GET  /api/ledger/customers/<id>/statement/
GET  /api/ledger/recurring-services/
POST /api/ledger/recurring-services/upsert/
GET  /api/ledger/billable-entries/
POST /api/ledger/billable-entries/upsert/
GET  /api/ledger/invoices/
POST /api/ledger/invoices/create/
GET  /api/ledger/invoices/next-number/
POST /api/ledger/invoices/<id>/lines/
POST /api/ledger/invoices/<id>/issue/
POST /api/ledger/invoices/<id>/void/
POST /api/ledger/invoices/<id>/payments/
POST /api/ledger/invoices/<id>/documents/
GET  /api/ledger/invoice-documents/<id>/download/
```

The generic `ledger/<resource>/<id>/` detail, archive, restore, and history
routes accept `customers`, `recurring-services`, `billable-entries`, `invoices`,
`invoice-lines`, `invoice-payments`, and `invoice-documents`.

### Host responsibilities

The host still owns database audit triggers for the new tables. A deployment is
incomplete if `ledger__customers`, `ledger__recurring_services`,
`ledger__billable_entries`, `ledger__invoices`, `ledger__invoice_lines`,
`ledger__invoice_payments`, and `ledger__invoice_documents` exist without their
insert, update, and delete triggers.

### Documents

Invoice documents accept PDF, PNG, JPEG, TIFF, and DOCX up to 20 MB. Each upload
records a sanitized filename, content type, size, SHA-256 digest, and uploader
id. Re-uploading identical bytes to the same invoice returns the existing record
rather than storing a second copy, so a double submission cannot leave orphaned
duplicates in storage. Recorded content type and size are metadata, not a
security boundary; scanning, retention, and purge remain host responsibilities.

### Not included

There is no invoice PDF renderer, no email delivery, no customer payment portal,
no tax or multi-currency handling, no late fees, and no importer. Statement
presentation is a host concern.

## Host Project Requirements

This package expects the host Django project to provide:

- A Django user model available through `django.contrib.auth.get_user_model()`
- A user meta model referenced by `WORKFLOWS["USER_META_MODEL"]`
- A user manager `create_user(...)` method that accepts `username`, because this package explicitly sets `username=email`

The user meta model should include at least:

- `user` relation
- `verify_code` field
- `verify_time` field
- `attempts` field

Optional (used if present):

- `force_password_reset`

## Django Settings

Add a `WORKFLOWS` dict in your Django settings.

```python
WORKFLOWS = {
	# Required in most projects unless your model path matches the default.
	"USER_META_MODEL": "users.models_user_meta.UserMeta",

	# Optional settings with defaults shown.
	"BCC_RECIPIENTS": os.getenv("BCC_RECIPIENTS", ""),
	"COMPANY_NAME": "My Company",
	"EMAIL_TEMPLATE_RENDERER": "project.utils.emails.render_branded_email",
	"ENABLE_EMAIL_DELIVERY": False,
	"FORGOT_PASSWORD_URL": "https://app.example.com/forgot-password",
	"RESET_CODE_TTL_MINUTES": 10,
	"MAX_VERIFY_ATTEMPTS": 3,
}
```

Notes:

- `USER_META_MODEL` must be a dotted import path such as `myapp.models.UserMeta`.
- `EMAIL_TEMPLATE_RENDERER` can point at a callable that receives `body_html` and an optional `title` keyword and returns branded HTML for package-owned auth emails.
- `BCC_RECIPIENTS` is read at send time when provided in `WORKFLOWS`, avoiding import-order dependencies in host settings.
- `FORGOT_PASSWORD_URL` is used in the admin-created account email to link users into the host app's forgot-password flow.
- Host apps will usually source `FORGOT_PASSWORD_URL` from an environment variable in their own settings module.
- If `ENABLE_EMAIL_DELIVERY` is true, configure the email transport environment variables used by the mail service.

Example host-project wiring:

```python
import os

WORKFLOWS = {
	"USER_META_MODEL": "users.models_user_meta.UserMeta",
	"EMAIL_TEMPLATE_RENDERER": "project.utils.emails.render_branded_email",
	"FORGOT_PASSWORD_URL": os.getenv("FORGOT_PASSWORD_URL", ""),
}
```

## Email Delivery Environment Variables

When email delivery is enabled, set:

- `ENABLE_EMAIL_DELIVERY=true`
- `EMAIL_DELIVERY_PROVIDER=mailgun|mailpit|smtp|disabled`
- `EMAIL_FROM="My Company <no-reply@example.com>"`

For the `mailgun` provider, also set:

- `EMAIL_API_KEY`
- `EMAIL_DOMAIN`

Optional:

- `BCC_RECIPIENTS` as a comma-, semicolon-, or newline-separated list. A host can instead provide it as `WORKFLOWS["BCC_RECIPIENTS"]` for runtime configuration.
- `EMAIL_REPLY_TO` as a single email or comma-separated list for reply handling
- `EMAIL_LOG_RESPONSE_TEXT=true` to log response bodies at debug level

Example:

```bash
ENABLE_EMAIL_DELIVERY=true
EMAIL_DELIVERY_PROVIDER=mailgun
EMAIL_FROM="My Company <no-reply@example.com>"
EMAIL_DOMAIN="mg.example.com"
EMAIL_API_KEY="key-example"
BCC_RECIPIENTS="audit@example.com,ops@example.com"
EMAIL_REPLY_TO="support@example.com"
```

If `BCC_RECIPIENTS` is not set, no static BCC recipients are added.

### Email Delivery Logs

Email delivery emits structured fields that JSON log formatters can expose to Datadog:

- `event_name=email.recipients_prepared` includes `email.provider`, recipient counts, masked `email.bcc_recipients`, and `email.mailgun_domain` for Mailgun sends.
- `event_name=email.provider_response` includes `outcome`, `email.response_code`, `email.message_id`, and `email.mailgun_domain`.
- A non-2xx provider response is logged at warning level with `outcome=rejected`; a 2xx response uses `outcome=accepted`.

Recipient local parts are masked in logs. The Mailgun message ID can be used to find the corresponding accepted, delivered, suppressed, or failed event in Mailgun without logging message content or full recipient addresses.

### Old To New Env Mapping

If a consuming app previously used the Mailgun-specific names, update them as follows:

- `MAILGUN_COMPANY_NAME` -> `EMAIL_FROM`
- `ENABLE_MAILGUN` -> `ENABLE_EMAIL_DELIVERY`
- `MAILGUN_LOG_RESPONSE_TEXT` -> `EMAIL_LOG_RESPONSE_TEXT`
- `MAILGUN_API_KEY` -> `EMAIL_API_KEY`
- `MAILGUN_DOMAIN` -> `EMAIL_DOMAIN`
- `MAILGUN_BCC_RECIPIENTS` -> `BCC_RECIPIENTS`
- no old equivalent -> `EMAIL_REPLY_TO`

### Built-In Defaults

If a consuming app does not define one of these values in `.env`, the package now defaults to:

- `ENABLE_EMAIL_DELIVERY=False`
- `EMAIL_API_KEY=""`
- `EMAIL_DOMAIN=""`
- `EMAIL_DELIVERY_PROVIDER=""`
- `DEVELOPMENT_MODE=False`
- `DEFAULT_FROM_EMAIL=""`
- `BCC_RECIPIENTS=""`
- `EMAIL_REPLY_TO=""`
- `EMAIL_LOG_RESPONSE_TEXT=False`

Additional behavior:

- `EMAIL_FROM` falls back to `DEFAULT_FROM_EMAIL` when `EMAIL_FROM` is unset.
- If `EMAIL_DELIVERY_PROVIDER` is blank, the package resolves the transport from the other flags:
- If `ENABLE_EMAIL_DELIVERY=true`, it defaults to the `mailgun` transport.
- If `DEVELOPMENT_MODE=true`, it defaults to the `smtp` transport.
- Otherwise delivery remains disabled.

Practical implication:

- Production apps using Mailgun should set `ENABLE_EMAIL_DELIVERY`, `EMAIL_FROM`, `EMAIL_API_KEY`, and `EMAIL_DOMAIN`.
- If replies should go to a real inbox, also set `EMAIL_REPLY_TO`.
- Local apps using Mailpit should usually set `EMAIL_DELIVERY_PROVIDER=mailpit`, `EMAIL_FROM`, and the Django SMTP settings shown below.
- Apps that do not want this package to send email can omit everything and leave delivery disabled.

Example for a branded sender with a monitored reply inbox:

```bash
EMAIL_FROM="Bourbonnais Township Highway Department <no-reply@mail.bthwy.org>"
EMAIL_REPLY_TO="office@bthwy.org"
```

This keeps the authenticated sender in the `From` header while directing user replies to the `EMAIL_REPLY_TO` inbox.

## Django Email Backend Settings

If a consuming app uses `EMAIL_DELIVERY_PROVIDER=smtp` or `EMAIL_DELIVERY_PROVIDER=mailpit`, it should configure Django's email backend in `settings.py`.

```python
import os

EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
DEFAULT_FROM_EMAIL = os.getenv("DEFAULT_FROM_EMAIL")
EMAIL_HOST = os.getenv("EMAIL_HOST", "localhost")
EMAIL_PORT = int(os.getenv("EMAIL_PORT", "25"))
EMAIL_HOST_USER = os.getenv("EMAIL_HOST_USER", "")
EMAIL_HOST_PASSWORD = os.getenv("EMAIL_HOST_PASSWORD", "")
EMAIL_USE_TLS = os.getenv("EMAIL_USE_TLS", "False") == "True"
EMAIL_USE_SSL = os.getenv("EMAIL_USE_SSL", "False") == "True"
```

Notes:

- This is only needed for the `smtp` and `mailpit` providers.
- `mailpit` commonly listens on port `1025`, so set `EMAIL_PORT` accordingly in local development.
- If you set `EMAIL_FROM`, that value is preferred by this package. Otherwise it falls back to `DEFAULT_FROM_EMAIL`.

## Example Usage

```python
from django_workflows.users.services.auth_flow import (
	register_user_and_send_verification_email,
	send_forgot_password_code,
	verify_reset_code,
	change_password,
)

result = register_user_and_send_verification_email(
	email="person@example.com",
	first_name="First",
	last_name="Last",
	password="example-password",
)

forgot = send_forgot_password_code("person@example.com")

verify = verify_reset_code(email="person@example.com", code="AB12CD")

changed = change_password(
	email="person@example.com",
	password="new-password",
	password_verify="new-password",
)
```

### Direct Email Service Usage

Attachment tuple shape:

- `(filename, file_bytes_or_file_object, mimetype)`

Example attachment entry:

- `("report.pdf", pdf_bytes, "application/pdf")`

```python
from django_workflows.services.email import send_email

response = send_email(
	to=["primary@example.com", "secondary@example.com"],
	subject="Welcome",
	html="<p>Thanks for joining.</p>",
	cc="manager@example.com",
	bcc=["audit@example.com"],
	reply_to="support@example.com",
	attachments=[("report.pdf", pdf_bytes, "application/pdf")],
)

# Optional: explicit runtime override for enablement
send_email(
	to="user@example.com",
	subject="Dry run",
	html="<p>This will not send.</p>",
	enabled=False,
)
```

## Local Development

Run tests:

```bash
make test
```

Run tests with coverage:

```bash
make test-coverage
```

CI runs tests on push and pull requests using [`.github/workflows/tests.yml`](.github/workflows/tests.yml).

## Troubleshooting

### ImproperlyConfigured for USER_META_MODEL

Error example:

```text
WORKFLOWS['USER_META_MODEL'] must be a dotted path like 'myapp.models.UserMeta'.
```

Fix:

- Set `WORKFLOWS["USER_META_MODEL"]` to a valid dotted import path.
- Verify the target model is importable by Django at runtime.

### UserMeta field errors

If you see attribute errors around verification state, confirm your user meta model provides:

- `verify_code`
- `verify_time`
- `attempts`

### Email delivery not sending

Check:

- `ENABLE_EMAIL_DELIVERY=true`
- `EMAIL_DELIVERY_PROVIDER`
- `EMAIL_FROM` or `DEFAULT_FROM_EMAIL`
- `EMAIL_API_KEY` and `EMAIL_DOMAIN` when using the Mailgun provider

### No static BCC recipients applied

This is expected unless you set `BCC_RECIPIENTS`.

## Release

Releases are maintainer-owned. Before releasing:

1. Confirm the intended distribution source and artifact visibility.
2. Run the complete package test suite from a clean environment.
3. Update `VERSION` through the reviewed release process.
4. Review the release commit and tag before pushing.
5. Confirm the built wheel and source distribution install from the approved package source.
6. Pin the exact version in each consuming host and rebuild it.
7. Run host migration, trigger, API, and integration checks.

The included release script creates and pushes a version tag:

```bash
./release.sh <version>
```

At present, that tag invokes [`.github/workflows/publish.yml`](.github/workflows/publish.yml), which uploads to public PyPI. Replace or reconfigure that workflow before using the script for a private release. The private index endpoint and credentials must be supplied by the release environment; they must not be committed to this repository.
