v1

README.md

@@ -1,84 +1,130 @@
-# A Statamic addon that automatically subscribes form submissions to MailerLite, with per-form configuration for subscriber groups and field mapping manageable from the Control Panel.
+# Concept7 Statamic MailerLite
 
-[![Latest Version on Packagist](https://img.shields.io/packagist/v/concept7/statamic-mailerlite.svg?style=flat-square)](https://packagist.org/packages/concept7/statamicmailerlite)
-[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/concept7/statamic-mailerlite/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/concept7/statamicmailerlite/actions?query=workflow%3Arun-tests+branch%3Amain)
-[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/concept7/statamic-mailerlite/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/concept7/statamicmailerlite/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
-[![Total Downloads](https://img.shields.io/packagist/dt/concept7/statamic-mailerlite.svg?style=flat-square)](https://packagist.org/packages/concept7/statamicmailerlite)
+Automatically subscribe Statamic form submitters to MailerLite, with per-form configuration (enable toggle, field mapping, group selection) editable from the Statamic Control Panel. Supports plain Statamic 6 sites and multi-tenant hosts running `spatie/laravel-multitenancy`.
 
-This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.
+[![Latest Version on Packagist](https://img.shields.io/packagist/v/concept7/statamic-mailerlite.svg?style=flat-square)](https://packagist.org/packages/concept7/statamic-mailerlite)
+[![Tests](https://img.shields.io/github/actions/workflow/status/concept7/statamic-mailerlite/run-tests.yml?branch=0.x&label=tests&style=flat-square)](https://github.com/concept7/statamic-mailerlite/actions/workflows/run-tests.yml?query=branch%3A0.x)
+[![PHPStan](https://img.shields.io/github/actions/workflow/status/concept7/statamic-mailerlite/phpstan.yml?branch=0.x&label=phpstan&style=flat-square)](https://github.com/concept7/statamic-mailerlite/actions/workflows/phpstan.yml?query=branch%3A0.x)
+[![Total Downloads](https://img.shields.io/packagist/dt/concept7/statamic-mailerlite.svg?style=flat-square)](https://packagist.org/packages/concept7/statamic-mailerlite)
 
-## Support us
+## What it does
 
-[<img src="https://github-ads.s3.eu-central-1.amazonaws.com/StatamicMailerLite.jpg?t=1" width="419px" />](https://spatie.be/github-ad-click/StatamicMailerLite)
+When a visitor submits a Statamic form that has the MailerLite integration enabled, the configured fields and groups are reliably synced to the correct MailerLite account — **without blocking the form response** and **without leaking config or subscribers across tenants**.
 
-We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).
+- **Per-form configuration** — enable the integration, map Statamic fields to MailerLite custom fields, and choose which MailerLite groups the subscriber joins. Edited inline from each form's edit screen in the Statamic Control Panel.
+- **Top-level Control Panel section** — a "MailerLite" nav item (nested under a "Concept7" parent for future addons) gives you a dashboard of every form, its enabled status, configured groups, last sync timestamp, and 24-hour failure count.
+- **Per-form activity log** — every sync attempt with timestamp, status, redacted payload snapshot, error message, and a Retry action for failed jobs.
+- **Settings + test connection** — global page for entering and rotating the MailerLite API key, with an inline "Test connection" button that hits a cheap read-only endpoint and surfaces a clear pass/fail status.
+- **Async sync via queued job** — the `SubmissionCreated` listener implements `ShouldQueue`, so the form response is never blocked by MailerLite latency or downtime. Backoff and retry policy honor MailerLite's documented error codes.
+- **Encrypted at rest** — the API key is encrypted via Laravel's `Crypt` facade before persistence. Activity log payloads redact obvious secret-shaped fields (`*_token`, `*_key`, `*_secret`, etc.) before storage.
+- **Multi-tenant aware** — auto-detects whether `spatie/laravel-multitenancy` is installed and routes storage accordingly:
+  - **Plain Statamic** — single global API key, per-form config in addon YAML (`Addon::setting('forms')`).
+  - **Spatie file driver** — per-tenant YAML inside each tenant's storage directory.
+  - **Spatie DB driver** — per-tenant configuration row; the activity log table is migrated into each tenant's database.
+- **Reusable fieldtypes** — `MailerLiteField` and `MailerLiteGroups` are Relationship-based fieldtypes that fetch live custom fields and groups directly from the MailerLite API, so you never have to hand-sync available options.
 
-We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).
+## Requirements
 
-## Installation
+- PHP **8.4** or higher
+- Statamic **6.0** or higher (Laravel **12.x** or **13.x**)
+- A MailerLite account with an API key (free tier works)
+- *(Optional)* `spatie/laravel-multitenancy` **^4.0** — only required if the host is multi-tenant
 
-You can install the package via composer:
+## Installation
 
 ```bash
 composer require concept7/statamic-mailerlite
 ```
 
-You can publish and run the migrations with:
+Run the activity-log migration — required on every install, including plain Statamic mode:
 
 ```bash
-php artisan vendor:publish --tag="statamic-mailerlite-migrations"
 php artisan migrate
 ```
 
-You can publish the config file with:
+The activity log is always database-backed. (In plain Statamic mode the API key and per-form config are stored in addon YAML, but every sync attempt is logged to the `mailerlite_activity_log` table so the Dashboard and per-form Activity views can render.)
+
+Publish (and re-publish) the compiled CP frontend assets:
 
 ```bash
-php artisan vendor:publish --tag="statamic-mailerlite-config"
+php artisan vendor:publish --provider="Concept7\\StatamicMailerLite\\StatamicMailerLiteServiceProvider" --force
 ```
 
-This is the contents of the published config file:
+The `--force` flag is required when upgrading — the Vite manifest hash changes on every release.
 
-```php
-return [
-];
-```
+### Multi-tenant hosts
+
+For hosts running `spatie/laravel-multitenancy`, tenant-scoped variants of the activity-log migration ship under `database/migrations/tenant/`. Wire them into your tenant migration runner per Spatie's documentation — each tenant's database needs its own `mailerlite_activity_log` table.
 
-Optionally, you can publish the views using
+If you want to customise the migrations before running them, publish them first:
 
 ```bash
-php artisan vendor:publish --tag="statamic-mailerlite-views"
+php artisan vendor:publish --tag="statamic-mailerlite-migrations"
 ```
 
-## Usage
+## Configuration
 
-```php
-$statamicMailerLite = new Concept7\StatamicMailerLite();
-echo $statamicMailerLite->echoPhrase('Hello, Concept7!');
-```
+Open the Statamic Control Panel and navigate to **Concept7 → MailerLite → Settings**:
+
+1. Paste your MailerLite API key. Click **Test connection** — a green pill confirms the key is valid; a red one tells you exactly what went wrong (HTTP 401 unauthorized, network error, etc.).
+2. The key is encrypted via `Crypt::encryptString` before persistence; it never appears in any log, dump, or environment variable.
+
+Then, for each form you want to wire up:
+
+1. Edit the form in Statamic (**Forms → [Your Form] → Configure**).
+2. In the **MailerLite** tab:
+   - Toggle **Enable** on.
+   - Pick one or more **Groups** the subscriber should join.
+   - Map each MailerLite field to a Statamic form field. A built-in synthetic "email" row is provided automatically and locked to the form's email field.
+3. Submit the form as a visitor. Check **Concept7 → MailerLite → Dashboard** — you'll see the form's sync count tick up. Open the form row to see the per-submission activity log.
+
+## Multi-tenancy
+
+The addon auto-detects whether `\Spatie\Multitenancy\Multitenancy` is present in the host application:
+
+- **Absent** → all form configs and the API key live in addon YAML (a single global key).
+- **Present (file driver)** → per-tenant YAML files inside each tenant's storage directory. Tenant isolation is enforced by Spatie's tenant resolver — no tenant can read another's API key, mappings, or activity log.
+- **Present (database driver)** → per-tenant configuration rows. Migrations for both the landlord and tenant connections ship in `database/migrations/`.
+
+Sync jobs are tenant-aware: the dispatched `SyncSubscriberJob` re-resolves the current tenant inside `handle()` (never at dispatch time), so re-queued jobs always sync to the right MailerLite account.
 
 ## Testing
 
+The addon ships with a Pest test suite (Orchestra Testbench) covering storage adapters, service layer, listeners, the queued sync job, Control Panel routes, and fieldtypes.
+
 ```bash
+composer install
 composer test
 ```
 
+PHPStan and Pint also run clean against the source:
+
+```bash
+composer analyse
+composer format
+```
+
+## Documentation
+
+A compact code-reference document — `documentation.md` — lives at the package root. It cross-references every decision (D-XX), requirement (STOR/SYNC/SET/FT/CP/TEN/SPEC), threat (T-XX), and code-review finding referenced in inline code comments. Use it as a lookup table when reading the source.
+
 ## Changelog
 
-Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
+See [CHANGELOG.md](CHANGELOG.md).
 
 ## Contributing
 
-Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
+Issues and pull requests welcome — please target the `0.x` branch. Run `composer test`, `composer analyse`, and `composer format` before opening a PR.
 
-## Security Vulnerabilities
+## Security
 
-Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
+If you discover a security vulnerability, please email security@concept7.nl rather than opening a public issue.
 
 ## Credits
 
-- [Jan Henk Hazelaar](https://github.com/jhhazelaar)
-- [All Contributors](../../contributors)
+- [Jan Henk Hazelaar](https://github.com/jhhazelaar) — original author
+- [Concept7](https://concept7.nl) — sponsor
 
 ## License
 
-The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
+The MIT License (MIT). See [LICENSE.md](LICENSE.md).

composer.json

@@ -23,9 +23,9 @@
         "statamic/cms": "^6.0"
     },
     "require-dev": {
+        "larastan/larastan": "^3.0",
         "laravel/pint": "^1.14",
         "nunomaduro/collision": "^8.8",
-        "larastan/larastan": "^3.0",
         "orchestra/testbench": "^10.0.0||^9.0.0",
         "pestphp/pest": "^4.0",
         "pestphp/pest-plugin-arch": "^4.0",