core/README.md

# Core Module

A Laravel module providing authentication, notifications, activity logging, CLI tooling, and functional types on top of the [Lunar](https://lunarphp.io) admin panel. Designed to be consumed as a standalone Composer package.

---

## What's Inside

### OTP Authentication

Passwordless login for both staff (Lunar panel) and customers via 6-digit codes delivered by email. Codes expire after 10 minutes. The Lunar panel login page is a two-step flow: email → OTP. Rate-limited to 5 attempts.

See [`docs/otp-auth.md`](docs/otp-auth.md).

### Notification Registry

An event-driven notification system. Each notification class declares which event it listens to and who to notify — the registry wires up the listener automatically. All notifications extend `BaseNotification` which implements `ShouldQueue`, so delivery is async. Supports optional delays.

**Creating a notification:**

```php
class MyNotification extends BaseNotification
{
    public function __construct(private readonly MyEvent $event) {}

    public static function getKey(): string { return 'my.notification.key'; }
    public static function listensTo(): string { return MyEvent::class; }
    public function via(object $notifiable): array { return ['mail']; }
    public function notifiable(): AnonymousNotifiable { ... }
}

// Register in a service provider:
NotificationRegistry::get()->register([MyNotification::class]);
```

### Activity Logging

Thin wrapper around [Spatie Laravel Activity Log](https://github.com/spatie/laravel-activitylog). Four standardized methods: `created()`, `updated()`, `failed()`, `deleted()`. Logs to the `lunar` channel and auto-resolves the actor from the staff session.

See [`docs/activity-log.md`](docs/activity-log.md).

### Lunar Panel Integration

- Custom OTP login page replacing the default Lunar panel login
- `StaffResourceExtension` — removes password field from Lunar's staff resource
- `CustomerResourceExtension` — replaces default address relation manager with a custom implementation
- `CorePlugin` — configures panel path, branding, logos, navigation items, and activity log field exclusions for staff

Register the plugin in your Lunar panel provider:

```php
->plugin(\Modules\Core\CorePlugin::make())
```

### CLI Commands

| Command | Description |
|---|---|
| `core:create-admin` | Create a Lunar admin user |
| `core:anonymize` | GDPR anonymization of users and customers (local only) |
| `core:export` | Dump database + storage files to a timestamped zip |
| `core:import` | Restore from a zip export (runs anonymize automatically, local only) |
| `core:export-cleanup` | Delete old export zips, keep N most recent |

### Functional Types

Result and Option monads for explicit error handling without exceptions.

```php
// Result<T, E>
$result = Success::of($value);
$result = Error::of('something went wrong');
$result->map(fn($v) => ...)->flatMap(fn($v) => ...);

// Option<T>
$option = Option::fromValue($nullableValue);
$option->getOrElse('default');
$option->map(fn($v) => ...)->filter(fn($v) => $v > 0);
```

---

## Installation

Add the repository to your project's `composer.json`:

```json
{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://code.radical-elements.com/boboko/core.git"
        }
    ],
    "require": {
        "boboko/core": "^1.0"
    }
}
```

Then run:

```bash
composer require boboko/core
php artisan vendor:publish --tag=core-assets
php artisan migrate
```

---

## Requirements

- PHP 8.2+
- Laravel 11+
- Lunar (lunarphp/lunar + lunarphp/admin)
- Spatie Laravel Activity Log

---

## Documentation

- [`docs/otp-auth.md`](docs/otp-auth.md) — OTP authentication flow
- [`docs/activity-log.md`](docs/activity-log.md) — Activity logging
- [`docs/lunar.md`](docs/lunar.md) — Lunar framework reference
- [`docs/notifications.md`](docs/notifications.md) — Notification registry
- [`docs/modules.md`](docs/modules.md) — Module architecture, Customer/User pairing, provider registration pitfalls